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.
- package/.claude-plugin/marketplace.json +1 -1
- package/README.md +1 -1
- package/docs/architecture.md +2 -1
- package/docs/cross-session-recall.md +1 -1
- package/docs/gate-model.md +6 -2
- package/docs/how-it-works.md +6 -6
- package/docs/index.md +1 -1
- package/docs/operating-tips.md +3 -2
- package/docs/troubleshooting.md +3 -3
- package/docs/why-ultracode-goal.md +1 -1
- package/package.json +1 -1
- package/skills/ucg-resolve/SKILL.md +40 -1
- package/skills/ucg-status/SKILL.md +3 -2
- package/skills/ultracode-goal/SKILL.md +2 -2
- package/skills/ultracode-goal/references/define-done.md +5 -1
- package/skills/ultracode-goal/references/execute.md +29 -8
- package/skills/ultracode-goal/references/finalize.md +7 -5
- package/skills/ultracode-goal/references/gate.md +83 -17
- package/skills/ultracode-goal/references/ingest-and-scope.md +3 -1
- package/skills/ultracode-goal/references/preflight.md +5 -3
- package/skills/ultracode-goal/scripts/drive_epic.py +59 -4
- package/skills/ultracode-goal/scripts/formalize_check.py +94 -10
- package/skills/ultracode-goal/scripts/gate_trail.py +5 -3
- package/skills/ultracode-goal/scripts/hooks/budget_stop.py +9 -0
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +942 -33
- package/skills/ultracode-goal/scripts/mem_observation.py +13 -6
- package/skills/ultracode-goal/scripts/mutate_check.py +158 -32
- package/skills/ultracode-goal/scripts/operator_owed.py +338 -0
- package/skills/ultracode-goal/scripts/preflight_check.py +208 -6
|
@@ -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
|
-
"""
|
|
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)
|
|
351
|
-
|
|
352
|
-
|
|
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,
|
|
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(
|
|
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
|
|
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
|
|
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(
|
|
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,
|
|
658
|
-
|
|
659
|
-
|
|
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);
|