Neutral unified project-state inspection #991

New Issue

2026-07-31T10:17:15-05:00

jcwalker3 commented

2026-07-31 10:17:15 -05:00

Parent umbrella: issue #989. Informative bootstrap evidence only, not a machine-enforced dependency; Child 1 delivers structured relationships and backfills this.

Problem

No single surface returns the complete candidate inventory neutrally. The neutral primitives are fragmented and cannot prove completeness; the one complete surface recommends a task.

Charter connection

Steps 2, 3, and 4 require inspecting the complete authoritative project state and comparing candidates. Responsibilities forbids the MCP deciding which task the LLM wants, and its guardrail treats routing patterns as dispatch. What this project is not forbids dispatch and allocator authority.

Verified current gap

The neutral issue and PR listings express none of priority, urgency, impact, claims, or dependencies; dependencies and claims require two further tools with different shapes and no join key. The issue listing exposes no page or cursor input and no completeness metadata and truncates silently — a request limited to 50 returned exactly 50 with no signal distinguishing truncation from exhaustion. The only surface asserting inventory completeness emits a primary next-safe-action and per-role next targets.

Scope

One unified candidate-level inventory covering implementation issues, PRs awaiting review, approved PRs eligible for merge, change-requested remediation, prerequisite work, and abandoned or orphaned reconciliation work.
Returns priority, dependencies, urgency, impact, readiness, clarification state, and active Gitea claims as separate facts, with evidence sufficient for independent LLM comparison.
Provides explicit pagination, terminal evidence, completeness, and freshness contracts, and fails closed when completeness cannot be established.
Provides no selected task, ranking, recommendation, role assignment, substitution, or hidden steering.
Preserves the lower-level diagnostic reads.

Non-goals

Defining the field authorities — Child 1. Claiming — Child 3. Modifying the existing dashboard contract. Removing the existing list operations. Ranking anything.

Functional requirements

Deterministic stable ordering by item number, carrying no preference semantics.
Explicit pagination at parity with the existing PR-listing contract: caller-visible page or cursor inputs, terminal evidence, and a completeness assertion. Silent truncation prohibited.
A state-freshness contract stating the observation point and its source.
Every field authoritative or an explicit typed state gap from Child 1.
Active claim per candidate, sourced from Child 1's Gitea record.
Hard dependency and readiness returned as distinct fields.
Stable typed failure contracts.

Safety and authority boundaries

Read-only; emits no recommendation. No field may name a next task, a preferred role, or a ranked order. Eligibility filtering that hides otherwise-valid candidates is prohibited; filtering must be caller-requested and reported.

Acceptance criteria

One operation returns all six work classes in one unified candidate shape.
All seven comparison facts are separate fields, each authoritative or an explicit state gap.
Active claims appear per candidate.
Hard dependency and readiness are structurally distinct.
The response contains no ranking, selection, recommended action, or per-role next target — asserted by test.
Pagination is explicit; a truncated response is distinguishable from an exhausted one.
Incomplete inventory fails closed.
No candidate is silently excluded by an eligibility filter.
Existing list and dashboard surfaces remain backward-compatible according to their own documented contracts. They are not required to be semantically equivalent to the new neutral inventory, and charter-conflicting recommendation behavior is removed by Child 5.
Abandoned and orphaned work appears reliably, closing the #952 omission class.

Required tests and validation

Field completeness and state-gap honesty. A schema assertion that no ranking or next-action field exists. Pagination traversal to explicit exhaustion plus a deliberately truncated request proving the distinction. Incomplete-inventory fail-closed. Per-candidate claim presence. Contract tests for the legacy list and dashboard surfaces under deterministic fixtures with timestamps, identifiers, and ordering normalized. No byte-identical live-response requirement anywhere. Abandoned-work discoverability reproducing the #952 evidence.

Dependencies

Until Child 1 delivers sanctioned structured relationship operations, the references below are informative bootstrap evidence only. They must not be treated as machine-enforced hard dependencies. Child 1 must backfill the appropriate structured relationships.

Child 1. Consumes #952, the durable dependency-edge store, and workflow-lease listing.

Compatibility and rollout

Purely additive. Existing surfaces keep their documented fields and typed failure contracts; equivalence is demonstrated semantically, not by literal comparison of live responses. Charter-conflicting guidance is corrected in Child 5, not here.

Rollback behavior

Removing the new operation restores the prior fragmented reads with no loss of safety. It never reintroduces a recommendation field into a neutral surface.

Documentation requirements

The candidate schema, the pagination and freshness contracts, and an explicit statement that the operation neither selects nor recommends.

Completion evidence

Schema documentation, the non-recommendation assertion result, and a recorded exhaustive traversal.

Reusable existing issues, PRs, and primitives

#952. Live primitives: issue listing, PR listing, dependency-edge listing, workflow-lease listing. The existing PR-listing pagination contract is the model to match.

Fundamental-workflow stage supported

