1 added, 1 removed. Audit A to A.
---
name: commit
description: "Commit the current session's changes only, gateway-inline. Session-isolated (never -A, staged set verified against the session list), doc-sync-gated. The gateway runs the commit inline — it already holds the diff, session file list, and change intent; the doc-sync scan dispatches on a mechanical grep-gate hit, and the premise-closure judge on a product-anchor hit — nothing else leaves the gateway. Conventional message, commits directly, offers push on explicit confirmation. Bundled with super-bootstrap — encodes the harness commit rules."
tags: [commit, git, session, doc-sync]
---
# Commit — Session-Isolated, Doc-Sync-Gated (gateway-inline)
Commits the changes this Claude session produced, leaving prior uncommitted work alone. The gateway runs the flow inline — it holds the session's diff, file list, and change intent, so the mechanics carry no closure a fresh container would hold. Only the **doc-sync scan** dispatches, and only when the diff touches the doc surface: it is the one step that earns a cold, context-clean pass — cold-eyes catch staleness the author is blind to.
## Execution (gateway-inline)
1. **Session file list** — from this conversation, the files this session edited/wrote. This is the session-isolation ground truth; a file you don't remember touching stays off it. Stage by explicit path only.
2. **Gather state** — `git status`, `git diff`, `git diff --staged` (a staged path outside the §1 list is another session's — early warning only; §5's readback is the gate), `git log --oneline -10` (recent style).
3. **Doc-sync grep-gate** — mechanical, no judgment:
- **Deferred mode — check first** (drain-worktree isolated commit): doc-sync belongs to the merge boundary — skip all of §3, go to §5.
- - **Frozen-provenance exemption — card lifecycle, history dimension:** every changed path inside `docs/work/` (card-thread appends, card deletions, work-README high-water bump), plus `docs/outward.md` entry appends / deletions / high-water bumps (flat state rows, like card threads) → skip the gate, go to the link check below then §5. Card threads are self-contained; cross-card ID mentions are frozen provenance, not behavior narration — so `hits` leaves every `docs/work/` card thread and `docs/outward.md` out of the scan scope too, whatever term they name. A doc whose leading frontmatter declares `dimension: history` is frozen provenance the same way — a change to it yields no term (`terms` skips it), `hits` and `refs` leave it out of the scan scope, and the link check below still covers it. Mixed diff → run the gate on the other paths only.
+ - **Frozen-provenance exemption — card lifecycle, history dimension:** every changed path inside `docs/work/` (card-thread appends, card deletions, work-README high-water bump), plus `docs/outward.md` entry appends / deletions / high-water bumps (flat state rows, like card threads) → skip the gate, go to the link check below then §5. Card threads are self-contained; cross-card ID mentions are frozen provenance, not behavior narration — so `hits` and `refs` leave every `docs/work/` card thread and `docs/outward.md` out of the scan scope too, whatever term they name or anchor they cite; the folder's standing `README.md` narrates the thread contract and stays in both lanes. A doc whose leading frontmatter declares `dimension: history` is frozen provenance the same way — a change to it yields no term (`terms` skips it), `hits` and `refs` leave it out of the scan scope, and the link check below still covers it. Mixed diff → run the gate on the other paths only.
- **Premise lane — product-anchor paths:** the diff touches the product anchor (`docs/overview.md` § Problem / § User, or a dedicated product doc where the repo splits one out) → route the anchor portion through §3b — its closure set is the whole doc surface, so it already covers everything this gate would reach for the anchor; the rest of the diff continues through this gate.
- **Terms → grep hits — one script call each:** `<skill-base>/assets/doc-links.sh terms <changed paths…>` prints the gate's terms; scaffolding paths (bench, tests, fixtures, goldens, session ledgers), asset extensions, generic basenames, terms under four characters, and the machine state harness-bootstrap seeds under `.claude/` (the runway receipt, `templates/`) yield none. Nothing printed → the grep lane is empty, skip to the citer lookup. Otherwise `<skill-base>/assets/doc-links.sh hits <terms…> | grep -vxF "$(printf '%s\n' <changed files>)"` prints the doc-surface files mentioning a term in **code shape** — a whole word inside backticks, or a path segment — so bare prose stays out. Harness-seeded hub stems (`overview`, `techstack`, `decisions`, the runway receipt, the worktree template) count only as a bare token inside backticks: a path mention of a hub doc is a citation the anchored citer lane already reaches, not a narration. Hit files join the scan scope; the agent judges them cold (§4). `hits` walks the markdown surface — a manifest description field the diff changes is read here directly.
- **Link-hit (reverse citers) — mechanical, beside the grep:** for each changed `docs/**` / root `README.md` / plugin-README (`plugins/*/README.md`) path, take its post-image hunk ranges from `git diff -U0 -- <path>` (`@@ -a,b +c,d @@` → `+c,d`) and run `<skill-base>/assets/doc-links.sh anchors <path> <ranges…>`. `(top)` among the slugs means whole-file grain → `<skill-base>/assets/doc-links.sh refs <path>`; otherwise `refs <path>#<slug>…` in one call of the same script, which prints the union. Exclude the changed files themselves. Every file returned is a declared citer of the changed truth — collect them as the **citer read-set**.
- **Link-target extraction (forward links) — mechanical, beside the reverse lookup:** from the diff's added lines, extract every markdown link target (`grep -oE '\]\([^)]+\.md[^)]*\)'` over `+` lines), resolve each relative to its linking file. Each target is a doc the new prose claims agreement with — add the target files to the scan scope. A target that is itself a changed file still joins: its unchanged sections are exactly where a same-commit contradiction hides.
- **Scope ceiling — count before dispatching:** the scan scope is citers ∪ grep hits ∪ link-targets. Above **8** docs, surface it to the user first — the count, the list grouped by lane (citer / hit / link-target), and the options: split the commit by concern, narrow to the anchors actually changed, or proceed over the full set. A hub doc fans out visibly or not at all. At or under 8 → dispatch as below.
- **Any grep hit OR any citer OR any link-target found → dispatch the doc-sync scan (§4), the scan scope — citer read-set + grep-hit files + link-target files — riding the prompt.**
- **Neither → the diff narrates nothing; go to §5.**
- **Link integrity (every non-deferred commit, exemption included):** run `<skill-base>/assets/doc-links.sh check` from the repo root — `<skill-base>` is the `Base directory for this skill:` path surfaced at invocation; zero model tokens. Broken links (path or anchor) surface to the user with the commit: fix or explicitly acknowledge before landing; never silently skip. One class is exempt by construction — the consumed-card-link skip: a link from a card thread (`docs/work/{BUG,DEBT,GAP}-###.md`) to an absent card ID is consumed provenance — the sibling resolved — so `check` skips it uncounted, while every other target from a card, and any dangling card link from a non-card doc, stays strict.
3b. **Premise-closure lane (product-anchor diff)** — a problem/ICP revision changes premise, not behavior; its closure is every doc whose framing leans on the anchor. Enumerate mechanically — `<skill-base>/assets/doc-links.sh closure <anchor-path>` prints the set: the doc surface minus consumables (per-item work files — `docs/work/{BUG,DEBT}-*.md`, `docs/work/TEMPLATE.md`) minus the anchor. Judgment runs only over the enumerated set — dispatch the `premise-closure` agent (`Agent` tool, `subagent_type: "premise-closure"`; prompt = the anchor diff hunks + the anchor path + the enumerated paths, no staleness leans): its sheet (holds / re-frame / dangling per doc + coverage line) returns here; resolve with the user before the commit lands — re-frame: update the doc to align / acknowledge still-accurate; dangling: drop / merge / defer. Never silently fix, never silently skip. Then continue §3 on the rest of the diff.
4. **Doc-sync scan (dispatched on hit)** — `Agent`, `subagent_type: "doc-sync-scan"`; prompt = the diff (`git diff` + `git diff --staged`) + today's date + the scan scope (§3's citer read-set + grep-hit files + link-target files). The agent judges cold and scoped: each scope doc against the diff's claims, plus the diff-scoped new-assertion residual (each new asserting line verified against its link target, or — unlinked — against any existing doc answering the same question) — never a whole-surface re-derivation; whole-surface coverage belongs to `/super-bootstrap:check-docs-consistency`. Returns one shape:
- **`stale-docs`** → resolve each candidate with the user (update / acknowledge-accurate / skip — never silently fix, never silently skip). Land approved doc edits (inline for bounded prose; dispatch by closure). Resolved docs join the stage list.
- **`clean`** → proceed.
5. **Message + commit** — draft a Conventional Commit (`<type>(<scope>): <subject>`, imperative ≤72 chars, body only when the why isn't in the diff, match `git log` style; one logical change per commit — a diff spanning two unrelated changes splits). `git add <explicit paths>` — never `-A` / `.`, never secrets (`.env`, keys).
- **Index readback — the gate between `git add` and `git commit`.** `git diff --cached --name-only` compared against the §1 session file list: the index is shared across sessions in one checkout, so a concurrent session's staged paths ride into this commit unless read back. Any staged path outside the session list → **stop and surface**: the foreign paths, and the pick — unstage-and-continue (`git restore --staged <foreign>`, on the user's say-so only) or abort. Never commit through it.
- **Where a harness-audit stamp call sits between add and commit — `git add` → readback → stamp → `git commit`.** The stamp is a set comparison: it matches only when its path set equals the commit's staged harness set. A foreign path stamped in widens that set, and the readback's own remedy (`git restore --staged <foreign>`) then narrows what commits — leaving a fingerprint that can never match, so the gate re-fires on a commit whose audit did run and §5 carries no re-stamp step. Stamp the set that commits.
- Commit with HEREDOC formatting; after, `git show --name-only --format= HEAD` equals the session list — prior dirty state is sacred, so a clean tree is not the check. Pre-commit hooks run; on failure fix the cause, never bypass. Always a new commit — amend only if asked.
6. **Push (on confirmation)** — present branch → upstream, commits ahead. Ask **"Push these now? (y / skip)"**. Push on explicit yes only (`git push <remote> <branch>`); skip on silence or decline. Never force, never unannounced.
7. **Cycle handoff** — one line from cycle facts (any `docs/work/{BUG,DEBT,GAP}-###.md` present; a card whose latest Plan block has steps the latest Progress doesn't report done = in-flight). Don't expand into a status table — that's `/super-bootstrap:todo`'s job:
| Cycle facts | Handoff one-liner |
|---|---|
| No open cards | `Cycle complete. Safe to /clear. Next session: /super-bootstrap:todo picks up next item.` |
| In-flight card (Plan steps not all reported done in latest Progress) | `Cycle complete. {ID} still in-flight — /clear then /super-bootstrap:todo to resume.` |
| Open cards, none in-flight | `Cycle complete. Open cards, none in-flight — /clear then /super-bootstrap:todo to pick next.` |
## Rules
- **Gateway-inline; two dispatch paths, each on its own gate.** The gateway holds the diff, session list, and intent → mechanics stay inline (no closure a fresh container would hold). The cold doc-sync scan (grep-gate hit) and the premise-closure judge (product-anchor hit) are the steps a clean context serves.
- **Grep-gate is mechanical.** Term extraction is path-structure only, never a judgment about which identifiers matter — a judgment gate gets omitted. Any hit dispatches; conservative by design. A pure asset/binary diff with no narrated path is the skippable class.
- **Session-isolated.** The session list decides; prior dirty state is sacred. Explicit paths, never `-A` — and the staged set is read back against that list before every commit, so isolation holds at the index, not only at `git add`.
- **Doc-sync round-trip, never bypass** — a `stale-docs` return goes through the user before commit.
- **Whole-diff-once.** Doc-sync runs at the integration boundary, on the whole diff, once. Drain-worktree defers it to merge; an implementer never owns doc-sync — a partial-slice view gives false confidence.
- **Push on explicit yes only** — committed work is safe locally either way.