bmad-module-ultracode-goal 2.0.0 → 2.1.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.
Files changed (41) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/README.md +3 -4
  3. package/docs/404.md +1 -1
  4. package/docs/_internal/STABILITY.md +9 -7
  5. package/docs/architecture.md +15 -11
  6. package/docs/comparison.md +19 -11
  7. package/docs/getting-started.md +1 -1
  8. package/docs/how-it-works.md +2 -2
  9. package/docs/index.md +0 -1
  10. package/docs/operating-tips.md +1 -1
  11. package/docs/troubleshooting.md +5 -5
  12. package/docs/why-ultracode-goal.md +1 -1
  13. package/package.json +5 -4
  14. package/skills/ucg-formalize/SKILL.md +136 -39
  15. package/skills/ucg-resolve/SKILL.md +86 -58
  16. package/skills/ucg-status/SKILL.md +64 -30
  17. package/skills/ultracode-goal/SKILL.md +9 -11
  18. package/skills/ultracode-goal/assets/module-help.csv +1 -1
  19. package/skills/ultracode-goal/assets/module.yaml +8 -3
  20. package/skills/ultracode-goal/assets/ucg-awareness/bmad-testarch-test-design.toml +8 -0
  21. package/skills/ultracode-goal/customize.toml +11 -6
  22. package/skills/ultracode-goal/references/define-done.md +3 -3
  23. package/skills/ultracode-goal/references/execute.md +34 -53
  24. package/skills/ultracode-goal/references/finalize.md +12 -12
  25. package/skills/ultracode-goal/references/gate.md +24 -7
  26. package/skills/ultracode-goal/references/health-check.md +7 -4
  27. package/skills/ultracode-goal/references/ingest-and-scope.md +4 -4
  28. package/skills/ultracode-goal/references/preflight.md +9 -8
  29. package/skills/ultracode-goal/scripts/gate_eval.py +518 -37
  30. package/skills/ultracode-goal/scripts/gate_trail.py +131 -32
  31. package/skills/ultracode-goal/scripts/health_check_fp.py +98 -3
  32. package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +56 -14
  33. package/skills/ultracode-goal/scripts/mem_observation.py +48 -10
  34. package/skills/ultracode-goal/scripts/preflight_check.py +397 -3
  35. package/skills/ultracode-goal/scripts/status_render.py +20 -2
  36. package/skills/ultracode-goal/scripts/story_sizing.py +193 -0
  37. package/tools/build-docs.js +24 -1
  38. package/tools/validate-docs-links.js +169 -8
  39. package/website/astro.config.mjs +0 -1
  40. package/docs/parallel-mode.md +0 -68
  41. package/skills/ultracode-goal/assets/execute-epic.workflow.js +0 -249