inspect -> choose, and reassess — charter steps 2, 3, 4, and 12.

Parent umbrella: issue #989. Informative bootstrap evidence only, not a machine-enforced dependency; Child 1 delivers structured relationships and backfills this. ## Problem No single surface returns the complete candidate inventory neutrally. The neutral primitives are fragmented and cannot prove completeness; the one complete surface recommends a task. ## Charter connection Steps 2, 3, and 4 require inspecting the complete authoritative project state and comparing candidates. Responsibilities forbids the MCP deciding which task the LLM wants, and its guardrail treats routing patterns as dispatch. What this project is not forbids dispatch and allocator authority. ## Verified current gap The neutral issue and PR listings express none of priority, urgency, impact, claims, or dependencies; dependencies and claims require two further tools with different shapes and no join key. The issue listing exposes no page or cursor input and no completeness metadata and truncates silently — a request limited to 50 returned exactly 50 with no signal distinguishing truncation from exhaustion. The only surface asserting inventory completeness emits a primary next-safe-action and per-role next targets. ## Scope - One unified candidate-level inventory covering implementation issues, PRs awaiting review, approved PRs eligible for merge, change-requested remediation, prerequisite work, and abandoned or orphaned reconciliation work. - Returns priority, dependencies, urgency, impact, readiness, clarification state, and active Gitea claims as separate facts, with evidence sufficient for independent LLM comparison. - Provides explicit pagination, terminal evidence, completeness, and freshness contracts, and fails closed when completeness cannot be established. - Provides **no** selected task, ranking, recommendation, role assignment, substitution, or hidden steering. - Preserves the lower-level diagnostic reads. ## Non-goals Defining the field authorities — Child 1. Claiming — Child 3. Modifying the existing dashboard contract. Removing the existing list operations. Ranking anything. ## Functional requirements - Deterministic stable ordering by item number, carrying no preference semantics. - Explicit pagination at parity with the existing PR-listing contract: caller-visible page or cursor inputs, terminal evidence, and a completeness assertion. Silent truncation prohibited. - A state-freshness contract stating the observation point and its source. - Every field authoritative or an explicit typed state gap from Child 1. - Active claim per candidate, sourced from Child 1's Gitea record. - Hard dependency and readiness returned as distinct fields. - Stable typed failure contracts. ## Safety and authority boundaries Read-only; emits no recommendation. No field may name a next task, a preferred role, or a ranked order. Eligibility filtering that hides otherwise-valid candidates is prohibited; filtering must be caller-requested and reported. ## Acceptance criteria - One operation returns all six work classes in one unified candidate shape. - All seven comparison facts are separate fields, each authoritative or an explicit state gap. - Active claims appear per candidate. - Hard dependency and readiness are structurally distinct. - The response contains no ranking, selection, recommended action, or per-role next target — asserted by test. - Pagination is explicit; a truncated response is distinguishable from an exhausted one. - Incomplete inventory fails closed. - No candidate is silently excluded by an eligibility filter. - Existing list and dashboard surfaces remain backward-compatible according to their own documented contracts. They are not required to be semantically equivalent to the new neutral inventory, and charter-conflicting recommendation behavior is removed by Child 5. - Abandoned and orphaned work appears reliably, closing the #952 omission class. ## Required tests and validation Field completeness and state-gap honesty. A schema assertion that no ranking or next-action field exists. Pagination traversal to explicit exhaustion plus a deliberately truncated request proving the distinction. Incomplete-inventory fail-closed. Per-candidate claim presence. Contract tests for the legacy list and dashboard surfaces under deterministic fixtures with timestamps, identifiers, and ordering normalized. No byte-identical live-response requirement anywhere. Abandoned-work discoverability reproducing the #952 evidence. ## Dependencies Until Child 1 delivers sanctioned structured relationship operations, the references below are informative bootstrap evidence only. They must not be treated as machine-enforced hard dependencies. Child 1 must backfill the appropriate structured relationships. Child 1. Consumes #952, the durable dependency-edge store, and workflow-lease listing. ## Compatibility and rollout Purely additive. Existing surfaces keep their documented fields and typed failure contracts; equivalence is demonstrated semantically, not by literal comparison of live responses. Charter-conflicting guidance is corrected in Child 5, not here. ## Rollback behavior Removing the new operation restores the prior fragmented reads with no loss of safety. It never reintroduces a recommendation field into a neutral surface. ## Documentation requirements The candidate schema, the pagination and freshness contracts, and an explicit statement that the operation neither selects nor recommends. ## Completion evidence Schema documentation, the non-recommendation assertion result, and a recorded exhaustive traversal. ## Reusable existing issues, PRs, and primitives #952. Live primitives: issue listing, PR listing, dependency-edge listing, workflow-lease listing. The existing PR-listing pagination contract is the model to match. ## Fundamental-workflow stage supported inspect -> choose, and reassess — charter steps 2, 3, 4, and 12.

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#991