bmad-module-ultracode-goal 7.1.0 → 7.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +1 -1
- package/docs/_internal/STABILITY.md +1 -1
- package/docs/architecture.md +3 -2
- package/docs/gate-model.md +3 -1
- package/docs/health-check.md +108 -23
- package/docs/operating-tips.md +4 -0
- package/docs/troubleshooting.md +1 -1
- package/package.json +1 -1
- package/skills/ultracode-goal/SKILL.md +3 -5
- package/skills/ultracode-goal/customize.toml +52 -5
- package/skills/ultracode-goal/references/execute.md +3 -1
- package/skills/ultracode-goal/references/finalize.md +3 -3
- package/skills/ultracode-goal/references/gate.md +28 -16
- package/skills/ultracode-goal/references/health-check.md +125 -175
- package/skills/ultracode-goal/references/preflight.md +1 -1
- package/skills/ultracode-goal/scripts/carry_build_cache.py +435 -0
- package/skills/ultracode-goal/scripts/formalize_check.py +37 -21
- package/skills/ultracode-goal/scripts/health_check_fp.py +1240 -234
|
@@ -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": "7.
|
|
22
|
+
"version": "7.3.0",
|
|
23
23
|
"author": {
|
|
24
24
|
"name": "Armel"
|
|
25
25
|
},
|
|
@@ -20,7 +20,7 @@ The installer CLI is invoked via `npx bmad-module-ultracode-goal <subcommand>`.
|
|
|
20
20
|
|
|
21
21
|
### The `[workflow]` customize.toml keys
|
|
22
22
|
|
|
23
|
-
The keys in the shipped `[workflow]` block of `customize.toml` (including `persistent_facts`, `tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`, `epic_branch_prefix`, `protected_branches`, `max_turns_per_story`, `story_token_budget` (**deprecated, no-op**), `parallel_max_concurrency` (**deprecated, no-op**), `allowlist_commands`, `on_epic_complete`, `on_escalation`, `cross_session_recall`, `cross_session_recall_store`, and `graphify_integration`) are the supported override surface. Teams and users override them in `_bmad/custom/ultracode-goal.toml` (and `.user.toml`) with base → team → user resolution (scalars override, tables deep-merge, arrays append). Renaming or removing a key, or changing how it resolves, is a contract change. See [architecture](../architecture.md).
|
|
23
|
+
The keys in the shipped `[workflow]` block of `customize.toml` (including `persistent_facts`, `tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`, `epic_branch_prefix`, `protected_branches`, `max_turns_per_story`, `story_token_budget` (**deprecated, no-op**), `parallel_max_concurrency` (**deprecated, no-op**), `allowlist_commands`, `backfill_sweep`, `on_epic_complete`, `on_escalation`, `cross_session_recall`, `cross_session_recall_store`, and `graphify_integration`) are the supported override surface. Teams and users override them in `_bmad/custom/ultracode-goal.toml` (and `.user.toml`) with base → team → user resolution (scalars override, tables deep-merge, arrays append). Renaming or removing a key, or changing how it resolves, is a contract change. See [architecture](../architecture.md).
|
|
24
24
|
|
|
25
25
|
`story_token_budget` is **deprecated** as of the deprecation note in `CHANGELOG.md`: it is still shipped, still accepted, and still resolves, so existing overrides keep working and nothing errors. It is a no-op; no layer reads it any more. The runaway bound is turns only, via `max_turns_per_story`. The key stays enumerated here (and stays in `customize.toml`) precisely because removing it would be the contract break this section forbids.
|
|
26
26
|
|
package/docs/architecture.md
CHANGED
|
@@ -61,6 +61,7 @@ skills/ultracode-goal/
|
|
|
61
61
|
│ ├── mutate_check.py # mutation harness: attributable-red proof for the story's guards
|
|
62
62
|
│ ├── probe_servers.py # which URLs a test runner may reuse already answer, from which folder; stops a server the run left up
|
|
63
63
|
│ ├── link_worktree_deps.py # links the main tree's dependency folders into the gate worktree
|
|
64
|
+
│ ├── carry_build_cache.py # carries the gate worktree's build folders aside across its rebuild
|
|
64
65
|
│ ├── gate_trail.py # per-story evidence trail (gate-trail.md) at finalize
|
|
65
66
|
│ ├── formalize_check.py # readiness kernel behind the /ucg-formalize gate
|
|
66
67
|
│ ├── status_render.py # read-side render behind /ucg-status
|
|
@@ -69,7 +70,7 @@ skills/ultracode-goal/
|
|
|
69
70
|
│ ├── claim_check.py # pre-commit: paths a message names that the staged diff skips
|
|
70
71
|
│ ├── drive_epic.py # one `claude -p` per story (--max-stories work bound)
|
|
71
72
|
│ ├── headless_envelope.py # the one five-key headless-envelope adapter
|
|
72
|
-
│ ├── health_check_fp.py # health-check fingerprint
|
|
73
|
+
│ ├── health_check_fp.py # health-check fingerprint, seen-cache and queue plumbing
|
|
73
74
|
│ ├── mem_observation.py # Cross-Session Recall write path (write/drain)
|
|
74
75
|
│ ├── mem_recall.py # Cross-Session Recall latch and read path (latch/filter/unlatch)
|
|
75
76
|
│ ├── merge_config.py # install-time config merge into shared _bmad
|
|
@@ -109,7 +110,7 @@ Configuration resolves in three layers, base → team → user, via `resolve_cus
|
|
|
109
110
|
|
|
110
111
|
Neither override file is created by any installer, and a missing one is not an error: the resolver loads it non-required and treats absence as an empty table, so a fresh project resolves the base layer alone. You create them when you first need to override something. Do not mistake them for the `config.toml` and `config.user.toml` already sitting in that directory: those are BMAD's own configuration, and a UCG knob written there resolves to nothing.
|
|
111
112
|
|
|
112
|
-
Merge semantics: **scalars override**, **tables deep-merge**, **arrays append**. At activation the skill runs `resolve_customization.py --skill {skill-root} --key workflow`; if that fails, it resolves the three files itself in the same order. The shipped base layer defines the run's knobs: the TEA/artifact paths (`tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`), the git guardrails (`epic_branch_prefix`, `protected_branches`), the turn budget (`max_turns_per_story`; `story_token_budget` remains as a deprecated no-op key), `parallel_max_concurrency` (deprecated no-op since the `--parallel` retirement), the `allowlist_commands`, the two lifecycle hooks (`on_epic_complete`, `on_escalation`), the [health check](./health-check.md) family (`health_check_repo`, `health_check_seen_cache`, `health_check_queue_path`, `health_check_autosubmit`), and the two optional integrations, both off by default: [`cross_session_recall`](./cross-session-recall.md) with its store folder `cross_session_recall_store`, and the third-party [`graphify_integration`](./knowledge-graph-refresh.md). Teams and users override without editing the shipped file. Remember that a budget or branch override only reaches the *enforcement* layer because preflight threads it into the hook env (see layer 2 above).
|
|
113
|
+
Merge semantics: **scalars override**, **tables deep-merge**, **arrays append**. At activation the skill runs `resolve_customization.py --skill {skill-root} --key workflow`; if that fails, it resolves the three files itself in the same order. The shipped base layer defines the run's knobs: the TEA/artifact paths (`tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`), the git guardrails (`epic_branch_prefix`, `protected_branches`), the turn budget (`max_turns_per_story`; `story_token_budget` remains as a deprecated no-op key), `parallel_max_concurrency` (deprecated no-op since the `--parallel` retirement), the `allowlist_commands`, the opt-in `backfill_sweep` (the gate's sweep before it commits a backfilled test, `full` by default), the two lifecycle hooks (`on_epic_complete`, `on_escalation`), the [health check](./health-check.md) family (`health_check_repo`, `health_check_seen_cache`, `health_check_queue_path`, `health_check_autosubmit`), and the two optional integrations, both off by default: [`cross_session_recall`](./cross-session-recall.md) with its store folder `cross_session_recall_store`, and the third-party [`graphify_integration`](./knowledge-graph-refresh.md). Teams and users override without editing the shipped file. Remember that a budget or branch override only reaches the *enforcement* layer because preflight threads it into the hook env (see layer 2 above).
|
|
113
114
|
|
|
114
115
|
The three TOML layers merge once, but a branch or budget value then travels two ways: the conductor reads it directly, while the hooks only see it if preflight re-injects it as env:
|
|
115
116
|
|
package/docs/gate-model.md
CHANGED
|
@@ -94,6 +94,8 @@ Under `--profile light` none of this applies: the trace gate is the whole decisi
|
|
|
94
94
|
|
|
95
95
|
Independent of profile, a per-story gate is also handed the story's `.tests-ran-<story_id>` marker via `--tests-ran`. Execute writes a `scope=<full|scoped>` line into that marker beside `baseline=`, naming which sweep form the green run behind this gate was: the full three-axis sweep, or a re-loop iteration's affected-set sweep (changed packages plus their dependents, still cache-defeated, with the resolved package list printed and recorded on a `packages=` line). The script reads the line and applies one rule: **a story only moves forward off a full-scope sweep.** `scope=full` passes the verdict through; `scope=scoped` caps `advance` at `reloop`, and caps `defer` too, because defer's route advances the story after parking its concerns. A missing marker, a marker with no `scope=` line, or an unrecognised value gets the same cap, fail-closed, with a reason naming what was wrong.
|
|
96
96
|
|
|
97
|
+
The gate writes the marker too, when it commits a test `bmad-testarch-automate` backfilled, always with `scope=full`. By default its sweep before that commit is the full three-axis sweep. With the opt-in `backfill_sweep = "scoped"` in `customize.toml`, a backfill that stages test files alone, on a story whose full step-5 sweep went green at the commit the backfill builds on, re-runs only the checks of the packages that hold those files and every check that reads files across packages or git's file list, unless that check's own declared inputs exclude every staged path, and prints each check it leaves out. Its marker then keeps `scope=full` beside a `sweep=` line naming the two green captures it rests on, which the script does not read, and one scoped sweep never builds on another.
|
|
98
|
+
|
|
97
99
|
Two boundaries:
|
|
98
100
|
|
|
99
101
|
- `--epic-level` refuses `--tests-ran` outright (an invocation error, exit 2): the epic roll-up gates no sweep of its own, since every story proved its own scope before reaching `done`.
|
|
@@ -103,7 +105,7 @@ The verdict JSON carries the recognised value as `sweep_scope` (or `null`), so a
|
|
|
103
105
|
|
|
104
106
|
## The delta cycle profile
|
|
105
107
|
|
|
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.
|
|
108
|
+
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. A test that reads the code's source text instead of executing it, where no test runner can execute that code, measures only its spelling: the behaviour stays an `unmeasured` gap naming the test and what could execute the code, and no test that reads source text closes it. `--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.
|
|
107
109
|
|
|
108
110
|
## The thresholds
|
|
109
111
|
|
package/docs/health-check.md
CHANGED
|
@@ -7,7 +7,7 @@ Every UltraCode Goal run that reaches Finalize ends with a health check: a brief
|
|
|
7
7
|
|
|
8
8
|
## What it is, and when it runs
|
|
9
9
|
|
|
10
|
-
The health check is a reflection step that runs **after every run that reaches Finalize**: a completed Epic, or one that ended in a story escalation. It does **not** run on an early block
|
|
10
|
+
The health check is a reflection step that runs **after every run that reaches Finalize**: a completed Epic, or one that ended in a story escalation. It does **not** run on an early block, a Stage 1 or Stage 2 stop: the next run of that Epic that reaches Finalize, if one does, reports the friction the blocked run logged. As it goes, a run logs each instruction that was unclear, contradictory or silent on its case as a `friction:` line in its decision log; every health check, however it ends, logs one `health-check:` line, and reports the `friction:` lines logged after the last one. So a health check that never finished has its friction reported by the next one too. To report a run's friction now, without waiting for a later run, ask the conductor to run the health check for that run: it reads that run folder's `.decision-log.md`, with no other stage, and reports from the log's `friction:` lines alone. Findings are graded into three severities: `bug`, `friction`, and `gap`.
|
|
11
11
|
|
|
12
12
|
## Exactly what gets sent
|
|
13
13
|
|
|
@@ -25,22 +25,28 @@ Explicitly **not** sent: no source code, no Epic content, no secrets. The eviden
|
|
|
25
25
|
|
|
26
26
|
## Privacy
|
|
27
27
|
|
|
28
|
-
Issues are filed
|
|
28
|
+
Issues are filed on the configured `health_check_repo` with your own GitHub account, and on the default, `armelhbobdad/bmad-module-ultracode-goal`, they are public. On an **attended** run nothing is sent silently: the health check first drafts each finding's issue body in the run folder, then always **HALTS at a `[Y]` / `[A]` / `[N]` / `[E]` / `[Q]` gate** that shows each finding's title and its full body and asks "Submit these findings as issues on `<health_check_repo>`, filed with your GitHub account?", saying public issues on the default and, for any other repository, that they are public if it is. Yes files the `bug` findings and keeps the `friction` and `gap` ones on disk, all files every finding, no skips them, edit revises the drafts first, and queue keeps every finding on disk and sends nothing. A finding about the health check itself (stage `health-check`) is queued, never posted, whatever you choose but no. What you approve is what is sent, except for these changes after the gate: when the defect was fixed before, a line linking to that fix opens the body, and a confirmed regression's title gains `REGRESSION: `; when you choose to file anyway at an open issue with the same fingerprint, the finding takes a more specific defect key, which rewrites its Fingerprint and Defect Key; and when you choose to comment on a matching issue, the comment is written then and shown to you before it is posted.
|
|
29
29
|
|
|
30
|
-
The boundary below shows the disable path, everything computed on your machine, and the
|
|
30
|
+
The boundary below shows the disable path, everything computed on your machine, and the three points where anything crosses to GitHub, all behind a gate: the seen-cache check, which reads the state of an issue already recorded on this machine and sends only that issue's URL, the dedup search, and the issue itself:
|
|
31
31
|
|
|
32
32
|
```mermaid
|
|
33
33
|
flowchart TD
|
|
34
34
|
Start["Reaches Finalize"] --> Enabled{"health_check_repo set"}
|
|
35
|
-
Enabled -->|"empty"| Off["Log
|
|
36
|
-
Enabled -->|"set"| Reflect["
|
|
35
|
+
Enabled -->|"empty"| Off["Log the disabled marker and exit. Nothing computed, nothing sent"]
|
|
36
|
+
Enabled -->|"set"| Reflect["Read the friction logged since the last marker, reflect on this run. Grade bug, friction, gap"]
|
|
37
37
|
Reflect --> Clean{"Any findings"}
|
|
38
|
-
Clean -->|"no"| Done["Clean run.
|
|
39
|
-
Clean -->|"yes"|
|
|
40
|
-
|
|
41
|
-
Gate -->|"
|
|
38
|
+
Clean -->|"no"| Done["Clean run. Log the clean marker and exit"]
|
|
39
|
+
Clean -->|"yes"| Draft["Fingerprint each finding and draft its issue body"]
|
|
40
|
+
Draft --> Gate{"Your answer at the gate"}
|
|
41
|
+
Gate -->|"N"| Discard["Discard the findings. Log the discarded marker"]
|
|
42
|
+
Gate -->|"Q, or Y for friction and gap"| Queue["Write finding to local queue. Stays on disk"]
|
|
43
|
+
Gate -->|"Y for bug, or A"| Fp["Check seen-cache"]
|
|
42
44
|
Fp --> Search["Remote dedup search on GitHub"]
|
|
43
|
-
|
|
45
|
+
Fp -->|"record holds an issue URL"| State["Read that issue's state on GitHub. Sends only its URL"]
|
|
46
|
+
State --> Search
|
|
47
|
+
Search --> Create["Create or react on an issue on health_check_repo"]
|
|
48
|
+
Queue --> Close["Log the done marker with its counts"]
|
|
49
|
+
Create --> Close
|
|
44
50
|
|
|
45
51
|
subgraph local["On your machine"]
|
|
46
52
|
Enabled
|
|
@@ -48,11 +54,15 @@ flowchart TD
|
|
|
48
54
|
Reflect
|
|
49
55
|
Clean
|
|
50
56
|
Done
|
|
57
|
+
Draft
|
|
51
58
|
Gate
|
|
59
|
+
Discard
|
|
52
60
|
Queue
|
|
53
61
|
Fp
|
|
62
|
+
Close
|
|
54
63
|
end
|
|
55
64
|
subgraph net["Leaves the machine"]
|
|
65
|
+
State
|
|
56
66
|
Search
|
|
57
67
|
Create
|
|
58
68
|
end
|
|
@@ -63,16 +73,48 @@ flowchart TD
|
|
|
63
73
|
class Create verdict
|
|
64
74
|
```
|
|
65
75
|
|
|
66
|
-
The gate that admits anything to the right of the boundary is the `[Y]` approval on an attended run, or the autosubmit opt-in restricted to `bug`-severity findings on a headless run
|
|
76
|
+
The gate that admits anything to the right of the boundary is the `[Y]` or `[A]` approval on an attended run, or the autosubmit opt-in restricted to `bug`-severity findings on a headless run.
|
|
67
77
|
|
|
68
78
|
## Unattended behavior
|
|
69
79
|
|
|
70
|
-
Headless runs do not have a human at the gate, so by default they **queue findings locally and never live-submit**. Two config knobs
|
|
80
|
+
Headless runs do not have a human at the gate, so by default they **queue findings locally and never live-submit**. Two config knobs change this:
|
|
71
81
|
|
|
72
|
-
- `health_check_repo = ""`: disables the health check entirely (the target repo doubles as the on/off switch; no target, nothing to run).
|
|
73
|
-
- `health_check_autosubmit = true`: opts **bug-severity** findings into live submission on unattended runs. `friction` and `gap` findings are **never** auto-submitted; they always queue regardless of this setting.
|
|
82
|
+
- `health_check_repo = ""`: disables the health check entirely (the target repo doubles as the on/off switch; no target, nothing to run). Each run it skips still logs its `disabled` marker, which closes the `friction:` entries logged so far: turning the check back on reports only friction logged after that. Finalize lists those entries in the run's addendum first, so they are still on record.
|
|
83
|
+
- `health_check_autosubmit = true`: opts **bug-severity** findings into live submission on unattended runs. `friction` and `gap` findings are **never** auto-submitted; they always queue regardless of this setting, as does a finding about the health check itself.
|
|
74
84
|
|
|
75
|
-
|
|
85
|
+
Set them in your project's `_bmad/custom/ultracode-goal.toml`, or for yourself alone in `ultracode-goal.user.toml` beside it, under the `[workflow]` table header. To turn the health check off:
|
|
86
|
+
|
|
87
|
+
```toml
|
|
88
|
+
[workflow]
|
|
89
|
+
# Health check off: no target repository, nothing to run.
|
|
90
|
+
health_check_repo = ""
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
The `[workflow]` table header matters: the resolver extracts the `workflow` block from the merged files, so a bare top-level line is silently discarded and the knob keeps its default.
|
|
94
|
+
|
|
95
|
+
**To send findings to another repository**, set `health_check_repo` to it under the same header (`OWNER/REPO`, or `HOST/OWNER/REPO` on a host other than github.com), and set that repository up as the default one is: create the labels `health-check`, `workflow-improvement`, `bug`, `friction`, `gap`, `duplicate` and `possible-duplicate` there, and copy two files into it unchanged, the issue template [`.github/ISSUE_TEMPLATE/workflow-health-check.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/.github/ISSUE_TEMPLATE/workflow-health-check.md) and the dedup Action [`.github/workflows/health-check-dedup.yaml`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/.github/workflows/health-check-dedup.yaml), which reads its repository from the run. Without the labels the first create fails and the retry files the issue unlabeled; without the Action nothing labels it or closes a duplicate. Set the project's own `health_check_seen_cache` too: the cache keys each record by fingerprint alone, so two projects that share it and file to different repositories would block or overwrite each other's records.
|
|
96
|
+
|
|
97
|
+
**To let autosubmit post unattended**, allow the four `gh` commands a submission runs. Without an allow rule, each is left to Claude Code's permission check: under Auto Mode the classifier decides whether it runs, and in a mode that asks first, such as `drive_epic.py`'s default `acceptEdits`, nobody is there to answer, so the call is refused and the finding is queued with a reason that says a `gh` call was refused. Add them to `allowlist_commands` under the same `[workflow]` header, not a second one: TOML refuses a table declared twice, and the resolver then rejects the whole file. Arrays append to the shipped list, and preflight writes each entry as an allow rule in `.claude/settings.local.json`. The whole file then reads:
|
|
98
|
+
|
|
99
|
+
```toml
|
|
100
|
+
[workflow]
|
|
101
|
+
health_check_autosubmit = true
|
|
102
|
+
allowlist_commands = ["gh auth status", "gh search issues", "gh label create", "gh issue create"]
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
These rules outlast the run: they stay in `.claude/settings.local.json` and apply to every later session in the project, so any agent working there can then create issues and labels on any repository without asking. To keep the three that take a repository to the health-check repository, scope them with it. Every `gh` command the health check runs puts `--repo` right after its subcommand, so the narrower rules still match:
|
|
106
|
+
|
|
107
|
+
```toml
|
|
108
|
+
[workflow]
|
|
109
|
+
health_check_autosubmit = true
|
|
110
|
+
allowlist_commands = ["gh auth status", "gh search issues --repo <health_check_repo>", "gh label create --repo <health_check_repo>", "gh issue create --repo <health_check_repo>"]
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
When you turn autosubmit off, remove the entries, then delete the rules preflight wrote for them, such as `Bash(gh issue create:*)`, from `.claude/settings.local.json` yourself: preflight only adds rules.
|
|
114
|
+
|
|
115
|
+
The local queue lives at the configured `health_check_queue_path` (by default `{project-root}/_bmad-output/ultracode-goal/improvement-queue/`), which is created when it is missing. `health_check_fp.py queue` writes each finding there as one file, named `hc-ultracode-goal-{stage}-{YYYYMMDD-HHmmss}.md` from the UTC time, and holding the finding's issue body exactly as it was drafted, with no frontmatter. When two findings of one stage are written in the same second, the later names get `-2`, `-3` and so on before `.md`, so no file is overwritten. Whatever the reason a finding stays local (the `[Q]` choice, a headless run, a friction or gap finding, a finding about the health check itself, no GitHub CLI, a refused `gh` call, a skipped or failed submission), the health check lists each file it wrote with one sentence giving the reason and the commands that submit it, which `health_check_fp.py queue` prints with every argument quoted: on screen in an attended run, in the log in a headless one.
|
|
116
|
+
|
|
117
|
+
A headless run with `health_check_autosubmit = true` that finds an open issue matching a bug finding has nobody to choose between upvoting, commenting and filing anyway, so it takes the skip choice: the finding is queued with the match as its reason, and nothing is posted.
|
|
76
118
|
|
|
77
119
|
## Deduplication
|
|
78
120
|
|
|
@@ -80,23 +122,66 @@ Findings are deduped by a deterministic fingerprint so the same defect does not
|
|
|
80
122
|
|
|
81
123
|
```
|
|
82
124
|
fp-XXXXXXX = "fp-" + sha1("{severity}|ultracode-goal/{stage}|"
|
|
83
|
-
"skills/ultracode-goal/references/{stage}.md|
|
|
125
|
+
"skills/ultracode-goal/references/{stage}.md|"
|
|
126
|
+
"{section-slug}|{defect-key}")[:7]
|
|
84
127
|
```
|
|
85
128
|
|
|
86
|
-
The `step_file` component is always the source-repo form `skills/ultracode-goal/references/{stage}.md` regardless of where the skill is installed, so the same defect dedups to the same key across a dev checkout and an installed `_bmad/` tree. `severity` is one of `bug`/`friction`/`gap`; `stage` is one of the six stage names (`ingest-and-scope`, `preflight`, `define-done`, `execute`, `gate`, `finalize`)
|
|
129
|
+
The `step_file` component is always the source-repo form `skills/ultracode-goal/references/{stage}.md` regardless of where the skill is installed, so the same defect dedups to the same key across a dev checkout and an installed `_bmad/` tree. `severity` is one of `bug`/`friction`/`gap`; `stage` is one of the six stage names (`ingest-and-scope`, `preflight`, `define-done`, `execute`, `gate`, `finalize`), or `health-check` for a defect in the health check's own instructions or in a script or command it runs, which is never posted: it goes to the local queue unless you discard it, so the run's last step never files a report about itself, which a defect in that filing would call for again.
|
|
130
|
+
|
|
131
|
+
`section-slug` comes from the heading of the section where the issue occurred. The script checks that the heading is one of that stage file's own, then:
|
|
132
|
+
|
|
133
|
+
1. drops its leading `#`s;
|
|
134
|
+
2. folds it: NFKD, the Unicode compatibility decomposition, then no combining mark, so an accented letter gives its base letter and a ligature, a superscript or a full-width form gives its plain characters (a letter NFKD cannot split, such as `ß`, `ø`, `ł`, `æ`, `œ` or `ı`, stays as it is);
|
|
135
|
+
3. drops its numbering (`1b.`, `5a-ii.`, `4-headless.`);
|
|
136
|
+
4. lower-cases it and turns each run of characters that are not ASCII letters or digits into a hyphen.
|
|
137
|
+
|
|
138
|
+
So `1b. Run the formalize readiness check` gives `run-the-formalize-readiness-check`, `Résumé du run` gives `resume-du-run`, `Phase ² final` gives `phase-2-final`, `1. Run the gate` gives `run-the-gate` and `Straße` gives `stra-e`.
|
|
139
|
+
|
|
140
|
+
The `defect-key` is one to four kebab-case words naming the thing the fix would change, in the stage reference's or the script's own words. The script derives it from that name:
|
|
141
|
+
|
|
142
|
+
1. folds it as the slug's;
|
|
143
|
+
2. trims from both ends, in any layering, the whitespace and the edge characters: backticks, straight and curly quotes, `*`, the brackets `()[]{}<>`, `.`, `,`, `;`, `!` and `?`;
|
|
144
|
+
3. keeps the last path component (after `/` or `\`);
|
|
145
|
+
4. drops a trailing location: a `:N`, then up to two more `-N` or `:N`, then an optional `:` or `-` (`:42`, `:42-50`, `:42:7:`, `:42:7-12`); a lone `:`; or a GitHub anchor, which is an optional `?plain=1`, then `#L42`, an optional column `C7` and an optional range `-L50`, `-L50C3` or `-50` (`#L42`, `#L42-L50`, `#L42C7-L50C3`, `?plain=1#L42`);
|
|
146
|
+
5. trims the whitespace and the edge characters again, and repeats steps 4 and 5 until the name stops changing;
|
|
147
|
+
6. drops a known file extension, then leading dashes and underscores;
|
|
148
|
+
7. splits the rest into words at whitespace, `_`, `-`, `.` and each lower-case letter followed by an upper-case one;
|
|
149
|
+
8. drops every character that is not an ASCII letter or digit, a letter NFKD cannot split included;
|
|
150
|
+
9. lower-cases the words and keeps the last four.
|
|
151
|
+
|
|
152
|
+
For example, `gate_status` gives `gate-status`; `` `scripts/gate_eval.py:42:7` ``, `` `gate_eval.py`:42 ``, `` **`gate_eval.py`** ``, `“gate_eval.py”`, `(gate_eval.py)`, `gate_eval.py:42:7:`, `gate_eval.py#L42C7-L50C3` and `` `gate_eval.py:42`: `` all give `gate-eval`, and `gate.md?plain=1#L42` gives `gate`; `composeStories` gives `compose-stories`, `HTTP2Client` gives `http2client`, `ÉtatMachine` gives `etat-machine`, `fileLoader` gives `file-loader` and `Straße` gives `strae`. A name with no ASCII letter or digit left, one written in another alphabet included, yields no word, and the script refuses it. So two different defects in one section get two fingerprints, while two reports of one defect that name the same thing get one.
|
|
153
|
+
|
|
154
|
+
The same hash without `|{defect-key}` is the **section fingerprint**, which every defect of one severity in one section shares. Versions before the defect key used it as the fingerprint, so issues and seen-cache records made by them carry it, and every issue filed now records it in a `` Section fingerprint: `fp-XXXXXXX` `` line of its body. A match on it is only ever a possible match: it never suppresses a finding, and it never closes an issue. Since the script derives the section slug from the heading, the section fingerprint of a defect differs from the fingerprint an issue or a seen-cache record made by version 7.1.0 or earlier carries wherever the slug chosen then differed from the real heading's, as it mostly did. Such an issue then no longer turns up in the section-fingerprint search or the dedup Action's possible-duplicate flag, and a recurrence of its defect is filed without its "Possibly a regression of" line; nothing is silenced, since such a record never suppresses a finding.
|
|
87
155
|
|
|
88
156
|
Dedup runs at three levels:
|
|
89
157
|
|
|
90
|
-
1. **Machine-global seen-cache** at the configured `health_check_seen_cache` (by default `~/.ultracode-goal/health-check-seen.json`)
|
|
91
|
-
2. **Remote search**: before filing, the
|
|
92
|
-
3. **Server-side**: a repository Action closes duplicates and upvotes the canonical issue, so even a race between two machines converges on one issue.
|
|
158
|
+
1. **Machine-global seen-cache** at the configured `health_check_seen_cache` (by default `~/.ultracode-goal/health-check-seen.json`). The `seen` subcommand reads it into a verdict, and `record` merge-writes one record under a lock on `health-check-seen.json.lock`, through a synced temporary file renamed over the cache, so parallel runs keep each other's records. A missing or empty cache is an empty one; a cache that does not parse is renamed to `health-check-seen.json.corrupt-<UTC time>` rather than erased, so its records can be repaired by hand. Each record carries the issue URL, the action taken (`created` / `reacted` / `commented` / `resolved`), and the date. `seen` is given the configured `health_check_repo` and reads a record of an issue on another repository as no record, so that record neither suppresses a finding nor links its body to that issue; `record` still keys the cache by fingerprint alone, so a project that files to another repository sets its own `health_check_seen_cache`. Only a record tied to a real issue is written: a finding that stays in the local queue records nothing, so a bug a headless run queued is still filed when a later attended run approves it. `created`, `reacted` and `commented` suppress a later sighting of the same fingerprint. `resolved` records that a finding was fixed, and deliberately does **not** suppress: a fresh sighting of a fixed defect is a regression rather than a duplicate, so it is reported and linked back to the original, and `record` never replaces a `resolved` record unless the issue it records tracks that regression. An unrecognized action (an old `queued` record included) does not suppress either, on the same reasoning: a duplicate report is closed automatically, whereas a silenced regression is caught by nothing. A record found only under the section fingerprint never suppresses, and a fix it records is reported as a *possible* regression. The cache is machine-local, so where a record carries a real issue URL the shared source of truth is that issue's own state, which `seen` reads itself (with `gh`, never one found in the current folder, stopped after 10 seconds) in preference to the local record. Only a *completed* close, or a merged pull request, counts as a fix there: an issue closed as *not planned* keeps the local verdict, because that is how the dedup Action closes a duplicate and how a wontfix is closed, and neither is a fix.
|
|
159
|
+
2. **Remote search**: before filing, the open issues are searched for the fingerprint, so a finding already filed by another machine is not duplicated. When none carries it, a second search for the section fingerprint offers each issue it finds as a possible match, which only you can confirm.
|
|
160
|
+
3. **Server-side**: a repository Action closes duplicates and upvotes the canonical issue, so even a race between two machines converges on one issue. It reads each issue as it is now and runs once at a time per issue, and it closes an issue only in favour of an earlier open one, so two reports filed together never close each other. When a new issue shares only its section fingerprint with an earlier open one, under a different defect key, the Action comments with a link to each and adds the `possible-duplicate` label, and leaves the issue open for a maintainer to decide. GitHub keeps none of the labels a reporter without push access to the repository passes through `gh` or the API, so the Action labels a report that has no `fp-*` label first: it reads the fingerprint and severity from the title, or else from the body's Fingerprint and Severity sections, creates the `fp-*` label and adds each of `health-check`, `workflow-improvement`, the severity and the `fp-*` label the issue lacks, then dedups it like any other. A report that names no fingerprint there is left as it is. The Action reads label names, the fingerprint and the `Section fingerprint:` line in any letter case, and uses a fingerprint in lower case: an issue labeled `FP-ABC1234` is deduped as one labeled `fp-abc1234`. One limit: two reports of one fingerprint, both filed without labels at the same moment, can both stay open, since the later one's run can search before the earlier one's run has labeled it.
|
|
93
161
|
|
|
94
162
|
## Submitting a queued finding manually
|
|
95
163
|
|
|
96
|
-
A queued finding
|
|
164
|
+
A queued finding is a file under the queue directory holding the finding's issue body, exactly as the health check drafted it and, on an attended run, as the gate showed it: its Workflow, Step File, Section, Severity, Fingerprint and `Section fingerprint:` line, Defect Key, the `file:line` evidence and the Environment table. Submit one when you are ready with the commands the health check printed for it, whose title `health_check_fp.py fingerprint` built from the finding's severity, fingerprint, stage and short description: the first two, the label create and the issue create, or, without push access to the repository, the third alone, the issue create without labels. `health_check_fp.py queue` quotes every argument for a POSIX shell (bash, zsh, Git Bash or WSL), so they paste there as printed, a path with a space included. Filled in by hand, they take their values from the file's sections, and the short description is yours to write, with no backtick, `$`, double quote, backslash, `!`, tab, line break or other character that is not printable, since the title goes on the command line, and with the whole title at most 256 characters long. A queue file written by an earlier version opens with YAML frontmatter between two `---` lines: delete it before you pass the file to `--body-file`.
|
|
97
165
|
|
|
98
166
|
```bash
|
|
99
|
-
gh
|
|
167
|
+
gh label create --repo <health-check-repo> "<fingerprint>" --color "ededed" \
|
|
168
|
+
--description "Health-check fingerprint dedup key"
|
|
169
|
+
gh issue create --repo <health-check-repo> \
|
|
170
|
+
--title "[health-check][<severity>][<fingerprint>] ultracode-goal/<stage>: <short description>" \
|
|
171
|
+
--label "health-check,workflow-improvement,<severity>,<fingerprint>" \
|
|
172
|
+
--body-file <path-to-queued-finding>
|
|
100
173
|
```
|
|
101
174
|
|
|
102
|
-
Nothing is sent until you run
|
|
175
|
+
Keep the full title: the dedup Action reads the fingerprint and severity from it when the issue has no `fp-*` label, and the next reporter's search looks for the fingerprint in titles. A failed `gh label create`, when the label exists already, is no error: run the create anyway. Without push access to the repository you can neither create a label nor set one, so drop the `gh label create` command and the `--label` line: the dedup Action adds the labels from the title. Nothing is sent until you run these commands. Afterwards, record the new issue with the URL `gh issue create` printed, so this machine does not report the finding again while that issue stays open (`<skill-root>` is the installed `ultracode-goal` skill folder, and `<health_check_seen_cache>` the configured `health_check_seen_cache`, by default `~/.ultracode-goal/health-check-seen.json`):
|
|
176
|
+
|
|
177
|
+
```bash
|
|
178
|
+
uv run <skill-root>/scripts/health_check_fp.py record \
|
|
179
|
+
--fp <fingerprint> --cache <health_check_seen_cache> \
|
|
180
|
+
--issue-url "<the new issue URL>" --action created --date YYYY-MM-DD
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
When the body opens with "Regression of", add `--regression`: the new issue tracks the recurrence, so it replaces the `resolved` record the fix left.
|
|
184
|
+
|
|
185
|
+
Then retire the queue file: delete it, or move it into a `resolved/` subfolder of the queue directory.
|
|
186
|
+
|
|
187
|
+
You can also open one through the issue chooser of `<health-check-repo>`, `https://github.com/<health-check-repo>/issues/new/choose` (on the default, <https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/new/choose>). An issue filed that way keeps the template's `health-check` and `workflow-improvement` labels and lacks only the `fp-*` and severity ones, so replace its sections from Workflow through Defect Key with the `body_header` that the `health_check_fp.py fingerprint` command in the template's comments prints: the dedup Action adds those two labels from its Fingerprint and Severity, and leaves an issue whose Fingerprint still holds the `fp-XXXXXXX` placeholder as it is.
|
package/docs/operating-tips.md
CHANGED
|
@@ -177,4 +177,8 @@ Each of these was hit while verifying real work, and each one first looked like
|
|
|
177
177
|
|
|
178
178
|
**Stop a dev server before an unattended drive.** A test runner that reuses a server already answering at its URL, as Playwright does with `reuseExistingServer` (which TEA's framework scaffold turns on outside CI), attaches the gate's runs in its measurement worktree to the dev server you left running from your own checkout. Those browser runs then exercise your checkout's source, not the commit under assessment, and a mutation the gate writes into the worktree never reaches them. The gate checks the URLs a runner config may reuse and never stops a server unless it reads as one the run itself left up (below): it gives the worktree's runs their own server on a free port when a scratch runner config can, whether or not one answers, and otherwise tells every assessor the limit, so a risk that only a browser run could measure goes unmeasured. Observed: a gate's worktree runs attached to a vite dev server listening on `[::1]:3001` that had been started from the main tree, and automate left the source mutation behind one acceptance criterion unrun, since no run from the worktree could reach it. With the dev server stopped, the runner starts its own from the worktree, but a server it starts through a launcher such as turbo, which runs it in a process group of its own, outlives the run that started it, and with reuse on the runs after it reuse it, serving the files as they were when it started: the gate turns reuse off through its scratch config where it can, and otherwise reads a mutation row run through such a server as one that cannot run. A start command in your runner config that runs the server itself (the package's own dev script rather than turbo's) keeps it from outliving the run. On Linux the gate stops a server the run itself left up, such as one the sweep right before the gate started through turbo, at each of its checks and once more when the story's gate ends, so those servers do not pile up over an Epic, and the decision log names each one it stopped. It stops one only when every process of it is yours, has no controlling terminal and started after the current story's baseline marker was written, the process that started its session has exited, nothing else that still runs in that session started before the marker or is the parent of one of its processes (a watcher or supervisor that can start it again), and it runs from your project or the gate's worktree. A server of yours can meet all of that: one inside the project and on a port the gate checks, started in the background by a command that has since exited (a script's, or another agent session's) or from a terminal you then close (a `nohup ... &`), with nothing that began before the story still running in its session, reads as the run's and is stopped. So does one that a watcher of yours starts again after the story began, when the watcher too began after the story and runs in the server's process group, or starts the server through a command that then exits and either began after the story or had that command give the server a session of its own. That marker is written when the story starts, and the resume of a stopped or blocked run keeps it, so such a server you start between a run and its resume is stopped too. So stop it before you start or resume a drive, as this tip says, or start it outside the project, on another port or from a terminal you keep open.
|
|
179
179
|
|
|
180
|
+
**Expect one cold Cargo build per gated story, not two.** The production gate replaces its measurement worktree once automate has finished, and `git worktree remove --force` deletes every ignored folder with it. The gate carries the worktree's Cargo build folders (`target`, `src-tauri/target`) out before that removal and back after the new worktree is added, and does the same across a `reloop`, so only the story's first gate setup builds from nothing. After an `escalate`, `advance` or `defer` verdict it carries nothing, and an escalation deletes what it had carried, so a re-gate after an escalation builds cold again. The decision log's honesty line names each folder it carried, skipped or could not move.
|
|
181
|
+
|
|
182
|
+
**Turn on `backfill_sweep = "scoped"` when a backfill's full sweep costs you more than it tells you.** When the gate commits a test `bmad-testarch-automate` backfilled, it runs the full three-axis sweep first, which on a large monorepo can take longer than the story did. With the key set to `scoped` in your team or user `customize.toml` layer, a backfill that stages test files alone re-runs only the checks those files can change, and trusts Execute's step 5 for the rest: the green capture step 5 left in `evidence-<story_id>/` as `sweep-step5-<short sha>.log` at the commit the backfill builds on. Set the key before the story's Execute runs: a step 5 that ran with it unset saved no such capture, and the gate then runs the full sweep.
|
|
183
|
+
|
|
180
184
|
**Pin the parallelism of the verification suite if it is timing-sensitive.** Observed: a full-concurrency test run was flaky two green in five, because one unrelated gate crept past a 10-second default timeout under contention while taking 1.7 seconds alone. Pinning the runner to one worker (`ava --concurrency=1`; your runner's own name for it will differ) was green every time. A flaky verification tier makes every story's evidence unreliable, which is worse than a slow one.
|
package/docs/troubleshooting.md
CHANGED
|
@@ -65,7 +65,7 @@ Note this is fail-closed on purpose: a missing or unreadable gate artifact escal
|
|
|
65
65
|
|
|
66
66
|
## Gate re-loops on a sweep-scope or delta cap
|
|
67
67
|
|
|
68
|
-
A per-story gate can return `reloop` with a `PASS` gate status when a cap fired rather than a finding: the `reasons` name either the sweep-scope cap (the `.tests-ran` marker says `scope=scoped`, or the marker/`scope=` line is missing) or the delta-profile cap (`--cycle-profile delta` was declared). Neither is an error; both mean "not yet, and here is why": a story only advances off a full-scope sweep judged by the full gate instrument. The remedy is the cap-only re-loop, which skips the generalize ceremony entirely: re-run the full three-axis sweep, refresh the marker with `scope=full`, and re-run the gate without `--cycle-profile`. See the cap sections in the [gate model](./gate-model.md).
|
|
68
|
+
A per-story gate can return `reloop` with a `PASS` gate status when a cap fired rather than a finding: the `reasons` name either the sweep-scope cap (the `.tests-ran` marker says `scope=scoped`, or the marker/`scope=` line is missing) or the delta-profile cap (`--cycle-profile delta` was declared). Neither is an error; both mean "not yet, and here is why": a story only advances off a full-scope sweep judged by the full gate instrument. The remedy is the cap-only re-loop, which skips the generalize ceremony entirely: re-run the full three-axis sweep, refresh the marker with `scope=full`, and re-run the gate without `--cycle-profile`. A marker that carries a `sweep=` line beside `scope=full` is no cause: the gate wrote it after a scoped backfill sweep (`backfill_sweep = "scoped"`), and the script reads only its `scope=` line. See the cap sections in the [gate model](./gate-model.md).
|
|
69
69
|
|
|
70
70
|
## The gate stopped a server, or left one up
|
|
71
71
|
|
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": "7.
|
|
4
|
+
"version": "7.3.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",
|
|
@@ -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). 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.
|
|
39
|
+
**Resume.** The workspace is this skill's run folder holding `.decision-log.md`. An operator's request to run the health check for a run skips the resume offer and creates nothing: the operator names the Epic or its run folder (ask in an attended run when they name neither, and refuse in a headless one), refuse a folder that holds no `.decision-log.md`, and otherwise load `references/health-check.md` against that folder's log (Stages row 7). 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
|
|
|
@@ -59,9 +59,9 @@ These exist because the documented mechanics make the intuitive shortcut wrong.
|
|
|
59
59
|
| 4 | Execute | Sequential `/goal` spine | `references/execute.md` |
|
|
60
60
|
| 5 | Gate | `gate_eval.py` verdict → advance / defer / reloop / escalate | `references/gate.md` |
|
|
61
61
|
| 6 | Finalize | Auto Memory capture, optional retrospective, decision-log audit, report | `references/finalize.md` |
|
|
62
|
-
| 7 | Health Check | Terminal self-improvement audit
|
|
62
|
+
| 7 | Health Check | Terminal self-improvement audit: Finalize's close-out loads it, and an operator's request to run the health check for a run loads it against that run folder's `.decision-log.md`, with no other stage and no resume prompt; capture real workflow friction | `references/health-check.md` |
|
|
63
63
|
|
|
64
|
-
Run the stages in order; each routes by the testable conditions stated in its file. The decision log is canonical memory: record scope, the preflight verdict, every gate outcome, and every deferral as you go. **Append it with Write/Edit, never a Bash heredoc**, from Stage 1 on: a heredoc puts the log's prose into a Bash command string, and the guard's git gates read that string as commands (`references/execute.md`, step 4, gives the reason). Once the log is too large to Read affordably, do not Read it: Write the entry to a new file beside the log, in the run folder that holds it, `<log folder>/dlog-slice-<label>-<n>.md`, where `<log folder>` is that folder's full path, `<label>` is the story's id for an entry about a story and `stage<k>` for one a stage writes outside a story (`stage1` for Ingest & Scope), and `<n>` is one past the highest number a `dlog-slice-<label>-*.md` there already carries, so the name is new for every append. Then append it in one Bash call, `cat "<log folder>/dlog-slice-<label>-<n>.md" >> "<log folder>/.decision-log.md"`, and keep the slice.
|
|
64
|
+
Run the stages in order; each routes by the testable conditions stated in its file. The decision log is canonical memory: record scope, the preflight verdict, every gate outcome, and every deferral as you go, and, without stopping, a one-line `friction: <stage>.md "<section heading, exactly as the file writes it, numbering included>": <what was unclear, contradictory or missing>` entry whenever an instruction is unclear, contradictory or silent on the case in hand (the next health check reports it, or Finalize lists it in the run's addendum when the check is off). An entry for a defect hit before any stage file was running (On Activation, the resume routing) names `ingest-and-scope.md` and its H1. **Append it with Write/Edit, never a Bash heredoc**, from Stage 1 on: a heredoc puts the log's prose into a Bash command string, and the guard's git gates read that string as commands (`references/execute.md`, step 4, gives the reason). Once the log is too large to Read affordably, do not Read it: Write the entry to a new file beside the log, in the run folder that holds it, `<log folder>/dlog-slice-<label>-<n>.md`, where `<log folder>` is that folder's full path, `<label>` is the story's id for an entry about a story and `stage<k>` for one a stage writes outside a story (`stage1` for Ingest & Scope), and `<n>` is one past the highest number a `dlog-slice-<label>-*.md` there already carries, so the name is new for every append. Then append it in one Bash call, `cat "<log folder>/dlog-slice-<label>-<n>.md" >> "<log folder>/.decision-log.md"`, and keep the slice.
|
|
65
65
|
|
|
66
66
|
## Headless
|
|
67
67
|
|
|
@@ -87,5 +87,3 @@ A run that blocked (the same five keys, plus `reason`). `report`/`deferred_work`
|
|
|
87
87
|
"deferred_work": null,
|
|
88
88
|
"reason": "<one line, the blocking cause>"}
|
|
89
89
|
```
|
|
90
|
-
|
|
91
|
-
Runs that reach Stage 6 (complete or escalated) also run the terminal workflow health check before emitting — in headless it queues findings locally and never blocks the emit. Runs that block at Stage 1 or Stage 2 do not: there is no executed workflow surface to audit, and inventing findings there would be fabrication.
|
|
@@ -43,6 +43,22 @@ parallel_max_concurrency = 8
|
|
|
43
43
|
# git and `uv run` command the references prescribe covered by this list.
|
|
44
44
|
allowlist_commands = ["git status", "git add", "git commit", "git rev-parse", "git diff", "git check-ignore", "git worktree", "npm test", "npm run lint", "npm run build", "pytest", "uv run", "date"]
|
|
45
45
|
|
|
46
|
+
# --- Gate backfill sweep (opt-in) ---
|
|
47
|
+
# The sweep the gate runs before it commits a test bmad-testarch-automate
|
|
48
|
+
# backfilled. "full" (default) = the full three-axis sweep, cache-defeated, as
|
|
49
|
+
# Execute's step 5 runs it. "scoped" = when every path the backfill stages is a
|
|
50
|
+
# test file (named as its toolchain names one, and mentioned by no other file
|
|
51
|
+
# outside the run's own records) and Execute's full step-5 sweep went green at
|
|
52
|
+
# the commit the backfill builds on, re-run only the checks of the packages
|
|
53
|
+
# that hold those files and every check that reads files across packages or
|
|
54
|
+
# git's file list (unless its own declared inputs exclude every staged path),
|
|
55
|
+
# and print each check left out. It trusts that earlier full sweep for every
|
|
56
|
+
# check it does not re-run, which is why it is opt-in. The tests-ran marker
|
|
57
|
+
# keeps scope=full and gains a sweep= line naming both captures. Any other
|
|
58
|
+
# backfill runs the full sweep. A scalar: a team or user layer overrides it;
|
|
59
|
+
# any value other than "scoped" reads as "full".
|
|
60
|
+
backfill_sweep = "full"
|
|
61
|
+
|
|
46
62
|
# --- Hook fired at epic completion (prompt or shell command); empty = none ---
|
|
47
63
|
on_epic_complete = ""
|
|
48
64
|
|
|
@@ -60,22 +76,53 @@ on_escalation = ""
|
|
|
60
76
|
# See https://armelhbobdad.github.io/bmad-module-ultracode-goal/health-check/
|
|
61
77
|
# Set health_check_repo = "" to disable the health check entirely; the repo
|
|
62
78
|
# doubles as the on/off switch (no target, nothing to run); there is no
|
|
63
|
-
# separate enabled toggle. (assets/module.yaml
|
|
64
|
-
#
|
|
79
|
+
# separate enabled toggle. (assets/module.yaml carries a test-pinned mirror of
|
|
80
|
+
# this default for BMad-core readers of module.yaml; this file is what the live
|
|
81
|
+
# run reads.)
|
|
82
|
+
# A repository on a host other than github.com is given as HOST/OWNER/REPO.
|
|
83
|
+
# To send findings to another repository, create these labels there:
|
|
84
|
+
# health-check, workflow-improvement, bug, friction, gap, duplicate and
|
|
85
|
+
# possible-duplicate, and copy two files into it unchanged: the issue template,
|
|
86
|
+
# https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/.github/ISSUE_TEMPLATE/workflow-health-check.md
|
|
87
|
+
# and the dedup Action, which reads its repository from the run,
|
|
88
|
+
# https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/.github/workflows/health-check-dedup.yaml
|
|
89
|
+
# Without the labels the first create fails and the retry files the issue
|
|
90
|
+
# unlabeled; without the Action nothing labels it or closes a duplicate.
|
|
91
|
+
# Such a project must also set its own health_check_seen_cache: the cache keys
|
|
92
|
+
# each record by fingerprint alone, so two projects filing to different
|
|
93
|
+
# repositories would block or overwrite each other's records. The check only
|
|
94
|
+
# keeps another repository's record from suppressing or linking a finding.
|
|
65
95
|
health_check_repo = "armelhbobdad/bmad-module-ultracode-goal"
|
|
66
96
|
# Deliberately a home-relative `~` path (expanduser semantics, unlike the
|
|
67
97
|
# {project-root} brace tokens above): the seen-cache is machine-global because
|
|
68
|
-
# dedup must span
|
|
69
|
-
# report. Use `~`, not `$HOME`: health_check_fp.py normalises the path with
|
|
98
|
+
# dedup must span the projects that file to one repository: the same defect
|
|
99
|
+
# met in two of them is still one report. Use `~`, not `$HOME`: health_check_fp.py normalises the path with
|
|
70
100
|
# Path.expanduser() only, so a literal `$HOME` survives unexpanded whenever the
|
|
71
101
|
# shell does not expand it first and silently writes a `$HOME/` directory under
|
|
72
102
|
# the current project, making the dedup per-cwd instead of machine-global.
|
|
73
103
|
health_check_seen_cache = "~/.ultracode-goal/health-check-seen.json"
|
|
104
|
+
# The folder where findings that stay local are written, one file per finding,
|
|
105
|
+
# with a resolved/ subfolder for retired ones; redirect it to share a triage folder.
|
|
74
106
|
health_check_queue_path = "{project-root}/_bmad-output/ultracode-goal/improvement-queue"
|
|
75
|
-
# In unattended/headless runs there is no human at the [Y]/[N]/[E] gate.
|
|
107
|
+
# In unattended/headless runs there is no human at the [Y]/[A]/[N]/[E]/[Q] gate.
|
|
76
108
|
# false (default) = queue findings locally, NEVER live-submit without a human.
|
|
77
109
|
# true = additionally live-submit `bug`-severity findings unattended (still
|
|
78
110
|
# deduped + seen-cache-guarded). friction/gap never auto-submit.
|
|
111
|
+
# It posts only when the four gh calls a submit makes are allowed:
|
|
112
|
+
# an unattended run has nobody to approve them, so each is refused
|
|
113
|
+
# and the finding queued. Allow them under [workflow] in
|
|
114
|
+
# {project-root}/_bmad/custom/ultracode-goal.toml (or .user.toml):
|
|
115
|
+
# allowlist_commands = ["gh auth status", "gh search issues", "gh label create", "gh issue create"]
|
|
116
|
+
# Arrays append: the list above keeps every command it holds.
|
|
117
|
+
# Preflight writes each entry as an allow rule in
|
|
118
|
+
# .claude/settings.local.json, where it stays for every later session
|
|
119
|
+
# in the project: any agent there can then create issues and labels on
|
|
120
|
+
# any repository without asking. To keep them to the health-check
|
|
121
|
+
# repository, write "gh search issues --repo <repo>",
|
|
122
|
+
# "gh label create --repo <repo>" and "gh issue create --repo <repo>",
|
|
123
|
+
# <repo> being health_check_repo. When you turn autosubmit off, drop the
|
|
124
|
+
# entries and delete their Bash(gh ...) rules from
|
|
125
|
+
# .claude/settings.local.json yourself: preflight only adds rules.
|
|
79
126
|
health_check_autosubmit = false
|
|
80
127
|
|
|
81
128
|
# --- Cross-Session Recall (optional; consults this repo's prior runs) ---
|
|
@@ -107,7 +107,7 @@ uv run {skill-root}/scripts/claim_check.py --message {workflow.implementation_ar
|
|
|
107
107
|
|
|
108
108
|
The second `--message` is there because the record names files the message may only describe. Its `not_in_diff` lists the paths it reads as named in either text that the staged diff does not touch, each a claim about the tree that needs no judgment to refute; paths git ignores (the mutation ledger the record cites, a story file under an ignored artifact tree) are listed apart, in `ignored`, since no commit can carry them. A record names its own artifacts from the folder that holds them (`sweep.sh`, `red-phase/INDEX.md`), so the command names three folders with `--artifacts-root` (the run folder, this story's scratch folder and its evidence folder) and a fourth with `--tea-config`, the TEA test-artifacts root that holds `atdd-checklist-<story_id>.md`, resolved from the TEA config as preflight resolves it (`scripts/preflight_check.py`, `_tea_artifacts_root`), and such a name is read there: one that does not exist from `{project-root}` but exists in one of them lands in `ignored` when each copy that holds it is either ignored by git or outside the work tree, and in `not_in_diff` otherwise; one that exists from `{project-root}`, that a file the tree holds could be, or that is in none of them, is read from `{project-root}` as before. A file this commit claims and never wrote, named bare, under a folder the tree does not hold, or under an empty or ignored-only folder inside an untracked one (git lists only the topmost untracked folder), cannot be told from an artifact of that name, so a copy in one of the folders reads it as the copy: the hunk pass below, which finds the hunk for each edit the message or the notes say this commit makes, is what catches it. For each path in `not_in_diff`: stage it if this commit changed it; if the work tree shows no change there, the edit did not happen, so make it or remove the claim; and reword the message or correct the story record itself (not only its scratch copy) when the text says this commit changed a file it did not. A path under this story's `.scratch-<story_id>/` or `evidence-<story_id>/` is never staged, since both folders stay untracked: the record names it on purpose, as its own evidence, and it may stay listed. A text may name an unchanged file on purpose, if it says so. Run the check again until every path left in `not_in_diff` is one a text names on purpose and says so. Then make one pass over the claims the diff itself adds (its new comment and header lines, the story's new completion notes) and each line of the message, for a superlative or a property: "exactly", "every", "always", "cannot", "not X but Y", "composed", or a claim that something exists or does not exist yet. Each one either cites evidence this cycle already produced (a test, a mutation row, a printed measurement) or is softened to what that evidence shows; start no new run to back a sentence, since the usual fix is to weaken the sentence, not to strengthen the code. In the same pass, read `git diff --cached` once and find the hunk for each edit the message or the notes say this commit makes ("now says", "narrowed", "landed", "fixed"), path or no path: an edit described by its content has a path too, and an edit whose script failed leaves no hunk. And look for a claim this commit makes false without touching it: a forward reference to what it lands in a comment or doc elsewhere in the tree. Search the project's own files with the Grep tool, case-insensitive, for this story's id, "does not exist yet" and "owed by", and for the name of each file the commit adds, leaving out the installed skill, the run folder and this story's own record and tests; correct a hit only when it refers to what this commit lands, in this commit, staged with this story's paths, unless a sibling story's uncommitted edits share its file, in which case log it to `.decision-log.md` for that story instead. Re-stage every file this pass edited, in its own `git add` call, then commit from the message file (`-F`). Run the same check before any re-commit step 5 makes, and before an amend with `--amend` added, on every run for that amend, a reword's re-run included: it compares the texts with what the amend would commit (the index against `HEAD`'s first parent, or the empty tree at a root commit), so a path the amended commit already carries from `HEAD` stays out of `not_in_diff`, and for that amend the hunk pass reads `git diff --cached <base>`, with the `base` the check printed.
|
|
109
109
|
|
|
110
|
-
5. **Re-verify on the committed HEAD.** Re-run the authoritative suite (tests + lint + build, the same scope step 2 ran this cycle: all three axes including the declared gate set when full; the same resolved package set when this re-loop cycle legitimately ran scoped, per step 2's re-loop rule) on the just-committed, clean tree and **PRINT** the result before advancing. **Run it cache-defeating.** Committing changes a file's git *tracking state* and not one of its bytes, so a content-addressed cache key is unchanged and this re-run replays the pre-commit answer verbatim, observing nothing: eight of eight tasks reported cached, returning in 719ms immediately after a commit, is the whole failure. Pass `--force` (or invoke the package's runner directly), because the one thing this step must actually execute is the tracked-file gates against the newly tracked fileset. Step 2's marks show a story's **new** files to a **conformance gate scoped to *tracked* files** (a `git ls-files`-based ref/ownership/architecture-boundary check) before the commit, but three kinds of new file still hide from it there, so the gate skips them and reports green at step 2, then reds the instant the commit tracks them: a generated or `.gitignore`d file, which no mark can reach; a file created after step 2's last mark; and, for a gate that reads the staged content (one built on git grep --cached, say), every new file, since a mark holds an empty blob. This committed tree is the exact fileset CI and the Stage-5 gate will see, so a story that is green pre-commit but red here is a **false green** the pre-commit run and any transcript-only evaluator (a `/goal` an operator started, say) both miss. A red step 2 reads as not yet a red (a timeout on a loaded machine, or a red the story's changes do not explain) is read that way here too: a red the story's changes do not explain whose second sweep shows no red leaves this step green, with nothing committed. A red means the story is **not** done: remediate, write a fresh `.tests-ran-<story_id>` marker, and re-commit (amend or a follow-up within the story boundary) until the committed HEAD is green, and only then advance. **That fresh marker carries the same `baseline=<sha>` line as step 2's**: the verbatim, whitespace-stripped content of `{workflow.implementation_artifacts}/.baseline-<story_id>`, **copied, never re-derived from `git rev-parse HEAD`**. The story's baseline has not moved; HEAD has, because step 4 just committed. Re-deriving it here would re-anchor the story to that commit and quietly retire the freshness net for the rest of it, which is the very replayed-marker hole the line exists to close, and without the line the guard denies the re-commit outright, so a story that legitimately needs remediation could never close. The fresh marker also re-states `scope=` (and `packages=` when scoped) to match what THIS re-verify actually ran, because the `scope=` line the gate will read through `--tests-ran` is the one written here, not step 2's. **Rewrite `{workflow.implementation_artifacts}/.commit-<story_id>` from `git rev-parse HEAD` once this step's HEAD is green**, in step 4's format: every time, including when nothing was remediated, because an amend replaces the SHA step 4 recorded and a follow-up commit moves it. This marker is the one step-0 artifact whose rule is *refresh*, not *keep*: the baseline names where the story started and must never move, this one names where it ended and must never be stale. That re-commit carries the SAME staging rule as step 4: stage in a prior, SEPARATE tool call (`git add <this story's paths>`), then run the commit (or `git commit --amend`) as a second, distinct call. `git commit -a` and a chained `git add … && git commit` are unsupported here too: the staged index is still empty when the guard pre-evaluates the command string, so the re-commit is denied.
|
|
110
|
+
5. **Re-verify on the committed HEAD.** Re-run the authoritative suite (tests + lint + build, the same scope step 2 ran this cycle: all three axes including the declared gate set when full; the same resolved package set when this re-loop cycle legitimately ran scoped, per step 2's re-loop rule) on the just-committed, clean tree and **PRINT** the result before advancing. **Run it cache-defeating.** Committing changes a file's git *tracking state* and not one of its bytes, so a content-addressed cache key is unchanged and this re-run replays the pre-commit answer verbatim, observing nothing: eight of eight tasks reported cached, returning in 719ms immediately after a commit, is the whole failure. Pass `--force` (or invoke the package's runner directly), because the one thing this step must actually execute is the tracked-file gates against the newly tracked fileset. Step 2's marks show a story's **new** files to a **conformance gate scoped to *tracked* files** (a `git ls-files`-based ref/ownership/architecture-boundary check) before the commit, but three kinds of new file still hide from it there, so the gate skips them and reports green at step 2, then reds the instant the commit tracks them: a generated or `.gitignore`d file, which no mark can reach; a file created after step 2's last mark; and, for a gate that reads the staged content (one built on git grep --cached, say), every new file, since a mark holds an empty blob. This committed tree is the exact fileset CI and the Stage-5 gate will see, so a story that is green pre-commit but red here is a **false green** the pre-commit run and any transcript-only evaluator (a `/goal` an operator started, say) both miss. A red step 2 reads as not yet a red (a timeout on a loaded machine, or a red the story's changes do not explain) is read that way here too: a red the story's changes do not explain whose second sweep shows no red leaves this step green, with nothing committed. A red means the story is **not** done: remediate, write a fresh `.tests-ran-<story_id>` marker, and re-commit (amend or a follow-up within the story boundary) until the committed HEAD is green, and only then advance. **That fresh marker carries the same `baseline=<sha>` line as step 2's**: the verbatim, whitespace-stripped content of `{workflow.implementation_artifacts}/.baseline-<story_id>`, **copied, never re-derived from `git rev-parse HEAD`**. The story's baseline has not moved; HEAD has, because step 4 just committed. Re-deriving it here would re-anchor the story to that commit and quietly retire the freshness net for the rest of it, which is the very replayed-marker hole the line exists to close, and without the line the guard denies the re-commit outright, so a story that legitimately needs remediation could never close. The fresh marker also re-states `scope=` (and `packages=` when scoped) to match what THIS re-verify actually ran, because the `scope=` line the gate will read through `--tests-ran` is the one written here, not step 2's. **Rewrite `{workflow.implementation_artifacts}/.commit-<story_id>` from `git rev-parse HEAD` once this step's HEAD is green**, in step 4's format: every time, including when nothing was remediated, because an amend replaces the SHA step 4 recorded and a follow-up commit moves it. This marker is the one step-0 artifact whose rule is *refresh*, not *keep*: the baseline names where the story started and must never move, this one names where it ended and must never be stale. That re-commit carries the SAME staging rule as step 4: stage in a prior, SEPARATE tool call (`git add <this story's paths>`), then run the commit (or `git commit --amend`) as a second, distinct call. `git commit -a` and a chained `git add … && git commit` are unsupported here too: the staged index is still empty when the guard pre-evaluates the command string, so the re-commit is denied. When `{workflow.backfill_sweep}` is `scoped`, capture this step's sweep in `evidence-<story_id>/` as `sweep-step5-<short sha>.log` ("Evidence never goes in scratch", above): the gate's scoped backfill sweep builds on that capture and names it (`references/gate.md`, "A backfill of test files alone may scope its sweep"), and without it the gate runs the full sweep. No marker this file writes carries a `sweep=` line.
|
|
111
111
|
|
|
112
112
|
**Sub-skill halt catch-all.** If any orchestrated sub-skill blocks on interactive input mid-run, treat it as escalate for that story: write the typed escalation sidecar `{workflow.implementation_artifacts}/escalation-<story_id>.json` (shape below, under "Escalation sidecar") and stop; do not answer its prompt blind. A sub-skill that is not installed at all (the Skill tool does not know its name) takes the same route: escalate, and never substitute another skill (`bmad-build`, `bmad-build-auto`, or BMAD's deprecated `bmad-create-story` and `bmad-dev-story` for UCG's story skills) or hand-author the work it would have produced.
|
|
113
113
|
|
|
@@ -167,6 +167,8 @@ One object, never an array: the file is already named per story, so a list would
|
|
|
167
167
|
|
|
168
168
|
`kind` is **open vocabulary**. A reader renders whatever string it finds and never validates it against a fixed list, in particular never against the red-kind vocabulary the semantic scan returns in `references/preflight.md`, which classifies *planning-artifact* reds and has no term for anything that happens at run time. `budget-overrun` is a live `kind` and sits deliberately outside that vocabulary; a reader that validated against it would silently drop the most common escalation there is. `operator-evidence-owed` is a live `kind` too: the story is delivered and gated except evidence only a person can record (`references/gate.md`). So is `evidence-commit-rejected`: the story advanced, and a repo commit hook rejected its evidence commit in a way the gate may not answer, so that evidence waits, uncommitted, for the operator (`references/gate.md`'s advance route). So is `coupled-stories`: the earlier of two stories that are green only together owes clauses only the later story's build satisfies, and moving them narrows its AC, which only the operator may rule on (the story loop's "Two stories green only together").
|
|
169
169
|
|
|
170
|
+
**An escalated story keeps no gate build.** The gate carries its worktree's build folders into `<stash>` only for a story it will gate again (`references/gate.md`, the first caveat under "Measure the commit, not the working tree", which says what `<stash>` is), and an escalation stops the story instead, whatever route it came by. So whenever you are about to write this sidecar and `<stash>` holds a build folder, run `uv run {skill-root}/scripts/carry_build_cache.py drop --stash <stash>` right before you write it, so a session that ends between the two leaves no build behind a story it escalated. It deletes each folder `<stash>` holds, never through a link, and prints what it deleted, skipped and failed to delete; log that in `.decision-log.md` beside the escalation. The story's re-gate, once the operator answers, builds cold.
|
|
171
|
+
|
|
170
172
|
**Promoting the turn-budget marker.** The `budget_stop.py` Stop hook writes only its own markdown, `{workflow.implementation_artifacts}/.escalation-<story_id>.md`. It stays a recorder: it emits no JSON and starts no process, and its marker records a count without stopping the drive, so the story still goes on to its gate. **Execute is the sole promoter of that markdown, and the story's gate decides whether it promotes.** A marker counts only while the story's recorded count (`turns` in `{workflow.implementation_artifacts}/.budget-<story_id>.json`) is at or past `{workflow.max_turns_per_story}`: after `/ucg-resolve` closes a `budget-overrun` escalation and resets that counter, the marker left on disk is the answered escalation's residue, and nothing below applies to it. **When the gate advances the story (`advance`, or `defer`, whose route advances anyway), do not promote the marker.** The gate decides completion, and none of the decisions the marker asks for has anything left to act on once the story is done: in a real project, every overrun escalation written for a story that then passed its gate was left open and never answered. Log a sizing note in `.decision-log.md` instead, naming the story and the hook's count against `{workflow.max_turns_per_story}`; Finalize's run report carries it. The note records the turns the drive spent, and never says a row of this shape should be split: sizing reads a row's criteria, never its turns ("Sizing: a story too large to drive" above), and the turns follow how the drive waited. **When the gate escalates the story on the turn count** (a re-loop that would exceed the ceiling, which `references/gate.md` turns into `escalate`), promote the marker as that escalation's sidecar: read the `.escalation-<story_id>.md` the hook left behind and write the typed sidecar from it, mapping `source` to that markdown's path, `kind` to `budget-overrun`, `decision_needed` to the human decision the marker asks for (re-scope, split, or hand off), and `evidence` to one line quoted from the marker. The gate can escalate on the count before the hook has written a marker (a re-loop expected to take several responses, from a count still under the ceiling); write the same `budget-overrun` sidecar then from `{workflow.implementation_artifacts}/.budget-<story_id>.json`, with `source` that file's path and `evidence` its count, so `/ucg-resolve` still resets the counter when it closes it. A cap-only `reloop` (a sweep-scope or delta cap) is not that verdict: the full re-gate it leads to decides. A story that escalates for its own reason (a gate file that cannot be read, a sub-skill halt) keeps that reason's sidecar, and the marker's count goes into the decision log beside it. A resume that finds the count already at or past the ceiling escalates before step 0 with the same `kind`, as "Authoring the `/goal` condition" above says. Keeping promotion here means one code path produces the typed JSON whatever the escalation's origin, instead of two writers racing on a file three readers depend on.
|
|
171
173
|
|
|
172
174
|
**Leave the markdown in place — never delete it, never rewrite it.** It is the hook's own record of the count. For a story that advanced it is the sizing note's source, and for a story that escalates it is the residual that survives a session which died before this promotion, so consuming it could destroy the only evidence that an escalation happened at all.
|
|
@@ -17,7 +17,7 @@ Interactive runs **offer** the retrospective at Epic close (skip it by default i
|
|
|
17
17
|
|
|
18
18
|
## Decision-log audit
|
|
19
19
|
|
|
20
|
-
Walk every entry **this invocation wrote** (scope, preflight verdict, each gate verdict, each deferral, every assumption). On a fresh run that is the whole `.decision-log.md`; on a mature Epic it is not, and must not be: execute.md step 4 forbids Reading the log once it is too large to Read affordably, so the auditable unit there is this session's own `dlog-slice-*.md` files, which sit beside the log in the run folder (never in `{workflow.implementation_artifacts}`), plus what is still in context. Entries from prior invocations were audited by the invocations that wrote them; say that in the accounting below rather than silently narrowing the walk, so a reader can tell a scoped audit from a skipped one. Each entry must resolve to one of three: **captured in the run report** (a primary decision or outcome the user takes away), **captured in the addendum** (a parked alternative or rejected option that needs a home but not the report), or **explicitly marked process noise** (set aside, not silently dropped). End with a shared accounting of how the run's reasoning was handled, not a one-sided polish.
|
|
20
|
+
Walk every entry **this invocation wrote** (scope, preflight verdict, each gate verdict, each deferral, every assumption). On a fresh run that is the whole `.decision-log.md`; on a mature Epic it is not, and must not be: execute.md step 4 forbids Reading the log once it is too large to Read affordably, so the auditable unit there is this session's own `dlog-slice-*.md` files, which sit beside the log in the run folder (never in `{workflow.implementation_artifacts}`), plus what is still in context. Entries from prior invocations were audited by the invocations that wrote them; say that in the accounting below rather than silently narrowing the walk, so a reader can tell a scoped audit from a skipped one. Each entry must resolve to one of three: **captured in the run report** (a primary decision or outcome the user takes away), **captured in the addendum** (a parked alternative or rejected option that needs a home but not the report), or **explicitly marked process noise** (set aside, not silently dropped). A `friction:` entry is left for the health check when `{workflow.health_check_repo}` is set, since the check reports it. When that is empty, the check is off, and the `disabled` marker it appends closes every `friction:` entry after the log's last `health-check:` marker unreported, so list each of those in the addendum: search `.decision-log.md` with the Grep tool for the regex `^\s*([-*]\s+)?(friction:|health-check: (disabled|clean|discarded|done)\b)` and take the `friction:` entries after the last marker it finds (all of them when there is none). End with a shared accounting of how the run's reasoning was handled, not a one-sided polish.
|
|
21
21
|
|
|
22
22
|
## Run report
|
|
23
23
|
|
|
@@ -147,7 +147,7 @@ This is a side effect on the way out, never a gate on the exit: a hook that erro
|
|
|
147
147
|
|
|
148
148
|
## Headless output
|
|
149
149
|
|
|
150
|
-
In headless (`-H`), build the final JSON **through the `scripts/headless_envelope.py` adapter** (never hand-composed here), run the Workflow health check (below)
|
|
150
|
+
In headless (`-H`), build the final JSON **through the `scripts/headless_envelope.py` adapter** (never hand-composed here), run the Workflow health check (below), then emit the JSON and stop. `status` is `complete` when the Epic-level gate advanced and its evidence is committed, or `blocked` when a story escalated, the last story's `evidence-commit-rejected` included, though the Epic-level gate advanced before it (`references/gate.md`), and the adapter has one entry point per shape:
|
|
151
151
|
|
|
152
152
|
```
|
|
153
153
|
build_complete_envelope(<path to this run's .decision-log.md>, report=<run-report.md path or None>, deferred_work=<{workflow.deferred_work_path} or None>, impl_artifacts={workflow.implementation_artifacts})
|
|
@@ -179,4 +179,4 @@ A blocked exit (a story escalated) emits the same five keys plus `reason` — th
|
|
|
179
179
|
|
|
180
180
|
## Workflow health check (terminal)
|
|
181
181
|
|
|
182
|
-
After the run-status is settled and (in headless) the JSON is composed but **before** the final emit/exit, load `references/health-check.md`, read it fully
|
|
182
|
+
After the run-status is settled and (in headless) the JSON is composed but **before** the final emit/exit, load `references/health-check.md`, read it fully and execute it, for a `complete` and a `blocked` (escalated) run alike, since both drove real work. It routes its own headless mode and **never blocks the emit**. Take no other action between this section and the health check: a turn that ends on the run report skips the check.
|