bmad-module-ultracode-goal 6.0.0 → 7.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/docs/_internal/STABILITY.md +3 -3
- package/docs/architecture.md +1 -1
- package/docs/getting-started.md +1 -1
- package/docs/how-it-works.md +1 -1
- package/package.json +1 -1
- package/skills/ultracode-goal/references/execute.md +5 -3
- package/skills/ultracode-goal/references/preflight.md +1 -1
- package/skills/ultracode-goal/scripts/claim_check.py +117 -16
- package/skills/ultracode-goal/scripts/drive_epic.py +33 -10
- package/skills/ultracode-goal/scripts/hooks/guard_pretooluse.py +100 -15
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"name": "bmad-module-ultracode-goal",
|
|
20
20
|
"source": "./",
|
|
21
21
|
"description": "Supercharges BMAD with Claude Code's Auto Mode, Auto Memory, and hooks: autonomous Epic execution to a machine-checked, TEA-gated Definition-of-Done. Execute Epics. Accumulate Knowledge. Deliver Outcomes.",
|
|
22
|
-
"version": "
|
|
22
|
+
"version": "7.0.0",
|
|
23
23
|
"author": {
|
|
24
24
|
"name": "Armel"
|
|
25
25
|
},
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Stability and Public Contract
|
|
3
|
-
description: "The
|
|
3
|
+
description: "The 7.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:** 7.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 `7.x`. It enumerates the surfaces a downstream consumer or automator may reasonably depend on, versus everything else, which is `@internal`.
|
|
9
9
|
|
|
10
10
|
## Public contract
|
|
11
11
|
|
package/docs/architecture.md
CHANGED
|
@@ -27,7 +27,7 @@ These are the module's non-negotiables. Each exists because the documented mecha
|
|
|
27
27
|
|
|
28
28
|
A set of invariants must hold before the runtime lets a tool call through, and none of them can live in memory, which is context the model may or may not weigh:
|
|
29
29
|
|
|
30
|
-
- **`scripts/hooks/guard_pretooluse.py`** (PreToolUse): inspects each `git commit`/`git push` and enforces seven invariants. It denies the command on a protected branch; denies a `git commit` when no tests-ran marker (`<impl-artifacts>/.tests-ran-<story_id>`) exists for the current story; denies it when that marker's `baseline=<sha>` does not match the SHA the story recorded at start; denies it when the staged index is empty or unreadable; and denies it, when armed with `ULTRACODE_TEST_ARTIFACTS`, while the staged content of a checklist-enumerated acceptance test still contains `test.skip(`. The last two are not about git at all: they run for every tool call while a Cross-Session Recall latch is present. The sixth denies every claude-mem MCP call and any reach into `.claude-mem`, whatever the latch records. The seventh denies tool calls that name the recall store or would change the latch itself, except the skill's own two recall scripts; reading the latch stays allowed. It returns a `deny` decision in the hook JSON and also exits 2 with the reason on stderr so older clients that ignore the JSON still block. The marker, freshness, staged-index, and recall-latch checks fail **closed**, denying on an input they cannot read. Two do not: the protected-branch check fails **open** when `git rev-parse` cannot report a branch, and the un-skip proof is out of scope entirely when `ULTRACODE_TEST_ARTIFACTS` is unset. The protected-branch check is also scoped to the **session's** working directory rather than the repository the command names, so it denies a `git commit`/`git push` aimed at another checkout whenever the session's own repo is on a protected branch.
|
|
30
|
+
- **`scripts/hooks/guard_pretooluse.py`** (PreToolUse): inspects each `git commit`/`git push` and enforces seven invariants. It denies the command on a protected branch; denies a `git commit` when no tests-ran marker (`<impl-artifacts>/.tests-ran-<story_id>`) exists for the current story; denies it when that marker's `baseline=<sha>` does not match the SHA the story recorded at start; denies it when the staged index is empty or unreadable, or while it holds an intent-to-add entry (`git add -N`, which Execute makes for a story's new files before its sweep), naming each one, since the commit would leave that file out, or, for a mark over a path HEAD holds, delete HEAD's file; and denies it, when armed with `ULTRACODE_TEST_ARTIFACTS`, while the staged content of a checklist-enumerated acceptance test still contains `test.skip(`. The last two are not about git at all: they run for every tool call while a Cross-Session Recall latch is present. The sixth denies every claude-mem MCP call and any reach into `.claude-mem`, whatever the latch records. The seventh denies tool calls that name the recall store or would change the latch itself, except the skill's own two recall scripts; reading the latch stays allowed. It returns a `deny` decision in the hook JSON and also exits 2 with the reason on stderr so older clients that ignore the JSON still block. The marker, freshness, staged-index, intent-to-add, and recall-latch checks fail **closed**, denying on an input they cannot read. Two do not: the protected-branch check fails **open** when `git rev-parse` cannot report a branch, and the un-skip proof is out of scope entirely when `ULTRACODE_TEST_ARTIFACTS` is unset. The protected-branch check is also scoped to the **session's** working directory rather than the repository the command names, so it denies a `git commit`/`git push` aimed at another checkout whenever the session's own repo is on a protected branch.
|
|
31
31
|
- **`scripts/hooks/budget_stop.py`** (Stop): counts turns for the current story against `max_turns_per_story`. On overrun it writes an escalation marker and surfaces a message, then **lets the stop proceed**. Its documented limitation: a Stop hook fires only when Claude is already trying to stop, so it cannot interrupt a `/goal` condition mid-turn. Its count advances once per Stop, so it cannot see re-loops spent inside a single response. The conductor reads it before a story starts and before each re-loop, where the gate's re-loop budget turns a re-loop that would exceed the ceiling into `escalate`. The in-condition "stop after N turns" clause binds only an operator's own `/goal`, since the conductor cannot start one. This hook itself is the recorder. The conductor promotes its marker to a `budget-overrun` escalation only when the story's gate escalates it on that count; a story that advances gets a sizing note instead.
|
|
32
32
|
|
|
33
33
|
Both hooks read their config from env first (so the conductor injects per-run values) and fall back to hardcoded defaults (`main`/`master`, `25`, `ultracode/epic-`). Because of that fallback, a `customize.toml` override **silently no-ops at the enforcement layer** unless the conductor passes it through the hook env, so preflight injects `ULTRACODE_PROTECTED_BRANCHES`, `ULTRACODE_IMPL_ARTIFACTS`, `ULTRACODE_MAX_TURNS`, `ULTRACODE_EPIC_BRANCH_PREFIX`, and `ULTRACODE_TEST_ARTIFACTS`.
|
package/docs/getting-started.md
CHANGED
|
@@ -83,7 +83,7 @@ The driver is read-only on your tree with exactly one exception: it deletes the
|
|
|
83
83
|
|
|
84
84
|
**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.
|
|
85
85
|
|
|
86
|
-
**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>`
|
|
86
|
+
**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 (Execute marks a story's new files that way before each sweep), because `git checkout -- <path>` and `git restore <path>` truncate those to zero bytes and exit `0`, and `git reset --hard` deletes a new one and reverts one git already tracked to its last commit, discarding its edits.
|
|
87
87
|
|
|
88
88
|
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`).
|
|
89
89
|
|
package/docs/how-it-works.md
CHANGED
|
@@ -78,7 +78,7 @@ Turn the Epic's acceptance criteria into **executable, red-phase acceptance test
|
|
|
78
78
|
|
|
79
79
|
### Stage 4: Execute
|
|
80
80
|
|
|
81
|
-
Drive each in-scope story from its red-phase tests to a green, committed state. Execution is the **sequential `/goal` spine**; per story, in sprint order: set the current story (so the PreToolUse hook can find its marker) → `ucg-dev-story` implements the feature and un-skips the story's ATDD tests → run tests/lint/build and **print the raw output** as evidence → (production) `bmad-testarch-test-review` then `bmad-code-review` → check the commit message against the staged diff (`claim_check.py` lists each path it names that the commit does not touch) and soften any claim the diff's own new lines make that no evidence shows → commit at green (one implementation commit per green story; the gate's commits follow it: a test backfill when automate makes one, then the evidence) → **re-run the suite at this cycle's scope on the committed HEAD (a story only advances off a full-scope sweep)** and print it, because a
|
|
81
|
+
Drive each in-scope story from its red-phase tests to a green, committed state. Execution is the **sequential `/goal` spine**; per story, in sprint order: set the current story (so the PreToolUse hook can find its marker) → `ucg-dev-story` implements the feature and un-skips the story's ATDD tests → mark the story's new files intent-to-add (`git add -N`), so a conformance gate scoped to git's tracked files sees them, then run tests/lint/build and **print the raw output** as evidence → (production) `bmad-testarch-test-review` then `bmad-code-review` → check the commit message against the staged diff (`claim_check.py` lists each path it names that the commit does not touch) and soften any claim the diff's own new lines make that no evidence shows → commit at green (one implementation commit per green story; the gate's commits follow it: a test backfill when automate makes one, then the evidence) → **re-run the suite at this cycle's scope on the committed HEAD (a story only advances off a full-scope sweep)** and print it, because a new file no mark reaches (a generated or ignored one, or one made after the last mark) is untracked until the commit, so a tracked-files conformance gate can only red on it once it lands; a red here means the story is not done and must be remediated and re-committed before it advances, except that a red in a case outside the story's changes, whose cause shows inside that test, and that a second sweep at the same commit does not repeat, is logged as flaky and parked on the ledger, with nothing committed. The conductor writes a per-story `/goal`-style condition that encodes the Definition-of-Done and carries the literal "…or stop after N turns" escape clause, and records it in the decision log. A live `/goal` runs only when you start one, on your own condition, because the conductor cannot start `/goal` itself. The Stop hook records a turn count, once per response, which the conductor reads before each story and each re-loop. The printed evidence keeps the run judgeable mid-flight, but **passing the `/goal` condition is not completion**; the authoritative verdict is Stage 5. As the spine advances it overwrites a `run-status.json` heartbeat for pollers. See [`references/execute.md`](https://github.com/armelhbobdad/bmad-module-ultracode-goal/blob/main/skills/ultracode-goal/references/execute.md).
|
|
82
82
|
|
|
83
83
|
### Stage 5: Gate
|
|
84
84
|
|
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": "7.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",
|
|
@@ -77,6 +77,8 @@ For each in-scope story, in sprint order, run this loop (leave out a decomposed
|
|
|
77
77
|
|
|
78
78
|
2. Run the tests, lint, and build, and **PRINT the raw output** (pass/fail counts, lint result, build result) into the transcript. **In a monorepo, scope that test run wide enough to catch cross-package regressions** — run the full suite, or the changed package(s) plus everything downstream of them (e.g. an `--affected` set *and its dependents*), not just this story's own package. A story's change can regress a *sibling* package's conformance gate (a cross-package RBAC, ownership, or architecture-boundary check), and a run scoped to only this story's package reports green while that sibling gate is red — deferring the red (and its fix) to a later story or the Epic gate instead of catching it at the story that caused it. This printed evidence is what keeps the run judgeable mid-flight, and what a `/goal` evaluator reads when the operator started one — but it is *evidence*, not the gate. **Once all three go green, write the tests-ran marker** `{workflow.implementation_artifacts}/.tests-ran-<story_id>` — the PreToolUse guard denies the step-4 commit unless this marker exists for the current story, so write it only after a real green run. **That marker must carry a `baseline=<sha>` line** whose value is the verbatim, whitespace-stripped content of `{workflow.implementation_artifacts}/.baseline-<story_id>` written at step 0 — **copied, never re-derived from `git rev-parse HEAD`** at marker-write time. The guard compares the two strings character for character and denies the commit when they differ or when the line is missing, which is what stops a marker written against an older code state from being replayed to satisfy a later commit. Re-deriving the value here instead of copying it is the trap: on a story that commits more than once, HEAD has already moved past the baseline, so a re-derived line denies the story's own second commit. **Write that marker with the Write tool**, after Reading the baseline file and pasting its line unchanged — for the same reason step 4 writes the decision log with Write/Edit. The obvious Bash form, `printf 'baseline=%s\n' "$(cat …/.baseline-<story_id>)" > …/.tests-ran-<story_id>`, is a command substitution that a harness which statically analyses Bash strings refuses outright (the PreToolUse guard permits it; the refusal comes from above). Hand-retyping the forty hex characters instead is precisely the transcription error the freshness clause exists to catch, and its denial says only that the SHAs differ, never that one was mistyped. **The marker carries the sweep's scope beside its baseline** — two more lines, same file: `scope=<full|scoped>` naming which sweep form this green run was (the re-loop rule below is the only thing that ever writes `scoped`; a first pass writes `scope=full`), and — scoped only — `packages=<the resolved package list>` copied from the runner's own printout, never hand-typed. The gate reads the `scope=` line through `gate_eval.py --tests-ran` and caps a scoped cycle's verdict at `reloop` (`references/gate.md`, the sweep-scope AND), which is what stops a scoped sweep from impersonating a full one at the only place the distinction pays.
|
|
79
79
|
|
|
80
|
+
**Mark this story's new files intent-to-add before every sweep this step runs.** A conformance gate scoped to *tracked* files (a `git ls-files`-based ref, ownership or architecture-boundary check) skips a file git does not track, so an unmarked new file first reaches it at step 5, after the commit, where its red costs an amend and two more full sweeps. Before each sweep, a re-loop's and a resumed session's included, read `git status --porcelain --untracked-files=all` and take this story's own files from its `??` entries: the source and test paths step 4 will stage, the acceptance tests this story's checklist lists among them. Mark them in one call of its own, `git add -N -- <those paths>`, naming each file by its path. Without `-z`, any name git prints inside double quotes is C-quoted (a space, a double quote, a backslash or a control character in it, and under git's default `core.quotePath` a non-ASCII byte, which it writes as an octal escape: `"my file.ts"`, `"caf\303\251.ts"`): pass it as the name it stands for, its escapes decoded and quoted for the shell, never as printed, which matches no file. Never name a folder (git marks every file under it), a sibling story's red-phase tests, anything under `.scratch-<story_id>/` or `evidence-<story_id>/`, a run marker, or a path git ignores. A mark puts the path in the index with no content (the index holds an empty blob for it): a gate that lists git's files now sees the file, nothing of it is staged, and step 4 still stages each one in full. Marking a path the index already holds changes nothing, so a re-loop or a resume runs this again safely. A non-zero exit can leave some paths marked and others not: git refuses an ignored path and marks the rest, and a path that matches no file makes git exit 128 and mark none of the paths in the call. After any non-zero exit, read `git status --porcelain --no-renames --untracked-files=all` again, where a marked file shows as ` A`, and mark again, in one more call, every chosen path still listed `??` that git did not refuse as ignored. When that call fails too, mark nothing more: log the paths left unmarked in `.decision-log.md` and sweep, since step 5 runs the tracked-file gates on the commit. A mark on a path `HEAD` already holds (status `DA`) is cleared by staging the file in place, `git add -- <path>`, since moving it aside would stage its deletion. A marked new file the story will not ship (a sibling story's test marked by mistake, a mark another session left) is moved aside into `{workflow.implementation_artifacts}/.scratch-<story_id>/`, untracked in the run's own folder, then `git add -- <path>` clears its entry, and the file is moved back, where it is untracked again. Delete such a file instead only when nothing needs it. The guard refuses any commit while the index holds a mark (step 4). A gate that fails on any uncommitted change (`git diff --exit-code`, say) reads a mark as one, as it reads an edit to a tracked file. Its red is the state before the commit, and does not count against the tests-ran marker this step writes once all three go green, only when its output names no path but those this story changes or marks: any other path in it (a stale generated file the story never touched, say) makes it a red. State in the printed evidence that the red was read that way. Step 5 runs that gate on the committed tree, where a red is a red.
|
|
81
|
+
|
|
80
82
|
**Scope the sweep on three axes, not one.** Package breadth above is the first; the other two are how a green sweep is most often blind:
|
|
81
83
|
|
|
82
84
|
- **Language.** An aggregate task runner only runs the tasks packages *declare* to it, so in a polyglot repo the wide run can report every task green while an entire language's suite was never invoked. Read the runner's executed-task list against the languages actually present: a Rust crate with no `test` task simply does not appear in a turbo task count, and "8 of 8 tasks passed" says nothing about it. Run each uncovered language's suite explicitly (`cargo test`, `go test ./...`, `pytest`) and print those results alongside. **A task count is not a coverage claim.**
|
|
@@ -95,7 +97,7 @@ For each in-scope story, in sprint order, run this loop (leave out a decomposed
|
|
|
95
97
|
**A repo with commit hooks carries gates this sweep structurally cannot see.** `lefthook` / `husky` / `.git/hooks/pre-commit` jobs — typos, formatters, staged-file linters, clippy — run against the staged index and are reachable from no script you can invoke here. So the step-4 commit attempt is itself part of verification rather than the end of it: a rejection there is expected traffic, not a failure of this sweep. What that rejection does to the tests-ran marker is step 4's problem, and it is not the obvious answer.
|
|
96
98
|
|
|
97
99
|
3. **Production profile only:** `bmad-testarch-test-review`, then `bmad-code-review`. A `CONCERNS`-grade or non-critical finding appends to `{workflow.deferred_work_path}` and the story proceeds. A **P0 / critical FAIL never defers** — re-loop within the turn budget or escalate.
|
|
98
|
-
4. **Commit at green** (one implementation commit per green story; the gate's evidence commit follows inside the same story boundary, per `references/gate.md`'s advance route, and when the gate's `bmad-testarch-automate` backfills a test, a commit of that backfill comes before it, per gate.md's "When automate backfills"). The PreToolUse hook blocks a commit on a protected branch, blocks a commit when no "tests-ran" marker exists for the current story, and (its marker-freshness clause) blocks a commit when that marker's `baseline=` line does not match the story's recorded baseline, so step 0 must have set the current story and step 2 must have actually run and written `{workflow.implementation_artifacts}/.tests-ran-<story_id>`, in the format step 2 pins, **in a prior, SEPARATE command**. The guard pre-evaluates the command *string* before it runs, so a marker written by a `printf`/`echo` in the SAME compound command as the commit (e.g. `printf … > .tests-ran-<id> && git commit …`) does not yet exist at hook-eval time and the commit is denied. Write the marker, then commit: two distinct tool calls. **A commit can also be rejected by something that is NOT the guard, and the marker rule inverts there.** A repo-side `pre-commit` hook (lefthook, husky, a plain `.git/hooks/pre-commit`) running clippy, rustfmt, typos or a staged-file linter rejects the commit without moving anything: HEAD is where it was, so the tests-ran marker's `baseline=` line still matches character for character and the guard will wave the retry straight through, carrying evidence collected *before* the fix. The freshness clause keys on the BASELINE, not on the code state, so it cannot see this case by construction. Treat a hook rejection exactly as step 5 treats a post-commit red: remediate, re-run the story's tests/lint/build to green, write a **fresh** `.tests-ran-<story_id>` (same `baseline=` line, still copied and never re-derived; `scope=`/`packages=` re-stated for what the re-run actually was), and only then retry the commit. This rule binds the story's own commits: this step's, and any re-commit or amend step 5 makes. The gate's two commits keep their own rules in `references/gate.md`: "When automate backfills" reads a hook rejection of its commit of a test `bmad-testarch-automate` backfilled as its backfill sweep's red, which it fixes only in the backfilled test files and otherwise ends the cycle at a re-loop, and the advance route says how to answer a hook rejection of its evidence commit. **A `commit-msg` hook that rejects the message alone takes a shorter route, on the story's own commits.** Git runs that hook only once every `pre-commit` job has passed, so such a rejection asks for no file change: reword `message.txt` ("Check the record's claims before the commit", below), run the claim check again, and retry the commit from the message file (`-F`) with the marker as it stands, re-running no sweep and writing no fresh marker. A change a `pre-commit` job staged on its way there (a formatter that rewrote and re-staged a file) rides the retry as it would ride an accepted commit, and step 5's re-verify measures it. A path the re-run claim check has you stage or edit is a file change, which takes the rule above. Reword at most twice for one commit: when the hook rejects the second rewording too, the message it wants may hold what the run does not have (a ticket id, say), so commit nothing and escalate for the story as the sub-skill halt catch-all below does, with a `decision_needed` that names the hook and the rule it applies. A rejection whose fix needs a file changed, or whose output does not show that a `commit-msg` hook made it, keeps the rule above. **Append `.decision-log.md` with Write/Edit, never a Bash heredoc.** Stages 4 and 6 require a log of what happened during the run, and what happened *is* commit behaviour, so the log quotes the verbs. The guard evaluates Bash command strings, and a heredoc carrying that prose is a Bash command string: a line leading with the verb is a verb-leading segment, and backticked identifiers or an apostrophe send the whole segment down the fail-closed matches-anywhere path. Its git gates read **Bash command strings alone**, so writing the log with the file tools removes the collision instead of phrasing around it, and keeps Bash for commands you actually mean to run. Said that way rather than "the guard never sees Write/Edit", because preflight arms the hook for EVERY tool: the hook IS invoked for a `Write`, and it does decide on file tools, but only through its Cross-Session Recall rules, which deny a file-tool call that names the recall store or would change the run latch (`references/preflight.md`). A decision-log append is neither, so the conclusion is unchanged, but a reader who believes the guard cannot see a `Write` and then meets the all-tools matcher will try to resolve the contradiction by narrowing the matcher back, and that leaves the recall rules enforcing nothing. **Once the log is too large to Read affordably, do not Read it.** It grows monotonically, one session's prose per invocation, and both file tools refuse a file that has not been Read in this session, so on a long-running Epic (288 KB by its eleventh invocation) the two sanctioned paths are both closed at once. Compose this session's entry with Write into a NEW sibling file beside the log, in the folder that holds `.decision-log.md` and never in `{workflow.implementation_artifacts}`, which is another folder: `<log folder>/dlog-slice-<story_id>-<n>.md`, where `<log folder>` is that folder's full path and `<n>` is one past the highest number a `dlog-slice-<story_id>-*.md` there already carries, so it increments per append: the name has to be unique per append, not per story, or a story's SECOND entry finds the slice already on disk and walks straight back into the Read it was escaping; then append it in one Bash call with both paths in full, `cat "<log folder>/dlog-slice-<story_id>-<n>.md" >> "<log folder>/.decision-log.md"`. That command's leading token is `cat`, it carries no backtick, no `$(`, and no verb-leading segment, so the guard makes no decision on it and the prose never enters a Bash command string at all. Keep the slice beside the log rather than deleting it: it is the only per-session copy if the append is ever interrupted. **Stage only the current story's paths.** In production, Stage 3 generated *every* in-scope story's red-phase tests up front, so a sibling story's still-skipped tests can co-reside in the same shared dirs as this story's (one `test/` package may hold two stories' acceptance specs before either commits). A blanket `git add -A` here sweeps those uncommitted sibling tests into this story's commit and pollutes the per-story boundary: stage this story's source + test paths explicitly (`git add <this story's paths>`) instead. The allowlist ships plain `git add` (a prefix covering both `-A` and a scoped `git add <paths>`) so the targeted add needs no extra approval. **Staging is itself a prior, SEPARATE tool call**: `git add <this story's paths>` as one call, then `git commit` as a second: the same two-distinct-tool-calls rule the marker follows, and for the same reason. The guard also denies a commit whose staged index is empty, and a chained `git add … && git commit` has staged nothing at the moment it pre-evaluates that command string, so the chained form is denied even though the add would have worked. `git commit -a` and commit-time pathspecs (`git commit <paths>`) are unsupported inside the story loop for exactly that reason. (Under `--light` no ATDD tests are generated, so the collision cannot arise.) **Once the commit lands, record the story's END sha.** Write `{workflow.implementation_artifacts}/.commit-<story_id>` with the output of `git rev-parse HEAD`, in exactly the format step 0 pins for the baseline: one newline-terminated line carrying the full 40-hex SHA. Unlike the baseline, **this marker is refreshed, not preserved**: step 5 rewrites it after any remediation re-commit or amend, the gate rewrites it after the commit of a test `bmad-testarch-automate` backfilled (gate.md's "When automate backfills"), and the gate's advance route rewrites it after its evidence commit, so it always names the story's last commit rather than its first. It exists to close the story's commit range explicitly: without it the evidence trail has to *infer* a range end from the NEXT story's baseline marker, and a later story anchored at this story's own SHA collapses that range to `X..X`, so a story that did commit renders as having committed nothing.
|
|
100
|
+
4. **Commit at green** (one implementation commit per green story; the gate's evidence commit follows inside the same story boundary, per `references/gate.md`'s advance route, and when the gate's `bmad-testarch-automate` backfills a test, a commit of that backfill comes before it, per gate.md's "When automate backfills"). The PreToolUse hook blocks a commit on a protected branch, blocks a commit when no "tests-ran" marker exists for the current story, and (its marker-freshness clause) blocks a commit when that marker's `baseline=` line does not match the story's recorded baseline, so step 0 must have set the current story and step 2 must have actually run and written `{workflow.implementation_artifacts}/.tests-ran-<story_id>`, in the format step 2 pins, **in a prior, SEPARATE command**. The guard pre-evaluates the command *string* before it runs, so a marker written by a `printf`/`echo` in the SAME compound command as the commit (e.g. `printf … > .tests-ran-<id> && git commit …`) does not yet exist at hook-eval time and the commit is denied. Write the marker, then commit: two distinct tool calls. **A commit can also be rejected by something that is NOT the guard, and the marker rule inverts there.** A repo-side `pre-commit` hook (lefthook, husky, a plain `.git/hooks/pre-commit`) running clippy, rustfmt, typos or a staged-file linter rejects the commit without moving anything: HEAD is where it was, so the tests-ran marker's `baseline=` line still matches character for character and the guard will wave the retry straight through, carrying evidence collected *before* the fix. The freshness clause keys on the BASELINE, not on the code state, so it cannot see this case by construction. Treat a hook rejection exactly as step 5 treats a post-commit red: remediate, re-run the story's tests/lint/build to green, write a **fresh** `.tests-ran-<story_id>` (same `baseline=` line, still copied and never re-derived; `scope=`/`packages=` re-stated for what the re-run actually was), and only then retry the commit. This rule binds the story's own commits: this step's, and any re-commit or amend step 5 makes. The gate's two commits keep their own rules in `references/gate.md`: "When automate backfills" reads a hook rejection of its commit of a test `bmad-testarch-automate` backfilled as its backfill sweep's red, which it fixes only in the backfilled test files and otherwise ends the cycle at a re-loop, and the advance route says how to answer a hook rejection of its evidence commit. **A `commit-msg` hook that rejects the message alone takes a shorter route, on the story's own commits.** Git runs that hook only once every `pre-commit` job has passed, so such a rejection asks for no file change: reword `message.txt` ("Check the record's claims before the commit", below), run the claim check again, and retry the commit from the message file (`-F`) with the marker as it stands, re-running no sweep and writing no fresh marker. A change a `pre-commit` job staged on its way there (a formatter that rewrote and re-staged a file) rides the retry as it would ride an accepted commit, and step 5's re-verify measures it. A path the re-run claim check has you stage or edit is a file change, which takes the rule above. Reword at most twice for one commit: when the hook rejects the second rewording too, the message it wants may hold what the run does not have (a ticket id, say), so commit nothing and escalate for the story as the sub-skill halt catch-all below does, with a `decision_needed` that names the hook and the rule it applies. A rejection whose fix needs a file changed, or whose output does not show that a `commit-msg` hook made it, keeps the rule above. **Append `.decision-log.md` with Write/Edit, never a Bash heredoc.** Stages 4 and 6 require a log of what happened during the run, and what happened *is* commit behaviour, so the log quotes the verbs. The guard evaluates Bash command strings, and a heredoc carrying that prose is a Bash command string: a line leading with the verb is a verb-leading segment, and backticked identifiers or an apostrophe send the whole segment down the fail-closed matches-anywhere path. Its git gates read **Bash command strings alone**, so writing the log with the file tools removes the collision instead of phrasing around it, and keeps Bash for commands you actually mean to run. Said that way rather than "the guard never sees Write/Edit", because preflight arms the hook for EVERY tool: the hook IS invoked for a `Write`, and it does decide on file tools, but only through its Cross-Session Recall rules, which deny a file-tool call that names the recall store or would change the run latch (`references/preflight.md`). A decision-log append is neither, so the conclusion is unchanged, but a reader who believes the guard cannot see a `Write` and then meets the all-tools matcher will try to resolve the contradiction by narrowing the matcher back, and that leaves the recall rules enforcing nothing. **Once the log is too large to Read affordably, do not Read it.** It grows monotonically, one session's prose per invocation, and both file tools refuse a file that has not been Read in this session, so on a long-running Epic (288 KB by its eleventh invocation) the two sanctioned paths are both closed at once. Compose this session's entry with Write into a NEW sibling file beside the log, in the folder that holds `.decision-log.md` and never in `{workflow.implementation_artifacts}`, which is another folder: `<log folder>/dlog-slice-<story_id>-<n>.md`, where `<log folder>` is that folder's full path and `<n>` is one past the highest number a `dlog-slice-<story_id>-*.md` there already carries, so it increments per append: the name has to be unique per append, not per story, or a story's SECOND entry finds the slice already on disk and walks straight back into the Read it was escaping; then append it in one Bash call with both paths in full, `cat "<log folder>/dlog-slice-<story_id>-<n>.md" >> "<log folder>/.decision-log.md"`. That command's leading token is `cat`, it carries no backtick, no `$(`, and no verb-leading segment, so the guard makes no decision on it and the prose never enters a Bash command string at all. Keep the slice beside the log rather than deleting it: it is the only per-session copy if the append is ever interrupted. **Stage only the current story's paths.** In production, Stage 3 generated *every* in-scope story's red-phase tests up front, so a sibling story's still-skipped tests can co-reside in the same shared dirs as this story's (one `test/` package may hold two stories' acceptance specs before either commits). A blanket `git add -A` here sweeps those uncommitted sibling tests into this story's commit and pollutes the per-story boundary: stage this story's source + test paths explicitly (`git add <this story's paths>`) instead. Those paths take in every path step 2 marked intent-to-add, a marked file since deleted included (staging a deleted file's path drops its entry), and a mark on a path `HEAD` already holds is staged in place like the rest. A marked new file the story will not ship is moved aside into `.scratch-<story_id>/` before that call, so staging its path clears its entry the same way, and moved back after it, untracked again. Such a file is deleted instead only when nothing needs it. The guard refuses any commit while the index holds a mark, naming each one, because the commit would leave that file out while the index keeps it, or, for a mark on a path `HEAD` holds, delete `HEAD`'s file. The allowlist ships plain `git add` (a prefix covering both `-A` and a scoped `git add <paths>`) so the targeted add needs no extra approval. **Staging is itself a prior, SEPARATE tool call**: `git add <this story's paths>` as one call, then `git commit` as a second: the same two-distinct-tool-calls rule the marker follows, and for the same reason. The guard also denies a commit whose staged index is empty, and a chained `git add … && git commit` has staged nothing at the moment it pre-evaluates that command string, so the chained form is denied even though the add would have worked. `git commit -a` and commit-time pathspecs (`git commit <paths>`) are unsupported inside the story loop for exactly that reason. (Under `--light` no ATDD tests are generated, so the collision cannot arise.) **Once the commit lands, record the story's END sha.** Write `{workflow.implementation_artifacts}/.commit-<story_id>` with the output of `git rev-parse HEAD`, in exactly the format step 0 pins for the baseline: one newline-terminated line carrying the full 40-hex SHA. Unlike the baseline, **this marker is refreshed, not preserved**: step 5 rewrites it after any remediation re-commit or amend, the gate rewrites it after the commit of a test `bmad-testarch-automate` backfilled (gate.md's "When automate backfills"), and the gate's advance route rewrites it after its evidence commit, so it always names the story's last commit rather than its first. It exists to close the story's commit range explicitly: without it the evidence trail has to *infer* a range end from the NEXT story's baseline marker, and a later story anchored at this story's own SHA collapses that range to `X..X`, so a story that did commit renders as having committed nothing.
|
|
99
101
|
|
|
100
102
|
**Check the record's claims before the commit.** Gate reviews keep finding one shape of defect in the record: a commit message, a code comment or a story sentence that asserts a property the code does not hold, written by the author who just built it. A catch after the commit costs a re-loop, so check between the staging call and the commit call. Write the commit message with Write to `{workflow.implementation_artifacts}/.scratch-<story_id>/message.txt`, and the story-record notes this cycle added (completion notes, a re-loop's notes, File List entries; for a decomposed child, which has no record, the File List and completion notes from `ucg-dev-story`'s step 10 summary; an empty file when the cycle added none) to `record-notes.md` beside it, Reading either first if an earlier session left it, then run:
|
|
101
103
|
|
|
@@ -103,9 +105,9 @@ For each in-scope story, in sprint order, run this loop (leave out a decomposed
|
|
|
103
105
|
uv run {skill-root}/scripts/claim_check.py --message {workflow.implementation_artifacts}/.scratch-<story_id>/message.txt --message {workflow.implementation_artifacts}/.scratch-<story_id>/record-notes.md --project-root {project-root} --artifacts-root {workflow.implementation_artifacts} --artifacts-root {workflow.implementation_artifacts}/.scratch-<story_id> --artifacts-root {workflow.implementation_artifacts}/evidence-<story_id> --tea-config {workflow.tea_config_path}
|
|
104
106
|
```
|
|
105
107
|
|
|
106
|
-
The second `--message` is there because the record names files the message may only describe. Its `not_in_diff` lists the paths it reads as named in either text that the staged diff does not touch, each a claim about the tree that needs no judgment to refute; paths git ignores (the mutation ledger the record cites, a story file under an ignored artifact tree) are listed apart, in `ignored`, since no commit can carry them. A record names its own artifacts from the folder that holds them (`sweep.sh`, `red-phase/INDEX.md`), so the command names three folders with `--artifacts-root` (the run folder, this story's scratch folder and its evidence folder) and a fourth with `--tea-config`, the TEA test-artifacts root that holds `atdd-checklist-<story_id>.md`, resolved from the TEA config as preflight resolves it (`scripts/preflight_check.py`, `_tea_artifacts_root`), and such a name is read there: one that does not exist from `{project-root}` but exists in one of them lands in `ignored` when each copy that holds it is either ignored by git or outside the work tree, and in `not_in_diff` otherwise; one that exists from `{project-root}`, that a file the tree holds could be, or that is in none of them, is read from `{project-root}` as before. A file this commit claims and never wrote, named bare, under a folder the tree does not hold, or under an empty or ignored-only folder inside an untracked one (git lists only the topmost untracked folder), cannot be told from an artifact of that name, so a copy in one of the folders reads it as the copy: the hunk pass below, which finds the hunk for each edit the message or the notes say this commit makes, is what catches it. For each path in `not_in_diff`: stage it if this commit changed it; if the work tree shows no change there, the edit did not happen, so make it or remove the claim; and reword the message or correct the story record itself (not only its scratch copy) when the text says this commit changed a file it did not. A path under this story's `.scratch-<story_id>/` or `evidence-<story_id>/` is never staged, since both folders stay untracked: the record names it on purpose, as its own evidence, and it may stay listed. A text may name an unchanged file on purpose, if it says so. Run the check again until every path left in `not_in_diff` is one a text names on purpose and says so. Then make one pass over the claims the diff itself adds (its new comment and header lines, the story's new completion notes) and each line of the message, for a superlative or a property: "exactly", "every", "always", "cannot", "not X but Y", "composed", or a claim that something exists or does not exist yet. Each one either cites evidence this cycle already produced (a test, a mutation row, a printed measurement) or is softened to what that evidence shows; start no new run to back a sentence, since the usual fix is to weaken the sentence, not to strengthen the code. In the same pass, read `git diff --cached` once and find the hunk for each edit the message or the notes say this commit makes ("now says", "narrowed", "landed", "fixed"), path or no path: an edit described by its content has a path too, and an edit whose script failed leaves no hunk. And look for a claim this commit makes false without touching it: a forward reference to what it lands in a comment or doc elsewhere in the tree. Search the project's own files with the Grep tool, case-insensitive, for this story's id, "does not exist yet" and "owed by", and for the name of each file the commit adds, leaving out the installed skill, the run folder and this story's own record and tests; correct a hit only when it refers to what this commit lands, in this commit, staged with this story's paths, unless a sibling story's uncommitted edits share its file, in which case log it to `.decision-log.md` for that story instead. Re-stage every file this pass edited, in its own `git add` call, then commit from the message file (`-F`). Run the same check before any re-commit or amend
|
|
108
|
+
The second `--message` is there because the record names files the message may only describe. Its `not_in_diff` lists the paths it reads as named in either text that the staged diff does not touch, each a claim about the tree that needs no judgment to refute; paths git ignores (the mutation ledger the record cites, a story file under an ignored artifact tree) are listed apart, in `ignored`, since no commit can carry them. A record names its own artifacts from the folder that holds them (`sweep.sh`, `red-phase/INDEX.md`), so the command names three folders with `--artifacts-root` (the run folder, this story's scratch folder and its evidence folder) and a fourth with `--tea-config`, the TEA test-artifacts root that holds `atdd-checklist-<story_id>.md`, resolved from the TEA config as preflight resolves it (`scripts/preflight_check.py`, `_tea_artifacts_root`), and such a name is read there: one that does not exist from `{project-root}` but exists in one of them lands in `ignored` when each copy that holds it is either ignored by git or outside the work tree, and in `not_in_diff` otherwise; one that exists from `{project-root}`, that a file the tree holds could be, or that is in none of them, is read from `{project-root}` as before. A file this commit claims and never wrote, named bare, under a folder the tree does not hold, or under an empty or ignored-only folder inside an untracked one (git lists only the topmost untracked folder), cannot be told from an artifact of that name, so a copy in one of the folders reads it as the copy: the hunk pass below, which finds the hunk for each edit the message or the notes say this commit makes, is what catches it. For each path in `not_in_diff`: stage it if this commit changed it; if the work tree shows no change there, the edit did not happen, so make it or remove the claim; and reword the message or correct the story record itself (not only its scratch copy) when the text says this commit changed a file it did not. A path under this story's `.scratch-<story_id>/` or `evidence-<story_id>/` is never staged, since both folders stay untracked: the record names it on purpose, as its own evidence, and it may stay listed. A text may name an unchanged file on purpose, if it says so. Run the check again until every path left in `not_in_diff` is one a text names on purpose and says so. Then make one pass over the claims the diff itself adds (its new comment and header lines, the story's new completion notes) and each line of the message, for a superlative or a property: "exactly", "every", "always", "cannot", "not X but Y", "composed", or a claim that something exists or does not exist yet. Each one either cites evidence this cycle already produced (a test, a mutation row, a printed measurement) or is softened to what that evidence shows; start no new run to back a sentence, since the usual fix is to weaken the sentence, not to strengthen the code. In the same pass, read `git diff --cached` once and find the hunk for each edit the message or the notes say this commit makes ("now says", "narrowed", "landed", "fixed"), path or no path: an edit described by its content has a path too, and an edit whose script failed leaves no hunk. And look for a claim this commit makes false without touching it: a forward reference to what it lands in a comment or doc elsewhere in the tree. Search the project's own files with the Grep tool, case-insensitive, for this story's id, "does not exist yet" and "owed by", and for the name of each file the commit adds, leaving out the installed skill, the run folder and this story's own record and tests; correct a hit only when it refers to what this commit lands, in this commit, staged with this story's paths, unless a sibling story's uncommitted edits share its file, in which case log it to `.decision-log.md` for that story instead. Re-stage every file this pass edited, in its own `git add` call, then commit from the message file (`-F`). Run the same check before any re-commit step 5 makes, and before an amend with `--amend` added, on every run for that amend, a reword's re-run included: it compares the texts with what the amend would commit (the index against `HEAD`'s first parent, or the empty tree at a root commit), so a path the amended commit already carries from `HEAD` stays out of `not_in_diff`, and for that amend the hunk pass reads `git diff --cached <base>`, with the `base` the check printed.
|
|
107
109
|
|
|
108
|
-
5. **Re-verify on the committed HEAD.** Re-run the authoritative suite (tests + lint + build, the same scope step 2 ran this cycle: all three axes including the declared gate set when full; the same resolved package set when this re-loop cycle legitimately ran scoped, per step 2's re-loop rule) on the just-committed, clean tree and **PRINT** the result before advancing. **Run it cache-defeating.** Committing changes a file's git *tracking state* and not one of its bytes, so a content-addressed cache key is unchanged and this re-run replays the pre-commit answer verbatim, observing nothing: eight of eight tasks reported cached, returning in 719ms immediately after a commit, is the whole failure. Pass `--force` (or invoke the package's runner directly), because the one thing this step must actually execute is the tracked-file gates against the newly tracked fileset. Step 2's
|
|
110
|
+
5. **Re-verify on the committed HEAD.** Re-run the authoritative suite (tests + lint + build, the same scope step 2 ran this cycle: all three axes including the declared gate set when full; the same resolved package set when this re-loop cycle legitimately ran scoped, per step 2's re-loop rule) on the just-committed, clean tree and **PRINT** the result before advancing. **Run it cache-defeating.** Committing changes a file's git *tracking state* and not one of its bytes, so a content-addressed cache key is unchanged and this re-run replays the pre-commit answer verbatim, observing nothing: eight of eight tasks reported cached, returning in 719ms immediately after a commit, is the whole failure. Pass `--force` (or invoke the package's runner directly), because the one thing this step must actually execute is the tracked-file gates against the newly tracked fileset. Step 2's marks show a story's **new** files to a **conformance gate scoped to *tracked* files** (a `git ls-files`-based ref/ownership/architecture-boundary check) before the commit, but three kinds of new file still hide from it there, so the gate skips them and reports green at step 2, then reds the instant the commit tracks them: a generated or `.gitignore`d file, which no mark can reach; a file created after step 2's last mark; and, for a gate that reads the staged content (one built on git grep --cached, say), every new file, since a mark holds an empty blob. This committed tree is the exact fileset CI and the Stage-5 gate will see, so a story that is green pre-commit but red here is a **false green** the pre-commit run and any transcript-only evaluator (a `/goal` an operator started, say) both miss. A red step 2 reads as not yet a red (a timeout on a loaded machine, or a red the story's changes do not explain) is read that way here too: a red the story's changes do not explain whose second sweep shows no red leaves this step green, with nothing committed. A red means the story is **not** done: remediate, write a fresh `.tests-ran-<story_id>` marker, and re-commit (amend or a follow-up within the story boundary) until the committed HEAD is green, and only then advance. **That fresh marker carries the same `baseline=<sha>` line as step 2's**: the verbatim, whitespace-stripped content of `{workflow.implementation_artifacts}/.baseline-<story_id>`, **copied, never re-derived from `git rev-parse HEAD`**. The story's baseline has not moved; HEAD has, because step 4 just committed. Re-deriving it here would re-anchor the story to that commit and quietly retire the freshness net for the rest of it, which is the very replayed-marker hole the line exists to close, and without the line the guard denies the re-commit outright, so a story that legitimately needs remediation could never close. The fresh marker also re-states `scope=` (and `packages=` when scoped) to match what THIS re-verify actually ran, because the `scope=` line the gate will read through `--tests-ran` is the one written here, not step 2's. **Rewrite `{workflow.implementation_artifacts}/.commit-<story_id>` from `git rev-parse HEAD` once this step's HEAD is green**, in step 4's format: every time, including when nothing was remediated, because an amend replaces the SHA step 4 recorded and a follow-up commit moves it. This marker is the one step-0 artifact whose rule is *refresh*, not *keep*: the baseline names where the story started and must never move, this one names where it ended and must never be stale. That re-commit carries the SAME staging rule as step 4: stage in a prior, SEPARATE tool call (`git add <this story's paths>`), then run the commit (or `git commit --amend`) as a second, distinct call. `git commit -a` and a chained `git add … && git commit` are unsupported here too: the staged index is still empty when the guard pre-evaluates the command string, so the re-commit is denied.
|
|
109
111
|
|
|
110
112
|
**Sub-skill halt catch-all.** If any orchestrated sub-skill blocks on interactive input mid-run, treat it as escalate for that story: write the typed escalation sidecar `{workflow.implementation_artifacts}/escalation-<story_id>.json` (shape below, under "Escalation sidecar") and stop; do not answer its prompt blind. A sub-skill that is not installed at all (the Skill tool does not know its name) takes the same route: escalate, and never substitute another skill (`bmad-build`, `bmad-build-auto`, or BMAD's deprecated `bmad-create-story` and `bmad-dev-story` for UCG's story skills) or hand-author the work it would have produced.
|
|
111
113
|
|
|
@@ -218,7 +218,7 @@ Do these in order; each must be asserted, not assumed:
|
|
|
218
218
|
- `ULTRACODE_EPIC_BRANCH_PREFIX='{workflow.epic_branch_prefix}'`
|
|
219
219
|
- `ULTRACODE_TEST_ARTIFACTS='<the resolved TEA test-artifacts root>'`: deliberately **not** a `{workflow.…}` scalar (no such workflow key exists, and a `{workflow.test_artifacts}` placeholder would never be filled by config resolution). Inject the same root TEA config resolution yields (`scripts/preflight_check.py`, `_tea_artifacts_root`): the tea-config `test_artifacts` value with `{project-root}` substituted (a relative value resolves under the project root), defaulting to `{project-root}/_bmad-output/test-artifacts` when tea config names none. This is the directory the guard reads the story's `atdd-checklist-<story-id>.md` from; leave it unset and the un-skip proof below is out of scope and silently enforces nothing.
|
|
220
220
|
- The same PreToolUse guard also enforces the Cross-Session Recall latch from `{workflow.implementation_artifacts}/.mem-state.json`: the merged hook reads it automatically, fail-closed, with no new env var to inject. While a latch is present, whatever its version or colour, it denies every claude-mem call; every tool call that names the recall store, except the two pinned recall scripts (`scripts/mem_recall.py` and `scripts/mem_observation.py` under `uv run` or python); and every tool call that would change the latch itself, except those same scripts. Reading the latch stays allowed. **It enforces nothing unless the matcher above covers every tool**, because most of what it denies is a file-tool or MCP call, and a group matched on `Bash` is never invoked for one. This is the invariant that makes the all-tools matcher load-bearing rather than tidy.
|
|
221
|
-
- **Un-skip proof (production only).** With `ULTRACODE_TEST_ARTIFACTS` injected, the guard reads the **staged post-image** of every acceptance-test file the story's `atdd-checklist-<story-id>.md` lists in its `generatedTestFiles` frontmatter (`git show :<path>`) and denies the commit while any of them still contains `test.skip(`. A checklist with no such list, or one that names no JS/TS test file, is scanned whole for test-file paths instead, and a list that cannot be read as a list denies. It proves the marker is absent from the blob being committed, so it fires on a story's *first* commit too, where there is no prior blob to diff against. Caveat worth stating plainly: **`test.skip(` is a JS/Vitest-specific token** (the Playwright/Vitest form TEA's ATDD generates today, which is web/JS-only), so a pytest (`@pytest.mark.skip`) or Go (`t.Skip()`) stack marks skips differently and this check would not see them. Under `--light` there is no atdd-checklist, so the check stays inert.
|
|
221
|
+
- **Un-skip proof (production only).** With `ULTRACODE_TEST_ARTIFACTS` injected, the guard reads the **staged post-image** of every acceptance-test file the story's `atdd-checklist-<story-id>.md` lists in its `generatedTestFiles` frontmatter (`git show :<path>`) and denies the commit while any of them still contains `test.skip(`. A checklist with no such list, or one that names no JS/TS test file, is scanned whole for test-file paths instead, and a list that cannot be read as a list denies. It proves the marker is absent from the blob being committed, so it fires on a story's *first* commit too, where there is no prior blob to diff against. Before it reads them, the guard refuses any commit while the index holds an intent-to-add entry (`git add -N`, which `references/execute.md` step 2 makes for a story's new files), naming each one: `git show :<path>` reads such an entry as an empty blob, with no `test.skip(` in it, and the commit would leave the file out, so the proof never reads one. Caveat worth stating plainly: **`test.skip(` is a JS/Vitest-specific token** (the Playwright/Vitest form TEA's ATDD generates today, which is web/JS-only), so a pytest (`@pytest.mark.skip`) or Go (`t.Skip()`) stack marks skips differently and this check would not see them. Under `--light` there is no atdd-checklist, so the check stays inert.
|
|
222
222
|
- **The commit/push guard anchors on each segment's leading token (`fp-7ac2643`).** The guard splits the command into shell segments and flags one only when `git` is that segment's **leading** token, once leading `VAR=val` assignments, shell keywords and group openers (`if`/`then`/`else`/`fi`, `for`/`while`/`until`/`do`/`done`, `case`/`esac`, `!`, and `(`/`{`, whether spaced or glued to the command name), and known exec wrappers (`env`, `command`, `sudo`, `time`, `nice`, `nohup`, `timeout`, `setsid`, `stdbuf`, `ionice`, `doas`, plus the string payload of a `sh|bash|zsh|dash` invoked with any `-c`-bearing flag cluster, `-lc` and `-cx` included) are stripped, and the subcommand it would then run is exactly `commit` or `push`, or any subcommand that is not one of git's built-in commands (spelled as git spells them), which counts as both, since what an alias runs, or whether an external `git-<name>` command shadows it, cannot be read from the command: so a git alias, even a read-only one (an alias `st` for `status`), and an external command run through git meet the commit and push gates, and the deny says to run the git command an alias stands for, or the external command by its own name. The keyword strip is what keeps a commit inside a compound command (`if true; then git commit …; fi`, `for … do git commit … done`, `( git commit … )`) reachable by the gates: without it a keyword sits in the leading position, the segment classifies as carrying no git write, and the protected-branch, tests-ran, freshness and empty-index gates are all skipped at once. Segment splitting covers `&&`, `||`, `;`, `|`, a newline, **and a lone `&`** (`npm run build & git commit …` is two segments, not one); those separator sets are applied as a **union** rather than merged into one regex, because splitting on `&` or a newline is quote-blind and a lone set would tear `git -c alias.x='a&b' commit` into fragments that each escape detection. So a verb merely *mentioned* inside an `echo`, a log line, or a here-string in a verification command is no longer denied, while a real `FOO=bar git commit`, `sudo git commit` or `timeout 30 git commit` still is: on a `{workflow.protected_branches}` branch both verbs are denied, and on the epic branch, before the story's `.tests-ran-<story_id>` marker exists, a real `git commit` is denied (the marker gate is commit-only: a real `git push` is never marker-gated). Residual, stated rather than hidden: a wrapper **not** on that list (`xargs git commit`, say) leaves a non-`git` leading token and is allowed through, so the tests-ran marker and the remote's branch protection are the nets behind this one. Three shapes still take the older matches-anywhere path and deny on a mention: a segment whose quoting cannot be parsed, one that hides its command inside a `$(…)` substitution or backticks, and, the newest, a **listed** shell wrapper (`sh|bash|zsh|dash`) whose command-string payload cannot be located at all, meaning no `-c`-bearing flag cluster with an operand after it, or nesting deeper than the shell-recursion cap. That third lane exists because locating the payload by the bare token `-c` alone missed every combined form (`bash -lc`, `sh -lc`, `bash -cx`, `zsh -ic`), and a wrapper whose payload went unread classified as carrying no git write and skipped all four commit gates. It is fail-closed in the same direction as the other two, and it has the same cost: `bash <script> "…git commit…"` now denies on the mention, so a verification command's own arguments must not spell a write verb. Two more shapes fail closed. A segment whose command sits behind a run of more than 32 exec wrappers is read through the first 32 only, and counts as both a commit and a push whatever follows them. And a command the guard cannot classify at all, because reading it raised an error, is denied outright, whatever it holds, as is a commit or push whose checks raise one, and so is any other call the guard raises an error while deciding on (an event or a Bash input that is not a JSON object, JSON nested past what Python reads), with the error named, so the guard exits 0 or 2 and nothing else. What it cannot catch itself (an interpreter or `uv` that cannot start, a timeout) Claude Code refuses, under the guard item's `"onFailure": "block"` above; without that key a hook that ends on an error makes no decision, and the command would go through, as one led by about a thousand `env` words once did. **Do not read the anchoring as having eliminated the false-positive class: it narrowed it, and the remainder bites prose about commits in particular.** Markdown prose names identifiers in backticks, and an apostrophe (`don't`) is unbalanced quoting, so a run-log line describing a commit denial routinely hits both fallbacks; a line that *leads* with the verb is a real verb-leading segment and denies on its own, and so does a line that leads with `git` and a word that is not one of git's commands. The rule that avoids all of it: **write prose with Write/Edit, never a Bash heredoc.** The guard's git gates read **Bash command strings alone**, so a decision-log append made with the file tools reaches none of them and no phrasing of the log can trip a gate. Now that the group is armed for every tool, the hook IS invoked for a `Write`, and it does decide on file tools, but only through its Cross-Session Recall rules: it denies a file-tool call that names the recall store or would change the run latch, and a decision-log append is neither, so it passes. Do not narrow the matcher back to `Bash` on the strength of this clause: that would leave those rules enforcing nothing. Reserve Bash for commands you actually mean to run. (execute.md step 4 covers the narrower marker-written-in-the-same-compound-command trap.)
|
|
223
223
|
- **Allowlist.** Pre-populate the tool allowlist with `{workflow.allowlist_commands}` so the unattended run can run tests/lint/build/commit without a permission prompt that no one is there to approve. Write one `Bash(<entry>:*)` allow rule per entry, with the entry exactly as it stands (`Bash(git worktree:*)` for `git worktree`). That rule matches the entry alone, or the entry, a space and anything after it, which is how `git worktree` covers the gate's `git worktree add <tmp-path> <commit>`. A rule without `:*` matches one exact command, so the stage's own calls would stop for approval. The entries land in the same `settings.local.json`, so a refused write here follows the same rule.
|
|
224
224
|
- **Prove this session runs the hooks.** `--assert-armed` proves what `.claude/settings.local.json` holds, not what this session runs: Claude Code's docs say its file watcher normally picks up a settings edit made while a session runs, and that it can miss one, which a restart of the session reloads. So, after the last write above, make one Bash call, exactly `git commit --dry-run`, alone, with no other command, redirection or assignment beside it. `--dry-run` makes git create no commit and run no commit hook, whatever is staged, so the call changes nothing when no guard runs. The purge above removed `.current-story`, so a guard this session runs finds no story on this Epic branch and refuses the call with a reason that holds both `Tests-ran guard: refusing` and `current story (unknown)`. The reason follows a `PreToolUse:Bash hook error:` prefix in the result, so match both anywhere in it. That refusal is the proof: log it to `.decision-log.md` as the expected refusal, and act on nothing it says (write no marker and set no story). It is not a refused call under step 2's "A refused settings write". It stands for the Stop hook too by inference: the Hooks bullet above writes that hook in the same merge as the guard. One residual stands: a guard an earlier arming left loaded when this session started, reading the same implementation-artifacts folder, refuses the call the same way, so the probe proves that a guard runs, not that it runs with the matcher and env this arming wrote. Read any other result this way:
|
|
@@ -3,7 +3,8 @@
|
|
|
3
3
|
# requires-python = ">=3.11"
|
|
4
4
|
# dependencies = []
|
|
5
5
|
# ///
|
|
6
|
-
"""List the paths a commit message names that the staged diff
|
|
6
|
+
"""List the paths a commit message names that the staged diff (with `--amend`,
|
|
7
|
+
the amended commit) does not touch.
|
|
7
8
|
|
|
8
9
|
A commit message that says a path changed, when the commit leaves that path
|
|
9
10
|
alone, is a claim about the tree that needs no judgment to refute. The field
|
|
@@ -62,6 +63,16 @@ text names one from the project root, so when the project root is a folder
|
|
|
62
63
|
below the top level (a BMAD install in a monorepo's `app/`), `src/a.py` and
|
|
63
64
|
`app/src/a.py` both name a staged `app/src/a.py`.
|
|
64
65
|
|
|
66
|
+
Before an amend, `--amend` compares the texts with what the amend would commit
|
|
67
|
+
instead: the same command is given HEAD's first parent (`HEAD~1`), or the empty
|
|
68
|
+
tree when HEAD has none (a root commit, a shallow clone's oldest commit), so a
|
|
69
|
+
path the amended commit already carries from HEAD matches as a staged one does.
|
|
70
|
+
That is the list `git commit --amend` shows: an intent-to-add entry stays out of
|
|
71
|
+
it, a merge is compared with its first parent, and a path HEAD changed that the
|
|
72
|
+
index has restored to its content in HEAD's parent drops out. Without `--amend`
|
|
73
|
+
a path only HEAD changed is in `not_in_diff`, which is right before a commit
|
|
74
|
+
that adds to HEAD, and wrong before an amend.
|
|
75
|
+
|
|
65
76
|
Matching. A named path that exists in the work tree or the index must match a
|
|
66
77
|
staged path exactly, or be a directory holding one: `README.md` does not match
|
|
67
78
|
a staged `docs/README.md` when a root `README.md` exists, and below the top
|
|
@@ -93,17 +104,22 @@ string, an issue reference or a token holding a glob or a `$` is not a path.
|
|
|
93
104
|
|
|
94
105
|
Usage:
|
|
95
106
|
uv run claim_check.py --message <file, or - for stdin> [--message <file> ...] [--project-root <dir>]
|
|
96
|
-
[--artifacts-root <dir> ...] [--tea-config <file>]
|
|
107
|
+
[--artifacts-root <dir> ...] [--tea-config <file>] [--amend]
|
|
97
108
|
|
|
98
109
|
Output: JSON on stdout, `{"named": [...], "staged": [...], "not_in_diff":
|
|
99
110
|
[...], "ignored": [...], "clean": bool}`, where `clean` means `not_in_diff`
|
|
100
|
-
is empty and `staged` lists paths from the top level, as git does.
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
111
|
+
is empty and `staged` lists paths from the top level, as git does. With
|
|
112
|
+
`--amend`, `staged` lists the paths the amended commit carries, and one more
|
|
113
|
+
key, `base`, gives the commit or tree they were compared with (the full id of
|
|
114
|
+
HEAD's first parent, or the empty tree's); without it the output is the one
|
|
115
|
+
before the flag. Stdin and the JSON are UTF-8 whatever the console's code page,
|
|
116
|
+
and a staged name that is not UTF-8 is written as its `\\udcXX` escape, which
|
|
117
|
+
a JSON reader reads back as the name git holds. Several `--message` files are
|
|
118
|
+
read as one text, in order. Exit 0 whenever it ran (a non-empty `not_in_diff`
|
|
119
|
+
is a result, not an error); exit 2 when a message file cannot be read, when
|
|
120
|
+
`-` (stdin) is given more than once, when the project root is not a git work
|
|
121
|
+
tree, or when `--amend` is given and HEAD names no commit ("nothing to
|
|
122
|
+
amend").
|
|
107
123
|
"""
|
|
108
124
|
|
|
109
125
|
from __future__ import annotations
|
|
@@ -286,11 +302,71 @@ def project_prefix(project_root: Path) -> str:
|
|
|
286
302
|
return proc.stdout.decode("utf-8", errors="surrogateescape").rstrip("\r\n")
|
|
287
303
|
|
|
288
304
|
|
|
289
|
-
|
|
305
|
+
class NothingToAmend(Exception):
|
|
306
|
+
"""`--amend` was given and HEAD names no commit (an unborn branch)."""
|
|
307
|
+
|
|
308
|
+
|
|
309
|
+
def _rev_parse(project_root: Path, rev: str) -> tuple[int, str]:
|
|
310
|
+
try:
|
|
311
|
+
proc = subprocess.run(
|
|
312
|
+
["git", "rev-parse", "--verify", "-q", rev], cwd=project_root, capture_output=True, timeout=60
|
|
313
|
+
)
|
|
314
|
+
except (OSError, subprocess.TimeoutExpired):
|
|
315
|
+
return 128, ""
|
|
316
|
+
return proc.returncode, proc.stdout.decode("ascii", errors="replace").strip()
|
|
317
|
+
|
|
318
|
+
|
|
319
|
+
def amend_base(project_root: Path) -> str | None:
|
|
320
|
+
"""What an amend of HEAD compares the index with: HEAD's first parent, or
|
|
321
|
+
the empty tree when HEAD has none. None when git cannot say.
|
|
322
|
+
|
|
323
|
+
`rev-parse --verify -q` exits 1 for a name that resolves to nothing and 128
|
|
324
|
+
outside a repository. `HEAD~1`, not `HEAD^`, so a hand-run copy needs no
|
|
325
|
+
quoting in cmd.exe. A root commit, or a shallow clone's oldest commit, has
|
|
326
|
+
no parent git can read, and an amend of it commits the whole index: the
|
|
327
|
+
empty tree stands in, asked of git (`hash-object -t tree` on empty input,
|
|
328
|
+
which writes nothing) so a SHA-256 repository gets its own id. When HEAD
|
|
329
|
+
names no readable commit (an unborn branch, or a HEAD whose commit object
|
|
330
|
+
is missing, where `HEAD~1` also exits 1), there is nothing to amend: the
|
|
331
|
+
second probe is `HEAD^{commit}`, which reads the object, since plain
|
|
332
|
+
`HEAD` resolves from the ref alone.
|
|
333
|
+
"""
|
|
334
|
+
code, sha = _rev_parse(project_root, "HEAD~1")
|
|
335
|
+
if code == 0 and sha:
|
|
336
|
+
return sha
|
|
337
|
+
if code != 1:
|
|
338
|
+
# Not "no such commit" but a probe that failed (a timeout, a git that
|
|
339
|
+
# cannot read the repository): the empty tree would read every index
|
|
340
|
+
# path as carried, and the check as clean.
|
|
341
|
+
return None
|
|
342
|
+
code, _ = _rev_parse(project_root, "HEAD^{commit}")
|
|
343
|
+
if code == 1:
|
|
344
|
+
raise NothingToAmend
|
|
345
|
+
if code != 0:
|
|
346
|
+
return None
|
|
347
|
+
try:
|
|
348
|
+
proc = subprocess.run(
|
|
349
|
+
["git", "hash-object", "-t", "tree", "--stdin"],
|
|
350
|
+
cwd=project_root,
|
|
351
|
+
input=b"",
|
|
352
|
+
capture_output=True,
|
|
353
|
+
timeout=60,
|
|
354
|
+
)
|
|
355
|
+
except (OSError, subprocess.TimeoutExpired):
|
|
356
|
+
return None
|
|
357
|
+
tree = proc.stdout.decode("ascii", errors="replace").strip()
|
|
358
|
+
return tree if proc.returncode == 0 and tree else None
|
|
359
|
+
|
|
360
|
+
|
|
361
|
+
def staged_paths(project_root: Path, base: str | None = None) -> list[str] | None:
|
|
362
|
+
"""The paths the index changes against HEAD, or against `base` when one
|
|
363
|
+
is given. Porcelain `git diff --cached` on purpose: it leaves an
|
|
364
|
+
intent-to-add entry out, as a commit or an amend does."""
|
|
290
365
|
try:
|
|
291
366
|
proc = subprocess.run(
|
|
292
367
|
# From the top level even where diff.relative would name them from the cwd.
|
|
293
|
-
["git", "-c", "diff.relative=false", "diff", "--cached", "--name-only", "--no-renames", "-z"]
|
|
368
|
+
["git", "-c", "diff.relative=false", "diff", "--cached", "--name-only", "--no-renames", "-z"]
|
|
369
|
+
+ ([base, "--"] if base else []),
|
|
294
370
|
cwd=project_root,
|
|
295
371
|
capture_output=True,
|
|
296
372
|
timeout=60,
|
|
@@ -593,8 +669,19 @@ def ignored_paths(
|
|
|
593
669
|
return found
|
|
594
670
|
|
|
595
671
|
|
|
596
|
-
def check(
|
|
597
|
-
|
|
672
|
+
def check(
|
|
673
|
+
message: str, project_root: Path, artifacts_roots: list[Path] | tuple = (), amend: bool = False
|
|
674
|
+
) -> dict | None:
|
|
675
|
+
"""The comparison; None when git cannot read the work tree. With `amend`,
|
|
676
|
+
the paths an amend of HEAD would commit stand in for the staged ones, and
|
|
677
|
+
the result carries the `base` they were compared with. Raises
|
|
678
|
+
NothingToAmend when `amend` is asked and HEAD names no commit."""
|
|
679
|
+
base = None
|
|
680
|
+
if amend:
|
|
681
|
+
base = amend_base(project_root)
|
|
682
|
+
if base is None:
|
|
683
|
+
return None
|
|
684
|
+
staged = staged_paths(project_root, base)
|
|
598
685
|
if staged is None:
|
|
599
686
|
return None
|
|
600
687
|
prefix = project_prefix(project_root)
|
|
@@ -602,13 +689,16 @@ def check(message: str, project_root: Path, artifacts_roots: list[Path] | tuple
|
|
|
602
689
|
unmatched = [path for path in named if not _matches(path, staged, project_root, prefix)]
|
|
603
690
|
ignored = ignored_paths(unmatched, project_root, artifacts_roots, staged)
|
|
604
691
|
missing = [path for path in unmatched if path not in ignored]
|
|
605
|
-
|
|
692
|
+
result = {
|
|
606
693
|
"named": named,
|
|
607
694
|
"staged": staged,
|
|
608
695
|
"not_in_diff": missing,
|
|
609
696
|
"ignored": [path for path in unmatched if path in ignored],
|
|
610
697
|
"clean": not missing,
|
|
611
698
|
}
|
|
699
|
+
if amend:
|
|
700
|
+
result["base"] = base
|
|
701
|
+
return result
|
|
612
702
|
|
|
613
703
|
|
|
614
704
|
def _tea_root(tea_config: str, project_root: Path) -> Path | None:
|
|
@@ -640,7 +730,8 @@ def _tea_root(tea_config: str, project_root: Path) -> Path | None:
|
|
|
640
730
|
|
|
641
731
|
def main(argv: list[str] | None = None) -> int:
|
|
642
732
|
parser = argparse.ArgumentParser(
|
|
643
|
-
description="List the paths a commit message names that the staged diff
|
|
733
|
+
description="List the paths a commit message names that the staged diff (with --amend, the amended "
|
|
734
|
+
"commit) does not touch."
|
|
644
735
|
)
|
|
645
736
|
parser.add_argument(
|
|
646
737
|
"--message",
|
|
@@ -664,6 +755,12 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
664
755
|
help="the TEA config ({project-root} is substituted): its test-artifacts root, resolved as preflight "
|
|
665
756
|
"resolves it, is read as one more --artifacts-root, the folder that holds atdd-checklist-<story_id>.md",
|
|
666
757
|
)
|
|
758
|
+
parser.add_argument(
|
|
759
|
+
"--amend",
|
|
760
|
+
action="store_true",
|
|
761
|
+
help="compare with what an amend of HEAD would commit (the index against HEAD's first parent, or the empty "
|
|
762
|
+
"tree for a root commit) instead of the staged diff; run it before an amend",
|
|
763
|
+
)
|
|
667
764
|
args = parser.parse_args(argv)
|
|
668
765
|
if args.message.count("-") > 1:
|
|
669
766
|
parser.error("stdin (-) can be read only once")
|
|
@@ -687,7 +784,11 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
687
784
|
tea_root = _tea_root(args.tea_config, Path(args.project_root))
|
|
688
785
|
if tea_root is not None:
|
|
689
786
|
roots.append(tea_root)
|
|
690
|
-
|
|
787
|
+
try:
|
|
788
|
+
result = check(message, Path(args.project_root), roots, amend=args.amend)
|
|
789
|
+
except NothingToAmend:
|
|
790
|
+
print(json.dumps({"error": "nothing to amend: HEAD names no commit in %s" % args.project_root}), file=sys.stderr)
|
|
791
|
+
return 2
|
|
691
792
|
if result is None:
|
|
692
793
|
print(json.dumps({"error": "not a git work tree: %s" % args.project_root}), file=sys.stderr)
|
|
693
794
|
return 2
|
|
@@ -105,12 +105,17 @@ entry carries a BLANK index column and `A` in the worktree column, so the
|
|
|
105
105
|
obvious `^A ` match - which reads the index column - misses every one of them,
|
|
106
106
|
and `git checkout -- <path>` then truncates one to zero bytes and exits 0.
|
|
107
107
|
|
|
108
|
-
The status read is `--porcelain -z`, and that is not cosmetic.
|
|
109
|
-
C-QUOTES any path holding a space or a non-ASCII byte, so a
|
|
110
|
-
`a -> b.txt` arrives quoted and splits on its own arrow, and
|
|
111
|
-
as octal escapes. Both then name a file that does not exist,
|
|
112
|
-
warning that tells an operator which files to back up before
|
|
113
|
-
`-z` nothing is quoted and the bytes are the path.
|
|
108
|
+
The status read is `--porcelain -z --no-renames`, and that is not cosmetic.
|
|
109
|
+
Without `-z` git C-QUOTES any path holding a space or a non-ASCII byte, so a
|
|
110
|
+
file named `a -> b.txt` arrives quoted and splits on its own arrow, and
|
|
111
|
+
`café.rs` arrives as octal escapes. Both then name a file that does not exist,
|
|
112
|
+
inside the very warning that tells an operator which files to back up before
|
|
113
|
+
reverting. Under `-z` nothing is quoted and the bytes are the path. Without
|
|
114
|
+
`--no-renames` git pairs a tracked file a story moved (`mv old new`, then
|
|
115
|
+
`git add -N new`, as Execute marks a new file before its sweep) into one
|
|
116
|
+
` R new` entry, whose worktree column is `R`, not `A`, so the moved file's
|
|
117
|
+
mark went unnamed. Execute marks every new file now, so the triage must name
|
|
118
|
+
each one.
|
|
114
119
|
|
|
115
120
|
An UNREADABLE pre-spawn HEAD (an unborn HEAD: `git init` with no commit yet) is
|
|
116
121
|
its own reading, never "nothing landed". Folding it into "unmoved" let a session
|
|
@@ -638,7 +643,18 @@ def intent_to_add_paths(entries: list[tuple[str, str, str]]) -> list[str]:
|
|
|
638
643
|
and ``A`` in the worktree column, so the obvious ``^A `` match - which reads
|
|
639
644
|
the index column - misses every one of them. A `git checkout -- <path>`
|
|
640
645
|
against one then rewrites it to ZERO BYTES and exits 0, silently, because
|
|
641
|
-
the index entry it restores from is empty
|
|
646
|
+
the index entry it restores from is empty; `git restore <path>` does the
|
|
647
|
+
same, and `git reset --hard` deletes a new file outright and reverts one
|
|
648
|
+
HEAD holds to HEAD's copy, discarding the story's edits.
|
|
649
|
+
|
|
650
|
+
A mark over a path HEAD holds (`git rm --cached p`, then `git add -N p`)
|
|
651
|
+
reads ``DA``: the index column says the tracked file is gone, and the
|
|
652
|
+
worktree column is the same ``A``. So the worktree column must be ``A``
|
|
653
|
+
and the index column blank or ``D``.
|
|
654
|
+
|
|
655
|
+
It reads the worktree column's ``A`` only, so the status it is given must
|
|
656
|
+
come from `--no-renames`: with rename detection on, a mark on a moved
|
|
657
|
+
file reads ` R` and is missed.
|
|
642
658
|
|
|
643
659
|
Read off the parsed columns rather than sniffed out of the raw line, because
|
|
644
660
|
every string-sniffing shortcut here has a filename that defeats it.
|
|
@@ -647,7 +663,7 @@ def intent_to_add_paths(entries: list[tuple[str, str, str]]) -> list[str]:
|
|
|
647
663
|
destructive-data hazard that fires exactly when someone is cleaning up after
|
|
648
664
|
a crash, which is when they are least likely to be reading carefully.
|
|
649
665
|
"""
|
|
650
|
-
return [path for x, y, path in entries if x
|
|
666
|
+
return [path for x, y, path in entries if x in (" ", "D") and y == "A"]
|
|
651
667
|
|
|
652
668
|
|
|
653
669
|
def _relative_to_repo(repo: Path, path: Path) -> str | None:
|
|
@@ -690,7 +706,12 @@ def post_stop_triage(repo: Path, head_before: str | None, run_artifacts: Path |
|
|
|
690
706
|
# `?? _bmad-output/` entry, which no per-file prefix test can match - so the
|
|
691
707
|
# run-artifacts exclusion below silently missed the commonest case, and the
|
|
692
708
|
# report named a directory where an operator needs the files.
|
|
693
|
-
|
|
709
|
+
# `--no-renames` because a mark on a moved file otherwise pairs with the
|
|
710
|
+
# old path into a ` R` entry, whose worktree column is not `A`, and goes
|
|
711
|
+
# unnamed (see the module docstring).
|
|
712
|
+
porcelain = _git_out(
|
|
713
|
+
repo, "status", "--porcelain", "-z", "--no-renames", "--untracked-files=all"
|
|
714
|
+
)
|
|
694
715
|
head_after = head_sha(repo)
|
|
695
716
|
triage = {
|
|
696
717
|
"git_available": porcelain is not None and head_after is not None,
|
|
@@ -782,7 +803,9 @@ def render_triage(triage: dict) -> list[str]:
|
|
|
782
803
|
if triage["intent_to_add"]:
|
|
783
804
|
lines.append(
|
|
784
805
|
f" DANGER: {len(triage['intent_to_add'])} intent-to-add path(s) below. "
|
|
785
|
-
"`git checkout -- <path>` TRUNCATES these to zero bytes and exits 0
|
|
806
|
+
"`git checkout -- <path>` TRUNCATES these to zero bytes and exits 0, "
|
|
807
|
+
"`git restore <path>` empties them the same way, and `git reset --hard` "
|
|
808
|
+
"DELETES a new one and reverts a tracked one to HEAD, discarding its edits. "
|
|
786
809
|
"Back them up and verify the copies before reverting anything."
|
|
787
810
|
)
|
|
788
811
|
for path in triage["intent_to_add"]:
|
|
@@ -26,7 +26,13 @@ Enforces invariants that must NOT live in memory (context, not enforcement):
|
|
|
26
26
|
after HEAD moves. Fail closed: a marker with no `baseline=` line, or an
|
|
27
27
|
unreadable baseline file, denies.
|
|
28
28
|
4. No `git commit` while the staged index is empty (a commit that captures no
|
|
29
|
-
work), or while the staged-index probe cannot answer (fail closed).
|
|
29
|
+
work), or while the staged-index probe cannot answer (fail closed). An
|
|
30
|
+
intent-to-add entry (`git add -N`, which Execute's step 2 makes for a
|
|
31
|
+
story's new files) is no staged work here. Then, no `git commit` while
|
|
32
|
+
the index holds any intent-to-add entry, or while that probe cannot
|
|
33
|
+
answer (fail closed): a commit leaves such an entry out while the index
|
|
34
|
+
keeps it (over a path HEAD holds, it deletes HEAD's file), and
|
|
35
|
+
`git show :<path>` reads it as an empty blob. The deny names each entry.
|
|
30
36
|
5. Un-skip proof: in production (an atdd-checklist for the current story is on
|
|
31
37
|
disk), no `git commit` while the STAGED CONTENT of any acceptance-test file
|
|
32
38
|
that checklist enumerates still contains `test.skip(`. The files are the
|
|
@@ -34,7 +40,8 @@ Enforces invariants that must NOT live in memory (context, not enforcement):
|
|
|
34
40
|
such list, or one naming no JS/TS test file, is scanned whole for
|
|
35
41
|
test-file paths. A list that cannot be read as a list denies. This reads
|
|
36
42
|
the blob being committed, not a diff, so it also catches a story's first
|
|
37
|
-
commit, where there is no prior blob to compare against.
|
|
43
|
+
commit, where there is no prior blob to compare against. It runs after
|
|
44
|
+
invariant 4, so it never reads an intent-to-add entry's empty blob.
|
|
38
45
|
6. Cross-Session Recall, claude-mem: while a run latch (.mem-state.json) is
|
|
39
46
|
present, every claude-mem MCP call (the plugin form and both bare-server
|
|
40
47
|
forms, an MCP resource read or listing on a claude-mem server, and a
|
|
@@ -285,6 +292,52 @@ def _staged_index_nonempty(cwd: str | None) -> bool:
|
|
|
285
292
|
return False # any other exit code is a probe failure -> fail closed
|
|
286
293
|
|
|
287
294
|
|
|
295
|
+
def _intent_to_add_entries(cwd: str | None) -> list[str] | None:
|
|
296
|
+
"""The index's intent-to-add entries (`git add -N`), named from the top
|
|
297
|
+
level, or None when git cannot say (the caller fails closed on None).
|
|
298
|
+
|
|
299
|
+
Porcelain `git diff --cached` reads such an entry as absent from the
|
|
300
|
+
index, which is why the empty-index probe above never counts one as
|
|
301
|
+
staged work, and the same command with `--ita-visible-in-index` reads it
|
|
302
|
+
as an empty file. An entry that is no mark reads the same in both, so
|
|
303
|
+
the marks are the paths of the (status, path) pairs only one of them
|
|
304
|
+
lists. Pairs, not names, and both directions: a mark over a path HEAD
|
|
305
|
+
holds (`git rm --cached p`, then `git add -N p`, status `DA`) is listed
|
|
306
|
+
as `M` with marks visible and `D` without, so a name-only subtraction
|
|
307
|
+
dropped it; over a file HEAD holds empty (an `__init__.py`), the visible
|
|
308
|
+
form lists nothing at all (the mark's empty blob is HEAD's) and only the
|
|
309
|
+
other lists `D`. Either way the commit deletes HEAD's file.
|
|
310
|
+
Both compare the index with HEAD (with the empty tree on an unborn HEAD),
|
|
311
|
+
so a marked file since deleted or moved out of the work tree is still
|
|
312
|
+
listed, where `git status` would show it as ` D` or pair it into a
|
|
313
|
+
rename. `diff.relative=false` keeps both lists whole and named from the
|
|
314
|
+
top level whatever folder the hook runs in. Its own probe on purpose:
|
|
315
|
+
this hook imports nothing from its siblings.
|
|
316
|
+
"""
|
|
317
|
+
listed: list[set[tuple[bytes, bytes]]] = []
|
|
318
|
+
for visible in (["--ita-visible-in-index"], []):
|
|
319
|
+
try:
|
|
320
|
+
out = subprocess.run(
|
|
321
|
+
["git", "-c", "diff.relative=false", "diff", "--cached", *visible,
|
|
322
|
+
"--name-status", "--no-renames", "-z"],
|
|
323
|
+
cwd=cwd or None,
|
|
324
|
+
capture_output=True,
|
|
325
|
+
timeout=10,
|
|
326
|
+
)
|
|
327
|
+
except (OSError, subprocess.SubprocessError):
|
|
328
|
+
return None # git missing, timeout, ...: cannot answer -> fail closed
|
|
329
|
+
if out.returncode != 0:
|
|
330
|
+
return None # any non-zero exit is a probe failure -> fail closed
|
|
331
|
+
# `-z` with `--no-renames`: a status field, then its path, each
|
|
332
|
+
# NUL-terminated, so the fields pair up in order.
|
|
333
|
+
fields = out.stdout.split(b"\0")[:-1]
|
|
334
|
+
if len(fields) % 2:
|
|
335
|
+
return None # a status with no path: unreadable output -> fail closed
|
|
336
|
+
listed.append(set(zip(fields[0::2], fields[1::2])))
|
|
337
|
+
visible_pairs, plain_pairs = listed
|
|
338
|
+
return sorted({os.fsdecode(path) for _, path in visible_pairs ^ plain_pairs})
|
|
339
|
+
|
|
340
|
+
|
|
288
341
|
def _impl_artifacts(cwd: str | None) -> Path | None:
|
|
289
342
|
env = os.environ.get("ULTRACODE_IMPL_ARTIFACTS")
|
|
290
343
|
if env:
|
|
@@ -1531,9 +1584,12 @@ def _repo_relative(raw: str, cwd: str | None) -> str:
|
|
|
1531
1584
|
def _staged_blob(path: str, cwd: str | None) -> tuple[bool, str]:
|
|
1532
1585
|
"""Return (readable, staged content) for one path via `git show :<path>`.
|
|
1533
1586
|
|
|
1534
|
-
`:<path>` addresses the index, i.e.
|
|
1535
|
-
|
|
1536
|
-
|
|
1587
|
+
`:<path>` addresses the index, i.e. the bytes this commit would write for
|
|
1588
|
+
a staged path. An intent-to-add entry is the exception: it reads as the
|
|
1589
|
+
empty blob with exit 0, and the commit leaves it out, so _git_write_gates
|
|
1590
|
+
refuses any commit while the index holds one before this read runs.
|
|
1591
|
+
readable is False when the probe could not answer at all (git missing,
|
|
1592
|
+
timeout, path not in the index): the caller fails closed on it.
|
|
1537
1593
|
"""
|
|
1538
1594
|
try:
|
|
1539
1595
|
out = subprocess.run(
|
|
@@ -3891,8 +3947,8 @@ def _decide() -> None:
|
|
|
3891
3947
|
f"tool_input is a JSON {_json_kind(tool_input)}, not an object, so "
|
|
3892
3948
|
"the command cannot be read for a `git commit` or `git push`, and "
|
|
3893
3949
|
"it is refused (failing closed) rather than let past the "
|
|
3894
|
-
"protected-branch, tests-ran, freshness, empty-index
|
|
3895
|
-
"checks."
|
|
3950
|
+
"protected-branch, tests-ran, freshness, empty-index, intent-to-add "
|
|
3951
|
+
"and un-skip checks."
|
|
3896
3952
|
)
|
|
3897
3953
|
command = tool_input.get("command") or ""
|
|
3898
3954
|
if not isinstance(command, str):
|
|
@@ -3910,8 +3966,8 @@ def _decide() -> None:
|
|
|
3910
3966
|
f"for a `git commit` or `git push` failed ({type(exc).__name__}): "
|
|
3911
3967
|
"whether it runs one cannot be told, so it is refused (failing "
|
|
3912
3968
|
"closed) rather than let past the protected-branch, tests-ran, "
|
|
3913
|
-
"freshness, empty-index and un-skip checks. Run it as
|
|
3914
|
-
"plainer commands."
|
|
3969
|
+
"freshness, empty-index, intent-to-add and un-skip checks. Run it as "
|
|
3970
|
+
"shorter, plainer commands."
|
|
3915
3971
|
)
|
|
3916
3972
|
if not verbs:
|
|
3917
3973
|
_allow()
|
|
@@ -3926,18 +3982,19 @@ def _decide() -> None:
|
|
|
3926
3982
|
_deny(
|
|
3927
3983
|
f"Commit/push guard: refusing this `git {'/'.join(sorted(verbs))}`, "
|
|
3928
3984
|
f"because checking it raised an error ({type(exc).__name__}: {detail}), "
|
|
3929
|
-
"so the protected-branch, tests-ran, freshness, empty-index
|
|
3930
|
-
"un-skip checks could not all run, and it is
|
|
3931
|
-
"closed) rather than let through unchecked. Fix
|
|
3932
|
-
"names, then run it again."
|
|
3985
|
+
"so the protected-branch, tests-ran, freshness, empty-index, "
|
|
3986
|
+
"intent-to-add and un-skip checks could not all run, and it is "
|
|
3987
|
+
"refused (failing closed) rather than let through unchecked. Fix "
|
|
3988
|
+
"what the error names, then run it again."
|
|
3933
3989
|
)
|
|
3934
3990
|
|
|
3935
3991
|
|
|
3936
3992
|
def _git_write_gates(cwd: str | None, verbs: set[str], unknown: list[str]) -> NoReturn:
|
|
3937
3993
|
"""The checks a Bash command that commits or pushes must pass: the
|
|
3938
3994
|
protected branch for either verb, then, for a commit, the tests-ran
|
|
3939
|
-
marker, its freshness, a staged index
|
|
3940
|
-
denies; a command that passes them
|
|
3995
|
+
marker, its freshness, a staged index, an index with no intent-to-add
|
|
3996
|
+
entry and the un-skip proof. Each one denies; a command that passes them
|
|
3997
|
+
all is allowed."""
|
|
3941
3998
|
hint = _unknown_hint(unknown)
|
|
3942
3999
|
|
|
3943
4000
|
protected = _protected_branches()
|
|
@@ -3981,6 +4038,34 @@ def _git_write_gates(cwd: str | None, verbs: set[str], unknown: list[str]) -> No
|
|
|
3981
4038
|
"does not exist yet at that point.",
|
|
3982
4039
|
hint,
|
|
3983
4040
|
)
|
|
4041
|
+
marked = _intent_to_add_entries(cwd)
|
|
4042
|
+
if marked is None:
|
|
4043
|
+
_deny(
|
|
4044
|
+
"Intent-to-add guard: refusing `git commit`, because the index "
|
|
4045
|
+
"could not be read for intent-to-add entries (`git add -N`), so "
|
|
4046
|
+
"whether this commit would leave one out cannot be told. Failing "
|
|
4047
|
+
"closed. Check that git can read this repository's index, then "
|
|
4048
|
+
"commit.",
|
|
4049
|
+
hint,
|
|
4050
|
+
)
|
|
4051
|
+
if marked:
|
|
4052
|
+
_deny(
|
|
4053
|
+
"Intent-to-add guard: refusing `git commit`, because the index "
|
|
4054
|
+
"holds intent-to-add entries (`git add -N`) for "
|
|
4055
|
+
f"{', '.join(f'`{path}`' for path in marked)}. A commit leaves "
|
|
4056
|
+
"such an entry out while the index keeps it (over a path HEAD "
|
|
4057
|
+
"holds, it deletes HEAD's file), and its staged content reads as "
|
|
4058
|
+
"an empty file. Stage each one the story ships "
|
|
4059
|
+
"(`git add -- <path>`) in a prior, SEPARATE tool call. A mark on "
|
|
4060
|
+
"a path HEAD already holds is cleared the same way, staging the "
|
|
4061
|
+
"file in place, since moving it aside would stage its deletion. "
|
|
4062
|
+
"For a new file the story will not ship, move it aside into the "
|
|
4063
|
+
"story's `.scratch-<story_id>/` folder, run `git add -- <path>`, "
|
|
4064
|
+
"which clears its entry, then move it back, where it is untracked "
|
|
4065
|
+
"again (delete it only when nothing needs it). Then commit as a "
|
|
4066
|
+
"second, distinct tool call.",
|
|
4067
|
+
hint,
|
|
4068
|
+
)
|
|
3984
4069
|
_unskip_gate(cwd, story)
|
|
3985
4070
|
|
|
3986
4071
|
_allow()
|