bmad-module-ultracode-goal 7.0.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 +2 -1
- package/docs/gate-model.md +1 -1
- package/docs/health-check.md +108 -23
- package/package.json +1 -1
- package/skills/ucg-resolve/SKILL.md +37 -6
- package/skills/ultracode-goal/SKILL.md +3 -5
- package/skills/ultracode-goal/customize.toml +36 -5
- package/skills/ultracode-goal/references/define-done.md +1 -1
- package/skills/ultracode-goal/references/execute.md +1 -1
- package/skills/ultracode-goal/references/finalize.md +3 -3
- package/skills/ultracode-goal/references/gate.md +29 -19
- 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
- package/skills/ultracode-goal/scripts/moved_ac_check.py +233 -0
- package/skills/ultracode-goal/scripts/operator_owed.py +59 -27
|
@@ -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
|
@@ -57,6 +57,7 @@ skills/ultracode-goal/
|
|
|
57
57
|
│ ├── preflight_check.py # mechanical preflight facts + blocker budget
|
|
58
58
|
│ ├── gate_eval.py # gate status -> verdict (the completion authority)
|
|
59
59
|
│ ├── operator_owed.py # is a gate FAIL owed only operator-evidence ACs' records? (fail-closed)
|
|
60
|
+
│ ├── moved_ac_check.py # does trace's matrix still score an AC the operator moved out? (fail-closed)
|
|
60
61
|
│ ├── mutate_check.py # mutation harness: attributable-red proof for the story's guards
|
|
61
62
|
│ ├── probe_servers.py # which URLs a test runner may reuse already answer, from which folder; stops a server the run left up
|
|
62
63
|
│ ├── link_worktree_deps.py # links the main tree's dependency folders into the gate worktree
|
|
@@ -68,7 +69,7 @@ skills/ultracode-goal/
|
|
|
68
69
|
│ ├── claim_check.py # pre-commit: paths a message names that the staged diff skips
|
|
69
70
|
│ ├── drive_epic.py # one `claude -p` per story (--max-stories work bound)
|
|
70
71
|
│ ├── headless_envelope.py # the one five-key headless-envelope adapter
|
|
71
|
-
│ ├── health_check_fp.py # health-check fingerprint
|
|
72
|
+
│ ├── health_check_fp.py # health-check fingerprint, seen-cache and queue plumbing
|
|
72
73
|
│ ├── mem_observation.py # Cross-Session Recall write path (write/drain)
|
|
73
74
|
│ ├── mem_recall.py # Cross-Session Recall latch and read path (latch/filter/unlatch)
|
|
74
75
|
│ ├── merge_config.py # install-time config merge into shared _bmad
|
package/docs/gate-model.md
CHANGED
|
@@ -54,7 +54,7 @@ Any unrecognized status escalates (the script's `GATE_VERDICT.get(gate_status, "
|
|
|
54
54
|
|
|
55
55
|
One `FAIL` takes a different route. When the only criteria TEA's coverage matrix holds open are acceptance criteria tagged `**Gate-ability:** operator-evidence`, whose proof is a live result a person records, no re-loop can change the gate. A plain `**Gate-ability:** operator` tag is not read this way: it marks work the dev agent builds, so an open criterion carrying it keeps the re-loop. The skill checks that with `scripts/operator_owed.py`, which fails closed, and escalates with kind `operator-evidence-owed` instead of re-looping. `gate_eval.py` still prints `reloop`: the route changes, not the verdict.
|
|
56
56
|
|
|
57
|
-
Once `/ucg-resolve` closes that escalation, with the person's records on disk at the commit the gate measured, the resume re-gates that same commit instead of re-driving the story. An `operator-evidence` criterion that already has a counted `pass` record, and that TEA still holds below `FULL`, is still owed: the record covers only part of the criterion, so the escalation names the records already counted and asks the operator to record the rest or to narrow or move the criterion in writing. Re-gating the records already counted changes nothing, so `/ucg-resolve` closes it only on a new `pass` record or on that written change.
|
|
57
|
+
Once `/ucg-resolve` closes that escalation, with the person's records on disk at the commit the gate measured, the resume re-gates that same commit instead of re-driving the story. An `operator-evidence` criterion that already has a counted `pass` record, and that TEA still holds below `FULL`, is still owed: the record covers only part of the criterion, so the escalation names the records already counted and asks the operator to record the rest or to narrow or move the criterion in writing. Re-gating the records already counted changes nothing, so `/ucg-resolve` closes it only on a new `pass` record or on that written change. A criterion the operator moves out of the story leaves the story's numbered list for a section of its own that names its owner and the ruling, its number retired and never reused, and `/ucg-resolve` closes on the move only once the story file carries it, recording each moved criterion in a per-story `.moved-<story_id>` file. A decomposed child's criterion is not moved this way, since its parent's story file is never edited. TEA's trace has no status for a moved criterion and can still score it from the epic, the PRD or the test design, so every gate cycle of a story with that record names the main-tree story file, and every recorded oracle source, to trace, and before `gate_eval.py` runs, `scripts/moved_ac_check.py --commit` reads TEA's coverage matrix for the commit under assessment: while a row still holds a moved criterion, or the trace files cannot be read or measured another commit, the story escalates `operator-evidence-owed` again, with a `decision_needed` that opens "The moved-AC check refused" and its exit code, instead of re-looping with nothing left to build.
|
|
58
58
|
|
|
59
59
|
## The production AND
|
|
60
60
|
|
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",
|
|
@@ -230,9 +230,13 @@ the file holds more than one entry for that `id`, carry each forward, in file or
|
|
|
230
230
|
write one entry in their place. Leave `history` off an entry that replaced nothing. A pass
|
|
231
231
|
that only parks an item records one line, while the entry it replaces can hold the
|
|
232
232
|
operator's whole ruling: a plain replacement would erase that ruling, and nothing in the
|
|
233
|
-
pass would report the loss. Every reader of the file keys on `id` and `action` alone
|
|
233
|
+
pass would report the loss. Every reader of the file but one keys on `id` and `action` alone
|
|
234
234
|
(`{ucg-root}/scripts/red_ids.py`, which preflight and the resume read it through), so
|
|
235
|
-
`history` changes no suppression.
|
|
235
|
+
`history` changes no suppression. The one is the gate's re-read of rulings at the start of
|
|
236
|
+
each cycle (`{ucg-root}/references/gate.md`, "An owned `gate-gap:` line is not this
|
|
237
|
+
story's to close"), which reads the `answer` and the `history` of each `close` entry and
|
|
238
|
+
applies only the latest ruling for each line or AC: a later return or reassignment
|
|
239
|
+
replaces an earlier one.
|
|
236
240
|
|
|
237
241
|
**If an existing `.decisions.json` is unreadable, unparseable, or parsed but missing a
|
|
238
242
|
list-valued `decisions`, stop — do not overwrite it.** Say which file failed and why. This
|
|
@@ -278,18 +282,45 @@ The two dispositions are genuinely different things, not two names for one:
|
|
|
278
282
|
every AC it lists, made at the commit it names. Those are the story's
|
|
279
283
|
`**Gate-ability:** operator-evidence` ACs; a plain `operator` tag is work the dev agent
|
|
280
284
|
builds, never evidence this close waits on. If one is missing, say which and record
|
|
281
|
-
`defer`. An AC the
|
|
285
|
+
`defer`. An AC the operator moves out of the story in writing needs no record, and the
|
|
286
|
+
close waits for the move instead: the story file must carry it in the moved-AC form
|
|
287
|
+
(`{ucg-root}/references/gate.md`, "A moved AC leaves the story's list"), its number
|
|
288
|
+
starting no item under `## Acceptance Criteria` and a note under an H2 heading of its own
|
|
289
|
+
after that section naming that number, the owner and the ruling. Until it does, record
|
|
290
|
+
`defer`. When it does, write `{workflow.implementation_artifacts}/.moved-<story_id>`,
|
|
291
|
+
one line per AC it moves, opened by its `AC-<n>`, `AC-<n> to <owner> per <ruling>`,
|
|
292
|
+
adding to any lines already there, and an `oracle=<absolute path>` line for each oracle
|
|
293
|
+
source the operator edited with the move (a relative one resolved against
|
|
294
|
+
`{project-root}`, and only a path inside the work tree `git rev-parse --show-toplevel`
|
|
295
|
+
prints); log each open `gate-gap:` line on the moved AC again, under the story's key,
|
|
296
|
+
with `owned-by` the same owner per the same ruling; and log the move in the story's
|
|
297
|
+
`.decision-log.md` entry as a `moved:` line, which records it for a reader and which no
|
|
298
|
+
step reads. A written return of a moved AC to the story is applied here too, as
|
|
299
|
+
`{ucg-root}/references/gate.md`, "A moved AC leaves the story's list", says: its line
|
|
300
|
+
leaves the record, and the record goes once no AC line is left. A decomposed child's AC
|
|
301
|
+
is not moved this way: it lives in its parent's story file, which is never edited and
|
|
302
|
+
which every sibling reads; record `defer` and propose a re-plan of the split instead. An
|
|
303
|
+
escalation whose `decision_needed` opens with "The moved-AC check refused (exit 1)"
|
|
304
|
+
closes, its moved ACs owing no record, only once the operator states in writing that
|
|
305
|
+
each source it names no longer lists the AC for this story and you have added each
|
|
306
|
+
source they edited inside the work tree to `.moved-<story_id>` as an `oracle=<absolute
|
|
307
|
+
path>` line, or once they return the AC in writing; until then record `defer`. One that
|
|
308
|
+
opens with "The moved-AC check refused (exit 2)" closes at once when it is the story's
|
|
309
|
+
first exit-2 refusal at that commit; when it says one came before at that commit, it
|
|
310
|
+
closes only once the operator confirms in writing that trace can write its files there,
|
|
311
|
+
and until then record `defer`. An AC the escalation names as partly recorded, with the
|
|
312
|
+
ids of the records TEA
|
|
282
313
|
already counted for it, closes only on a `pass` record at that commit whose `id` is not
|
|
283
314
|
among the ones the escalation names, or on the operator's written narrowing or move of
|
|
284
315
|
the AC: the records already counted are not enough, since re-gating them changes
|
|
285
316
|
nothing. This surface never writes a record itself: the operator is its producer
|
|
286
317
|
(`{ucg-root}/references/gate.md`, "Operator evidence is a recorded live result"). A
|
|
287
|
-
ruling that narrows or moves the AC is the operator's story edit: record it,
|
|
318
|
+
ruling that narrows or moves the AC is the operator's story edit: record it, naming each
|
|
319
|
+
AC a move retires, then close.
|
|
288
320
|
**That close also writes the story's re-gate marker and resets its turn counter.** Write
|
|
289
321
|
`{workflow.implementation_artifacts}/.regate-<story_id>` as two lines, `sha=` the
|
|
290
322
|
assessed commit the sidecar names (in full, as `git rev-parse` prints it) and
|
|
291
|
-
`decision=` the id you closed, then delete the sidecar as for any close, and delete
|
|
292
|
-
`{workflow.implementation_artifacts}/.budget-<story_id>.json`: waiting for operator
|
|
323
|
+
`decision=` the id you closed, then delete the sidecar as for any close, and delete `{workflow.implementation_artifacts}/.budget-<story_id>.json`: waiting for operator
|
|
293
324
|
evidence is not the story's work. The marker is the re-gate entry. While its `sha=`
|
|
294
325
|
names `HEAD`, the resume's `--assert-armed` call routes the story `gate-owed`, so it
|
|
295
326
|
re-enters at Stage 5 to re-gate that commit, and is never re-driven from step 0, where
|
|
@@ -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) ---
|
|
@@ -24,7 +24,7 @@ For every **in-scope** story, in sprint order (leave out a parent that preflight
|
|
|
24
24
|
|
|
25
25
|
1. **`ucg-create-story`**: produce the dedicated story file with full implementation context and *clear, testable* acceptance criteria. Pass it `implementation_artifacts` set to `{workflow.implementation_artifacts}`, so the file lands where this run reads it. If preflight already generated this story, treat the change request as a refinement, not a re-create. Vague ACs are the single most common cause of the next step halting, so sharpen them here.
|
|
26
26
|
|
|
27
|
-
**A criterion with an operator half is split here.** UCG's shaping asks every acceptance criterion for a CI-versus-operator split. When an AC's split names a part no script or test can decide (a measurement on a build or machine CI cannot run, a judgment only a person can make), have `ucg-create-story` split it. The machine-decidable part stays one AC tagged `**Gate-ability:** ci-machine`. The operator part becomes its own numbered AC, numbered after the story
|
|
27
|
+
**A criterion with an operator half is split here.** UCG's shaping asks every acceptance criterion for a CI-versus-operator split. When an AC's split names a part no script or test can decide (a measurement on a build or machine CI cannot run, a judgment only a person can make), have `ucg-create-story` split it. The machine-decidable part stays one AC tagged `**Gate-ability:** ci-machine`. The operator part becomes its own numbered AC, numbered after the highest number the story has ever used, so no existing number moves and no retired number comes back: the number of an AC the operator moved out of the story stays retired (`references/gate.md`, "A moved AC leaves the story's list"), since live records key on `AC-<n>`. It carries its own `**Gate-ability:** operator-evidence` line. An AC whose split names only such a part, with nothing a script or test can decide, is not split. Retag it in place, keeping its number, with `**Gate-ability:** operator-evidence`, whatever tag it carried, only when it asks the dev agent to build or change nothing: its whole content is a measurement, run or observation a person makes and records. The test is whether the AC asks for anything to be built or changed, not who can check it: an AC that asks for a change (code, a comment, a doc, a ledger edit) keeps its tag even when only a person's read can check it. The `operator-evidence` tag is this class's alone: a plain `**Gate-ability:** operator` tag keeps its meaning, work the dev agent builds that a person or a script verifies, and nothing reads it as owed evidence. Its **Verification** is a recorded live result (`references/gate.md`, "Operator evidence is a recorded live result"), and its anti-vacuous twin is that a `fail` record, or a record made at another commit, leaves it uncovered. Never leave the operator part inside a ci-machine AC as prose such as "recorded rather than gated": trace classifies a criterion by everything it states, so the unrecorded half holds the whole AC at PARTIAL. The split drops and relaxes nothing. Log each split in `.decision-log.md`.
|
|
28
28
|
|
|
29
29
|
**A decomposed child gets no story file.** Skip this step for a key the readiness check listed in `checks.decomposed_children` when the split is recorded (its split record (`.split-<parent key>.json` beside `sprint-status.yaml`, which `scripts/story_sizing.py --record` writes) names the child, the child's row cites the parent ACs it claims, or `.decision-log.md` names the parent and the ACs each child claims): the child has no story file and must never get one, and its criteria are the parent ACs it claims, in the parent's file (`references/execute.md`, step 1). A listed key with none of these records is a story of its own that reads like a child (above a `done` parent's row, or under a parent whose row was removed): create its file here, and log in `.decision-log.md` that the readiness check never read its criteria. One such key already has its file: a key whose title starts with a single letter or a roman numeral (`2-4-a-new-login-page`) reads one level below its story number, so its own story file named by that number alone (`2-4.md`) or by another title is listed as the parent of a removed row. When the listed parent file is that story's own (`parent_row` is `null`, no other key in the list names the same file, and the file's title and criteria are this key's), rename that file to `<key>.md` instead, in one `mv <that file> <its folder>/<key>.md` call (a filesystem command `acceptEdits` runs without asking on a path inside the project, unlike a git move, which no allow rule covers), then run this step on it as a refinement, and log the rename: the readiness check did read its criteria. A file two listed keys name is a parent's, so rename it for neither.
|
|
30
30
|
|
|
@@ -22,7 +22,7 @@ Preconditions (asserted, not assumed): you are on the Epic branch (`{workflow.ep
|
|
|
22
22
|
|
|
23
23
|
**A third case: a story already committed, green and un-gated.** The routing above sorts stories into two classes — re-drive, and do not re-run — and a session that died between its commit and its gate belongs to neither. Recognise it by artifacts, never by prose: the row carries commits past its baseline marker **and** a `.tests-ran-<story_id>` marker whose `baseline=` line still matches that marker, **and** neither `trace-<story_id>.md` nor `gate-decision-<story_id>.json` exists under `{workflow.trace_output_dir}`. That story owes **evidence and a gate, not implementation**. Re-set the `.current-story` pointer (the pointer half of step 0 only — the baseline marker is still re-read, never rewritten), skip steps 1 through 4, and enter at **step 5**, re-measuring the committed HEAD rather than reading the tests-ran marker's numbers back — at FULL scope, since no step 2 ran this session to inherit from — and once green, rewrite the tests-ran marker fresh (same `baseline=` line, `scope=full`) **even on a green first try**: the inherited marker may predate the scope contract or carry a mid-loop `scope=scoped`, and the gate reads the marker THIS session leaves behind, not the dead one's; then continue into Stage 5 as normal. Trust the artifacts and the `sprint-status.yaml` row, never the story file's own prose: such a file routinely carries a close-out asserting a gate `PASS` that no artifact backs, which is precisely the claim this stage does not get to make. **The discriminator must hold in full.** A tests-ran marker with no commits, or commits with no marker, is a story that died before or during the sweep, and it takes the ordinary loop from step 0.
|
|
24
24
|
|
|
25
|
-
**A fourth case: a closed `operator-evidence-owed` story owes a re-gate, not a re-drive.** Its FAIL gate left `trace-<story_id>.md` and `gate-decision-<story_id>.json` on disk, so the third case never fires for it. When `/ucg-resolve` closes that escalation, it deletes the sidecar, resets the story's turn counter (waiting for operator evidence is not the story's work) and writes `{workflow.implementation_artifacts}/.regate-<story_id>`, holding `sha=` the assessed commit and `decision=` the closed id. The `story` block reports that marker as `regate`: `null` when there is none, otherwise its `state`. While it reads `fresh` (its `sha=` resolves to `HEAD`) and the baseline marker exists, the route is `gate-owed`: enter exactly as the third case does, re-setting the pointer, skipping step 0's turn-ceiling read and steps 1 through 4, re-measuring `HEAD` at step 5 with any runner or harness the escalated cycle built in `.scratch-<story_id>/` (step 0 keeps that directory until the story advances), then re-gating it in Stage 5, whose trace counts the operator's records. When that directory is gone (a run under an earlier rule removed it at step 5, or an operator did), re-author any runner or harness the story's declared gate set needs before step 5 runs. Check it against the gates the escalated cycle's step-5 capture in `evidence-<story_id>/` names, when that folder holds one, so the re-gate measures the gate set that cycle measured. Commit nothing before that gate while step 5's re-measure is green, since a commit past the assessed commit makes the records stale. On a red, take step 5's red route (remediate, write a fresh `.tests-ran-<story_id>` marker, re-commit): that commit moves `HEAD` past the assessed commit, so the records no longer count and the `.regate-<story_id>` marker is stale, and the re-gate at the new `HEAD` escalates `operator-evidence-owed` again at the new commit. A `stale` marker (one naming another commit, or no commit id) routes as if it were absent, normally `mid-story`: a later commit already made the records stale. On either route the gate deletes the marker once this story's verdict is logged (`references/gate.md`, "A logged verdict settles an owed re-gate").
|
|
25
|
+
**A fourth case: a closed `operator-evidence-owed` story owes a re-gate, not a re-drive.** Its FAIL gate left `trace-<story_id>.md` and `gate-decision-<story_id>.json` on disk, so the third case never fires for it. When `/ucg-resolve` closes that escalation, it deletes the sidecar, resets the story's turn counter (waiting for operator evidence is not the story's work) and writes `{workflow.implementation_artifacts}/.regate-<story_id>`, holding `sha=` the assessed commit and `decision=` the closed id. The `story` block reports that marker as `regate`: `null` when there is none, otherwise its `state`. While it reads `fresh` (its `sha=` resolves to `HEAD`) and the baseline marker exists, the route is `gate-owed`: enter exactly as the third case does, re-setting the pointer, skipping step 0's turn-ceiling read and steps 1 through 4, re-measuring `HEAD` at step 5 with any runner or harness the escalated cycle built in `.scratch-<story_id>/` (step 0 keeps that directory until the story advances), then re-gating it in Stage 5, whose trace counts the operator's records and, for a story with a `{workflow.implementation_artifacts}/.moved-<story_id>` record, reads the main tree's story file and the sources that record lists, and whose check that trace scored no moved AC runs before `gate_eval.py` (`references/gate.md`, "After a move, check that trace scored no moved AC"). When that directory is gone (a run under an earlier rule removed it at step 5, or an operator did), re-author any runner or harness the story's declared gate set needs before step 5 runs. Check it against the gates the escalated cycle's step-5 capture in `evidence-<story_id>/` names, when that folder holds one, so the re-gate measures the gate set that cycle measured. Commit nothing before that gate while step 5's re-measure is green, since a commit past the assessed commit makes the records stale. On a red, take step 5's red route (remediate, write a fresh `.tests-ran-<story_id>` marker, re-commit): that commit moves `HEAD` past the assessed commit, so the records no longer count and the `.regate-<story_id>` marker is stale, and the re-gate at the new `HEAD` escalates `operator-evidence-owed` again at the new commit. A `stale` marker (one naming another commit, or no commit id) routes as if it were absent, normally `mid-story`: a later commit already made the records stale. On either route the gate deletes the marker once this story's verdict is logged (`references/gate.md`, "A logged verdict settles an owed re-gate").
|
|
26
26
|
|
|
27
27
|
**A fifth case: a gate stopped between automate and trace.** `preflight_check.py` reads no log, so its `story` block cannot see this case and reads such a story as `gate-owed` or `mid-story`; take this case instead of either, but never instead of `decision-pending`. It takes three forms, each read from the story's `.decision-log.md`:
|
|
28
28
|
|
|
@@ -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.
|