bmad-module-ultracode-goal 4.1.0 → 6.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 +3 -3
- package/docs/architecture.md +1 -1
- package/docs/cross-session-recall.md +1 -1
- package/docs/how-it-works.md +2 -2
- package/docs/troubleshooting.md +10 -3
- package/docs/why-ultracode-goal.md +1 -1
- package/package.json +1 -1
- package/skills/ucg-formalize/SKILL.md +23 -4
- package/skills/ucg-resolve/SKILL.md +76 -18
- package/skills/ultracode-goal/SKILL.md +1 -1
- package/skills/ultracode-goal/references/execute.md +19 -14
- package/skills/ultracode-goal/references/finalize.md +5 -3
- package/skills/ultracode-goal/references/gate.md +8 -8
- package/skills/ultracode-goal/references/preflight.md +12 -4
- package/skills/ultracode-goal/scripts/claim_check.py +340 -15
- package/skills/ultracode-goal/scripts/formalize_check.py +228 -131
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +4 -0
- package/skills/ultracode-goal/scripts/lib/mem_common.py +30 -0
- package/skills/ultracode-goal/scripts/mem_observation.py +85 -10
- package/skills/ultracode-goal/scripts/mutate_check.py +22 -1
- package/skills/ultracode-goal/scripts/preflight_check.py +15 -6
|
@@ -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": "6.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 6.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:** 6.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 `6.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
|
|
package/docs/architecture.md
CHANGED
|
@@ -130,4 +130,4 @@ flowchart LR
|
|
|
130
130
|
|
|
131
131
|
## Why the hooks live in settings.local.json
|
|
132
132
|
|
|
133
|
-
The PreToolUse and Stop hooks are auto-merged into `{project-root}/.claude/settings.local.json` (machine-local, gitignored, honored after the workspace trust dialog), not into a committed settings file or memory. The reasoning: these hooks are **enforcement, not context**. A committed hook would impose this module's commit guard on every contributor and every unrelated session in the repo; a hook in memory would not block a commit at all. The machine-local file scopes enforcement to the machine actually running the unattended Epic, and the gitignore keeps it out of shared history. The skill re-merges them every run (idempotently) and
|
|
133
|
+
The PreToolUse and Stop hooks are auto-merged into `{project-root}/.claude/settings.local.json` (machine-local, gitignored, honored after the workspace trust dialog), not into a committed settings file or memory. The reasoning: these hooks are **enforcement, not context**. A committed hook would impose this module's commit guard on every contributor and every unrelated session in the repo; a hook in memory would not block a commit at all. The machine-local file scopes enforcement to the machine actually running the unattended Epic, and the gitignore keeps it out of shared history. The skill re-merges them every run (idempotently), checks the file, and then proves that the running session runs the guard before the run goes unattended, since Claude Code's file watcher can miss an edit made while a session runs; it does not assume a prior run left them in place. The guard's entry carries `"onFailure": "block"` (Claude Code 2.1.295 and later), so a guard that cannot start, crashes or times out refuses the tool call instead of letting it through: an enforcement layer that fails open when it breaks is no enforcement layer, and the price is that a broken guard stops the session until someone fixes it. Because the file is machine-local and executes on your machine, review what is merged; see [SECURITY.md](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/SECURITY.md).
|
|
@@ -91,7 +91,7 @@ flowchart TD
|
|
|
91
91
|
|
|
92
92
|
Each recall call is attempted once and never retried. A run whose recall turned off along the way says so in its report, with the tokens under [troubleshooting](#troubleshooting).
|
|
93
93
|
|
|
94
|
-
**What a record holds.** The Epic, the run id, the repo fingerprint, the gate status and verdict, the root-cause signatures (each with a class from a fixed taxonomy and an artifact path), the count of deferred items, the advisories the run consumed with whether
|
|
94
|
+
**What a record holds.** The Epic, the run id, the repo fingerprint, the gate status and verdict, the root-cause signatures (each with a class from a fixed taxonomy and an artifact path), the count of deferred items, the advisories the run consumed, each named by the run id of the record it read, with whether that record's root cause recurred (`yes` when a root cause outside the `other` class is in both records, `no` when that record names one and this run shares none, `unknown` otherwise), the time, and the project's folder name for display. Free text is redacted before it is written. A run that blocked with no gate status (it escalated or handed off before a gate ran, or its gate could not be read) writes a record with gate status `NOT_EVALUATED` and verdict `blocked`, so the next run sees that it blocked; a `WAIVED` outcome is written too. A resume that stops because the story's escalation is still open names no root cause in its record: the run that raised the escalation recorded it, so stopping again on one unanswered decision does not count as recurring. `NOT_EVALUATED` with any other verdict writes no record.
|
|
95
95
|
|
|
96
96
|
**When the store cannot take a record.** The record waits in `mem-outbox.<run_id>.jsonl` in the implementation artifacts folder, and the run logs `WARN mem-write-deferred`. The next run that reaches Finalize with a green latch drains it, keeping its original time. A deferred record older than 14 days is dropped, and one whose drain fails three times moves to `mem-outbox.dead.jsonl`, with `WARN mem-write-dead-lettered`. No drain replays that file.
|
|
97
97
|
|
package/docs/how-it-works.md
CHANGED
|
@@ -70,7 +70,7 @@ This is the load-bearing gate, because after it the run goes unattended. The pos
|
|
|
70
70
|
2. **Auto-remediation pass**: clear each remediable blocker, then re-run the check so `budget` reflects the fixes: create the Epic branch when the run started on a protected branch (it is a remediable, budget-counted blocker, so it has to clear here rather than at arming), scaffold the test framework (`bmad-testarch-framework`), scaffold the CI quality pipeline (`bmad-testarch-ci`, production only, strictly *after* the framework), generate missing acceptance criteria (`ucg-create-story`), pre-create the TEA output dirs, de-duplicate `project-context.md` when there is more than one (a missing one is logged, never generated), ensure `sprint-status.yaml` is present, force TEA **Create** mode, and prompt once (interactively) for any secrets.
|
|
71
71
|
3. **Semantic intervention scan**: the part the script cannot do: read the PRD and ADR for undecided product/architecture decisions, contradictions, acceptance criteria that presuppose an unmade decision, or a story whose "done" is undefinable. Any such item is **RED** and cannot be auto-remediated, because the fix is a human decision.
|
|
72
72
|
|
|
73
|
-
The run launches **only** when all hold: post-remediation `budget == 0`, the semantic scan found no RED, and ultracode session effort plus Auto Mode are on. Then the skill arms the environment: asserts the Epic branch off `epic_branch_prefix` (already created during remediation when the run started on a protected branch), merges the PreToolUse and Stop hooks into `.claude/settings.local.json` (
|
|
73
|
+
The run launches **only** when all hold: post-remediation `budget == 0`, the semantic scan found no RED, and ultracode session effort plus Auto Mode are on. Then the skill arms the environment: asserts the Epic branch off `epic_branch_prefix` (already created during remediation when the run started on a protected branch), merges the PreToolUse and Stop hooks into `.claude/settings.local.json` (checking the file, and injecting the resolved config into their env), pre-populates the allowlist, and then proves the session runs the hooks: one `git commit --dry-run`, which creates no commit, must be refused by the guard, or preflight stops. On an attended run it prints the launch briefing and takes one soft confirm. See [`references/preflight.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/preflight.md).
|
|
74
74
|
|
|
75
75
|
### Stage 3: Define Done
|
|
76
76
|
|
|
@@ -78,7 +78,7 @@ Turn the Epic's acceptance criteria into **executable, red-phase acceptance test
|
|
|
78
78
|
|
|
79
79
|
### Stage 4: Execute
|
|
80
80
|
|
|
81
|
-
Drive each in-scope story from its red-phase tests to a green, committed state. Execution is the **sequential `/goal` spine**; per story, in sprint order: set the current story (so the PreToolUse hook can find its marker) → `ucg-dev-story` implements the feature and un-skips the story's ATDD tests → run tests/lint/build and **print the raw output** as evidence → (production) `bmad-testarch-test-review` then `bmad-code-review` → check the commit message against the staged diff (`claim_check.py` lists each path it names that the commit does not touch) and soften any claim the diff's own new lines make that no evidence shows → commit at green (one implementation commit per green story; the gate's commits follow it: a test backfill when automate makes one, then the evidence) → **re-run the suite at this cycle's scope on the committed HEAD (a story only advances off a full-scope sweep)** and print it, because a story's new files are untracked until the commit, so a tracked-files conformance gate can only red once they land; a red here means the story is not done and must be remediated and re-committed before it advances. The conductor writes a per-story `/goal`-style condition that encodes the Definition-of-Done and carries the literal "…or stop after N turns" escape clause, and records it in the decision log. A live `/goal` runs only when you start one, on your own condition, because the conductor cannot start `/goal` itself. The Stop hook records a turn count, once per response, which the conductor reads before each story and each re-loop. The printed evidence keeps the run judgeable mid-flight, but **passing the `/goal` condition is not completion**; the authoritative verdict is Stage 5. As the spine advances it overwrites a `run-status.json` heartbeat for pollers. See [`references/execute.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/execute.md).
|
|
81
|
+
Drive each in-scope story from its red-phase tests to a green, committed state. Execution is the **sequential `/goal` spine**; per story, in sprint order: set the current story (so the PreToolUse hook can find its marker) → `ucg-dev-story` implements the feature and un-skips the story's ATDD tests → run tests/lint/build and **print the raw output** as evidence → (production) `bmad-testarch-test-review` then `bmad-code-review` → check the commit message against the staged diff (`claim_check.py` lists each path it names that the commit does not touch) and soften any claim the diff's own new lines make that no evidence shows → commit at green (one implementation commit per green story; the gate's commits follow it: a test backfill when automate makes one, then the evidence) → **re-run the suite at this cycle's scope on the committed HEAD (a story only advances off a full-scope sweep)** and print it, because a story's new files are untracked until the commit, so a tracked-files conformance gate can only red once they land; a red here means the story is not done and must be remediated and re-committed before it advances, except that a red in a case outside the story's changes, whose cause shows inside that test, and that a second sweep at the same commit does not repeat, is logged as flaky and parked on the ledger, with nothing committed. The conductor writes a per-story `/goal`-style condition that encodes the Definition-of-Done and carries the literal "…or stop after N turns" escape clause, and records it in the decision log. A live `/goal` runs only when you start one, on your own condition, because the conductor cannot start `/goal` itself. The Stop hook records a turn count, once per response, which the conductor reads before each story and each re-loop. The printed evidence keeps the run judgeable mid-flight, but **passing the `/goal` condition is not completion**; the authoritative verdict is Stage 5. As the spine advances it overwrites a `run-status.json` heartbeat for pollers. See [`references/execute.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/execute.md).
|
|
82
82
|
|
|
83
83
|
### Stage 5: Gate
|
|
84
84
|
|
package/docs/troubleshooting.md
CHANGED
|
@@ -48,6 +48,8 @@ flowchart TD
|
|
|
48
48
|
- **Story skills not installed.** The run delegates story creation to `ucg-create-story` and implementation to `ucg-dev-story`, the story skills UCG ships in place of BMAD Method's deprecated `bmad-create-story` and `bmad-dev-story`. UCG's installer copies them beside the `ultracode-goal` skill, so a missing one means a partial or older UCG install, or an install from the plugin marketplace alone, which ships only the `ultracode-goal` skill. The `story_skills` blocker is non-remediable: the run neither installs them nor works around them. Its detail names the fix, `npx bmad-module-ultracode-goal update` from the project root (`install` where UCG was never installed there). BMAD's own shims, installed with `--shims`, do not satisfy it (see [Prerequisites](./getting-started.md#prerequisites)). The same check runs on every resume, so a story skill deleted mid-Epic, by hand or by an install interrupted while it re-copies the UCG skills, stops the next spawn instead of letting it improvise.
|
|
49
49
|
- **TEA skills not installed.** The run delegates test design, acceptance tests, review and the gate to TEA's `bmad-testarch-*` skills. Production needs all eight. `--light` needs three: `bmad-testarch-framework`, `bmad-testarch-test-design` and `bmad-testarch-trace`. The `tea_skills` blocker is non-remediable: the run never installs TEA. UCG supports BMAD 6 with TEA 1.27.x, which BMAD Method 6.12.2 and later install. Add or repair TEA from the project root with `npx bmad-method install`, with the `tea` module selected, then re-run. If the detail says it found `bmad-tea-*` skills instead, the project has TEA 3.0 or later, which renamed the skills UCG calls. UCG does not support it yet: install TEA 1.27.x through BMAD 6 instead (see [Prerequisites](./getting-started.md#prerequisites)). Preflight checks skill names, not the TEA version. TEA 2.x moved to BMAD 7's module format but kept the `bmad-testarch-*` names, so preflight does not catch it, though UCG does not support it either. Preflight checks these skills at launch only. A TEA skill removed mid-Epic escalates the story that calls it.
|
|
50
50
|
|
|
51
|
+
- **This session does not run the hooks.** Preflight's last arming step proves that the session runs the hooks it wrote, and stops before the launch when it does not. See [Hooks not firing](#hooks-not-firing).
|
|
52
|
+
|
|
51
53
|
The decision log carries the full blocker list with what each needs to clear. Read it, clear the items, re-run.
|
|
52
54
|
|
|
53
55
|
## gate_eval reports blocked / escalate on a missing gate-decision.json
|
|
@@ -75,12 +77,17 @@ A per-story gate can return `reloop` with a `PASS` gate status when a cap fired
|
|
|
75
77
|
|
|
76
78
|
## Hooks not firing
|
|
77
79
|
|
|
78
|
-
**Symptom.** A commit lands on a protected branch, or a commit lands before a story's tests ran: the invariants the PreToolUse hook should enforce did not block.
|
|
80
|
+
**Symptom.** A commit lands on a protected branch, or a commit lands before a story's tests ran: the invariants the PreToolUse hook should enforce did not block. Or preflight stops before the launch, saying the hooks are in `.claude/settings.local.json` and this session does not run them.
|
|
79
81
|
|
|
80
82
|
**What to check.**
|
|
81
83
|
|
|
82
84
|
- **Older Claude Code.** The hook returns a `deny` decision in the hook JSON and *also* exits 2 with the reason on stderr precisely so older clients that ignore the JSON still block. If neither path fired, the client may not be honoring PreToolUse hooks at all. Update Claude Code.
|
|
83
|
-
- **`settings.local.json` not merged.** The hooks are merged into `{project-root}/.claude/settings.local.json` at preflight,
|
|
85
|
+
- **`settings.local.json` not merged.** The hooks are merged into `{project-root}/.claude/settings.local.json` at preflight. Before going unattended, preflight checks the file, then proves this session runs them with one `git commit --dry-run` that the guard must refuse. If the file wasn't merged (or the workspace trust dialog wasn't accepted), the hooks aren't loaded. Re-run preflight; verify the two hook entries are present in the resolved settings.
|
|
86
|
+
- **Hooks written while the session ran, and not loaded.** Preflight writes the hooks while Claude Code runs, and Claude Code's file watcher normally picks that edit up but can miss it. Preflight's probe catches this: its `git commit --dry-run` creates no commit, a guard the session runs refuses it with `Tests-ran guard: refusing` and `current story (unknown)`, and when it is not refused twice, preflight stops. Attended, it asks you to quit Claude Code and resume the conversation with ultracode effort and Auto Mode on, as you launched it, since a resumed session takes the effort and the mode its launch sets, and then to say continue: `claude --continue --effort ultracode --permission-mode auto` in the project resumes the most recent conversation, `claude --resume` with the same two flags lets you pick this one when another in the project is more recent, or reopen it in the desktop app. The resumed session reads the file as it starts. When either setting is off there, preflight names it and asks you to turn it on and say continue. A headless run stops with a RED blocker: invoke it again, since a new session reads the file as it starts. In the session, `/hooks` lists the hooks it loaded.
|
|
87
|
+
- **A setting that keeps the file's hooks from running.** When a resumed or a new session still does not refuse the probe, something other than the file watcher keeps the hooks from running: `disableAllHooks` set in another settings layer or in a `--settings` file, `allowManagedHooksOnly` in managed settings, a `--setting-sources` that leaves out `local`, or `--bare`, which skips hooks. Clear it, check that `/hooks` lists the guard, then invoke the run again.
|
|
88
|
+
- **A story set in Claude Code's environment.** A guard that runs can also let the probe through: with `ULTRACODE_STORY_ID` in the environment Claude Code runs hooks with, naming a story whose tests-ran marker is fresh, and something staged, the guard allows the call, and preflight reads that as a session that does not run the hooks. Unset the variable where you start Claude Code, start it again, then invoke the run again.
|
|
89
|
+
- **The probe refused for another reason.** Any guard reason other than `Tests-ran guard: refusing` with `current story (unknown)` means a guard runs but reads a story or a branch this run did not set: an `ULTRACODE_STORY_ID` in the environment Claude Code runs hooks with, or a guard from an earlier arming still loaded with another implementation-artifacts folder. For the variable, unset it where you start Claude Code, then start Claude Code again; for an earlier arming, quit and start Claude Code again so it loads the file this run wrote. Then invoke the run again.
|
|
90
|
+
- **A refusal from another hook.** A probe result that names another hook's command in brackets and holds no guard reason, such as `PreToolUse:Bash hook error: [<its command>]: <its stderr>`, is that hook's refusal, so the guard did not refuse the call. Check `/hooks` for the guard, as the bullets above say.
|
|
84
91
|
- **A `customize.toml` override that silently no-ops.** Both hooks read config from env first and fall back to hardcoded defaults (`main`/`master`, `25`, `ultracode/epic-`). A `protected_branches` or turn-budget override in `customize.toml` only reaches the hook if preflight injected it into the hook env (`ULTRACODE_PROTECTED_BRANCHES`, etc.). If your custom protected branch isn't being guarded, the override didn't reach the enforcement layer. Confirm preflight passed it through.
|
|
85
92
|
|
|
86
93
|
## Every tool call is refused
|
|
@@ -95,7 +102,7 @@ A per-story gate can return `reloop` with a `PASS` gate status when a cap fired
|
|
|
95
102
|
- **No Python `uv` can use.** `uv` cannot start a Python the script's header allows.
|
|
96
103
|
- **The guard ran past its timeout.** Claude Code's default for a command hook is 600 seconds; the message then says `timed out`.
|
|
97
104
|
|
|
98
|
-
A refusal the guard makes itself reads differently: it
|
|
105
|
+
A refusal the guard makes itself reads differently: in place of `[<command>]: failed; blocking`, it carries the guard's own reason (`Commit/push guard: …`, `Protected-branch guard: …`, `UltraCode-Goal guard: …`) and names what to fix. That is the guard deciding, not failing.
|
|
99
106
|
|
|
100
107
|
**What you do.** Fix it from outside the session, since the session cannot run a tool:
|
|
101
108
|
|
|
@@ -21,7 +21,7 @@ UltraCode Goal answers each shortcut with a layer the model cannot override, exc
|
|
|
21
21
|
|
|
22
22
|
**1. Deterministic gate truth.** Completion is decided by `scripts/gate_eval.py`, which reads TEA's `gate-decision.json` and maps its gate status to a routing verdict: `PASS`/`WAIVED` advance, `CONCERNS` defers, `FAIL` re-loops, `NOT_EVALUATED` escalates. The script never re-derives TEA's thresholds and never consults the transcript; it reads the artifact as given. The model produces evidence; the script reads the verdict. They are different things on purpose. See the [gate model](./gate-model.md).
|
|
23
23
|
|
|
24
|
-
**2. Hooks as invariants.** The invariants that must hold (no commit on a protected branch, no commit before a story's tests have actually run green, and five more covering marker freshness, an empty staged index, un-skipped acceptance tests, and two for Cross-Session Recall) live in a **PreToolUse** hook, not in memory. The hook inspects each `git commit`/`git push`, and every other tool call while a run latch is present, and denies the call when any of them is violated. It is merged into `.claude/settings.local.json` at preflight and
|
|
24
|
+
**2. Hooks as invariants.** The invariants that must hold (no commit on a protected branch, no commit before a story's tests have actually run green, and five more covering marker freshness, an empty staged index, un-skipped acceptance tests, and two for Cross-Session Recall) live in a **PreToolUse** hook, not in memory. The hook inspects each `git commit`/`git push`, and every other tool call while a run latch is present, and denies the call when any of them is violated. It is merged into `.claude/settings.local.json` at preflight, and preflight proves that the running session runs it before the run goes unattended. A denied commit is enforcement; a remembered rule is not. See [architecture](./architecture.md).
|
|
25
25
|
|
|
26
26
|
**3. Budget enforcement.** This is the one layer that rests on the conductor following a rule. A **Stop** hook tracks turns against `max_turns_per_story` and writes an escalation marker when it is breached, but it never blocks, and it counts once per response, so re-loops inside one response do not move it. The conductor reads that count before each story and each re-loop, and the gate's re-loop budget turns a `reloop` that would exceed it into an `escalate`. A story that passes its gate after an overrun is not escalated: the gate decides completion, and the overrun is logged as a sizing note. A `/goal` condition's literal "…or stop after N turns" clause binds only when an operator starts a `/goal` (the conductor cannot start one itself), and for `drive_epic.py` spawns a `--session-timeout` wall clock is the backstop. See [how it works](./how-it-works.md).
|
|
27
27
|
|
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": "6.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",
|
|
@@ -47,7 +47,19 @@ recomputes the readiness verdict. Each verdict and remediation lands in
|
|
|
47
47
|
for this Epic when one exists (appending a session entry), otherwise create
|
|
48
48
|
`epic-<id>-<UTC yyyymmddThhmmssZ>` for this standalone check. That resolved path is
|
|
49
49
|
what the Headless `decision_log` key carries, so two invocations over the same Epic
|
|
50
|
-
cannot scatter their verdicts across two files.
|
|
50
|
+
cannot scatter their verdicts across two files. Append to the log with Write/Edit,
|
|
51
|
+
never a Bash heredoc: a heredoc puts the log's prose into a Bash command string, and the
|
|
52
|
+
PreToolUse guard's git gates read that string as commands
|
|
53
|
+
(`{ucg-root}/references/execute.md`, step 4, gives the reason). Once the log is too large
|
|
54
|
+
to Read affordably, do not Read it, since both file tools refuse a file this session has
|
|
55
|
+
not Read. Write the entry instead to a new file beside the log,
|
|
56
|
+
`<run folder>/dlog-slice-formalize-<n>.md`, where `<run folder>` is the resolved folder
|
|
57
|
+
above in full and `<n>` is one past the highest number a `dlog-slice-formalize-*.md` in
|
|
58
|
+
it already carries (`1` when there is none), so the name is new for every append. Then
|
|
59
|
+
append it in one Bash call, with both paths in full:
|
|
60
|
+
`cat "<run folder>/dlog-slice-formalize-<n>.md" >> "<run folder>/.decision-log.md"`. Keep
|
|
61
|
+
the slice rather than deleting it: it is the only copy of the entry if the append is
|
|
62
|
+
interrupted.
|
|
51
63
|
|
|
52
64
|
## On Activation
|
|
53
65
|
|
|
@@ -91,7 +103,13 @@ them here. There is one kernel — a second readiness evaluator would let the tw
|
|
|
91
103
|
drift.
|
|
92
104
|
|
|
93
105
|
The kernel is fail-closed: a missing / unreadable / ambiguous artifact is recorded
|
|
94
|
-
as a failing gap, never a neutral pass.
|
|
106
|
+
as a failing gap, never a neutral pass. Of TEA's output it reads only the Epic's own,
|
|
107
|
+
under TEA's test-artifacts root (the TEA config's `test_artifacts`, else
|
|
108
|
+
`_bmad-output/test-artifacts`): every `test-design-epic-<id>.md`, and an
|
|
109
|
+
`nfr-assessment.md` whose `**Story:**` line names a story it reads (one beside the
|
|
110
|
+
Epic's test-design that cannot be read is a failing gap). A test-design or NFR
|
|
111
|
+
assessment the Epic does not have yet is no gap, and another Epic's test-design or
|
|
112
|
+
TEA's system-level files never raise one.
|
|
95
113
|
|
|
96
114
|
## 2. Mechanical auto-remediation pass
|
|
97
115
|
|
|
@@ -159,7 +177,8 @@ its `detail`: record it as a non-remediable blocker naming the kind and route to
|
|
|
159
177
|
kind blocks loudly instead of being guessed at, and the halt catch-all below then covers
|
|
160
178
|
the never-remediated case as well as the remediated-but-unfixed one.
|
|
161
179
|
|
|
162
|
-
Log each remediation to `.decision-log.md` as you apply it
|
|
180
|
+
Log each remediation to `.decision-log.md` as you apply it, appended the way Conventions
|
|
181
|
+
says. Never
|
|
163
182
|
auto-remediate a `judgment_candidate`, and never auto-remediate a
|
|
164
183
|
`remediable: false` mechanical gap (an unreadable artifact cannot be fixed from its
|
|
165
184
|
own unreadable content).
|
|
@@ -220,7 +239,7 @@ one-line evidence fields:
|
|
|
220
239
|
"candidate": "<only when this answers a seeded judgment candidate: its id, copied as given>"}],
|
|
221
240
|
"concerns": [{"source": "<artifact path:line>", "note": "<cosmetic / non-blocking gap, one line>",
|
|
222
241
|
"candidate": "<only when this answers a seeded judgment candidate: its id, copied as given>"}],
|
|
223
|
-
"advisories_checked": [{"sig": "<
|
|
242
|
+
"advisories_checked": [{"sig": "<the recalled record's id, copied as given>", "status": "recurred|not-observed|unknown"}]}
|
|
224
243
|
```
|
|
225
244
|
|
|
226
245
|
**Mint ids before mapping, and apply the operator's closes.** Hand the returned scan
|
|
@@ -38,7 +38,9 @@ more than a note-taker.
|
|
|
38
38
|
`{project-root}/_bmad-output/ultracode-goal/<run folder>/.decision-log.md` — the module's
|
|
39
39
|
default runs root, which no `customize.toml` scalar carries. Write to the folder whose
|
|
40
40
|
Epic the enumerated artifacts belong to; ask the operator when more than one could be it,
|
|
41
|
-
and when none exists append nothing rather than create a stray log.
|
|
41
|
+
and when none exists append nothing rather than create a stray log. Append to it with
|
|
42
|
+
Write/Edit, never a Bash heredoc, as section 3 says, which also covers a log too large to
|
|
43
|
+
Read.
|
|
42
44
|
|
|
43
45
|
## On Activation
|
|
44
46
|
|
|
@@ -78,8 +80,9 @@ and anything not written down is not a pending decision this surface can honor.
|
|
|
78
80
|
genuinely still pending: the arming step deliberately does not purge `escalation-*.json`,
|
|
79
81
|
so a decision an operator chose to leave open survives to this pass.
|
|
80
82
|
2. **The preflight RED sidecar** — `{workflow.implementation_artifacts}/.preflight-reds.json`,
|
|
81
|
-
shape `{"reds": [...]}`. **One** file holds
|
|
82
|
-
|
|
83
|
+
shape `{"reds": [...]}`. **One** file holds the REDs the last preflight left pending, from
|
|
84
|
+
whichever Epic ran it (section 2 says what that means for an entry no RED carries). There
|
|
85
|
+
is no second RED sidecar and no per-story one: a per-story or per-run RED file would carry
|
|
83
86
|
an id that changed between scans, and an id that changes cannot carry an answer forward.
|
|
84
87
|
3. **The deferred-work ledger** — `{workflow.deferred_work_path}`, restricted to its
|
|
85
88
|
`decision:` rows. Those are the rows whose `source` column reads `decision` (as opposed
|
|
@@ -114,7 +117,8 @@ For a sidecar the three arguments are its own `kind`, `source` and `decision_nee
|
|
|
114
117
|
fields, each passed verbatim: `<artifact path>` is the sidecar's `source` field, its
|
|
115
118
|
`:line` suffix and all (the id layer strips it), never the path of the sidecar file
|
|
116
119
|
itself. The resume also reads a close keyed by the sidecar file's own path as closed,
|
|
117
|
-
since earlier passes keyed some that way, but never
|
|
120
|
+
since earlier passes keyed some that way, but never key an answer by an id minted from
|
|
121
|
+
that path: section 2 mints those ids only to recognize an entry already recorded.
|
|
118
122
|
|
|
119
123
|
It prints the id and touches nothing. **A ledger `decision:` row is keyed by the same
|
|
120
124
|
call** — kind `decision`, the ledger path, and the row's reason — because the row's own
|
|
@@ -146,24 +150,56 @@ Re-asking a question the operator already **resolved** is the exact failure this
|
|
|
146
150
|
exists to remove.
|
|
147
151
|
|
|
148
152
|
An entry recorded with `action` `defer` is the opposite case: it is a parked question, not
|
|
149
|
-
an answered one. Present it again
|
|
150
|
-
|
|
151
|
-
the run outright: `defer` clears
|
|
152
|
-
so the next preflight still blocks on that RED
|
|
153
|
-
step 3, drops only the ids whose `action` is
|
|
154
|
-
can answer it, would never ask again. The
|
|
155
|
-
no longer offered.
|
|
153
|
+
an answered one. Present it again while an item this pass enumerated carries its `id`, and
|
|
154
|
+
replace its entry in place when the operator decides it, carrying its answer forward
|
|
155
|
+
(section 3). Suppressing a deferred item would deadlock the run outright: `defer` clears
|
|
156
|
+
nothing, so the next preflight still blocks on that RED
|
|
157
|
+
(`{ucg-root}/references/preflight.md`, step 3, drops only the ids whose `action` is
|
|
158
|
+
`close`), while this surface, the only one that can answer it, would never ask again. The
|
|
159
|
+
scan blocks forever on a question the operator is no longer offered.
|
|
156
160
|
|
|
157
161
|
An entry with no `action`, or with an `action` that is neither `close` nor `defer`, is
|
|
158
|
-
pending as well
|
|
159
|
-
preflight drops none of their ids, so
|
|
160
|
-
you present a deferred one.
|
|
162
|
+
pending as well while an item this pass enumerated carries its `id`. An earlier version of
|
|
163
|
+
this surface wrote some entries that way, and preflight drops none of their ids, so that
|
|
164
|
+
item's question stays open. Present it again, as you present a deferred one.
|
|
165
|
+
|
|
166
|
+
**An item carries an entry's `id` only on an exact match, as written.** A RED carries the
|
|
167
|
+
`id` on its `reds` entry, and a ledger `decision:` row the id the id layer printed for it.
|
|
168
|
+
An escalation sidecar carries the id the id layer printed from its own fields, and one
|
|
169
|
+
more for each spelling of the sidecar file's own path the resume reads a close by
|
|
170
|
+
(`_sidecar_ids` in `{ucg-root}/scripts/preflight_check.py`): its path relative to
|
|
171
|
+
`{project-root}`, its absolute path, that absolute path with its folder's symlinks
|
|
172
|
+
resolved, and the resolved path relative to `{project-root}`, each written with forward
|
|
173
|
+
slashes and, on Windows, with backslashes too. Ask the id layer for each of those with the
|
|
174
|
+
sidecar's own `kind` and `decision_needed`. Mint them only to recognize an entry already
|
|
175
|
+
recorded, never to key an answer: an entry keyed by any of them belongs to that sidecar's
|
|
176
|
+
item.
|
|
161
177
|
|
|
162
178
|
When an item you present already has an entry, show its `answer`, and each earlier answer
|
|
163
179
|
its `history` holds (section 3), beside the decision needed. Such an answer can hold the
|
|
164
180
|
operator's whole ruling: they decide on the record as it stands, and may find it already
|
|
165
181
|
answers the question.
|
|
166
182
|
|
|
183
|
+
**An entry no enumerated item carries is orphaned, not pending.** That is an entry whose
|
|
184
|
+
`action` is anything but `close` and whose `id` no item of this pass carries: none of the
|
|
185
|
+
three sources holds its question at this pass, so there is no item to present it with.
|
|
186
|
+
List the orphaned entries after the pending items, apart from them, each with its `id`,
|
|
187
|
+
its `answer` and each earlier answer its `history` holds, and ask nothing about them; the
|
|
188
|
+
record keeps each one as it stands. Say beside that list that a later preflight can raise
|
|
189
|
+
an orphaned entry again and block on it. `.preflight-reds.json` is one project-wide file
|
|
190
|
+
that each preflight replaces, so it holds only the REDs of the last preflight, from
|
|
191
|
+
whichever Epic ran it: a RED one Epic's preflight raised can be gone from it after another
|
|
192
|
+
Epic's preflight, while that first Epic's next preflight can raise it again. An orphaned
|
|
193
|
+
entry whose `id` a later RED, sidecar or ledger row carries is pending again at that pass,
|
|
194
|
+
which asks it.
|
|
195
|
+
|
|
196
|
+
**When a source could not be read in full, call nothing orphaned.** That is an unreadable
|
|
197
|
+
`.preflight-reds.json`, an escalation sidecar that cannot be read or whose fields no id can
|
|
198
|
+
be minted from, or a ledger on disk that cannot be read, or is malformed or a bullet list,
|
|
199
|
+
so it yields no rows here. In that case present every entry that is not a `close` as
|
|
200
|
+
pending, with its `id`, its `answer` and its `history`, since an id that source would carry
|
|
201
|
+
cannot be ruled out.
|
|
202
|
+
|
|
167
203
|
## 3. Record the answer, then apply its disposition
|
|
168
204
|
|
|
169
205
|
Every answer lands in `{workflow.implementation_artifacts}/.decisions.json`:
|
|
@@ -282,7 +318,8 @@ The two dispositions are genuinely different things, not two names for one:
|
|
|
282
318
|
and the id you closed, before you delete the sidecar: once the sidecar is gone, that
|
|
283
319
|
entry is the only copy of the move the resumed run writes into both story files, or for
|
|
284
320
|
two decomposed children into every record of their split (the split record, both child
|
|
285
|
-
rows in `sprint-status.yaml
|
|
321
|
+
rows in `sprint-status.yaml`, the earlier child's ATDD checklist and the later child's
|
|
322
|
+
when it has one). This
|
|
286
323
|
surface edits neither story file and moves no test case: the ruling is the operator's,
|
|
287
324
|
and the resumed run applies it before the earlier story's next commit. An answer that
|
|
288
325
|
re-plans the rows instead (one story in place of the two, or another order) is the
|
|
@@ -295,18 +332,39 @@ The two dispositions are genuinely different things, not two names for one:
|
|
|
295
332
|
anything**. The artifact stays exactly where it is, the item stays pending, and the next
|
|
296
333
|
preflight still blocks on it.
|
|
297
334
|
|
|
298
|
-
Record each answer and its disposition in `.decision-log.md` as you apply it
|
|
335
|
+
Record each answer and its disposition in `.decision-log.md` as you apply it, with
|
|
336
|
+
Write/Edit and never a Bash heredoc. A heredoc puts decision prose (commit and push verbs,
|
|
337
|
+
backticked names, apostrophes) into a Bash command string, and the PreToolUse guard's git
|
|
338
|
+
gates read that string as commands (`{ucg-root}/references/execute.md`, step 4, gives the
|
|
339
|
+
reason). Once the log is too large to Read affordably, do not Read it, since both file
|
|
340
|
+
tools refuse a file this session has not Read. Write the entry instead to a new file beside
|
|
341
|
+
the log, `{project-root}/_bmad-output/ultracode-goal/<run folder>/dlog-slice-resolve-<n>.md`,
|
|
342
|
+
with `<n>` one past the highest number a `dlog-slice-resolve-*.md` in that folder already
|
|
343
|
+
carries (`1` when there is none): the name has to be new for every append, or Write finds
|
|
344
|
+
the file on disk and asks for the Read again. Then append it in one Bash call, with both
|
|
345
|
+
paths in full:
|
|
346
|
+
`cat "{project-root}/_bmad-output/ultracode-goal/<run folder>/dlog-slice-resolve-<n>.md" >> "{project-root}/_bmad-output/ultracode-goal/<run folder>/.decision-log.md"`.
|
|
347
|
+
Keep the slice rather than deleting it: it is the only copy of the entry if the append is
|
|
348
|
+
interrupted. This holds for every entry the pass writes, the coupled-stories entry above
|
|
349
|
+
included.
|
|
299
350
|
|
|
300
351
|
## 4. Hand control back to the existing resume
|
|
301
352
|
|
|
302
353
|
`/ucg-resolve` defines no resume of its own. Close the pass by stating what closed, what is
|
|
303
354
|
still pending, and that anything still pending re-blocks at the next preflight. Name every
|
|
304
355
|
entry this pass replaced, by `id`, with the earlier answer it carried into `history`, so
|
|
305
|
-
the operator sees what the record held before this pass.
|
|
356
|
+
the operator sees what the record held before this pass. List the orphaned entries apart
|
|
357
|
+
from both, by `id`, and say that a later preflight can raise any of them again and block
|
|
358
|
+
on it, and that the pass after that preflight asks it. **Hand back
|
|
306
359
|
only when the pass closed at least one item, or when the operator asks for the resume**: a
|
|
307
360
|
pass that deferred everything hands into a run blocked on the identical items, and an empty
|
|
308
361
|
enumeration means the run stopped for a non-decision reason — say so, point at the read-only
|
|
309
|
-
`/ucg-status`, and hand nothing back.
|
|
362
|
+
`/ucg-status`, and hand nothing back. A pass that found only orphaned entries is not an
|
|
363
|
+
empty enumeration, so do not say the run stopped for a non-decision reason: the run can
|
|
364
|
+
have stopped on a RED that another Epic's preflight has since dropped from
|
|
365
|
+
`.preflight-reds.json`, and its next preflight raises that RED again. Such a pass closed
|
|
366
|
+
nothing, so point at the read-only `/ucg-status`, as for an empty enumeration, and hand
|
|
367
|
+
back only when the operator asks for the resume.
|
|
310
368
|
|
|
311
369
|
Otherwise hand back to the resume the module already has, which **routes by the last stage
|
|
312
370
|
the blocked run reached**, not by story. Which branch applies is not a detail this surface
|
|
@@ -61,7 +61,7 @@ These exist because the documented mechanics make the intuitive shortcut wrong.
|
|
|
61
61
|
| 6 | Finalize | Auto Memory capture, optional retrospective, decision-log audit, report | `references/finalize.md` |
|
|
62
62
|
| 7 | Health Check | Terminal self-improvement audit — Finalize's close-out loads it; capture real workflow friction | `references/health-check.md` |
|
|
63
63
|
|
|
64
|
-
Run the stages in order; each routes by the testable conditions stated in its file. The decision log is canonical memory
|
|
64
|
+
Run the stages in order; each routes by the testable conditions stated in its file. The decision log is canonical memory: record scope, the preflight verdict, every gate outcome, and every deferral as you go. **Append it with Write/Edit, never a Bash heredoc**, from Stage 1 on: a heredoc puts the log's prose into a Bash command string, and the guard's git gates read that string as commands (`references/execute.md`, step 4, gives the reason). Once the log is too large to Read affordably, do not Read it: Write the entry to a new file beside the log, in the run folder that holds it, `<log folder>/dlog-slice-<label>-<n>.md`, where `<log folder>` is that folder's full path, `<label>` is the story's id for an entry about a story and `stage<k>` for one a stage writes outside a story (`stage1` for Ingest & Scope), and `<n>` is one past the highest number a `dlog-slice-<label>-*.md` there already carries, so the name is new for every append. Then append it in one Bash call, `cat "<log folder>/dlog-slice-<label>-<n>.md" >> "<log folder>/.decision-log.md"`, and keep the slice.
|
|
65
65
|
|
|
66
66
|
## Headless
|
|
67
67
|
|