bmad-module-ultracode-goal 3.0.0 → 3.2.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.
@@ -54,7 +54,16 @@ run over.
54
54
 
55
55
  uv run formalize_check.py --epic <id> --project-root <p> \
56
56
  --planning-artifacts <p> --impl-artifacts <p> --tea-config <p> \
57
- [--scan <the step-3 scan object, or - for stdin>]
57
+ [--story <key> ...] [--scan <the step-3 scan object, or - for stdin>]
58
+
59
+ The in-scope stories are the Epic's not-`done` rows (ingest-and-scope.md Stage 1
60
+ rule 3), or, with `--story` (repeatable), the named ones among them: the
61
+ operator-scoped subset Stage 1 recorded. The per-story and per-AC checks read
62
+ only those stories' files, plus the done parent's file a decomposed child's
63
+ criteria come from, and `story_keys_uncovered` counts only those keys. A
64
+ `--story` key that names no not-`done` story row of the Epic is a
65
+ non-remediable gap, and when no `--story` key names one those checks read no
66
+ story file.
58
67
  """
59
68
 
60
69
  from __future__ import annotations
@@ -345,11 +354,13 @@ def _present_and_readable(path: Path | None) -> bool:
345
354
 
346
355
 
347
356
  def _story_files(impl_artifacts: Path, epic: str, story_keys: list[str]) -> list[Path]:
348
- """Story files under impl-artifacts whose name shares the Epic prefix.
357
+ """Every story file of the Epic under impl-artifacts, `done` ones included.
349
358
 
350
- Stories for an Epic share its number prefix (ingest-and-scope.md:16). Sorted
351
- for determinism. When the rollup named not-done keys, prefer files matching
352
- one of those keys; otherwise fall back to the Epic-prefix glob.
359
+ Stories for an Epic share its number prefix (ingest-and-scope.md:16), and a
360
+ file starting with one of `story_keys` counts too. Sorted for determinism.
361
+ The coverage check reads all of them, since a done parent's file covers its
362
+ decomposed children, and so does the declared-id set. Which of them the
363
+ per-story checks read is `_in_scope_story_files`'s call.
353
364
  """
354
365
  if not impl_artifacts.is_dir():
355
366
  return []
@@ -417,6 +428,34 @@ def _parent_stem(stem: str) -> str | None:
417
428
  return "%s-%s" % (parts[0], lettered.group(1)) if lettered else None
418
429
 
419
430
 
431
+ def _in_scope_story_files(
432
+ story_paths: list[Path], scope_keys: list[str], children: list[tuple[str, Path, str | None]]
433
+ ) -> list[Path]:
434
+ """The story files the per-story and per-AC checks read, in `story_paths` order.
435
+
436
+ Each in-scope key's own file, matched on the id stem as `_story_coverage`
437
+ matches it (the whole key for an alpha-keyed one), and the parent file each
438
+ in-scope decomposed child's criteria come from (`children`). A `done`
439
+ story's file is out of scope (ingest-and-scope.md Stage 1 rule 3), so its
440
+ acceptance criteria raise no gap here. With no in-scope key at all (every
441
+ row `done`, or no rollup to read), every file, as before. The caller never
442
+ asks for that fallback when `--story` was given: a `--story` list that
443
+ names no not-done row reads no file.
444
+ """
445
+ if not scope_keys:
446
+ return list(story_paths)
447
+ stems = {_story_stem(key) for key in scope_keys} - {None}
448
+ alpha = [key.lower() for key in scope_keys if _story_stem(key) is None]
449
+ parents = {parent for _, parent, _ in children}
450
+ return [
451
+ path
452
+ for path in story_paths
453
+ if path in parents
454
+ or _story_stem(path.name) in stems
455
+ or any(path.name.lower().startswith(key) for key in alpha)
456
+ ]
457
+
458
+
420
459
  def _uncovered_story_keys(
421
460
  story_paths: list[Path], story_keys: list[str], rows: dict[str, str] | None = None
422
461
  ) -> list[str]:
@@ -1039,6 +1078,7 @@ def build_verdict(
1039
1078
  impl_artifacts: Path,
1040
1079
  tea_config: Path,
1041
1080
  scan: str | None = None,
1081
+ stories: list[str] | None = None,
1042
1082
  ) -> dict:
