bmad-module-ultracode-goal 2.2.0 → 2.3.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 +2 -2
- package/README.md +12 -4
- package/docs/_internal/RELEASING.md +3 -2
- package/docs/architecture.md +6 -6
- package/docs/comparison.md +25 -25
- package/docs/gate-model.md +1 -1
- package/docs/getting-started.md +9 -5
- package/docs/how-it-works.md +5 -5
- package/docs/index.md +1 -1
- package/docs/operating-tips.md +1 -1
- package/docs/troubleshooting.md +6 -3
- package/docs/why-ultracode-goal.md +3 -3
- package/package.json +6 -2
- package/skills/ucg-formalize/SKILL.md +11 -4
- package/skills/ucg-resolve/SKILL.md +4 -4
- package/skills/ucg-status/SKILL.md +21 -8
- package/skills/ultracode-goal/SKILL.md +4 -4
- package/skills/ultracode-goal/assets/module.yaml +1 -1
- package/skills/ultracode-goal/references/define-done.md +3 -1
- package/skills/ultracode-goal/references/execute.md +16 -16
- package/skills/ultracode-goal/references/finalize.md +6 -5
- package/skills/ultracode-goal/references/gate.md +18 -12
- package/skills/ultracode-goal/references/preflight.md +20 -12
- package/skills/ultracode-goal/scripts/drive_epic.py +11 -6
- package/skills/ultracode-goal/scripts/gate_trail.py +107 -18
- package/skills/ultracode-goal/scripts/headless_envelope.py +20 -6
- package/skills/ultracode-goal/scripts/hooks/budget_stop.py +41 -22
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +26 -6
- package/skills/ultracode-goal/scripts/preflight_check.py +237 -12
- package/skills/ultracode-goal/scripts/status_render.py +96 -19
- package/tools/cli/lib/platform-codes.yaml +1 -1
- package/tools/cli/lib/ui.js +1 -1
- package/tools/validate-docs-links.js +302 -29
|
@@ -6,25 +6,39 @@
|
|
|
6
6
|
"""UltraCode-Goal turn-budget Stop hook (Claude Code hook).
|
|
7
7
|
|
|
8
8
|
Counts Stop events (turns) for the current story against max_turns_per_story.
|
|
9
|
-
On overrun it writes
|
|
10
|
-
LETS THE STOP PROCEED.
|
|
11
|
-
|
|
12
|
-
|
|
9
|
+
On overrun it writes its turn-ceiling marker and surfaces a clear message, then
|
|
10
|
+
LETS THE STOP PROCEED. The conductor promotes that marker to a budget-overrun
|
|
11
|
+
escalation only when the story's gate escalates it on this count; a story
|
|
12
|
+
that advances gets a sizing note instead (references/execute.md).
|
|
13
|
+
|
|
14
|
+
Turns are the only thing counted here: this layer sees one event per stop and
|
|
15
|
+
no usage totals, so any other ceiling could never fire and none is claimed.
|
|
13
16
|
|
|
14
17
|
A runaway story is bounded by three layers, in order of authority:
|
|
15
|
-
1. the
|
|
16
|
-
condition
|
|
17
|
-
|
|
18
|
-
|
|
18
|
+
1. the "…or stop after N turns" clause inside a /goal condition, but only
|
|
19
|
+
when an operator started a /goal whose own condition carries one, and then
|
|
20
|
+
it bounds the session rather than the story: the conductor has no way to
|
|
21
|
+
start a /goal itself, so in most sessions this layer is absent;
|
|
22
|
+
2. the gate's re-loop budget: before each re-loop the conductor reads the
|
|
23
|
+
turn count this hook keeps, and a reloop that would exceed
|
|
24
|
+
max_turns_per_story becomes an escalate. That count advances once per
|
|
25
|
+
Stop, so it cannot see re-loops spent inside a single response;
|
|
19
26
|
3. this hook, as RECORDER. A Stop hook fires only when Claude is *already*
|
|
20
27
|
trying to stop, so it cannot interrupt a /goal condition mid-turn. It
|
|
21
28
|
records the overrun and warns; it is advisory end to end and never blocks.
|
|
22
29
|
|
|
30
|
+
A Stop with no current story at all (no ULTRACODE_STORY_ID and no
|
|
31
|
+
.current-story marker, as before a project's first story's step 0 once the
|
|
32
|
+
hooks are armed) is not a story's turn: nothing is counted and nothing is
|
|
33
|
+
written, so the hook never leaves a stray .budget-unknown.json in the tree.
|
|
34
|
+
An empty or unreadable marker still counts against "unknown", because a
|
|
35
|
+
story may be in flight behind it.
|
|
36
|
+
|
|
23
37
|
Hook contract (reads one JSON object on stdin):
|
|
24
38
|
in : {session_id, cwd, hook_event_name:"Stop", ...}
|
|
25
39
|
out: exit 0. We never set decision:"block" (we WANT the stop to proceed);
|
|
26
40
|
on overrun we emit {systemMessage, suppressOutput:false} so the user
|
|
27
|
-
sees the
|
|
41
|
+
sees the overrun. JSON is best-effort; absence is also valid.
|
|
28
42
|
|
|
29
43
|
State + config (env wins so the conductor injects per-story values):
|
|
30
44
|
ULTRACODE_IMPL_ARTIFACTS state dir; default <cwd>/_bmad-output/implementation-artifacts
|
|
@@ -34,7 +48,7 @@ State + config (env wins so the conductor injects per-story values):
|
|
|
34
48
|
Any other ULTRACODE_* variable a conductor still injects is ignored here.
|
|
35
49
|
|
|
36
50
|
State file: <impl>/.budget-<story>.json {turns:int}
|
|
37
|
-
|
|
51
|
+
Turn-ceiling marker: <impl>/.escalation-<story>.md
|
|
38
52
|
"""
|
|
39
53
|
|
|
40
54
|
import json
|
|
@@ -77,10 +91,11 @@ def _impl_artifacts(cwd: str | None) -> Path | None:
|
|
|
77
91
|
return None
|
|
78
92
|
|
|
79
93
|
|
|
80
|
-
def _current_story(impl: Path | None) -> str:
|
|
81
|
-
|
|
94
|
+
def _current_story(impl: Path | None) -> str | None:
|
|
95
|
+
"""The current story id, "unknown" for an unusable marker, None for none at all."""
|
|
96
|
+
sid = (os.environ.get("ULTRACODE_STORY_ID") or "").strip()
|
|
82
97
|
if sid:
|
|
83
|
-
return sid
|
|
98
|
+
return sid
|
|
84
99
|
if impl is not None:
|
|
85
100
|
marker = impl / ".current-story"
|
|
86
101
|
if marker.is_file():
|
|
@@ -88,7 +103,7 @@ def _current_story(impl: Path | None) -> str:
|
|
|
88
103
|
return marker.read_text(encoding="utf-8").strip() or "unknown"
|
|
89
104
|
except OSError:
|
|
90
105
|
return "unknown"
|
|
91
|
-
return
|
|
106
|
+
return None
|
|
92
107
|
|
|
93
108
|
|
|
94
109
|
def _load_state(path: Path) -> dict:
|
|
@@ -116,6 +131,8 @@ def main() -> None:
|
|
|
116
131
|
_emit(None) # nowhere to keep state; proceed silently
|
|
117
132
|
|
|
118
133
|
story = _current_story(impl)
|
|
134
|
+
if story is None:
|
|
135
|
+
_emit(None) # no story yet: not a story's turn to count
|
|
119
136
|
max_turns = _int_env("ULTRACODE_MAX_TURNS", DEFAULT_MAX_TURNS)
|
|
120
137
|
|
|
121
138
|
state_path = impl / f".budget-{story}.json"
|
|
@@ -132,20 +149,22 @@ def main() -> None:
|
|
|
132
149
|
try:
|
|
133
150
|
marker.parent.mkdir(parents=True, exist_ok=True)
|
|
134
151
|
marker.write_text(
|
|
135
|
-
f"# Turn
|
|
136
|
-
f"Story turn
|
|
137
|
-
f"
|
|
138
|
-
f"
|
|
139
|
-
f"
|
|
152
|
+
f"# Turn ceiling reached: story {story}\n\n"
|
|
153
|
+
f"Story turn ceiling reached ({detail}). Unless this story advances at "
|
|
154
|
+
f"its gate, UltraCode-Goal escalates it: re-scope, split, or hand off. "
|
|
155
|
+
f"If it advances, this is a sizing note, not an escalation. A Stop hook "
|
|
156
|
+
f"cannot interrupt a session mid-turn, so this marker is a record: the "
|
|
157
|
+
f"conductor's checks against this count, at a resume and before each "
|
|
158
|
+
f"re-loop, are what stop the story.\n",
|
|
140
159
|
encoding="utf-8",
|
|
141
160
|
)
|
|
142
161
|
except OSError:
|
|
143
162
|
pass
|
|
144
163
|
|
|
145
164
|
_emit(
|
|
146
|
-
f"UltraCode-Goal
|
|
147
|
-
f"
|
|
148
|
-
f"
|
|
165
|
+
f"UltraCode-Goal: story {story} reached its turn ceiling ({detail}). "
|
|
166
|
+
f"Marker written to {marker}. It escalates if its gate does not advance it; "
|
|
167
|
+
f"if the gate advances it, the overrun becomes a sizing note."
|
|
149
168
|
)
|
|
150
169
|
|
|
151
170
|
|
|
@@ -48,8 +48,8 @@ are NOT imported).
|
|
|
48
48
|
Config resolution (all optional, env wins so the conductor can inject per run):
|
|
49
49
|
ULTRACODE_PROTECTED_BRANCHES comma-separated; default "main,master"
|
|
50
50
|
ULTRACODE_IMPL_ARTIFACTS dir holding run state (story id + markers)
|
|
51
|
-
ULTRACODE_STORY_ID current story id
|
|
52
|
-
<impl_artifacts>/.current-story
|
|
51
|
+
ULTRACODE_STORY_ID current story id (blank counts as unset);
|
|
52
|
+
else read from <impl_artifacts>/.current-story
|
|
53
53
|
ULTRACODE_TEST_ARTIFACTS TEA test-artifacts root; arms the un-skip proof.
|
|
54
54
|
No default is derived here on purpose (see
|
|
55
55
|
_test_artifacts): unset means the check is out
|
|
@@ -143,8 +143,26 @@ def _current_branch(cwd: str | None) -> str | None:
|
|
|
143
143
|
)
|
|
144
144
|
except (OSError, subprocess.SubprocessError):
|
|
145
145
|
return None
|
|
146
|
-
|
|
147
|
-
|
|
146
|
+
if out.returncode == 0:
|
|
147
|
+
branch = out.stdout.strip()
|
|
148
|
+
return branch or None
|
|
149
|
+
# An unborn HEAD (a fresh `git init`, nothing committed) fails rev-parse
|
|
150
|
+
# while still printing the literal `HEAD`, which matched no protected name
|
|
151
|
+
# and let a commit through on an unborn `main`. The symbolic ref still
|
|
152
|
+
# names the branch; outside a repository it fails too, and None stands.
|
|
153
|
+
try:
|
|
154
|
+
ref = subprocess.run(
|
|
155
|
+
["git", "symbolic-ref", "--short", "-q", "HEAD"],
|
|
156
|
+
cwd=cwd or None,
|
|
157
|
+
capture_output=True,
|
|
158
|
+
text=True,
|
|
159
|
+
timeout=10,
|
|
160
|
+
)
|
|
161
|
+
except (OSError, subprocess.SubprocessError):
|
|
162
|
+
return None
|
|
163
|
+
if ref.returncode != 0:
|
|
164
|
+
return None
|
|
165
|
+
return ref.stdout.strip() or None
|
|
148
166
|
|
|
149
167
|
|
|
150
168
|
def _staged_index_nonempty(cwd: str | None) -> bool:
|
|
@@ -200,9 +218,11 @@ def _test_artifacts() -> Path | None:
|
|
|
200
218
|
|
|
201
219
|
|
|
202
220
|
def _current_story(impl: Path | None) -> str | None:
|
|
203
|
-
|
|
221
|
+
# A blank ULTRACODE_STORY_ID counts as unset, as the Stop hook reads it, so
|
|
222
|
+
# both hooks resolve the same story from the same .current-story marker.
|
|
223
|
+
sid = (os.environ.get("ULTRACODE_STORY_ID") or "").strip()
|
|
204
224
|
if sid:
|
|
205
|
-
return sid
|
|
225
|
+
return sid
|
|
206
226
|
if impl is not None:
|
|
207
227
|
marker = impl / ".current-story"
|
|
208
228
|
if marker.is_file():
|
|
@@ -18,8 +18,15 @@ What counts as a mechanical blocker (each adds 1 to `budget`):
|
|
|
18
18
|
minimum versions the run depends on (`/goal`, dynamic workflows, auto memory),
|
|
19
19
|
- no test framework is detected (no playwright/cypress/jest/vitest config,
|
|
20
20
|
no pytest config/conftest.py, and no real package.json `test` script),
|
|
21
|
+
- a BMAD skill the run delegates story creation or implementation to
|
|
22
|
+
(`bmad-create-story`, `bmad-dev-story`) is not installed where Claude Code
|
|
23
|
+
loads skills,
|
|
24
|
+
- HEAD has no commit yet (a fresh `git init`, or an orphan branch): the
|
|
25
|
+
operator commits a baseline on the base branch first, because the run never
|
|
26
|
+
makes the commit its Epic branch would start from,
|
|
21
27
|
- the working tree is dirty (a per-green-story commit needs a clean base),
|
|
22
|
-
- the current branch is a protected branch (the epic must run on its own
|
|
28
|
+
- the current branch is a protected branch (the epic must run on its own
|
|
29
|
+
branch; an unborn HEAD's branch is read from its symbolic ref).
|
|
23
30
|
|
|
24
31
|
`green` is true iff `budget == 0`. A green preflight means there is nothing
|
|
25
32
|
MECHANICAL left to clear; the LLM still owns the true-RED hard gate
|
|
@@ -28,8 +35,9 @@ cannot and does not evaluate.
|
|
|
28
35
|
|
|
29
36
|
Severity is advisory metadata for the LLM, not a gate. `remediable` flags
|
|
30
37
|
blockers the remediation pass can plausibly auto-clear (e.g. scaffold the
|
|
31
|
-
framework, branch off, commit/stash) vs. ones that need a human (
|
|
32
|
-
|
|
38
|
+
framework, branch off, commit/stash) vs. ones that need a human (the Claude
|
|
39
|
+
Code version, a broken git repo, an unborn HEAD, a missing BMAD story skill;
|
|
40
|
+
true-RED items never reach this script).
|
|
33
41
|
|
|
34
42
|
Version gates (from the grounded constraints in .decision-log.md):
|
|
35
43
|
/goal >= 2.1.139, dynamic workflows >= 2.1.154, auto memory >= 2.1.59.
|
|
@@ -52,15 +60,16 @@ false, epics: []), not an error — rollup still exits 0.
|
|
|
52
60
|
Resume-manifest mode (`--assert-armed`): the one deterministic read a resumed
|
|
53
61
|
run makes in place of the tool-action-per-fact environment sweep the resume
|
|
54
62
|
rule otherwise costs (references/execute.md, resume). It asserts the epic
|
|
55
|
-
branch, both hooks with the all-tools PreToolUse matcher,
|
|
63
|
+
branch, both hooks with the all-tools PreToolUse matcher, the five injected
|
|
56
64
|
hook env vars (accepted from the hook command strings OR the inherited process
|
|
57
|
-
env, both of which preflight step 5 permits),
|
|
65
|
+
env, both of which preflight step 5 permits), and the BMAD story skills (a
|
|
66
|
+
BMAD update between spawns can remove them), reports the recall latch WITHOUT
|
|
58
67
|
certifying it (re-latching stays a model-owned Stage 1 step on every resume),
|
|
59
68
|
and, given --story, derives the story's resume route from artifacts alone:
|
|
60
69
|
story-boundary (no baseline), gate-owed (committed, green, un-gated - requires
|
|
61
70
|
--trace-output evidence; without it that route never fires), or mid-story.
|
|
62
|
-
Exit 0 iff branch+hooks+env are armed; the latch and story blocks
|
|
63
|
-
the exit code, because they inform model-owned actions rather than certify
|
|
71
|
+
Exit 0 iff branch+hooks+env+skills are armed; the latch and story blocks
|
|
72
|
+
never move the exit code, because they inform model-owned actions rather than certify
|
|
64
73
|
them.
|
|
65
74
|
|
|
66
75
|
uv run preflight_check.py --assert-armed --project-root <path> \
|
|
@@ -126,6 +135,17 @@ DEFAULT_PROTECTED = ("main", "master")
|
|
|
126
135
|
# in-scope decision (not-yet-done) reads off the leading count.
|
|
127
136
|
STORY_STATUSES = ("done", "in-progress", "ready-for-dev", "review", "backlog")
|
|
128
137
|
|
|
138
|
+
# The BMAD skills the run delegates story creation (Stage 2 remediation, Stage 3)
|
|
139
|
+
# and implementation (Stage 4) to. BMAD Method 6.12 ships both as deprecated
|
|
140
|
+
# shims: a fresh install leaves them out unless asked for (--shims, or Yes at the
|
|
141
|
+
# installer's shim prompt), and an update removes them when told not to keep
|
|
142
|
+
# them, which its prompt recommends. The rest of the BMAD toolbox the run uses
|
|
143
|
+
# installs unconditionally, so only these two are probed.
|
|
144
|
+
# (bmad-generate-project-context is a shim too: from 6.12 it forwards to
|
|
145
|
+
# bmad-project-context, which writes a block into AGENTS.md rather than a
|
|
146
|
+
# project-context.md. The project-context count is advisory and never blocks.)
|
|
147
|
+
BMAD_STORY_SKILLS = ("bmad-create-story", "bmad-dev-story")
|
|
148
|
+
|
|
129
149
|
|
|
130
150
|
def _run(cmd: list[str], cwd: Path | None = None) -> tuple[int, str, str]:
|
|
131
151
|
"""Run a command, returning (returncode, stdout, stderr). 127 if not found."""
|
|
@@ -174,6 +194,31 @@ def _git_branch(project_root: Path) -> str | None:
|
|
|
174
194
|
return out
|
|
175
195
|
|
|
176
196
|
|
|
197
|
+
def _git_unborn(project_root: Path) -> bool:
|
|
198
|
+
"""True when HEAD names a branch with no commit yet (a fresh `git init`).
|
|
199
|
+
|
|
200
|
+
`rev-parse --verify -q HEAD` exits 1 on an unborn HEAD and 128 outside a
|
|
201
|
+
repository, so only the 1 reads as unborn: a missing or broken repository
|
|
202
|
+
is the `git_repo` blocker's to report, not this one's.
|
|
203
|
+
"""
|
|
204
|
+
code, _ = _git(["rev-parse", "--verify", "-q", "HEAD"], project_root)
|
|
205
|
+
return code == 1
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
def _git_unborn_branch(project_root: Path) -> str | None:
|
|
209
|
+
"""The branch an unborn HEAD names, read from the symbolic ref.
|
|
210
|
+
|
|
211
|
+
`_git_branch` needs HEAD to resolve to a commit, so on an unborn HEAD it
|
|
212
|
+
returns None, and that None used to hide the protected-branch blocker on a
|
|
213
|
+
repository with nothing committed. `_git_branch` itself keeps returning None
|
|
214
|
+
there so `--assert-armed` still fails closed on an unborn Epic branch.
|
|
215
|
+
"""
|
|
216
|
+
code, out = _git(["symbolic-ref", "--short", "-q", "HEAD"], project_root)
|
|
217
|
+
if code != 0 or not out:
|
|
218
|
+
return None
|
|
219
|
+
return out
|
|
220
|
+
|
|
221
|
+
|
|
177
222
|
def _git_clean(project_root: Path) -> bool | None:
|
|
178
223
|
code, out = _git(["status", "--porcelain"], project_root)
|
|
179
224
|
if code != 0:
|
|
@@ -470,6 +515,117 @@ def _project_context_count(project_root: Path) -> int:
|
|
|
470
515
|
return sum(1 for _ in project_root.rglob("project-context.md"))
|
|
471
516
|
|
|
472
517
|
|
|
518
|
+
def _skill_roots(project_root: Path) -> tuple[Path, ...]:
|
|
519
|
+
"""Where Claude Code loads a skill that a bare-name invocation reaches: the
|
|
520
|
+
project's .claude/skills (where the BMAD installer copies BMAD's skills)
|
|
521
|
+
and the personal skills dir, under $CLAUDE_CONFIG_DIR when that relocates
|
|
522
|
+
Claude Code's home-directory files, else ~/.claude."""
|
|
523
|
+
roots = [project_root / ".claude" / "skills"]
|
|
524
|
+
config_dir = os.environ.get("CLAUDE_CONFIG_DIR")
|
|
525
|
+
if config_dir:
|
|
526
|
+
# Taken as given, the way Claude Code takes it: no ~ expansion, which
|
|
527
|
+
# would also raise on a ~user this machine does not have.
|
|
528
|
+
roots.append(Path(config_dir) / "skills")
|
|
529
|
+
else:
|
|
530
|
+
try:
|
|
531
|
+
roots.append(Path.home() / ".claude" / "skills")
|
|
532
|
+
except RuntimeError:
|
|
533
|
+
# No resolvable home directory: the project root is the only place.
|
|
534
|
+
pass
|
|
535
|
+
return tuple(roots)
|
|
536
|
+
|
|
537
|
+
|
|
538
|
+
def _skill_file_present(path: Path) -> bool:
|
|
539
|
+
try:
|
|
540
|
+
return path.is_file()
|
|
541
|
+
except OSError:
|
|
542
|
+
# A root this process cannot traverse holds no skill it can confirm;
|
|
543
|
+
# reporting the skill missing beats crashing without a payload.
|
|
544
|
+
return False
|
|
545
|
+
|
|
546
|
+
|
|
547
|
+
def _bmad_skills_installed(project_root: Path) -> dict[str, bool]:
|
|
548
|
+
"""Per story skill, whether a SKILL.md exists under any skill root.
|
|
549
|
+
|
|
550
|
+
The skill directory is the evidence, not BMAD's skill-manifest.csv: the CSV
|
|
551
|
+
lists every installed skill whichever tools the install selected, so a row
|
|
552
|
+
does not prove Claude Code can load it, and a skill directory without its
|
|
553
|
+
SKILL.md is not a skill Claude Code loads.
|
|
554
|
+
"""
|
|
555
|
+
roots = _skill_roots(project_root)
|
|
556
|
+
return {
|
|
557
|
+
skill_id: any(_skill_file_present(root / skill_id / "SKILL.md") for root in roots)
|
|
558
|
+
for skill_id in BMAD_STORY_SKILLS
|
|
559
|
+
}
|
|
560
|
+
|
|
561
|
+
|
|
562
|
+
def _bmad_install(project_root: Path) -> dict:
|
|
563
|
+
"""installation.version and installation.installShims from BMAD's
|
|
564
|
+
_bmad/_config/manifest.yaml, read only to word the missing-skill fix.
|
|
565
|
+
|
|
566
|
+
installShims first appears in 6.12 and is written only when the selected
|
|
567
|
+
modules ship shims, so None means "not recorded", never "declined". A line
|
|
568
|
+
read is enough for the flat, two-space `installation:` block BMAD writes.
|
|
569
|
+
"""
|
|
570
|
+
out: dict = {"version": None, "install_shims": None}
|
|
571
|
+
try:
|
|
572
|
+
text = (project_root / "_bmad" / "_config" / "manifest.yaml").read_text(
|
|
573
|
+
encoding="utf-8"
|
|
574
|
+
)
|
|
575
|
+
except (OSError, UnicodeDecodeError):
|
|
576
|
+
return out
|
|
577
|
+
in_installation = False
|
|
578
|
+
for raw in text.splitlines():
|
|
579
|
+
if not raw.strip() or raw.lstrip().startswith("#"):
|
|
580
|
+
continue
|
|
581
|
+
if not raw[0].isspace():
|
|
582
|
+
in_installation = _strip_inline_comment(raw) == "installation:"
|
|
583
|
+
continue
|
|
584
|
+
if not in_installation:
|
|
585
|
+
continue
|
|
586
|
+
key, sep, value = raw.strip().partition(":")
|
|
587
|
+
if not sep:
|
|
588
|
+
continue
|
|
589
|
+
value = _strip_inline_comment(value).strip('"').strip("'")
|
|
590
|
+
if key == "version" and value:
|
|
591
|
+
out["version"] = value
|
|
592
|
+
elif key == "installShims" and value.lower() in ("true", "false"):
|
|
593
|
+
out["install_shims"] = value.lower() == "true"
|
|
594
|
+
return out
|
|
595
|
+
|
|
596
|
+
|
|
597
|
+
def _bmad_skills_detail(project_root: Path, missing: list[str], install: dict) -> str:
|
|
598
|
+
"""One line (the headless `reason` flattens a blocker to one): what is
|
|
599
|
+
missing, why the run cannot proceed without it, and the fix."""
|
|
600
|
+
detail = (
|
|
601
|
+
"BMAD skill(s) not installed: %s. The run delegates story creation to "
|
|
602
|
+
"bmad-create-story and implementation to bmad-dev-story, and has no "
|
|
603
|
+
"substitute for either (looked for <skill>/SKILL.md under %s)."
|
|
604
|
+
% (", ".join(missing), " and ".join(str(r) for r in _skill_roots(project_root)))
|
|
605
|
+
)
|
|
606
|
+
if install["install_shims"] is False:
|
|
607
|
+
version = install["version"]
|
|
608
|
+
package = "bmad-method@%s" % version if version else "bmad-method"
|
|
609
|
+
# --directory is what makes the installer non-interactive here: --yes
|
|
610
|
+
# alone still prompts for the directory, and without a TTY that prompt
|
|
611
|
+
# exits 0 having installed nothing.
|
|
612
|
+
return detail + (
|
|
613
|
+
" BMAD Method %s was installed without its deprecated shim skills "
|
|
614
|
+
"(installShims: false in _bmad/_config/manifest.yaml), and from 6.12 "
|
|
615
|
+
"these two ship only as shims. Operator fix (the run never installs "
|
|
616
|
+
"them itself), from the project root: "
|
|
617
|
+
"`npx %s install --directory . --shims --yes`."
|
|
618
|
+
% (version or "(version not recorded)", package)
|
|
619
|
+
)
|
|
620
|
+
return detail + (
|
|
621
|
+
" Operator fix (the run never installs them itself): re-run the BMAD "
|
|
622
|
+
"Method installer from the project root with claude-code among its "
|
|
623
|
+
"tools, adding --shims on BMAD 6.12 or later, so both skills land in "
|
|
624
|
+
".claude/skills (BMAD before 6.2 names them differently and needs an "
|
|
625
|
+
"upgrade)."
|
|
626
|
+
)
|
|
627
|
+
|
|
628
|
+
|
|
473
629
|
def build_report(
|
|
474
630
|
project_root: Path,
|
|
475
631
|
epic: str,
|
|
@@ -482,7 +638,10 @@ def build_report(
|
|
|
482
638
|
workflows_ok = _meets(cc_ver, MIN_WORKFLOWS)
|
|
483
639
|
automemory_ok = _meets(cc_ver, MIN_AUTOMEMORY)
|
|
484
640
|
|
|
641
|
+
git_unborn = _git_unborn(project_root)
|
|
485
642
|
git_branch = _git_branch(project_root)
|
|
643
|
+
if git_branch is None and git_unborn:
|
|
644
|
+
git_branch = _git_unborn_branch(project_root)
|
|
486
645
|
git_clean = _git_clean(project_root)
|
|
487
646
|
|
|
488
647
|
tea_flags = _read_toml_or_yaml_flags(tea_config)
|
|
@@ -493,6 +652,8 @@ def build_report(
|
|
|
493
652
|
test_artifacts_dirs = _test_artifacts_dirs(artifacts_root)
|
|
494
653
|
sprint_status_present = _sprint_status_present(project_root, impl_artifacts)
|
|
495
654
|
project_context_count = _project_context_count(project_root)
|
|
655
|
+
bmad_skills = _bmad_skills_installed(project_root)
|
|
656
|
+
bmad_install = _bmad_install(project_root)
|
|
496
657
|
|
|
497
658
|
checks = {
|
|
498
659
|
"cc_version": cc_raw,
|
|
@@ -501,12 +662,15 @@ def build_report(
|
|
|
501
662
|
"automemory_ok": automemory_ok,
|
|
502
663
|
"git_branch": git_branch,
|
|
503
664
|
"git_clean": git_clean,
|
|
665
|
+
"git_unborn": git_unborn,
|
|
504
666
|
"framework_present": framework_present,
|
|
505
667
|
"framework_kind": framework_kind,
|
|
506
668
|
"test_artifacts_dirs": test_artifacts_dirs,
|
|
507
669
|
"sprint_status_present": sprint_status_present,
|
|
508
670
|
"project_context_count": project_context_count,
|
|
509
671
|
"tea_flags": tea_flags,
|
|
672
|
+
"bmad_skills": bmad_skills,
|
|
673
|
+
"bmad_install": bmad_install,
|
|
510
674
|
}
|
|
511
675
|
|
|
512
676
|
blockers: list[dict] = []
|
|
@@ -537,6 +701,21 @@ def build_report(
|
|
|
537
701
|
}
|
|
538
702
|
)
|
|
539
703
|
|
|
704
|
+
missing_skills = [s for s, present in bmad_skills.items() if not present]
|
|
705
|
+
if missing_skills:
|
|
706
|
+
blockers.append(
|
|
707
|
+
{
|
|
708
|
+
"id": "bmad_skills",
|
|
709
|
+
"kind": "dependency",
|
|
710
|
+
"severity": "high",
|
|
711
|
+
"detail": _bmad_skills_detail(project_root, missing_skills, bmad_install),
|
|
712
|
+
# Installing BMAD skills is the operator's call (BMAD itself
|
|
713
|
+
# recommends against keeping its shims); the remediation pass
|
|
714
|
+
# neither installs them nor works around their absence.
|
|
715
|
+
"remediable": False,
|
|
716
|
+
}
|
|
717
|
+
)
|
|
718
|
+
|
|
540
719
|
if not framework_present:
|
|
541
720
|
blockers.append(
|
|
542
721
|
{
|
|
@@ -552,6 +731,36 @@ def build_report(
|
|
|
552
731
|
}
|
|
553
732
|
)
|
|
554
733
|
|
|
734
|
+
if git_unborn:
|
|
735
|
+
baseline = "a baseline of the project (its BMAD install, planning artifacts and skeleton)"
|
|
736
|
+
if git_branch in protected_branches:
|
|
737
|
+
where = "Commit %s on '%s' yourself, then re-run." % (baseline, git_branch)
|
|
738
|
+
else:
|
|
739
|
+
# A baseline committed on an unborn Epic branch would be that
|
|
740
|
+
# branch's root, with no protected base under it: deleting the
|
|
741
|
+
# branch, the run's only undo, would delete the pre-run tree too.
|
|
742
|
+
base = protected_branches[0] if protected_branches else "main"
|
|
743
|
+
where = (
|
|
744
|
+
"Point HEAD at your base branch first (`git symbolic-ref HEAD "
|
|
745
|
+
"refs/heads/%s`), commit %s there yourself, then re-run; never "
|
|
746
|
+
"commit the baseline on an Epic branch." % (base, baseline)
|
|
747
|
+
)
|
|
748
|
+
blockers.append(
|
|
749
|
+
{
|
|
750
|
+
"id": "git_unborn",
|
|
751
|
+
"kind": "git",
|
|
752
|
+
"severity": "high",
|
|
753
|
+
"detail": "HEAD on '%s' has no commit yet (a fresh `git init`, or an "
|
|
754
|
+
"orphan branch). %s The run never makes the commit its Epic branch "
|
|
755
|
+
"would start from: that commit would sit outside its only rollback, "
|
|
756
|
+
"the Epic branch." % (git_branch or "HEAD", where),
|
|
757
|
+
# What the baseline holds is the operator's call. A remediation
|
|
758
|
+
# commit here would become the root commit, on the protected
|
|
759
|
+
# branch or on an Epic branch with nothing under it.
|
|
760
|
+
"remediable": False,
|
|
761
|
+
}
|
|
762
|
+
)
|
|
763
|
+
|
|
555
764
|
if git_clean is False:
|
|
556
765
|
blockers.append(
|
|
557
766
|
{
|
|
@@ -712,6 +921,15 @@ def _assert_hook_env(project_root: Path) -> dict:
|
|
|
712
921
|
return {"sources": sources, "missing": missing, "ok": not missing}
|
|
713
922
|
|
|
714
923
|
|
|
924
|
+
def _assert_bmad_skills(project_root: Path) -> dict:
|
|
925
|
+
"""The story skills a resumed spawn will delegate to, still installed. A
|
|
926
|
+
BMAD update between spawns (its prompt recommends dropping the shims) can
|
|
927
|
+
remove them from a run that passed preflight."""
|
|
928
|
+
installed = _bmad_skills_installed(project_root)
|
|
929
|
+
missing = [s for s, present in installed.items() if not present]
|
|
930
|
+
return {"installed": installed, "missing": missing, "ok": not missing}
|
|
931
|
+
|
|
932
|
+
|
|
715
933
|
def _assert_branch(
|
|
716
934
|
project_root: Path, epic_branch_prefix: str, protected: tuple[str, ...]
|
|
717
935
|
) -> dict:
|
|
@@ -881,10 +1099,12 @@ def build_assert_armed(
|
|
|
881
1099
|
branch = _assert_branch(project_root, epic_branch_prefix, protected)
|
|
882
1100
|
hooks = _assert_hooks(project_root)
|
|
883
1101
|
hook_env = _assert_hook_env(project_root)
|
|
1102
|
+
skills = _assert_bmad_skills(project_root)
|
|
884
1103
|
checks: dict = {
|
|
885
1104
|
"branch": branch,
|
|
886
1105
|
"hooks": hooks,
|
|
887
1106
|
"hook_env": hook_env,
|
|
1107
|
+
"skills": skills,
|
|
888
1108
|
"latch": _read_latch(impl_artifacts, run_id),
|
|
889
1109
|
}
|
|
890
1110
|
if story:
|
|
@@ -912,7 +1132,11 @@ def build_assert_armed(
|
|
|
912
1132
|
"hook env not fully injected; enforcing hardcoded fallbacks for: %s"
|
|
913
1133
|
% ", ".join(hook_env["missing"])
|
|
914
1134
|
)
|
|
915
|
-
|
|
1135
|
+
if not skills["ok"]:
|
|
1136
|
+
reasons.append(
|
|
1137
|
+
_bmad_skills_detail(project_root, skills["missing"], _bmad_install(project_root))
|
|
1138
|
+
)
|
|
1139
|
+
armed = branch["ok"] and hooks["ok"] and hook_env["ok"] and skills["ok"]
|
|
916
1140
|
return {"armed": armed, "checks": checks, "reasons": reasons}
|
|
917
1141
|
|
|
918
1142
|
|
|
@@ -952,10 +1176,11 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
952
1176
|
"--assert-armed",
|
|
953
1177
|
action="store_true",
|
|
954
1178
|
help="Emit only the resume manifest: branch, hooks (incl. the all-tools "
|
|
955
|
-
"matcher), injected hook env, the
|
|
956
|
-
"certified), and, with --story, the story's
|
|
957
|
-
"route. Exit 0 iff branch+hooks+env are
|
|
958
|
-
"--tea-config, and the mechanical preflight
|
|
1179
|
+
"matcher), injected hook env, the BMAD story skills, the recall latch "
|
|
1180
|
+
"(reported, never certified), and, with --story, the story's "
|
|
1181
|
+
"artifact-derived resume route. Exit 0 iff branch+hooks+env+skills are "
|
|
1182
|
+
"armed. When set, --epic, --tea-config, and the mechanical preflight "
|
|
1183
|
+
"checks do not run.",
|
|
959
1184
|
)
|
|
960
1185
|
parser.add_argument(
|
|
961
1186
|
"--story",
|