@@ -11,8 +11,8 @@ description: Opt-in standalone readiness verdict for one BMAD Epic via the `/ucg
11
11
  single BMAD Epic — the thin LLM layer over the readiness kernel
12
12
  (`scripts/formalize_check.py`). It adapts the kernel's graduated verdict
13
13
  (ready / remediable / blocked) into the canonical five-key headless envelope; it never
14
- recomputes the readiness verdict (Step 1 carries that rule at its point of use). Each
15
- verdict and remediation lands in `.decision-log.md`.
14
+ recomputes the readiness verdict. Each verdict and remediation lands in
15
+ `.decision-log.md`.
16
16
 
17
17
  ## Conventions
18
18
 
@@ -26,25 +26,43 @@ verdict and remediation lands in `.decision-log.md`.
26
26
  It is deliberately **not** `{skill-root}`: this is a top-level skill, so `{skill-root}`
27
27
  would resolve to this skill's own directory, which holds none of those files.
28
28
  - `{project-root}`-prefixed paths resolve from the project working directory.
29
- - `{workflow.implementation_artifacts}` and `{workflow.tea_config_path}` resolve from
30
- the parent module's `customize.toml` workflow block (the same scalars the autonomous
31
- run reads). `{planning_artifacts}` is not a workflow scalar — it resolves from BMad
29
+ - `{workflow.implementation_artifacts}`, `{workflow.tea_config_path}`,
30
+ `{workflow.trace_output_dir}` (step 2's leaked-TEA destination) and
31
+ `{workflow.deferred_work_path}` resolve from the parent module's `customize.toml`
32
+ workflow block (the same path scalars the autonomous run reads).
33
+ `{planning_artifacts}` is not a workflow scalar — it resolves from BMad
32
34
  core `config.yaml` (root + `bmm` section), mirroring the parent SKILL.md, and is not
33
35
  part of the customize override surface.
36
+ - **Of the three universal `[workflow]` defaults, this entry point loads one and runs
37
+ neither.** `persistent_facts` **is** loaded: it is read-only context, and a cold
38
+ standalone verdict is exactly the session that has none. `activation_steps_prepend` and
39
+ `activation_steps_append` are **not** executed here — they are operator-configured
40
+ actions belonging to the autonomous run, and the standalone surfaces stay thin and
41
+ side-effect-free. `ucg-resolve` and `ucg-status` state this same split, so the three
42
+ agree; `ucg-status` in particular could not honor it otherwise, having promised to write
43
+ nothing at all.
34
44
  - The decision log (`.decision-log.md`) is canonical memory: record the verdict and
35
- every auto-remediation as you go.
45
+ every auto-remediation as you go. It lives in the Epic's run folder under
46
+ `{project-root}/_bmad-output/ultracode-goal/`: reuse the newest `epic-<id>-*` folder
47
+ for this Epic when one exists (appending a session entry), otherwise create
48
+ `epic-<id>-<UTC yyyymmddThhmmssZ>` for this standalone check. That resolved path is
49
+ what the Headless `decision_log` key carries, so two invocations over the same Epic
50
+ cannot scatter their verdicts across two files.
36
51
 
37
52
  ## On Activation
38
53
 
39
54
  `/ucg-formalize` can run cold (outside an active `ultracode goal` run), so resolve the
40
- scalars the step-1 kernel consumes before calling it — against the **parent** module, so
41
- they are the same scalars the autonomous run reads. Run `python3
55
+ scalars this skill consumes — the step-1 kernel's *and* step 2's
56
+ `{workflow.trace_output_dir}` — before calling the kernel, against the **parent** module,
57
+ so they are the same path scalars the autonomous run reads. Run `python3
42
58
  {project-root}/_bmad/scripts/resolve_customization.py --skill {ucg-root} --key workflow`
43
59
  (on failure, merge `{ucg-root}/customize.toml` →
44
60
  `{project-root}/_bmad/custom/ultracode-goal.toml` →
45
61
  `{project-root}/_bmad/custom/ultracode-goal.user.toml`, scalars override / arrays append),
46
62
  and load `{planning_artifacts}` from `{project-root}/_bmad/config.yaml` (root + `bmm`
47
- section). If they cannot be resolved, do not pass unresolved `{…}` tokens to the kernel:
63
+ section). If they cannot be resolved, do not pass unresolved `{…}` tokens to the kernel
64
+ or to a step-2 file move (a move into a literal `{workflow.trace_output_dir}` directory
65
+ would log as a successful remediation the kernel re-run can never see):
48
66
  record a blocked verdict and push a non-remediable blocker — `source` the unresolved
49
67
  config path, note "customization/config scalars unresolved" — into step 4's ordered
50
68
  blocker list, so the Headless `reason` renders.
@@ -62,7 +80,7 @@ Read the kernel's readiness verdict JSON from stdout. Its shape is
62
80
  `{ready, verdict, mechanical_budget, judgment_required, mechanical_gaps[], judgment_candidates[], checks{}}`.
63
81
  Do not recompute it: read `mechanical_budget` and the verdict off the JSON, never re-derive
64
82
  them here. There is one kernel — a second readiness evaluator would let the two callers
65
- drift, the failure this shared kernel exists to prevent.
83
+ drift.
66
84
 
67
85
  The kernel is fail-closed: a missing / unreadable / ambiguous artifact is recorded
68
86
  as a failing gap, never a neutral pass.
@@ -74,7 +92,10 @@ each entry where `remediable: true`. The remediation per kind:
74
92
 
75
93
  - **`leaked_tea_artifact`** — move the TEA artifact from the source/impl tree to the
76
94
  `{workflow.trace_output_dir}` root and re-point any reference to it. A path move is
77
- meaning-preserving.
95
+ meaning-preserving. Verify identity before moving: a non-TEA false positive is
96
+ archived *out of* the impl-artifacts scan tree — never into the trace dir (that
97
+ misfiles it) and never left in place (an uncleared remediable gap keeps the verdict
98
+ off `ready`).
78
99
  - **`orphaned_index`** (regenerable story/AC) — regenerate the missing story or AC
79
100
  stub via `bmad-create-story` so the cited id resolves.
80
101
  - **`missing_planning_artifact` / `missing_impl_artifact`** — backfill the
@@ -83,6 +104,26 @@ each entry where `remediable: true`. The remediation per kind:
83
104
  - **`ac_missing_named_verification` / `ac_missing_anti_vacuous_twin`** — backfill the
