continuous-improvement 3.21.0 → 3.22.1

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "continuous-improvement",
       "description": "The persistent-memory and runtime-discipline layer for Claude Code. It remembers the corrections you already gave, grounds every edit in real facts before it lands, and — through the Mulahazah engine — turns each fix into a reusable instinct, so a lesson learned once is applied automatically next time with no re-teaching. Built on the 7 Laws of AI Agent Discipline (research, plan, verify, reflect, learn) and shipped as 28 bundled skills, instinct-aware hooks, an MCP toolset for recall and reflection, and a GitHub Action transcript linter that feeds real work history back into sharper instincts.",
-      "version": "3.21.0",
+      "version": "3.22.1",
       "source": "./plugins/continuous-improvement",
       "author": {
         "name": "naimkatiman"

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to this skill are documented here.
 
 ---
 
+## [3.22.1] — 2026-08-04
+
+### Fixed
+
+- **`ci-reconcile` blocks an unborn HEAD instead of treating it as a usable baseline** — `git init` with no commit yet is a real git repository, but `git rev-parse HEAD` fails there. The runner accepted that as a pinnable state, and `--snapshot` emitted an empty `head` field that reads like success. Now reported as a `head-commit` blocker, with `--snapshot` emitting `head: "unborn"` and `blocked: true`. (#291)
+- **`isSafeRefName` rejects ref shapes git itself rejects** — empty path components (`a//b`), dot-prefixed or dot-suffixed components (`a/.b`, `a/b.`), and a per-component `.lock` suffix (`a/b.lock/c`) previously passed. Validation is now component-by-component, closer to `git check-ref-format`. (#291)
+- **`parseRevListCounts` uses `Number.isSafeInteger`** — `Number.isInteger` accepts values beyond `MAX_SAFE_INTEGER`, where arithmetic silently loses precision. Out-of-range counts now read as `unknown`, consistent with the module's fail-closed stance. (#291)
+- **The CLI rejects malformed argument combinations instead of resolving them silently** — a repeated `--verify-push` or `--cwd` used to be last-wins, an empty or whitespace-only `--cwd` fell back to the process working directory, and `--snapshot` / `--explain` / `--verify-push` together picked one arbitrarily. Each is now an explicit error. (#291)
+
+### Changed
+
+- **`--snapshot` follows the same exit contract as the default mode** (`0` clear / `1` blocked / `2` not a repository) where it previously always exited `0`, and its envelope gains `blocked` and `blockers`. It still writes the JSON on a blocker, so a `set -e` script capturing a baseline must tolerate exit 1. Documented in the skill and command, along with the unborn-HEAD row. (#291)
+
+## [3.22.0] — 2026-08-02
+
+### Added
+
+- **`ci-reconcile`**: the `reconcile` ground-truth pass is now a command, not just prose. It spawns `git` argv with no shell — no bash, no coreutils, no `.git/`-relative path — so it behaves the same in PowerShell, cmd, Git Bash and WSL, and stays correct inside a linked worktree. `--json`, `--explain`, `--verify-push <branch>`, and `--snapshot` (field-compatible with `scripts/git-state-snapshot.sh`, plus `contentDrift` and `inProgress`). Exits `0` clear / `1` blocked / `2` not a git repository. (#289)
+- **`verify:reconcile-parity`**, the 16th `verify:all` invariant: a fenced code block in each of `skills/reconcile.md` and `commands/reconcile.md` must prescribe every probe in `GROUND_TRUTH_PROBES` verbatim, and no fenced block may reintroduce a retired form. Fenced-only, so prose stays free to explain *why* a command was retired. (#289)
+
+### Fixed
+
+- **`reconcile` no longer reports a false clean state at four boundaries.** Reproduced against real git: asking `git rev-list` for counts against `@{u}` exits **128** with `fatal: no upstream configured` rather than returning zeros; `git branch --show-current` prints an empty string and exits **0** on a detached HEAD, indistinguishable from a successful read; inside a linked worktree `.git` is a **file**, so listing a `.git/`-relative `MERGE_HEAD` exits **2** exactly as it does on a clean tree, meaning a real conflicted merge read as clean; and `git status` overstates drift on an `autocrlf` tree. The skill and command now document a portable probe for each, plus a compatibility matrix. (#289)
+- **Every `git-state` classifier fails closed.** Unparseable ahead/behind counts read as `unknown` (a blocker), never `even`. A failed `git ls-remote` reads as `unverified` — never `not-landed` and never `landed` — so a network failure can no longer be reported as either outcome. An unprobed in-progress marker reads as `unprobed`, never `absent`. An unparseable branch name never matches an expected one. (#289)
+- Verify-lint count prose corrected across `CLAUDE.md` (claimed 14 and omitted `landing-version`), `CONTRIBUTING.md` (13) and `docs/RELEASING.md` (12); the actual count was 15, now 16. (#289)
+
 ## [3.21.0] — 2026-07-11
 
 ### Added

package/bin/check-reconcile-parity.mjs

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * Reconcile-Parity Invariant Check
+ *
+ * The ground-truth git command set exists in three places at once: the runner
+ * (`bin/reconcile.mjs`), the skill (`skills/reconcile.md`) and the slash command
+ * (`commands/reconcile.md`). Prose copies drift — the `'@{u}'` Bash-quoting fix
+ * had to be applied by hand to both docs, and a portability fix applied to one
+ * copy leaves the other telling agents to run the broken form.
+ *
+ * `GROUND_TRUTH_PROBES` in src/lib/git-state.mts is the single source of truth.
+ * This lint asserts the docs still document exactly that set, and that neither
+ * doc has regressed to a command proven non-portable on 2026-08-02:
+ *
+ *   Side A — a fenced code block in each doc prescribes every probe in
+ *            GROUND_TRUTH_PROBES verbatim. Fenced blocks only: a probe named in
+ *            prose but dropped from the copyable block would otherwise pass
+ *            while the command an agent actually runs had lost it.
+ *   Side B — no fenced code block in either doc *prescribes* a retired form:
+ *              `ls .git/...`            (`.git` is a FILE in a linked worktree,
+ *                                        so the probe silently reports nothing)
+ *              `branch --show-current`  (empty stdout + exit 0 on a detached
+ *                                        HEAD is indistinguishable from success)
+ *            Only fenced blocks are scanned, so the prose stays free to explain
+ *            why each form was retired without tripping its own lint.
+ *   Side C — both docs document `rev-parse --git-path`, the worktree-correct way
+ *            to locate an in-progress-operation marker.
+ *
+ * Fail-closed: a missing file or an empty doc is a violation, not a silent pass.
+ *
+ * Usage:
+ *   node bin/check-reconcile-parity.mjs              # Check the current repo
+ *   node bin/check-reconcile-parity.mjs <repo-root>  # Check a specific repo root
+ *
+ * Exit codes:
+ *   0 — both docs match the shipped probe set and carry no retired form
+ *   1 — at least one drift
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { argv, cwd, exit } from "node:process";
+import { GROUND_TRUTH_PROBES } from "../lib/git-state.mjs";
+const DOCS = ["skills/reconcile.md", "commands/reconcile.md"];
+const RETIRED_FORMS = [
+    {
+        pattern: /\bls\s+[^\n`]*\.git\//,
+        label: "ls .git/<marker>",
+        why: "`.git` is a FILE inside a linked worktree, so this probe exits 2 exactly as it does on a clean tree — a real merge reads as no operation in progress",
+    },
+    {
+        pattern: /\bbranch\s+--show-current\b/,
+        label: "git branch --show-current",
+        why: "returns an empty string with exit 0 on a detached HEAD, which cannot be told apart from a successful read; use `symbolic-ref --quiet --short HEAD`",
+    },
+];
+const REQUIRED_SUBSTRINGS = [
+    {
+        needle: "rev-parse --git-path",
+        why: "the only worktree-correct way to locate MERGE_HEAD / rebase-merge / rebase-apply",
+    },
+];
+/**
+ * Normalize a doc or a command for comparison: collapse whitespace and drop the
+ * shell quoting docs add around `@{u}` refspecs. Returns "" for absent input.
+ */
+export function normalizeForMatch(text) {
+    if (typeof text !== "string")
+        return "";
+    return text.replace(/[`'"]/g, "").replace(/\s+/g, " ");
+}
+/** The literal command line a doc must contain for a probe, before normalization. */
+export function probeCommand(args) {
+    return `git ${args.join(" ")}`;
+}
+/**
+ * Concatenate the bodies of every fenced code block in `body`.
+ *
+ * Retired forms are only a defect when a doc *prescribes* them, so Side B scans
+ * fenced blocks alone — prose may name a retired command to explain it. Returns
+ * "" when the doc has no fenced block.
+ */
+export function fencedBlocks(body) {
+    const lines = body.split(/\r?\n/);
+    const collected = [];
+    let inside = false;
+    for (const line of lines) {
+        if (/^\s*```/.test(line)) {
+            inside = !inside;
+            continue;
+        }
+        if (inside)
+            collected.push(line);
+    }
+    return collected.join("\n");
+}
+/** Check one doc body against the shipped probe set. Returns [] when reconciled. */
+export function checkDoc(doc, body) {
+    if (body === null)
+        return [{ doc, kind: "missing-file", detail: "file does not exist" }];
+    if (body.trim().length === 0)
+        return [{ doc, kind: "empty", detail: "file is empty" }];
+    const violations = [];
+    const prescribed = fencedBlocks(body);
+    const prescribedHaystack = normalizeForMatch(prescribed);
+    // Side A scans fenced blocks only. A probe named in prose but absent from the
+    // copyable block would otherwise satisfy the check while the command an agent
+    // actually runs had silently dropped it.
+    for (const probe of GROUND_TRUTH_PROBES) {
+        const command = probeCommand(probe.args);
+        if (!prescribedHaystack.includes(normalizeForMatch(command))) {
+            violations.push({
+                doc,
+                kind: "missing-probe",
+                detail: `no fenced block prescribes probe "${probe.id}": ${command}`,
+            });
+        }
+    }
+    for (const retired of RETIRED_FORMS) {
+        if (retired.pattern.test(prescribed)) {
+            violations.push({
+                doc,
+                kind: "retired-form",
+                detail: `a fenced block still prescribes \`${retired.label}\` — ${retired.why}`,
+            });
+        }
+    }
+    const haystack = normalizeForMatch(body);
+    for (const required of REQUIRED_SUBSTRINGS) {
+        if (!haystack.includes(normalizeForMatch(required.needle))) {
+            violations.push({
+                doc,
+                kind: "missing-substring",
+                detail: `does not mention \`${required.needle}\` — ${required.why}`,
+            });
+        }
+    }
+    return violations;
+}
+/** Read every doc under `repoRoot` and collect violations across all of them. */
+export function checkRepo(repoRoot) {
+    return DOCS.flatMap((doc) => {
+        const path = join(repoRoot, doc);
+        const body = existsSync(path) ? readFileSync(path, "utf8") : null;
+        return checkDoc(doc, body);
+    });
+}
+function main() {
+    const repoRoot = argv[2] ?? cwd();
+    const violations = checkRepo(repoRoot);
+    if (violations.length === 0) {
+        console.log(`OK reconcile-parity: ${DOCS.length} doc(s) document all ${GROUND_TRUTH_PROBES.length} ground-truth probe(s), no retired forms.`);
+        return;
+    }
+    console.error(`FAIL reconcile-parity: ${violations.length} drift(s).`);
+    console.error("");
+    for (const violation of violations) {
+        console.error(`  ${violation.doc} — ${violation.detail}`);
+    }
+    console.error("");
+    console.error("Fix: GROUND_TRUTH_PROBES in src/lib/git-state.mts is the source of truth. Update the");
+    console.error("doc prose to match it (or change the probe set there first), then `npm run build` so the");
+    console.error("plugin mirrors regenerate.");
+    exit(1);
+}
+const invokedDirectly = argv[1] !== undefined && import.meta.url.endsWith(argv[1].replace(/\\/g, "/"));
+if (invokedDirectly || argv[1]?.endsWith("check-reconcile-parity.mjs")) {
+    main();
+}

package/bin/generate-plugin-manifests.mjs

@@ -147,6 +147,8 @@ async function writePluginBundle() {
         copyFileTo(join(REPO_ROOT, "bin", "mcp-server.mjs"), join(PLUGIN_BUNDLE_DIR, "bin", "mcp-server.mjs")),
         copyFileTo(join(REPO_ROOT, "bin", "observe.mjs"), join(PLUGIN_BUNDLE_DIR, "bin", "observe.mjs")),
         copyFileTo(join(REPO_ROOT, "bin", "backfill.mjs"), join(PLUGIN_BUNDLE_DIR, "bin", "backfill.mjs")),
+        copyFileTo(join(REPO_ROOT, "bin", "reconcile.mjs"), join(PLUGIN_BUNDLE_DIR, "bin", "reconcile.mjs")),
+        copyFileTo(join(REPO_ROOT, "lib", "git-state.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "git-state.mjs")),
         copyFileTo(join(REPO_ROOT, "bin", "gateguard-clear.mjs"), join(PLUGIN_BUNDLE_DIR, "bin", "gateguard-clear.mjs")),
         copyFileTo(join(REPO_ROOT, "lib", "gateguard-state.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "gateguard-state.mjs")),
         copyFileTo(join(REPO_ROOT, "lib", "plugin-metadata.mjs"), join(PLUGIN_BUNDLE_DIR, "lib", "plugin-metadata.mjs")),

package/bin/reconcile.mjs

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+/**
+ * reconcile (`ci-reconcile`).
+ *
+ * Run the `reconcile` skill's ground-truth pass and print the resolved-state
+ * block, so Law 1 is a command an agent runs rather than prose it claims to
+ * have followed.
+ *
+ *   node bin/reconcile.mjs                    resolved-state block; exit 1 on a blocker
+ *   node bin/reconcile.mjs --json             the same state as JSON
+ *   node bin/reconcile.mjs --snapshot         one-line envelope, field-compatible
+ *                                             with scripts/git-state-snapshot.sh
+ *   node bin/reconcile.mjs --verify-push <br> prove a push landed on origin/<br>
+ *   node bin/reconcile.mjs --explain          print the probe set and why each runs
+ *   node bin/reconcile.mjs --cwd <dir>        run against another repo root
+ *
+ * Portability: every probe is `git` argv spawned with `shell: false`. No bash,
+ * no coreutils, no `.git/`-relative paths — so it behaves the same in PowerShell,
+ * cmd, Git Bash, WSL and a POSIX shell, and it stays correct inside a linked
+ * worktree where `.git` is a file rather than a directory.
+ *
+ * Exit codes:
+ *   0 — ground truth established, nothing blocks a mutation
+ *   1 — at least one blocker (detached HEAD, in-progress op, unknown upstream)
+ *   2 — not a git repository, or git is unavailable
+ */
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { argv, cwd, exit, stderr, stdout } from "node:process";
+import { GROUND_TRUTH_PROBES, IN_PROGRESS_MARKERS, accountDirty, assessGitState, classifyHead, classifyUpstream, hasBlockers, isSafeRefName, parseRevListCounts, renderResolvedState, verifyPushLanded, } from "../lib/git-state.mjs";
+const NOT_A_REPO = 2;
+/** Spawn `git` with no shell. A missing git binary reads as a failed probe. */
+function git(args, root) {
+    const result = spawnSync("git", [...args], {
+        cwd: root,
+        encoding: "utf8",
+        shell: false,
+        windowsHide: true,
+    });
+    if (result.error) {
+        return { stdout: "", stderr: result.error.message, code: 127 };
+    }
+    return {
+        stdout: result.stdout ?? "",
+        stderr: result.stderr ?? "",
+        code: typeof result.status === "number" ? result.status : 1,
+    };
+}
+function parseArgs(args) {
+    const options = {
+        json: false,
+        snapshot: false,
+        explain: false,
+        verifyPush: null,
+        root: cwd(),
+    };
+    let cwdProvided = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i] ?? "";
+        if (arg === "--json")
+            options.json = true;
+        else if (arg === "--snapshot")
+            options.snapshot = true;
+        else if (arg === "--explain")
+            options.explain = true;
+        else if (arg === "--verify-push") {
+            if (options.verifyPush !== null) {
+                throw new Error("--verify-push may only be provided once");
+            }
+            const value = args[i + 1];
+            if (value === undefined || value.startsWith("--")) {
+                throw new Error("--verify-push requires a branch name");
+            }
+            if (!isSafeRefName(value)) {
+                throw new Error(`--verify-push branch is not a usable ref name: ${value}`);
+            }
+            options.verifyPush = value;
+            i++;
+        }
+        else if (arg === "--cwd") {
+            if (cwdProvided) {
+                throw new Error("--cwd may only be provided once");
+            }
+            const value = args[i + 1];
+            if (value === undefined || value.startsWith("--") || value.trim().length === 0) {
+                throw new Error("--cwd requires a directory");
+            }
+            options.root = value;
+            cwdProvided = true;
+            i++;
+        }
+        else if (arg === "--help" || arg === "-h") {
+            options.explain = true;
+        }
+        else {
+            throw new Error(`unknown argument: ${arg}`);
+        }
+    }
+    const actions = [
+        options.snapshot ? "--snapshot" : null,
+        options.explain ? "--explain" : null,
+        options.verifyPush !== null ? "--verify-push" : null,
+    ].filter((action) => action !== null);
+    if (actions.length > 1) {
+        throw new Error(`mutually exclusive action modes: ${actions.join(", ")}`);
+    }
+    return options;
+}
+/** Probe each in-progress marker through `--git-path`, which is worktree-correct. */
+function probeInProgress(root) {
+    const present = [];
+    for (const marker of IN_PROGRESS_MARKERS) {
+        const resolved = git(["rev-parse", "--git-path", marker.gitPath], root);
+        // A failed resolve leaves the marker unprobed rather than absent; the
+        // classifier reports that explicitly instead of implying a clean tree.
+        if (resolved.code !== 0)
+            continue;
+        const path = resolved.stdout.trim();
+        if (path.length > 0 && existsSync(path))
+            present.push(marker.id);
+    }
+    return present;
+}
+function explain() {
+    const rows = GROUND_TRUTH_PROBES.map((probe) => `  git ${probe.args.join(" ")}\n      ${probe.purpose}` +
+        (probe.tolerateFailure ? "\n      (a non-zero exit is an answer, not a failure)" : ""));
+    const markers = IN_PROGRESS_MARKERS.map((marker) => `  git rev-parse --git-path ${marker.gitPath}   # ${marker.label}`);
+    return [
+        "reconcile ground-truth probes (source: src/lib/git-state.mts):",
+        ...rows,
+        "",
+        "in-progress operation markers:",
+        ...markers,
+    ].join("\n");
+}
+function main() {
+    let options;
+    try {
+        options = parseArgs(argv.slice(2));
+    }
+    catch (error) {
+        stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        exit(NOT_A_REPO);
+        return;
+    }
+    if (options.explain) {
+        stdout.write(`${explain()}\n`);
+        exit(0);
+        return;
+    }
+    const root = git(["rev-parse", "--show-toplevel"], options.root);
+    if (root.code !== 0) {
+        if (options.snapshot) {
+            stdout.write('{"error":"not-a-git-repo"}\n');
+        }
+        else {
+            stderr.write("not a git repository (or git is unavailable)\n");
+        }
+        exit(NOT_A_REPO);
+        return;
+    }
+    const repoRoot = root.stdout.trim();
+    const headSha = git(["rev-parse", "HEAD"], options.root);
+    const branchProbe = git(["symbolic-ref", "--quiet", "--short", "HEAD"], options.root);
+    const head = classifyHead(branchProbe.stdout, branchProbe.code);
+    const upstreamProbe = git(["rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], options.root);
+    const upstreamRef = upstreamProbe.code === 0 ? upstreamProbe.stdout.trim() || null : null;
+    // Only ask for counts once an upstream is known to exist — the bare command
+    // exits 128 with `fatal: no upstream configured` otherwise.
+    const countsProbe = upstreamRef === null
+        ? null
+        : git(["rev-list", "--left-right", "--count", "@{u}...HEAD"], options.root);
+    const counts = countsProbe !== null && countsProbe.code === 0
+        ? parseRevListCounts(countsProbe.stdout)
+        : null;
+    const status = git(["status", "--porcelain=v1"], options.root);
+    const drift = git(["diff", "--name-only", "--ignore-all-space"], options.root);
+    const dirty = accountDirty(status.code === 0 ? status.stdout : null, drift.code === 0 ? drift.stdout : null);
+    const inProgress = probeInProgress(options.root);
+    const baseFindings = assessGitState({
+        headCommit: headSha.code === 0 ? headSha.stdout.trim() : null,
+        head,
+        upstreamRef,
+        counts,
+        inProgress,
+        dirty,
+    });
+    if (options.snapshot) {
+        // Field-compatible with scripts/git-state-snapshot.sh, plus `contentDrift`,
+        // `inProgress`, and a fail-closed blocker summary the shell version cannot
+        // report. An unborn HEAD is a git repo, but not a usable mutation baseline;
+        // do not emit an empty `head` field that looks like success.
+        const upstreamSha = upstreamRef === null ? "none" : git(["rev-parse", "--short", "@{u}"], options.root).stdout.trim() || "none";
+        const shortHead = headSha.code === 0 ? git(["rev-parse", "--short", "HEAD"], options.root).stdout.trim() : "";
+        const blockers = baseFindings.filter((finding) => finding.severity === "blocker").map((finding) => finding.id);
+        stdout.write(`${JSON.stringify({
+            head: shortHead.length > 0 ? shortHead : "unborn",
+            upstream: upstreamSha,
+            dirty: dirty.reported,
+            root: repoRoot,
+            branch: head.branch ?? "detached",
+            contentDrift: dirty.contentDrift,
+            inProgress,
+            blocked: blockers.length > 0,
+            blockers,
+        })}\n`);
+        exit(blockers.length > 0 ? 1 : 0);
+        return;
+    }
+    if (options.verifyPush !== null) {
+        const lsRemote = git(["ls-remote", "origin", `refs/heads/${options.verifyPush}`], options.root);
+        const verdict = verifyPushLanded({
+            localHead: headSha.stdout.trim(),
+            lsRemoteStdout: lsRemote.stdout,
+            lsRemoteExitCode: lsRemote.code,
+        });
+        const line = `push ${options.verifyPush}: ${verdict.verdict} — ${verdict.reason}`;
+        if (options.json)
+            stdout.write(`${JSON.stringify({ branch: options.verifyPush, ...verdict })}\n`);
+        else
+            stdout.write(`${line}\n`);
+        exit(verdict.verdict === "landed" ? 0 : 1);
+        return;
+    }
+    const findings = [...baseFindings];
+    const stashes = git(["stash", "list"], options.root);
+    const stashCount = stashes.code === 0
+        ? stashes.stdout.split(/\r?\n/).filter((line) => line.trim().length > 0).length
+        : null;
+    findings.push({
+        id: "stashes",
+        label: "stashes",
+        detail: stashCount === null
+            ? "unprobed"
+            : stashCount === 0
+                ? "none"
+                : `${stashCount} — may hold uncommitted work from an earlier session`,
+        severity: stashCount === null ? "warn" : "ok",
+    });
+    const worktrees = git(["worktree", "list", "--porcelain"], options.root);
+    const worktreeCount = worktrees.code === 0
+        ? worktrees.stdout.split(/\r?\n/).filter((line) => line.startsWith("worktree ")).length
+        : null;
+    findings.push({
+        id: "worktrees",
+        label: "worktrees",
+        detail: worktreeCount === null
+            ? "unprobed"
+            : worktreeCount <= 1
+                ? "1 (this one)"
+                : `${worktreeCount} — a concurrent writer may hold another; re-read HEAD immediately before each mutation`,
+        severity: worktreeCount === null || (worktreeCount ?? 0) > 1 ? "warn" : "ok",
+    });
+    const blocked = hasBlockers(findings);
+    if (options.json) {
+        stdout.write(`${JSON.stringify({
+            root: repoRoot,
+            head: headSha.stdout.trim(),
+            branch: head.branch,
+            headKind: head.kind,
+            upstream: upstreamRef,
+            relation: classifyUpstream(counts, upstreamRef !== null),
+            counts,
+            inProgress,
+            dirty,
+            stashes: stashCount,
+            worktrees: worktreeCount,
+            findings,
+            blocked,
+        }, null, 2)}\n`);
+    }
+    else {
+        stdout.write(`${renderResolvedState(findings)}\n`);
+        if (blocked) {
+            stdout.write("\nBLOCKED — resolve every blocker above before mutating this tree.\n");
+        }
+    }
+    exit(blocked ? 1 : 0);
+}
+const invokedDirectly = argv[1] !== undefined && import.meta.url.endsWith(argv[1].replace(/\\/g, "/"));
+if (invokedDirectly || argv[1]?.endsWith("reconcile.mjs")) {
+    main();
+}

package/commands/reconcile.md

@@ -13,15 +13,39 @@ Snapshots the full git state in one pass, detects a concurrent writer, classifie
 
 ## Establish ground truth
 
+One command, cross-platform, no shell required:
+
+```
+npx ci-reconcile              # resolved-state block; exit 0 clear / 1 blocked / 2 not a repo
+npx ci-reconcile --json       # machine-readable
+npx ci-reconcile --explain    # the probe set and why each probe runs
+```
+
+The same pass by hand. `src/lib/git-state.mts` is the source of truth for this list, and `npm run verify:reconcile-parity` fails if this file drifts from it:
+
 ```
-git branch --show-current
-git status --porcelain=v1                     # but trust git diff --stat for real drift (autocrlf)
-git rev-list --left-right --count '@{u}...HEAD'  # behind / ahead (quote the ref — bare @{u} trips the Bash parser)
+git rev-parse --show-toplevel                          # inside a work tree, and where
+git rev-parse HEAD                                     # the sha every later claim is relative to
+git symbolic-ref --quiet --short HEAD                  # branch; NON-ZERO EXIT = detached HEAD
+git rev-parse --abbrev-ref --symbolic-full-name @{u}   # upstream, or non-zero = none configured
+git rev-list --left-right --count @{u}...HEAD          # behind/ahead — only after the line above succeeded
+git status --porcelain=v1                              # reported changes (inflated by autocrlf)
+git diff --name-only --ignore-all-space                # real content drift — the number to trust
 git stash list
-git worktree list
-ls .git/MERGE_HEAD .git/rebase-merge .git/rebase-apply 2>/dev/null  # in-progress op = another actor; do not race
+git worktree list --porcelain
+git rev-parse --git-path MERGE_HEAD                    # in-progress op: test the RESOLVED path
 ```
 
+Four boundaries where the obvious command lies:
+
+- **No upstream** — asking `git rev-list` for counts against `@{u}` exits 128; it does not return zeros. Resolve the upstream first.
+- **Detached HEAD** — the `--show-current` form of `git branch` prints "" and exits 0, indistinguishable from success. `symbolic-ref --quiet` exits non-zero instead. Detached blocks.
+- **Linked worktree** — `.git` is a *file* there, so a `.git/`-relative marker probe exits 2 exactly as it does on a clean tree: a real conflicted merge reads as clean. Use `rev-parse --git-path`.
+- **autocrlf** — `git status` overstates drift. Stage by explicit filename, never `git add -A`.
+- **Unborn HEAD** — `git init` with no commit is a real repo with no usable baseline; `rev-parse HEAD` fails. Reported as `head: "unborn"` and blocked, never as an empty field that reads like success.
+
+`--snapshot` shares the exit contract (`0` clear / `1` blocked / `2` not a repo) and adds `contentDrift`, `inProgress`, `blocked`, `blockers` to the shell script's envelope. It still writes the JSON on a blocker, so tolerate exit 1 when capturing a baseline under `set -e`.
+
 ## Then act, with gates
 
 ```
@@ -51,9 +75,12 @@ gh pr create --fill --base main                      # open one PR, then STOP
 ## Verify the push landed
 
 ```
-git ls-remote origin refs/heads/<branch>   # remote tip must equal local HEAD, else it did not land
+npx ci-reconcile --verify-push <branch>    # exit 0 only when the remote tip equals local HEAD
+git ls-remote origin refs/heads/<branch>   # by hand: remote tip must equal local HEAD
 ```
 
+Three outcomes, never two: **landed** (tip matches), **not-landed** (probe succeeded, ref absent or different sha), **unverified** (`ls-remote` itself failed — you do not know; retry, and report neither success nor failure).
+
 ## Sync the default branch after the PR merges
 
 "Latest work on main" is true only once the PR merges, and on a protected branch that merge is a human action. After it lands: