plumbbob 0.9.1 → 0.9.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "plumbbob",
   "displayName": "PlumbBob",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Attention-first build process — driver skills + a CLI that keep you the decider: guidance on the work, a latch on the record.",
   "author": { "name": "Rob McLarty", "email": "hello@robmclarty.com", "url": "https://robmclarty.com" },
   "homepage": "https://github.com/robmclarty/plumbbob#readme",

package/README.md

@@ -292,6 +292,7 @@ Each doc answers one question — in rough reading order for a new user:
 - *How do I get a local model reviewing my steps?* → [`docs/local-model-review.md`](docs/local-model-review.md) — the ollama-reviewer example walked end to end, install to every-pause review.
 - *How do I install it, exactly?* → [`docs/install.md`](docs/install.md) — the full guide and the agent-neutral roadmap.
 - *What does the CLI underneath do?* → [`docs/cli-reference.md`](docs/cli-reference.md) — every verb, flag, exit code, and the `.plumbbob/` sidecar.
+- *What are these untracked files, and why is it touching my `.git`?* → [`docs/state-and-git.md`](docs/state-and-git.md) — the state files, the `info/exclude` mechanism, and the objections answered.
 - *Something's broken.* → [`docs/troubleshooting.md`](docs/troubleshooting.md) — fixes for the common snags.
 - *Why is it built this way?* → [`docs/decisions.md`](docs/decisions.md) — the `D#` / `C#` design-decision key the source cites.
 - *How does it hang together inside?* → [`docs/architecture.md`](docs/architecture.md) — the layers and planes, for contributors (in progress).

package/dist/lib/sidecar.js

@@ -583,3 +583,39 @@ export function excludeControl(root) {
 export function excludeSidecar(root) {
     addExcludes(root, [`${DIRNAME}/`, '.check/']);
 }
+/**
+ * Whether info/exclude already carries `pattern` verbatim.
+ *
+ * Absent or unreadable reads as "no" — the caller's job is to write it, not to
+ * fail on a repo that has never been excluded.
+ */
+function hasExclude(root, pattern) {
+    try {
+        return readFileSync(gitPath(root, 'info/exclude'), 'utf8')
+            .split('\n')
+            .some((line) => line.trim() === pattern);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Re-apply the control-plane excludes on the way into a `git add -A`.
+ *
+ * `start` writes them once, but a plumbbob upgraded mid-build can add a control
+ * file the running session's exclude never learned — TICK, GRANT and
+ * handoff.json all arrived that way — and checkpoint/finish stage with `-A`,
+ * which would sweep the unexcluded file into the commit and ride it into the PR.
+ * Idempotent, so the common path is one read and no write.
+ *
+ * A fully-untracked sidecar is already covered by its blanket `.plumbbob/` line;
+ * layering the narrow patterns underneath would only add noise, so skip it. That
+ * check reads info/exclude rather than the cursor because a null cursor means
+ * "`--local` OR no build named" — and calling excludeSidecar on the tracked
+ * layout would untrack the whole artifact plane.
+ */
+export function refreshExcludes(root) {
+    if (hasExclude(root, `${DIRNAME}/`))
+        return;
+    excludeControl(root);
+}

package/dist/verbs/checkpoint.js

@@ -11,7 +11,7 @@
 // DESIGN boundary.
 import { appendFileSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { commit, findRepoRoot, headSha, isDirty, stageAll, stagePath, stagedPaths, stagedStat } from "../lib/git.js";
-import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, checkpointsPath, clearHandoff, clearTick, hasSession, intentPath, readStats, seamPath, stampStepStat, stepPath, } from "../lib/sidecar.js";
+import { activeBuild, buildFolder, buildLogPath, buildScope, bumpStepStat, checkpointsPath, clearHandoff, clearTick, hasSession, intentPath, readStats, refreshExcludes, seamPath, stampStepStat, stepPath, } from "../lib/sidecar.js";
 import { runCheck } from "../lib/check.js";
 import { checkLatch } from "../lib/latch.js";
 import { markStepDone, parseSteps } from "../lib/orient.js";
@@ -31,6 +31,10 @@ export async function checkpoint(cwd, args) {
         process.stderr.write('plumbbob: no active session. Run `plumbbob start "<title>"` first.\n');
         return 1;
     }
+    // Before either staging path — `-A` below, and the plan commit's folder-scoped
+    // add, which also leans on the excludes to skip the in-flight markers inside
+    // the build folder.
+    refreshExcludes(root);
     if (args.includes('--plan')) {
         return checkpointPlan(root, args);
     }

package/dist/verbs/finish.js

@@ -11,7 +11,7 @@
 import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { commit, findRepoRoot, isDirty, stageAll } from "../lib/git.js";
-import { buildScope, checkpointsPath, clearTick, hasSession, intentPath, readStats, reportPath, resolveBuild, seamPath, setGrant, sidecarDir, spikePath, stepPath, } from "../lib/sidecar.js";
+import { buildScope, checkpointsPath, clearTick, hasSession, intentPath, readStats, refreshExcludes, reportPath, resolveBuild, seamPath, setGrant, sidecarDir, spikePath, stepPath, } from "../lib/sidecar.js";
 import { conventionalSubject, withMarker } from "../lib/commitmsg.js";
 import { parseBuildScope } from "../lib/intent.js";
 /**
@@ -43,6 +43,7 @@ export function finish(cwd, args = []) {
     // commit under the `finish` subject. `--allow-empty` (via `commit`) still marks
     // the narrative endpoint when the tree is already clean, or under `--local`,
     // where the whole sidecar is git-excluded and there is nothing tracked to stage.
+    refreshExcludes(root);
     if (isDirty(root)) {
         stageAll(root);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "plumbbob",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "description": "Attention-first build process: 12 skills + a CLI that keep you the decider — guidance on the work, a latch on the record.",
   "keywords": [
     "claude-code",