1043
1083
  mechanical_gaps: list[dict] = []
1044
1084
  judgment_candidates: list[dict] = []
@@ -1140,6 +1180,31 @@ def build_verdict(
1140
1180
  if _epic_id_of(key) == str(epic)
1141
1181
  }
1142
1182
 
1183
+ # The in-scope keys: every not-done story row, or the operator-scoped
1184
+ # subset `--story` names. A named key that is not a not-done story row of
1185
+ # this Epic (a typo, another Epic's row, a done row) is not silently
1186
+ # dropped: the verdict would then cover less than the run drives.
1187
+ scope_keys = story_keys
1188
+ if stories is not None:
1189
+ requested = list(dict.fromkeys(key.strip() for key in stories))
1190
+ scope_keys = [key for key in story_keys if key in requested]
1191
+ for key in requested:
1192
+ if key in story_keys:
1193
+ continue
1194
+ mechanical_gaps.append(
1195
+ {
1196
+ "id": "story_not_in_scope:%s" % key,
1197
+ "kind": "story_not_in_scope",
1198
+ "severity": "high",
1199
+ "detail": "--story %s names no not-done story row of Epic %s in sprint-status.yaml: %s"
1200
+ % (key, epic, _rel(impl_artifacts / "sprint-status.yaml", project_root)),
1201
+ # The invocation names the scope; only the caller can
1202
+ # correct it.
1203
+ "remediable": False,
1204
+ "source": _rel(impl_artifacts / "sprint-status.yaml", project_root),
1205
+ }
1206
+ )
1207
+
1143
1208
  # --- per-story / per-AC scan ---
1144
1209
  story_paths = _story_files(impl_artifacts, epic, story_keys)
1145
1210
 
@@ -1176,13 +1241,13 @@ def build_verdict(
1176
1241
  # zero case is already the gap above) and only when the rollup actually named
1177
1242
  # keys (with no keys there is nothing to compare against, and inventing a gap
1178
1243
  # from an unknown denominator would block legitimate runs).
1179
- coverage = _story_coverage(story_paths, story_keys, rows)
1244
+ coverage = _story_coverage(story_paths, scope_keys, rows)
1180
1245
  uncovered = coverage.uncovered
1181
1246
  if story_paths and uncovered:
1182
1247
  detail = "Epic %s is partially seeded: %d of %d in-scope stories resolve no story file under impl-artifacts: %s. Unresolved: %s" % (
1183
1248
  epic,
1184
1249
  len(uncovered),
1185
- len(story_keys),
1250
+ len(scope_keys),
1186
1251
  _rel(impl_artifacts, project_root),
1187
1252
  ", ".join(uncovered),
1188
1253
  )
@@ -1208,6 +1273,15 @@ def build_verdict(
1208
1273
  }
1209
1274
  )
1210
1275
 
1276
+ # The files the per-story checks below read: in-scope stories only. A
1277
+ # `--story` list that names no not-done row reads none: its
1278
+ # `story_not_in_scope` gaps already block, and falling back to every file
1279
+ # would bring back the done stories' gaps and candidates.
1280
+ if scope_keys or stories is None:
1281
+ scan_paths = _in_scope_story_files(story_paths, scope_keys, coverage.children)
1282
+ else:
1283
+ scan_paths = []
1284
+
1211
1285
  stories_with_ac = 0
1212
1286
  ac_total = 0
1213
1287
  ac_machine_checkable = 0
