bmad-module-ultracode-goal 2.0.0 → 2.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 +5 -5
- package/docs/404.md +1 -1
- package/docs/_internal/STABILITY.md +13 -9
- package/docs/architecture.md +17 -12
- package/docs/comparison.md +19 -11
- package/docs/gate-model.md +24 -0
- package/docs/getting-started.md +1 -1
- package/docs/how-it-works.md +3 -3
- package/docs/index.md +0 -1
- package/docs/operating-tips.md +4 -2
- package/docs/troubleshooting.md +9 -5
- package/docs/why-ultracode-goal.md +1 -1
- package/package.json +5 -4
- package/skills/ucg-formalize/SKILL.md +136 -39
- package/skills/ucg-resolve/SKILL.md +86 -58
- package/skills/ucg-status/SKILL.md +64 -30
- package/skills/ultracode-goal/SKILL.md +9 -11
- package/skills/ultracode-goal/assets/module-help.csv +1 -1
- package/skills/ultracode-goal/assets/module.yaml +8 -3
- package/skills/ultracode-goal/assets/ucg-awareness/bmad-testarch-test-design.toml +8 -0
- package/skills/ultracode-goal/customize.toml +12 -7
- package/skills/ultracode-goal/references/define-done.md +3 -3
- package/skills/ultracode-goal/references/execute.md +40 -53
- package/skills/ultracode-goal/references/finalize.md +12 -12
- package/skills/ultracode-goal/references/gate.md +42 -11
- package/skills/ultracode-goal/references/health-check.md +7 -4
- package/skills/ultracode-goal/references/ingest-and-scope.md +4 -4
- package/skills/ultracode-goal/references/preflight.md +10 -9
- package/skills/ultracode-goal/scripts/gate_eval.py +684 -39
- package/skills/ultracode-goal/scripts/gate_trail.py +131 -32
- package/skills/ultracode-goal/scripts/health_check_fp.py +98 -3
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +56 -14
- package/skills/ultracode-goal/scripts/mem_observation.py +48 -10
- package/skills/ultracode-goal/scripts/mutate_check.py +353 -0
- package/skills/ultracode-goal/scripts/preflight_check.py +397 -3
- package/skills/ultracode-goal/scripts/status_render.py +20 -2
- package/skills/ultracode-goal/scripts/story_sizing.py +193 -0
- package/tools/build-docs.js +24 -1
- package/tools/validate-docs-links.js +169 -8
- package/website/astro.config.mjs +0 -1
- package/docs/parallel-mode.md +0 -68
- 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
|
|
15
|
-
|
|
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}
|
|
30
|
-
|
|
31
|
-
|
|
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
|
|
41
|
-
|
|
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
|
|
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
|
-
|
|
126
|
-
|
|
127
|
-
`
|
|
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.
|
|
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
|
-
| `
|
|
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
|
-
|
|
148
|
-
|
|
149
|
-
the
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
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
|
-
|
|
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
|
|
168
|
-
`{ucg-root}/
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
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
|
|
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`.
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
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
|
|
37
|
-
|
|
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
|
|
72
|
-
|
|
73
|
-
|
|
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).
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
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
|
|
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. **
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
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
|
-
|
|
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.
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
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.
|
|
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.
|
|
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.
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
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
|
|
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.
|