84
105
  canonical named-verification / anti-vacuous-twin / gate-ability scaffold derivable
85
106
  from the AC shape.
107
+ - **`story_keys_uncovered` / `story_without_ac`** — run the `bmad-create-story` scaffold
108
+ for the story keys the gap's `detail` names: `story_keys_uncovered` lists the unresolved
109
+ subset, and `story_without_ac` names the one story whose AC section is missing.
110
+ - **`no_in_scope_stories`** — same scaffold, but this gap's `detail` names only the Epic
111
+ and the artifacts directory, never a key list, so take the keys from the **sprint
112
+ rollup's rows for this Epic** instead of trying to read them out of `detail`. First
113
+ discriminate on the input: when the Epic id matches **no row at all** in the rollup,
114
+ that is a mistyped or unseeded Epic, not a gap to scaffold over — record it as a
115
+ non-remediable blocker and route to `status=blocked` rather than authoring stories for
116
+ an Epic nobody planned.
117
+ - **`blank_pxi_score`** — write the gap's own `recomputed` value into the blank Score
118
+ cell at its `source` line. Use the value the kernel supplies; never re-derive the
119
+ product here, which would be a second multiplier free to disagree with the first.
120
+
121
+ The kernel emits **ten** `remediable: true` kinds and the list above covers all ten. A
122
+ `remediable: true` kind that is nonetheless *not* listed here is never improvised from
123
+ its `detail`: record it as a non-remediable blocker naming the kind and route to
124
+ `status=blocked`. That clause is what keeps this list honest as the kernel grows — a new
125
+ kind blocks loudly instead of being guessed at, and the halt catch-all below then covers
126
+ the never-remediated case as well as the remediated-but-unfixed one.
86
127
 
87
128
  Log each remediation to `.decision-log.md` as you apply it. Never
88
129
  auto-remediate a `judgment_candidate`, and never auto-remediate a
@@ -109,8 +150,19 @@ would double-judge the same candidates, so never two. Seed the subagent with the
109
150
  flagged sources, it does not scan blind), plus the artifact paths. The corpus stays in the
110
151
  subagent's discarded context (zero-net-context) — this layer holds only the returned findings.
111
152
 
153
+ The kernel only *flags*; the subagent *decides*. It must **confirm-or-clear** each seeded
154
+ `judgment_candidate` into `reds` or `concerns`, never recording one as a RED unprompted.
155
+ Fail-closed: a `judgment_candidate` the subagent can neither confirm nor clear **defaults
156
+ to RED** (JUDGMENT), mirroring `gate_eval.py`'s `nfr_status is None → failing` and the
157
+ identical rule the spine's scan carries (`{ucg-root}/references/preflight.md`, second hypothesis
158
+ stream). Without it a candidate the subagent simply does not return on is neither red nor
159
+ concern, and silently vanishes into an accept — which would make this standalone pass
160
+ fail-open exactly where the spine's is fail-closed, and contradict the kernel's own
161
+ fail-closed contract stated in step 1. **This rule binds the degraded inline read below
162
+ too**: losing the subagent costs the zero-net-context property, never the fail-closed one.
163
+
112
164
  The subagent must return **only this object** — the live three-key contract the parent
113
- `references/preflight.md` semantic scan uses — no prose, no document quotes beyond the
165
+ `{ucg-root}/references/preflight.md` semantic scan uses — no prose, no document quotes beyond the
114
166
  one-line evidence fields:
115
167
 
116
168
  ```json
@@ -122,15 +174,31 @@ one-line evidence fields:
122
174
  "advisories_checked": [{"sig": "<advisory id>", "status": "recurred|not-observed|unknown"}]}
123
175
  ```
124
176
 
125
- Any `reds` entry maps to `status=blocked`. Record each red with its source and the
126
- exact decision needed in `.decision-log.md`. A purely cosmetic gap belongs in
127
- `concerns`, never red.
177
+ **Mint ids before mapping, and apply the operator's closes.** Hand the returned scan
178
+ object — the degraded inline read below yields the same object — to the same id layer the
179
+ spine runs (`{ucg-root}/references/preflight.md`, step 3), in report-only mode:
180
+
181
+ ```
182
+ uv run {ucg-root}/scripts/red_ids.py --scan - --impl-artifacts {workflow.implementation_artifacts} --dry-run
183
+ ```
184
+
185
+ It mints each red's stable id and drops every red whose id an operator already closed in
186
+ `{workflow.implementation_artifacts}/.decisions.json`, so a decision answered through
187
+ `/ucg-resolve` does not re-block this surface at every invocation. Never mint, compare, or
188
+ edit an id by hand, and a non-zero exit clears nothing: every scanned red stands.
189
+ `--dry-run` is deliberate — `.preflight-reds.json` is the autonomous run's durable
190
+ registry and a standalone readiness check must not overwrite it, which also means a red
191
+ found only here is not answerable through `/ucg-resolve` until an autonomous preflight
192
+ records it.
193
+
194
+ Any surviving `reds` entry maps to `status=blocked`. Record each red with its minted id,
195
+ its source, and the exact decision needed in `.decision-log.md`. A purely cosmetic gap
196
+ belongs in `concerns`, never red.
128
197
 
