bmad-module-ultracode-goal 2.2.0 → 2.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +2 -2
- package/README.md +12 -4
- package/docs/_internal/RELEASING.md +3 -2
- package/docs/architecture.md +6 -6
- package/docs/comparison.md +25 -25
- package/docs/gate-model.md +1 -1
- package/docs/getting-started.md +9 -5
- package/docs/how-it-works.md +5 -5
- package/docs/index.md +1 -1
- package/docs/operating-tips.md +1 -1
- package/docs/troubleshooting.md +6 -3
- package/docs/why-ultracode-goal.md +3 -3
- package/package.json +6 -2
- package/skills/ucg-formalize/SKILL.md +11 -4
- package/skills/ucg-resolve/SKILL.md +4 -4
- package/skills/ucg-status/SKILL.md +21 -8
- package/skills/ultracode-goal/SKILL.md +4 -4
- package/skills/ultracode-goal/assets/module.yaml +1 -1
- package/skills/ultracode-goal/references/define-done.md +3 -1
- package/skills/ultracode-goal/references/execute.md +16 -16
- package/skills/ultracode-goal/references/finalize.md +6 -5
- package/skills/ultracode-goal/references/gate.md +18 -12
- package/skills/ultracode-goal/references/preflight.md +20 -12
- package/skills/ultracode-goal/scripts/drive_epic.py +11 -6
- package/skills/ultracode-goal/scripts/gate_trail.py +107 -18
- package/skills/ultracode-goal/scripts/headless_envelope.py +20 -6
- package/skills/ultracode-goal/scripts/hooks/budget_stop.py +41 -22
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +26 -6
- package/skills/ultracode-goal/scripts/preflight_check.py +237 -12
- package/skills/ultracode-goal/scripts/status_render.py +96 -19
- package/tools/cli/lib/platform-codes.yaml +1 -1
- package/tools/cli/lib/ui.js +1 -1
- package/tools/validate-docs-links.js +302 -29
|
@@ -23,9 +23,9 @@ Stage 5's subject is a COMMIT, but an assessor that runs or times anything by de
|
|
|
23
23
|
|
|
24
24
|
Record in `.decision-log.md`, once per gated story, whether the gate measured a worktree or the main tree — the same honesty line the sweep's `scope=` carries: an assessment reported as isolated that actually ran on the shared tree is a false claim about the evidence.
|
|
25
25
|
|
|
26
|
-
## Non-web stack
|
|
26
|
+
## Non-web stack: the red phase by hand, and the trace artifacts where trace cannot run
|
|
27
27
|
|
|
28
|
-
|
|
28
|
+
On TEA 1.27.2, `bmad-testarch-trace` runs on any stack (verified on a pytest project, where it authored the gate with `gate-provenance: tea`), so run it first on every stack and read its decision. Two things in this section still apply. The red phase established by hand (items 2 to 4 below) applies on any stack ATDD's generator cannot serve, whether or not trace runs. The two trace files described next are the fallback for when trace halts or cannot run (an older TEA build, say): then nothing else emits the binding gate decision, and you author it. Do **not** reverse-engineer a prior run's leftover artifacts — author the two files to the exact shape `scripts/gate_eval.py` reads; every other field in real TEA output (`target`, `links`/`trace_report_path`, `rationale`, `schema_version`) is decoration the reader never touches. **Name all four for the story** — `trace-<id>.md`, `gate-decision-<id>.json`, and on the production path `nfr-assessment-<id>.md` and `test-review-<id>.md`. The first pair must be per-story because `--story <id>` scoping resolves them by name in a shared `--trace-output` dir. The second pair binds nothing mechanically (the `--nfr` / `--test-review` flags take an explicit path), which is exactly why it needs stating: unnamed, each story's NFR and review overwrite the last one's in that shared directory, and the audit trail keeps only whichever story finished most recently.
|
|
29
29
|
|
|
30
30
|
**`trace-<id>.md`** — only the frontmatter is read (the body is human prose). The resolver needs exactly two keys:
|
|
31
31
|
|
|
@@ -46,19 +46,19 @@ gateDecisionFile: gate-decision-<id>.json # the slim file to read; a bare filena
|
|
|
46
46
|
|
|
47
47
|
Write a PASS only when the story is demonstrably done to its profile's Definition-of-Done (under `--light`: acceptance criteria satisfied with lint and build green; under production the bar is higher — also un-skipped passing acceptance tests plus test-review/code-review, per the profile note below — see `references/define-done.md`); a non-green story is `reloop`/`escalate`, never a hand-authored PASS (see the INVARIANT in "Route on the verdict"). `p0_status`/`p1_status`/`overall_status` are passthrough-only here — they do not drive the `--light` verdict, so write them to reflect reality, never to dress up a non-green story. If you instead write the always-present `e2e-trace-summary.json`, the reader takes its top-level `gate_status` and the nested `gate_criteria.{p0_status,p1_status,overall_status}` — the same fields one level down.
|
|
48
48
|
|
|
49
|
-
**Which profile's gate you then run.** The hand-authored trace decision above is the same file for either profile; only what you AND onto it differs. Under **`--light`** it *is* the whole gate — run `gate_eval.py --profile light` (below) and stop. Under **production** — the legitimate case when an operator scopes foundational, non-web packages to the full chain — the production ANDs still apply.
|
|
49
|
+
**Which profile's gate you then run.** The hand-authored trace decision above is the same file for either profile; only what you AND onto it differs. Under **`--light`** it *is* the whole gate — run `gate_eval.py --profile light` (below) and stop. Under **production** — the legitimate case when an operator scopes foundational, non-web packages to the full chain — the production ANDs still apply. What a non-web stack cannot use as-is is ATDD's generator in Stage 3, which on TEA 1.27.2 detects a backend stack but still emits only Playwright/TypeScript scaffolds. Trace runs on any stack, and automate lists a backend worker (pytest, JUnit, go-test) that this module has not yet verified. So the story's acceptance tests are authored and driven in the stack's own harness (the Vitest case) and reach the production Definition-of-Done un-skipped and passing; the trace decision is TEA's wherever trace runs, and you hand-author it as above only where it cannot.
|
|
50
50
|
|
|
51
|
-
**A production story on this path owes five deliverables.** (A `--light` story owes two of them
|
|
51
|
+
**A production story on this path owes five deliverables.** (A `--light` story owes at most two of them, items 1 and 5, and item 1 only where trace cannot run: the trace decision *is* its whole gate, and provenance is logged whichever path it took.) Each is independently checkable and each has been independently dropped by a run that complied with the rest — so they are numbered rather than prosed, and a production story is done with this section only when all five exist:
|
|
52
52
|
|
|
53
|
-
1. **The
|
|
53
|
+
1. **The trace decision** — TEA's own wherever trace runs, and the two hand-authored files above only where it cannot.
|
|
54
54
|
2. **The red phase is established BY HAND, and it must still be established.** Where ATDD cannot generate the `test.skip()` scaffold: author the acceptance cases with real assertions and RUN them before the first implementation edit — the window this rule governs closes in Stage 4, which is why `references/execute.md` step 1 states the same obligation where the first-edit decision is actually made. This section otherwise rules the artifacts thoroughly and the acceptance-test BAR ("un-skipped and passing") while saying nothing about how un-skipped is reached from a red start — so a run that skipped the red phase entirely satisfies every other sentence here. **A case nobody ever saw fail is not evidence**, and a hand-authored PASS resting on one is the same dishonesty the hand-authored-PASS rule above forbids.
|
|
55
55
|
3. **Capture that run's raw output to a file** under `{workflow.implementation_artifacts}`. An independent deliverable, not a detail of item 2: the capture is what makes the red phase auditable after the fact, and it cannot be honestly re-made once the implementation lands — a run that ran the red phase and read the result but captured nothing holds strictly weaker evidence than this item asks for, and a labelled transcription is the most it can honestly write.
|
|
56
|
-
4. **The red count recorded in the trace report, with a one-line justification for every case that was already green.** Where a shared acceptance file accumulates already-shipped siblings' cases, those green-by-design cases may be justified as one line naming that class rather than case-by-case — the per-case justification owed is for THIS story's cases that never went red.
|
|
57
|
-
5. **`gate-provenance
|
|
56
|
+
4. **The red count recorded in the trace report, with a one-line justification for every case that was already green.** Where TEA authored the trace report, record them beside the captured output of item 3 and in `.decision-log.md` instead, never in TEA's file: an edit there would make its provenance false. Where a shared acceptance file accumulates already-shipped siblings' cases, those green-by-design cases may be justified as one line naming that class rather than case-by-case — the per-case justification owed is for THIS story's cases that never went red.
|
|
57
|
+
5. **`gate-provenance:`, logged per story** exactly as "Run the gate" below requires: `gate-provenance: hand-authored` where item 1 applied, and `tea` where trace ran. A run that takes the hand-authored branch on every row produces an Epic whose every verdict rests on a file the run wrote for itself, and nothing else in the artifacts would say so.
|
|
58
58
|
|
|
59
|
-
`bmad-testarch-nfr` and `bmad-testarch-test-review` are independent of
|
|
59
|
+
`bmad-testarch-nfr` and `bmad-testarch-test-review` are independent of the automate→trace pair (see "Backfill the gate evidence" above), so still produce `nfr-assessment.md` and `test-review.md` the normal way and run `gate_eval.py --profile production --story <story_id> --nfr <…/nfr-assessment-<story_id>.md> --test-review <…/test-review-<story_id>.md> --tests-ran {workflow.implementation_artifacts}/.tests-ran-<story_id>`. Pass **both** signal flags (and `--tests-ran`, which every per-story gate carries — the sweep-scope AND binds this path unchanged). `gate_eval.py` fail-closes a `--nfr`/`--test-review` path that is given-but-missing **and one you simply omit**: an omitted flag on a per-story production gate is itself a failing signal, with a reason naming the flag. That is deliberate — a forgotten flag used to be skipped in silence, so the AND never ran, the field rendered `null`, and the verdict was computed without it, which bought a *higher* verdict than supplying a failing artifact would have. If a signal genuinely cannot be produced on the stack, that is a CONCERNS/`defer` or a `reloop`, never a dropped flag. The one legitimate omission is the epic roll-up, which declares itself with `--epic-level` (see "Route on the verdict") rather than by leaving the flags off. A stack that cannot meet the production acceptance-test bar at all belongs under `--light` (see the framework fitness caveat in `references/preflight.md`), not a hand-waved production PASS. The honesty bar is unchanged: a PASS requires full AC coverage by passing tests, never to dodge an AND.
|
|
60
60
|
|
|
61
|
-
**The epic-level roll-up needs no hand-authoring at all where sprint-status is available: run it with `--rollup`** (see "Route on the verdict"), which computes the aggregate from the per-story artifacts this section already had you author — no `trace-<epic>.md` required. Hand-author the epic pair only where the gate cannot be given sprint-status. **In that fallback the roll-up needs the same hand-authoring, named for the EPIC.** Everything above is written per story, and
|
|
61
|
+
**The epic-level roll-up needs no hand-authoring at all where sprint-status is available: run it with `--rollup`** (see "Route on the verdict"), which computes the aggregate from the per-story artifacts this section already had you author — no `trace-<epic>.md` required. Hand-author the epic pair only where the gate cannot be given sprint-status. **In that fallback the roll-up needs the same hand-authoring, named for the EPIC.** Everything above is written per story, and where trace cannot run nothing ever writes the epic's own `trace-<epic>.md`, while the omit-`--rollup` form of the gate below presumes it exists: `--story <epic_id>` in a per-story-named directory resolves nothing and fail-closes a completed Epic to `escalate`. When every story is `done`, hand-author the same two files named for the epic id — `trace-<epic>.md`, its frontmatter pointing at `gate-decision-<epic>.json` — with a `gate_status` that honestly summarises the per-story record: a PASS only when every story advanced, never a roll-up dressed over a story that did not. It takes no NFR and no test-review; the roll-up declares that omission with `--epic-level`, per "Route on the verdict" below.
|
|
62
62
|
|
|
63
63
|
**Hand-authored `nfr-assessment.md` and `test-review.md` shapes (production path only).** `gate_eval.py` scans these two files with the *same* parser it uses on real TEA output, so a hand- or agent-authored file must carry the exact fields below — otherwise the scanner reads the signal as *not found* and, under the fail-closed contract, treats it as **failing**, spuriously downgrading an `advance` to `reloop`. (Under `--light` neither file is read, so this whole block is production-only.) Only the named field is parsed; everything else is human prose.
|
|
64
64
|
|
|
@@ -81,6 +81,8 @@ The score **must** carry the `/100` denominator: a bare `score: 89` matches noth
|
|
|
81
81
|
|
|
82
82
|
## Run the gate
|
|
83
83
|
|
|
84
|
+
**Name the per-story paths trace writes, in either profile.** TEA 1.27.2's `bmad-testarch-trace` writes fixed, flat paths at the TEA `test_artifacts` root (`traceability-matrix.md`, `e2e-trace-summary.json`, `gate-decision.json`) and does not read `trace_output`. Left alone, its output neither lands in `{workflow.trace_output_dir}` nor names a story, so the gate below resolves nothing there, and each story's trace overwrites the last one's. When you delegate trace for a story, name the paths it must write in `{workflow.trace_output_dir}`: `trace-<story_id>.md` (frontmatter `workflowType: testarch-trace` and `gateDecisionFile: gate-decision-<story_id>.json`), `gate-decision-<story_id>.json` and `e2e-trace-summary-<story_id>.json`, with `<story_id>` the sprint-status key copied verbatim. If it writes the flat files anyway, move them to those names before anything else reads or overwrites them. Ask for nothing beyond those names and those frontmatter keys: the provenance stays `tea` only while TEA's own steps computed the content.
|
|
85
|
+
|
|
84
86
|
Production:
|
|
85
87
|
|
|
86
88
|
```
|
|
@@ -95,7 +97,7 @@ uv run {skill-root}/scripts/gate_eval.py --trace-output {workflow.trace_output_d
|
|
|
95
97
|
|
|
96
98
|
Resolve `{nfr-assessment.md}` and `{test-review.md}` to the paths TEA wrote them to (under `{workflow.trace_output_dir}` or the TEA output root); pass the production-only flags only in production. The script reads `gate-decision.json` (resolving its filename from the trace report frontmatter, falling back to the `e2e-trace-summary.json` gate fields when the slim file is absent — that fallback is **not** a failure).
|
|
97
99
|
|
|
98
|
-
**`--story` in a shared multi-story trace dir.** When every story in a multi-story Epic writes a per-story-named trace report + gate decision (`trace-<id>.md`, `gate-decision-<id>.json`) into the **one** shared `{workflow.trace_output_dir}`, an unscoped read resolves the first/oldest story's gate — a false verdict for every later story. Pass `--story <story_id>` (the id of the story you are gating) so resolution is scoped to that story's artifacts; matching is on id components (`11-6` == `11.6` == `11_6`) anchored to the trailing components, so epic id `1` resolves `trace-1` and never the child story `1-1`'s report. **`<story_id>` is ONE string, used byte-identically in three places:** the story's `sprint-status.yaml` key, the `<id>` in the artifact filenames above (`trace-<id>.md`, `gate-decision-<id>.json`, and the same `<id>` in the per-story NFR and test-review names the non-web section
|
|
100
|
+
**`--story` in a shared multi-story trace dir.** When every story in a multi-story Epic writes a per-story-named trace report + gate decision (`trace-<id>.md`, `gate-decision-<id>.json`) into the **one** shared `{workflow.trace_output_dir}`, an unscoped read resolves the first/oldest story's gate — a false verdict for every later story. Pass `--story <story_id>` (the id of the story you are gating) so resolution is scoped to that story's artifacts; matching is on id components (`11-6` == `11.6` == `11_6`) anchored to the trailing components, so epic id `1` resolves `trace-1` and never the child story `1-1`'s report. **`<story_id>` is ONE string, used byte-identically in three places:** the story's `sprint-status.yaml` key, the `<id>` in the artifact filenames above (`trace-<id>.md`, `gate-decision-<id>.json`, and the same `<id>` in the per-story NFR and test-review names the non-web section above pins), and this `--story` argument. Copy the key verbatim, whether it is bare (`4-2`) or carries a kebab title slug (`4-2-<kebab-title>`); do not abbreviate it to its number when invoking, and do not expand it when naming. When TEA wrote the files under other names, rename them to the sprint-status key per "Name the per-story paths trace writes" at the top of this section, rather than passing the stem it wrote. **A mismatch fails in both directions**: `--story 4-2-<kebab-title>` resolves `gate-decision-4-2-<kebab-title>.json` and *not* `gate-decision-4-2.json`, and `--story 4-2` resolves neither. The tolerance is deliberately no wider than this — matching is anchored to the trailing components on purpose, because a prefix match would let epic id `4` resolve `trace-4-2-<kebab-title>.md` and hand the epic roll-up a child story's verdict, which is the fail-open the anchor exists to close. **Recognise the symptom:** a spelling mismatch surfaces as `gate_status: NOT_EVALUATED` -> `escalate`, worded identically to a story that genuinely wrote nothing, so before treating that `escalate` as a real block, list `{workflow.trace_output_dir}` and compare the exact stem. For the **epic-level** gate after the last story, pass the epic's own id the same way (it resolves the epic's `trace-<epic>` report, not any child story). **`--story` fails closed on a genuine no-match — this is a behaviour change.** It used to fall back to the unscoped read whenever nothing matched, which meant a story that wrote *no* artifacts at all silently reported a NEIGHBOURING story's gate as its own: an unevaluated story could read `PASS`/`advance`. Now the fallback depends on how the directory is **named**. If any artifact there is named for a story, a `--story` that matches nothing means that story is genuinely absent, and the read returns `gate_status: NOT_EVALUATED` -> `escalate`, with a reason naming the artifact KIND that made the directory per-story-named (never a neighbour's filename — quoting one in an absent story's verdict is the very fail-open this branch closes). **"Named for a story" is wider than the two gate-bearing files, and the test is not "ends in a number".** Seven prefixes count — `gate-decision`, `e2e-trace-summary`, `nfr-assessment`, `test-review`, `traceability-matrix`, `trace`, `atdd-checklist` — and the rule is that the component **immediately after the prefix starts with a digit**, so `trace-92-0a.md` and `trace-5-8-some-slug.md` both count even though neither ends in a number. Two consequences worth holding: a per-story NFR assessment or test review, alone, flips the directory per-story-named on its own even with no trace or gate file beside it — and those are artifacts the non-web section above orders into this same directory; and an id whose first component is not a digit (`trace-st-5.md`) does not flip it, which is one more reason the isolated-track rule requires a numeric epic prefix. If instead every candidate is generically named (`trace.md`, `gate-decision.json`), the directory holds one story's artifacts and the documented unscoped fallback still applies, so passing `--story` against a single-story dir resolves exactly as before. `--story` remains optional; omit it only when `{workflow.trace_output_dir}` provably holds a single story's artifacts. If you were relying on the old silent fallback in a per-story-named dir, you will now get an `escalate` instead of a verdict — which is the point: it surfaces a story whose gate was never produced. TEA 1.27.2 does not name its trace artifacts per story on its own: give it the per-story names, or move its flat files to them, in the shared `{workflow.trace_output_dir}` exactly as "Name the per-story paths trace writes" at the top of this section says. Never isolate a story into a fresh directory instead: the `--rollup` Epic gate refuses a multi-story Epic whose trace directory is not per-story-named, and the gate trail reads one trace directory. It returns JSON:
|
|
99
101
|
|
|
100
102
|
```json
|
|
101
103
|
{"verdict": "advance|defer|reloop|escalate",
|
|
@@ -116,7 +118,11 @@ Do not recompute TEA thresholds or re-judge `gate_status` — read it as given.
|
|
|
116
118
|
|
|
117
119
|
## Route on the verdict
|
|
118
120
|
|
|
119
|
-
- **`advance`** (gate_status PASS or WAIVED) → the story passes. **Sync the story's row in `sprint-status.yaml` to `done` before moving on** — set `development_status[<story_id>]` to `done`, preserving the file's comments and key order, and log the transition in `.decision-log.md`. This write is the run's own, not a sub-skill's: `bmad-dev-story` leaves the row at `review`, and `bmad-code-review` (production only — it does not run under `--light` at all) writes `done` **only** when nothing was left as an action item, so a story that legitimately `defer`s a non-critical finding is left at `in-progress`. Every downstream reader keys on `done` — Stage 1's in-scope rule (`references/ingest-and-scope.md` rule 3), the Epic-level trigger in this very sentence, and `scripts/drive_epic.py`'s progress check — so an advanced story whose row still says `review` is an advanced story the next reader re-drives, and an Epic whose last story advanced without this write never satisfies the Epic-level condition below. Sync it here, at the one place the authoritative verdict is known.
|
|
121
|
+
- **`advance`** (gate_status PASS or WAIVED) → the story passes. **Sync the story's row in `sprint-status.yaml` to `done` before moving on** — set `development_status[<story_id>]` to `done`, preserving the file's comments and key order, and log the transition in `.decision-log.md`. This write is the run's own, not a sub-skill's: `bmad-dev-story` leaves the row at `review`, and `bmad-code-review` (production only — it does not run under `--light` at all) writes `done` **only** when nothing was left as an action item, so a story that legitimately `defer`s a non-critical finding is left at `in-progress`. Every downstream reader keys on `done` — Stage 1's in-scope rule (`references/ingest-and-scope.md` rule 3), the Epic-level trigger in this very sentence, and `scripts/drive_epic.py`'s progress check — so an advanced story whose row still says `review` is an advanced story the next reader re-drives, and an Epic whose last story advanced without this write never satisfies the Epic-level condition below. Sync it here, at the one place the authoritative verdict is known. In the same write, move the Epic's own `epic-<id>` row from `backlog` to `in-progress` when it still reads `backlog` (never backward, and only when the key exists): `bmad-build` makes that move when a story starts, but the story skills this run delegates to skip it when handed an explicit story key, so without it a finished Epic still reads `backlog`. If the Stop hook left a turn-budget marker for this story (`{workflow.implementation_artifacts}/.escalation-<story_id>.md`) and its count is still at or past the ceiling, do **not** promote it: log the sizing note `references/execute.md` describes under "Promoting the turn-budget marker", and leave the marker in place.
|
|
122
|
+
|
|
123
|
+
**Commit the gate's evidence before the next story starts.** The `done` sync, this story's trace and gate files (`trace-<id>.md`, `gate-decision-<id>.json`, `e2e-trace-summary-<id>.json`, and in production its per-story NFR assessment and test review), this gate's ledger rows and the decision log (with the first story, also Stage 3's test-design output) are tracked state written after Execute's commit-at-green. While `.current-story` still names this story, stage those of these paths that exist and are not ignored, by explicit path, in one call, and commit them in a second, before the next story's step 0. For the story whose advance makes every story `done`, make this commit after the Epic-level gate below instead, so it also carries that gate's writes. The commit carries no source or test path, so the story's existing tests-ran marker covers it: reuse that marker as it stands and never rewrite it for this commit. If it must carry an executable path (in production, tests automate backfilled), re-run the sweep and write a fresh marker per `references/execute.md` step 5 first. Then refresh `.commit-<story_id>` from `HEAD`, so this story's range in the gate trail includes the evidence commit. A path the project ignores is logged and left out, never forced in with `git add -f`; if nothing is staged, make no commit and leave `.commit-<story_id>` as it is. A resume that finds an advanced story's evidence still uncommitted makes this commit for it before the next story's step 0: point `.current-story` back at that story (its tests-ran marker still passes the guard), commit, and refresh its `.commit-<story_id>`. Then move to the next story.
|
|
124
|
+
|
|
125
|
+
When **every story of the Epic is `done`**, run the Epic-level gate: pass the epic's own id via `--story`, **add `--epic-level`**, and read its `gate_status` **only**. TEA produces NFR and test-review **per story, not per epic**, so there is no epic-level aggregate to AND, and every story's own production gate already ANDed its signals before reaching `done`. With `--rollup` the epic id is the sprint-status grouping key and the verdict is a computation over the per-story record; only in the omit-`--rollup` fallback is `--story` resolved against an epic-named artifact (scoped per the `--story` note above) and the roll-up a pure trace read. When the Epic-level gate returns `advance`, or `defer` (whose route advances anyway), set the `epic-<id>` row to `done` (when the key exists), preserving comments and key order, log it, and carry it in the last story's evidence commit. BMAD Method 6.12 has no other writer of an epic row's `done`, and `bmad-retrospective` writes only the `epic-<id>-retrospective` row. Never write it on any other route: the work bound, `partial-complete`, a handoff, a block or an escalation.
|
|
120
126
|
|
|
121
127
|
```
|
|
122
128
|
uv run {skill-root}/scripts/gate_eval.py --trace-output {workflow.trace_output_dir} --story <epic_id> --profile production --epic-level --rollup --sprint-status {workflow.implementation_artifacts}/sprint-status.yaml
|
|
@@ -128,7 +134,7 @@ uv run {skill-root}/scripts/gate_eval.py --trace-output {workflow.trace_output_d
|
|
|
128
134
|
|
|
129
135
|
- **`defer`** (gate_status CONCERNS, or non-critical code-review / NFR findings that did not flip the gate) → append the open items to the ledger at `{workflow.deferred_work_path}` using the schema below, then **advance** anyway. The Epic keeps moving; the parked work is visible.
|
|
130
136
|
|
|
131
|
-
- **`reloop`** (gate_status FAIL, or a production signal downgraded an advance, or a cap — sweep-scope or delta-profile) → **generalize before fixing.** Before `bmad-correct-course` writes any fix, take the verdict's `reasons` and the review's findings and, for each finding: (1) name, in ONE line, the defect CLASS the finding is an instance of; (2) state whether any earlier review of this story or this Epic already found that class — the previous gate artifacts and `{workflow.implementation_artifacts}/.class-ledger-<epic_id>.md` are the evidence, and they are already on disk, so this is a read, not a judgment call; (3) where the class is a repeat, the fix must close the CLASS — every sibling instance the same seam admits, not the one instance the reviewer demonstrated — and the log records why the class-level fix was not taken when the class was first named. A measured run spent five of six reviews re-finding one class ("an assertion that cannot go red") one seam over each time, with the class-killing move available from day one; the generalize step is what makes cycle N read cycle N-1 instead of re-buying it. Record one `class:` line per finding in this re-loop's `.decision-log.md` entry, and append any class not already present to `.class-ledger-<epic_id>.md` (create on first use; named for the Epic, so a later Epic starts a fresh ledger while this Epic's survives across its own invocations for exactly the resume case; one line per class, `- <class, one line> — first named <story_id>, cycle <n>`; **append-only** — Execute step 1 reads it before every story and re-loop, so a class named once is warned about everywhere after, including across stories, which no per-story artifact can do). **A score that does not move indicts the FIX STRATEGY, not the code:** when two consecutive gate evaluations of this story have moved `review_score` by less than 3 (production — under `--light` no review score exists, so the trigger there is two consecutive re-loops whose findings name any class already in the ledger), the generalize answers above are mandatory *in writing* before any further fix — a re-loop whose findings all name the same class as the previous re-loop's is a re-loop about to be spent badly. **A cap-only re-loop skips the ceremony.** When a cap alone produced the verdict — the `reasons` show only the sweep-scope cap, the delta-profile cap, or both, with no gate FAIL and no failed production signal — there is no finding to generalize and nothing to diagnose: re-run the full three-axis sweep where the sweep cap fired and refresh the marker with `scope=full`, then re-run the gate as the FULL instrument — **dropping `--cycle-profile`**, because the delta cap is lifted by the flag's absence and a re-gate that keeps it caps again forever — writing no `class:` lines, appending nothing to the ledger, and skipping `bmad-correct-course` entirely; such evaluations do not count toward the flat-score tripwire, and a capped CONCERNS keeps its findings for the next gate's own `defer` route — parking them is that gate's job, not this re-loop's. Otherwise, run `bmad-correct-course` to diagnose and adjust, then re-run the story (back through Execute, `references/execute.md`) — **within the remaining turn budget**. Re-run the gate after. If the re-loop would exceed `{workflow.max_turns_per_story}`, treat it as `escalate` instead.
|
|
137
|
+
- **`reloop`** (gate_status FAIL, or a production signal downgraded an advance, or a cap — sweep-scope or delta-profile) → **generalize before fixing.** Before `bmad-correct-course` writes any fix, take the verdict's `reasons` and the review's findings and, for each finding: (1) name, in ONE line, the defect CLASS the finding is an instance of; (2) state whether any earlier review of this story or this Epic already found that class — the previous gate artifacts and `{workflow.implementation_artifacts}/.class-ledger-<epic_id>.md` are the evidence, and they are already on disk, so this is a read, not a judgment call; (3) where the class is a repeat, the fix must close the CLASS — every sibling instance the same seam admits, not the one instance the reviewer demonstrated — and the log records why the class-level fix was not taken when the class was first named. A measured run spent five of six reviews re-finding one class ("an assertion that cannot go red") one seam over each time, with the class-killing move available from day one; the generalize step is what makes cycle N read cycle N-1 instead of re-buying it. Record one `class:` line per finding in this re-loop's `.decision-log.md` entry, and append any class not already present to `.class-ledger-<epic_id>.md` (create on first use; named for the Epic, so a later Epic starts a fresh ledger while this Epic's survives across its own invocations for exactly the resume case; one line per class, `- <class, one line> — first named <story_id>, cycle <n>`; **append-only** — Execute step 1 reads it before every story and re-loop, so a class named once is warned about everywhere after, including across stories, which no per-story artifact can do). **A score that does not move indicts the FIX STRATEGY, not the code:** when two consecutive gate evaluations of this story have moved `review_score` by less than 3 (production — under `--light` no review score exists, so the trigger there is two consecutive re-loops whose findings name any class already in the ledger), the generalize answers above are mandatory *in writing* before any further fix — a re-loop whose findings all name the same class as the previous re-loop's is a re-loop about to be spent badly. **A cap-only re-loop skips the ceremony.** When a cap alone produced the verdict — the `reasons` show only the sweep-scope cap, the delta-profile cap, or both, with no gate FAIL and no failed production signal — there is no finding to generalize and nothing to diagnose: re-run the full three-axis sweep where the sweep cap fired and refresh the marker with `scope=full`, then re-run the gate as the FULL instrument — **dropping `--cycle-profile`**, because the delta cap is lifted by the flag's absence and a re-gate that keeps it caps again forever — writing no `class:` lines, appending nothing to the ledger, and skipping `bmad-correct-course` entirely; such evaluations do not count toward the flat-score tripwire, and a capped CONCERNS keeps its findings for the next gate's own `defer` route — parking them is that gate's job, not this re-loop's. A cap-only re-gate re-measures without re-driving the story, so the turn-ceiling rule below never turns it into `escalate`. Otherwise, run `bmad-correct-course` to diagnose and adjust, then re-run the story (back through Execute, `references/execute.md`) — **within the remaining turn budget**. Re-run the gate after. If the re-loop would exceed `{workflow.max_turns_per_story}`, treat it as `escalate` instead; the count is the `turns` value the Stop hook records in `{workflow.implementation_artifacts}/.budget-<story_id>.json`. When the hook left a turn-budget marker for this story, that escalation's sidecar is the marker's promotion (`references/execute.md`, "Promoting the turn-budget marker").
|
|
132
138
|
|
|
133
139
|
- **`escalate`** (gate_status NOT_EVALUATED — the gate could not be read — or budget exhausted on a FAIL) → **stop.** Do not advance, do not defer the failing item. Record the reason and the verdict JSON in `.decision-log.md`, and write the typed escalation sidecar `{workflow.implementation_artifacts}/escalation-<story_id>.json` (shape in `references/execute.md`, under "Escalation sidecar") so the pending decision is readable without the transcript. In an attended run, surface the blocker to the user. In headless, this is a `blocked` outcome — emit the JSON in Stage 6 (`references/finalize.md`).
|
|
134
140
|
|
|
@@ -16,8 +16,9 @@ Qualify the script path with `{skill-root}` (per SKILL.md Conventions a bare `sc
|
|
|
16
16
|
{green: bool, budget: int,
|
|
17
17
|
blockers: [{id, kind, severity, detail, remediable: bool}],
|
|
18
18
|
checks: {cc_version, goal_ok, workflows_ok, automemory_ok, git_branch, git_clean,
|
|
19
|
-
framework_present, framework_kind, test_artifacts_dirs,
|
|
20
|
-
project_context_count, tea_flags
|
|
19
|
+
git_unborn, framework_present, framework_kind, test_artifacts_dirs,
|
|
20
|
+
sprint_status_present, project_context_count, tea_flags, bmad_skills,
|
|
21
|
+
bmad_install}}
|
|
21
22
|
```
|
|
22
23
|
|
|
23
24
|
`budget` is the count of mechanical blockers. The script does **not** decide semantic intervention — that is your job in step 3. Treat `green: true` from the script as *necessary but not sufficient*.
|
|
@@ -42,12 +43,14 @@ Per the measurement protocol, log the formalize duration provenance — `wall_cl
|
|
|
42
43
|
|
|
43
44
|
Clear each remediable blocker, then **re-run the check** so the budget reflects the fixes. Remediate:
|
|
44
45
|
|
|
46
|
+
- **HEAD has no commit yet** (`git_unborn`, `remediable: false`): a fresh `git init`, or an orphan branch, with nothing committed. While this blocker stands, make **no** branch and **no** commit in this pass, neither for `git_branch` nor for `git_clean`, and run **no** other remediation that writes to the tree: the operator's baseline should hold their project, not this run's scaffolding. A run-made first commit would become the branch's root commit, either on the protected branch or on an Epic branch with nothing under it, and deleting that branch (the run's only undo) would then also delete the only record of the pre-run tree. Record the other blockers in the blocked account instead. The blocker stands, step 4 stops the run, and its `detail` asks the operator to commit a baseline on their base branch, never on an Epic branch, and re-run.
|
|
45
47
|
- **On a protected branch** (`git_branch`): create this run's working branch — `{workflow.epic_branch_prefix}<epic-id>`, the same branch step 5 asserts — and check out onto it. The blocker is `remediable: true` and counts toward `budget`, so it has to clear *here*, like every other remediable blocker: step 5, the only other place the doc creates this branch, is headed "only when the gate passes" and so can never be what clears a blocker the gate is waiting on. Branch **before** the `git_clean` clear — `git checkout -b` carries an uncommitted tree across, and a remediation commit landed on a `{workflow.protected_branches}` branch sits outside the only rollback this run has (per step 5, deleting the branch is the real undo). Then re-run the check so `git_branch` clears. **This moves git state ahead of the hard gate**, so a run that STOPs at step 4 now leaves the operator checked out on a branch they never saw a launch briefing for: name the branch in the blocked account, and say that deleting it is the undo.
|
|
46
|
-
- **Test framework absent** (`framework_present: false`): the script already counts a pytest config / root `conftest.py` or a real `package.json` `test` script as a present framework (`framework_kind` is then `pytest` / `npm-test`, or `js-config` for a Playwright/Cypress/Jest/Vitest config), so a non-browser project does **not** trip this blocker. When it *does* fire (no harness of any kind recognized), scaffold one **appropriate to the stack**: for a web/E2E project, `bmad-testarch-framework` (Playwright/Cypress per `tea_flags`); for a **pytest or npm-script** project, stand up that harness directly (a `pytest.ini` / `conftest.py`, or a real `test` script) rather than an inapplicable browser framework — then re-run the check so `framework_present` flips true. ATDD in Stage 3 hard-halts without a configured framework — this must exist before launch. **Fitness caveat:** TEA
|
|
48
|
+
- **Test framework absent** (`framework_present: false`): the script already counts a pytest config / root `conftest.py` or a real `package.json` `test` script as a present framework (`framework_kind` is then `pytest` / `npm-test`, or `js-config` for a Playwright/Cypress/Jest/Vitest config), so a non-browser project does **not** trip this blocker. When it *does* fire (no harness of any kind recognized), scaffold one **appropriate to the stack**: for a web/E2E project, `bmad-testarch-framework` (Playwright/Cypress per `tea_flags`); for a **pytest or npm-script** project, stand up that harness directly (a `pytest.ini` / `conftest.py`, or a real `test` script) rather than an inapplicable browser framework — then re-run the check so `framework_present` flips true. ATDD in Stage 3 hard-halts without a configured framework — this must exist before launch. **Fitness caveat:** on TEA 1.27.2, ATDD detects a backend stack but still emits only Playwright/TypeScript scaffolds, and automate's backend worker (pytest, JUnit, go-test) is not yet verified with this module, so on a non-web module the framework is *present* but not *fit* for that pair; run such a module under `--light` (test-design and the trace gate, both of which run on any stack; no ATDD — see define-done.md's `--light` note and gate.md).
|
|
47
49
|
- **CI quality pipeline absent** (production profile only): if no CI quality pipeline exists yet, scaffold it via `bmad-testarch-ci` **after** the framework exists — `bmad-testarch-ci` halts if the framework is absent, so the strict order is framework → ci. This is one-time infra (force **Create** mode); the pipeline embeds TEA's coverage thresholds so the gate also lives durably in CI, while the per-epic loop gate remains `gate_eval.py` in Stage 5. Skip under `--light`.
|
|
48
50
|
- **Missing acceptance criteria / story** for an in-scope story: generate via `bmad-create-story` so each story carries clear, testable ACs. TEA atdd and trace both need them; a story without ACs has nothing to trace and will stall.
|
|
49
|
-
- **
|
|
50
|
-
-
|
|
51
|
+
- **BMAD story skills not installed** (`bmad_skills`, `remediable: false`): `bmad-create-story` and `bmad-dev-story` are the skills this run delegates story creation and implementation to, and BMAD Method 6.12 or later ships them as deprecated shims: a fresh install leaves them out unless asked for (`--shims`, or Yes at the installer's shim prompt), and an update removes them when told not to keep them (`checks.bmad_install` carries the recorded `version` and `install_shims`). This pass does not install them: the blocker stands, step 4 stops the run, and its `detail` (which names the installer command) is the account the operator acts on. Never clear it by substituting another skill (`bmad-build`, `bmad-build-auto`) or by writing the story file or the code by hand: the rest of the run reads the story file these two produce (`{story_key}.md` with numbered acceptance criteria), and a stand-in reaches the gate looking like a story that went through them.
|
|
52
|
+
- **Test-artifacts dirs absent** (`test_artifacts_dirs` incomplete): pre-create the trace/test-design/test-review output dirs (`{workflow.trace_output_dir}` and its siblings under the TEA `test_artifacts` root) so the per-story files the gate reads have a directory to land in. On TEA 1.27.2 trace does not read `trace_output`, so creating the directory does not route its output there: `references/gate.md` says how the per-story trace files reach it.
|
|
53
|
+
- **`project-context.md` count != 1** (`project_context_count`): advisory only. `preflight_check.py` reports it as a **check** and never appends it to `blockers[]`, so a count of `0` or `> 1` never moves `budget` and never blocks launch. **More than one:** de-duplicate to one, because `{workflow.persistent_facts}` loads every match into this run's context and `bmad-dev-story` and `bmad-code-review` read the file when present, so duplicates feed them conflicting facts. **Zero:** log it in `.decision-log.md` and invoke **no** sub-skill for it. No generator produces the file unattended: before BMAD Method 6.12, `bmad-generate-project-context` stops at interactive menus, and from 6.12 it is a shim that forwards to `bmad-project-context`, which interviews the operator and writes a block into `AGENTS.md`, never a `project-context.md`. A zero count therefore never reaches the remediation halt catch-all below and never becomes a RED. In an attended run, tell the operator they can write the file by hand, or run `bmad-project-context` themselves between runs.
|
|
51
54
|
- **`sprint-status.yaml` absent** (`sprint_status_present: false`): ensure it is present (via `bmad-sprint-planning`). Its presence makes TEA test-design **auto-select Epic-Level** and skip its interactive System/Epic mode prompt — without it, Stage 3 stalls on a question no one is there to answer. **Non-default-track caveat:** `preflight_check.py`'s `sprint_status_present` falls back to a repo-wide `_bmad-output/**` glob, so on a run scoped to a non-default `--impl-artifacts` dir (an isolated track, per ingest-and-scope.md's cross-file/colliding-epic rule) it can read `true` off a *foreign* track's `sprint-status.yaml` while this run's own track has none — this `sprint_status_present: false` trigger then never fires. On any non-default `--impl-artifacts` run, take `formalize_check.py`'s strict per-impl-artifacts read (the §1b `sprint_status_absent` mechanical gap) as the authoritative sprint-status signal and remediate off *that*, not the glob-backed flag.
|
|
52
55
|
- **TEA mode**: force **Create** mode for every TEA workflow this run. Resume/Validate/Edit are interactive and will halt an unattended run. Set/confirm whatever the TEA config exposes (`tea_execution_mode`) so no workflow resumes a prior session.
|
|
53
56
|
- **Secrets / credentials — and unresolvable EXTERNAL DEPENDENCIES generally** — that a story needs (test env keys, API tokens, and equally network egress for anything a story's tasks say to *fetch*: a vendored data file, a crate or package not already in the lockfile, a model download): **interactive** — prompt or resolve **once**, now, and capture secrets out of git. **Headless** — do not prompt; an unresolvable secret **or an external fetch the environment refuses** becomes a RED blocker (step 4), never a deferred question. The fetch case sits in this bullet on the same fail-closed terms as credentials because its discovery otherwise happens mid-Execute, after the work around it is done, with the gate as the story's only exit.
|
|
@@ -55,9 +58,14 @@ Clear each remediable blocker, then **re-run the check** so the budget reflects
|
|
|
55
58
|
|
|
56
59
|
**Stale-hook pre-arming (before any remediation commit).** A prior UCG run may have left its PreToolUse guard (`scripts/hooks/guard_pretooluse.py`) and Stop budget hook (`scripts/hooks/budget_stop.py`) armed in `{project-root}/.claude/settings.local.json` — still live *now*, because step 5 has not yet re-armed this run's hooks. That stale guard mis-governs any remediation that commits (the dirty-tree `git_clean: false` clear especially): its marker-gate keys on `.current-story` plus a `.tests-ran-<story_id>` marker in the impl-artifacts, and on a fresh run `.current-story` is either unset — so no marker resolves and the commit is **denied**, dead-ending the remediation — or still points at the prior run's last story, whose persisted marker (Finalize removes only `.mem-state.json`, never the tests-ran markers) it then **rides to a spurious green**, waving the commit through under stale, wrong-run enforcement. Both failure modes are wrong for this run. Do **not** forge a marker and do **not** wait on the gate: **disarm the prior-run hooks first**, then make the remediation commit, and let step 5 re-merge both hooks freshly with *this* run's injected env. **The entries are nested, not top-level.** `settings.local.json` carries them under a top-level `hooks` key as `hooks.PreToolUse[].hooks[]` and `hooks.Stop[].hooks[]`: each outer element is a matcher group (`Stop` groups carry no `matcher` key) holding its own inner `hooks[]` array, and the UCG entry is the inner item whose `command` string names `guard_pretooluse.py` / `budget_stop.py`. Remove those inner items, and the enclosing matcher group only when that leaves its `hooks[]` empty, so a co-resident non-UCG hook survives. A disarm aimed at top-level `PreToolUse` / `Stop` keys matches nothing, changes nothing, and reports success: the stale guard then rides armed through the whole of preflight while the log records a disarm that never happened. So **mirror step 5's assertion** — re-read the **resolved** settings and confirm neither script path appears in any hook `command`, **before** any remediation commit. Assert on the script path rather than on the shape, so the check still holds if the settings schema moves and so an entry armed in another settings layer is not missed. Disarming is exactly as load-bearing as arming, and is the one this stage would otherwise leave unverified. Log the disarm, that assertion, and the step-5 re-arm to `.decision-log.md`.
|
|
57
60
|
|
|
58
|
-
**
|
|
61
|
+
**A refused settings write.** The disarm above and step 5's arming both write `{project-root}/.claude/settings.local.json`, which Claude Code treats as a protected path. Under Auto Mode, which the hard gate requires, the permission classifier reviews that write: it may refuse it as self-modification, or let it land and then refuse the calls that follow it. In a headless session nobody can approve either refusal. Treat a refusal of the write, or of any call after it until the assertion that write serves has passed, as a stop. Do not retry it through another tool, script, encoding or subagent; do not delete or restore the file; do not forge a marker; do not skip the step-5 assertion; and do not progress. Log the refused action verbatim, the file's state (written or not, asserted or not) and the current branch to `.decision-log.md`. Then:
|
|
59
62
|
|
|
60
|
-
**
|
|
63
|
+
- **Attended:** show the operator the exact content the write was meant to apply, and ask them to approve it (under `/permissions`, on its Recently denied tab) or make the edit themselves. Then re-run the assertion that write served: `preflight_check.py --assert-armed` after arming, or, after a disarm, the check that no hook `command` names either script. A refused **disarm** has one more route. Hand the operator one `!`-prefixed command that stages the named remediation paths and commits them on the current branch, with no push. A `!` command runs outside the PreToolUse hooks, so the commit needs no disarm and the hooks stay armed. Record it as an operator-run deviation, then re-run step 1. Offer this route only after confirming the current branch is `{workflow.epic_branch_prefix}<epic-id>`, and only for a remediation commit made before Execute.
|
|
64
|
+
- **Headless:** record a **RED** blocker naming the refused write and the operator action that clears it (an attended pass that approves or makes the write), and stop through step 4's blocked exit. The way back is that attended pass, not `/ucg-resolve`.
|
|
65
|
+
|
|
66
|
+
**Ordering.** `git_branch` → the `git_clean` clear (the branch has to exist before a remediation commit lands, per its bullet) and framework → ci (the CI scaffold halts without a framework, as its bullet states) are both load-bearing, as is the stale-hook disarm above, which must precede any remediation commit. While `git_unborn` stands, no remediation that writes to the tree runs at all, the branch and the `git_clean` clear included, as its bullet says. Every *other* remediation above is mutually independent — run them in any order, or concurrently; do not serialize them defensively.
|
|
67
|
+
|
|
68
|
+
**Remediation halt catch-all.** If a remediation sub-skill itself fails, is not installed, or blocks on interactive input, do not re-invoke it blind and do not answer its prompt — record a **RED** blocker naming the sub-skill and the exact input or decision it needed, and let the hard gate (step 4) stop the run. This mirrors Execute's sub-skill halt catch-all; a bare re-report of "budget still N" with no cause is not an account.
|
|
61
69
|
|
|
62
70
|
Log each remediation to `.decision-log.md` as you do it. After remediating, run the script from step 1 again and read the new `budget`.
|
|
63
71
|
|
|
@@ -138,12 +146,12 @@ Pass `impl_artifacts={workflow.implementation_artifacts}` to that call: `scripts
|
|
|
138
146
|
Do these in order; each must be asserted, not assumed:
|
|
139
147
|
|
|
140
148
|
- **Epic branch.** Assert you are on `{workflow.epic_branch_prefix}<epic-id>`. When step 1 reported `git_branch`, step 2's remediation already created it, and this is a **re-assertion, not a rebuild** — the same treatment the resume path gives it. Create it here when it does not yet exist — and note that `budget == 0` does **not** by itself put you on it: `git_branch` fires on a protected branch and nothing else, so a run started on some unrelated feature branch clears the gate having never been asked about its branch, and step 2 has no bullet that fires for it. That case lands here, so resolve it here rather than routing back: check out the base this Epic should branch from (a `{workflow.protected_branches}` branch, per execute.md's "off a protected branch" precondition — or the base the operator named in Stage 1) and cut `{workflow.epic_branch_prefix}<epic-id>` from there. Do **not** branch from wherever HEAD happens to sit; an Epic branch cut off an unrelated feature branch carries that branch's uncommitted work into the run's history and makes the branch-deletion rollback destructive. Rollback for this run is git (per-story commits) — `/rewind` checkpoints miss Bash-driven changes, so the branch is the real undo. If the tree is dirty (`git_clean: false`), resolve before branching — the last budget re-run was at the end of step 2, and step 3 has since written its scan sidecar and appended to `.decision-log.md`, so `budget == 0` does **not** imply a clean tree by the time you arrive here (`git_clean` counts untracked files).
|
|
141
|
-
- **Purge stale run markers.** Delete any `{workflow.implementation_artifacts}/.escalation-*`, `{workflow.implementation_artifacts}/.on-escalation-fired-*`, `{workflow.implementation_artifacts}/.budget-*`, `{workflow.implementation_artifacts}/.heartbeat-*` and `{workflow.implementation_artifacts}/.stall-*` an earlier run left behind, before the hooks that write them are armed — a stale escalation marker makes this run look like it already escalated, a stale fired-marker silently swallows this run's first escalation ping, which is the one an absent operator is waiting on, and a stale turn counter is already at or past the ceiling, so
|
|
142
|
-
- **Hooks.** Idempotently merge the **PreToolUse** guard (`scripts/hooks/guard_pretooluse.py`) and the **Stop** budget hook (`scripts/hooks/budget_stop.py`) into `{project-root}/.claude/settings.local.json` (gitignored, machine-local, honored after the workspace trust dialog). Re-merge every run — do not assume a prior run left them.
|
|
149
|
+
- **Purge stale run markers.** Delete any `{workflow.implementation_artifacts}/.escalation-*`, `{workflow.implementation_artifacts}/.on-escalation-fired-*`, `{workflow.implementation_artifacts}/.budget-*`, `{workflow.implementation_artifacts}/.heartbeat-*` and `{workflow.implementation_artifacts}/.stall-*` an earlier run left behind, before the hooks that write them are armed — a stale escalation marker makes this run look like it already escalated, a stale fired-marker silently swallows this run's first escalation ping, which is the one an absent operator is waiting on, and a stale turn counter is already at or past the ceiling, so this run's **first** Stop marks the story at the ceiling, and a resume's step-0 ceiling check escalates it, before it has done a single turn of work — and a stale heartbeat's gap since the PRIOR run would fire this run's stall rule on its first resume about an idle nobody had. Those five dot-prefixed families only. **On a resume, purge nothing.** A resume re-asserts the environment rather than rebuilding it, and the turn counter is the one piece of that environment a resume must inherit: zeroing `.budget-*` on re-entry would hand an in-flight story a fresh ceiling every time it stopped, so a run could evade the budget indefinitely by resuming. A counter the operator has deliberately cleared is a different thing, and `/ucg-resolve` clears exactly that one when it closes a `budget-overrun` escalation. In particular do **not** delete `escalation-*.json`: the typed sidecar is an operator-facing artifact like `run-status.json` and `run-result.json`, neither of which is purged at arming either, and it is named per story rather than per run, so arming cannot tell a deliberately-pending sidecar from a stale one. A decision the operator chose to leave pending lives in exactly that file, and a prior run's unresolved escalation surfacing at `/ucg-resolve` is correct: it genuinely is still pending. Sidecar staleness is handled at read time instead, by the run-scoped marker scan in `references/execute.md`. **The story pointer is the exception to both rules.** On a fresh run and a resume alike, delete `{workflow.implementation_artifacts}/.current-story`. No stage removes it, Finalize included, so on arrival here it names whichever story an earlier session drove last: once this run's Stop hook is armed, every Stop before this invocation's first step 0 (the launch briefing's included) is booked to that story's counter (on a fresh run, recreating the one this purge just removed), and the freshly armed guard would take that story's persisted tests-ran marker as current. A resume is not exempt, because a run that blocked here and was re-invoked re-enters at this stage as a resume, with an earlier run's pointer still on disk. Deleting it costs nothing a later step needs: step 0 writes it afresh before any implementation, the gate-owed route and the evidence-commit resume each re-set it themselves, and with no pointer the Stop hook counts nothing.
|
|
150
|
+
- **Hooks.** Idempotently merge the **PreToolUse** guard (`scripts/hooks/guard_pretooluse.py`) and the **Stop** budget hook (`scripts/hooks/budget_stop.py`) into `{project-root}/.claude/settings.local.json` (gitignored, machine-local, honored after the workspace trust dialog). Re-merge every run — do not assume a prior run left them. A merge that would change nothing makes no write: when the file's UCG entries already match what this run would write (both script paths, the all-tools matcher, and every injected value equal to this run's resolved scalars) and the allowlist entries are present, assert instead of writing. `--assert-armed` alone is not that comparison, because it confirms the injected variables are present, not that their values are this run's. A write that is refused follows "A refused settings write" in step 2.
|
|
143
151
|
|
|
144
152
|
**Arm the PreToolUse group with a matcher that covers EVERY tool, not just `Bash`.** Use `"matcher": "*"`, or omit the `matcher` key entirely the way the `Stop` group already does. Five of the guard's six invariants are Bash/git, so `Bash` is the natural choice and it is the choice both known installs made — but the sixth, the Cross-Session Recall latch, exists to gate an **MCP tool call**. Claude Code only invokes a PreToolUse group for tools its matcher selects, so under `Bash` the hook is never run for `mcp__plugin_claude-mem_*__*` at all: the guard would deny that call correctly if it were asked, and it is never asked. The invariant then enforces nothing while every log line says the hooks are armed, which is the worst of both — a control that reports itself active and is not.
|
|
145
153
|
|
|
146
|
-
Then **assert they are active**: re-read the resolved settings and confirm both script paths appear **and** that the PreToolUse group's matcher is the all-tools form. A presence-only assertion passes on a `Bash`-only arming, which is exactly the state this bullet exists to prevent. The same assertion is scriptable — `preflight_check.py --assert-armed` performs it (branch, both hooks under their own events, matcher form, injected env) in one read and fail-closes with named reasons. Pass `--epic-branch-prefix {workflow.epic_branch_prefix}` and one `--protected-branch <name>` per entry in `{workflow.protected_branches}`, exactly as step 1 does: omit either and it asserts the branch against its hardcoded defaults (`ultracode/epic-`, `main, master`), silently no-opping those overrides and failing a correctly armed run on a false RED. The resume path leans on it (`references/execute.md`), and it is equally valid here. It reads `.claude/settings.local.json`, the file this bullet's arming writes — an arming that lives in another settings layer fail-closes, which is the correct answer for a control this stage must be able to disarm and re-merge. Invariants that live only in memory are context, not enforcement, and memory does not block a `git commit`.
|
|
154
|
+
Then **assert they are active**: re-read the resolved settings and confirm both script paths appear **and** that the PreToolUse group's matcher is the all-tools form. A presence-only assertion passes on a `Bash`-only arming, which is exactly the state this bullet exists to prevent. The same assertion is scriptable — `preflight_check.py --assert-armed` performs it (branch, both hooks under their own events, matcher form, injected env, and the BMAD story skills) in one read and fail-closes with named reasons. Pass `--epic-branch-prefix {workflow.epic_branch_prefix}` and one `--protected-branch <name>` per entry in `{workflow.protected_branches}`, exactly as step 1 does: omit either and it asserts the branch against its hardcoded defaults (`ultracode/epic-`, `main, master`), silently no-opping those overrides and failing a correctly armed run on a false RED. The resume path leans on it (`references/execute.md`), and it is equally valid here. It reads `.claude/settings.local.json`, the file this bullet's arming writes — an arming that lives in another settings layer fail-closes, which is the correct answer for a control this stage must be able to disarm and re-merge. Invariants that live only in memory are context, not enforcement, and memory does not block a `git commit`.
|
|
147
155
|
- **Inject the hook env from the resolved scalars.** Both hooks read config from env first ("env wins so the conductor can inject per run") and fall back to hardcoded defaults (`main/master`, `25`, `ultracode/epic-`) otherwise — so a `customize.toml` override of any of these **silently no-ops at the enforcement layer** unless you pass it through. Set these on the hook commands (in the `settings.local.json` hook `command`, e.g. `KEY=value uv run …`) or in the process env the hooks inherit:
|
|
148
156
|
- `ULTRACODE_PROTECTED_BRANCHES={workflow.protected_branches}` (comma-separated)
|
|
149
157
|
- `ULTRACODE_IMPL_ARTIFACTS={workflow.implementation_artifacts}`
|
|
@@ -153,14 +161,14 @@ Do these in order; each must be asserted, not assumed:
|
|
|
153
161
|
- The same PreToolUse guard now also enforces the Cross-Session Recall latch from `{workflow.implementation_artifacts}/.mem-state.json` — the merged hook reads it automatically, fail-closed; no new env var to inject. **It enforces nothing unless the matcher above covers MCP tools**, because the latch's whole purpose is to gate a claude-mem MCP call and a group matched on `Bash` is never invoked for one. This is the invariant that makes the all-tools matcher load-bearing rather than tidy.
|
|
154
162
|
- **Un-skip proof (production only).** With `ULTRACODE_TEST_ARTIFACTS` injected, the guard reads the **staged post-image** of every acceptance-test file the story's `atdd-checklist-<story-id>.md` enumerates (`git show :<path>`) and denies the commit while any of them still contains `test.skip(`. It proves the marker is absent from the blob being committed, so it fires on a story's *first* commit too, where there is no prior blob to diff against. Caveat worth stating plainly: **`test.skip(` is a JS/Vitest-specific token** (the Playwright/Vitest form TEA's ATDD generates today, which is web/JS-only) — a pytest (`@pytest.mark.skip`) or Go (`t.Skip()`) stack marks skips differently and this check would not see them. Under `--light` there is no atdd-checklist, so the check stays inert.
|
|
155
163
|
- **The commit/push guard anchors on each segment's leading token (`fp-7ac2643`).** The guard splits the command into shell segments and flags one only when `git` is that segment's **leading** token — after leading `VAR=val` assignments, shell keywords and group openers (`if`/`then`/`else`/`fi`, `for`/`while`/`until`/`do`/`done`, `case`/`esac`, `!`, and `(`/`{`, whether spaced or glued to the command name), and known exec wrappers (`env`, `command`, `sudo`, `time`, `nice`, `nohup`, `timeout`, `setsid`, `stdbuf`, `ionice`, `doas`, plus the string payload of a `sh|bash|zsh|dash` invoked with any `-c`-bearing flag cluster, `-lc` and `-cx` included) are stripped — and the subcommand it would then run is exactly `commit` or `push`. The keyword strip is what keeps a commit inside a compound command (`if true; then git commit …; fi`, `for … do git commit … done`, `( git commit … )`) reachable by the gates: without it a keyword sits in the leading position, the segment classifies as carrying no git write, and the protected-branch, tests-ran, freshness and empty-index gates are all skipped at once. Segment splitting covers `&&`, `||`, `;`, `|`, a newline, **and a lone `&`** (`npm run build & git commit …` is two segments, not one); those separator sets are applied as a **union** rather than merged into one regex, because splitting on `&` or a newline is quote-blind and a lone set would tear `git -c alias.x='a&b' commit` into fragments that each escape detection. So a verb merely *mentioned* inside an `echo`, a log line, or a here-string in a verification command is no longer denied, while a real `FOO=bar git commit`, `sudo git commit` or `timeout 30 git commit` still is: on a `{workflow.protected_branches}` branch both verbs are denied, and on the epic branch, before the story's `.tests-ran-<story_id>` marker exists, a real `git commit` is denied (the marker gate is commit-only — a real `git push` is never marker-gated). Residual, stated rather than hidden: a wrapper **not** on that list (`xargs git commit`, say) leaves a non-`git` leading token and is allowed through, so the tests-ran marker and the remote's branch protection are the nets behind this one. Three shapes still take the older matches-anywhere path and deny on a mention: a segment whose quoting cannot be parsed, one that hides its command inside a `$(…)` substitution or backticks, and — the newest — a **listed** shell wrapper (`sh|bash|zsh|dash`) whose command-string payload cannot be located at all, meaning no `-c`-bearing flag cluster with an operand after it, or nesting deeper than the shell-recursion cap. That third lane exists because locating the payload by the bare token `-c` alone missed every combined form (`bash -lc`, `sh -lc`, `bash -cx`, `zsh -ic`), and a wrapper whose payload went unread classified as carrying no git write and skipped all four commit gates. It is fail-closed in the same direction as the other two, and it has the same cost: `bash <script> "…git commit…"` now denies on the mention, so a verification command's own arguments must not spell a write verb. **Do not read the anchoring as having eliminated the false-positive class — it narrowed it, and the remainder bites prose about commits in particular.** Markdown prose names identifiers in backticks, and an apostrophe (`don't`) is unbalanced quoting, so a run-log line describing a commit denial routinely hits both fallbacks; a line that *leads* with the verb is a real verb-leading segment and denies on its own. The rule that avoids all of it: **write prose with Write/Edit, never a Bash heredoc.** The PreToolUse guard **evaluates Bash command strings only**, so a decision-log append made with the file tools reaches no matcher of its own and no phrasing of the log can trip a gate. Now that the group is armed for every tool, the hook IS invoked for a `Write`; it simply has nothing to evaluate and returns no decision (verified across `Read`/`Write`/`Edit`/`Grep`/`Glob`/`Task`/`WebFetch` and an unrelated MCP call - every one passes through), so do not narrow the matcher back to `Bash` on the strength of this clause. Reserve Bash for commands you actually mean to run. (execute.md step 4 covers the narrower marker-written-in-the-same-compound-command trap.)
|
|
156
|
-
- **Allowlist.** Pre-populate the tool allowlist with `{workflow.allowlist_commands}` so the unattended run can run tests/lint/build/commit without a permission prompt that no one is there to approve.
|
|
164
|
+
- **Allowlist.** Pre-populate the tool allowlist with `{workflow.allowlist_commands}` so the unattended run can run tests/lint/build/commit without a permission prompt that no one is there to approve. The entries land in the same `settings.local.json`, so a refused write here follows the same rule.
|
|
157
165
|
|
|
158
166
|
### Launch briefing (interactive only)
|
|
159
167
|
|
|
160
168
|
This is the moment the human leaves the loop. Before the first unattended action — **interactive runs only; headless skips this subsection entirely** — surface a one-screen briefing so the operator decides "should I let go right now?" with eyes open:
|
|
161
169
|
|
|
162
170
|
- **What is about to run unattended:** the Epic (id + title), in-scope story count, profile (production / `--light`), and the Epic branch (`{workflow.epic_branch_prefix}<epic-id>`).
|
|
163
|
-
- **
|
|
171
|
+
- **Turn ceiling:** `{workflow.max_turns_per_story}` turns per story, as the Stop hook counts them (one per response). A resumed story already at or over the ceiling (unless only its gate is owed), or a re-loop that would pass it, escalates instead. It sizes stories; it does not cap time or cost.
|
|
164
172
|
- **The autonomy line:** state plainly — *"from here I will not ask you anything."*
|
|
165
173
|
- **Kill switch:** Ctrl-C, or delete the Epic branch — and note that `/rewind` will not help (its checkpoints miss the Bash-driven changes that make up the run, the same reason the branch is the real undo).
|
|
166
174
|
- **Where to watch:** the run's `.decision-log.md` (prose account) and `{workflow.implementation_artifacts}/run-status.json` (the machine-readable heartbeat Execute updates as the spine advances).
|
|
@@ -125,12 +125,17 @@ every prompt in every story of the Epic, none of which anybody sees.
|
|
|
125
125
|
|
|
126
126
|
FLAG VOCABULARY IS PINNED, NOT INVENTED. Verified against Claude Code 2.1.220:
|
|
127
127
|
`--permission-mode` accepts exactly acceptEdits|auto|bypassPermissions|manual|
|
|
128
|
-
dontAsk|plan, `--output-format` accepts text|json|stream-json
|
|
129
|
-
`--
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
128
|
+
dontAsk|plan, and `--output-format` accepts text|json|stream-json. `--max-turns`
|
|
129
|
+
exists in print mode but `--help` hides it, so a 2.1.220 `--help` read did not
|
|
130
|
+
list it. This driver deliberately does not pass it: it counts agentic turns
|
|
131
|
+
rather than story turns, and a session it cuts off writes no `run-result.json`. The per-story turn
|
|
132
|
+
ceiling is the skill's own `{workflow.max_turns_per_story}`: the `budget_stop.py`
|
|
133
|
+
Stop hook counts Stops, once per response, and the conductor reads that count
|
|
134
|
+
before a story's step 0 and before each re-loop (the `/goal` turn clause binds
|
|
135
|
+
only when an operator starts a `/goal`, which this driver's spawns never do).
|
|
136
|
+
A spawn is usually one long response per story, so that count barely moves
|
|
137
|
+
inside it and cannot bound a session wedged inside a single tool call - hence
|
|
138
|
+
`--session-timeout`, a wall clock the driver owns and the backstop for spawns.
|
|
134
139
|
|
|
135
140
|
THE INVOCATION STRING IS NOT UNIVERSAL, so it is a flag rather than a constant.
|
|
136
141
|
`/ultracode-goal` is the form an npx/`ucg install` install produces, where the
|
|
@@ -106,9 +106,32 @@ GENERIC_ARTIFACT_STEMS = frozenset("-".join(prefix) for prefix in gate_eval._ART
|
|
|
106
106
|
# Column headers are matched by NAME, never by position: the house trace table
|
|
107
107
|
# carries an extra split column that a future trace author may drop, and a
|
|
108
108
|
# positional parser would then read the wrong column as the planned test.
|
|
109
|
-
_AC_HEADERS = {"ac", "acs", "ac #", "id", "criterion", "criteria", "acceptance criterion"}
|
|
110
|
-
|
|
111
|
-
|
|
109
|
+
_AC_HEADERS = {"ac", "acs", "ac #", "id", "criterion", "criteria", "acceptance criterion", "criterion id"}
|
|
110
|
+
# Ordered by preference, because a TEA trace matrix can carry several matching
|
|
111
|
+
# columns (`Test ID` beside `Test (node)`, `Result` beside `Coverage`): the house
|
|
112
|
+
# names first, then TEA's node and file columns, and a bare test id last.
|
|
113
|
+
_TEST_HEADER_PREFERENCE = (
|
|
114
|
+
"verification",
|
|
115
|
+
"planned test",
|
|
116
|
+
"planned tests",
|
|
117
|
+
"named verification",
|
|
118
|
+
"test",
|
|
119
|
+
"tests",
|
|
120
|
+
"test (node)",
|
|
121
|
+
"test file:line",
|
|
122
|
+
"test file",
|
|
123
|
+
"test id",
|
|
124
|
+
)
|
|
125
|
+
_RESULT_HEADER_PREFERENCE = ("result", "status", "outcome", "coverage", "coverage status")
|
|
126
|
+
# Bare criterion headers that also key tables that are not acceptance criteria:
|
|
127
|
+
# TEA's gate-threshold tables read `| Criterion | Threshold | Actual | Status |`.
|
|
128
|
+
# Keyed only by one of these, a table counts only when it names a planned test.
|
|
129
|
+
_AMBIGUOUS_AC_HEADERS = frozenset({"id", "criterion", "criteria"})
|
|
130
|
+
# Keys that may make a trace report's tested table win over its first one. A
|
|
131
|
+
# bare `ID` keys case lists (`| ID | Test | Status |`) and an `ACs` column is a
|
|
132
|
+
# cross-reference in a file inventory (`| # | File | Tests | Level | ACs |`):
|
|
133
|
+
# either would render test ids or file numbers as criteria.
|
|
134
|
+
_OVERRIDE_AC_HEADERS = frozenset(_AC_HEADERS - {"id", "acs"})
|
|
112
135
|
|
|
113
136
|
_STORY_HEADING = re.compile(r"^#{2,4}\s+story\s+([0-9][\w.\-]*)", re.IGNORECASE | re.MULTILINE)
|
|
114
137
|
_JSON_FENCE = re.compile(r"```(?:json)?\s*\n(\{.*?\})\s*\n```", re.DOTALL)
|
|
@@ -188,21 +211,76 @@ def _tables(text: str) -> list[tuple[list[str], list[list[str]]]]:
|
|
|
188
211
|
return out
|
|
189
212
|
|
|
190
213
|
|
|
191
|
-
def
|
|
214
|
+
def _column(headers: list[str], preference: tuple[str, ...]) -> int | None:
|
|
215
|
+
"""The index of the most preferred header present, by name, never by position."""
|
|
216
|
+
for name in preference:
|
|
217
|
+
if name in headers:
|
|
218
|
+
return headers.index(name)
|
|
219
|
+
return None
|
|
220
|
+
|
|
221
|
+
|
|
222
|
+
def _result_column(headers: list[str]) -> int | None:
|
|
223
|
+
"""The result column: an exact result name, else a pass count, else coverage.
|
|
224
|
+
|
|
225
|
+
A TEA matrix may name its pass count only as `Pytest items (passed)` or
|
|
226
|
+
`Cases (passed)`; that is a result, while `Coverage` is not, so a header
|
|
227
|
+
carrying "passed" is preferred before the coverage names.
|
|
228
|
+
"""
|
|
229
|
+
exact = _column(headers, _RESULT_HEADER_PREFERENCE[:3])
|
|
230
|
+
if exact is not None:
|
|
231
|
+
return exact
|
|
232
|
+
passed = next((i for i, h in enumerate(headers) if "passed" in h), None)
|
|
233
|
+
if passed is not None:
|
|
234
|
+
return passed
|
|
235
|
+
return _column(headers, _RESULT_HEADER_PREFERENCE[3:])
|
|
236
|
+
|
|
237
|
+
|
|
238
|
+
def criterion_rows(text: str | None, *, prefer_tested: bool = False) -> list[tuple[str, str, str]]:
|
|
192
239
|
"""Extract (criterion, planned test, result) triples from a markdown table.
|
|
193
240
|
|
|
194
|
-
|
|
241
|
+
By default the first criterion-keyed table wins: an acceptance checklist's
|
|
242
|
+
first such table is its AC table, and a later one is an inventory or a
|
|
243
|
+
case list whose first column is not an acceptance criterion. A trace
|
|
244
|
+
report is different (`prefer_tested`): TEA puts an AC-to-design summary
|
|
245
|
+
with no test column ahead of its matrix, so there the first criterion-keyed
|
|
246
|
+
table that also names a planned test wins, and the first criterion-keyed
|
|
247
|
+
table only when none does. A table keyed by a bare `ID`, or only by an
|
|
248
|
+
`ACs` cross-reference column, never wins that way: a case list keyed
|
|
249
|
+
`| ID | Test | Status |` would render its test ids as criteria with a PASS
|
|
250
|
+
beside each, and a file inventory would render file numbers.
|
|
251
|
+
|
|
252
|
+
In either mode, a table keyed only by a bare `Criterion`, `Criteria` or
|
|
253
|
+
`ID` header counts only when it names a planned test, so TEA's
|
|
254
|
+
gate-threshold tables never render as acceptance criteria. Columns are
|
|
195
255
|
located by header name; any column the table does not carry renders `n/a`.
|
|
196
256
|
"""
|
|
197
257
|
if not text:
|
|
198
258
|
return []
|
|
259
|
+
first: list[tuple[str, str, str]] = []
|
|
260
|
+
skipped_ambiguous = False
|
|
199
261
|
for headers, rows in _tables(text):
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
262
|
+
ac_cols = [i for i, h in enumerate(headers) if h in _AC_HEADERS]
|
|
263
|
+
if not ac_cols:
|
|
264
|
+
continue
|
|
265
|
+
# The criterion text comes from the first criterion-like column, but the
|
|
266
|
+
# table's KEYS are all of them: TEA 1.27.2's own checklist AC table reads
|
|
267
|
+
# `| ID | ID source | Acceptance criterion |`, so judging it by `ID`
|
|
268
|
+
# alone skipped the one table that names the acceptance criteria.
|
|
269
|
+
ac_at = ac_cols[0]
|
|
270
|
+
keys = {headers[i] for i in ac_cols}
|
|
271
|
+
test_at = _column(headers, _TEST_HEADER_PREFERENCE)
|
|
272
|
+
result_at = _result_column(headers)
|
|
273
|
+
# Coverage is not a pass: where it is the only result-like column, its
|
|
274
|
+
# cells are labelled so `FULL` cannot read as a passing result.
|
|
275
|
+
coverage_only = result_at is not None and headers[result_at] in _RESULT_HEADER_PREFERENCE[3:]
|
|
276
|
+
if test_at is None and keys <= _AMBIGUOUS_AC_HEADERS:
|
|
277
|
+
skipped_ambiguous = True
|
|
278
|
+
continue
|
|
279
|
+
if skipped_ambiguous and keys <= {"id"}:
|
|
280
|
+
# A criterion table was already set aside for naming no test, so a
|
|
281
|
+
# later table keyed only by `ID` is a case list, never the criteria:
|
|
282
|
+
# taking it would render test ids with a PASS beside each.
|
|
203
283
|
continue
|
|
204
|
-
test_at = next((i for i, h in enumerate(headers) if h in _TEST_HEADERS), None)
|
|
205
|
-
result_at = next((i for i, h in enumerate(headers) if h in _RESULT_HEADERS), None)
|
|
206
284
|
|
|
207
285
|
def pick(row: list[str], at: int | None) -> str:
|
|
208
286
|
if at is None or at >= len(row):
|
|
@@ -216,10 +294,19 @@ def criterion_rows(text: str | None) -> list[tuple[str, str, str]]:
|
|
|
216
294
|
criterion = row[ac_at].strip()
|
|
217
295
|
if not criterion:
|
|
218
296
|
continue
|
|
219
|
-
|
|
220
|
-
|
|
297
|
+
result = pick(row, result_at)
|
|
298
|
+
if coverage_only and result != NA:
|
|
299
|
+
result = f"coverage: {result}"
|
|
300
|
+
extracted.append((criterion, pick(row, test_at), result))
|
|
301
|
+
if not extracted:
|
|
302
|
+
continue
|
|
303
|
+
if not prefer_tested:
|
|
304
|
+
return extracted
|
|
305
|
+
if test_at is not None and keys & _OVERRIDE_AC_HEADERS:
|
|
221
306
|
return extracted
|
|
222
|
-
|
|
307
|
+
if not first:
|
|
308
|
+
first = extracted
|
|
309
|
+
return first
|
|
223
310
|
|
|
224
311
|
|
|
225
312
|
# --------------------------------------------------------------------------
|
|
@@ -566,9 +653,10 @@ def baseline_sha(impl_artifacts: Path | None, story: str) -> str | None:
|
|
|
566
653
|
def commit_sha(impl_artifacts: Path | None, story: str) -> str | None:
|
|
567
654
|
"""The story's recorded END commit, or None when the run wrote no such marker.
|
|
568
655
|
|
|
569
|
-
`references/execute.md` step 4 writes `.commit-<story>` once the commit lands
|
|
570
|
-
|
|
571
|
-
|
|
656
|
+
`references/execute.md` step 4 writes `.commit-<story>` once the commit lands,
|
|
657
|
+
step 5 refreshes it after any amend or remediation re-commit, and the gate's
|
|
658
|
+
advance route refreshes it after its evidence commit, so it names the
|
|
659
|
+
story's LAST commit. Reading it is what lets the trail stop inferring a
|
|
572
660
|
range end from the next story's baseline.
|
|
573
661
|
|
|
574
662
|
The inference it replaces could not be made correct from baselines alone. Two
|
|
@@ -591,8 +679,9 @@ def _git_log(repo: Path, start: str, end: str) -> list[str] | None:
|
|
|
591
679
|
capture_output=True,
|
|
592
680
|
text=True,
|
|
593
681
|
check=False,
|
|
682
|
+
timeout=30,
|
|
594
683
|
)
|
|
595
|
-
except (OSError, ValueError):
|
|
684
|
+
except (OSError, ValueError, subprocess.SubprocessError):
|
|
596
685
|
return None
|
|
597
686
|
if proc.returncode != 0:
|
|
598
687
|
return None
|
|
@@ -650,7 +739,7 @@ def story_section(
|
|
|
650
739
|
rows = criterion_rows(checklist_text)
|
|
651
740
|
criteria_source = checklist.name if (rows and checklist is not None) else None
|
|
652
741
|
if not rows:
|
|
653
|
-
rows = criterion_rows(trace_text)
|
|
742
|
+
rows = criterion_rows(trace_text, prefer_tested=True)
|
|
654
743
|
criteria_source = trace.name if (rows and trace is not None) else criteria_source
|
|
655
744
|
|
|
656
745
|
gate_status, gate_source = gate_status_for(trace_output, story)
|
|
@@ -45,10 +45,23 @@ CANONICAL_KEYS = ("status", "skill", "decision_log", "report", "deferred_work")
|
|
|
45
45
|
RESULT_FILENAME = "run-result.json"
|
|
46
46
|
|
|
47
47
|
|
|
48
|
+
def _blocker_fields(blocker: dict) -> tuple[str, str]:
|
|
49
|
+
"""(source, decision) for a blocker of either shape.
|
|
50
|
+
|
|
51
|
+
Formalize and semantic-scan reds carry {source, decision_needed};
|
|
52
|
+
preflight_check.py's mechanical blockers carry {id, detail}. Reading only the
|
|
53
|
+
first shape rendered an empty `reason` whenever a mechanical blocker led the
|
|
54
|
+
list (a missing BMAD story skill, an unborn HEAD), so a headless operator got
|
|
55
|
+
a blocked envelope with no cause in it.
|
|
56
|
+
"""
|
|
57
|
+
source = str(blocker.get("source") or blocker.get("id") or "").strip()
|
|
58
|
+
decision = str(blocker.get("decision_needed") or blocker.get("detail") or "").strip()
|
|
59
|
+
return source, decision
|
|
60
|
+
|
|
61
|
+
|
|
48
62
|
def _one_line(blocker: dict) -> str:
|
|
49
|
-
"""Render a blocker
|
|
50
|
-
source =
|
|
51
|
-
decision = str(blocker.get("decision_needed", "")).strip()
|
|
63
|
+
"""Render a blocker as ONE physical line (no newline)."""
|
|
64
|
+
source, decision = _blocker_fields(blocker)
|
|
52
65
|
text = f"{source} - {decision}" if source and decision else (source or decision)
|
|
53
66
|
return re.sub(r"\s+", " ", text.replace("\n", " ")).strip()
|
|
54
67
|
|
|
@@ -95,7 +108,8 @@ def _append_blockers_to_log(decision_log: str, blockers: list[dict]) -> None:
|
|
|
95
108
|
"""Write the full formalize/semantic blockers (source:line + decision_needed) to the log."""
|
|
96
109
|
lines = ["", "## Headless blocked envelope - full blocker list", ""]
|
|
97
110
|
for b in blockers:
|
|
98
|
-
|
|
111
|
+
source, decision = _blocker_fields(b)
|
|
112
|
+
lines.append(f"- {source} :: {decision}")
|
|
99
113
|
_append_to_log(decision_log, lines)
|
|
100
114
|
|
|
101
115
|
|
|
@@ -167,8 +181,8 @@ def build_headless_envelope(
|
|
|
167
181
|
:data:`build_blocked_envelope` alias below, which is what new callers should
|
|
168
182
|
read for.
|
|
169
183
|
|
|
170
|
-
``source`` is either an ordered list of blocker dicts (each {source, decision_needed}
|
|
171
|
-
or a formalize verdict dict (adapted via :func:`fr5_blockers`). Returns exactly the five
|
|
184
|
+
``source`` is either an ordered list of blocker dicts (each {source, decision_needed},
|
|
185
|
+
or a preflight_check.py mechanical blocker {id, detail}) or a formalize verdict dict (adapted via :func:`fr5_blockers`). Returns exactly the five
|
|
172
186
|
canonical keys plus ``reason`` (the one-line rendering of ``blockers[0]``).
|
|
173
187
|
|
|
174
188
|
``report`` / ``deferred_work`` are optional because a blocked exit is not
|