bmad-module-ultracode-goal 7.1.0 → 7.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +1 -1
- package/docs/architecture.md +1 -1
- package/docs/health-check.md +108 -23
- package/package.json +1 -1
- package/skills/ultracode-goal/SKILL.md +3 -5
- package/skills/ultracode-goal/customize.toml +36 -5
- package/skills/ultracode-goal/references/finalize.md +3 -3
- package/skills/ultracode-goal/references/health-check.md +125 -175
- package/skills/ultracode-goal/references/preflight.md +1 -1
- 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.2.0",
|
|
23
23
|
"author": {
|
|
24
24
|
"name": "Armel"
|
|
25
25
|
},
|
package/docs/architecture.md
CHANGED
|
@@ -69,7 +69,7 @@ skills/ultracode-goal/
|
|
|
69
69
|
│ ├── claim_check.py # pre-commit: paths a message names that the staged diff skips
|
|
70
70
|
│ ├── drive_epic.py # one `claude -p` per story (--max-stories work bound)
|
|
71
71
|
│ ├── headless_envelope.py # the one five-key headless-envelope adapter
|
|
72
|
-
│ ├── health_check_fp.py # health-check fingerprint
|
|
72
|
+
│ ├── health_check_fp.py # health-check fingerprint, seen-cache and queue plumbing
|
|
73
73
|
│ ├── mem_observation.py # Cross-Session Recall write path (write/drain)
|
|
74
74
|
│ ├── mem_recall.py # Cross-Session Recall latch and read path (latch/filter/unlatch)
|
|
75
75
|
│ ├── merge_config.py # install-time config merge into shared _bmad
|
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/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.2.0",
|
|
5
5
|
"description": "BMAD module — Run a BMAD Epic autonomously to a machine-checked, TEA-gated Definition-of-Done.",
|
|
6
6
|
"keywords": [
|
|
7
7
|
"bmad",
|
|
@@ -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.
|
|
@@ -60,22 +60,53 @@ on_escalation = ""
|
|
|
60
60
|
# See https://armelhbobdad.github.io/bmad-module-ultracode-goal/health-check/
|
|
61
61
|
# Set health_check_repo = "" to disable the health check entirely; the repo
|
|
62
62
|
# doubles as the on/off switch (no target, nothing to run); there is no
|
|
63
|
-
# separate enabled toggle. (assets/module.yaml
|
|
64
|
-
#
|
|
63
|
+
# separate enabled toggle. (assets/module.yaml carries a test-pinned mirror of
|
|
64
|
+
# this default for BMad-core readers of module.yaml; this file is what the live
|
|
65
|
+
# run reads.)
|
|
66
|
+
# A repository on a host other than github.com is given as HOST/OWNER/REPO.
|
|
67
|
+
# To send findings to another repository, create these labels there:
|
|
68
|
+
# health-check, workflow-improvement, bug, friction, gap, duplicate and
|
|
69
|
+
# possible-duplicate, and copy two files into it unchanged: the issue template,
|
|
70
|
+
# https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/.github/ISSUE_TEMPLATE/workflow-health-check.md
|
|
71
|
+
# and the dedup Action, which reads its repository from the run,
|
|
72
|
+
# https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/.github/workflows/health-check-dedup.yaml
|
|
73
|
+
# Without the labels the first create fails and the retry files the issue
|
|
74
|
+
# unlabeled; without the Action nothing labels it or closes a duplicate.
|
|
75
|
+
# Such a project must also set its own health_check_seen_cache: the cache keys
|
|
76
|
+
# each record by fingerprint alone, so two projects filing to different
|
|
77
|
+
# repositories would block or overwrite each other's records. The check only
|
|
78
|
+
# keeps another repository's record from suppressing or linking a finding.
|
|
65
79
|
health_check_repo = "armelhbobdad/bmad-module-ultracode-goal"
|
|
66
80
|
# Deliberately a home-relative `~` path (expanduser semantics, unlike the
|
|
67
81
|
# {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
|
|
82
|
+
# dedup must span the projects that file to one repository: the same defect
|
|
83
|
+
# met in two of them is still one report. Use `~`, not `$HOME`: health_check_fp.py normalises the path with
|
|
70
84
|
# Path.expanduser() only, so a literal `$HOME` survives unexpanded whenever the
|
|
71
85
|
# shell does not expand it first and silently writes a `$HOME/` directory under
|
|
72
86
|
# the current project, making the dedup per-cwd instead of machine-global.
|
|
73
87
|
health_check_seen_cache = "~/.ultracode-goal/health-check-seen.json"
|
|
88
|
+
# The folder where findings that stay local are written, one file per finding,
|
|
89
|
+
# with a resolved/ subfolder for retired ones; redirect it to share a triage folder.
|
|
74
90
|
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.
|
|
91
|
+
# In unattended/headless runs there is no human at the [Y]/[A]/[N]/[E]/[Q] gate.
|
|
76
92
|
# false (default) = queue findings locally, NEVER live-submit without a human.
|
|
77
93
|
# true = additionally live-submit `bug`-severity findings unattended (still
|
|
78
94
|
# deduped + seen-cache-guarded). friction/gap never auto-submit.
|
|
95
|
+
# It posts only when the four gh calls a submit makes are allowed:
|
|
96
|
+
# an unattended run has nobody to approve them, so each is refused
|
|
97
|
+
# and the finding queued. Allow them under [workflow] in
|
|
98
|
+
# {project-root}/_bmad/custom/ultracode-goal.toml (or .user.toml):
|
|
99
|
+
# allowlist_commands = ["gh auth status", "gh search issues", "gh label create", "gh issue create"]
|
|
100
|
+
# Arrays append: the list above keeps every command it holds.
|
|
101
|
+
# Preflight writes each entry as an allow rule in
|
|
102
|
+
# .claude/settings.local.json, where it stays for every later session
|
|
103
|
+
# in the project: any agent there can then create issues and labels on
|
|
104
|
+
# any repository without asking. To keep them to the health-check
|
|
105
|
+
# repository, write "gh search issues --repo <repo>",
|
|
106
|
+
# "gh label create --repo <repo>" and "gh issue create --repo <repo>",
|
|
107
|
+
# <repo> being health_check_repo. When you turn autosubmit off, drop the
|
|
108
|
+
# entries and delete their Bash(gh ...) rules from
|
|
109
|
+
# .claude/settings.local.json yourself: preflight only adds rules.
|
|
79
110
|
health_check_autosubmit = false
|
|
80
111
|
|
|
81
112
|
# --- Cross-Session Recall (optional; consults this repo's prior runs) ---
|
|
@@ -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.
|