129
198
  **If subagent spawning is unavailable** — wrong runtime, quota exhausted, or the spawn
130
199
  errors — do not dead-end the verdict: read the kernel's flagged
131
200
  `judgment_candidates[].source` inline in the current context (accepting the context cost;
132
- only the zero-net-context property is lost) and proceed to verdict mapping. This degraded
133
- path runs zero subagents, never an extra one, so it preserves the one-subagent determinism.
201
+ only the zero-net-context property is lost) and proceed to verdict mapping.
134
202
 
135
203
  ## 4. Verdict mapping
136
204
 
@@ -140,21 +208,34 @@ emit value.
140
208
 
141
209
  | Condition | Route | Headless status |
142
210
  |-----------|-------|-----------------|
143
- | `mechanical_budget == 0` AND no reds (verdict ready) | accept | `status=complete` |
211
+ | post-remediation kernel `verdict == ready` AND no reds | accept | `status=complete` |
144
212
  | `mechanical_budget > 0`, all gaps remediable, no reds (verdict remediable) | remediate-then-re-run (step 2), then re-map | (loops; never emits `remediable`) |
145
213
  | any red OR any non-remediable mechanical gap OR any artifact the kernel could not read | reject | `status=blocked` |
146
-
147
- The blocked row's three triggers (any red, any non-remediable mechanical gap, any
148
- unreadable artifact) are all load-bearing. The one whose *why* the table cannot carry is
149
- the unreadable artifact: an artifact the kernel could not read is fail-closed to
150
- `status=blocked` (mirroring `gate_eval.py`'s `nfr_status is None -> failing` read), never
151
- treated as neutral — formalize's `blocked` is a deliberate strengthening over gate_eval's
152
- reloop.
214
+ | kernel `verdict == blocked` on judgment alone — `mechanical_budget == 0`, no non-remediable gap, no red, because the subagent cleared every flagged candidate into `concerns` | reject | `status=blocked` |
215
+
216
+ **The last row is why this list is total.** Without it the common case falls through
217
+ every row: the kernel flags a judgment candidate on most Epics, the subagent clears it,
218
+ and the result satisfies neither the accept row (the kernel never said `ready`) nor the
219
+ first reject row (there is no red and no non-remediable gap). Its blocker list is the
220
+ cleared candidates themselves, each by `source`, with `decision_needed` naming that the
221
+ kernel flagged it and the judgment pass cleared it.
222
+
223
+ **Row 1 is keyed on the kernel's own verdict word, never on the budget alone.** The two
224
+ are not equivalent: `formalize_check.py` sets `verdict = "blocked"` whenever
225
+ `judgment_required` is true, *independent of* `mechanical_budget`, and step 2 never
226
+ removes a judgment candidate (it is forbidden to remediate one). So budget `0` with zero
227
+ reds is reachable while the kernel still reads `blocked` — whenever the subagent classified
228
+ every flagged candidate into `concerns`. Keying the accept row on the budget would route
229
+ that state to `complete` and hand back a ready verdict the kernel never gave. The budget
230
+ and reds clause is the *explanation* of a ready verdict, not the test for one.
231
+
232
+ An artifact the kernel could not read is fail-closed to `status=blocked` (mirroring
233
+ `gate_eval.py`'s `nfr_status is None -> failing` read), never treated as neutral —
234
+ formalize's `blocked` is a deliberate strengthening over gate_eval's reloop.
153
235
 
154
236
  For a blocked envelope, assemble the **ordered blocker list** — confirmed reds before
155
237
  non-remediable mechanical gaps, each in `source` (`path:line`) order — and hand it to the
156
- shared `build_headless_envelope` adapter (see Headless), which renders `reason` positionally
157
- from it.
238
+ blocked adapter (see Headless), which renders `reason` positionally from it.
158
239
 
159
240
  ## Headless
160
241
 
@@ -164,12 +245,28 @@ autonomous parent `SKILL.md` shape: `skill` is the constant `ultracode-goal` (ne
164
245
  `ucg-formalize`), and the script-layer keys (`verdict`, `mechanical_budget`) never leak
165
246
  into the envelope.
166
247
 
167
- Serialize the envelope through the one shared adapter
168
- `{ucg-root}/scripts/headless_envelope.py` (`build_headless_envelope`) — the same
169
- definition `references/preflight.md` uses — passing the ordered blocker list
170
- from step 4. The adapter emits the canonical keys and the positional `reason`
171
- (`blockers[0]`), so this entry point and the autonomous run cannot serialize a blocked
172
- exit differently.
248
+ Serialize through the one shared module `{ucg-root}/scripts/headless_envelope.py` — the
249
+ same definition `{ucg-root}/references/preflight.md` and `{ucg-root}/references/finalize.md` use — so this entry
250
+ point and the autonomous run cannot serialize the same verdict differently. The module
251
+ exposes **two** entry points, and they are **picked by shape, never by name**:
252
+
253
+ | Path | Entry point | Argument |
254
+ |------|-------------|----------|
255
+ | accept (`status=complete`) | `build_complete_envelope(<decision-log path>)` | no blocker list; `report=` / `deferred_work=` when those artifacts exist |
256
+ | reject (`status=blocked`) | `build_headless_envelope(<ordered blocker list>, <decision-log path>)` | the step-4 ordered blocker list |
257
+
258
+ `build_headless_envelope` reads like the general adapter and is not: it is the **blocked**
259
+ one, which is why it is also exported as `build_blocked_envelope` — the name to read for.
260
+ Handing it a complete-shaped mapping now raises `ValueError`; before it raised, it read no
261
+ blockers, *synthesised* one, appended that fabrication to `.decision-log.md`, and wrote a
262
+ `blocked` `run-result.json` over a successful run. That was observed in the field, which is
263
+ why the shape rule is stated here rather than left to inference.
264
+
265
+ **This entry point passes no `impl_artifacts`.** The parent passes it so the adapter also
266
+ pins the envelope to `{workflow.implementation_artifacts}/run-result.json`; a readiness
267
+ check is not a run, and writing that file here would overwrite an autonomous run's terminal
268
+ verdict with the result of a standalone question. Stdout is the sole output of
269
+ `/ucg-formalize`.
173
270
 
174
271
  On the accept path (`status=complete`, post-remediation verdict ready) emit all five
175
272
  keys:
@@ -179,7 +276,7 @@ keys:
179
276
  "skill": "ultracode-goal",
180
277
  "decision_log": "<path to this run's .decision-log.md>",
181
278
  "report": "<path to the readiness report, or null>",
182
- "deferred_work": "<path to the deferred-work ledger, or null>"}
279
+ "deferred_work": "<path to {workflow.deferred_work_path}, or null>"}
183
280
  ```
184
281
 
185
282
  On the reject path (`status=blocked`) emit the same five keys plus the conditional
@@ -202,11 +299,11 @@ blocked emit. Record the final verdict to
202
299
  ## Measurement protocol
203
300
 
204
301
  The kernel emits a self-measured `timing` block on every verdict carrying `wall_clock_ms`,
205
- `mechanical_ms`, `epic`, and `artifact_count`. This layer measures `end_to_end_ms` by bracketing the
206
- step-2 remediation loop and step-3 judgment read with two real monotonic clock reads (a one-line
207
- `python3 -c 'import time; print(time.monotonic_ns())'` before and after — measured, never authored),
208
- and appends one line (`epic`, `artifact_count`, `wall_clock_ms`, `mechanical_ms`, `end_to_end_ms`) to
209
- `.decision-log.md` on every verdict, reusing the existing decision-log channel.
302
+ `mechanical_ms`, `epic`, and `artifact_count`. Append those four values verbatim as one line to
303
+ `.decision-log.md` on every verdict, reusing the existing decision-log channel. They are the
304
+ only durations recorded: measured by the kernel in Python, copied here, never authored. This
305
+ layer times nothing itself — a duration the model derives by subtracting two clock reads it
306
+ carried across the remediation loop is authored arithmetic wearing a measurement's name.
210
307
 
211
308
  The wall-clock ceiling is declared-unknown: set only from a first real
212
309
  preflight-invoked run, never authored here. An over-budget formalize never blocks, escalates, or
@@ -33,8 +33,12 @@ more than a note-taker.
33
33
  - `{workflow.implementation_artifacts}` and `{workflow.deferred_work_path}` resolve from
34
34
  the parent module's `customize.toml` workflow block (the same scalars the autonomous
35
35
  run reads and writes).
36
- - The decision log (`.decision-log.md`) is canonical memory: record each answer and the
37
- disposition applied to it as you go.
36
+ - The decision log is canonical memory: record each answer and the disposition applied to
37
+ it as you go. It lives in the run's own folder,
38
+ `{project-root}/_bmad-output/ultracode-goal/<run folder>/.decision-log.md` — the module's
39
+ default runs root, which no `customize.toml` scalar carries. Write to the folder whose
40
+ Epic the enumerated artifacts belong to; ask the operator when more than one could be it,
41
+ and when none exists append nothing rather than create a stray log.
38
42
 
39
43
  ## On Activation
40
44
 
@@ -46,6 +50,14 @@ scalars before reading any artifact. Run `python3
46
50
  `{project-root}/_bmad/custom/ultracode-goal.toml` →
