Authoritative Gitea candidate-state schema, claims, and relationships #990

New Issue

2026-07-31T10:16:24-05:00

jcwalker3 commented

2026-07-31 10:16:24 -05:00

Parent umbrella: issue #989 — "MCP Control Plane: charter-compliant autonomous task selection (umbrella)". This reference is informative bootstrap evidence only and is not a machine-enforced dependency; this issue delivers the structured relationship operations that replace it.

Problem

A worker cannot perform the charter's comparison step, cannot route around in-progress work, and cannot escalate an ambiguity, because the required facts have no durable authoritative Gitea representation, active claims live only in the control-plane database, no sanctioned operation creates structured relationships, and issue-edit authority is indistinguishable from comment authority.

Charter connection

Responsibilities assigns authoritative claims to Gitea and priority-setting to the human maintainer. Project state model requirements makes active claims, priorities, hard dependencies, and blocked-pending-clarification mandatory structured, machine-discoverable Gitea state, and declares any inability to express them a defect to be fixed rather than worked around. Contention is normal requires active claims to be visible so workers route around in-progress work before attempting a claim. Dependencies keeps hard dependencies (a gate) distinct from priority (a comparison). Escalation requires a machine-discoverable marker.

Verified current gap

The repository label catalog contains no priority, urgency, project-impact, or blocked-pending-clarification representation. Present are ready, in-progress, pr-open, and blocked status labels. Two informal hints exist with empty descriptions and no ordering.
Workflow leases report authoritative_source: control_plane_db.
Active claims are exposed only in aggregate, never per candidate.
Dependency edges are durable and structured but live in the control plane, and the only mechanism recording them is the allocator.
No native operation creates a Gitea parent/child or hard-dependency relationship.
Capability resolution maps the issue-edit task to the issue-comment permission; no distinct issue-edit permission exists in any of the eight profiles.

Consequence: Escalation is inoperable.

Scope

A. Field authority. Structured Gitea authority for priority, hard dependencies, clarification blocks, readiness, urgency, project impact, and active claims. Permitted sources, maintainer ownership, ordering for comparable values, conflict handling, invalid-state handling, and typed missing-state failures.

Field	Permitted source	Ownership	Missing / conflicting / invalid
priority	one ordered maintainer-owned label set	maintainer only	absent gives null plus `priority_unset`; two labels give null plus `multiple_priority_labels` listing both; unknown value gives null plus `unknown_priority_label`. Never pick one, never default, never rank unlabelled work last
hard dependencies	structured Gitea relationship	declared by any role, resolved by computation	unresolvable reference gives a typed gap, never silently dropped
clarification block	dedicated machine-discoverable marker created by this issue	applied by workers per Escalation, cleared by maintainer	absence is a distinct state from "not blocked"
active claim	authoritative Gitea claim record	claim holder	unknown gives null plus a reason code, never a guess
readiness	existing status representation	maintainer and workflow	ambiguous gives a typed gap
urgency	only durable structured Gitea state: maintainer urgency label, structured deadline, linked incident, referenced SLA	maintainer; incident links may come from the incident bridge	none gives null plus `urgency_unset`; conflicting returns all signals separately with scalar null plus `conflicting_urgency_signals`
project impact	to be defined here; no authority exists today	maintainer	until defined gives null plus `no_impact_authority`. Never synthesised from dependency counts, labels, or inference

Any count derived from dependency edges is named unblocks_count or dependency_reach and is never presented as project impact.

B. Label policy. Authoritative label policy documenting which labels affect priority, readiness, clarification state, or worker eligibility. Resolve the duplicate label IDs — the feature-type name resolves to IDs 103 and 130, and the workflow-hardening name to IDs 105 and 128; both are live and unarchived. Record which is canonical, whether the duplicate is archived or removed, and how existing issues carrying each ID are reconciled.

