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.
Files changed (33) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/README.md +12 -4
  3. package/docs/_internal/RELEASING.md +3 -2
  4. package/docs/architecture.md +6 -6
  5. package/docs/comparison.md +25 -25
  6. package/docs/gate-model.md +1 -1
  7. package/docs/getting-started.md +9 -5
  8. package/docs/how-it-works.md +5 -5
  9. package/docs/index.md +1 -1
  10. package/docs/operating-tips.md +1 -1
  11. package/docs/troubleshooting.md +6 -3
  12. package/docs/why-ultracode-goal.md +3 -3
  13. package/package.json +6 -2
  14. package/skills/ucg-formalize/SKILL.md +11 -4
  15. package/skills/ucg-resolve/SKILL.md +4 -4
  16. package/skills/ucg-status/SKILL.md +21 -8
  17. package/skills/ultracode-goal/SKILL.md +4 -4
  18. package/skills/ultracode-goal/assets/module.yaml +1 -1
  19. package/skills/ultracode-goal/references/define-done.md +3 -1
  20. package/skills/ultracode-goal/references/execute.md +16 -16
  21. package/skills/ultracode-goal/references/finalize.md +6 -5
  22. package/skills/ultracode-goal/references/gate.md +18 -12
  23. package/skills/ultracode-goal/references/preflight.md +20 -12
  24. package/skills/ultracode-goal/scripts/drive_epic.py +11 -6
  25. package/skills/ultracode-goal/scripts/gate_trail.py +107 -18
  26. package/skills/ultracode-goal/scripts/headless_envelope.py +20 -6
  27. package/skills/ultracode-goal/scripts/hooks/budget_stop.py +41 -22
  28. package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +26 -6
  29. package/skills/ultracode-goal/scripts/preflight_check.py +237 -12
  30. package/skills/ultracode-goal/scripts/status_render.py +96 -19
  31. package/tools/cli/lib/platform-codes.yaml +1 -1
  32. package/tools/cli/lib/ui.js +1 -1
  33. 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 an escalation marker and surfaces a clear message, then
10
- LETS THE STOP PROCEED. Turns are the only thing counted here: this layer sees
11
- one event per stop and no usage totals, so any other ceiling could never fire
12
- and none is claimed.
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 in-condition "…or stop after N turns" clause inside the /goal
16
- condition — the real in-loop bound;
17
- 2. the deterministic gate re-loop budget — a reloop that would exceed
18
- max_turns_per_story becomes an escalate instead;
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 escalation. JSON is best-effort; absence is also valid.
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
- Escalation marker: <impl>/.escalation-<story>.md
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
- sid = os.environ.get("ULTRACODE_STORY_ID")
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.strip()
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 "unknown"
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 budget escalation — story {story}\n\n"
136
- f"Story turn budget exceeded ({detail}). UltraCode-Goal stops this story "
137
- f"and escalates: re-scope, split, or hand off. A Stop hook cannot "
138
- f"interrupt a /goal condition mid-turn, so treat this as advisory — "
139
- f"the deterministic guard is the gate_eval re-loop budget.\n",
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 turn budget exceeded for story {story} ({detail}). "
147
- f"Escalation marker written to {marker}. Stop and escalate this story; "
148
- f"do not keep re-looping."
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; else read from
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
- branch = out.stdout.strip()
147
- return branch or None
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
- sid = os.environ.get("ULTRACODE_STORY_ID")
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.strip()
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 branch).
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 (none here are
32
- inherently un-remediable; true-RED items never reach this script).
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, and the five injected
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), reports the recall latch WITHOUT
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 never move
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
- armed = branch["ok"] and hooks["ok"] and hook_env["ok"]
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 recall latch (reported, never "
956
- "certified), and, with --story, the story's artifact-derived resume "
957
- "route. Exit 0 iff branch+hooks+env are armed. When set, --epic, "
958
- "--tea-config, and the mechanical preflight checks do not run.",
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",