47
51
  `{project-root}/_bmad/custom/ultracode-goal.user.toml`, scalars override / arrays append).
48
52
 
53
+ That block also carries the module's three universal defaults, and this entry point takes
54
+ **one of them**: load `{workflow.persistent_facts}` — read-only context, and a cold session
55
+ is the one that most needs it. Do **not** execute `{workflow.activation_steps_prepend}` or
56
+ `{workflow.activation_steps_append}`: those are operator-configured actions belonging to the
57
+ autonomous run, and a standalone decide-surface stays side-effect-free apart from the answers
58
+ it is here to record. `ucg-formalize` and `ucg-status` state the same split, so the three
59
+ sub-skills agree on what the shared override file reaches.
60
+
49
61
  If a scalar cannot be resolved, do not pass an unresolved `{…}` token to a path: say
50
62
  which scalar failed and stop. A decision surface rooted at a path nobody resolved would
51
63
  enumerate some other run's pending work, or none at all, while looking exactly like a
@@ -53,6 +65,10 @@ real answer.
53
65
 
54
66
  ## 1. Enumerate the pending decisions
55
67
 
68
+ This surface applies answers and clears artifacts, so it is for a run that has **stopped**.
69
+ An operator who only wants to know what is pending gets that from the read-only
70
+ `/ucg-status`; begin this pass only when they are here to decide.
71
+
56
72
  Three sources, all on disk. Read these and nothing else — the run's transcript is gone,