C. Claim authority. Durable active-claim publication in Gitea: existence, owner identity, task binding, validity window. A worker inspecting Gitea alone must see enough to route around active work. Database reservations taken before publication are strictly transient: timeout-bounded, non-authoritative, never returned to the caller as an acquired claim, never usable as a durable ownership record, and automatically rolled back or reconciled on failure or timeout. No successful worker claim, capability activation, or mutation authority exists before Gitea claim publication succeeds. No long-lived blocking condition may be invisible to a worker inspecting Gitea.

This is not a distributed transaction and must not be described as one. Deliver a documented consistency protocol with bounded failure states, idempotent recovery, and fail-closed mutation authority.

D. Reconciliation — fail closed, never resolving toward the more permissive side:

Condition	Resolution
transient reservation, no Gitea record, within timeout	not a claim; no mutation authority; publication may still complete
transient reservation, no Gitea record, timeout exceeded	reservation rolled back; caller must re-inspect and re-claim
partial publication, Gitea write ambiguous	fail closed; no mutation authority; idempotent recovery completes or rolls back exactly once
Gitea record, no database row	live claim by the named identity; no other worker may claim; recovery rebuilds the enforcement row or expires it per the Gitea-recorded window
both present, owner identity differs	unresolvable automatically; no mutation; apply the clarification marker and escalate
both present, window or head differs	Gitea authoritative for existence, owner, task binding; database authoritative for the fencing generation only; any other divergence fails closed
ownership expired	becomes a discoverable reconciliation task; never silently swept

Neither store may delete a claim record on the strength of the other alone.

E. Structured relationships. Sanctioned native operations for creating, reading, verifying, and reconciling structured parent/child and hard-dependency relationships. Remove allocator-only authority for dependency edges. Backfill structured relationships for the umbrella, Children 1 through 5, #963, #964, and #916 where appropriate, replacing the bootstrap body references.

F. Distinct issue-edit permission. Define a permission for editing issue titles and bodies, separate from issue commenting. Stop treating comment permission as proof of title and body edit authority. Make the issue-edit operation resolve through the distinct permission. Keep commenting and editing independently grantable. Migrate affected profiles intentionally. Preserve typed denial when comment permission exists but edit permission does not. Document compatibility and rollout for the permission change.

Non-goals

Building the inspection surface (Child 2) or the claim operation (Child 3). Re-owning lease lifecycle mechanics — consume #952, #792, #793, #890. Weakening ownership, fencing, or fail-closed behaviour. Letting a caller assert its own priority, urgency, impact, ownership, or eligibility. Claiming a distributed transaction. Broadening any profile's permissions beyond the intentional edit-permission migration.

Functional requirements

Every field resolves from its named authority or returns an explicit typed state gap. The MCP never invents, combines, weights, or silently defaults any project fact. Hard dependency and readiness remain structurally distinct fields, never collapsed into one string.

Safety and authority boundaries

Gitea is the durable claim authority. The database enforces, caches, indexes, and fences but is never the sole durable authority. Priority is maintainer-owned. Fail-closed ownership enforcement is preserved throughout.

Acceptance criteria

Durable machine-discoverable Gitea representations exist for all seven fields, or the field returns a typed state gap naming the missing authority.
An ordered priority representation exists with its ordering published as a durable artifact.
A blocked-pending-clarification marker exists, is machine-discoverable, and is documented as excluding an item from normal eligible work without implying readiness or selectability.
Conflicting, invalid, and missing values behave exactly as tabulated; no silent default.
Label policy is documented, including eligibility effects, and the duplicate label IDs are resolved.
Gitea holds the authoritative active claim; a worker inspecting Gitea alone can route around active work.
A transient reservation is never returned as an acquired claim and never confers capability activation or mutation authority.
All reconciliation conditions are implemented and fail closed; recovery is idempotent.
Sanctioned operations create, read, verify, and reconcile structured parent/child and hard-dependency relationships; dependency edges no longer require the allocator.
Relationships for the umbrella, Children 1 through 5, and the referenced issues are backfilled.
A distinct issue-edit permission exists; the issue-edit operation resolves through it; commenting and editing are independently grantable; typed denial is preserved when comment permission exists without edit permission.
Expired ownership becomes a discoverable reconciliation task.
Hard dependency and readiness are structurally distinct.
Existing ownership and fail-closed enforcement are unchanged, proven by contract tests.

