bmad-module-ultracode-goal 3.0.0 → 3.2.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 +1 -1
- package/README.md +1 -1
- package/docs/architecture.md +2 -1
- package/docs/cross-session-recall.md +1 -1
- package/docs/gate-model.md +6 -2
- package/docs/how-it-works.md +6 -6
- package/docs/index.md +1 -1
- package/docs/operating-tips.md +3 -2
- package/docs/troubleshooting.md +3 -3
- package/docs/why-ultracode-goal.md +1 -1
- package/package.json +1 -1
- package/skills/ucg-resolve/SKILL.md +40 -1
- package/skills/ucg-status/SKILL.md +3 -2
- package/skills/ultracode-goal/SKILL.md +2 -2
- package/skills/ultracode-goal/references/define-done.md +5 -1
- package/skills/ultracode-goal/references/execute.md +29 -8
- package/skills/ultracode-goal/references/finalize.md +7 -5
- package/skills/ultracode-goal/references/gate.md +83 -17
- package/skills/ultracode-goal/references/ingest-and-scope.md +3 -1
- package/skills/ultracode-goal/references/preflight.md +5 -3
- package/skills/ultracode-goal/scripts/drive_epic.py +59 -4
- package/skills/ultracode-goal/scripts/formalize_check.py +94 -10
- package/skills/ultracode-goal/scripts/gate_trail.py +5 -3
- package/skills/ultracode-goal/scripts/hooks/budget_stop.py +9 -0
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +942 -33
- package/skills/ultracode-goal/scripts/mem_observation.py +13 -6
- package/skills/ultracode-goal/scripts/mutate_check.py +158 -32
- package/skills/ultracode-goal/scripts/operator_owed.py +338 -0
- package/skills/ultracode-goal/scripts/preflight_check.py +208 -6
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"name": "bmad-module-ultracode-goal",
|
|
20
20
|
"source": "./",
|
|
21
21
|
"description": "Supercharges BMAD with Claude Code's Auto Mode, Auto Memory, and hooks: autonomous Epic execution to a machine-checked, TEA-gated Definition-of-Done. Execute Epics. Accumulate Knowledge. Deliver Outcomes.",
|
|
22
|
-
"version": "3.
|
|
22
|
+
"version": "3.2.0",
|
|
23
23
|
"author": {
|
|
24
24
|
"name": "Armel"
|
|
25
25
|
},
|
package/README.md
CHANGED
|
@@ -102,7 +102,7 @@ A skeptical reader is probably already running one of these. Here is the honest
|
|
|
102
102
|
| Completion authority | `gate_eval.py` reads TEA's `gate-decision.json` | you, story by story | the model's self-assessment | CI, but only after the agent stops |
|
|
103
103
|
| Preflight autonomy gate | hard-gate to remediated green (intervention budget 0)| ad hoc, per story | none | none: CI runs post-hoc |
|
|
104
104
|
| Invariants enforcement | `PreToolUse` hooks in `settings.local.json` | your attention | prompt text (context, not a gate)| CI checks, after the fact |
|
|
105
|
-
| Rollback | git: epic branch, code +
|
|
105
|
+
| Rollback | git: epic branch, code + gate commits per story | manual | `/rewind` (misses Bash changes) | revert after merge |
|
|
106
106
|
| Knowledge capture | Auto Memory + CLAUDE.md split at Finalize | none structured | none structured | none |
|
|
107
107
|
|
|
108
108
|
The alternatives aren't bad; they solve different problems. **UCG solves exactly one: advancing an epic only when a deterministic script confirms the gate passed, and giving you the verdict JSON to check it yourself.**
|
package/docs/architecture.md
CHANGED
|
@@ -34,7 +34,7 @@ Both hooks read their config from env first (so the conductor injects per-run va
|
|
|
34
34
|
|
|
35
35
|
### 3. Budget enforcement
|
|
36
36
|
|
|
37
|
-
Three layers can bound a runaway story, in order of authority: the **in-condition** "…or stop after N turns" clause inside a `/goal` condition (only an operator's own `/goal` condition, which then bounds the session; the conductor cannot start one itself), the **gate re-loop budget** (the conductor reads the hook's turn count before each re-loop, so a `reloop` that would exceed `max_turns_per_story` becomes `escalate`, though that count cannot see re-loops inside one response), and the **Stop hook** as the recorder described above. In a single attended or `-H` session with no operator `/goal`, nothing bounds re-loops spent inside one response; for `drive_epic.py` spawns, the `--session-timeout` wall clock is the backstop. Rollback is git, not `/rewind` (an Epic branch off a protected branch, one implementation commit per green story plus its gate's evidence
|
|
37
|
+
Three layers can bound a runaway story, in order of authority: the **in-condition** "…or stop after N turns" clause inside a `/goal` condition (only an operator's own `/goal` condition, which then bounds the session; the conductor cannot start one itself), the **gate re-loop budget** (the conductor reads the hook's turn count before each re-loop, so a `reloop` that would exceed `max_turns_per_story` becomes `escalate`, though that count cannot see re-loops inside one response), and the **Stop hook** as the recorder described above. In a single attended or `-H` session with no operator `/goal`, nothing bounds re-loops spent inside one response; for `drive_epic.py` spawns, the `--session-timeout` wall clock is the backstop. Rollback is git, not `/rewind` (an Epic branch off a protected branch, one implementation commit per green story plus its gate's commits: a test backfill when automate makes one, then the evidence) because `/rewind` checkpoints miss the Bash-driven changes that make up the run.
|
|
38
38
|
|
|
39
39
|
## File layout
|
|
40
40
|
|
|
@@ -56,6 +56,7 @@ skills/ultracode-goal/
|
|
|
56
56
|
├── scripts/ # Deterministic truth (run via `uv`)
|
|
57
57
|
│ ├── preflight_check.py # mechanical preflight facts + blocker budget
|
|
58
58
|
│ ├── gate_eval.py # gate status -> verdict (the completion authority)
|
|
59
|
+
│ ├── operator_owed.py # is a gate FAIL owed only operator-evidence ACs' records? (fail-closed)
|
|
59
60
|
│ ├── mutate_check.py # mutation harness: attributable-red proof for the story's guards
|
|
60
61
|
│ ├── gate_trail.py # per-story evidence trail (gate-trail.md) at finalize
|
|
61
62
|
│ ├── formalize_check.py # readiness kernel behind the /ucg-formalize gate
|
|
@@ -91,7 +91,7 @@ flowchart TD
|
|
|
91
91
|
|
|
92
92
|
Each recall call is attempted once and never retried. A run whose recall turned off along the way says so in its report, with the tokens under [troubleshooting](#troubleshooting).
|
|
93
93
|
|
|
94
|
-
**What a record holds.** The Epic, the run id, the repo fingerprint, the gate status and verdict, the root-cause signatures (each with a class from a fixed taxonomy and an artifact path), the count of deferred items, the advisories the run consumed with whether they recurred, the time, and the project's folder name for display. Free text is redacted before it is written. A run
|
|
94
|
+
**What a record holds.** The Epic, the run id, the repo fingerprint, the gate status and verdict, the root-cause signatures (each with a class from a fixed taxonomy and an artifact path), the count of deferred items, the advisories the run consumed with whether they recurred, the time, and the project's folder name for display. Free text is redacted before it is written. A run that blocked with no gate status (it escalated or handed off before a gate ran, or its gate could not be read) writes a record with gate status `NOT_EVALUATED` and verdict `blocked`, so the next run sees that it blocked; a `WAIVED` outcome is written too. A resume that stops because the story's escalation is still open names no root cause in its record: the run that raised the escalation recorded it, so stopping again on one unanswered decision does not count as recurring. `NOT_EVALUATED` with any other verdict writes no record.
|
|
95
95
|
|
|
96
96
|
**When the store cannot take a record.** The record waits in `mem-outbox.<run_id>.jsonl` in the implementation artifacts folder, and the run logs `WARN mem-write-deferred`. The next run that reaches Finalize with a green latch drains it, keeping its original time. A deferred record older than 14 days is dropped, and one whose drain fails three times moves to `mem-outbox.dead.jsonl`, with `WARN mem-write-dead-lettered`. No drain replays that file.
|
|
97
97
|
|
package/docs/gate-model.md
CHANGED
|
@@ -52,6 +52,10 @@ The gate status maps to a verdict (`GATE_VERDICT` in the script):
|
|
|
52
52
|
|
|
53
53
|
Any unrecognized status escalates (the script's `GATE_VERDICT.get(gate_status, "escalate")` default), with a `reasons` entry noting it.
|
|
54
54
|
|
|
55
|
+
One `FAIL` takes a different route. When the only criteria TEA's coverage matrix holds open are acceptance criteria tagged `**Gate-ability:** operator-evidence`, whose proof is a live result a person records, no re-loop can change the gate. A plain `**Gate-ability:** operator` tag is not read this way: it marks work the dev agent builds, so an open criterion carrying it keeps the re-loop. The skill checks that with `scripts/operator_owed.py`, which fails closed, and escalates with kind `operator-evidence-owed` instead of re-looping. `gate_eval.py` still prints `reloop`: the route changes, not the verdict.
|
|
56
|
+
|
|
57
|
+
Once `/ucg-resolve` closes that escalation, with the person's records on disk at the commit the gate measured, the resume re-gates that same commit instead of re-driving the story. An `operator-evidence` criterion that already has a counted `pass` record, and that TEA still holds below `FULL`, is still owed: the record covers only part of the criterion, so the escalation names the records already counted and asks the operator to record the rest or to narrow or move the criterion in writing. Re-gating the records already counted changes nothing, so `/ucg-resolve` closes it only on a new `pass` record or on that written change.
|
|
58
|
+
|
|
55
59
|
## The production AND
|
|
56
60
|
|
|
57
61
|
Under `--profile production`, an otherwise-`advance` verdict is additionally ANDed against two TEA signals, and any failure downgrades it to `reloop`. The downgrade floor is `reloop`. A `defer`/`reloop`/`escalate` is unchanged; only an `advance` moves:
|
|
@@ -99,7 +103,7 @@ The verdict JSON carries the recognised value as `sweep_scope` (or `null`), so a
|
|
|
99
103
|
|
|
100
104
|
## The delta cycle profile
|
|
101
105
|
|
|
102
|
-
A mid-loop re-gate may declare `--cycle-profile delta`: only the assessor dimension(s) whose findings produced the previous reloop re-run in full, while the other assessors re-check their prior artifact against the diff since the commit they assessed. The script caps a delta gate's verdict at `reloop` (defer too, for the sweep-cap reason): a delta gate can say "not yet, and here is why", never move the story. Advancing requires the full instrument, every assessor over a `scope=full` sweep, so the oracle's finality is untouched and a wrong guess costs one extra full gate rather than an unearned advance. The fallback is mechanical: any prior finding without a clean dimension attribution means the full gate runs. `--epic-level` refuses the flag (invocation error, exit 2); omitting it is the full behaviour, and the `cycle_profile` JSON key appears exactly when the flag was supplied.
|
|
106
|
+
A mid-loop re-gate may declare `--cycle-profile delta`: only the assessor dimension(s) whose findings produced the previous reloop re-run in full, while the other assessors re-check their prior artifact against the diff since the commit they assessed. The script caps a delta gate's verdict at `reloop` (defer too, for the sweep-cap reason): a delta gate can say "not yet, and here is why", never move the story. Advancing requires the full instrument, every assessor over a `scope=full` sweep, so the oracle's finality is untouched and a wrong guess costs one extra full gate rather than an unearned advance. The fallback is mechanical: any prior finding without a clean dimension attribution means the full gate runs. `bmad-testarch-automate` sits outside this choice: after a story's first gate cycle, full or delta, it searches only the diff since the previous gate and re-runs the mutation rows behind the gaps that gate backfilled and behind every gap still open, and the full instrument runs it at that scope too. It backfills every gap it finds on a P0 criterion, in any cycle, so trace counts the new test and the script decides; only a gap on another criterion is reported instead, when it lies outside that scope or while operator live results sit at the commit under assessment. A reported gap stays open until a pass at a later commit finds its mutants killed, and it never changes the route a verdict takes. Automate confirms each test it backfills in the same pass, with the test copied into the worktree, and a test that leaves its mutant alive (perhaps an equivalent mutant, which no test can kill) is logged as an `unkilled` gap that no later pass writes another test for while that code stands. `--epic-level` refuses the flag (invocation error, exit 2); omitting it is the full behaviour, and the `cycle_profile` JSON key appears exactly when the flag was supplied.
|
|
103
107
|
|
|
104
108
|
## The thresholds
|
|
105
109
|
|
|
@@ -109,7 +113,7 @@ The P0/P1/overall percentage thresholds (**P0 = 100%, P1 >= 90%, overall >= 80%*
|
|
|
109
113
|
|
|
110
114
|
The production AND is deliberately fail-closed (see the `apply_production_and` docstring in the script): a missing `nfr-assessment.md` or `test-review.md`, or a field the scanners cannot parse, is treated as a **failing** signal, not a neutral or absent one. So if TEA's prose format drifts and the Overall Status or Quality Score cannot be read, an otherwise-`advance` degrades to a conservative `reloop` rather than a silent false-advance. The direction is intentional: the module would rather re-loop a green story than advance a story whose evidence it could not actually read. Likewise, a missing or corrupt gate artifact yields `NOT_EVALUATED` → `escalate`: the gate is never assumed green.
|
|
111
115
|
|
|
112
|
-
This is reinforced by the routing invariant in Stage 5: **a P0/critical FAIL never defers.** Only non-gate-blocking work (CONCERNS, non-critical findings, parked decisions) reaches the deferred-work ledger; a FAIL or a P0/critical finding re-loops within budget or escalates.
|
|
116
|
+
This is reinforced by the routing invariant in Stage 5: **a P0/critical FAIL never defers.** Only non-gate-blocking work (CONCERNS, non-critical findings, parked decisions, and the coverage gaps automate logged as `gate-gap:` lines that are still open) reaches the deferred-work ledger; a FAIL or a P0/critical finding re-loops within budget or escalates. A `gate-gap:` row is neither, whatever its criterion's priority: it reaches the ledger at `med` severity and never re-loops or escalates the story.
|
|
113
117
|
|
|
114
118
|
## Output shape
|
|
115
119
|
|
package/docs/how-it-works.md
CHANGED
|
@@ -44,7 +44,7 @@ flowchart TD
|
|
|
44
44
|
S5 -->|"advance or defer"| S6
|
|
45
45
|
S5 -->|"reloop: gate FAIL within budget"| Correct
|
|
46
46
|
Correct --> S4
|
|
47
|
-
S5 -->|"escalate: NOT_EVALUATED or
|
|
47
|
+
S5 -->|"escalate: NOT_EVALUATED, budget exhausted, or operator evidence owed"| S6
|
|
48
48
|
|
|
49
49
|
classDef accent fill:#6366F1,stroke:#4F46E5,color:#fff
|
|
50
50
|
classDef verdict fill:#4F46E5,stroke:#3730A3,color:#fff
|
|
@@ -54,7 +54,7 @@ flowchart TD
|
|
|
54
54
|
class NotBmad,Blocked stop
|
|
55
55
|
```
|
|
56
56
|
|
|
57
|
-
A `defer` verdict appends non-blocking items to the ledger and advances anyway; an `escalate` ends the run as `blocked` at Stage 6 rather than `complete`. The reloop edge re-runs the story only while turn budget remains (`max_turns_per_story`); once exhausted, a FAIL becomes an escalate.
|
|
57
|
+
A `defer` verdict appends non-blocking items to the ledger and advances anyway; an `escalate` ends the run as `blocked` at Stage 6 rather than `complete`. The reloop edge re-runs the story only while turn budget remains (`max_turns_per_story`); once exhausted, a FAIL becomes an escalate. A FAIL that only evidence a person records can change (an acceptance criterion tagged `**Gate-ability:** operator-evidence` with no recorded live result, or one that covers only part of it) escalates at once with kind `operator-evidence-owed`, since no re-loop can produce that evidence.
|
|
58
58
|
|
|
59
59
|
### Stage 1: Ingest & Scope
|
|
60
60
|
|
|
@@ -78,11 +78,11 @@ Turn the Epic's acceptance criteria into **executable, red-phase acceptance test
|
|
|
78
78
|
|
|
79
79
|
### Stage 4: Execute
|
|
80
80
|
|
|
81
|
-
Drive each in-scope story from its red-phase tests to a green, committed state. Execution is the **sequential `/goal` spine**; per story, in sprint order: set the current story (so the PreToolUse hook can find its marker) → `ucg-dev-story` implements the feature and un-skips the story's ATDD tests → run tests/lint/build and **print the raw output** as evidence → (production) `bmad-testarch-test-review` then `bmad-code-review` → check the commit message against the staged diff (`claim_check.py` lists each path it names that the commit does not touch) and soften any claim the diff's own new lines make that no evidence shows → commit at green (one implementation commit per green story; the gate's
|
|
81
|
+
Drive each in-scope story from its red-phase tests to a green, committed state. Execution is the **sequential `/goal` spine**; per story, in sprint order: set the current story (so the PreToolUse hook can find its marker) → `ucg-dev-story` implements the feature and un-skips the story's ATDD tests → run tests/lint/build and **print the raw output** as evidence → (production) `bmad-testarch-test-review` then `bmad-code-review` → check the commit message against the staged diff (`claim_check.py` lists each path it names that the commit does not touch) and soften any claim the diff's own new lines make that no evidence shows → commit at green (one implementation commit per green story; the gate's commits follow it: a test backfill when automate makes one, then the evidence) → **re-run the suite at this cycle's scope on the committed HEAD (a story only advances off a full-scope sweep)** and print it, because a story's new files are untracked until the commit, so a tracked-files conformance gate can only red once they land; a red here means the story is not done and must be remediated and re-committed before it advances. The conductor writes a per-story `/goal`-style condition that encodes the Definition-of-Done and carries the literal "…or stop after N turns" escape clause, and records it in the decision log. A live `/goal` runs only when you start one, on your own condition, because the conductor cannot start `/goal` itself. The Stop hook records a turn count, once per response, which the conductor reads before each story and each re-loop. The printed evidence keeps the run judgeable mid-flight, but **passing the `/goal` condition is not completion**; the authoritative verdict is Stage 5. As the spine advances it overwrites a `run-status.json` heartbeat for pollers. See [`references/execute.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/execute.md).
|
|
82
82
|
|
|
83
83
|
### Stage 5: Gate
|
|
84
84
|
|
|
85
|
-
Decide whether a story (or, after the last story, the Epic) advances, by a deterministic artifact read. In production, the skill first backfills the evidence
|
|
85
|
+
Decide whether a story (or, after the last story, the Epic) advances, by a deterministic artifact read. In production, the skill first backfills the evidence: `bmad-testarch-automate` runs first and alone, a test it backfills is committed before anything else measures the story, and only then do `bmad-testarch-trace` (which writes the gate decision), `bmad-testarch-nfr` and, when the story lacks a current review, `bmad-testarch-test-review` run. Assessors that run or time anything measure a worktree of the commit under assessment, never the shared working tree. Then it runs `gate_eval.py`; a mid-loop re-gate may declare a delta profile (only the previously failed dimension re-runs in full) whose verdict is capped at reloop, so only the full instrument ever advances a story. The script reads TEA's `gate-decision.json` and returns a verdict the skill executes: `advance` (move to the next story), `defer` (append non-blocking items to the ledger and advance anyway), `reloop` (generalize each finding to its defect class against the Epic's class ledger, then run `bmad-correct-course` and re-run the story within the remaining budget), or `escalate` (stop). The invariant: **a P0/critical FAIL never defers**; it re-loops within budget or escalates. See the [gate model](./gate-model.md) and [`references/gate.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/gate.md).
|
|
86
86
|
|
|
87
87
|
This is how the verdict is read deterministically; the conductor never grades the work itself, it runs the script and routes on what comes back:
|
|
88
88
|
|
|
@@ -117,13 +117,13 @@ The **production** profile wires the full TEA chain as gates: test-design, atdd,
|
|
|
117
117
|
|
|
118
118
|
## The decision log
|
|
119
119
|
|
|
120
|
-
The run's `.decision-log.md`, held in the skill's run folder, is canonical memory. Compaction can drop everything else; the log recovers full state. It records scope, the preflight verdict, every gate outcome, every deferral, and (in headless) every assumption. **Resume** reads it: on a resumed run, Execute re-enters at the first story whose last logged gate verdict is not `advance`; advanced stories are not re-run, and the Epic branch, hooks, and allowlist are re-asserted (not rebuilt) before continuing.
|
|
120
|
+
The run's `.decision-log.md`, held in the skill's run folder, is canonical memory. Compaction can drop everything else; the log recovers full state. It records scope, the preflight verdict, every gate outcome, every deferral, and (in headless) every assumption. **Resume** reads it: on a resumed run, Execute re-enters at the first story whose last logged gate verdict is not `advance`; advanced stories are not re-run, and the Epic branch, hooks, and allowlist are re-asserted (not rebuilt) before continuing. A re-entry story that still carries an open escalation is not re-entered: the run stops and points at `/ucg-resolve`.
|
|
121
121
|
|
|
122
122
|
## The run report, the gate trail, and the deferred-work ledger
|
|
123
123
|
|
|
124
124
|
Finalize leaves two durable outputs beside the decision log, in the run folder. The **run report** (`run-report.md`) is the human takeaway. The **gate trail** (`gate-trail.md`, written by `gate_trail.py`) is the evidence trail: one section per story naming the checklist, trace report, gate decision, and baseline behind that story's verdict, so the gate can be audited without the transcript. Sources it cannot read render as `n/a` rather than failing the trail, but the trail refuses to render at all when no story is named, because an evidence trail that traces nothing is the exact failure it exists to prevent.
|
|
125
125
|
|
|
126
|
-
The third output lives elsewhere on purpose. The **deferred-work ledger** (at `deferred_work_path`, outside the run folder because it spans runs) holds one heading per Epic with a row per parked item: only non-gate-blocking work lands here (CONCERNS, non-critical findings, parked decisions); a P0/critical FAIL is never deferred. Finalize surfaces this run's Epic heading so nothing parked is invisible at handoff.
|
|
126
|
+
The third output lives elsewhere on purpose. The **deferred-work ledger** (at `deferred_work_path`, outside the run folder because it spans runs) holds one heading per Epic with a row per parked item: only non-gate-blocking work lands here (CONCERNS, non-critical findings, parked decisions, and the coverage gaps the gate's automate pass logged that are still open, at `med` severity whatever their priority); a P0/critical FAIL is never deferred. Finalize surfaces this run's Epic heading so nothing parked is invisible at handoff.
|
|
127
127
|
|
|
128
128
|
## Headless contract
|
|
129
129
|
|
package/docs/index.md
CHANGED
|
@@ -41,7 +41,7 @@ If the gate file is missing or unparseable, the contract counts it as a *failing
|
|
|
41
41
|
|
|
42
42
|
## What you get
|
|
43
43
|
|
|
44
|
-
Completion stops being a feeling in the transcript and becomes a fact on disk. Every green story lands as an implementation commit, plus its gate's
|
|
44
|
+
Completion stops being a feeling in the transcript and becomes a fact on disk. Every green story lands as an implementation commit, plus its gate's commits (a test backfill when the gate adds coverage, then the evidence), on an isolated epic branch: rollback you can actually trust, not a checkpoint that misses Bash changes. The run ends with a delivered, gate-passed epic, a run report, and a deferred-work ledger of anything safely parked for later.
|
|
45
45
|
|
|
46
46
|
## Read the rest
|
|
47
47
|
|
package/docs/operating-tips.md
CHANGED
|
@@ -42,13 +42,14 @@ Do not write a latch from the parent between drives. The old workaround, `latch
|
|
|
42
42
|
|
|
43
43
|
## Reading the driver's stop reasons
|
|
44
44
|
|
|
45
|
-
The driver names
|
|
45
|
+
The driver names fourteen stop reasons (`drive_epic.py`'s `STOP_*` constants). Three mean the invocation finished its work and exit 0: `all-done`, `limit-reached`, `dry-run`. Every other stop is a fail-closed halt and exits 1, so a wrapper can branch on the exit code before it parses anything.
|
|
46
46
|
|
|
47
|
-
These
|
|
47
|
+
These seven are the ones you will actually meet in a working week, and getting them confused wastes a spawn or, worse, propagates an ungated story. The rest name their own cause and need no table: `dry-run`, the pre-spawn refusals (`no-sprint-status`, `epic-not-found`, `sprint-status-elsewhere`, `stale-result`), a row carrying a status the driver does not recognize (`unknown-status`), and a drive that was killed (`signalled`).
|
|
48
48
|
|
|
49
49
|
| Stop reason | What happened | What to do |
|
|
50
50
|
|---|---|---|
|
|
51
51
|
| `all-done` | Every story of the Epic is `done`. | Nothing. The Epic is finished. |
|
|
52
|
+
| `evidence-owed` | Every story is `done`, but a commit hook rejected the last story's gate evidence commit, which is still staged (`.evidence-owed-<story>`). | Close its escalation with `/ucg-resolve` if it is still open, then resume the run once (`/ultracode-goal <epic> -H`) to make the commit. |
|
|
52
53
|
| `limit-reached` | Normal. `--limit` was reached. | Nothing. Drive again. |
|
|
53
54
|
| `blocked` | The story escalated, and a typed sidecar holds the pending decision. | Run `/ucg-resolve`, which reconstructs every pending decision from the sidecars and walks them. |
|
|
54
55
|
| `no-terminal` | The spawn exited without a readable result envelope. | **The work may be complete.** See below. |
|
package/docs/troubleshooting.md
CHANGED
|
@@ -52,7 +52,7 @@ The decision log carries the full blocker list with what each needs to clear. Re
|
|
|
52
52
|
|
|
53
53
|
**What happened.** `gate_eval.py` reads TEA's gate artifact from the trace output directory. `NOT_EVALUATED` means neither the slim `gate-decision.json` nor the fallback `e2e-trace-summary.json` was found there, or the run carried no gate fields. Almost always this is one of:
|
|
54
54
|
|
|
55
|
-
- **The TEA trace gate did not run.** In production, Stage 5 must backfill evidence first (`bmad-testarch-automate`
|
|
55
|
+
- **The TEA trace gate did not run.** In production, Stage 5 must backfill evidence first (`bmad-testarch-automate` first and alone, then the commit of any test it backfilled, then `bmad-testarch-trace` and `bmad-testarch-nfr`) before the gate; `bmad-testarch-trace` is what writes the gate decision. If it didn't run, there is nothing to read.
|
|
56
56
|
- **Wrong `trace_output_dir`.** The script reads the directory passed as `--trace-output` (resolved from `{workflow.trace_output_dir}`). If TEA wrote elsewhere, or the output dirs were never pre-created at preflight, the artifact is real but in a different place. Confirm `trace_output_dir` matches where TEA actually wrote.
|
|
57
57
|
|
|
58
58
|
Note this is fail-closed on purpose: a missing or unreadable gate artifact escalates rather than being assumed green. The slim file's *absence alone* is not the problem: the script falls back to the summary, and that fallback is explicitly not a failure. See the [gate model](./gate-model.md) for how the artifact resolves into a `gate_status` and the full verdict mapping.
|
|
@@ -75,7 +75,7 @@ A per-story gate can return `reloop` with a `PASS` gate status when a cap fired
|
|
|
75
75
|
|
|
76
76
|
**Symptom.** A story stops re-looping; an escalation marker (`<impl-artifacts>/.escalation-<story>.md`) appears; the run surfaces a budget message.
|
|
77
77
|
|
|
78
|
-
**What happened.** Three layers can bound a runaway story. The literal "…or stop after N turns" clause inside a `/goal` condition binds only when you started a `/goal` whose own condition carries it, and then it bounds the session: the conductor cannot start one itself. Otherwise the bound is the gate's re-loop budget: before each re-loop the conductor reads the hook's recorded turn count, and a `reloop` that would exceed `max_turns_per_story` becomes an `escalate` instead. That count advances once per response, so re-loops spent inside one response do not move it, and for `drive_epic.py` spawns the `--session-timeout` wall clock is the backstop. The **Stop** hook (`budget_stop.py`) is the defensive third layer: it counts turns and, on overrun, writes the escalation marker and lets the stop proceed. The marker records the count and does not stop the drive, so the story goes on toward its gate. It becomes an escalation only when the gate escalates the story on that count. A story that passes its gate gets a sizing note in the decision log and the run report instead: no escalation, no ping, and nothing left open.
|
|
78
|
+
**What happened.** Three layers can bound a runaway story. The literal "…or stop after N turns" clause inside a `/goal` condition binds only when you started a `/goal` whose own condition carries it, and then it bounds the session: the conductor cannot start one itself. Otherwise the bound is the gate's re-loop budget: before each re-loop the conductor reads the hook's recorded turn count, and a `reloop` that would exceed `max_turns_per_story` becomes an `escalate` instead. That count advances once per response, so re-loops spent inside one response do not move it, and for `drive_epic.py` spawns the `--session-timeout` wall clock is the backstop. It counts responses, not work: a background task's notification that lands while the session is idle starts a response of its own, which counts the same as one that edits code, so a story whose sweeps, reviews and gate assessors run in the background can reach the ceiling on waiting. Execute keeps that small by making each wait report once, and by starting no other story's work while a story is current. The **Stop** hook (`budget_stop.py`) is the defensive third layer: it counts turns and, on overrun, writes the escalation marker and lets the stop proceed. The marker records the count and does not stop the drive, so the story goes on toward its gate. It becomes an escalation only when the gate escalates the story on that count. A story that passes its gate gets a sizing note in the decision log and the run report instead: no escalation, no ping, and nothing left open.
|
|
79
79
|
|
|
80
80
|
**Its documented limitation.** A Stop hook fires only when Claude is *already* trying to stop: it **cannot interrupt a `/goal` condition mid-turn**. So at this layer the ceiling is advisory; what can stop the story is the conductor's re-loop budget checked against this count, plus the in-condition turn clause when you started a `/goal`. In a single attended or `-H` session with no `/goal` of yours, nothing bounds re-loops spent inside one response; only `drive_epic.py` spawns have a hard backstop, their `--session-timeout` (unless set to `0`). If a story keeps consuming budget, that is the signal to re-scope, split, or hand it off, not to raise the budget and hope.
|
|
81
81
|
|
|
@@ -83,7 +83,7 @@ A per-story gate can return `reloop` with a `PASS` gate status when a cap fired
|
|
|
83
83
|
|
|
84
84
|
**Symptom.** A run was interrupted (Ctrl-C, a crash, a compaction) and you want to continue rather than restart.
|
|
85
85
|
|
|
86
|
-
**What happens.** The run's `.decision-log.md` is canonical memory and recovers full state regardless of compaction. On resume the skill surfaces the existing log with its last session date and offers to resume. Execute re-enters at the **first story whose last logged gate verdict is not `advance`**; already-advanced stories are not re-run. The Epic branch, hooks, and allowlist are **re-asserted, not rebuilt**, before continuing. You do not need to reconstruct state by hand. Point the skill at the same Epic and accept the resume offer.
|
|
86
|
+
**What happens.** The run's `.decision-log.md` is canonical memory and recovers full state regardless of compaction. On resume the skill surfaces the existing log with its last session date and offers to resume. Execute re-enters at the **first story whose last logged gate verdict is not `advance`**; already-advanced stories are not re-run. The Epic branch, hooks, and allowlist are **re-asserted, not rebuilt**, before continuing. You do not need to reconstruct state by hand. Point the skill at the same Epic and accept the resume offer. One case stops instead: when the story it would re-enter still has an open escalation (its `escalation-<story_id>.json` on disk, not closed by `/ucg-resolve`), the run drives nothing and points you at `/ucg-resolve`; a headless run ends `blocked` with a `reason` naming the sidecar. Answer it there, then resume. When the answered escalation was `operator-evidence-owed`, the resume then re-gates the commit your records were made at instead of re-driving the story, as long as nothing was committed after it.
|
|
87
87
|
|
|
88
88
|
## The retired `--parallel` flag
|
|
89
89
|
|
|
@@ -11,7 +11,7 @@ Three intuitive shortcuts all push an unattended Epic toward false completion, a
|
|
|
11
11
|
|
|
12
12
|
**The evaluator only sees the transcript.** Claude Code's `/goal` mode drives a loop until a success condition is met, then asks an evaluator to confirm. But that evaluator reads the transcript; it cannot open a file on disk. It cannot read TEA's `gate-decision.json`. So if you let the `/goal` condition be the final word on "is this story done," you have asked the model to grade its own homework from its own notes. The model cannot be the judge of its own completion: the thing that decides "done" has to be something it cannot author.
|
|
13
13
|
|
|
14
|
-
**`/rewind` checkpoints miss Bash changes.** The obvious undo for a runaway agent is `/rewind`. But its checkpoints do not capture changes made through Bash, and an autonomous Epic run is mostly Bash: test commands, lint, build, and the git commits themselves. Rolling back to a checkpoint leaves the working tree's Bash-driven mutations in place. The real undo for this kind of run is git: an Epic branch off a protected branch, one implementation commit per green story plus its gate's evidence
|
|
14
|
+
**`/rewind` checkpoints miss Bash changes.** The obvious undo for a runaway agent is `/rewind`. But its checkpoints do not capture changes made through Bash, and an autonomous Epic run is mostly Bash: test commands, lint, build, and the git commits themselves. Rolling back to a checkpoint leaves the working tree's Bash-driven mutations in place. The real undo for this kind of run is git: an Epic branch off a protected branch, one implementation commit per green story plus its gate's commits (a test backfill when automate makes one, then the evidence). On a project that gitignores its BMAD output, that undo covers the code only: what the run wrote under the ignored tree stays, the story files, the run's decision log and its sprint-status edits among it. See the [gate model](./gate-model.md) and [architecture](./architecture.md) for how this is wired.
|
|
15
15
|
|
|
16
16
|
**Memory is context, not enforcement.** It is tempting to encode the run's invariants ("never commit on `main`", "never commit before tests pass") into Auto Memory or a CLAUDE.md rule and trust the model to honor them. But memory is context the model may or may not weigh; it does not *block* a `git commit`. An invariant that lives only in memory is a suggestion. An invariant that must hold has to live somewhere the model cannot talk its way past.
|
|
17
17
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json.schemastore.org/package.json",
|
|
3
3
|
"name": "bmad-module-ultracode-goal",
|
|
4
|
-
"version": "3.
|
|
4
|
+
"version": "3.2.0",
|
|
5
5
|
"description": "BMAD module — Run a BMAD Epic autonomously to a machine-checked, TEA-gated Definition-of-Done.",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"bmad",
|
|
@@ -110,6 +110,12 @@ at four fields and cannot carry one, so its id is derived rather than read:
|
|
|
110
110
|
uv run {ucg-root}/scripts/red_ids.py --mint-one <kind> <artifact path> <decision_needed>
|
|
111
111
|
```
|
|
112
112
|
|
|
113
|
+
For a sidecar the three arguments are its own `kind`, `source` and `decision_needed`
|
|
114
|
+
fields, each passed verbatim: `<artifact path>` is the sidecar's `source` field, its
|
|
115
|
+
`:line` suffix and all (the id layer strips it), never the path of the sidecar file
|
|
116
|
+
itself. The resume also reads a close keyed by the sidecar file's own path as closed,
|
|
117
|
+
since earlier passes keyed some that way, but never mint a new id from that path.
|
|
118
|
+
|
|
113
119
|
It prints the id and touches nothing. **A ledger `decision:` row is keyed by the same
|
|
114
120
|
call** — kind `decision`, the ledger path, and the row's reason — because the row's own
|
|
115
121
|
`id` column is unique only within its Epic heading, so `d1` under one Epic and `d1` under
|
|
@@ -205,6 +211,37 @@ The two dispositions are genuinely different things, not two names for one:
|
|
|
205
211
|
the close would apply in name only. Answering a budget overrun by re-scoping, splitting,
|
|
206
212
|
or handing off the story *is* the operator granting it a fresh budget, so the counter that
|
|
207
213
|
recorded the exhausted one has no claim on the resumed run.
|
|
214
|
+
**Closing an `operator-evidence-owed` escalation needs the evidence on disk.** Read the
|
|
215
|
+
live results file its `decision_needed` names and confirm a `status` `pass` record for
|
|
216
|
+
every AC it lists, made at the commit it names. Those are the story's
|
|
217
|
+
`**Gate-ability:** operator-evidence` ACs; a plain `operator` tag is work the dev agent
|
|
218
|
+
builds, never evidence this close waits on. If one is missing, say which and record
|
|
219
|
+
`defer`. An AC the escalation names as partly recorded, with the ids of the records TEA
|
|
220
|
+
already counted for it, closes only on a `pass` record at that commit whose `id` is not
|
|
221
|
+
among the ones the escalation names, or on the operator's written narrowing or move of
|
|
222
|
+
the AC: the records already counted are not enough, since re-gating them changes
|
|
223
|
+
nothing. This surface never writes a record itself: the operator is its producer
|
|
224
|
+
(`{ucg-root}/references/gate.md`, "Operator evidence is a recorded live result"). A
|
|
225
|
+
ruling that narrows or moves the AC is the operator's story edit: record it, then close.
|
|
226
|
+
**That close also writes the story's re-gate marker and resets its turn counter.** Write
|
|
227
|
+
`{workflow.implementation_artifacts}/.regate-<story_id>` as two lines, `sha=` the
|
|
228
|
+
assessed commit the sidecar names (in full, as `git rev-parse` prints it) and
|
|
229
|
+
`decision=` the id you closed, then delete the sidecar as for any close, and delete
|
|
230
|
+
`{workflow.implementation_artifacts}/.budget-<story_id>.json`: waiting for operator
|
|
231
|
+
evidence is not the story's work. The marker is the re-gate entry. While its `sha=`
|
|
232
|
+
names `HEAD`, the resume's `--assert-armed` call routes the story `gate-owed`, so it
|
|
233
|
+
re-enters at Stage 5 to re-gate that commit, and is never re-driven from step 0, where
|
|
234
|
+
the turn-ceiling read could escalate it and a commit past the assessed one would make
|
|
235
|
+
the records stale (`{ucg-root}/references/execute.md`, the resume rule). The gate
|
|
236
|
+
deletes the marker once the re-gate's verdict is logged.
|
|
237
|
+
**Closing an `evidence-commit-rejected` escalation makes no commit.** Record the
|
|
238
|
+
operator's answer (the hook fixed or reconfigured, or the file it named changed by them),
|
|
239
|
+
then delete only the sidecar. Leave the staged evidence and
|
|
240
|
+
`{workflow.implementation_artifacts}/.evidence-owed-<story_id>` alone, even when the
|
|
241
|
+
answer is to commit as it stands: the resume makes that commit under the gate's hook rule
|
|
242
|
+
and removes the marker (`{ucg-root}/references/gate.md`, "Commit the gate's evidence
|
|
243
|
+
before the next story starts"), on the Epic's last story too, where every row already
|
|
244
|
+
reads `done` and the resume re-enters only for that commit before Finalize.
|
|
208
245
|
- **`defer`** — the decision is not made yet. Record the entry **without clearing
|
|
209
246
|
anything**. The artifact stays exactly where it is, the item stays pending, and the next
|
|
210
247
|
preflight still blocks on it.
|
|
@@ -233,7 +270,9 @@ may skip, because the two arrive from different places:
|
|
|
233
270
|
verdict is not advance; advanced stories are not re-run. Within that branch there is
|
|
234
271
|
no other re-entry point: it is not the first story of the Epic, and not the story the
|
|
235
272
|
answered decision happened to name, either of which would re-run stories that already
|
|
236
|
-
advanced, which is precisely what the shipped resume rule exists to prevent.
|
|
273
|
+
advanced, which is precisely what the shipped resume rule exists to prevent. When every
|
|
274
|
+
story advanced and a story's `.evidence-owed-<story_id>` is on disk, the resume drives no
|
|
275
|
+
story: it makes that story's owed evidence commit and goes to Finalize.
|
|
237
276
|
|
|
238
277
|
Either branch **re-asserts** — never rebuilds — the Epic branch, both hooks, the
|
|
239
278
|
allowlist, the `.mem-state.json` recall latch, and the in-flight story's baseline marker.
|
|
@@ -176,8 +176,9 @@ typed record as never written.
|
|
|
176
176
|
|
|
177
177
|
When `hunk` is on PATH, each story that recorded a baseline commit gains copy-paste
|
|
178
178
|
`hunk show <commit>` lines, so a reader can go straight from a story row to its diff:
|
|
179
|
-
one line per commit in the story's range (its implementation commit
|
|
180
|
-
|
|
179
|
+
one line per commit in the story's range (its implementation commit, the gate's test
|
|
180
|
+
backfill commit when automate made one, and the gate's evidence commit) when the
|
|
181
|
+
repository is readable, else one line for the story's
|
|
181
182
|
recorded end commit, or for its baseline when no end commit was recorded. When it is not on PATH, nothing about it is rendered and the render is otherwise
|
|
182
183
|
unchanged.
|
|
183
184
|
|
|
@@ -36,7 +36,7 @@ Load config from `{project-root}/_bmad/config.yaml` and `config.user.yaml` (root
|
|
|
36
36
|
|
|
37
37
|
**Quick launch** (swap in your Epic id): `ultracode goal epic-7` — attended, production, sequential. `ultracode goal epic-7 --light --yes` — the expert one-liner: trace-only gate, no conversational stops. Add `-H` for headless, `--retro` for the close-out retrospective, `--max-stories 1` to take a single story this invocation.
|
|
38
38
|
|
|
39
|
-
**Resume.** The workspace is this skill's run folder holding `.decision-log.md`. If one exists for the Epic, surface it with its last session date and offer to resume: the log recovers full state regardless of compaction. Otherwise create it at intent and append a session heading. **Route resume by the last stage the log reached**: the run folder is created at intent (Stage 1), so a prior run that blocked *before* Execute also leaves one. If the log carries gate verdicts, re-enter Execute at the first story whose last verdict is not advance (advanced stories are not re-run), re-asserting (not rebuilding) the Epic branch, hooks, allowlist, and the `.mem-state.json` recall latch first (the latch by minting this invocation's own run id as Stage 1 does, never reusing one an earlier invocation logged, and re-running Stage 1's `mem_recall.py latch` step with it, which replaces a latch another run left; `references/execute.md` says why each, and why the latch especially). If instead it blocked at Stage 1 (epic unresolved) or Stage 2 (preflight RED: the case an operator fixes then re-invokes), re-run from that stage so the hard preflight gate is never skipped. A re-run from Stage 2 first runs Stage 1's Cross-Session Recall section with a fresh run id (the latch and, on a green latch, its one filter call, whose output Stage 2 reads), since the blocked run's preflight STOP removed its latch. In headless (`-H`) never offer: auto-resume a not-all-done Epic by this same stage routing (a previously-preflight-RED Epic re-runs the gate, it does not enter Execute), delete any existing `{workflow.implementation_artifacts}/run-result.json` as soon as that scalar resolves exactly as a fresh run does (`references/ingest-and-scope.md`), and log the resume as an assumption. **A resume routed into Execute does NOT re-run the Stage-2 formalize gate.** That verdict is Stage 2's and it
|
|
39
|
+
**Resume.** The workspace is this skill's run folder holding `.decision-log.md`. If one exists for the Epic, surface it with its last session date and offer to resume: the log recovers full state regardless of compaction. Otherwise create it at intent and append a session heading. **Route resume by the last stage the log reached**: the run folder is created at intent (Stage 1), so a prior run that blocked *before* Execute also leaves one. If the log carries gate verdicts, re-enter Execute at the first story whose last verdict is not advance (advanced stories are not re-run), re-asserting (not rebuilding) the Epic branch, hooks, allowlist, and the `.mem-state.json` recall latch first (the latch by minting this invocation's own run id as Stage 1 does, never reusing one an earlier invocation logged, and re-running Stage 1's `mem_recall.py latch` step with it, which replaces a latch another run left; `references/execute.md` says why each, and why the latch especially). That re-entry stops short when the story still carries an open escalation: the re-assertion sweep's story route then reads `decision-pending`, and the resume drives nothing (attended, offer `/ucg-resolve`; headless, end `blocked` with a `reason` naming its `escalation-<story_id>.json`; `references/execute.md` says what counts as open). If instead it blocked at Stage 1 (epic unresolved) or Stage 2 (preflight RED: the case an operator fixes then re-invokes), re-run from that stage so the hard preflight gate is never skipped. A re-run from Stage 2 first runs Stage 1's Cross-Session Recall section with a fresh run id (the latch and, on a green latch, its one filter call, whose output Stage 2 reads), since the blocked run's preflight STOP removed its latch. In headless (`-H`) never offer: auto-resume a not-all-done Epic by this same stage routing (a previously-preflight-RED Epic re-runs the gate, it does not enter Execute), delete any existing `{workflow.implementation_artifacts}/run-result.json` as soon as that scalar resolves exactly as a fresh run does (`references/ingest-and-scope.md`), and log the resume as an assumption. An Epic whose stories all read `done` while a story's `.evidence-owed-<story_id>` is on disk (its evidence commit, escalated as `evidence-commit-rejected`, is still owed, whether or not `/ucg-resolve` has closed that escalation) counts as not-all-done here and in Stage 1's already-done short-circuit: its resume re-enters Execute only for that commit, then goes to Finalize (`references/execute.md`'s resume rule). **A resume routed into Execute does NOT re-run the Stage-2 formalize gate.** That verdict is Stage 2's and it covers the run's whole in-scope set by construction (`formalize_check.py` reads every not-`done` story of the Epic, or the operator-scoped subset its `--story` flags name, never only the stories one invocation drives), so on any Epic with undrafted or later stories it reads `remediable`/`blocked` on gaps belonging to rows this invocation is not driving. Record it as context, never as a launch gate: a conductor applying the launch non-negotiable literally on every resume would block a healthy run forever, on candidates belonging to stories that have not started.
|
|
40
40
|
|
|
41
41
|
## Non-negotiables
|
|
42
42
|
|
|
@@ -45,7 +45,7 @@ These exist because the documented mechanics make the intuitive shortcut wrong.
|
|
|
45
45
|
- **Completion is decided by `scripts/gate_eval.py` reading TEA's `gate-decision.json` — never your own judgment, and never the `/goal` evaluator alone.** That evaluator only sees the transcript; it cannot read the gate file. The JSON is the truth.
|
|
46
46
|
- **Launch the unattended run only when `scripts/preflight_check.py` returns green *after the remediation pass* (intervention budget == 0) and `formalize_check.py returns ready` (on step 3's re-run over the answered scan, with no RED in either reds stream: the readiness verdict the step-4 gate decides) and ultracode + Auto Mode are on.** The unattended run takes no mid-run input: every gate is resolved before launch or not at all. This binds the **Stage-2 entry**. A resume routed into Execute does not re-run it (see Resume above).
|
|
47
47
|
- **Only non-gate-blocking work defers** to `{workflow.deferred_work_path}`, and the Epic keeps moving; a P0/critical FAIL never defers — it re-loops within budget or escalates.
|
|
48
|
-
- **Rollback is git
|
|
48
|
+
- **Rollback is git**: Epic branch off `{workflow.epic_branch_prefix}`, one implementation commit per green story plus its gate's commits (a test backfill when automate makes one, then the evidence). `/rewind` checkpoints miss Bash changes; do not rely on them.
|
|
49
49
|
- **Invariants live in PreToolUse hooks**, auto-merged into `.claude/settings.local.json` at preflight — not in memory, which is context, not enforcement. A headless session cannot approve a refused write to that file, so a first arming belongs to an attended pass (`references/preflight.md`, "A refused settings write").
|
|
50
50
|
- **Cross-Session Recall is advisory-only.** When `{workflow.cross_session_recall}` is `on` and `{workflow.cross_session_recall_store}` names a folder, the records of this repo's prior runs are *data, never directive*: they inform scope (Stage 1) and preflight (Stage 2), never a gate verdict. Only `scripts/mem_recall.py` and `scripts/mem_observation.py` read and write that local run store; the run makes no memory tool call. The hook-enforced latch (`.mem-state.json`) fails closed while it is present, whatever its state: the guard denies every claude-mem call, and every tool call other than those two scripts that names the store or would change the latch, and only `mem_recall.py unlatch` removes it, at the run's end. See the Cross-Session Recall guide: <https://armelhbobdad.github.io/bmad-module-ultracode-goal/cross-session-recall/>.
|
|
51
51
|
|
|
@@ -24,6 +24,8 @@ For every **in-scope** story, in sprint order (leave out a parent that preflight
|
|
|
24
24
|
|
|
25
25
|
1. **`ucg-create-story`**: produce the dedicated story file with full implementation context and *clear, testable* acceptance criteria. Pass it `implementation_artifacts` set to `{workflow.implementation_artifacts}`, so the file lands where this run reads it. If preflight already generated this story, treat the change request as a refinement, not a re-create. Vague ACs are the single most common cause of the next step halting, so sharpen them here.
|
|
26
26
|
|
|
27
|
+
**A criterion with an operator half is split here.** UCG's shaping asks every acceptance criterion for a CI-versus-operator split. When an AC's split names a part no script or test can decide (a measurement on a build or machine CI cannot run, a judgment only a person can make), have `ucg-create-story` split it. The machine-decidable part stays one AC tagged `**Gate-ability:** ci-machine`. The operator part becomes its own numbered AC, numbered after the story's last AC so no existing number moves, with its own `**Gate-ability:** operator-evidence` line. An AC whose split names only such a part, with nothing a script or test can decide, is not split. Retag it in place, keeping its number, with `**Gate-ability:** operator-evidence`, whatever tag it carried, only when it asks the dev agent to build or change nothing: its whole content is a measurement, run or observation a person makes and records. The test is whether the AC asks for anything to be built or changed, not who can check it: an AC that asks for a change (code, a comment, a doc, a ledger edit) keeps its tag even when only a person's read can check it. The `operator-evidence` tag is this class's alone: a plain `**Gate-ability:** operator` tag keeps its meaning, work the dev agent builds that a person or a script verifies, and nothing reads it as owed evidence. Its **Verification** is a recorded live result (`references/gate.md`, "Operator evidence is a recorded live result"), and its anti-vacuous twin is that a `fail` record, or a record made at another commit, leaves it uncovered. Never leave the operator part inside a ci-machine AC as prose such as "recorded rather than gated": trace classifies a criterion by everything it states, so the unrecorded half holds the whole AC at PARTIAL. The split drops and relaxes nothing. Log each split in `.decision-log.md`.
|
|
28
|
+
|
|
27
29
|
**A decomposed child gets no story file.** Skip this step for a key the readiness check listed in `checks.decomposed_children` when the split is recorded (its split record (`.split-<parent key>.json` beside `sprint-status.yaml`, which `scripts/story_sizing.py --record` writes) names the child, the child's row cites the parent ACs it claims, or `.decision-log.md` names the parent and the ACs each child claims): the child has no story file and must never get one, and its criteria are the parent ACs it claims, in the parent's file (`references/execute.md`, step 1). A listed key with none of these records is a story of its own that reads like a child (above a `done` parent's row, or under a parent whose row was removed): create its file here, and log in `.decision-log.md` that the readiness check never read its criteria. One such key already has its file: a key whose title starts with a single letter or a roman numeral (`2-4-a-new-login-page`) reads one level below its story number, so its own story file named by that number alone (`2-4.md`) or by another title is listed as the parent of a removed row. When the listed parent file is that story's own (`parent_row` is `null`, no other key in the list names the same file, and the file's title and criteria are this key's), rename that file to `<key>.md` instead, in one `mv <that file> <its folder>/<key>.md` call (a filesystem command `acceptEdits` runs without asking on a path inside the project, unlike a git move, which no allow rule covers), then run this step on it as a refinement, and log the rename: the readiness check did read its criteria. A file two listed keys name is a parent's, so rename it for neither.
|
|
28
30
|
|
|
29
31
|
On a project whose artifact tree git does not track (preflight's `impl_artifacts_tracked: false`), no acceptance criterion may have a test read a file under that tree at run time: it does not exist in CI. Preflight step 2 states the rule ("A gitignored artifact tree").
|
|
@@ -36,6 +38,8 @@ For every **in-scope** story, in sprint order (leave out a parent that preflight
|
|
|
36
38
|
|
|
37
39
|
**For a decomposed child, run it under the child's own key** (on a stack ATDD cannot run on, the hand-established red phase above stands in, as for any story, scoped to the parent ACs the child claims). Give it the parent's story file for the text of the parent ACs the child claims, and have it write `atdd-checklist-<child key>.md` with the child's key as its story key and the parent's key and those AC numbers in its frontmatter. ATDD otherwise takes the story key from the file it reads, so it would write the parent's checklist, and each sibling's into the same file, while Execute and its commit guard read the child's. Build its criterion registry from the parent's whole AC list, so each id keeps the parent's number, and scaffold the claimed ids only. Treat the parent's file as one ATDD cannot update safely, so it skips the link back into it: the parent's story file is never edited. ATDD's closing checks that every declared criterion has a scaffold and that the link back was written do not apply to a child, and are not gaps to fix. A halt on vague criteria is no loop back here: never run `ucg-create-story` for the child and never edit the parent's file. Record the halt in `.decision-log.md` and escalate as Execute's sub-skill halt catch-all does (`references/execute.md`: write the typed escalation sidecar, then stop), naming the parent ACs that need sharpening.
|
|
38
40
|
|
|
41
|
+
**An operator-evidence AC gets no red-phase scaffold**, and on a stack ATDD cannot run on, no hand-established red-phase case either: no test can decide it, and its proof is the recorded live result. Build ATDD's criterion registry from the whole AC list and scaffold every AC except the ones tagged `**Gate-ability:** operator-evidence`, as for a decomposed child's claimed subset. ATDD's closing check that every declared criterion has a scaffold does not apply to an operator-evidence AC, and is not a gap to fix.
|
|
42
|
+
|
|
39
43
|
Force **Create** mode (not Resume/Validate/Edit) for the same unattended reason.
|
|
40
44
|
|
|
41
45
|
**In `--light`:** run step 1 (`ucg-create-story`) but **skip step 2 (`bmad-testarch-atdd`)**: `--light` produces no executable red-phase acceptance tests. The story file and its acceptance criteria become the Definition-of-Done and the oracle `bmad-testarch-trace` resolves the Stage 5 gate against, mirroring gate.md's `--light` branch (which runs only `bmad-testarch-trace`). The per-Epic test-design above still runs in `--light`: `bmad-testarch-trace` consumes its risk scores and P0–P3 priorities when they are available, and they are the backbone you sharpen the ACs against in either profile. Sharpen the ACs here exactly as you would for production: under `--light` they are the *only* machine-checkable DoD a story gets, so vague ACs leave the trace gate nothing to resolve against.
|
|
@@ -50,6 +54,6 @@ Stage 3 is complete, and Stage 4 may begin, when **all three** hold:
|
|
|
50
54
|
|
|
51
55
|
- The Epic has a `bmad-testarch-test-design` plan with a populated risk matrix, P0–P3 priorities assigned, and every in-scope NFR threshold either resolved or explicitly marked `UNKNOWN`/deferred.
|
|
52
56
|
- **Every in-scope story** has a story file with clear acceptance criteria. A recorded decomposed child, which has none of its own, meets this through its parent's story file, which holds the parent ACs it claims.
|
|
53
|
-
- **Every in-scope story** has a generated `atdd-checklist-{story_key}.md` and red-phase (`test.skip`) acceptance tests on disk
|
|
57
|
+
- **Every in-scope story** has a generated `atdd-checklist-{story_key}.md` and red-phase (`test.skip`) acceptance tests on disk (**production only**, on a stack ATDD can run on). An operator-evidence AC needs no scaffold (step 2). Under `--light` this is skipped by design; the story file's acceptance criteria stand as the trace oracle instead, and this bullet is satisfied by the clear-ACs bullet above. On a **non-web stack** (ATDD's generator cannot run), this bullet is satisfied by the recorded hand-establishment commitment per story (the substitution in step 2 above), never by a checklist nobody could generate.
|
|
54
58
|
|
|
55
59
|
In production, if any in-scope story is missing its atdd-checklist, this stage is not done — Execute has nothing executable to drive that story to. (Under `--light` an absent atdd-checklist is expected, not a gap; on a non-web stack the hand-established red phase per `references/gate.md`'s non-web section stands in for it, and the decision log says so per story.) Record in `.decision-log.md`: the test-design verdict, each story's AC + checklist status (or the `--light` skip), and any deferral appended to `{workflow.deferred_work_path}`.
|