Commit

---
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; on a mechanical gate hit it judges doc-sync warm in its own context (the cold doc-sync-scan agent dispatches only past the scope ceiling), and the premise-closure judge dispatches on a product-anchor hit. 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. The doc-sync judgment runs warm in that same context: the diff, the change intent, and the session's read docs are the judgment's inputs, and the gateway already holds them all. Dispatch survives as the scope-overload valve — a scan scope past the ceiling moves whole to the cold `doc-sync-scan` agent rather than being truncated inline.

## 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** (autorun-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 every changed `docs/outward/OUT-###.md` (thread appends, entry deletions) and the outward README's high-water bump → skip the gate, go to the link check below then §5. Both are append-only threads, self-contained; cross-card ID mentions are frozen provenance, not behavior narration — so `hits` and `refs` leave every `docs/work/` card thread and every `docs/outward/OUT-###.md` thread out of the scan scope too, whatever term they name or anchor they cite; each folder's standing `README.md` narrates its 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) and those sections' post-image carries a premise — body past the skeleton's `{…}` placeholder line, or, for a dedicated product doc with no shipped skeleton, prose beyond a scaffold stub in its Problem / User-equivalent sections → 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. Sections still on the placeholder revise no premise → the anchor path stays in this gate like any other changed doc.
   - **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. A Godot text asset (`.tscn`, `.tres`) runs the inverse: `terms` keeps its extension (`levels/Ending.tscn` → `Ending.tscn`), and `hits` counts that term only as a path segment (`levels/Ending.tscn`, `Ending.tscn`), never as a bare backticked `Ending` — a scene or resource basename doubles as domain vocabulary. Pass the printed terms to `hits` verbatim, extension included. 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**.
   - **Self-scope (changed docs) — mechanical, beside the citer lookup:** `<skill-base>/assets/doc-links.sh self <changed paths…>` prints the changed paths that are doc-surface files in their own right — a deleted path, an off-surface path, and frozen provenance (card threads, `docs/outward/OUT-###.md`, `dimension: history`) all drop out. Every path printed joins the scan scope as its own scope doc: §4 reads it whole and holds its **unchanged** sections against the diff's claims, which is where a same-commit contradiction with the file's pre-existing prose sits.
   - **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.
   - **Scope ceiling — count before judging:** the scan scope is citers ∪ grep hits ∪ link-targets ∪ changed docs. At or under **8** docs → the gateway judges the scope warm-inline (§4). Above 8 → the scope moves whole to the cold `doc-sync-scan` dispatch (§4's fallback lane) — never truncated to fit inline.
   - **Any grep hit OR any citer OR any link-target OR any changed doc → run the doc-sync judgment (§4) over the scan scope — citer read-set + grep-hit files + link-target files + the changed docs themselves.**
   - **All four lanes empty → the diff narrates nothing; go to §5.** The self lane makes this the narrow branch it reads as: a diff that touched no doc-surface file outside the frozen-provenance exemptions — an asset, code, or exempt-thread diff.
   - **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.
   - **Model-pin integrity (every non-deferred commit):** run `<skill-base>/assets/doc-links.sh pins` from the repo root; zero model tokens. Reads each agent file's frontmatter `model:` and reports doc-surface lines whose restated tier disagrees with the agent named inside an inline code span — `<doc>:<lineno>` + claimed tokens + actual tier + source path. Deliberately narrow, so the per-commit gate stays quiet: a line resolving to no agent or to several is skipped, and any one agreeing tier token clears it. Whole-surface by construction: it consults no scan scope, so a doc no enumeration lane reached is covered the same. Frozen provenance is out, as in every other claim lane — a closed-fork row or card thread restates a past tier by design. Stale pins surface to the user with the commit: fix or explicitly acknowledge before landing; never silently skip.

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 — `git diff -U0 -- <anchor-path>`, `--cached` once the anchor is staged, output pasted verbatim into the prompt (the judge has no shell; the pasted lines are its only view of the old premise) — + the anchor path + the enumerated paths, no staleness leans): its sheet (holds / re-frame / dangling per doc + coverage line) returns here; a coverage mismatch or a `no-hunks` line re-dispatches, the latter with the hunks pasted. 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 judgment (gate hit)** — warm gateway-inline by default; the cold dispatch is the overload lane. Both lanes run the same procedure — `agents/doc-sync-scan.md` § Scan — and end in the same resolution.
   - **Warm-inline (scope ≤ ceiling):** the gateway applies § Scan itself, in its own context. Warm eyes are the point: hold the change intent and the session's reads beside the diff while judging. Every scope doc gets an outcome — a stale candidate (path + what's outdated + hunk) or read-and-confirmed-unchanged; a doc skimmed or skipped is an incomplete gate, not a `clean`.
   - **Cold dispatch (scope > ceiling):** `Agent`, `subagent_type: "doc-sync-scan"`; prompt = the diff (`git diff` + `git diff --staged`) + today's date + the scan scope. The agent judges the same procedure in its own window and returns `stale-docs` or `clean`.
   - Either lane stays scoped — never a whole-surface re-derivation; whole-surface coverage belongs to `/super-bootstrap:check-docs-consistency`.
   - **Stale candidates** → resolve each 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.
   - **Nothing stale** → 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 (where a push surface exists)** — probe first, ask second; the probe is a fact the gateway reads itself. `git remote` prints nothing → no push surface: §7's handoff line is the next and only output. A remote but no upstream for the branch (`git rev-parse --abbrev-ref @{u}` errors) → say so in one line and ask once: **"Set upstream and push (`git push -u <remote> <branch>`)? (y / skip)"** — `<remote>` is the sole remote, or the one the user names when several exist. Remote + upstream → present branch → upstream, commits ahead; ask **"Push these now? (y / skip)"**. Push on explicit yes only; skip on silence or decline. Never force, never unannounced. Invoked by `/super-bootstrap:session-close` → no ask: the close pick's push answer is the answer.

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 — `/super-bootstrap:needs-me` recommends, this line only hands off (skipped when invoked by `/super-bootstrap:session-close` — its Output is the terminal output):

| Cycle facts | Handoff one-liner |
|---|---|
| No open cards | `Cycle complete. Safe to /clear. Next session: /super-bootstrap:needs-me or /super-bootstrap:autorun.` |
| In-flight card (Plan steps not all reported done in latest Progress) | `Cycle complete. {ID} still in-flight — /clear then pick it up by ID or via /super-bootstrap:needs-me.` |
| Open cards, none in-flight | `Cycle complete. Open cards, none in-flight — /clear then /super-bootstrap:needs-me (needs you) or /super-bootstrap:autorun (does not).` |

## Rules

- **Gateway-inline, judgment included; two dispatch valves, each on its own gate.** The gateway holds the diff, session list, intent, and session reads → mechanics and the doc-sync judgment stay inline (the judgment's inputs are exactly what the gateway holds). The cold doc-sync scan dispatches past the scope ceiling; the premise-closure judge dispatches on a product-anchor hit.
- **Grep-gate is mechanical.** Term extraction is path-structure only, never a judgment about which identifiers matter — a judgment gate gets omitted. Any lane hit triggers the doc-sync judgment (§4); conservative by design. A diff that touches no doc-surface file and hits no lane — 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. An autorun worktree defers it to merge; an implementer never owns doc-sync — a partial-slice view gives false confidence.
- **Push asks only where a push surface exists, and only on explicit yes** — §6's probe decides whether the question fires; committed work is safe locally either way.