57
73
  and anything not written down is not a pending decision this surface can honor.
58
74
 
@@ -68,48 +84,49 @@ and anything not written down is not a pending decision this surface can honor.
68
84
  3. **The deferred-work ledger** — `{workflow.deferred_work_path}`, restricted to its
69
85
  `decision:` rows. Those are the rows whose `source` column reads `decision` (as opposed
70
86
  to `gate` or `code-review`) **and** whose `status` is still `open`; a row already marked
71
- `resolved` is not a pending decision. The ledger is a markdown table per Epic, and the
72
- in-repo parser is table-only and fails soft — match that behavior: a malformed or
73
- bullet-list ledger yields no rows here, never a crash.
87
+ `resolved` is not a pending decision. The ledger is a markdown table per Epic: read
88
+ **every** table, not just the first (earlier runs' parked work sits under the earlier
89
+ headings), locate columns by header **name** rather than by position, and let a malformed
90
+ or bullet-list ledger yield no rows here rather than a crash — the same three properties
91
+ the in-repo reader has (`{ucg-root}/scripts/status_render.py`, `ledger_rows()`).
74
92
 
75
93
  **Every pending item is keyed by a stable `id`.**
76
94
 
77
95
  **For a preflight RED, read the `id` off the sidecar entry — never re-derive it.** Each
78
96
  entry in `.preflight-reds.json` carries its own minted `id`, written there by the preflight
79
- that found it (`{ucg-root}/references/preflight.md`, step 3). That stored value is the
80
- one the next preflight matches an answer against, so it is the only id that can close the
81
- loop — and because it is stored rather than recomputed, a RED a later scan re-detects
82
- **inherits its existing id** instead of arriving as something nobody has answered. That
83
- holds while the scan restates the decision unchanged; a reworded one is deliberately
84
- treated as a new decision and asked again, which is why an answer you record here is
85
- keyed to the wording the operator actually saw. Re-deriving your own from the entry's other fields would be guesswork against a
86
- recipe run by a different session: the moment your version and the stored one diverge, the
87
- `close` you record names an id no scan ever produces, the RED stands, and the run blocks
88
- forever on a question the operator already answered — while this surface, matching on its
89
- own self-consistent id, never offers it again.
97
+ that found it (`{ucg-root}/references/preflight.md`, step 3). The id is a pure function of
98
+ the decision — its `kind`, the bare artifact path, and a digest of the wording — so a RED a
99
+ later scan restates unchanged **inherits its existing id**, and the value on the entry is
100
+ the same one the next preflight derives for that finding; a reworded decision derives a new
101
+ id and is asked again. Re-deriving your own by hand would be guesswork against a recipe run
102
+ by a different session: the moment your version and the derived one diverge, the `close` you
103
+ record names an id no scan ever produces, the RED stands, and the run blocks forever on a
104
+ question the operator already answered.
90
105
 
