bmad-module-ultracode-goal 1.0.1 → 2.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/README.md +2 -0
- package/docs/_internal/STABILITY.md +25 -10
- package/docs/cross-session-recall.md +8 -0
- package/docs/gate-model.md +12 -5
- package/docs/getting-started.md +7 -1
- package/docs/index.md +1 -0
- package/docs/operating-tips.md +183 -0
- package/docs/troubleshooting.md +6 -2
- package/package.json +1 -1
- package/skills/{ultracode-goal/skills/ucg-formalize → ucg-formalize}/SKILL.md +13 -10
- package/skills/{ultracode-goal/skills/ucg-resolve → ucg-resolve}/SKILL.md +18 -14
- package/skills/{ultracode-goal/skills/ucg-status → ucg-status}/SKILL.md +12 -9
- package/skills/ultracode-goal/SKILL.md +5 -9
- package/skills/ultracode-goal/assets/execute-epic.workflow.js +44 -3
- package/skills/ultracode-goal/references/execute.md +41 -5
- package/skills/ultracode-goal/references/finalize.md +13 -4
- package/skills/ultracode-goal/references/gate.md +12 -4
- package/skills/ultracode-goal/references/ingest-and-scope.md +10 -2
- package/skills/ultracode-goal/references/preflight.md +9 -5
- package/skills/ultracode-goal/scripts/drive_epic.py +461 -58
- package/skills/ultracode-goal/scripts/formalize_check.py +42 -2
- package/skills/ultracode-goal/scripts/gate_eval.py +194 -13
- package/skills/ultracode-goal/scripts/gate_trail.py +214 -25
- package/skills/ultracode-goal/scripts/headless_envelope.py +45 -6
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +78 -4
- package/skills/ultracode-goal/scripts/preflight_check.py +27 -1
- package/tools/build-docs.js +1 -0
- package/tools/cli/lib/ide-skills.js +11 -2
- package/website/astro.config.mjs +1 -0
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"name": "bmad-module-ultracode-goal",
|
|
20
20
|
"source": "./",
|
|
21
21
|
"description": "Supercharges BMAD with Claude Code Goal Mode, Auto Mode, and Auto Memory: autonomous Epic execution to a machine-checked, TEA-gated Definition-of-Done. Execute Epics. Accumulate Knowledge. Deliver Outcomes.",
|
|
22
|
-
"version": "
|
|
22
|
+
"version": "2.0.0",
|
|
23
23
|
"author": {
|
|
24
24
|
"name": "Armel"
|
|
25
25
|
},
|
package/README.md
CHANGED
|
@@ -139,7 +139,9 @@ The docs are organized into three buckets: **Why** (start here), **Try** (do stu
|
|
|
139
139
|
- **[Health Check](./docs/health-check.md)**: the terminal self-improvement loop: what it sends, privacy, and how to disable it.
|
|
140
140
|
- **[Cross-Session Recall](./docs/cross-session-recall.md)**: the optional claude-mem integration: touchpoints, trust model, and how to enable it.
|
|
141
141
|
- **[Knowledge-Graph Refresh](./docs/knowledge-graph-refresh.md)**: the optional graphify integration: preconditions, what it sends where, and what it never touches.
|
|
142
|
+
- **[Operating Tips](./docs/operating-tips.md)**: field notes from real drives: the driver's stop reasons, sequencing by row order, and the verification traps.
|
|
142
143
|
- **[Troubleshooting](./docs/troubleshooting.md)**: real failure modes and their remediations.
|
|
144
|
+
- **[UCG vs bmad-loop](./docs/comparison.md)**: a side-by-side comparison with bmad-code-org's bmad-loop orchestrator.
|
|
143
145
|
|
|
144
146
|
Every run that reaches Finalize ends with a self-improvement check that can file a deduplicated GitHub issue with your approval, so **please let runs finish through Finalize**, or [open an issue](https://github.com/armelhbobdad/bmad-module-ultracode-goal/issues/new/choose) directly. If UCG shipped an epic while you slept, a ⭐ helps others find it.
|
|
145
147
|
|
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Stability and Public Contract
|
|
3
|
-
description: "The
|
|
3
|
+
description: "The 1.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:** 1.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 `1.x`. It enumerates the surfaces a downstream consumer or automator may reasonably depend on, versus everything else, which is `@internal`.
|
|
9
9
|
|
|
10
|
-
## Public contract
|
|
10
|
+
## Public contract
|
|
11
11
|
|
|
12
|
-
The following surfaces are the
|
|
12
|
+
The following surfaces are the public contract. Breaking one requires a MAJOR bump; see [SemVer note](#semver-note).
|
|
13
13
|
|
|
14
14
|
### CLI command surface
|
|
15
15
|
|
|
@@ -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`, `allowlist_commands`, `on_epic_complete`, and `
|
|
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`, `allowlist_commands`, `on_epic_complete`, `on_escalation`, `cross_session_recall`, 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
|
|
|
@@ -58,7 +58,8 @@ The skill name `ultracode-goal` and its documented invocation phrases ("run an e
|
|
|
58
58
|
|
|
59
59
|
`scripts/gate_eval.py` is the deterministic completion authority. Covered:
|
|
60
60
|
|
|
61
|
-
- **CLI flags**: `--trace-output` (required), `--profile` (`light` | `production`, required), `--story`, `--nfr`, `--test-review` (production only)
|
|
61
|
+
- **CLI flags**: `--trace-output` (required), `--profile` (`light` | `production`, required), `--story`, `--nfr`, `--test-review` (production only), `--epic-level`.
|
|
62
|
+
- **The production signals are required, not optional, on a per-story gate.** Under `--profile production` an omitted `--nfr` or `--test-review` is a *failing* signal, exactly as a supplied-but-missing path already was. `--epic-level` is the one sanctioned omission: it declares the epic roll-up, where TEA writes no aggregate to AND, and it cannot be combined with either path (doing so is an invocation error, exit 2). Under `--profile light` the flag is a no-op.
|
|
62
63
|
- **Verdict vocabulary**: the `verdict` values `advance` / `defer` / `reloop` / `escalate`, and the `gate_status` values `PASS` / `CONCERNS` / `FAIL` / `WAIVED` / `NOT_EVALUATED`, plus the mapping between them. See the [gate model](../gate-model.md).
|
|
63
64
|
- **`--story` fail-closed resolution**: when `--story` matches no artifact in a trace dir whose reports or gate-decision files are named per story, the result is `NOT_EVALUATED` (so, `escalate`), never a fallback to another story's gate. A trace dir whose candidates are all generically named (`trace.md`, `gate-decision.json`) still resolves unscoped. Which file the resolver picks, and how it decides that a name carries a story id, are internal.
|
|
64
65
|
|
|
@@ -75,11 +76,11 @@ flowchart LR
|
|
|
75
76
|
class ADV,DEF,REL,ESC verdict
|
|
76
77
|
```
|
|
77
78
|
|
|
78
|
-
The printed JSON object's key set (`verdict`, `gate_status`, `p0_status`, `p1_status`, `overall_status`, `nfr_status`, `review_score`, `reasons`) is the consumable shape; the human-readable `reasons` strings are not contractual wording.
|
|
79
|
+
The printed JSON object's key set (`verdict`, `gate_status`, `p0_status`, `p1_status`, `overall_status`, `nfr_status`, `review_score`, `epic_level`, `reasons`) is the consumable shape; the human-readable `reasons` strings are not contractual wording. `epic_level` is how a consumer tells an `advance` that ANDed both production signals from one that skipped them by declaration: `nfr_status: null` alone cannot say which, and the distinction is not readable from `reasons` precisely because that wording is not contractual.
|
|
79
80
|
|
|
80
81
|
## @internal: not covered
|
|
81
82
|
|
|
82
|
-
Everything not enumerated above is `@internal` and may change in any
|
|
83
|
+
Everything not enumerated above is `@internal` and may change in any release, major or minor, without a deprecation note. Do not pin against:
|
|
83
84
|
|
|
84
85
|
- **Installer library internals**: the implementation behind the CLI subcommands; what is covered is the observable subcommand surface, not how the files get placed.
|
|
85
86
|
- **Reference file structure**: the `references/*.md` stage files' internal structure, step ordering, prose, and section headings. The stage *names* are referenced by the health-check fingerprint (see below) but the file contents are an authoring surface.
|
|
@@ -89,4 +90,18 @@ Everything not enumerated above is `@internal` and may change in any `0.x` relea
|
|
|
89
90
|
|
|
90
91
|
## SemVer note
|
|
91
92
|
|
|
92
|
-
|
|
93
|
+
**A breaking change to any surface in [Public contract](#public-contract) requires a MAJOR bump.** That is the whole rule, and it is deliberately stricter than "we try": this module's value is that a machine-checked contract means what it says, so the versioning of the contract has to as well.
|
|
94
|
+
|
|
95
|
+
What counts as breaking, stated so it is not re-litigated per release:
|
|
96
|
+
|
|
97
|
+
- Removing or renaming an enumerated CLI flag, subcommand, config key, or JSON key.
|
|
98
|
+
- **Changing the verdict an unchanged, previously-documented invocation returns.** This is the one that bites, and it bit at 2.0.0: `gate_eval.py --profile production` with neither signal flag was the documented epic-level invocation and returned `advance`; it now returns `reloop` unless `--epic-level` is passed. That the old answer was unearned did not make the change non-breaking — a consumer's pipeline still changed behaviour on an upgrade they did not ask for.
|
|
99
|
+
- Adding a key to the printed verdict JSON or the headless envelope, for a consumer validating the shape strictly.
|
|
100
|
+
|
|
101
|
+
What does not:
|
|
102
|
+
|
|
103
|
+
- Fixing a resolver so it returns the *right* artifact rather than a neighbour's, where the documented invocation and its vocabulary are unchanged.
|
|
104
|
+
- Anything behind `@internal`, including which file a resolver picks and how it decides a name carries a story id.
|
|
105
|
+
- Prose in `references/*.md`, which is an authoring surface.
|
|
106
|
+
|
|
107
|
+
**Deprecation.** The two surfaces an automator is most likely to encode against — the **headless five-key JSON emit shape** and the **`[workflow]` customize.toml keys** — get a deprecation note in `CHANGELOG.md` at least one minor before changing, and the key stays shipped and accepted meanwhile. `story_token_budget` is the worked example: deprecated, still resolving, no-op.
|
|
@@ -17,6 +17,14 @@ You need [claude-mem](https://github.com/thedotmack/claude-mem) installed and th
|
|
|
17
17
|
|
|
18
18
|
> claude-mem is a third-party plugin maintained independently of this module. We don't bundle, endorse, or install it; Cross-Session Recall simply uses it when you already have it.
|
|
19
19
|
|
|
20
|
+
**Two headless caveats, both observed rather than theoretical.**
|
|
21
|
+
|
|
22
|
+
*Your harness may gate the MCP call behind a permission prompt.* An unattended run has nobody to answer it, so the tools are listed, their schemas resolve, and the one sanctioned `search` is refused at call time. UCG handles that correctly (it latches red, logs a `WARN`, and proceeds gateless, since recall is advisory and never part of the gate) but it pays one call every run to rediscover it. One project recorded that outcome on 25 consecutive runs. If that is your situation, `on` means **off in practice**: either grant the permission once, or set `cross_session_recall = "off"` and stop paying for the probe.
|
|
23
|
+
|
|
24
|
+
*The latch only enforces anything if your PreToolUse hook is armed for MCP tools.* The guard denies a claude-mem call under a red latch, but Claude Code only invokes a hook group for the tools its `matcher` selects, and a group armed for `Bash` alone is never invoked for an MCP call. Preflight arms it with an all-tools matcher for exactly this reason; if you merge the hook by hand, match every tool or this gate is inert.
|
|
25
|
+
|
|
26
|
+
*And claude-mem may expose reads without a write.* The latch is validated by a read-shaped probe, so `present` certifies that UCG can look, not that there is anywhere to write. On a surface with no write tool, Finalize parks its summary and says so rather than reporting a failed write.
|
|
27
|
+
|
|
20
28
|
## The touchpoints
|
|
21
29
|
|
|
22
30
|
Recall touches the run in exactly three places, and a machine latch (`.mem-state.json`) gates every one of them. The latch is written **once** at Ingest and removed at Finalize close-out; while it is present a `PreToolUse` hook allows claude-mem calls only when recall is green, and denies them otherwise: fail closed. The Execute and Gate stages are never touched.
|
package/docs/gate-model.md
CHANGED
|
@@ -59,25 +59,32 @@ Under `--profile production`, an otherwise-`advance` verdict is additionally AND
|
|
|
59
59
|
- **NFR** (`nfr-assessment.md`): the audit's Overall Status must not be `FAIL`.
|
|
60
60
|
- **Test review** (`test-review.md`): the Quality Score must be `>= 80` **and** the Recommendation must not be `Block`.
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
**Both paths are required, and an omitted flag is a failure too.** A path that is given but missing counts as failing, and so does one you simply leave off: the AND cannot run on a signal nobody named. That matters because the two used to differ. A forgotten flag was skipped in silence, `nfr_status` rendered `null`, and the verdict was computed without it, so forgetting a flag bought a *higher* verdict than supplying a failing artifact would have.
|
|
63
|
+
|
|
64
|
+
The one legitimate omission is the **epic roll-up**, where TEA writes no aggregate to AND, because it produces both artifacts per story. That case declares itself with `--epic-level` rather than being inferred from an absent flag, and the flag cannot be combined with either path (an invocation error, exit 2). The verdict JSON carries `epic_level` so a reader can tell a skipped-AND `advance` from one that ANDed both signals.
|
|
65
|
+
|
|
66
|
+
How the AND folds the two signals in, with every unreadable *or unsupplied* path counting as a failure:
|
|
63
67
|
|
|
64
68
|
```mermaid
|
|
65
69
|
flowchart TD
|
|
66
70
|
V{"Verdict is advance?"} -->|"no, defer/reloop/escalate"| K["Unchanged"]
|
|
67
|
-
V -->|"yes"|
|
|
71
|
+
V -->|"yes"| E{"--epic-level declared?"}
|
|
72
|
+
E -->|"yes, no aggregate to AND"| A["Stay advance"]
|
|
73
|
+
E -->|"no, per-story gate"| N{"NFR Overall Status"}
|
|
68
74
|
N -->|"FAIL"| F["Signal failed"]
|
|
69
75
|
N -->|"file missing or unparsable"| F
|
|
76
|
+
N -->|"--nfr not supplied"| F
|
|
70
77
|
N -->|"parsed and not FAIL"| R{"Test review"}
|
|
71
78
|
R -->|"score lt 80 or Block"| F
|
|
72
79
|
R -->|"score unparsable, file missing"| F
|
|
73
|
-
R -->|"
|
|
80
|
+
R -->|"--test-review not supplied"| F
|
|
81
|
+
R -->|"score gte 80 and not Block"| A
|
|
74
82
|
F --> D["Downgrade advance to reloop"]
|
|
75
|
-
P --> A["Stay advance"]
|
|
76
83
|
classDef verdict fill:#4F46E5,stroke:#3730A3,color:#fff
|
|
77
84
|
class A,D,K verdict
|
|
78
85
|
```
|
|
79
86
|
|
|
80
|
-
Under `--profile light` none of this applies: the trace gate is the whole decision.
|
|
87
|
+
Under `--profile light` none of this applies: the trace gate is the whole decision, and `--epic-level` is a no-op there.
|
|
81
88
|
|
|
82
89
|
## The thresholds
|
|
83
90
|
|
package/docs/getting-started.md
CHANGED
|
@@ -67,7 +67,13 @@ Run it from your project root. The path above is the Claude Code skill copy the
|
|
|
67
67
|
|
|
68
68
|
Drop `--dry-run` to actually spawn. Point `--impl-artifacts` at the directory holding your `sprint-status.yaml`; the driver refuses to start if it is not there, since that is the sprint plan it reads. That directory also has to be the one your config resolves `implementation_artifacts` to, because the spawned session writes its terminal `run-result.json` where the config says, not where the driver was pointed. The driver cannot check that half for you: it would have to re-implement the skill's own config resolution to do it.
|
|
69
69
|
|
|
70
|
-
The driver is read-only on your tree with exactly one exception: it deletes the pinned `run-result.json` before each spawn, so the file's presence means *that* spawn reached a terminal. It stops on anything it cannot verify, and says why: no readable terminal, a `blocked` envelope (with the reason), a status it does not recognize, a `complete` whose story did not reach `done`, or a session that outran `--session-timeout` (2 hours by default; `0` disables it).
|
|
70
|
+
The driver is read-only on your tree with exactly one exception: it deletes the pinned `run-result.json` before each spawn, so the file's presence means *that* spawn reached a terminal. It stops on anything it cannot verify, and says why: no readable terminal, a `blocked` envelope (with the reason), a status it does not recognize, a `complete` whose story did not reach `done`, or a session that outran `--session-timeout` (2 hours by default; `0` disables it).
|
|
71
|
+
|
|
72
|
+
**One of those is retried rather than fatal.** A `claude -p` can be terminated in flight by the API layer, leaving no terminal, and that is not a story problem: the same row lands on the next attempt against identical state. The driver retries a no-terminal stop up to `--max-abort-retries` times (default 2, `0` disables), but **only** when its post-stop triage finds the tree clean and HEAD unmoved, so a retry can never re-spawn over work in progress.
|
|
73
|
+
|
|
74
|
+
**Every post-spawn stop now prints a triage block** describing the tree the session left: clean with HEAD advanced (the work committed and only close-out is missing, so verify and mark it done rather than re-driving), clean and unmoved (nothing landed), or dirty (which may hold a suite that is already green). It reports and never decides. It also names any intent-to-add path, because `git checkout -- <path>` truncates those to zero bytes and exits `0`.
|
|
75
|
+
|
|
76
|
+
Useful flags: `--limit N` caps how many sessions it spawns, retries included, `--permission-mode` defaults to `acceptEdits` and refuses `bypassPermissions` unless you also pass `--allow-full-autonomy`, and `--skill-command` overrides the invocation string for a plugin-marketplace install (`/bmad-module-ultracode-goal:ultracode-goal`).
|
|
71
77
|
|
|
72
78
|
## Hook security
|
|
73
79
|
|
package/docs/index.md
CHANGED
|
@@ -64,5 +64,6 @@ The docs split into three buckets: **Why** (start here), **Try** (do stuff), and
|
|
|
64
64
|
- [Health Check](./health-check.md): the terminal self-improvement reflection: what it sends, the privacy model, and how to disable it.
|
|
65
65
|
- [Cross-Session Recall](./cross-session-recall.md): the optional claude-mem integration and its trust model.
|
|
66
66
|
- [Knowledge-Graph Refresh](./knowledge-graph-refresh.md): the optional graphify integration, its preconditions, and what it sends where.
|
|
67
|
+
- [Operating Tips](./operating-tips.md): field notes from real drives: the driver's stop reasons, why row order is the only sequencing mechanism, and the verification traps.
|
|
67
68
|
- [Troubleshooting](./troubleshooting.md): real failure modes and their remediations.
|
|
68
69
|
- [UCG vs bmad-loop](./comparison.md): a side-by-side comparison with bmad-code-org's bmad-loop orchestrator (formerly bmad-auto).
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
---
|
|
2
|
+
title: Operating Tips
|
|
3
|
+
description: "Field notes from driving a real 22-story epic: giving Bash room for a foreground drive, reading the driver stop reasons that need a decision, why row order is the only sequencing mechanism, splitting a story that escalates, and the verification traps that produce confident false greens."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
Everything here was learned by driving one real epic (22 stories, 12 landed across a single day, four of them split on contact, three of those consecutively) rather than from reading the scripts. Where a tip contradicts an intuition, the measurement is given. The numbers are one run on one codebase: treat them as something to measure your own against, not as properties of the tool.
|
|
7
|
+
|
|
8
|
+
For the designed behavior of the run's own failure modes (preflight, the gate, hooks, budget, resume, `--parallel`) see [troubleshooting](./troubleshooting.md). The driver's stop reasons are documented here and nowhere else in these docs; the full set is `drive_epic.py`'s `STOP_*` constants.
|
|
9
|
+
|
|
10
|
+
## Running the loop
|
|
11
|
+
|
|
12
|
+
### Give Bash an hour so drives can run in the foreground
|
|
13
|
+
|
|
14
|
+
A `drive_epic.py` invocation took 25 to 45 minutes per story in the run behind these notes; measure your own before sizing a timeout. The Bash tool defaults to a 120-second timeout with a 600-second ceiling (measured on Claude Code 2.1.220, and neither of those env vars appears in the published settings reference, so re-check them if the numbers stop matching). So an agent driving the loop cannot ask to watch a drive to the end: past the timeout the harness moves the command to the background, where it keeps running with nothing watching it.
|
|
15
|
+
|
|
16
|
+
Raise the ceiling in `~/.claude/settings.json`:
|
|
17
|
+
|
|
18
|
+
```json
|
|
19
|
+
{
|
|
20
|
+
"env": {
|
|
21
|
+
"BASH_DEFAULT_TIMEOUT_MS": "120000",
|
|
22
|
+
"BASH_MAX_TIMEOUT_MS": "3600000"
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
`BASH_DEFAULT_TIMEOUT_MS` is already the stock default and is here as a pin; only the ceiling changes. **Env settings are read at startup**, so this takes effect on the next session, not the current one.
|
|
28
|
+
|
|
29
|
+
The ceiling only sets what a call is *allowed* to ask for. A call that passes no `timeout` of its own is still cut at the 120-second default however high the ceiling is, so ask for the full hour on the drive call itself. And the cut is not a kill: the command is moved to the background and runs to completion there (measured: a 135-second command finished after being backgrounded at 120 seconds), so what you lose is the foreground, not the work.
|
|
30
|
+
|
|
31
|
+
Two limits to respect. An hour covers roughly one story at the rate above, so pair a foreground drive with `--limit 1`. And the driver's own `--session-timeout` defaults to two hours, which a one-hour Bash ceiling can never reach: if you want the driver's wall clock to be the thing that stops a drive, pass a `--session-timeout` below the ceiling, or raise `BASH_MAX_TIMEOUT_MS` past the driver's default.
|
|
32
|
+
|
|
33
|
+
The tradeoff is real: a foreground drive blocks the agent for its whole duration. For a strict drive-then-verify loop that costs nothing, because there is nothing to do in between. If you want the agent working on something else while a story runs, background is still the right mechanism.
|
|
34
|
+
|
|
35
|
+
### The recall latch does not repair itself between drives
|
|
36
|
+
|
|
37
|
+
That Stage 6 removes `.mem-state.json` at close-out is covered in [cross-session recall](./cross-session-recall.md). The resume half is not in these docs, so: a resume re-writes the latch by re-running Stage 1's latch step. (The story's baseline marker is the opposite case, re-read and never regenerated. Do not carry the latch's rule across to it.)
|
|
38
|
+
|
|
39
|
+
The operational addition, worth knowing before you chain drives: **observed across a multi-drive day, the spawned session's own attempt to write the latch was permission-denied, so a missing latch did not repair itself on the next spawn.** What denied it was never diagnosed, and UCG's own PreToolUse recall gate is not a candidate, since it no-ops when the latch is absent, which is exactly the state Stage 6 leaves behind. Treat this as an unexplained observation: check for the file rather than assume it.
|
|
40
|
+
|
|
41
|
+
Re-assert from the parent between drives with the skill's own latch writer, never by hand (a hand-written latch forges the capability check the file exists to record):
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
uv run <skill-root>/scripts/mem_recall.py latch \
|
|
45
|
+
--impl-artifacts <impl-artifacts> --run-id <run-id> \
|
|
46
|
+
--recall off --claude-mem-absent
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
That writes a latch recording claude-mem as absent with recall off, which restores fail-closed gating. Use the `--recall on --probe <probe.json>` form when recall is meant to be live. Otherwise accept that spawns 2..N run with recall gating silently off.
|
|
50
|
+
|
|
51
|
+
## Reading the driver's stop reasons
|
|
52
|
+
|
|
53
|
+
The driver names thirteen stop reasons (`drive_epic.py`'s `STOP_*` constants). Three mean the invocation finished its work and exit 0: `all-done`, `limit-reached`, `dry-run`. Every other stop is a fail-closed halt and exits 1, so a wrapper can branch on the exit code before it parses anything.
|
|
54
|
+
|
|
55
|
+
These six are the ones you will actually meet in a working week, and getting them confused wastes a spawn or, worse, propagates an ungated story. The rest name their own cause and need no table: `dry-run`, the pre-spawn refusals (`no-sprint-status`, `epic-not-found`, `sprint-status-elsewhere`, `stale-result`), a row carrying a status the driver does not recognize (`unknown-status`), and a drive that was killed (`signalled`).
|
|
56
|
+
|
|
57
|
+
| Stop reason | What happened | What to do |
|
|
58
|
+
|---|---|---|
|
|
59
|
+
| `all-done` | Every story of the Epic is `done`. | Nothing. The Epic is finished. |
|
|
60
|
+
| `limit-reached` | Normal. `--limit` was reached. | Nothing. Drive again. |
|
|
61
|
+
| `blocked` | The story escalated, and a typed sidecar holds the pending decision. | Run `/ucg-resolve`, which reconstructs every pending decision from the sidecars and walks them. |
|
|
62
|
+
| `no-terminal` | The spawn exited without a readable result envelope. | **The work may be complete.** See below. |
|
|
63
|
+
| `no-progress` | The spawn reported `complete` but the row is not `done`. | Usually a split. Check whether a *child* advanced (`/ucg-status`). |
|
|
64
|
+
| `session-timeout` | The spawn outran `--session-timeout` (two hours by default). | Re-drive. The in-flight story is un-gated; see `no-terminal` below. |
|
|
65
|
+
|
|
66
|
+
Reading the `blocked` sidecar by hand instead: it is `<impl-artifacts>/escalation-<story-id>.json`, four string fields (`source`, `kind`, `decision_needed`, `evidence`), and it is distinct from the `.escalation-<story>.md` marker the Stop hook writes. Not every `blocked` terminal has one: a Stage 1 refusal carries its whole decision in the `reason` the driver already printed.
|
|
67
|
+
|
|
68
|
+
### `no-terminal`: the work is often done, and the story file may lie about it
|
|
69
|
+
|
|
70
|
+
A spawn that dies on a transient upstream error (an API 500, for instance) can have already committed its work and run its full verification, and still leave no gate artifact.
|
|
71
|
+
|
|
72
|
+
The dangerous part is what it leaves behind. In the observed case the dead session **had already written its own close-out into the story file, reading "gate PASS"**, while there was no `trace-*.md`, no `gate-decision-*.json`, no decision-log entry, and `sprint-status.yaml` still said `ready-for-dev`. The gate had never run.
|
|
73
|
+
|
|
74
|
+
**On any resume, believe the artifacts and the sprint-status row, never the story file's prose.** Check for the gate *file* before treating a story as gated.
|
|
75
|
+
|
|
76
|
+
The correct recovery is to re-drive the story. The skill re-enters at Execute, re-measures the committed tree, produces the trace evidence (TEA's `bmad-testarch-trace`, or hand-authored to `gate_eval.py`'s shape on a stack where TEA's browser chain cannot run), and runs `gate_eval.py` for real. Because the dead session already committed, make sure the re-drive re-reads the story's existing baseline marker rather than regenerating it: a rebuilt baseline re-anchors the evidence range to a mid-story HEAD, and the trace then measures only the tail of the work.
|
|
77
|
+
|
|
78
|
+
Do not hand-mark the story `done` on the strength of your own verification, however thorough: that substitutes your judgment for the gate and produces exactly the artifact-free "PASS" the tool exists to prevent.
|
|
79
|
+
|
|
80
|
+
### `no-progress`: check for a split before assuming failure
|
|
81
|
+
|
|
82
|
+
If a spawn splits its story into children and advances a child, the parent row stays un-`done`, so the driver correctly reports that the story it was told to drive did not advance. Nothing is wrong. Confirm a child went `done` and that the children are ordered ahead of the parent.
|
|
83
|
+
|
|
84
|
+
## Sequencing: row order is the only mechanism
|
|
85
|
+
|
|
86
|
+
This is the single most surprising thing about operating the driver.
|
|
87
|
+
|
|
88
|
+
**`pending_ids` keeps every story row that is not `done`**, `epic_stories` hands them over in file order, and the drive loop takes the first of those. Setting a story to `backlog`, or inventing a `blocked` status, changes nothing: the driver will still pick it. `epic-N`, retrospective and `BUG-` rows are filtered out upstream and are never drivable.
|
|
89
|
+
|
|
90
|
+
So the only way to gate story B behind story A is to **put A above B in `sprint-status.yaml`**. `done` is the only status the machine reads; every other value is documentation for humans, and order is what sequences the run. The `done` match is exact, so a hand-edited `Done` or `DONE` row reads as pending and gets re-driven.
|
|
91
|
+
|
|
92
|
+
Two consequences:
|
|
93
|
+
|
|
94
|
+
- **Verify a sequencing change by asking the driver, not by reading the file.** Reading `sprint-status.yaml` tells you what you wrote, not what the driver will pick. `--dry-run` ([introduced in getting started](./getting-started.md)) prints one line per story it would spawn, in the order it would take them, and starts nothing. Add `--limit 1` to print exactly the row that gets picked next. That makes it the cheap check to run after every edit to that file. For a stronger assertion, import the driver's own functions from the project root and read the index directly. These are `@internal` (see the stability policy) and can change without a deprecation note:
|
|
95
|
+
|
|
96
|
+
```bash
|
|
97
|
+
python3 - <<'PY'
|
|
98
|
+
import sys, pathlib
|
|
99
|
+
sys.path.insert(0, ".claude/skills/ultracode-goal/scripts")
|
|
100
|
+
import preflight_check, drive_epic
|
|
101
|
+
root = pathlib.Path(".") # edit these two
|
|
102
|
+
arts = pathlib.Path("_bmad-output/implementation-artifacts") # to match your project
|
|
103
|
+
st = drive_epic.epic_stories(
|
|
104
|
+
preflight_check.build_rollup(root, arts), drive_epic.normalise_epic("7")) or []
|
|
105
|
+
print(drive_epic.pending_ids(st)[:3])
|
|
106
|
+
PY
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
Keep the `or []`: it is what turns a mistyped epic id into an empty list instead of a traceback.
|
|
110
|
+
|
|
111
|
+
- **Umbrella stories belong last.** A story that "ships nothing of its own" and only completes when its children do will otherwise be picked, burn a full spawn discovering it has no work, and stop with `no-progress`.
|
|
112
|
+
|
|
113
|
+
An umbrella row is the one row worth hand-marking `done`, and it is not a license to hand-mark a story that had work (see the `no-terminal` recovery above). Know what it costs: the Epic-level trace gate fires on *every* story of the Epic being `done`, and a drive that finds the Epic already all-done stops without spawning. So mark it inside a run that then authors the Epic-level gate and Finalize, or accept that the Epic closes with neither.
|
|
114
|
+
|
|
115
|
+
When you move a row, leave the reasoning in a comment beside it. A future session reading an unexplained reorder will assume it was accidental and undo it.
|
|
116
|
+
|
|
117
|
+
## When a story escalates as too large
|
|
118
|
+
|
|
119
|
+
Expect this. In the epic behind these notes, stories drafted before the substrate they depend on existed ran two to four times one invocation: three consecutive stories split (into 3, 3, and 4 pieces), and every split was diagnosed by measurement rather than estimated up front.
|
|
120
|
+
|
|
121
|
+
### Keep real call sites in every half
|
|
122
|
+
|
|
123
|
+
The tempting split is primitive-from-call-sites: land the mechanism in one story, adopt it in the next. **Resist it when a guard needs both.** A primitive with no call site cannot have a non-vacuous whole-tree guard: no scan finds anything, and the acceptance test degrades into an assertion about intent.
|
|
124
|
+
|
|
125
|
+
Prefer a split along a domain boundary where each half keeps genuine callers and a genuine test subject.
|
|
126
|
+
|
|
127
|
+
### If you must split a primitive out, use an enumerated exemption list
|
|
128
|
+
|
|
129
|
+
When the first half genuinely cannot satisfy a whole-tree guard, ship the guard at full strength and have it **enumerate, by name, every site still outstanding**, printing the list on every run including passing ones. Then make emptying the list the last half's Definition of Done, and delete the exemption mechanism with it rather than leaving an empty array.
|
|
130
|
+
|
|
131
|
+
This keeps the first half honest (it does not claim the acceptance criterion) while keeping the guard live and the debt visible. Observed working: the list shrank on each story and reached zero across two of them, each entry naming the story that owed it, and the guard was mutation-proved live at every stage.
|
|
132
|
+
|
|
133
|
+
### Check sibling stories before accepting a plan
|
|
134
|
+
|
|
135
|
+
A split plan derived from the work in front of you can rest on a change that another story forbids.
|
|
136
|
+
|
|
137
|
+
Observed: one story's preserved work-in-progress made a destructive schema change that a later story in the same epic explicitly forbade, having pre-registered the objection as "a blocking finding to raise" against precisely this story. **Grep the epic for constraints on anything you are about to change destructively.**
|
|
138
|
+
|
|
139
|
+
The consequence went further than the schema. The earlier conclusion "no green subset exists, so this story is atomic" had been measured over a configuration built on the forbidden change. Correcting it dissolved the coupling and the substrate landed green with nothing rewired.
|
|
140
|
+
|
|
141
|
+
**Generalizable: when a measurement says a change is atomic, check whether the coupling comes from the change being wrong before accepting it as a property of the problem.**
|
|
142
|
+
|
|
143
|
+
## Verifying a spawn's own report
|
|
144
|
+
|
|
145
|
+
The gate is a real verdict and worth trusting. The prose around it is not evidence. A short independent pass catches things a green gate does not.
|
|
146
|
+
|
|
147
|
+
**Re-measure the committed tree, not the working tree.** A spawn mid-write leaves files dirty; a sweep taken then describes something that was never committed. Check `git status` is clean and that HEAD is what you expect before running anything.
|
|
148
|
+
|
|
149
|
+
**Mutation-test every new guard.** Reading a guard never finds its blindness. Delete or invert its subject and confirm it goes red. In the observed epic, six guards were mutation-proved this way and all six were live, but two *tests* were found vacuous by the same method, and one guard's own twin turned out to model the dropped constraint rather than delete it, which is strictly weaker.
|
|
150
|
+
|
|
151
|
+
**Prefer executed mutation over a modeled mutant.** A hand-written mutant that differs from the real pre-fix code proves nothing about the real branch. Where a story claims a mutation-proof, re-run one yourself against the shipped code.
|
|
152
|
+
|
|
153
|
+
**Make the mutation harness hard-error on a missing anchor.** Observed: a harness silently skipped its mutation twice when a refactor moved the anchor, and reported the suite's ordinary green as a passing twin.
|
|
154
|
+
|
|
155
|
+
**Back files up with `cp` and restore from the backup.** Never `git checkout -- <path>` or `git restore <path>` to undo a mutation: both restore from the *index*, and an intent-to-add entry (`git add -N`) holds the empty blob, so they truncate the file to zero bytes and exit 0 (measured on git 2.47). For a file that has a committed version, `git checkout HEAD -- <path>` is safe. For a file the story just created, nothing git offers is: `git checkout HEAD --` refuses, and `git restore --source=HEAD --` deletes the file with exit 0. The `cp` backup is the only restore that always works.
|
|
156
|
+
|
|
157
|
+
## Verification traps that produce confident false greens
|
|
158
|
+
|
|
159
|
+
Each of these was hit while verifying real work, and each one first looked like a result.
|
|
160
|
+
|
|
161
|
+
**The piped exit code.** `cmd | tail && echo OK || echo FAIL` reports `tail`'s exit status, not `cmd`'s. A scanner that correctly exited 1 was recorded as "green, the guard is dead". `$?` after a pipeline is *also* `tail`'s status, so capturing it changes nothing. Use `${PIPESTATUS[0]}` on the very next line (after `&& echo OK || echo FAIL` it has already been overwritten), or put `set -o pipefail` in front of the pipeline, or drop the pipe and capture `$?` from the bare command. `PIPESTATUS` is bash only: in a `sh` or Makefile recipe use `set -o pipefail` where the shell supports it, or drop the pipe.
|
|
162
|
+
|
|
163
|
+
**The self-matching process check.** `pgrep -af "drive_epic.py --epic 7"` matches the shell command containing that pattern, so it finds itself. Read carelessly, a stopped drive looks alive. Match on something your own command line cannot contain (`--epic [7]`) and read the exit status rather than the output. Note the Bash tool puts your whole command string in the wrapping shell's argv, so the bracket trick only holds while the plain pattern appears nowhere else in the same call.
|
|
164
|
+
|
|
165
|
+
**Probe errors that masquerade as findings.** Three separate times, a failed reproduction looked like a refutation or a discovered property:
|
|
166
|
+
|
|
167
|
+
- A function read its input from disk and ignored the text passed to it, so both arms of a comparison returned the same violation.
|
|
168
|
+
- A field was named differently than the probe assumed, so every containment check silently read `undefined`, producing a "0 of 40 correct" result that was pure probe error.
|
|
169
|
+
- A compile error on a misremembered constructor name made a type look like it had *no* such constructor at all. It had one, under a different name, and the property nearly reported was false.
|
|
170
|
+
|
|
171
|
+
**On a typed API, a compile error is evidence about your probe first and about the subject second.** Check the probe before reporting either a finding or a clean result.
|
|
172
|
+
|
|
173
|
+
**A red-phase gate can pass over an empty collection.** A suite that runs *no cases* can still exit 0: a test target compiled out or filtered away (`cargo test` prints `running 0 tests ... ok`), a runner told `--passWithNoTests` with nothing matched, or an exit code swallowed by a pipe (see above). A missing subject module is the opposite case and is loud, not silent: pytest exits 2 on the collection error and 5 when it merely collects nothing, vitest exits 1 even under `--passWithNoTests`, and `cargo test` exits 101. So read the collected count *as well as* the exit code, and assert the count is the number you expect. UCG's own red phase is an all-skipped suite, which correctly exits 0 with every case reported *skipped*: a zero in the collected column is the thing to distrust, not a zero exit.
|
|
174
|
+
|
|
175
|
+
**A `not.toContain` over an empty container is vacuous**, as is any absence assertion whose container is empty for an unrelated reason. Assert something positive alongside it: that the scan found a non-zero number of items, that the batch is non-empty, that the file count is not zero.
|
|
176
|
+
|
|
177
|
+
## Environment gotchas
|
|
178
|
+
|
|
179
|
+
**UCG's own empty-index guard constrains tool sequencing.** The PreToolUse guard inspects the command string before it runs, so a `git add <paths> && git commit` that relies on its own `add` to fill the index is denied: at evaluation time the index is still empty. Stage in one call, commit in the next. This is not a host-project quirk, it is one of the guard's invariants, armed in every project UCG runs in, and the deny message says exactly this. Two sharper edges: it probes the staged index in the hook event's working directory, so it can refuse a commit you aimed at a different checkout, and two command shapes still deny on a mere *mention* of the verb (inside `$(...)` or backticks), so write prose about committing with Write or Edit rather than a Bash heredoc.
|
|
180
|
+
|
|
181
|
+
**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.**
|
|
182
|
+
|
|
183
|
+
**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
|
@@ -5,6 +5,8 @@ description: Maps the real failure modes of an autonomous Epic run (preflight re
|
|
|
5
5
|
|
|
6
6
|
Real failure modes, sourced from the skill's stage files and scripts, with what the run does about each and what you do. For the design behind these behaviors see [how it works](./how-it-works.md), [the gate model](./gate-model.md), and [architecture](./architecture.md).
|
|
7
7
|
|
|
8
|
+
For the operator's side of a run that is technically working and still not doing what you meant, see [operating tips](./operating-tips.md). It covers the driver stop reasons that need a decision, why row order is the only sequencing mechanism, and the verification traps that produce confident false greens.
|
|
9
|
+
|
|
8
10
|
Start from the symptom you observed and follow it to the section that explains it:
|
|
9
11
|
|
|
10
12
|
```mermaid
|
|
@@ -19,9 +21,11 @@ flowchart TD
|
|
|
19
21
|
B -->|"yes"| BUD["See: Budget exhausted mid-story"]
|
|
20
22
|
B -->|"no"| R{"Run was interrupted, want to continue"}
|
|
21
23
|
R -->|"yes"| RES["See: Resume after an interruption"]
|
|
22
|
-
R -->|"no"|
|
|
24
|
+
R -->|"no"| D{"A drive stopped and you cannot tell why"}
|
|
25
|
+
D -->|"yes"| OPS["See: operating tips, the driver's stop reasons"]
|
|
26
|
+
D -->|"no"| PAR["See: --parallel issues"]
|
|
23
27
|
classDef accent fill:#6366F1,stroke:#4F46E5,color:#fff
|
|
24
|
-
class PRE,GATE,HOOK,BUD,RES,PAR accent
|
|
28
|
+
class PRE,GATE,HOOK,BUD,RES,OPS,PAR accent
|
|
25
29
|
```
|
|
26
30
|
|
|
27
31
|
## Preflight can't reach budget-zero
|
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": "2.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",
|
|
@@ -16,12 +16,15 @@ verdict and remediation lands in `.decision-log.md`.
|
|
|
16
16
|
|
|
17
17
|
## Conventions
|
|
18
18
|
|
|
19
|
-
- This
|
|
19
|
+
- This skill ships no `scripts/` or `customize.toml` of its own: the kernel
|
|
20
20
|
(`formalize_check.py`, `headless_envelope.py`), `customize.toml`, and `references/`
|
|
21
|
-
all live in the **parent
|
|
22
|
-
|
|
23
|
-
`{
|
|
24
|
-
|
|
21
|
+
all live in the **parent `ultracode-goal` module**. `{ucg-root}` names that module
|
|
22
|
+
directory — `{project-root}/_bmad/ucg/ultracode-goal` in an installed project, or
|
|
23
|
+
`{project-root}/skills/ultracode-goal` in a source checkout of the module itself.
|
|
24
|
+
Resolve it once (first of those two that exists) and qualify every script path with
|
|
25
|
+
it, so `{ucg-root}/scripts/…` and `{ucg-root}/customize.toml` resolve from any cwd.
|
|
26
|
+
It is deliberately **not** `{skill-root}`: this is a top-level skill, so `{skill-root}`
|
|
27
|
+
would resolve to this skill's own directory, which holds none of those files.
|
|
25
28
|
- `{project-root}`-prefixed paths resolve from the project working directory.
|
|
26
29
|
- `{workflow.implementation_artifacts}` and `{workflow.tea_config_path}` resolve from
|
|
27
30
|
the parent module's `customize.toml` workflow block (the same scalars the autonomous
|
|
@@ -36,8 +39,8 @@ verdict and remediation lands in `.decision-log.md`.
|
|
|
36
39
|
`/ucg-formalize` can run cold (outside an active `ultracode goal` run), so resolve the
|
|
37
40
|
scalars the step-1 kernel consumes before calling it — against the **parent** module, so
|
|
38
41
|
they are the same scalars the autonomous run reads. Run `python3
|
|
39
|
-
{project-root}/_bmad/scripts/resolve_customization.py --skill {
|
|
40
|
-
(on failure, merge `{
|
|
42
|
+
{project-root}/_bmad/scripts/resolve_customization.py --skill {ucg-root} --key workflow`
|
|
43
|
+
(on failure, merge `{ucg-root}/customize.toml` →
|
|
41
44
|
`{project-root}/_bmad/custom/ultracode-goal.toml` →
|
|
42
45
|
`{project-root}/_bmad/custom/ultracode-goal.user.toml`, scalars override / arrays append),
|
|
43
46
|
and load `{planning_artifacts}` from `{project-root}/_bmad/config.yaml` (root + `bmm`
|
|
@@ -49,10 +52,10 @@ blocker list, so the Headless `reason` renders.
|
|
|
49
52
|
## 1. Run the readiness kernel
|
|
50
53
|
|
|
51
54
|
Resolve the Epic id `<id>` the operator named, then run the readiness kernel — qualified
|
|
52
|
-
by `{
|
|
55
|
+
by `{ucg-root}` so it resolves from any cwd:
|
|
53
56
|
|
|
54
57
|
```
|
|
55
|
-
uv run {
|
|
58
|
+
uv run {ucg-root}/scripts/formalize_check.py --epic <id> --project-root {project-root} --planning-artifacts {planning_artifacts} --impl-artifacts {workflow.implementation_artifacts} --tea-config {workflow.tea_config_path}
|
|
56
59
|
```
|
|
57
60
|
|
|
58
61
|
Read the kernel's readiness verdict JSON from stdout. Its shape is
|
|
@@ -162,7 +165,7 @@ autonomous parent `SKILL.md` shape: `skill` is the constant `ultracode-goal` (ne
|
|
|
162
165
|
into the envelope.
|
|
163
166
|
|
|
164
167
|
Serialize the envelope through the one shared adapter
|
|
165
|
-
`{
|
|
168
|
+
`{ucg-root}/scripts/headless_envelope.py` (`build_headless_envelope`) — the same
|
|
166
169
|
definition `references/preflight.md` uses — passing the ordered blocker list
|
|
167
170
|
from step 4. The adapter emits the canonical keys and the positional `reason`
|
|
168
171
|
(`blockers[0]`), so this entry point and the autonomous run cannot serialize a blocked
|
|
@@ -15,16 +15,20 @@ back to the resume the module already has.
|
|
|
15
15
|
The loop only counts as closed if an answer given here is not asked for again. So a
|
|
16
16
|
decision resolved at this surface is consumed by the next preflight's semantic
|
|
17
17
|
intervention scan and does not re-fire — that consumption lives in
|
|
18
|
-
`{
|
|
18
|
+
`{ucg-root}/references/preflight.md`, step 3, and it is the half that makes this skill
|
|
19
19
|
more than a note-taker.
|
|
20
20
|
|
|
21
21
|
## Conventions
|
|
22
22
|
|
|
23
|
-
- This
|
|
24
|
-
`customize.toml`, and `references/` all live in the **parent
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
23
|
+
- This skill ships no `scripts/` or `customize.toml` of its own: the scripts,
|
|
24
|
+
`customize.toml`, and `references/` all live in the **parent `ultracode-goal`
|
|
25
|
+
module**. `{ucg-root}` names that module directory —
|
|
26
|
+
`{project-root}/_bmad/ucg/ultracode-goal` in an installed project, or
|
|
27
|
+
`{project-root}/skills/ultracode-goal` in a source checkout of the module itself.
|
|
28
|
+
Resolve it once (first of those two that exists) and qualify every script path with
|
|
29
|
+
it, so `{ucg-root}/scripts/…` and `{ucg-root}/customize.toml` resolve from any cwd.
|
|
30
|
+
It is deliberately **not** `{skill-root}`: this is a top-level skill, so `{skill-root}`
|
|
31
|
+
would resolve to this skill's own directory, which holds none of those files.
|
|
28
32
|
- `{project-root}`-prefixed paths resolve from the project working directory.
|
|
29
33
|
- `{workflow.implementation_artifacts}` and `{workflow.deferred_work_path}` resolve from
|
|
30
34
|
the parent module's `customize.toml` workflow block (the same scalars the autonomous
|
|
@@ -37,8 +41,8 @@ more than a note-taker.
|
|
|
37
41
|
`/ucg-resolve` normally runs **cold** — the operator arrives at a run that stopped, in a
|
|
38
42
|
session that never saw it start. That is the whole point of this surface, so resolve the
|
|
39
43
|
scalars before reading any artifact. Run `python3
|
|
40
|
-
{project-root}/_bmad/scripts/resolve_customization.py --skill {
|
|
41
|
-
(on failure, merge `{
|
|
44
|
+
{project-root}/_bmad/scripts/resolve_customization.py --skill {ucg-root} --key workflow`
|
|
45
|
+
(on failure, merge `{ucg-root}/customize.toml` →
|
|
42
46
|
`{project-root}/_bmad/custom/ultracode-goal.toml` →
|
|
43
47
|
`{project-root}/_bmad/custom/ultracode-goal.user.toml`, scalars override / arrays append).
|
|
44
48
|
|
|
@@ -72,7 +76,7 @@ and anything not written down is not a pending decision this surface can honor.
|
|
|
72
76
|
|
|
73
77
|
**For a preflight RED, read the `id` off the sidecar entry — never re-derive it.** Each
|
|
74
78
|
entry in `.preflight-reds.json` carries its own minted `id`, written there by the preflight
|
|
75
|
-
that found it (`{
|
|
79
|
+
that found it (`{ucg-root}/references/preflight.md`, step 3). That stored value is the
|
|
76
80
|
one the next preflight matches an answer against, so it is the only id that can close the
|
|
77
81
|
loop — and because it is stored rather than recomputed, a RED a later scan re-detects
|
|
78
82
|
**inherits its existing id** instead of arriving as something nobody has answered. That
|
|
@@ -89,7 +93,7 @@ at four fields and cannot carry one, so it is the one case where an id is derive
|
|
|
89
93
|
than read:
|
|
90
94
|
|
|
91
95
|
```
|
|
92
|
-
uv run {
|
|
96
|
+
uv run {ucg-root}/scripts/red_ids.py --mint-one <kind> <artifact path> <decision_needed>
|
|
93
97
|
```
|
|
94
98
|
|
|
95
99
|
It prints the id and touches nothing. **Never derive an id by hand at either surface.** The
|
|
@@ -121,7 +125,7 @@ exists to remove.
|
|
|
121
125
|
An entry recorded with `action` `defer` is the opposite case: it is a parked question, not
|
|
122
126
|
an answered one. Present it again, and replace its entry in place when the operator decides
|
|
123
127
|
it. Suppressing a deferred item would deadlock the run outright — `defer` clears nothing,
|
|
124
|
-
so the next preflight still blocks on that RED (`{
|
|
128
|
+
so the next preflight still blocks on that RED (`{ucg-root}/references/preflight.md`,
|
|
125
129
|
step 3, drops only the ids whose `action` is `close`), while this surface, the only one that
|
|
126
130
|
can answer it, would never ask again. The scan blocks forever on a question the operator is
|
|
127
131
|
no longer offered.
|
|
@@ -168,7 +172,7 @@ The two dispositions are genuinely different things, not two names for one:
|
|
|
168
172
|
|
|
169
173
|
- **`close`** — the decision is made. Apply it immediately, record the entry, and clear
|
|
170
174
|
the artifact that carried it. For a preflight RED, record the entry and then re-apply the
|
|
171
|
-
override through the id layer with `uv run {
|
|
175
|
+
override through the id layer with `uv run {ucg-root}/scripts/red_ids.py --from-sidecar
|
|
172
176
|
--impl-artifacts {workflow.implementation_artifacts}`, which removes it and records the
|
|
173
177
|
closed id in the sidecar's `resolved` audit list. For the other two sources, delete the answered typed
|
|
174
178
|
escalation sidecar, or mark the ledger row resolved. Clearing the RED sidecar is
|
|
@@ -180,9 +184,9 @@ The two dispositions are genuinely different things, not two names for one:
|
|
|
180
184
|
**Closing a `budget-overrun` escalation also resets that story's turn counter** — delete
|
|
181
185
|
`{workflow.implementation_artifacts}/.budget-<story_id>.json`, or set its `turns` to `0`.
|
|
182
186
|
The Stop hook's counter is persistent and monotonic
|
|
183
|
-
(`{
|
|
187
|
+
(`{ucg-root}/scripts/hooks/budget_stop.py` increments it every Stop event and escalates
|
|
184
188
|
once it reaches the ceiling), and no ordinary resume clears it — the Stage 2 arming purge
|
|
185
|
-
(`{
|
|
189
|
+
(`{ucg-root}/references/preflight.md`, step 5) deliberately skips it on re-entry so a story cannot evade its ceiling by stopping and
|
|
186
190
|
resuming. Leave it standing here and the resumed story escalates again on its **first**
|
|
187
191
|
Stop event, before it has done a single turn of the work the operator just authorized, and
|
|
188
192
|
the close would apply in name only. Answering a budget overrun by re-scoping, splitting,
|
|
@@ -18,12 +18,15 @@ one move: run the renderer and show what came back.
|
|
|
18
18
|
|
|
19
19
|
## Conventions
|
|
20
20
|
|
|
21
|
-
- This
|
|
22
|
-
(`status_render.py`), `customize.toml`, and `references/` all live in the **parent
|
|
23
|
-
`ultracode-goal
|
|
24
|
-
|
|
25
|
-
`{
|
|
26
|
-
|
|
21
|
+
- This skill ships no `scripts/` or `customize.toml` of its own: the renderer
|
|
22
|
+
(`status_render.py`), `customize.toml`, and `references/` all live in the **parent
|
|
23
|
+
`ultracode-goal` module**. `{ucg-root}` names that module directory —
|
|
24
|
+
`{project-root}/_bmad/ucg/ultracode-goal` in an installed project, or
|
|
25
|
+
`{project-root}/skills/ultracode-goal` in a source checkout of the module itself.
|
|
26
|
+
Resolve it once (first of those two that exists) and qualify every script path with
|
|
27
|
+
it, so `{ucg-root}/scripts/…` and `{ucg-root}/customize.toml` resolve from any cwd.
|
|
28
|
+
It is deliberately **not** `{skill-root}`: this is a top-level skill, so `{skill-root}`
|
|
29
|
+
would resolve to this skill's own directory, which holds none of those files.
|
|
27
30
|
- `{project-root}`-prefixed paths resolve from the project working directory.
|
|
28
31
|
- `{workflow.implementation_artifacts}` and `{workflow.deferred_work_path}` resolve from
|
|
29
32
|
the parent module's `customize.toml` workflow block (the same scalars the autonomous
|
|
@@ -38,8 +41,8 @@ one move: run the renderer and show what came back.
|
|
|
38
41
|
exactly the situation where nobody can see the transcript any more. Resolve the scalars
|
|
39
42
|
the renderer needs before calling it, against the **parent** module, so they are the same
|
|
40
43
|
paths the autonomous run wrote to. Run `python3
|
|
41
|
-
{project-root}/_bmad/scripts/resolve_customization.py --skill {
|
|
42
|
-
(on failure, merge `{
|
|
44
|
+
{project-root}/_bmad/scripts/resolve_customization.py --skill {ucg-root} --key workflow`
|
|
45
|
+
(on failure, merge `{ucg-root}/customize.toml` →
|
|
43
46
|
`{project-root}/_bmad/custom/ultracode-goal.toml` →
|
|
44
47
|
`{project-root}/_bmad/custom/ultracode-goal.user.toml`, scalars override / arrays append).
|
|
45
48
|
|
|
@@ -50,7 +53,7 @@ some other run, or no run, while looking exactly like a real answer.
|
|
|
50
53
|
## 1. Run the renderer
|
|
51
54
|
|
|
52
55
|
```
|
|
53
|
-
uv run {
|
|
56
|
+
uv run {ucg-root}/scripts/status_render.py --impl-artifacts {workflow.implementation_artifacts} --deferred-work {workflow.deferred_work_path} --runs-root {project-root}/_bmad-output/ultracode-goal --repo {project-root}
|
|
54
57
|
```
|
|
55
58
|
|
|
56
59
|
`--deferred-work` carries the scalar Conventions told you to resolve. The two paths are
|