@@ -1236,7 +1310,7 @@ def build_verdict(
1236
1310
  prd_text = _safe_read_text(prd_path) if prd_path is not None else None
1237
1311
  declared_ids = _collect_declared_ids(story_bodies, story_keys, prd_text)
1238
1312
 
1239
- for story_path in story_paths:
1313
+ for story_path in scan_paths:
1240
1314
  body = story_reads[story_path]
1241
1315
  rel = _rel(story_path, project_root)
1242
1316
  if body is not None:
@@ -1417,7 +1491,7 @@ def build_verdict(
1417
1491
  )
1418
1492
 
1419
1493
  # --- whole-story-level catch-all + gate-tag absence (reporting + judgment) ---
1420
- for story_path in story_paths:
1494
+ for story_path in scan_paths:
1421
1495
  body = story_reads[story_path]
1422
1496
  if body is None:
1423
1497
  continue
@@ -1507,7 +1581,7 @@ def build_verdict(
1507
1581
  (ac_machine_checkable / ac_total) if ac_total else 0.0
1508
1582
  )
1509
1583
  gate_ability_tag_coverage = (
1510
- (stories_with_gate_tag / len(story_paths)) if story_paths else 0.0
1584
+ (stories_with_gate_tag / len(scan_paths)) if scan_paths else 0.0
1511
1585
  )
1512
1586
 
1513
1587
  checks = {
@@ -1620,6 +1694,13 @@ def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
1620
1694
  "setting judgment_required; an unreadable scan, or one red_ids.py refuses, "
1621
1695
  "judges nothing.",
1622
1696
  )
1697
+ parser.add_argument(
1698
+ "--story",
1699
+ action="append",
1700
+ help="An in-scope story key, as its sprint-status row spells it (repeatable): "
1701
+ "the operator-scoped subset. Without it every not-done story of the Epic is in "
1702
+ "scope. A key that names no not-done story row of the Epic is a non-remediable gap.",
1703
+ )
1623
1704
  args = parser.parse_args(argv)
1624
1705
 
1625
1706
  # Invocation-error lane (exit 2): any required flag missing OR empty. argparse
@@ -1632,6 +1713,8 @@ def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
1632
1713
  ("--tea-config", args.tea_config),
1633
1714
  )
1634
1715
  missing = [name for name, value in required if value is None or value.strip() == ""]
1716
+ if args.story is not None and any(value.strip() == "" for value in args.story):
1717
+ missing.append("--story")
1635
1718
  if missing:
1636
1719
  parser.error("the following arguments are required and non-empty: %s" % ", ".join(missing))
1637
1720
  return args
@@ -1660,6 +1743,7 @@ def main(argv: list[str] | None = None) -> int:
1660
1743
  impl_artifacts=impl_artifacts,
1661
1744
  tea_config=tea_config,
1662
1745
  scan=args.scan if args.scan in (None, "-") else str(_resolve(args.scan, project_root)),
1746
+ stories=args.story,
1663
1747
  )
1664
1748
  print(json.dumps(verdict, sort_keys=True, indent=2))
1665
1749
  return 0
@@ -654,9 +654,11 @@ def commit_sha(impl_artifacts: Path | None, story: str) -> str | None:
654
654
  """The story's recorded END commit, or None when the run wrote no such marker.
655
655
 
656
656
  `references/execute.md` step 4 writes `.commit-<story>` once the commit lands,
657
- step 5 refreshes it after any amend or remediation re-commit, and the gate's
658
- advance route refreshes it after its evidence commit, so it names the
659
- story's LAST commit. Reading it is what lets the trail stop inferring a
657
+ step 5 refreshes it after any amend or remediation re-commit, the gate
658
+ refreshes it after it commits a test `bmad-testarch-automate` backfilled
659
+ (`references/gate.md`, "When automate backfills"), and the gate's advance
660
+ route refreshes it after its evidence commit, so it names the story's LAST
661
+ commit. Reading it is what lets the trail stop inferring a
660
662
  range end from the next story's baseline.
661
663
 
662
664
  The inference it replaces could not be made correct from baselines alone. Two
@@ -34,6 +34,15 @@ written, so the hook never leaves a stray .budget-unknown.json in the tree.
34
34
  An empty or unreadable marker still counts against "unknown", because a
35
35
  story may be in flight behind it.
36
36
 
37
+ Every other Stop counts, including one that ends a response that only
38
+ acknowledged a background task's notification. The Stop input carries the
39
+ response's final text and the tasks still in flight, not its tool calls, and
40
+ the transcript may not hold the final message yet, so the hook cannot tell
41
+ waiting from work and does not try: skipping a Stop on a guess would let a
42
+ story that keeps a task running spend responses the ceiling never sees.
43
+ Execute keeps waits few instead (references/execute.md, "Waiting spends
44
+ turns").
45
+
37
46
  Hook contract (reads one JSON object on stdin):
38
47
  in : {session_id, cwd, hook_event_name:"Stop", ...}
39
48
  out: exit 0. We never set decision:"block" (we WANT the stop to proceed);