91
106
  **For a typed escalation sidecar, ask the id layer for the id** — that file is hard-capped
92
- at four fields and cannot carry one, so it is the one case where an id is derived rather
93
- than read:
107
+ at four fields and cannot carry one, so its id is derived rather than read:
94
108
 
95
109
  ```
96
110
  uv run {ucg-root}/scripts/red_ids.py --mint-one <kind> <artifact path> <decision_needed>
97
111
  ```
98
112
 
99
- It prints the id and touches nothing. **Never derive an id by hand at either surface.** The
100
- id is the join key between this session and a preflight that ran days ago or will run days
101
- from now, and a value two model invocations have to agree on by hand is a value they will
102
- eventually disagree on. One implementation mints it; both surfaces read it.
113
+ It prints the id and touches nothing. **A ledger `decision:` row is keyed by the same
114
+ call** — kind `decision`, the ledger path, and the row's reason — because the row's own
115
+ `id` column is unique only within its Epic heading, so `d1` under one Epic and `d1` under
116
+ another would key to a single entry in a project-wide `.decisions.json` and one answer
117
+ would silently suppress a decision the operator was never shown.
118
+
119
+ **Never derive an id by hand at any of these surfaces.** The id is the join key between
120
+ this session and a preflight that ran days ago or will run days from now, and a value two
121
+ model invocations have to agree on by hand is a value they will eventually disagree on. One
122
+ implementation mints it; every surface reads it.
103
123
 
104
- Both forms keep **line numbers excluded**: the scan reports `source` as
124
+ Every minted form keeps **line numbers excluded**: the scan reports `source` as
105
125
  `<artifact path:line>`, and the id layer strips that `:line` suffix before deriving
106
- anything, so an id is never minted from the raw `source` value. A line-bearing id would
107
- evaporate the moment anyone edited above the finding, taking the operator's answer with it. The id also carries a
108
- digest of the decision itself, which is what keeps it unique: one artifact routinely carries
109
- several findings of the same `kind`, and on `kind` plus path alone they would collide, so
110
- answering one would clear every other decision sharing that id. At this surface that means
111
- an operator sees one question where two were pending, and the one they never saw silently
112
- stops blocking.
126
+ anything, so an id is never minted from the raw `source` value. Why the recipe is shaped
127
+ that way — including the digest that keeps two findings of the same `kind` in one artifact
128
+ apart — lives in `{ucg-root}/references/preflight.md`, step 3, and in
129
+ `{ucg-root}/scripts/red_ids.py`.
113
130
 
114
131
  ## 2. Walk them in one guided pass
115
132
 
@@ -140,10 +157,6 @@ Every answer lands in `{workflow.implementation_artifacts}/.decisions.json`:
140
157
  "action": "close|defer"}]}
