spec-kitty / spec-kitty/spec-kitty

bug: `next --result success` blocks at review on artifacts its own query mode reports present — no operator recovery

Open
#3,883 7 comments 0 reactions 1 assignee Claimed by @robertDouglass View on GitHub
priority:P0 reliability status:claimed workflow
Dominant language
Python
Stars
1.6k
Forks
165
Avg merge
14h 52m
Merged PRs (30d)
303

Description

## Summary

At a mission's `review` step, `spec-kitty next --result success` reports required artifacts as
missing while `spec-kitty next` in query mode — against the identical repository state —
reports no guard failures at all. The advance path and the query path disagree, and the advance
path is the one that is wrong.

There is no recovery available to an operator: everything inspectable says the mission is
ready, and the one command that advances it says otherwise without naming an actionable
difference.

## Reproduction

Observed on a `qa`-type mission provided by an org doctrine pack, at the `review` step, with:

- both required artifacts (`qa-traceability.yaml`, `test-report.md`) authored at the paths the
step's own expected-artifacts manifest specifies,
- both committed,
- all work packages driven to `approved`.

Three probes against that same tree:

```
$ spec-kitty next --result success
blocked — guard_failures: ["qa-traceability.yaml", "test-report.md"]

$ spec-kitty next # query mode
guard_failures: []
approved_wps: 2
```

and calling the functions `next` itself uses, directly in-process:

```python
_check_cli_guards(...) # -> no failures
gather_artifact_presence(...) # -> both artifacts present
```

Re-running `next --result success` returns the identical `blocked` result indefinitely.

## Impact

This is reachable from the documented happy path of a shipped doctrine pack — a consumer
following that pack's own install runbook and driving a mission arrives here at step six of
seven. It blocks mission completion with no documented or discoverable way forward.

Characterising the symptom required reading `runtime/next/runtime_bridge.py`; an operator
without source access has no way to distinguish this from their own error.

## Hypothesis (unconfirmed)

A stale or cross-worktree read in `committed_authority` / `coord`-topology status resolution,
such that the advance path evaluates artifact presence against a different view of the tree
than the query path does.

## Suggested fix

1. Have the advance path resolve state through the same path the query path uses, so the two
cannot disagree.
2. Independently of the root cause: make a `blocked` result name **the specific file and the
specific absolute-or-repo-relative path it looked at**. A guard that reports "missing"
without saying where it looked is not diagnosable without a source read, and that is what
turned this from a bug into a dead end.

## Provenance

Found during an end-to-end validation run of an org doctrine pack. Reproduced repeatedly.

Measured against source commit `db5014ab5b83bb72a0da5a2b68794592cdbb2147`, which **predates**
the recent merge that brought the rebuild branch into this repository. A re-test against
current `main` is in progress and I will comment with the result — if it no longer reproduces,
I will close this with that evidence rather than leaving it open.

A related finding from the same run, filed separately if it survives re-test: the `implement`
step advances with zero work packages ever claimed, so its completion gate cannot fail.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.