Required tests and validation

Per-field authority resolution and state-gap honesty. Two-priority-label conflict. Unknown priority value. Conflicting urgency signals. Absent impact authority. A database-only provisional reservation cannot become an invisible active claim or a successful mutation grant — asserted directly. Timeout rollback. Partial-publication idempotent recovery. Each reconciliation condition. Relationship create, read, verify, reconcile, and backfill. Positive and negative capability tests for issue editing, including comment-without-edit denial. Expired-ownership discoverability reproducing the #952 evidence combination. Contract tests use deterministic fixtures with timestamps, identifiers, and ordering normalized.

Dependencies

Until this issue delivers sanctioned structured relationship operations, the references below are informative bootstrap evidence only. They must not be treated as machine-enforced hard dependencies and must be backfilled as structured relationships when the capability exists.

#890 single authoritative ownership record (hard). #952 single lease-eligibility model. #792 terminal retirement. #793 read-side generation fencing.

Maintainer inputs required before completion: priority ordering, permitted urgency sources, project-impact authority, reconciliation window, canonical-label resolution, and approval of the edit-permission migration.

Compatibility and rollout

Additive. New labels and markers extend the catalog. Claim-record migration is additive-then-cutover, never destructive; existing locks, leases, worktrees, and handoff ledgers are preserved. The edit-permission change is a deliberate migration with documented rollout, not an implicit broadening. Compatibility is proven by schema-compatibility and contract tests, not literal response comparison.

Rollback behavior

Reverting leaves existing enforcement intact and stops publication of new Gitea claim records. It never re-authorizes database-only active ownership as a supported state, never returns a transient reservation as a claim, and never restores comment permission as proof of edit authority.

Documentation requirements

A field-authority reference covering source, ordering, conflict rule, and state-gap code per field. A claim-authority document covering the publication protocol, every bounded failure state, and recovery semantics, explicitly stating this is not a distributed transaction. A label policy document. A relationship-operations reference. A permission-migration guide.

Completion evidence

The published ordering artifact, the marker definition and its documented semantics, the label policy and duplicate resolution, the relationship backfill result, the edit-permission test matrix, and the invisible-claim test results — all recorded on this issue.

Reusable existing issues, PRs, and primitives

#890, #952, #792, #793. Live primitives: dependency-edge listing, workflow-lease listing, label listing and setting, issue marking.

Fundamental-workflow stage supported

inspect -> choose — charter steps 3 and 4, plus Project state model requirements and Escalation.

