bmad-module-ultracode-goal 7.2.0 → 8.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/marketplace.json +1 -1
- package/docs/_internal/STABILITY.md +4 -4
- package/docs/architecture.md +3 -2
- package/docs/gate-model.md +4 -2
- package/docs/health-check.md +6 -4
- package/docs/operating-tips.md +5 -1
- package/docs/troubleshooting.md +1 -1
- package/package.json +3 -2
- package/skills/ucg-formalize/SKILL.md +1 -1
- package/skills/ucg-resolve/SKILL.md +8 -1
- package/skills/ultracode-goal/SKILL.md +1 -1
- package/skills/ultracode-goal/customize.toml +25 -3
- package/skills/ultracode-goal/references/execute.md +9 -7
- package/skills/ultracode-goal/references/finalize.md +1 -1
- package/skills/ultracode-goal/references/gate.md +33 -21
- package/skills/ultracode-goal/references/health-check.md +17 -7
- package/skills/ultracode-goal/references/ingest-and-scope.md +3 -3
- package/skills/ultracode-goal/references/preflight.md +1 -1
- package/skills/ultracode-goal/scripts/carry_build_cache.py +435 -0
- package/skills/ultracode-goal/scripts/drive_epic.py +5 -3
- package/skills/ultracode-goal/scripts/formalize_check.py +133 -38
- package/skills/ultracode-goal/scripts/gate_eval.py +13 -13
- package/skills/ultracode-goal/scripts/gate_trail.py +19 -19
- package/skills/ultracode-goal/scripts/health_check_fp.py +110 -5
- package/skills/ultracode-goal/scripts/link_worktree_deps.py +480 -11
- package/skills/ultracode-goal/scripts/moved_ac_check.py +2 -2
- package/skills/ultracode-goal/scripts/operator_owed.py +45 -14
|
@@ -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": "
|
|
22
|
+
"version": "8.0.0",
|
|
23
23
|
"author": {
|
|
24
24
|
"name": "Armel"
|
|
25
25
|
},
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Stability and Public Contract
|
|
3
|
-
description: "The
|
|
3
|
+
description: "The 8.x stability posture: which CLI, config, JSON, and gate surfaces are the supported public contract, what a major costs, and everything that is @internal and free to change."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
> **Status:**
|
|
6
|
+
> **Status:** 8.x. The surfaces below are the public contract. Per [Semantic Versioning 2.0.0](https://semver.org/), a breaking change to any of them requires a MAJOR bump; everything marked `@internal` may change in any release. This document is what a consumer pins against.
|
|
7
7
|
|
|
8
|
-
This is the stability posture for `bmad-module-ultracode-goal` at `
|
|
8
|
+
This is the stability posture for `bmad-module-ultracode-goal` at `8.x`. It enumerates the surfaces a downstream consumer or automator may reasonably depend on, versus everything else, which is `@internal`.
|
|
9
9
|
|
|
10
10
|
## Public contract
|
|
11
11
|
|
|
@@ -20,7 +20,7 @@ The installer CLI is invoked via `npx bmad-module-ultracode-goal <subcommand>`.
|
|
|
20
20
|
|
|
21
21
|
### The `[workflow]` customize.toml keys
|
|
22
22
|
|
|
23
|
-
The keys in the shipped `[workflow]` block of `customize.toml` (including `persistent_facts`, `tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`, `epic_branch_prefix`, `protected_branches`, `max_turns_per_story`, `story_token_budget` (**deprecated, no-op**), `parallel_max_concurrency` (**deprecated, no-op**), `allowlist_commands`, `on_epic_complete`, `on_escalation`, `cross_session_recall`, `cross_session_recall_store`, and `graphify_integration`) are the supported override surface. Teams and users override them in `_bmad/custom/ultracode-goal.toml` (and `.user.toml`) with base → team → user resolution (scalars override, tables deep-merge, arrays append). Renaming or removing a key, or changing how it resolves, is a contract change. See [architecture](../architecture.md).
|
|
23
|
+
The keys in the shipped `[workflow]` block of `customize.toml` (including `persistent_facts`, `tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`, `epic_branch_prefix`, `protected_branches`, `max_turns_per_story`, `story_token_budget` (**deprecated, no-op**), `parallel_max_concurrency` (**deprecated, no-op**), `allowlist_commands`, `backfill_sweep`, `on_epic_complete`, `on_escalation`, `cross_session_recall`, `cross_session_recall_store`, and `graphify_integration`) are the supported override surface. Teams and users override them in `_bmad/custom/ultracode-goal.toml` (and `.user.toml`) with base → team → user resolution (scalars override, tables deep-merge, arrays append). Renaming or removing a key, or changing how it resolves, is a contract change. See [architecture](../architecture.md).
|
|
24
24
|
|
|
25
25
|
`story_token_budget` is **deprecated** as of the deprecation note in `CHANGELOG.md`: it is still shipped, still accepted, and still resolves, so existing overrides keep working and nothing errors. It is a no-op; no layer reads it any more. The runaway bound is turns only, via `max_turns_per_story`. The key stays enumerated here (and stays in `customize.toml`) precisely because removing it would be the contract break this section forbids.
|
|
26
26
|
|
package/docs/architecture.md
CHANGED
|
@@ -61,6 +61,7 @@ skills/ultracode-goal/
|
|
|
61
61
|
│ ├── mutate_check.py # mutation harness: attributable-red proof for the story's guards
|
|
62
62
|
│ ├── probe_servers.py # which URLs a test runner may reuse already answer, from which folder; stops a server the run left up
|
|
63
63
|
│ ├── link_worktree_deps.py # links the main tree's dependency folders into the gate worktree
|
|
64
|
+
│ ├── carry_build_cache.py # carries the gate worktree's build folders aside across its rebuild
|
|
64
65
|
│ ├── gate_trail.py # per-story evidence trail (gate-trail.md) at finalize
|
|
65
66
|
│ ├── formalize_check.py # readiness kernel behind the /ucg-formalize gate
|
|
66
67
|
│ ├── status_render.py # read-side render behind /ucg-status
|
|
@@ -69,7 +70,7 @@ skills/ultracode-goal/
|
|
|
69
70
|
│ ├── claim_check.py # pre-commit: paths a message names that the staged diff skips
|
|
70
71
|
│ ├── drive_epic.py # one `claude -p` per story (--max-stories work bound)
|
|
71
72
|
│ ├── headless_envelope.py # the one five-key headless-envelope adapter
|
|
72
|
-
│ ├── health_check_fp.py # health-check fingerprint, seen-cache and queue plumbing
|
|
73
|
+
│ ├── health_check_fp.py # health-check fingerprint, seen-cache, repository split and queue plumbing
|
|
73
74
|
│ ├── mem_observation.py # Cross-Session Recall write path (write/drain)
|
|
74
75
|
│ ├── mem_recall.py # Cross-Session Recall latch and read path (latch/filter/unlatch)
|
|
75
76
|
│ ├── merge_config.py # install-time config merge into shared _bmad
|
|
@@ -109,7 +110,7 @@ Configuration resolves in three layers, base → team → user, via `resolve_cus
|
|
|
109
110
|
|
|
110
111
|
Neither override file is created by any installer, and a missing one is not an error: the resolver loads it non-required and treats absence as an empty table, so a fresh project resolves the base layer alone. You create them when you first need to override something. Do not mistake them for the `config.toml` and `config.user.toml` already sitting in that directory: those are BMAD's own configuration, and a UCG knob written there resolves to nothing.
|
|
111
112
|
|
|
112
|
-
Merge semantics: **scalars override**, **tables deep-merge**, **arrays append**. At activation the skill runs `resolve_customization.py --skill {skill-root} --key workflow`; if that fails, it resolves the three files itself in the same order. The shipped base layer defines the run's knobs: the TEA/artifact paths (`tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`), the git guardrails (`epic_branch_prefix`, `protected_branches`), the turn budget (`max_turns_per_story`; `story_token_budget` remains as a deprecated no-op key), `parallel_max_concurrency` (deprecated no-op since the `--parallel` retirement), the `allowlist_commands`, the two lifecycle hooks (`on_epic_complete`, `on_escalation`), the [health check](./health-check.md) family (`health_check_repo`, `health_check_seen_cache`, `health_check_queue_path`, `health_check_autosubmit`), and the two optional integrations, both off by default: [`cross_session_recall`](./cross-session-recall.md) with its store folder `cross_session_recall_store`, and the third-party [`graphify_integration`](./knowledge-graph-refresh.md). Teams and users override without editing the shipped file. Remember that a budget or branch override only reaches the *enforcement* layer because preflight threads it into the hook env (see layer 2 above).
|
|
113
|
+
Merge semantics: **scalars override**, **tables deep-merge**, **arrays append**. At activation the skill runs `resolve_customization.py --skill {skill-root} --key workflow`; if that fails, it resolves the three files itself in the same order. The shipped base layer defines the run's knobs: the TEA/artifact paths (`tea_config_path`, `trace_output_dir`, `implementation_artifacts`, `deferred_work_path`), the git guardrails (`epic_branch_prefix`, `protected_branches`), the turn budget (`max_turns_per_story`; `story_token_budget` remains as a deprecated no-op key), `parallel_max_concurrency` (deprecated no-op since the `--parallel` retirement), the `allowlist_commands`, the opt-in `backfill_sweep` (the gate's sweep before it commits a backfilled test, `full` by default), the two lifecycle hooks (`on_epic_complete`, `on_escalation`), the [health check](./health-check.md) family (`health_check_repo`, `health_check_seen_cache`, `health_check_queue_path`, `health_check_autosubmit`), and the two optional integrations, both off by default: [`cross_session_recall`](./cross-session-recall.md) with its store folder `cross_session_recall_store`, and the third-party [`graphify_integration`](./knowledge-graph-refresh.md). Teams and users override without editing the shipped file. Remember that a budget or branch override only reaches the *enforcement* layer because preflight threads it into the hook env (see layer 2 above).
|
|
113
114
|
|
|
114
115
|
The three TOML layers merge once, but a branch or budget value then travels two ways: the conductor reads it directly, while the hooks only see it if preflight re-injects it as env:
|
|
115
116
|
|
package/docs/gate-model.md
CHANGED
|
@@ -52,7 +52,7 @@ The gate status maps to a verdict (`GATE_VERDICT` in the script):
|
|
|
52
52
|
|
|
53
53
|
Any unrecognized status escalates (the script's `GATE_VERDICT.get(gate_status, "escalate")` default), with a `reasons` entry noting it.
|
|
54
54
|
|
|
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.
|
|
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. When the story tags such a criterion but the script cannot read TEA's coverage matrix (there is no trace report, or it lost its absolute `tempCoverageMatrixPath`, the file is gone, or the matrix or the summary is not this gate's), it answers `evaluated: false` rather than a plain `owed: false`, and the story escalates the same way, with a `decision_needed` that opens "The operator-evidence check could not read trace's coverage matrix", since what kept the check from the matrix is the files trace left, which no build work changes. The gate moves that cycle's trace files aside first, so `/ucg-resolve` closes the first such escalation at a commit at once and its re-gate runs trace again, and closes a later one at that commit only on the operator's written word that trace can leave a matrix the check can read there. A hand-authored trace, which holds no matrix by design, keeps the re-loop, and so does a decomposed child none of whose claimed criteria carries the tag. `gate_eval.py` still prints `reloop`: the route changes, not the verdict.
|
|
56
56
|
|
|
57
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
|
|
|
@@ -94,6 +94,8 @@ Under `--profile light` none of this applies: the trace gate is the whole decisi
|
|
|
94
94
|
|
|
95
95
|
Independent of profile, a per-story gate is also handed the story's `.tests-ran-<story_id>` marker via `--tests-ran`. Execute writes a `scope=<full|scoped>` line into that marker beside `baseline=`, naming which sweep form the green run behind this gate was: the full three-axis sweep, or a re-loop iteration's affected-set sweep (changed packages plus their dependents, still cache-defeated, with the resolved package list printed and recorded on a `packages=` line). The script reads the line and applies one rule: **a story only moves forward off a full-scope sweep.** `scope=full` passes the verdict through; `scope=scoped` caps `advance` at `reloop`, and caps `defer` too, because defer's route advances the story after parking its concerns. A missing marker, a marker with no `scope=` line, or an unrecognised value gets the same cap, fail-closed, with a reason naming what was wrong.
|
|
96
96
|
|
|
97
|
+
The gate writes the marker too, when it commits a test `bmad-testarch-automate` backfilled, always with `scope=full`. By default its sweep before that commit is the full three-axis sweep. With the opt-in `backfill_sweep = "scoped"` in `customize.toml`, a backfill that stages test files alone, on a story whose full step-5 sweep went green at the commit the backfill builds on, re-runs only the checks of the packages that hold those files and every check that reads files across packages or git's file list, unless that check's own declared inputs exclude every staged path, and prints each check it leaves out. Its marker then keeps `scope=full` beside a `sweep=` line naming the two green captures it rests on, which the script does not read, and one scoped sweep never builds on another.
|
|
98
|
+
|
|
97
99
|
Two boundaries:
|
|
98
100
|
|
|
99
101
|
- `--epic-level` refuses `--tests-ran` outright (an invocation error, exit 2): the epic roll-up gates no sweep of its own, since every story proved its own scope before reaching `done`.
|
|
@@ -103,7 +105,7 @@ The verdict JSON carries the recognised value as `sweep_scope` (or `null`), so a
|
|
|
103
105
|
|
|
104
106
|
## The delta cycle profile
|
|
105
107
|
|
|
106
|
-
A mid-loop re-gate may declare `--cycle-profile delta`: only the assessor dimension(s) whose findings produced the previous reloop re-run in full, while the other assessors re-check their prior artifact against the diff since the commit they assessed. The script caps a delta gate's verdict at `reloop` (defer too, for the sweep-cap reason): a delta gate can say "not yet, and here is why", never move the story. Advancing requires the full instrument, every assessor over a `scope=full` sweep, so the oracle's finality is untouched and a wrong guess costs one extra full gate rather than an unearned advance. The fallback is mechanical: any prior finding without a clean dimension attribution means the full gate runs. `bmad-testarch-automate` sits outside this choice: after a story's first gate cycle, full or delta, it searches only the diff since the previous gate and re-runs the mutation rows behind the gaps that gate backfilled and behind every gap still open, and the full instrument runs it at that scope too. It backfills every gap it finds on a P0 criterion, in any cycle, so trace counts the new test and the script decides; only a gap on another criterion is reported instead, when it lies outside that scope or while operator live results sit at the commit under assessment. A reported gap stays open until a pass at a later commit finds its mutants killed, and it never changes the route a verdict takes. Automate confirms each test it backfills in the same pass, with the test copied into the worktree, and a test that leaves its mutant alive (perhaps an equivalent mutant, which no test can kill) is logged as an `unkilled` gap that no later pass writes another test for while that code stands. `--epic-level` refuses the flag (invocation error, exit 2); omitting it is the full behaviour, and the `cycle_profile` JSON key appears exactly when the flag was supplied.
|
|
108
|
+
A mid-loop re-gate may declare `--cycle-profile delta`: only the assessor dimension(s) whose findings produced the previous reloop re-run in full, while the other assessors re-check their prior artifact against the diff since the commit they assessed. The script caps a delta gate's verdict at `reloop` (defer too, for the sweep-cap reason): a delta gate can say "not yet, and here is why", never move the story. Advancing requires the full instrument, every assessor over a `scope=full` sweep, so the oracle's finality is untouched and a wrong guess costs one extra full gate rather than an unearned advance. The fallback is mechanical: any prior finding without a clean dimension attribution means the full gate runs. `bmad-testarch-automate` sits outside this choice: after a story's first gate cycle, full or delta, it searches only the diff since the previous gate and re-runs the mutation rows behind the gaps that gate backfilled and behind every gap still open, and the full instrument runs it at that scope too. It backfills every gap it finds on a P0 criterion, in any cycle, so trace counts the new test and the script decides; only a gap on another criterion is reported instead, when it lies outside that scope or while operator live results sit at the commit under assessment. A reported gap stays open until a pass at a later commit finds its mutants killed, and it never changes the route a verdict takes. Automate confirms each test it backfills in the same pass, with the test copied into the worktree, and a test that leaves its mutant alive (perhaps an equivalent mutant, which no test can kill) is logged as an `unkilled` gap that no later pass writes another test for while that code stands. A test that reads the code's source text instead of executing it, where no test runner can execute that code, measures only its spelling: the behaviour stays an `unmeasured` gap naming the test and what could execute the code, and no test that reads source text closes it. `--epic-level` refuses the flag (invocation error, exit 2); omitting it is the full behaviour, and the `cycle_profile` JSON key appears exactly when the flag was supplied.
|
|
107
109
|
|
|
108
110
|
## The thresholds
|
|
109
111
|
|
package/docs/health-check.md
CHANGED
|
@@ -92,14 +92,14 @@ health_check_repo = ""
|
|
|
92
92
|
|
|
93
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
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.
|
|
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, such as a GitHub Enterprise Server host: log in to that host first, with `gh auth login --hostname HOST`, writing HOST in lower case and without a leading `www.`, as `gh` reads the host of a repository), 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. On a host other than github.com, the Action runs only once GitHub Actions is on there, its `runs-on` names one of the host's runners, the host can reach `actions/github-script` at the commit the Action pins, and those runners can run the Node version that commit's `action.yml` names in `runs.using`. 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
96
|
|
|
97
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
98
|
|
|
99
99
|
```toml
|
|
100
100
|
[workflow]
|
|
101
101
|
health_check_autosubmit = true
|
|
102
|
-
allowlist_commands = ["gh auth status", "gh
|
|
102
|
+
allowlist_commands = ["gh auth status", "gh issue list", "gh label create", "gh issue create"]
|
|
103
103
|
```
|
|
104
104
|
|
|
105
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:
|
|
@@ -107,9 +107,11 @@ These rules outlast the run: they stay in `.claude/settings.local.json` and appl
|
|
|
107
107
|
```toml
|
|
108
108
|
[workflow]
|
|
109
109
|
health_check_autosubmit = true
|
|
110
|
-
allowlist_commands = ["gh auth status", "gh
|
|
110
|
+
allowlist_commands = ["gh auth status", "gh issue list --repo <health_check_repo>", "gh label create --repo <health_check_repo>", "gh issue create --repo <health_check_repo>"]
|
|
111
111
|
```
|
|
112
112
|
|
|
113
|
+
An override written for 7.3.0 or earlier allows `gh search issues`, which the health check no longer runs: it searches with `gh issue list`, whose `--repo` also takes a host. In the `[workflow]` override, replace `"gh search issues"` with `"gh issue list"` (or `"gh search issues --repo <health_check_repo>"` with `"gh issue list --repo <health_check_repo>"`), and delete the rule preflight wrote for the old entry, `Bash(gh search issues:*)` or `Bash(gh search issues --repo <health_check_repo>:*)`, from `.claude/settings.local.json`.
|
|
114
|
+
|
|
113
115
|
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
116
|
|
|
115
117
|
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.
|
|
@@ -184,4 +186,4 @@ When the body opens with "Regression of", add `--regression`: the new issue trac
|
|
|
184
186
|
|
|
185
187
|
Then retire the queue file: delete it, or move it into a `resolved/` subfolder of the queue directory.
|
|
186
188
|
|
|
187
|
-
You can also open one through the issue chooser of `<health-check-repo>`, `https
|
|
189
|
+
You can also open one through the issue chooser of `<health-check-repo>`, `https://<host>/<owner>/<repo>/issues/new/choose`, `<host>` being the host you logged in to for a `HOST/OWNER/REPO` value, and `github.com` for `OWNER/REPO` (on the default, <https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/new/choose>). An issue filed that way keeps the template's `health-check` and `workflow-improvement` labels and lacks only the `fp-*` and severity ones, so replace its sections from Workflow through Defect Key with the `body_header` that the `health_check_fp.py fingerprint` command in the template's comments prints: the dedup Action adds those two labels from its Fingerprint and Severity, and leaves an issue whose Fingerprint still holds the `fp-XXXXXXX` placeholder as it is.
|
package/docs/operating-tips.md
CHANGED
|
@@ -175,6 +175,10 @@ Each of these was hit while verifying real work, and each one first looked like
|
|
|
175
175
|
|
|
176
176
|
**The spawned session's sandbox may refuse network egress when the parent's does not.** A story escalated reporting that two data files "cannot be fetched" and a dependency was "absent". From the parent session both were trivially available: the dependency was already in the local package cache and a plain `curl` reached the upstream host. **When a spawn reports a dependency it cannot fetch, check the local package caches and try the fetch yourself before accepting the block.**
|
|
177
177
|
|
|
178
|
-
**Stop a dev server before an unattended drive.** A test runner that reuses a server already answering at its URL, as Playwright does with `reuseExistingServer` (which TEA's framework scaffold turns on outside CI), attaches the gate's runs in its measurement worktree to the dev server you left running from your own checkout. Those browser runs then exercise your checkout's source, not the commit under assessment, and a mutation the gate writes into the worktree never reaches them. The gate checks the URLs a runner config may reuse and never stops a server unless it reads as one the run itself left up (below): it gives the worktree's runs their own server on a free port when a scratch runner config can, whether or not one answers, and otherwise tells every assessor the limit, so a risk that only a browser run could measure goes unmeasured. Observed: a gate's worktree runs attached to a vite dev server listening on `[::1]:
|
|
178
|
+
**Stop a dev server before an unattended drive.** A test runner that reuses a server already answering at its URL, as Playwright does with `reuseExistingServer` (which TEA's framework scaffold turns on outside CI), attaches the gate's runs in its measurement worktree to the dev server you left running from your own checkout. Those browser runs then exercise your checkout's source, not the commit under assessment, and a mutation the gate writes into the worktree never reaches them. The gate checks the URLs a runner config may reuse and never stops a server unless it reads as one the run itself left up (below): it gives the worktree's runs their own server on a free port when a scratch runner config can, whether or not one answers, and otherwise tells every assessor the limit, so a risk that only a browser run could measure goes unmeasured. Observed: a gate's worktree runs attached to a vite dev server listening on `[::1]:5173` that had been started from the main tree, and automate left the source mutation behind one acceptance criterion unrun, since no run from the worktree could reach it. With the dev server stopped, the runner starts its own from the worktree, but a server it starts through a launcher such as turbo, which runs it in a process group of its own, outlives the run that started it, and with reuse on the runs after it reuse it, serving the files as they were when it started: the gate turns reuse off through its scratch config where it can, and otherwise reads a mutation row run through such a server as one that cannot run. A start command in your runner config that runs the server itself (the package's own dev script rather than turbo's) keeps it from outliving the run. On Linux the gate stops a server the run itself left up, such as one the sweep right before the gate started through turbo, at each of its checks and once more when the story's gate ends, so those servers do not pile up over an Epic, and the decision log names each one it stopped. It stops one only when every process of it is yours, has no controlling terminal and started after the current story's baseline marker was written, the process that started its session has exited, nothing else that still runs in that session started before the marker or is the parent of one of its processes (a watcher or supervisor that can start it again), and it runs from your project or the gate's worktree. A server of yours can meet all of that: one inside the project and on a port the gate checks, started in the background by a command that has since exited (a script's, or another agent session's) or from a terminal you then close (a `nohup ... &`), with nothing that began before the story still running in its session, reads as the run's and is stopped. So does one that a watcher of yours starts again after the story began, when the watcher too began after the story and runs in the server's process group, or starts the server through a command that then exits and either began after the story or had that command give the server a session of its own. That marker is written when the story starts, and the resume of a stopped or blocked run keeps it, so such a server you start between a run and its resume is stopped too. So stop it before you start or resume a drive, as this tip says, or start it outside the project, on another port or from a terminal you keep open.
|
|
179
|
+
|
|
180
|
+
**Expect one cold Cargo build per gated story, not two.** The production gate replaces its measurement worktree once automate has finished, and `git worktree remove --force` deletes every ignored folder with it. The gate carries the worktree's Cargo build folders (`target`, `src-tauri/target`) out before that removal and back after the new worktree is added, and does the same across a `reloop`, so only the story's first gate setup builds from nothing. After an `escalate`, `advance` or `defer` verdict it carries nothing, and an escalation deletes what it had carried, so a re-gate after an escalation builds cold again. The decision log's honesty line names each folder it carried, skipped or could not move.
|
|
181
|
+
|
|
182
|
+
**Turn on `backfill_sweep = "scoped"` when a backfill's full sweep costs you more than it tells you.** When the gate commits a test `bmad-testarch-automate` backfilled, it runs the full three-axis sweep first, which on a large monorepo can take longer than the story did. With the key set to `scoped` in your team or user `customize.toml` layer, a backfill that stages test files alone re-runs only the checks those files can change, and trusts Execute's step 5 for the rest: the green capture step 5 left in `evidence-<story_id>/` as `sweep-step5-<short sha>.log` at the commit the backfill builds on. Set the key before the story's Execute runs: a step 5 that ran with it unset saved no such capture, and the gate then runs the full sweep.
|
|
179
183
|
|
|
180
184
|
**Pin the parallelism of the verification suite if it is timing-sensitive.** Observed: a full-concurrency test run was flaky two green in five, because one unrelated gate crept past a 10-second default timeout under contention while taking 1.7 seconds alone. Pinning the runner to one worker (`ava --concurrency=1`; your runner's own name for it will differ) was green every time. A flaky verification tier makes every story's evidence unreliable, which is worse than a slow one.
|
package/docs/troubleshooting.md
CHANGED
|
@@ -65,7 +65,7 @@ Note this is fail-closed on purpose: a missing or unreadable gate artifact escal
|
|
|
65
65
|
|
|
66
66
|
## Gate re-loops on a sweep-scope or delta cap
|
|
67
67
|
|
|
68
|
-
A per-story gate can return `reloop` with a `PASS` gate status when a cap fired rather than a finding: the `reasons` name either the sweep-scope cap (the `.tests-ran` marker says `scope=scoped`, or the marker/`scope=` line is missing) or the delta-profile cap (`--cycle-profile delta` was declared). Neither is an error; both mean "not yet, and here is why": a story only advances off a full-scope sweep judged by the full gate instrument. The remedy is the cap-only re-loop, which skips the generalize ceremony entirely: re-run the full three-axis sweep, refresh the marker with `scope=full`, and re-run the gate without `--cycle-profile`. See the cap sections in the [gate model](./gate-model.md).
|
|
68
|
+
A per-story gate can return `reloop` with a `PASS` gate status when a cap fired rather than a finding: the `reasons` name either the sweep-scope cap (the `.tests-ran` marker says `scope=scoped`, or the marker/`scope=` line is missing) or the delta-profile cap (`--cycle-profile delta` was declared). Neither is an error; both mean "not yet, and here is why": a story only advances off a full-scope sweep judged by the full gate instrument. The remedy is the cap-only re-loop, which skips the generalize ceremony entirely: re-run the full three-axis sweep, refresh the marker with `scope=full`, and re-run the gate without `--cycle-profile`. A marker that carries a `sweep=` line beside `scope=full` is no cause: the gate wrote it after a scoped backfill sweep (`backfill_sweep = "scoped"`), and the script reads only its `scope=` line. See the cap sections in the [gate model](./gate-model.md).
|
|
69
69
|
|
|
70
70
|
## The gate stopped a server, or left one up
|
|
71
71
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://json.schemastore.org/package.json",
|
|
3
3
|
"name": "bmad-module-ultracode-goal",
|
|
4
|
-
"version": "
|
|
4
|
+
"version": "8.0.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",
|
|
@@ -45,7 +45,7 @@
|
|
|
45
45
|
"lint:md": "markdownlint-cli2 \"**/*.md\" && node tools/changes.js lint",
|
|
46
46
|
"prepare": "husky || exit 0",
|
|
47
47
|
"postprepare": "node tools/link-reference-skills.js --quiet || exit 0",
|
|
48
|
-
"quality": "run-p --print-label --aggregate-output format:check lint lint:md lint:instructions test:install test:cli test:pack test:python test:rehype test:docs-links-tool test:skill-links test:em-dash-tool test:tool-requirements-tool test:context-index-tool test:changes-tool validate:skills validate:refs validate:fixtures validate:docs-links validate:em-dash validate:tool-requirements validate:context-index validate:changes",
|
|
48
|
+
"quality": "run-p --print-label --aggregate-output format:check lint lint:md lint:instructions test:install test:cli test:pack test:python test:rehype test:docs-links-tool test:skill-links test:em-dash-tool test:tool-requirements-tool test:context-index-tool test:changes-tool test:private-tokens-tool validate:skills validate:refs validate:fixtures validate:docs-links validate:em-dash validate:tool-requirements validate:context-index validate:changes",
|
|
49
49
|
"skills:link": "node tools/link-reference-skills.js",
|
|
50
50
|
"test": "npm run quality",
|
|
51
51
|
"test:changes-tool": "node test/test-changes.js && node test/test-covered-surfaces.js && node test/test-release-state.js",
|
|
@@ -55,6 +55,7 @@
|
|
|
55
55
|
"test:em-dash-tool": "node test/test-validate-no-em-dash.js",
|
|
56
56
|
"test:install": "node test/test-installation-components.js",
|
|
57
57
|
"test:pack": "node test/test-pack-contents.js",
|
|
58
|
+
"test:private-tokens-tool": "node test/test-check-private-tokens.js",
|
|
58
59
|
"test:python": "uv run --with pytest==9.1.1 --with pytest-xdist==3.8.0 --with pyyaml==6.0.3 pytest skills/ultracode-goal/scripts/tests/ test/ -o \"python_files=test-*.py test_*.py *_test.py\" -n auto",
|
|
59
60
|
"test:rehype": "node test/test-rehype-markdown-links.js",
|
|
60
61
|
"test:skill-links": "node test/test-link-reference-skills.js",
|
|
@@ -136,7 +136,7 @@ each entry where `remediable: true`. The remediation per kind:
|
|
|
136
136
|
decomposed child is never scaffolded: it has no story file by design, and the kernel
|
|
137
137
|
already counts it covered by its parent's file when its row sits above the parent's
|
|
138
138
|
row and the parent row is `done`, or when the split removed the parent's row. So a
|
|
139
|
-
listed key whose id extends a parent's (`
|
|
139
|
+
listed key whose id extends a parent's (`55-0-a-i` of `55-0-a`) is a story of its own,
|
|
140
140
|
or a child the kernel found under a parent row that is not `done` or below a `done`
|
|
141
141
|
parent's row (the `detail` names each key below a `done` parent's row, with that row;
|
|
142
142
|
for a parent row that is not `done`, find the parent from the key's id). The split
|
|
@@ -308,7 +308,14 @@ The two dispositions are genuinely different things, not two names for one:
|
|
|
308
308
|
opens with "The moved-AC check refused (exit 2)" closes at once when it is the story's
|
|
309
309
|
first exit-2 refusal at that commit; when it says one came before at that commit, it
|
|
310
310
|
closes only once the operator confirms in writing that trace can write its files there,
|
|
311
|
-
and until then record `defer`.
|
|
311
|
+
and until then record `defer`. One that opens with "The operator-evidence check could not
|
|
312
|
+
read trace's coverage matrix" lists no AC and waits on no record: it closes at once when
|
|
313
|
+
it is the story's first such escalation at that commit, and the re-gate it owes runs
|
|
314
|
+
trace again, since the gate moved that cycle's trace files aside; when it says one came
|
|
315
|
+
before at that commit, it closes only once the operator confirms in writing that trace
|
|
316
|
+
can leave a coverage matrix the check can read there, with what its `evidence` names
|
|
317
|
+
fixed, and until then record `defer`.
|
|
318
|
+
An AC the escalation names as partly recorded, with the
|
|
312
319
|
ids of the records TEA
|
|
313
320
|
already counted for it, closes only on a `pass` record at that commit whose `id` is not
|
|
314
321
|
among the ones the escalation names, or on the operator's written narrowing or move of
|
|
@@ -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`. 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.
|
|
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 (that step alone, never Stage 1's filter call), 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
|
|
|
@@ -43,6 +43,22 @@ parallel_max_concurrency = 8
|
|
|
43
43
|
# git and `uv run` command the references prescribe covered by this list.
|
|
44
44
|
allowlist_commands = ["git status", "git add", "git commit", "git rev-parse", "git diff", "git check-ignore", "git worktree", "npm test", "npm run lint", "npm run build", "pytest", "uv run", "date"]
|
|
45
45
|
|
|
46
|
+
# --- Gate backfill sweep (opt-in) ---
|
|
47
|
+
# The sweep the gate runs before it commits a test bmad-testarch-automate
|
|
48
|
+
# backfilled. "full" (default) = the full three-axis sweep, cache-defeated, as
|
|
49
|
+
# Execute's step 5 runs it. "scoped" = when every path the backfill stages is a
|
|
50
|
+
# test file (named as its toolchain names one, and mentioned by no other file
|
|
51
|
+
# outside the run's own records) and Execute's full step-5 sweep went green at
|
|
52
|
+
# the commit the backfill builds on, re-run only the checks of the packages
|
|
53
|
+
# that hold those files and every check that reads files across packages or
|
|
54
|
+
# git's file list (unless its own declared inputs exclude every staged path),
|
|
55
|
+
# and print each check left out. It trusts that earlier full sweep for every
|
|
56
|
+
# check it does not re-run, which is why it is opt-in. The tests-ran marker
|
|
57
|
+
# keeps scope=full and gains a sweep= line naming both captures. Any other
|
|
58
|
+
# backfill runs the full sweep. A scalar: a team or user layer overrides it;
|
|
59
|
+
# any value other than "scoped" reads as "full".
|
|
60
|
+
backfill_sweep = "full"
|
|
61
|
+
|
|
46
62
|
# --- Hook fired at epic completion (prompt or shell command); empty = none ---
|
|
47
63
|
on_epic_complete = ""
|
|
48
64
|
|
|
@@ -63,7 +79,9 @@ on_escalation = ""
|
|
|
63
79
|
# separate enabled toggle. (assets/module.yaml carries a test-pinned mirror of
|
|
64
80
|
# this default for BMad-core readers of module.yaml; this file is what the live
|
|
65
81
|
# run reads.)
|
|
66
|
-
# A repository on a host other than github.com is given as HOST/OWNER/REPO
|
|
82
|
+
# A repository on a host other than github.com is given as HOST/OWNER/REPO:
|
|
83
|
+
# log gh in to that host first, with gh auth login --hostname HOST, HOST in
|
|
84
|
+
# lower case and without a leading www.
|
|
67
85
|
# To send findings to another repository, create these labels there:
|
|
68
86
|
# health-check, workflow-improvement, bug, friction, gap, duplicate and
|
|
69
87
|
# possible-duplicate, and copy two files into it unchanged: the issue template,
|
|
@@ -72,6 +90,10 @@ on_escalation = ""
|
|
|
72
90
|
# https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/.github/workflows/health-check-dedup.yaml
|
|
73
91
|
# Without the labels the first create fails and the retry files the issue
|
|
74
92
|
# unlabeled; without the Action nothing labels it or closes a duplicate.
|
|
93
|
+
# On a host other than github.com the Action runs only once GitHub Actions is
|
|
94
|
+
# on there, its runs-on names one of the host's runners, the host can reach
|
|
95
|
+
# actions/github-script at the commit the Action pins, and those runners can
|
|
96
|
+
# run the Node version that commit's action.yml names in runs.using.
|
|
75
97
|
# Such a project must also set its own health_check_seen_cache: the cache keys
|
|
76
98
|
# each record by fingerprint alone, so two projects filing to different
|
|
77
99
|
# repositories would block or overwrite each other's records. The check only
|
|
@@ -96,13 +118,13 @@ health_check_queue_path = "{project-root}/_bmad-output/ultracode-goal/improvemen
|
|
|
96
118
|
# an unattended run has nobody to approve them, so each is refused
|
|
97
119
|
# and the finding queued. Allow them under [workflow] in
|
|
98
120
|
# {project-root}/_bmad/custom/ultracode-goal.toml (or .user.toml):
|
|
99
|
-
# allowlist_commands = ["gh auth status", "gh
|
|
121
|
+
# allowlist_commands = ["gh auth status", "gh issue list", "gh label create", "gh issue create"]
|
|
100
122
|
# Arrays append: the list above keeps every command it holds.
|
|
101
123
|
# Preflight writes each entry as an allow rule in
|
|
102
124
|
# .claude/settings.local.json, where it stays for every later session
|
|
103
125
|
# in the project: any agent there can then create issues and labels on
|
|
104
126
|
# any repository without asking. To keep them to the health-check
|
|
105
|
-
# repository, write "gh
|
|
127
|
+
# repository, write "gh issue list --repo <repo>",
|
|
106
128
|
# "gh label create --repo <repo>" and "gh issue create --repo <repo>",
|
|
107
129
|
# <repo> being health_check_repo. When you turn autosubmit off, drop the
|
|
108
130
|
# entries and delete their Bash(gh ...) rules from
|
|
@@ -8,7 +8,7 @@ Preconditions (asserted, not assumed): you are on the Epic branch (`{workflow.ep
|
|
|
8
8
|
|
|
9
9
|
**A decomposed child's ATDD run** (the precondition's case above) follows `references/define-done.md` step 2's rule for a decomposed child: under the child's own key, so the checklist the commit guard reads is the child's; the parent's story file read for the text of the parent ACs the child claims, never edited; and, on a halt over vague criteria, an escalation, never a `ucg-create-story` run for the child. The run is the child's own work: it comes after the child's step 0 (story loop, below) has written both the `.current-story` pointer and the child's baseline marker, and before step 1, so the Stop hook books its turns to the child. Step 0 is never split around it, pointer first and baseline after: the run commits nothing and leaves `HEAD` where it was, so the baseline step 0 records is the one the child starts from either way. Sizing still comes first ("Sizing: a story too large to drive" sizes the row ahead of step 0), so a child that is split again gets no run. In production, on a stack ATDD can run on, a resume that finds the child's `.baseline-<story_id>` still owes the run, before step 1, when `atdd-checklist-<child key>.md` is absent or a `generatedTestFiles` path it lists does not exist: an interrupted run can leave either.
|
|
10
10
|
|
|
11
|
-
**On resume, re-enter Execute at the first story whose last logged gate verdict is not advance; advanced stories are not re-run; re-assert (do not rebuild) the Epic branch, hooks, the allowlist, the `.mem-state.json` recall latch, and the in-flight story's baseline marker before continuing**, and read the story's recorded turn count before driving it ("Authoring the `/goal` condition" below says when a resumed count escalates instead). Before the next story's step 0, also check whether the last advanced story's gate evidence is still uncommitted, and if it is, make that evidence commit first, exactly as `references/gate.md`'s "Commit the gate's evidence before the next story starts" describes (and when that story advanced with its count at or past the turn ceiling and no sizing note was logged, log it now, per "Promoting the turn-budget marker"): a resume enters here, before Stage 5 is ever loaded, so this is where that rule has to be met. That story carries an `evidence-commit-rejected` escalation when a repo commit hook rejected that commit in a way the gate may not answer, so run the `--assert-armed` call below with `--story` naming that story first: while its `escalation` reads `open`, make no commit and take the `decision-pending` route below for that story, and once `/ucg-resolve` has closed it (its sidecar is gone, and `.evidence-owed-<story_id>` is still on disk), make the commit and remove that marker. Check every `.evidence-owed-<story_id>` of this Epic's stories this way, not only the last advanced story's: a marker whose evidence was committed some other way is removed as `references/gate.md` says, with no commit. When that story is the Epic's last, so every story reads `done`, no story is left to drive: after the commit go to Stage 6 (`references/finalize.md`) with the Epic-level verdict the log holds, and run neither a story nor the Epic-level gate again. Stage 1 resolved no in-scope story for that resume, so Finalize passes that story as its one `--story` to `scripts/gate_trail.py`, whose range then ends at the commit this resume made, and the run report names the route as the owed evidence commit made and the Epic complete. Before the next story's step 0, or before Stage 6 on that route, remove `.scratch-<story_id>/` of each story of this Epic whose row is already `done` (`references/gate.md`, "Commit the gate's evidence before the next story starts"): a run that stopped after that story's evidence commit, or with nothing staged for it, left the folder there. And "re-assert the hooks" means preflight step 5's assertion, not a presence check: both script paths appear in the resolved settings **and** the PreToolUse group's matcher is the all-tools form (`references/preflight.md`, "Arm the PreToolUse group with a matcher that covers EVERY tool"). A presence-only read passes on a prior run's `Bash`-only arming, and a resume that skips Stage 2 never meets the bullet where that requirement lives, so this is the one place it binds a resumed run, and without it the Cross-Session Recall invariant enforces nothing outside Bash for the whole session while every log line says the hooks are armed. The latch is *re-written* by re-running Stage 1's latch step (`references/ingest-and-scope.md`, its `mem_recall.py latch` command) with this invocation's own run id, minted first by Stage 1's convention and logged. A resume never reuses an id an earlier invocation logged: the run's record file is named after it and never rewritten, so a reused id turns this run's Finalize write into `skipped-existing` and loses its record. It is re-written because every terminal removes it with `mem_recall.py unlatch` (Stage 6 at every close-out), and the PreToolUse hook reads an absent latch as "no run active" and stops gating recall entirely. A latch already on disk whose `run_id` is not this run's is **another run's (or a spawning wrapper's) artifact, never evidence**: re-latch from this run's own measurement, which replaces it, and never inherit its `store_ok` colour, because an inherited green latch certifies a store this run never checked. Never delete that latch to make room for this run's: the guard refuses it while a latch is present, and the latch command is what replaces it. The baseline marker is the opposite of the latch, split by which case the resume is, and the test is simply whether `.baseline-<story_id>` exists. **Mid-story (it exists):** *re-read* and never regenerate: the story may already carry commits, and a rebuilt baseline silently re-anchors its evidence range to a mid-story HEAD. **Story boundary (it does not exist**, the NORMAL case under `--max-stories N`, where every invocation after the first resumes at a fresh story): there is nothing to re-read; write it fresh at `HEAD` exactly as step 0 does for a first-run story, because the PreToolUse marker-freshness gate fail-closes without it.
|
|
11
|
+
**On resume, re-enter Execute at the first story whose last logged gate verdict is not advance; advanced stories are not re-run; re-assert (do not rebuild) the Epic branch, hooks, the allowlist, the `.mem-state.json` recall latch, and the in-flight story's baseline marker before continuing**, and read the story's recorded turn count before driving it ("Authoring the `/goal` condition" below says when a resumed count escalates instead). Before the next story's step 0, also check whether the last advanced story's gate evidence is still uncommitted, and if it is, make that evidence commit first, exactly as `references/gate.md`'s "Commit the gate's evidence before the next story starts" describes (and when that story advanced with its count at or past the turn ceiling and no sizing note was logged, log it now, per "Promoting the turn-budget marker"): a resume enters here, before Stage 5 is ever loaded, so this is where that rule has to be met. That story carries an `evidence-commit-rejected` escalation when a repo commit hook rejected that commit in a way the gate may not answer, so run the `--assert-armed` call below with `--story` naming that story first: while its `escalation` reads `open`, make no commit and take the `decision-pending` route below for that story, and once `/ucg-resolve` has closed it (its sidecar is gone, and `.evidence-owed-<story_id>` is still on disk), make the commit and remove that marker. Check every `.evidence-owed-<story_id>` of this Epic's stories this way, not only the last advanced story's: a marker whose evidence was committed some other way is removed as `references/gate.md` says, with no commit. When that story is the Epic's last, so every story reads `done`, no story is left to drive: after the commit go to Stage 6 (`references/finalize.md`) with the Epic-level verdict the log holds, and run neither a story nor the Epic-level gate again. Stage 1 resolved no in-scope story for that resume, so Finalize passes that story as its one `--story` to `scripts/gate_trail.py`, whose range then ends at the commit this resume made, and the run report names the route as the owed evidence commit made and the Epic complete. Before the next story's step 0, or before Stage 6 on that route, remove `.scratch-<story_id>/` of each story of this Epic whose row is already `done` (`references/gate.md`, "Commit the gate's evidence before the next story starts"): a run that stopped after that story's evidence commit, or with nothing staged for it, left the folder there. And "re-assert the hooks" means preflight step 5's assertion, not a presence check: both script paths appear in the resolved settings **and** the PreToolUse group's matcher is the all-tools form (`references/preflight.md`, "Arm the PreToolUse group with a matcher that covers EVERY tool"). A presence-only read passes on a prior run's `Bash`-only arming, and a resume that skips Stage 2 never meets the bullet where that requirement lives, so this is the one place it binds a resumed run, and without it the Cross-Session Recall invariant enforces nothing outside Bash for the whole session while every log line says the hooks are armed. The latch is *re-written* by re-running Stage 1's latch step (`references/ingest-and-scope.md`, its `mem_recall.py latch` command) with this invocation's own run id, minted first by Stage 1's convention and logged. The resume re-runs that latch step alone, never Stage 1's filter call: it reads no prior run, so this invocation consumes no record and Finalize passes no `--advisory` for it (`references/finalize.md`, "Cross-Session Recall write"). A resume never reuses an id an earlier invocation logged: the run's record file is named after it and never rewritten, so a reused id turns this run's Finalize write into `skipped-existing` and loses its record. It is re-written because every terminal removes it with `mem_recall.py unlatch` (Stage 6 at every close-out), and the PreToolUse hook reads an absent latch as "no run active" and stops gating recall entirely. A latch already on disk whose `run_id` is not this run's is **another run's (or a spawning wrapper's) artifact, never evidence**: re-latch from this run's own measurement, which replaces it, and never inherit its `store_ok` colour, because an inherited green latch certifies a store this run never checked. Never delete that latch to make room for this run's: the guard refuses it while a latch is present, and the latch command is what replaces it. The baseline marker is the opposite of the latch, split by which case the resume is, and the test is simply whether `.baseline-<story_id>` exists. **Mid-story (it exists):** *re-read* and never regenerate: the story may already carry commits, and a rebuilt baseline silently re-anchors its evidence range to a mid-story HEAD. **Story boundary (it does not exist**, the NORMAL case under `--max-stories N`, where every invocation after the first resumes at a fresh story): there is nothing to re-read; write it fresh at `HEAD` exactly as step 0 does for a first-run story, because the PreToolUse marker-freshness gate fail-closes without it.
|
|
12
12
|
|
|
13
13
|
**The cursor passes over a decomposed parent.** A story whose row is `done` and whose split is recorded (its split record (`.split-<key>.json` beside `sprint-status.yaml`) names it, a child row cites the parent ACs it claims, or `.decision-log.md` names it and the ACs each child claims) never gets a gate verdict of its own: its children carry its contract, and on its split record the Epic-level roll-up reads their gates in its place (`references/gate.md`). So it is never "a story whose last logged gate verdict is not advance" in the sense above: pass over it and re-enter at the next story, and never drive it. This is the shape a sizing decomposition leaves (below): the invocation that split the row ends without a verdict, the next one re-enters at the first child, since the child rows sit above the parent's, and once every child has advanced the cursor reaches the parent's row and passes over it. A `done` row with no recorded split is not passed over on this rule; Stage 1 rule 3's `skipped-already-done` log is what keeps a fresh run from re-driving one.
|
|
14
14
|
|
|
@@ -34,7 +34,7 @@ Preconditions (asserted, not assumed): you are on the Epic branch (`{workflow.ep
|
|
|
34
34
|
|
|
35
35
|
### Sizing: a story too large to drive
|
|
36
36
|
|
|
37
|
-
**Before step 0 writes any marker, size the row.** Count its acceptance criteria and tasks. **Take that set from the ROW, not from a neighbour's prose.** The `sprint-status.yaml` row is the authority on *which* acceptance criteria a story owes; the story file it cites (its own, or the parent it was split from) is only where those criteria's text lives. A decomposed child has no story file of its own by the convention below, so its contract exists solely as the criteria its row cites. A sibling's ledger entry, or a decision-log entry, names what that sibling **handed off** (a different set, with no reason to be complete), and a scope read from one undersizes the row here and under-delivers it at step 1. Nothing downstream catches that: the trace, the gate-decision file and the gate verdict are all written from this same reading, so they come out green over a missing criterion by construction. When the count is implausible against `{workflow.max_turns_per_story}`, **do not start the story**: decompose it into child rows and terminate the invocation. "Implausible" has a first-pass test, not just a judgment: **when the row's acceptance-criteria count reaches roughly half of `{workflow.max_turns_per_story}`, treat the row as implausible** (13 criteria at the default 25). Count the tasks too, as evidence for the tie-break and the override, but keep them out of the threshold: a task list is how its author sliced the work, and it also holds steps every row pays (reading the skills, running the gates, a step the operator owns). Criteria plus tasks flagged 25 of one real Epic's 30 rows and 4 of another's 5, and nearly every flagged row was then driven whole. The threshold sizes what the story owes; it is not a forecast of turns. The Stop hook counts one turn per response ("Waiting spends turns" below), so the turns a story spends follow how its drive waits, not how many criteria it closes: drives that ran each stage as one delegated workflow took rows of 9 and 13 criteria to their gates in 6 and 7 turns, a 3-criterion row whose sweeps and suite runs each cost turns passed the ceiling twice over, and a `scripts/drive_epic.py` spawn is usually one long response per story. Tie-break against this Epic's own record: the criteria counts of rows already driven cleanly versus rows already split; a row matching an already-split parent's shape is answered by that precedent. The tie-break reads no turn counts. The turns a row spends follow how its drive waits, as above, and no record holds the turns a driven row used: `/ucg-resolve` resets or deletes its `.budget-<story_id>.json` when it closes a `budget-overrun` or `operator-evidence-owed` escalation, and the Stop hook adds each response of a later session to the story `.current-story` still names, so that file, and a count logged from it beside a gate verdict, can hold fewer turns than the row used or more. The judgment word stays as the override in both directions (a count under the threshold can still be implausible when each AC owes an executed artifact; over it can be plausible when the ACs are one-line checklist items), but an override is a recorded reason in `.decision-log.md`, never the whole method: two conductors meeting the same row must be able to reach the same verdict.
|
|
37
|
+
**Before step 0 writes any marker, size the row.** Count its acceptance criteria and tasks. **Take that set from the ROW, not from a neighbour's prose.** The `sprint-status.yaml` row is the authority on *which* acceptance criteria a story owes; the story file it cites (its own, or the parent it was split from) is only where those criteria's text lives. A decomposed child has no story file of its own by the convention below, so its contract exists solely as the criteria its row cites. Any other row with no story file has not been drafted, so it has no criteria to count yet: it fails Stage 3's exit condition, which binds every profile (`references/define-done.md`: every in-scope story has a story file with clear acceptance criteria), and a resume that enters this stage from the log never re-checks it. Send that row alone back to Stage 3, never every in-scope story: Stage 3's `ucg-create-story` drafts its story file (and, in production on a stack ATDD can run on, `bmad-testarch-atdd` scaffolds its red phase) before step 0 writes any marker, and the draft's criteria are then the set this section counts. A sibling's ledger entry, or a decision-log entry, names what that sibling **handed off** (a different set, with no reason to be complete), and a scope read from one undersizes the row here and under-delivers it at step 1. Nothing downstream catches that: the trace, the gate-decision file and the gate verdict are all written from this same reading, so they come out green over a missing criterion by construction. When the count is implausible against `{workflow.max_turns_per_story}`, **do not start the story**: decompose it into child rows and terminate the invocation. "Implausible" has a first-pass test, not just a judgment: **when the row's acceptance-criteria count reaches roughly half of `{workflow.max_turns_per_story}`, treat the row as implausible** (13 criteria at the default 25). Count the tasks too, as evidence for the tie-break and the override, but keep them out of the threshold: a task list is how its author sliced the work, and it also holds steps every row pays (reading the skills, running the gates, a step the operator owns). Criteria plus tasks flagged 25 of one real Epic's 30 rows and 4 of another's 5, and nearly every flagged row was then driven whole. The threshold sizes what the story owes; it is not a forecast of turns. The Stop hook counts one turn per response ("Waiting spends turns" below), so the turns a story spends follow how its drive waits, not how many criteria it closes: drives that ran each stage as one delegated workflow took rows of 9 and 13 criteria to their gates in 6 and 7 turns, a 3-criterion row whose sweeps and suite runs each cost turns passed the ceiling twice over, and a `scripts/drive_epic.py` spawn is usually one long response per story. Tie-break against this Epic's own record: the criteria counts of rows already driven cleanly versus rows already split; a row matching an already-split parent's shape is answered by that precedent. The tie-break reads no turn counts. The turns a row spends follow how its drive waits, as above, and no record holds the turns a driven row used: `/ucg-resolve` resets or deletes its `.budget-<story_id>.json` when it closes a `budget-overrun` or `operator-evidence-owed` escalation, and the Stop hook adds each response of a later session to the story `.current-story` still names, so that file, and a count logged from it beside a gate verdict, can hold fewer turns than the row used or more. The judgment word stays as the override in both directions (a count under the threshold can still be implausible when each AC owes an executed artifact; over it can be plausible when the ACs are one-line checklist items), but an override is a recorded reason in `.decision-log.md`, never the whole method: two conductors meeting the same row must be able to reach the same verdict.
|
|
38
38
|
|
|
39
39
|
Nothing else in this stage covers that case, and the two routes it seems to offer are both wrong. Driving it reaches the turn bound with a baseline marker and a tests-ran marker on disk and no commit, which is exactly the abandoned-mid-story outcome the work bound below exists to avoid. Escalating reaches the same conclusion having first spent the whole budget proving what an AC count showed in five minutes. **A decomposition writes no baseline and no tests-ran marker at all**, so the abandoned-story shape cannot arise from it.
|
|
40
40
|
|
|
@@ -66,7 +66,7 @@ For each in-scope story, in sprint order, run this loop (leave out a decomposed
|
|
|
66
66
|
|
|
67
67
|
**Evidence never goes in scratch.** The scratch directory is removed when the story advances, while the story record and the gate trail (`references/finalize.md`) cite their evidence after that, so the story's evidence has a folder of its own, `{workflow.implementation_artifacts}/evidence-<story_id>/`, which no step removes. The red-phase capture (step 1's, on a stack where Stage 3 could not generate the ATDD scaffold), a sweep log the record or the gate cites, a coupled-stories measurement and a planted-defect run (a case shown red against a defect planted for it) go there; a runner or harness built only to produce them stays in scratch. It holds captured output and the notes recorded on it (the red count `references/gate.md`'s non-web item 4 records beside a red-phase capture), nothing runnable: it has no dot prefix, so on a tracked tree a repo-wide tool can reach it. The mutation ledger keeps its own name-pinned path (step 2). Name each capture by the step that wrote it and the commit `HEAD` named when it ran (`sweep-step2-<short sha>.log`, `sweep-step5-<short sha>.log`, `sweep-backfill-<short sha>.log`), and give a name already taken the next free number (`-2`), so no capture overwrites another: step 2's sweep can run at the `HEAD` the cycle before it measured at step 5 (when that cycle's gate committed no backfill), and the backfill's sweep runs at the `HEAD` step 5 measured. A file already in the folder when step 0 writes a fresh baseline is an earlier run's, never cited as this run's. On a tracked artifact tree the folder stays untracked, as the mutation ledger does: the gate's evidence commit stages its own list of paths, and this folder is not on it.
|
|
68
68
|
|
|
69
|
-
1. `ucg-create-story`
|
|
69
|
+
1. `ucg-create-story` as a refinement of the story file Stage 3 drafted, when that file is not already current (never to draft a missing one: sizing, above, sends a row with no story file back to Stage 3 before step 0) → `ucg-dev-story` implementing the feature and **un-skipping** the story's ATDD acceptance tests (remove `test.skip()`; **production only**): under `--light` there are no ATDD tests to un-skip, so the DoD is the story's acceptance criteria satisfied with lint and build green. The commit guard reads the story's acceptance-test files from the checklist's `generatedTestFiles` frontmatter, so a test file the story adds to hold acceptance cases (a scaffolded file split in two, say) goes into that list as a repo-relative path. **For a decomposed child row, skip `ucg-create-story` entirely**: the child has no story file and must never get one (running the sub-skill would duplicate the contract, which the sizing conventions above forbid); its owed criteria are its sprint-status row comment plus the parent story file it cites by AC number, and the parent file is read for the AC text only, with its Dev Notes as guidance. Pass both story skills `implementation_artifacts` set to `{workflow.implementation_artifacts}` on every call, so the story file and the sprint-status row they touch are the ones this run reads. Hand `ucg-dev-story` the child's input in place of a story path: `story_key` the child's row key, `parent_story_path` the parent's story file, and `claimed_acs` the parent AC ids the child's row claims, taken from the row as the sizing section above requires. On a re-loop, also hand it `review_findings`: the `reasons` of the gate verdict that sent the child back and the findings of that cycle's reviews, which no review can write into a story file the child does not have. Its "Decomposed Child" section keeps it to those ACs, has it write no story file, and has it move only the child's row (to `in-progress`, then `review`), so the parent's row stays `done` and the parent's file unedited. A halt there over a claimed AC takes the sub-skill halt catch-all's route below, naming the parent ACs concerned: never a `ucg-create-story` run for the child, and never an edit to the parent's file. **On a stack where Stage 3 could not generate the ATDD scaffold** (the non-web case), the story still owes a red phase and it is owed **now, before the first implementation edit**: author the acceptance cases with real assertions, RUN them, and capture that run's raw output to a file in `{workflow.implementation_artifacts}/evidence-<story_id>/` ("Evidence never goes in scratch", above). `references/gate.md`'s non-web section is the authority on the shape, but by the time that file is read at Stage 5 the window this rule governs has already closed. Before delegating, check the run's `.decision-log.md` for an **Operator notes** entry naming this story (a pre-launch hint like "watch the auth flow in story 3") and surface that note into the `ucg-dev-story` / review context for this story so the operator's last words actually reach the work. Read `{workflow.implementation_artifacts}/.class-ledger-<epic_id>.md` the same way when it exists (the defect classes this Epic's reviews have already caught, appended by the gate's re-loop route, `references/gate.md`) and surface it into the same context: a class named there is a class the reviewers will look for again, and code written blind to it is a re-loop pre-booked. (A story otherwise inherits nothing from its siblings' reviews: a measured run re-found the previous story's review finding on its very first cycle, so the ledger is the one artifact that crosses that boundary.)
|
|
70
70
|
**On a gitignored artifact tree** (`impl_artifacts_tracked: false`, which preflight step 1 reports and a resumed session reads in its `--assert-armed` manifest's `checks`), no test this story writes or un-skips may read a file under that tree, or any other path `git check-ignore` reports, at run time: it does not exist in CI. Point the test at a tracked fixture instead. Preflight step 2 states the rule ("A gitignored artifact tree"); a session that resumed straight into this stage may not have read it.
|
|
71
71
|
|
|
72
72
|
**An operator-evidence AC is not `ucg-dev-story`'s to satisfy.** When the story carries an AC tagged `**Gate-ability:** operator-evidence` (`references/define-done.md`, step 1), say so when you hand it the story: that AC is proven at the gate by a live result a person records (`references/gate.md`), so it builds nothing for it and does not hold the story's completion on it. An AC tagged plain `**Gate-ability:** operator` is not one: it is work `ucg-dev-story` builds like any other AC, which a person or a script then verifies.
|
|
@@ -88,7 +88,7 @@ For each in-scope story, in sprint order, run this loop (leave out a decomposed
|
|
|
88
88
|
|
|
89
89
|
**A re-loop iteration may scope the sweep; the cycle that expects to advance owes the full one.** The first pass through this loop runs the full three-axis sweep above. A story re-entered from a `reloop` verdict may instead run the affected set — the changed package(s) *and their dependents*, computed against the story's last recorded commit (`{workflow.implementation_artifacts}/.commit-<story_id>`, the previous cycle's end marker): e.g. turbo's `--filter=...[<that sha>]`, still cache-defeated, still with raw output printed. Two obligations keep the scoped form honest. **Print the resolved package list** — the runner computes it; copy its own output into the transcript and the marker's `packages=` line, because a wrong baseline ref narrows coverage *silently*, and the printed list is the only place a narrowing shows. And **write the marker with `scope=scoped`**, so the record says which form ran — a scoped sweep reported as a full one is the same class of false claim reviews keep finding elsewhere. When the re-loop believes its findings are closed and the next gate should advance, run the full sweep and write `scope=full`: the gate refuses to advance a story off a `scope=scoped` marker (`references/gate.md`, the sweep-scope AND), so a scoped cycle that unexpectedly goes fully green costs one extra full-sweep cycle rather than producing an advance nothing re-proved. When in doubt, run it full — `scope=full` is never wrong, only slower. (Measured, on a seven-cycle story: the whole-repo cache-defeated sweep re-proved untouched packages seven times, roughly six of every eight sweep minutes; this split is that cost's fix, at no loss of gate authority. A repo whose runner cannot compute an affected set simply keeps running the full sweep — the scoped form is an optimisation, never an obligation.)
|
|
90
90
|
|
|
91
|
-
**A wide sweep is also a loaded machine.** Running every language's suite plus the declared gate set, cache-defeating, means suites share a host with concurrent native builds
|
|
91
|
+
**A wide sweep is also a loaded machine.** Running every language's suite plus the declared gate set, cache-defeating, means suites share a host with concurrent native builds, and a case bounded by a wall-clock timeout can fail from contention alone (measured: a 180-second-bounded case took 197s beside a concurrent `cargo test` + clippy + type-check, and 93s alone). A timeout in a wide sweep is therefore not yet a red: re-run that package in isolation before treating it as one, and where the two can be sequenced, do not schedule a long native build beside a wall-clock-bounded suite. Run each isolation run once, on its own (one package at a time, with no other suite or build this run started still running), at the same tree, changing nothing between the sweep and it, cache-defeated, with the test command and time bound the sweep gave that package: a raised bound, an edited test, a cached result or a second attempt proves nothing about contention. Keep that sweep's capture in `evidence-<story_id>/`, and capture the isolation run there too as `isolation-<step>-<short sha>.log`, named by the step whose sweep timed out and the `HEAD` that sweep ran at (`isolation-step2-<short sha>.log`, `isolation-step5-<short sha>.log`, `isolation-backfill-<short sha>.log`), a name already taken getting the next free number ("Evidence never goes in scratch", above): its stem is not `sweep-`, so it is never read as the numbered capture of a second sweep. When that package then passes in isolation, the timeout puts no red in that sweep, so a sweep that ran every task it scheduled and whose only reds were such timeouts is its step's green: step 2 writes its marker from that sweep, and a gate step that writes one after its sweep by its own rule (`references/gate.md`: the backfill's step 3 once its sweep is green, a cap-only re-loop's `scope=full` refresh) writes it from that sweep too; at step 5 the marker stands, and step 5 commits nothing for it. For each such pass, log one `timeout:` line in `.decision-log.md` naming the package, the `HEAD` the sweep ran at, the sweep's capture and the isolation run's capture; the timeout owes no `flaky:` line of its own and no row to `{workflow.deferred_work_path}`, since contention on the host is not deferred work. A sweep that left tasks unrun (a runner that stops at its first failure, turbo without `--continue` say) and whose only reds were timeouts is no green yet: before any isolation run, run it once more at the same tree and scope, cache-defeated, with every task run, captured under the next free number, and read that sweep instead; at the gate's backfill that re-run is no fix, so it counts toward neither of its two fixes. When that package fails in isolation too, the timeout is that sweep's red, and takes its step's route.
|
|
92
92
|
|
|
93
93
|
**A red the story's changes do not explain is not yet a red either.** In any wide sweep this file or `references/gate.md` runs (this step's, step 5's, and each sweep the gate runs as step 5 runs it), a failing case that is not a timeout (the paragraph above rules a timeout) is not yet this story's red when all three of these hold: its test file appears in neither `git diff --name-only --no-renames <the sha in .baseline-<story_id>>` (which lists both sides of a rename) nor `git status --porcelain --untracked-files=all`; its captured failure names no path either command lists; and the output shows the failure's cause inside that test, such as a random value the test draws that hit a string it asserts is absent, or a date or clock boundary. A failure that shows state another test left behind (the order the cases ran in, a shared fixture, a leftover file or port) does not qualify, since this story's own tests can leave that state. For a case that qualifies, keep that sweep's capture, change nothing, and run the same sweep once more at the same tree and scope, cache-defeated, captured under the next free number ("Evidence never goes in scratch", above). Running the case alone does not answer it: a case can pass alone and fail in the sweep on state another test leaves behind. When that second sweep shows no red at all, it is the step's green: log a `flaky:` line in `.decision-log.md` naming the case, its file, the `HEAD` both sweeps ran at (at step 2 the story's changes are uncommitted: they sit on that `HEAD`, untouched between the two sweeps), the cause the output shows and both captures; append a row for the case to `{workflow.deferred_work_path}`, worded as a non-critical finding (`references/gate.md`, "Deferred-work ledger schema"), with `source` `sweep`, `severity` `med`, `story` this story's id, a `reason` naming the case, its file and both captures, a `suggested_action` to fix the test outside this Epic's stories, and `status` `open`; and edit, skip or retry-wrap nothing in that file, which is not this story's to change. Step 2 then writes its marker from that second sweep, and a gate step that writes one after its sweep by its own rule (`references/gate.md`: the backfill's step 3 once its sweep is green, a cap-only re-loop's `scope=full` refresh) writes it from that second sweep too. At step 5 nothing has changed, so commit nothing (the guard refuses a commit whose staged index is empty): the marker stands as it does after a green first try. A timeout in the second sweep still takes the paragraph above first, as a timeout in any wide sweep does, before it is read as that sweep's red. When that package then passes in isolation, the timeout puts no red in the second sweep, and the `flaky:` line and the ledger row cite that isolation run's capture beside both sweeps' captures. Any red in the second sweep, in that case or in another, is a red, and takes its step's route.
|
|
94
94
|
|
|
@@ -107,7 +107,7 @@ uv run {skill-root}/scripts/claim_check.py --message {workflow.implementation_ar
|
|
|
107
107
|
|
|
108
108
|
The second `--message` is there because the record names files the message may only describe. Its `not_in_diff` lists the paths it reads as named in either text that the staged diff does not touch, each a claim about the tree that needs no judgment to refute; paths git ignores (the mutation ledger the record cites, a story file under an ignored artifact tree) are listed apart, in `ignored`, since no commit can carry them. A record names its own artifacts from the folder that holds them (`sweep.sh`, `red-phase/INDEX.md`), so the command names three folders with `--artifacts-root` (the run folder, this story's scratch folder and its evidence folder) and a fourth with `--tea-config`, the TEA test-artifacts root that holds `atdd-checklist-<story_id>.md`, resolved from the TEA config as preflight resolves it (`scripts/preflight_check.py`, `_tea_artifacts_root`), and such a name is read there: one that does not exist from `{project-root}` but exists in one of them lands in `ignored` when each copy that holds it is either ignored by git or outside the work tree, and in `not_in_diff` otherwise; one that exists from `{project-root}`, that a file the tree holds could be, or that is in none of them, is read from `{project-root}` as before. A file this commit claims and never wrote, named bare, under a folder the tree does not hold, or under an empty or ignored-only folder inside an untracked one (git lists only the topmost untracked folder), cannot be told from an artifact of that name, so a copy in one of the folders reads it as the copy: the hunk pass below, which finds the hunk for each edit the message or the notes say this commit makes, is what catches it. For each path in `not_in_diff`: stage it if this commit changed it; if the work tree shows no change there, the edit did not happen, so make it or remove the claim; and reword the message or correct the story record itself (not only its scratch copy) when the text says this commit changed a file it did not. A path under this story's `.scratch-<story_id>/` or `evidence-<story_id>/` is never staged, since both folders stay untracked: the record names it on purpose, as its own evidence, and it may stay listed. A text may name an unchanged file on purpose, if it says so. Run the check again until every path left in `not_in_diff` is one a text names on purpose and says so. Then make one pass over the claims the diff itself adds (its new comment and header lines, the story's new completion notes) and each line of the message, for a superlative or a property: "exactly", "every", "always", "cannot", "not X but Y", "composed", or a claim that something exists or does not exist yet. Each one either cites evidence this cycle already produced (a test, a mutation row, a printed measurement) or is softened to what that evidence shows; start no new run to back a sentence, since the usual fix is to weaken the sentence, not to strengthen the code. In the same pass, read `git diff --cached` once and find the hunk for each edit the message or the notes say this commit makes ("now says", "narrowed", "landed", "fixed"), path or no path: an edit described by its content has a path too, and an edit whose script failed leaves no hunk. And look for a claim this commit makes false without touching it: a forward reference to what it lands in a comment or doc elsewhere in the tree. Search the project's own files with the Grep tool, case-insensitive, for this story's id, "does not exist yet" and "owed by", and for the name of each file the commit adds, leaving out the installed skill, the run folder and this story's own record and tests; correct a hit only when it refers to what this commit lands, in this commit, staged with this story's paths, unless a sibling story's uncommitted edits share its file, in which case log it to `.decision-log.md` for that story instead. Re-stage every file this pass edited, in its own `git add` call, then commit from the message file (`-F`). Run the same check before any re-commit step 5 makes, and before an amend with `--amend` added, on every run for that amend, a reword's re-run included: it compares the texts with what the amend would commit (the index against `HEAD`'s first parent, or the empty tree at a root commit), so a path the amended commit already carries from `HEAD` stays out of `not_in_diff`, and for that amend the hunk pass reads `git diff --cached <base>`, with the `base` the check printed.
|
|
109
109
|
|
|
110
|
-
5. **Re-verify on the committed HEAD.** Re-run the authoritative suite (tests + lint + build, the same scope step 2 ran this cycle: all three axes including the declared gate set when full; the same resolved package set when this re-loop cycle legitimately ran scoped, per step 2's re-loop rule) on the just-committed, clean tree and **PRINT** the result before advancing. **Run it cache-defeating.** Committing changes a file's git *tracking state* and not one of its bytes, so a content-addressed cache key is unchanged and this re-run replays the pre-commit answer verbatim, observing nothing: eight of eight tasks reported cached, returning in 719ms immediately after a commit, is the whole failure. Pass `--force` (or invoke the package's runner directly), because the one thing this step must actually execute is the tracked-file gates against the newly tracked fileset. Step 2's marks show a story's **new** files to a **conformance gate scoped to *tracked* files** (a `git ls-files`-based ref/ownership/architecture-boundary check) before the commit, but three kinds of new file still hide from it there, so the gate skips them and reports green at step 2, then reds the instant the commit tracks them: a generated or `.gitignore`d file, which no mark can reach; a file created after step 2's last mark; and, for a gate that reads the staged content (one built on git grep --cached, say), every new file, since a mark holds an empty blob. This committed tree is the exact fileset CI and the Stage-5 gate will see, so a story that is green pre-commit but red here is a **false green** the pre-commit run and any transcript-only evaluator (a `/goal` an operator started, say) both miss. A red step 2 reads as not yet a red (a timeout on a loaded machine, or a red the story's changes do not explain) is read that way here too: a red the story's changes do not explain whose second sweep shows no red leaves this step green, with nothing committed. A red means the story is **not** done: remediate, write a fresh `.tests-ran-<story_id>` marker, and re-commit (amend or a follow-up within the story boundary) until the committed HEAD is green, and only then advance. **That fresh marker carries the same `baseline=<sha>` line as step 2's**: the verbatim, whitespace-stripped content of `{workflow.implementation_artifacts}/.baseline-<story_id>`, **copied, never re-derived from `git rev-parse HEAD`**. The story's baseline has not moved; HEAD has, because step 4 just committed. Re-deriving it here would re-anchor the story to that commit and quietly retire the freshness net for the rest of it, which is the very replayed-marker hole the line exists to close, and without the line the guard denies the re-commit outright, so a story that legitimately needs remediation could never close. The fresh marker also re-states `scope=` (and `packages=` when scoped) to match what THIS re-verify actually ran, because the `scope=` line the gate will read through `--tests-ran` is the one written here, not step 2's. **Rewrite `{workflow.implementation_artifacts}/.commit-<story_id>` from `git rev-parse HEAD` once this step's HEAD is green**, in step 4's format: every time, including when nothing was remediated, because an amend replaces the SHA step 4 recorded and a follow-up commit moves it. This marker is the one step-0 artifact whose rule is *refresh*, not *keep*: the baseline names where the story started and must never move, this one names where it ended and must never be stale. That re-commit carries the SAME staging rule as step 4: stage in a prior, SEPARATE tool call (`git add <this story's paths>`), then run the commit (or `git commit --amend`) as a second, distinct call. `git commit -a` and a chained `git add … && git commit` are unsupported here too: the staged index is still empty when the guard pre-evaluates the command string, so the re-commit is denied.
|
|
110
|
+
5. **Re-verify on the committed HEAD.** Re-run the authoritative suite (tests + lint + build, the same scope step 2 ran this cycle: all three axes including the declared gate set when full; the same resolved package set when this re-loop cycle legitimately ran scoped, per step 2's re-loop rule) on the just-committed, clean tree and **PRINT** the result before advancing. **Run it cache-defeating.** Committing changes a file's git *tracking state* and not one of its bytes, so a content-addressed cache key is unchanged and this re-run replays the pre-commit answer verbatim, observing nothing: eight of eight tasks reported cached, returning in 719ms immediately after a commit, is the whole failure. Pass `--force` (or invoke the package's runner directly), because the one thing this step must actually execute is the tracked-file gates against the newly tracked fileset. Step 2's marks show a story's **new** files to a **conformance gate scoped to *tracked* files** (a `git ls-files`-based ref/ownership/architecture-boundary check) before the commit, but three kinds of new file still hide from it there, so the gate skips them and reports green at step 2, then reds the instant the commit tracks them: a generated or `.gitignore`d file, which no mark can reach; a file created after step 2's last mark; and, for a gate that reads the staged content (one built on git grep --cached, say), every new file, since a mark holds an empty blob. This committed tree is the exact fileset CI and the Stage-5 gate will see, so a story that is green pre-commit but red here is a **false green** the pre-commit run and any transcript-only evaluator (a `/goal` an operator started, say) both miss. A red step 2 reads as not yet a red (a timeout on a loaded machine, or a red the story's changes do not explain) is read that way here too: a red the story's changes do not explain whose second sweep shows no red leaves this step green, with nothing committed. A red means the story is **not** done: remediate, write a fresh `.tests-ran-<story_id>` marker, and re-commit (amend or a follow-up within the story boundary) until the committed HEAD is green, and only then advance. **That fresh marker carries the same `baseline=<sha>` line as step 2's**: the verbatim, whitespace-stripped content of `{workflow.implementation_artifacts}/.baseline-<story_id>`, **copied, never re-derived from `git rev-parse HEAD`**. The story's baseline has not moved; HEAD has, because step 4 just committed. Re-deriving it here would re-anchor the story to that commit and quietly retire the freshness net for the rest of it, which is the very replayed-marker hole the line exists to close, and without the line the guard denies the re-commit outright, so a story that legitimately needs remediation could never close. The fresh marker also re-states `scope=` (and `packages=` when scoped) to match what THIS re-verify actually ran, because the `scope=` line the gate will read through `--tests-ran` is the one written here, not step 2's. **Rewrite `{workflow.implementation_artifacts}/.commit-<story_id>` from `git rev-parse HEAD` once this step's HEAD is green**, in step 4's format: every time, including when nothing was remediated, because an amend replaces the SHA step 4 recorded and a follow-up commit moves it. This marker is the one step-0 artifact whose rule is *refresh*, not *keep*: the baseline names where the story started and must never move, this one names where it ended and must never be stale. That re-commit carries the SAME staging rule as step 4: stage in a prior, SEPARATE tool call (`git add <this story's paths>`), then run the commit (or `git commit --amend`) as a second, distinct call. `git commit -a` and a chained `git add … && git commit` are unsupported here too: the staged index is still empty when the guard pre-evaluates the command string, so the re-commit is denied. When `{workflow.backfill_sweep}` is `scoped`, capture this step's sweep in `evidence-<story_id>/` as `sweep-step5-<short sha>.log` ("Evidence never goes in scratch", above): the gate's scoped backfill sweep builds on that capture and names it (`references/gate.md`, "A backfill of test files alone may scope its sweep"), and without it the gate runs the full sweep. No marker this file writes carries a `sweep=` line.
|
|
111
111
|
|
|
112
112
|
**Sub-skill halt catch-all.** If any orchestrated sub-skill blocks on interactive input mid-run, treat it as escalate for that story: write the typed escalation sidecar `{workflow.implementation_artifacts}/escalation-<story_id>.json` (shape below, under "Escalation sidecar") and stop; do not answer its prompt blind. A sub-skill that is not installed at all (the Skill tool does not know its name) takes the same route: escalate, and never substitute another skill (`bmad-build`, `bmad-build-auto`, or BMAD's deprecated `bmad-create-story` and `bmad-dev-story` for UCG's story skills) or hand-author the work it would have produced.
|
|
113
113
|
|
|
@@ -165,7 +165,9 @@ It is a single JSON object, exactly these four string fields and no fifth:
|
|
|
165
165
|
|
|
166
166
|
One object, never an array: the file is already named per story, so a list would only re-encode the story id inside a file that carries it in its name.
|
|
167
167
|
|
|
168
|
-
`kind` is **open vocabulary**. A reader renders whatever string it finds and never validates it against a fixed list, in particular never against the red-kind vocabulary the semantic scan returns in `references/preflight.md`, which classifies *planning-artifact* reds and has no term for anything that happens at run time. `budget-overrun` is a live `kind` and sits deliberately outside that vocabulary; a reader that validated against it would silently drop the most common escalation there is. `operator-evidence-owed` is a live `kind` too: the story is delivered and gated except evidence only a person can record (`references/gate.md`). So is `evidence-commit-rejected`: the story advanced, and a repo commit hook rejected its evidence commit in a way the gate may not answer, so that evidence waits, uncommitted, for the operator (`references/gate.md`'s advance route). So is `coupled-stories`: the earlier of two stories that are green only together owes clauses only the later story's build satisfies, and moving them narrows its AC, which only the operator may rule on (the story loop's "Two stories green only together").
|
|
168
|
+
`kind` is **open vocabulary**. A reader renders whatever string it finds and never validates it against a fixed list, in particular never against the red-kind vocabulary the semantic scan returns in `references/preflight.md`, which classifies *planning-artifact* reds and has no term for anything that happens at run time. `budget-overrun` is a live `kind` and sits deliberately outside that vocabulary; a reader that validated against it would silently drop the most common escalation there is. `operator-evidence-owed` is a live `kind` too: the story is delivered and gated except evidence only a person can record, or the gate could not check that, because the operator-evidence check could not read trace's coverage matrix or the check after a move refused (`references/gate.md`). So is `evidence-commit-rejected`: the story advanced, and a repo commit hook rejected its evidence commit in a way the gate may not answer, so that evidence waits, uncommitted, for the operator (`references/gate.md`'s advance route). So is `coupled-stories`: the earlier of two stories that are green only together owes clauses only the later story's build satisfies, and moving them narrows its AC, which only the operator may rule on (the story loop's "Two stories green only together").
|
|
169
|
+
|
|
170
|
+
**An escalated story keeps no gate build.** The gate carries its worktree's build folders into `<stash>` only for a story it will gate again (`references/gate.md`, the first caveat under "Measure the commit, not the working tree", which says what `<stash>` is), and an escalation stops the story instead, whatever route it came by. So whenever you are about to write this sidecar and `<stash>` holds a build folder, run `uv run {skill-root}/scripts/carry_build_cache.py drop --stash <stash>` right before you write it, so a session that ends between the two leaves no build behind a story it escalated. It deletes each folder `<stash>` holds, never through a link, and prints what it deleted, skipped and failed to delete; log that in `.decision-log.md` beside the escalation. The story's re-gate, once the operator answers, builds cold.
|
|
169
171
|
|
|
170
172
|
**Promoting the turn-budget marker.** The `budget_stop.py` Stop hook writes only its own markdown, `{workflow.implementation_artifacts}/.escalation-<story_id>.md`. It stays a recorder: it emits no JSON and starts no process, and its marker records a count without stopping the drive, so the story still goes on to its gate. **Execute is the sole promoter of that markdown, and the story's gate decides whether it promotes.** A marker counts only while the story's recorded count (`turns` in `{workflow.implementation_artifacts}/.budget-<story_id>.json`) is at or past `{workflow.max_turns_per_story}`: after `/ucg-resolve` closes a `budget-overrun` escalation and resets that counter, the marker left on disk is the answered escalation's residue, and nothing below applies to it. **When the gate advances the story (`advance`, or `defer`, whose route advances anyway), do not promote the marker.** The gate decides completion, and none of the decisions the marker asks for has anything left to act on once the story is done: in a real project, every overrun escalation written for a story that then passed its gate was left open and never answered. Log a sizing note in `.decision-log.md` instead, naming the story and the hook's count against `{workflow.max_turns_per_story}`; Finalize's run report carries it. The note records the turns the drive spent, and never says a row of this shape should be split: sizing reads a row's criteria, never its turns ("Sizing: a story too large to drive" above), and the turns follow how the drive waited. **When the gate escalates the story on the turn count** (a re-loop that would exceed the ceiling, which `references/gate.md` turns into `escalate`), promote the marker as that escalation's sidecar: read the `.escalation-<story_id>.md` the hook left behind and write the typed sidecar from it, mapping `source` to that markdown's path, `kind` to `budget-overrun`, `decision_needed` to the human decision the marker asks for (re-scope, split, or hand off), and `evidence` to one line quoted from the marker. The gate can escalate on the count before the hook has written a marker (a re-loop expected to take several responses, from a count still under the ceiling); write the same `budget-overrun` sidecar then from `{workflow.implementation_artifacts}/.budget-<story_id>.json`, with `source` that file's path and `evidence` its count, so `/ucg-resolve` still resets the counter when it closes it. A cap-only `reloop` (a sweep-scope or delta cap) is not that verdict: the full re-gate it leads to decides. A story that escalates for its own reason (a gate file that cannot be read, a sub-skill halt) keeps that reason's sidecar, and the marker's count goes into the decision log beside it. A resume that finds the count already at or past the ceiling escalates before step 0 with the same `kind`, as "Authoring the `/goal` condition" above says. Keeping promotion here means one code path produces the typed JSON whatever the escalation's origin, instead of two writers racing on a file three readers depend on.
|
|
171
173
|
|
|
@@ -211,7 +213,7 @@ When the prior snapshot's `budget_used.turns` and the current `.budget-<story>.j
|
|
|
211
213
|
|
|
212
214
|
Before the Stop hook has fired for a story, no `.budget-<story>.json` exists yet. That is a normal early-story state, not an error: render `budget_used` as `{"turns": 0, "max_turns": <the resolved ceiling>}` and write the snapshot anyway — an absent hook file is never a reason to skip the write, defer it, or leave the heartbeat partially written.
|
|
213
215
|
|
|
214
|
-
**A resume writes its first heartbeat at re-entry, before step 0 of the story it is about to drive
|
|
216
|
+
**A resume writes its first heartbeat at re-entry, before step 0 of the story it is about to drive**: `story` naming that story, its `stories` entry at `phase` `"resuming"`, `verdict` null. Until that write the file still holds the prior invocation's terminal snapshot, and everything a resume does before the loop (branch and hook re-assertion, the latch, a grounding read) is real work during which a poller would otherwise be watching a stale terminal. `budget_used.turns` legitimately stays put through all of it (at `0` for a story not yet driven, at the inherited count for a mid-story resume), because the hook counts only Stops booked to the current story: an unmoved count beside a fresh `updated` is a conductor re-asserting the environment, not a stalled run. The poller's liveness signal is `updated` and `phase`, never `turns` alone.
|
|
215
217
|
|
|
216
218
|
This is the file the Stage 2 launch briefing points the operator at ("where to watch"); Stage 6 (finalize) records the terminal state into it when the run closes, carrying every key above forward rather than overwriting the file with a narrower object.
|
|
217
219
|
|
|
@@ -76,7 +76,7 @@ Whichever case applies, repeat in the run report a `NOTE recall-latch-visible` l
|
|
|
76
76
|
uv run {skill-root}/scripts/mem_observation.py write --impl-artifacts {workflow.implementation_artifacts} --store '{workflow.cross_session_recall_store}' --project-root {project-root} --epic <id> --run-id <run-id> --gate-status <status> --verdict <advance|blocked> --deferred {workflow.deferred_work_path} [--root-cause class=<taxonomy>,path=<artifact>]… [--advisory sig=<record-id>]…
|
|
77
77
|
```
|
|
78
78
|
|
|
79
|
-
Each `--advisory` names one record this invocation's own Stage 1 filter call consumed: `sig` is that record's `id`, the `run_id` of the run that wrote it, copied as given from the attributed advisory Stage 1 logged to `.decision-log.md` (the same `id` the record carries in `recall-filter-<run-id>.json`, when Stage 1 wrote that file). It is never a root-cause signature, a story id or this run's own run id. Pass no `recurred`: the script decides it from the store. It stores `yes` when a root cause whose class is not `other` is in both that record and this run (the same class and artifact path), `no` when that record names such a root cause and this run shares none of them, and `unknown` otherwise: the `id` is not a run id, that record cannot be read or is not this repo's, it names no root cause outside `other`, or this run did not advance and names no root cause (a handoff or a `decision-pending` stop). A matching gate status or verdict is not a recurrence, and preflight's `advisories_checked` status does not feed `recurred`. Pass no `--advisory` on a resume routed into Execute, which makes no filter call, nor when this invocation's filter call was skipped, refused or failed, or consumed no record.
|
|
79
|
+
Each `--advisory` names one record this invocation's own Stage 1 filter call consumed: `sig` is that record's `id`, the `run_id` of the run that wrote it, copied as given from the attributed advisory Stage 1 logged to `.decision-log.md` (the same `id` the record carries in `recall-filter-<run-id>.json`, when Stage 1 wrote that file). It is never a root-cause signature, a story id or this run's own run id. Pass no `recurred`: the script decides it from the store. It stores `yes` when a root cause whose class is not `other` is in both that record and this run (the same class and artifact path), `no` when that record names such a root cause and this run shares none of them, and `unknown` otherwise: the `id` is not a run id, that record cannot be read or is not this repo's, it names no root cause outside `other`, or this run did not advance and names no root cause (a handoff or a `decision-pending` stop). A matching gate status or verdict is not a recurrence, and preflight's `advisories_checked` status does not feed `recurred`. Pass no `--advisory` on a resume routed into Execute, which makes no filter call under `references/execute.md`'s resume rule (that resume re-runs Stage 1's latch step alone), nor when this invocation's filter call was skipped, refused or failed, or consumed no record.
|
|
80
80
|
|
|
81
81
|
Each call prints one JSON object. Log every line in its `notes` to `.decision-log.md` and carry it into the run report: the `mem-` tokens belong to the write path (`WARN mem-write-deferred` when the store could not take the record and it waits in the outbox for a later drain, `WARN mem-write-dead-lettered` when a parked record failed its third write and moved to `mem-outbox.dead.jsonl`, which no drain replays, `NOTE mem-target-foreign`, `NOTE mem-run-id-invalid`, `NOTE mem-legacy-unconvertible`), and `NOTE recall-store-unset` means the store key is unset. Log the write's `status` the same way: `written`, or why no record landed (`skipped-existing`, `deferred`, `foreign-target`, `skip`, `no-fingerprint` or `store-unset`), since some of those print no note. Print the drain's `converted`, `legacy_unconvertible`, `dead_lettered` and `tombstones` counts in the run report too. If the permission layer refuses the drain or the write call, log `NOTE recall-write-refused`, do not retry it, and continue: a refused write never reaches the script, so nothing is parked. If the drain or the write call exits non-zero, log what it printed to `.decision-log.md` and the run report, do not retry it, and go on: to the write after a failed drain, and to the close-out below after a failed write. Recall is advisory, so a failed call never stops the run. The run report always lands; the record is best-effort.
|
|
82
82
|
|