141
158
  ```
142
159
 
143
- Three keys per entry — `id`, `answer`, `action` — and the action enum has exactly the two
144
- values shown. There is no third one to reach for; in particular, a re-presented `defer` is
145
- answered by **replacing** its entry, not by inventing a third action word for it.
146
-
147
160
  **Write the file read-modify-write, keyed by `id`.** Read any existing `.decisions.json`
148
161
  first, merge this pass's answers into its `decisions[]` — a new answer for an `id` already
149
162
  present replaces that entry, every other entry is preserved untouched — and write the whole
@@ -191,39 +204,54 @@ The two dispositions are genuinely different things, not two names for one:
191
204
  Stop event, before it has done a single turn of the work the operator just authorized, and
192
205
  the close would apply in name only. Answering a budget overrun by re-scoping, splitting,
193
206
  or handing off the story *is* the operator granting it a fresh budget, so the counter that
194
- recorded the exhausted one has no claim on the resumed run. This is the one artifact a
195
- `close` resets beyond the record that carried the decision.
207
+ recorded the exhausted one has no claim on the resumed run.
196
208
  - **`defer`** — the decision is not made yet. Record the entry **without clearing
197
209
  anything**. The artifact stays exactly where it is, the item stays pending, and the next
198
- preflight still blocks on it. A deferred answer clears nothing, which is what makes it
199
- honest: it parks a decision, it does not resolve one.
210
+ preflight still blocks on it.
200
211
 
201
212
  Record each answer and its disposition in `.decision-log.md` as you apply it.
202
213
 
203
214
  ## 4. Hand control back to the existing resume
204
215
 
205
- `/ucg-resolve` defines no resume of its own. Once the pass is done, hand back to the
206
- resume the module already has: **re-enter Execute at the first story whose last verdict is
207
- not advance**; advanced stories are not re-run; and **re-assert** — never rebuild — the
208
- Epic branch, both hooks, the allowlist, the `.mem-state.json` recall latch, and the
209
- in-flight story's baseline marker. The latch belongs on that list here more than anywhere:
210
- this skill is reached from a blocked run, whose Stage 6 already deleted it.
211
-
212
- That rule is not restated here in a second form. It already lives in the module's Execute
213
- reference and in the parent skill's Resume paragraph, and a second copy would become a
214
- second, divergent rule the first time one of them changed.
215
-
216
- There is no other re-entry point. It is not the first story of the Epic, and not the story
217
- the answered decision happened to name — either would re-run stories that already
218
- advanced, which is precisely what the shipped resume rule exists to prevent. The baseline
219
- marker in particular is **re-read, never regenerated**: the in-flight story may already
220
- carry commits, and a regenerated baseline silently re-anchors its evidence range to a
221
- mid-story HEAD.
216
+ `/ucg-resolve` defines no resume of its own. Close the pass by stating what closed, what is
217
+ still pending, and that anything still pending re-blocks at the next preflight. **Hand back
218
+ only when the pass closed at least one item, or when the operator asks for the resume**: a
219
+ pass that deferred everything hands into a run blocked on the identical items, and an empty
220
+ enumeration means the run stopped for a non-decision reason — say so, point at the read-only
221
+ `/ucg-status`, and hand nothing back.
222
+
223
+ Otherwise hand back to the resume the module already has, which **routes by the last stage
224
+ the blocked run reached**, not by story. Which branch applies is not a detail this surface
225
+ may skip, because the two arrive from different places:
226
+
227
+ - **Blocked at Stage 1 or Stage 2** — epic unresolved, or a preflight RED, which is the
228
+ arrival this skill's own trigger advertises. Re-run **from that stage**, so the hard
229
+ preflight gate is never skipped and the answered RED is consumed by the scan that
230
+ applies the override. Such a run blocked before any story, so it carries no gate
231
+ verdicts and there is no story to re-enter at.
232
+ - **The log carries gate verdicts** — re-enter Execute at the first story whose last
233
+ verdict is not advance; advanced stories are not re-run. Within that branch there is
234
+ no other re-entry point: it is not the first story of the Epic, and not the story the
235
+ 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.
237
+
238
+ Either branch **re-asserts** — never rebuilds — the Epic branch, both hooks, the
239
+ allowlist, the `.mem-state.json` recall latch, and the in-flight story's baseline marker.
240
+ The latch belongs on that list here more than anywhere: this skill is reached from a
241
+ blocked run, whose Stage 6 already deleted it. The baseline marker splits on whether
242
+ `.baseline-<story_id>` exists: mid-story it is **re-read, never regenerated** — the story
243
+ may already carry commits, and a regenerated baseline silently re-anchors its evidence
244
+ range to a mid-story HEAD — while at a story boundary there is none to re-read and one is
245
+ written fresh at `HEAD`, which is the half the Execute reference owns.
246
+
247
+ What this section pins is the routing branch and the re-assert set, nothing further. The
248
+ rule itself already lives in `{ucg-root}/references/execute.md`'s resume paragraph and in
249
+ the parent skill's Resume paragraph, which are loaded at hand-back time and carry the
250
+ current script call and both halves of that split. Where those two and this one ever
251
+ disagree, they are the owners and this is the stale copy.
222
252
 
223
253
  ## Scope
224
254
 
225
255
  This is a decide-surface, not a runner. It launches nothing itself: it reads artifacts,
226
256
  records answers, applies what a `close` resolves, and hands off. Like the read-only status
227
- view, it targets the **sequential spine** — under the experimental `--parallel` fan-out each
228
- worktree agent sees its own implementation-artifacts directory, so there is no single set of
229
- pending decisions for this to reconstruct.
257
+ view, it targets the **sequential spine**, which is the only execution path.