Parent umbrella: issue #989 — "MCP Control Plane: charter-compliant autonomous task selection (umbrella)". This reference is informative bootstrap evidence only and is not a machine-enforced dependency; this issue delivers the structured relationship operations that replace it. ## Problem A worker cannot perform the charter's comparison step, cannot route around in-progress work, and cannot escalate an ambiguity, because the required facts have no durable authoritative Gitea representation, active claims live only in the control-plane database, no sanctioned operation creates structured relationships, and issue-edit authority is indistinguishable from comment authority. ## Charter connection Responsibilities assigns authoritative claims to Gitea and priority-setting to the human maintainer. Project state model requirements makes active claims, priorities, hard dependencies, and blocked-pending-clarification mandatory structured, machine-discoverable Gitea state, and declares any inability to express them a defect to be fixed rather than worked around. Contention is normal requires active claims to be visible so workers route around in-progress work before attempting a claim. Dependencies keeps hard dependencies (a gate) distinct from priority (a comparison). Escalation requires a machine-discoverable marker. ## Verified current gap - The repository label catalog contains no priority, urgency, project-impact, or blocked-pending-clarification representation. Present are ready, in-progress, pr-open, and blocked status labels. Two informal hints exist with empty descriptions and no ordering. - Workflow leases report `authoritative_source: control_plane_db`. - Active claims are exposed only in aggregate, never per candidate. - Dependency edges are durable and structured but live in the control plane, and the only mechanism recording them is the allocator. - No native operation creates a Gitea parent/child or hard-dependency relationship. - Capability resolution maps the issue-edit task to the issue-comment permission; no distinct issue-edit permission exists in any of the eight profiles. Consequence: Escalation is inoperable. ## Scope **A. Field authority.** Structured Gitea authority for priority, hard dependencies, clarification blocks, readiness, urgency, project impact, and active claims. Permitted sources, maintainer ownership, ordering for comparable values, conflict handling, invalid-state handling, and typed missing-state failures. | Field | Permitted source | Ownership | Missing / conflicting / invalid | | --- | --- | --- | --- | | priority | one ordered maintainer-owned label set | maintainer only | absent gives null plus `priority_unset`; two labels give null plus `multiple_priority_labels` listing both; unknown value gives null plus `unknown_priority_label`. Never pick one, never default, never rank unlabelled work last | | hard dependencies | structured Gitea relationship | declared by any role, resolved by computation | unresolvable reference gives a typed gap, never silently dropped | | clarification block | dedicated machine-discoverable marker created by this issue | applied by workers per Escalation, cleared by maintainer | absence is a distinct state from "not blocked" | | active claim | authoritative Gitea claim record | claim holder | unknown gives null plus a reason code, never a guess | | readiness | existing status representation | maintainer and workflow | ambiguous gives a typed gap | | urgency | only durable structured Gitea state: maintainer urgency label, structured deadline, linked incident, referenced SLA | maintainer; incident links may come from the incident bridge | none gives null plus `urgency_unset`; conflicting returns all signals separately with scalar null plus `conflicting_urgency_signals` | | project impact | to be defined here; no authority exists today | maintainer | until defined gives null plus `no_impact_authority`. Never synthesised from dependency counts, labels, or inference | Any count derived from dependency edges is named `unblocks_count` or `dependency_reach` and is never presented as project impact. **B. Label policy.** Authoritative label policy documenting which labels affect priority, readiness, clarification state, or worker eligibility. Resolve the duplicate label IDs — the feature-type name resolves to IDs 103 and 130, and the workflow-hardening name to IDs 105 and 128; both are live and unarchived. Record which is canonical, whether the duplicate is archived or removed, and how existing issues carrying each ID are reconciled. **C. Claim authority.** Durable active-claim publication in Gitea: existence, owner identity, task binding, validity window. A worker inspecting Gitea alone must see enough to route around active work. Database reservations taken before publication are strictly transient: timeout-bounded, non-authoritative, never returned to the caller as an acquired claim, never usable as a durable ownership record, and automatically rolled back or reconciled on failure or timeout. No successful worker claim, capability activation, or mutation authority exists before Gitea claim publication succeeds. No long-lived blocking condition may be invisible to a worker inspecting Gitea. This is **not** a distributed transaction and must not be described as one. Deliver a documented consistency protocol with bounded failure states, idempotent recovery, and fail-closed mutation authority. **D. Reconciliation** — fail closed, never resolving toward the more permissive side: | Condition | Resolution | | --- | --- | | transient reservation, no Gitea record, within timeout | not a claim; no mutation authority; publication may still complete | | transient reservation, no Gitea record, timeout exceeded | reservation rolled back; caller must re-inspect and re-claim | | partial publication, Gitea write ambiguous | fail closed; no mutation authority; idempotent recovery completes or rolls back exactly once | | Gitea record, no database row | live claim by the named identity; no other worker may claim; recovery rebuilds the enforcement row or expires it per the Gitea-recorded window | | both present, owner identity differs | unresolvable automatically; no mutation; apply the clarification marker and escalate | | both present, window or head differs | Gitea authoritative for existence, owner, task binding; database authoritative for the fencing generation only; any other divergence fails closed | | ownership expired | becomes a discoverable reconciliation task; never silently swept | Neither store may delete a claim record on the strength of the other alone. **E. Structured relationships.** Sanctioned native operations for creating, reading, verifying, and reconciling structured parent/child and hard-dependency relationships. Remove allocator-only authority for dependency edges. Backfill structured relationships for the umbrella, Children 1 through 5, #963, #964, and #916 where appropriate, replacing the bootstrap body references. **F. Distinct issue-edit permission.** Define a permission for editing issue titles and bodies, separate from issue commenting. Stop treating comment permission as proof of title and body edit authority. Make the issue-edit operation resolve through the distinct permission. Keep commenting and editing independently grantable. Migrate affected profiles intentionally. Preserve typed denial when comment permission exists but edit permission does not. Document compatibility and rollout for the permission change. ## Non-goals Building the inspection surface (Child 2) or the claim operation (Child 3). Re-owning lease lifecycle mechanics — consume #952, #792, #793, #890. Weakening ownership, fencing, or fail-closed behaviour. Letting a caller assert its own priority, urgency, impact, ownership, or eligibility. Claiming a distributed transaction. Broadening any profile's permissions beyond the intentional edit-permission migration. ## Functional requirements Every field resolves from its named authority or returns an explicit typed state gap. The MCP never invents, combines, weights, or silently defaults any project fact. Hard dependency and readiness remain structurally distinct fields, never collapsed into one string. ## Safety and authority boundaries Gitea is the durable claim authority. The database enforces, caches, indexes, and fences but is never the sole durable authority. Priority is maintainer-owned. Fail-closed ownership enforcement is preserved throughout. ## Acceptance criteria - Durable machine-discoverable Gitea representations exist for all seven fields, or the field returns a typed state gap naming the missing authority. - An ordered priority representation exists with its ordering published as a durable artifact. - A blocked-pending-clarification marker exists, is machine-discoverable, and is documented as excluding an item from normal eligible work without implying readiness or selectability. - Conflicting, invalid, and missing values behave exactly as tabulated; no silent default. - Label policy is documented, including eligibility effects, and the duplicate label IDs are resolved. - Gitea holds the authoritative active claim; a worker inspecting Gitea alone can route around active work. - A transient reservation is never returned as an acquired claim and never confers capability activation or mutation authority. - All reconciliation conditions are implemented and fail closed; recovery is idempotent. - Sanctioned operations create, read, verify, and reconcile structured parent/child and hard-dependency relationships; dependency edges no longer require the allocator. - Relationships for the umbrella, Children 1 through 5, and the referenced issues are backfilled. - A distinct issue-edit permission exists; the issue-edit operation resolves through it; commenting and editing are independently grantable; typed denial is preserved when comment permission exists without edit permission. - Expired ownership becomes a discoverable reconciliation task. - Hard dependency and readiness are structurally distinct. - Existing ownership and fail-closed enforcement are unchanged, proven by contract tests. ## Required tests and validation Per-field authority resolution and state-gap honesty. Two-priority-label conflict. Unknown priority value. Conflicting urgency signals. Absent impact authority. A database-only provisional reservation cannot become an invisible active claim or a successful mutation grant — asserted directly. Timeout rollback. Partial-publication idempotent recovery. Each reconciliation condition. Relationship create, read, verify, reconcile, and backfill. Positive and negative capability tests for issue editing, including comment-without-edit denial. Expired-ownership discoverability reproducing the #952 evidence combination. Contract tests use deterministic fixtures with timestamps, identifiers, and ordering normalized. ## Dependencies Until this issue delivers sanctioned structured relationship operations, the references below are informative bootstrap evidence only. They must not be treated as machine-enforced hard dependencies and must be backfilled as structured relationships when the capability exists. #890 single authoritative ownership record (hard). #952 single lease-eligibility model. #792 terminal retirement. #793 read-side generation fencing. Maintainer inputs required before completion: priority ordering, permitted urgency sources, project-impact authority, reconciliation window, canonical-label resolution, and approval of the edit-permission migration. ## Compatibility and rollout Additive. New labels and markers extend the catalog. Claim-record migration is additive-then-cutover, never destructive; existing locks, leases, worktrees, and handoff ledgers are preserved. The edit-permission change is a deliberate migration with documented rollout, not an implicit broadening. Compatibility is proven by schema-compatibility and contract tests, not literal response comparison. ## Rollback behavior Reverting leaves existing enforcement intact and stops publication of new Gitea claim records. It never re-authorizes database-only active ownership as a supported state, never returns a transient reservation as a claim, and never restores comment permission as proof of edit authority. ## Documentation requirements A field-authority reference covering source, ordering, conflict rule, and state-gap code per field. A claim-authority document covering the publication protocol, every bounded failure state, and recovery semantics, explicitly stating this is not a distributed transaction. A label policy document. A relationship-operations reference. A permission-migration guide. ## Completion evidence The published ordering artifact, the marker definition and its documented semantics, the label policy and duplicate resolution, the relationship backfill result, the edit-permission test matrix, and the invisible-claim test results — all recorded on this issue. ## Reusable existing issues, PRs, and primitives #890, #952, #792, #793. Live primitives: dependency-edge listing, workflow-lease listing, label listing and setting, issue marking. ## Fundamental-workflow stage supported inspect -> choose — charter steps 3 and 4, plus Project state model requirements and Escalation.

