@smartmemory/compose 0.3.6-beta → 0.3.8

package/lib/completion-writer.js

@@ -14,9 +14,11 @@
  *   <cwd>/.compose/data/locks/feature-<feature_code>.lock
  *   (Decision 10; mirrors acquireLock pattern from lib/idempotency.js:42).
  *
- * setFeatureStatus is lazy-imported inside the writer to avoid circular load.
- * (feature-writer.js must NOT import completion-writer.js — that would create
- *  a cycle. The lazy import here is intentional and must stay inside the function.)
+ * The completion gate is lazy-imported inside the writer to avoid circular load
+ * (gate → writer → gate). The lazy import is intentional and must stay inside
+ * the function. Since COMP-COMPLETION-GATE slice 3 this writer never flips
+ * status itself: the completing path (set_status ≠ false) delegates to the
+ * gate, and the gate calls back with set_status:false for the record write.
  *
  * No HTTP, no transport awareness.
  */
@@ -113,10 +115,16 @@ function notFoundError(code) {
   return e;
 }
 
-function statusFlipError(message, cause) {
-  const e = new Error(message);
-  e.code = 'STATUS_FLIP_AFTER_COMPLETION_RECORDED';
-  if (cause) e.cause = cause;
+function completionRefusedError(gated) {
+  const reasons = (gated.reasons || []).join('; ') || 'refused';
+  const e = new Error(
+    `completion-writer: completion of "${gated.featureCode}" refused at ${gated.refusedAt} — ${reasons}. ` +
+    `Nothing was written.`,
+  );
+  e.code = 'COMPLETION_REFUSED';
+  e.refusedAt = gated.refusedAt;
+  e.reasons = gated.reasons || [];
+  if (gated.error) e.cause = gated.error;
   return e;
 }
 
@@ -287,6 +295,34 @@ export async function recordCompletion(cwd, args) {
   // 1. Validate
   validate(args);
 
+  // COMP-COMPLETION-GATE slice 3 (AC-7, Decision 2): a completion that moves
+  // the feature goes THROUGH the gate — evidence, guarded transition, then the
+  // gate performs every write (record, status, ROADMAP, vision, events) in
+  // §2.3a order. This writer no longer flips status itself: `setFeatureStatus`
+  // refuses COMPLETE unconditionally (AC-9), and the only module authorized to
+  // raw-write COMPLETE is the gate. `set_status:false` is the record-only path
+  // the gate itself calls back into (step 1 of §2.3a) and that evidence-only
+  // callers use; it never touches status. No recursion: the gate always passes
+  // `set_status:false`.
+  if (args.set_status !== false) {
+    const { completionGate } = await import('./completion-gate.js');
+    const gated = await completionGate({
+      featureCode: args.feature_code,
+      ...(args.commit_sha === undefined || args.commit_sha === null ? {} : { commitSha: args.commit_sha }),
+      testsPass: args.tests_pass,
+      filesChanged: args.files_changed,
+      notes: args.notes,
+      force: args.force,
+      builtVia: args.built_via,
+      idempotencyKey: args.idempotency_key,
+      workspaceRoot: cwd,
+      ...(args.evidence_root ? { evidenceRoot: args.evidence_root } : {}),
+      ...(args.mode ? { mode: args.mode } : {}),
+    });
+    if (!gated.ok) throw completionRefusedError({ featureCode: args.feature_code, ...gated });
+    return gated.result;
+  }
+
   // 2. Normalize SHA (omitted/null ⇒ NULL_SHA sentinel — commit-less completion)
   const commit_sha       = (args.commit_sha === undefined || args.commit_sha === null)
     ? NULL_SHA
@@ -366,46 +402,10 @@ export async function recordCompletion(cwd, args) {
         ...(args.built_via ? { built_via: args.built_via } : {}),
       });
 
-      // 5i. Status flip (default on)
-      const set_status = args.set_status !== false;
-      let status_changed = null;
-
-      if (set_status && feature.status !== 'COMPLETE') {
-        const fromStatus = feature.status;
-        // Terminal states (KILLED, SUPERSEDED) have no valid outgoing transitions.
-        // We deliberately do NOT force for terminal states so that the transition
-        // policy enforcement fires and produces the STATUS_FLIP_AFTER_COMPLETION_RECORDED
-        // error (test #11 / Decision 4). For non-terminal states we pass force: true
-        // so that intermediate-state features (e.g. PLANNED → COMPLETE) succeed without
-        // requiring callers to manually walk through IN_PROGRESS first.
-        const TERMINAL_STATES = new Set(['KILLED', 'SUPERSEDED']);
-        const flipForce = !TERMINAL_STATES.has(fromStatus);
-        try {
-          // Lazy-import setFeatureStatus to avoid circular load
-          // (completion-writer.js must not be statically imported by feature-writer.js)
-          const { setFeatureStatus } = await import('./feature-writer.js');
-          await setFeatureStatus(cwd, {
-            code: feature_code,
-            status: 'COMPLETE',
-            commit_sha,
-            reason: 'record_completion',
-            force: flipForce,
-          });
-          status_changed = { from: fromStatus, to: 'COMPLETE' };
-        } catch (flipErr) {
-          // Both failure sub-cases (transition rejected AND ROADMAP_PARTIAL_WRITE) rethrow
-          // as STATUS_FLIP_AFTER_COMPLETION_RECORDED. The completion record IS persisted (step h).
-          throw statusFlipError(
-            flipErr.code === 'ROADMAP_PARTIAL_WRITE'
-              ? `completion-writer: completion recorded for "${feature_code}" but ROADMAP regen failed after status flip. ` +
-                `This is the ROADMAP_PARTIAL_WRITE subcase (Decision 4). ` +
-                `Recover with \`compose roadmap generate\`.`
-              : `completion-writer: completion recorded for "${feature_code}" but status flip to COMPLETE failed. ` +
-                `err.cause carries the underlying transition error.`,
-            flipErr,
-          );
-        }
-      }
+      // 5i. No status flip here. The gate owns it (§2.3a step 2) — see the
+      //     delegation at the top of this function. This branch is record-only.
+      const set_status = false;
+      const status_changed = null;
 
       // 5j. Audit event (not appended for idempotent no-ops — they return early at 5e)
       const auditEvent = {

package/lib/consumer-fanout.js

@@ -143,19 +143,80 @@ function cumulativeDiff(cwd, baseCommit) {
   });
 }
 