Sign in to join this conversation.

Branches Tags

master

fix/issue-987-native-mcp-bootstrap

feat/issue-985-project-scoped-launcher-identity

fix/issue-983-cross-repo-base-ref

feat/issue-980-stale-worker-retirement

fix/issue-975-client-identity-heartbeat

fix/issue-973-cross-repo-canonical-roots

fix/issue-970-safely-resolve-missing-worktrees

fix/issue-969-native-mcp-bootstrap

feat/issue-664-break-glass-restart

feat/issue-708-mcp-namespace-attachment

feat/issue-665-restart-audit

fix/issue-700-durable-walls

fix/issue-704-prevent-env-workspace-bindings

feat/issue-707-cross-project-boundaries

fix/issue-690-review-profile-switch-guard

fix/issue-953-bootstrap-lock-provenance

feat/issue-949-native-fleet-inventory

fix/issue-943-runtime-context-helpers

fix/issue-945-owning-pr-renewal-evidence

fix/issue-941-scope-guard-bootstrap-wiring

docs/issue-930-remote-mcp-coupling-inventory

fix/issue-892-author-bootstrap-deadlock

fix/issue-686-detect-reject-manual-mcp

fix/issue-672-mcp-config-drift

fix/issue-689-deterministic-mcp-namespace

feat/issue-666-concurrent-mcp-restart-tests

feat/issue-659-maintenance-drain-mode

feat/issue-648-notifications-console

fix/issue-670-direct-master-incident

feat/issue-644-console-recovery

feat/issue-650-providers-insights

feat/issue-669-scoped-component-recovery

docs/issue-668-mcp-ha-rolling-restart

feat/issue-667-console-restart-controls

feat/issue-645-linkage-console

feat/issue-643-request-preview-initiate

fix/issue-897-permission-stale-runtime-classification

feat/issue-641-runtime-session-view

feat/issue-663-restart-classes

feat/issue-661-drain-proof-hard-gate

fix/issue-854-semantic-container-exclusion

issue-640

fix/issue-682-starlette-httpx2

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#990