+/**
+ * Apply one lane's cumulative diff to a temporary index.
+ *
+ * `--3way`: every lane diffs against the SAME baseline, so once lane 1 has
+ * landed, lane 2's hunks still carry baseline context. A plain `git apply`
+ * rejects any hunk whose context line was touched by an earlier lane — even
+ * when the edits themselves do not overlap (two lanes appending tests to the
+ * same file, 2026-08-30: `patch failed: test/version-check.test.js:5`, four
+ * paid revise rounds). Three-way falls back to merging against the recorded
+ * preimage blobs (`index` lines in the diff), so only a genuine overlap fails.
+ * A genuine conflict still throws: `git apply` exits non-zero and the temporary
+ * index (with its conflict entries) is discarded by withTemporaryIndex.
+ */
+function applyDiffToIndex(cwd, diff, env) {
+  git(cwd, ['apply', '--cached', '--3way', '--binary', '-'], {
+    env,
+    input: diff,
+    timeout: 60_000,
+  });
+}
+
+/** Working tree + one lane diff, merged in a temporary index; returns the tree id. */
+function mergeDiffIntoWorkingTree(cwd, diff) {
+  return withTemporaryIndex(cwd, (env) => {
+    git(cwd, ['read-tree', 'HEAD'], { env });
+    git(cwd, ['add', '-A'], { env });
+    applyDiffToIndex(cwd, diff, env);
+    return git(cwd, ['write-tree'], { env });
+  });
+}
+
+/**
+ * Move the working tree from one snapshot tree to another WITHOUT `git clean`.
+ *
+ * A two-tree `read-tree -m -u` writes exactly the paths that differ between
+ * the trees and leaves untracked and ignored content alone. restoreWorkingTree
+ * (baseline restore) cleans first, which is right for a full reset but wrong
+ * mid-merge: a lane that edits .gitignore makes previously ignored files
+ * visible, and a clean under the new rules would delete files no snapshot ever
+ * captured (Codex review of e98ea87, 2026-08-30). The real index is untouched.
+ */
+function checkoutTreeDelta(cwd, fromTree, toTree) {
+  withTemporaryIndex(cwd, (env) => {
+    git(cwd, ['read-tree', fromTree], { env });
+    // A freshly read index has no stat data, so every entry looks modified and
+    // the two-tree merge refuses ("not uptodate"). Refresh against the working
+    // tree, which matches fromTree by the witness check that precedes this.
+    git(cwd, ['update-index', '-q', '--refresh'], { env });
+    git(cwd, ['read-tree', '-m', '-u', fromTree, toTree], { env });
+  });
+}
+
+/**
+ * Rollback variant of checkoutTreeDelta for a working tree that may be
+ * PARTIALLY written (a forward checkout that threw mid-way). `--reset -u`
+ * rewrites every path listed in fromTree or toTree to its toTree state without
+ * demanding an up-to-date worktree, and — unlike restoreWorkingTree — never
+ * runs `git clean`, so untracked and ignored content is untouched (Codex r3).
+ * fromTree must be a SUPERSET of anything the forward pass may have written.
+ */
+function rollbackTreeDelta(cwd, fromTree, toTree) {
+  withTemporaryIndex(cwd, (env) => {
+    git(cwd, ['read-tree', fromTree], { env });
+    git(cwd, ['read-tree', '--reset', '-u', toTree], { env });
+  });
+}
+
 function computeWitnessChain(cwd, orderedEntries) {
   return withTemporaryIndex(cwd, (env) => {
     git(cwd, ['read-tree', 'HEAD'], { env });
     git(cwd, ['add', '-A'], { env });
     const chain = [git(cwd, ['write-tree'], { env })];
     for (const entry of orderedEntries) {
-      if (entry.diff.length > 0) {
-        git(cwd, ['apply', '--cached', '--binary', '-'], {
-          env,
-          input: entry.diff,
-          timeout: 60_000,
-        });
-      }
+      if (entry.diff.length > 0) applyDiffToIndex(cwd, entry.diff, env);
       chain.push(git(cwd, ['write-tree'], { env }));
     }
     return chain;
@@ -808,7 +869,20 @@ export class ConsumerFanoutArtifacts {
     // evidence but owe no diff (a pure-none fanout yields zero ordered diffs).
     const worktreeAccepted = accepted.filter((entry) => entry.isolation !== 'none');
     const baselineTree = snapshotWorkingTree(this.targetCwd);
-    const orderedDiffs = worktreeAccepted.map((entry) => ({
+    // A worker that changed NOTHING owes an empty diff, not a missing one, and it
+    // must not join the merge: applying nothing leaves the tree identical, so its
+    // witness entry repeats its predecessor and the uniqueness check below fires
+    // — blocking a merge whose only fault is that one worker had nothing to do.
+    // That is the normal outcome whenever a task is fanned out more ways than it
+    // divides (observed: 2 workers on a 2-edit single-file doc change, one
+    // no-op). computeWitnessChain already skips `apply` for a zero-length diff;
+    // it just pushed a tree anyway, so the intent was there and the chain wasn't.
+    //
+    // Filtered AFTER the completeness accounting below reads `worktreeAccepted`,
+    // so a NULL diff (never captured — a real fault) still fails there. Empty and
+    // absent are different things and stay that way.
+    const mergeParticipants = worktreeAccepted.filter((entry) => (entry.diff?.length ?? 0) > 0);
+    const orderedDiffs = mergeParticipants.map((entry) => ({
       dispatchToken: entry.dispatchToken,
       scopedId: entry.scopedId,
       itemIndex: entry.itemIndex,
@@ -849,7 +923,7 @@ export class ConsumerFanoutArtifacts {
 
     let witnessChain;
     try {
-      witnessChain = computeWitnessChain(this.targetCwd, worktreeAccepted);
+      witnessChain = computeWitnessChain(this.targetCwd, mergeParticipants);
     } catch (error) {
       recordBlocked(
         'MERGE_WITNESS_PRECOMPUTE_FAILED',
@@ -983,6 +1057,8 @@ export class ConsumerFanoutArtifacts {
 
     for (let orderedIndex = prefix; orderedIndex < orderedDiffs.length; orderedIndex += 1) {
       const ordered = orderedDiffs[orderedIndex];
+      // Tree the working tree's TRACKED content currently equals (by witness).
+      let trackedTree = witnessChain[orderedIndex];
       try {
         if (typeof this.hooks.insideDiffApply === 'function') {
           await this.hooks.insideDiffApply({
@@ -1003,7 +1079,17 @@ export class ConsumerFanoutArtifacts {
         // not a lockfile in this slice.
         const live = this.#currentTransaction(gateToken);
         if (live) this.#assertMergeNotDecided(live, gateToken);
-        git(this.targetCwd, ['apply', '--binary', '-'], { input: ordered.diff, timeout: 60_000 });
+        // Same merge algorithm as the witness precompute (temporary index,
+        // three-way), then the merged tree is checked out. Applying straight to
+        // the working tree cannot use --3way (it requires the real index to match).
+        const mergedTree = mergeDiffIntoWorkingTree(this.targetCwd, ordered.diff);
+        // Mark the merged tree as written BEFORE the checkout starts: if the
+        // checkout throws part-way, the rollback still knows every path it may
+        // have touched. A rollback must transition from that tree, never from a
+        // fresh snapshot (which would reclassify newly un-ignored files as
+        // tracked and delete them on the way back to baseline — Codex r2/r3).
+        trackedTree = mergedTree;
+        checkoutTreeDelta(this.targetCwd, witnessChain[orderedIndex], mergedTree);
         const landedTree = snapshotWorkingTree(this.targetCwd);
         const expectedTree = witnessChain[orderedIndex + 1];
         if (landedTree !== expectedTree) {
@@ -1020,7 +1106,15 @@ export class ConsumerFanoutArtifacts {
         // as-is (no baseline restore / block) rather than mislabeling it as an
         // apply failure over a round another party already owns.
         if (error instanceof ConsumerMergeDecisionError) throw error;
-        restoreWorkingTree(this.targetCwd, baselineTree);
+        // Roll back by tree delta from the last tree we may have WRITTEN, never
+        // by clean and never from a fresh snapshot: the failing lane may have
+        // just un-ignored files that no snapshot holds. Reset-style so a
+        // partially written checkout rolls back too.
+        rollbackTreeDelta(this.targetCwd, trackedTree, baselineTree);
+        const restored = snapshotWorkingTree(this.targetCwd);
+        if (restored !== baselineTree) {
+          throw new Error(`consumer merge rollback verification failed: expected ${baselineTree}, got ${restored}`);
+        }
         this.#mutate(() => {
           const tx = this.journal.mergeTransactions.find((e) => e.gateToken === gateToken);
           // Never overwrite a concurrent decision, even on the error path.

package/lib/coverage-gate.js

@@ -0,0 +1,200 @@
+/**
+ * coverage-gate.js — COMP-COVERAGE-GATE slice 2.
+ *
+ * The check half of the feature. Slice 1 made the mutating surface DECLARED
+ * (`effect`/`writes` on every tool definition, derived by lib/tool-inventory.js);
+ * this module cross-checks that declaration against the two lists that are
+ * supposed to govern it — lib/canon-registry.js entries and
+ * server/mcp-tool-policy.js profile policy — and reports what neither accounts
+ * for.
+ *
+ * Pure, no I/O. Callers supply the three inputs (shape template:
+ * server/mcp-tool-policy.js).
+ *
+ * WHAT THIS ANSWERS. "Could this tool ever be enforced?" — not "was this call
+ * allowed?". It is a static check over declarations and adds NO enforcement
+ * point (design Decision 3); the runtime points (`hook`, `ship`, the MCP
+ * CallTool dispatch) are untouched, and the blast radius is validate_project's
+ * output.
+ *
+ * ADVISORY, WITH ONE HARD TIER (design Decision 2). Only MISSING_EFFECT is an
+ * error: it is unambiguous and one-line-fixable. C2–C4 encode conventions that
+ * can have legitimate exceptions, and a gate that blocks on a judgment call
+ * gets disabled.
+ *
+ * EVERY FINDING CARRIES A REMEDIATION, NOT A VERDICT (design Decision 4) — a
+ * specific instruction naming the file and the list to edit. That is the one
+ * PolicyGuide (arXiv:2608.19861 §3.3) result that transfers at zero cost:
+ * returning the required NEXT ACTION changes agent behavior where a bare
+ * allow/deny does not.
+ *
+ * HONEST LIMIT. This checks declarations, not behavior. A tool declaring
+ * `writes: []` while writing feature.json through a helper passes every check
+ * here. Closing that needs runtime write-path attribution — the `ship` point's
+ * correlation job, not this one.
+ */
+
+/**
+ * C4 exceptions — mutating tools an implementer-profile session is INTENDED to
+ * call, so their absence from IMPLEMENTER_DENY is a decision, not an omission.
+ *
+ * This list lives next to the check rather than in a doc on purpose: a doc
+ * nobody loads is how the three lists drifted in the first place (design, Open
+ * Questions). Adding a tool here is a recorded ruling and needs a reason.
+ *
+ * The bar: does an implementer doing ordinary feature work need it? Recording
+ * its own artifacts, notes and iteration state — yes. Granting itself
+ * authority, or writing the decision record — no.
+ */
+export const C4_EXCEPTIONS = {
+  scaffold_feature: 'implementer creates the feature folder templates it then fills in',
+  link_artifact: 'implementer records the artifacts it produced',
+  link_features: 'implementer records dependencies it discovered while building',
+  write_journal_entry: 'implementer progress notes — non-canon, append-only',
+  write_checkpoint: 'implementer checkpoints its own run — non-canon',
+  start_iteration_loop: 'the iteration loop is driven BY the implementer',
+  report_iteration_result: 'the iteration loop is driven BY the implementer',
+  abort_iteration_loop: 'the implementer must be able to stop its own loop',
+  add_changelog_entry: 'CHANGELOG entry ships in the same commit as the code (documentation standard)',
+
+  // The eight judgment writers. NOT an omission — COMP-JUDGMENT-WRITER
+  // design.md:137 rules that the write tools "stay implementer/orchestrator-only",
+  // with the provenance argument aimed squarely at REVIEWERS (a reviewer writing
+  // canon directly would be a second unattributed author). C4 raised all eight
+  // on its first run because the ruling lived only in prose; recording it here
+  // is the closure. Reversing it is a deliberate revisit of that design, not a
+  // coverage fix — and `test/judgment-writer-mcp.test.js` asserts the current
+  // behavior directly, so a reversal has one obvious place to start.
+  judgment_position_create: 'COMP-JUDGMENT-WRITER design.md:137 — judgment writes are implementer/orchestrator-only by design',
+  judgment_position_amend: 'COMP-JUDGMENT-WRITER design.md:137 — judgment writes are implementer/orchestrator-only by design',
+  judgment_joint_add: 'COMP-JUDGMENT-WRITER design.md:137 — judgment writes are implementer/orchestrator-only by design',
+  judgment_transition: 'COMP-JUDGMENT-WRITER design.md:137 — judgment writes are implementer/orchestrator-only by design',
+  judgment_ledger_append: 'COMP-JUDGMENT-WRITER design.md:137 — judgment writes are implementer/orchestrator-only by design',
+  judgment_person_write: 'COMP-JUDGMENT-WRITER design.md:137 — judgment writes are implementer/orchestrator-only by design',
+  judgment_situation_write: 'COMP-JUDGMENT-WRITER design.md:137 — judgment writes are implementer/orchestrator-only by design',
+  judgment_goal_write: 'COMP-JUDGMENT-WRITER design.md:137 — judgment writes are implementer/orchestrator-only by design',
+};
+
+/** Findings are reported in this order — most actionable first. */
+const CODE_RANK = ['MISSING_EFFECT', 'UNGATED_MUTATION', 'ORPHAN_REGISTRY_TOOL', 'UNCOVERED_WRITE'];
+
+/**
+ * @param {object} args
+ * @param {{read:string[], mutating:string[], setup:string[],
+ *          undeclared:Array<{name:string,reason:string}>,
+ *          writesByTool:Record<string,string[]>}} args.inventory
+ *   — lib/tool-inventory.js loadToolInventory() result.
+ * @param {Array<{id:string, display?:string, tools:string[]}>} args.registry
+ *   — lib/canon-registry.js canonEntries().
+ * @param {{PROFILE_POLICY:object, PHASE_REFINEMENT?:object}} args.policy
+ *   — server/mcp-tool-policy.js.
+ * @returns {{ findings: Array<{code:string, tool:string, path?:string,
+ *             severity:'error'|'warning'|'info', remediation:string}> }}
+ */
+export function checkAuthorizationCoverage({ inventory, registry, policy } = {}) {
+  const findings = [];
+
+  const inv = inventory || {};
+  const undeclared = Array.isArray(inv.undeclared) ? inv.undeclared : [];
+  const mutating = Array.isArray(inv.mutating) ? inv.mutating : [];
+  const writesByTool = inv.writesByTool || {};
+  const entries = Array.isArray(registry) ? registry : [];
+
+  // Every name the inventory has SEEN, declared or not — an undeclared tool
+  // still exists, so it must not also be reported as an orphan (C3).
+  const known = new Set([
+    ...(inv.read || []), ...mutating, ...(inv.setup || []),
+    ...undeclared.map((u) => u.name),
+  ]);
+
+  // ── C1 MISSING_EFFECT (hard) ───────────────────────────────────────────────
+  // Fail-closed on the declaration. This is the only check that can fail a
+  // validate run, because the fix is a single field with no judgment in it.
+  for (const { name, reason } of undeclared) {
+    findings.push({
+      code: 'MISSING_EFFECT',
+      tool: name,
+      severity: 'error',
+      remediation: `add \`effect: 'read' | 'mutating' | 'setup'\` to the '${name}' definition in server/mcp-tool-defs.js (${reason}); a mutating tool also needs \`writes: []\``,
+    });
+  }
+
+  // ── C4 UNGATED_MUTATION (the headline) ─────────────────────────────────────
+  // PROFILE_POLICY is the only one of the three lists that is actually
+  // ENFORCED — at the server/compose-mcp.js CallTool dispatch. A mutating tool
+  // named by none of its lists is callable by an implementer-profile session
+  // and nothing anywhere records whether that was intended.
+  const profilePolicy = (policy && policy.PROFILE_POLICY) || {};
+  const denyTools = _toolSet(profilePolicy.implementer);
+  const allowTools = _toolSet(profilePolicy.reviewer);
+  const refinementTools = new Set();
+  for (const set of Object.values((policy && policy.PHASE_REFINEMENT) || {})) {
+    for (const t of _iter(set)) refinementTools.add(t);
+  }
+
+  for (const tool of mutating) {
+    if (Object.prototype.hasOwnProperty.call(C4_EXCEPTIONS, tool)) continue;
+    if (denyTools.has(tool) || refinementTools.has(tool) || allowTools.has(tool)) continue;
+    findings.push({
+      code: 'UNGATED_MUTATION',
+      tool,
+      severity: 'warning',
+      remediation: `'${tool}' mutates state but is named by no profile list — add it to IMPLEMENTER_DENY in server/mcp-tool-policy.js, or record why an implementer may call it in C4_EXCEPTIONS (lib/coverage-gate.js)`,
+    });
+  }
+
+  // ── C3 ORPHAN_REGISTRY_TOOL ────────────────────────────────────────────────
+  // Reverse drift: the registry names a tool that no longer exists. Catches
+  // renames, which are otherwise silent — a renamed tool leaves its old name
+  // in a deny message that will never match anything again.
+  for (const entry of entries) {
+    for (const tool of entry.tools || []) {
+      if (known.has(tool)) continue;
+      findings.push({
+        code: 'ORPHAN_REGISTRY_TOOL',
+        tool,
+        path: entry.id,
+        severity: 'warning',
+        remediation: `canon entry '${entry.id}' names tool '${tool}', which is not in the tool inventory — remove it from lib/canon-registry.js, or restore the tool definition in server/mcp-tool-defs.js if it was renamed`,
+      });
+    }
+  }
+
+  // ── C2 UNCOVERED_WRITE (minor) ─────────────────────────────────────────────
+  // `entry.tools` has exactly ONE consumer — lib/canon-guard.js joins it into
+  // the deny message ("use one of these tools instead"). It is never an
+  // allow/deny input. So this keeps the REMEDIATION MESSAGE honest; it does not
+  // close a hole. Ranked last for that reason.
+  const entryById = new Map(entries.map((e) => [e.id, e]));
+  for (const tool of mutating) {
+    for (const canonId of writesByTool[tool] || []) {
+      const entry = entryById.get(canonId);
+      if (!entry) continue; // an unknown canon id is tool-inventory's `undeclared` job
+      if ((entry.tools || []).includes(tool)) continue;
+      findings.push({
+        code: 'UNCOVERED_WRITE',
+        tool,
+        path: canonId,
+        severity: 'info',
+        remediation: `'${tool}' declares it writes '${entry.display || canonId}' but is absent from that entry's tool list — add it in lib/canon-registry.js so a denied raw edit is offered it as an alternative`,
+      });
+    }
+  }
+
+  findings.sort((a, b) => {
+    const r = CODE_RANK.indexOf(a.code) - CODE_RANK.indexOf(b.code);
+    return r !== 0 ? r : a.tool.localeCompare(b.tool);
+  });
+  return { findings };
+}
+
+/** PROFILE_POLICY entries carry `tools` as a Set; tolerate an array or absence. */
+function _toolSet(profile) {
+  return new Set(_iter(profile && profile.tools));
+}
+
+function _iter(v) {
+  if (v instanceof Set) return v;
+  if (Array.isArray(v)) return v;
+  return [];
+}

package/lib/dir-lock.js

@@ -0,0 +1,170 @@
+/**
+ * lib/dir-lock.js — the one advisory lock, extracted.
+ *
+ * COMP-PLAN-IDEA-UNIFY S3b-1 (D17).
+ *
+ * `mkdir` is the primitive: it is atomic on every filesystem this runs on, and
+ * it fails with EEXIST rather than clobbering. Everything below exists to make
+ * that primitive survive the cases a bare `mkdirSync` does not.
+ *
+ * There were six independent copy-pasted versions of this in `lib/` when this
+ * module was written, and they did NOT agree — the weakest set its stale
+ * threshold equal to its acquire timeout, which makes ordinary contention
+ * indistinguishable from a crashed holder, so a busy lock gets stolen from a
+ * live owner. This is the hardened shape (from `lib/judgment-writer.js`),
+ * lifted so there is one implementation to reason about instead of six.
+ *
+ * The four things that are not obvious:
+ *
+ *  1. **An owner token inside the dir.** Without it, release cannot tell "my
+ *     lock" from "the lock that replaced mine after it was declared stale", so
+ *     a slow holder deletes the new owner's lock on the way out. This is the
+ *     ABA case and it is the reason release reads before it removes.
+ *
+ *  2. **A partial acquisition is undone.** If the dir is created but the token
+ *     write fails, every later release declines to remove a lock it cannot
+ *     prove is its own — stranding it until the stale window expires. So that
+ *     window is closed by hand rather than waited out.
+ *
+ *  3. **A heartbeat, and why the threshold is high.** The holder touches the
+ *     dir's mtime on a timer so a long-but-live operation is not mistaken for a
+ *     dead one. The timer runs on the event loop, so a SYNCHRONOUS block longer
+ *     than the stale threshold defeats it. 20s is set well above any sync
+ *     section this codebase produces (small-file fs I/O; long work is async).
+ *
+ *  4. **Stale reclaim is by mtime, not by pid.** A pid check cannot see across
+ *     containers or a reused pid, and this lock guards files that two clones
+ *     can reach.
+ *
+ * The lock is advisory: it coordinates writers that agree to use it. Nothing
+ * stops a writer that does not, which is why tool-owned canon also has the
+ * guard layer.
+ */
+
+import {
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  utimesSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+
+/** A holder is presumed dead once its mtime is this old. See note 3. */
+const LOCK_STALE_MS = 20000;
+/** How long to keep trying before giving up on a live holder. */
+const LOCK_ACQUIRE_TIMEOUT_MS = 30000;
+/** Keeps a live holder from being declared stale. */
+const LOCK_HEARTBEAT_MS = 1000;
+/** Poll interval while waiting on a holder. */
+const LOCK_RETRY_MS = 25;
+
+/** The holder's token, or null if it cannot be read (racing, or never written). */
+function readOwner(ownerFile) {
+  try { return readFileSync(ownerFile, 'utf8'); } catch { return null; }
+}
+
+export class DirLockTimeout extends Error {
+  constructor(path, ms) {
+    super(`dir-lock: timed out after ${ms}ms waiting for ${path}`);
+    this.name = 'DirLockTimeout';
+    this.code = 'DIR_LOCK_TIMEOUT';
+    this.path = path;
+  }
+}
+
+/**
+ * Acquire the lock at `path`, returning a release function.
+ *
+ * @param {string} path directory to create as the lock
+ * @returns {Promise<() => void>} release — idempotent, and a no-op if the lock
+ *   is no longer provably ours
+ */
+export async function acquireDirLock(path, { timeoutMs = LOCK_ACQUIRE_TIMEOUT_MS } = {}) {
+  const ownerFile = join(path, 'owner');
+  mkdirSync(dirname(path), { recursive: true });
+  const token = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  const start = Date.now();
+
+  for (;;) {
+    try {
+      mkdirSync(path);
+      try {
+        writeFileSync(ownerFile, token);
+      } catch (err) {
+        // Note 2: undo our own partial acquisition rather than strand the lock.
+        rmSync(path, { recursive: true, force: true });
+        throw err;
+      }
+      const heartbeat = setInterval(() => {
+        try {
+          utimesSync(path, new Date(), new Date());
+        } catch { /* stolen or gone — release will no-op */ }
+      }, LOCK_HEARTBEAT_MS);
+      heartbeat.unref?.();
+
+      let released = false;
+      return () => {
+        if (released) return;
+        released = true;
+        clearInterval(heartbeat);
+        try {
+          // Note 1: only remove a lock still provably ours.
+          if (readFileSync(ownerFile, 'utf8') === token) {
+            rmSync(path, { recursive: true, force: true });
+          }
+        } catch { /* not ours anymore — leave it */ }
+      };
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      try {
+        const { mtimeMs } = statSync(path);
+        if (Date.now() - mtimeMs > LOCK_STALE_MS) {
+          // Reclaim is compare-and-delete, not blind delete. Two contenders can
+          // both stat the same stale lock and both decide to remove it; if the
+          // first then acquires a fresh one, a blind `rmSync` from the second
+          // deletes the NEW owner's lock and both proceed into the critical
+          // section. That is the ABA case on the acquire side — the release side
+          // already guarded against it, and this side did not.
+          //
+          // Re-reading the owner token and removing only if it still matches
+          // what we saw when we judged it stale closes the window: the winner
+          // rewrote the token, so the loser's compare fails and it retries.
+          const staleOwner = readOwner(ownerFile);
+          const { mtimeMs: recheck } = statSync(path);
+          if (recheck === mtimeMs && readOwner(ownerFile) === staleOwner) {
+            rmSync(path, { recursive: true, force: true });
+          }
+          continue;
+        }
+      } catch { /* stat raced the holder's release; loop and retry */ }
+      if (Date.now() - start > timeoutMs) {
+        throw new DirLockTimeout(path, timeoutMs);
+      }
+      await new Promise((r) => setTimeout(r, LOCK_RETRY_MS));
+    }
+  }
+}
+
+/**
+ * Run `fn` holding the lock at `path`. The lock is always released, including
+ * when `fn` throws.
+ *
+ * Not reentrant: calling this for the same path from inside `fn` deadlocks
+ * until the acquire timeout. Callers compose by locking once at the outermost
+ * mutating boundary.
+ *
+ * @template T
+ * @param {string} path
+ * @param {() => Promise<T>|T} fn
+ * @returns {Promise<T>}
+ */
+export async function withDirLock(path, fn) {
+  const release = await acquireDirLock(path);
+  try {
+    return await fn();
+  } finally {
+    release();
+  }
+}