bearings 0.5.2 → 0.5.4

package/dist/{update-4DZKUPFP.js → update-YY5SLPDF.js}

@@ -1,22 +1,35 @@
 #!/usr/bin/env node
 import {
   ADAPTER_KINDS,
+  PLACEHOLDER,
   SCAFFOLD,
+  applyUpdate,
   canonicalAdapterEntries,
   entriesMatch,
   freeBackupPath,
+  isChecklistPayload,
   isStarterSkillTarget,
   migrateV1,
+  normalizeSetup,
+  pendingSetupReport,
+  protectSkills,
+  reconciliationTasks,
   renderUpdatePlan,
   renderUpdateReport,
+  saveManifest,
+  setupArtifacts,
   sha256,
   skillBaselinePath,
   skillIncomingPath,
   starterSkillNameFromTarget,
+  tailoringTask,
   templatesDir,
-  validateHarnesses,
-  writeBackup
-} from "./chunk-WYXKSCUW.js";
+  uniqueSetupTasks,
+  validateHarnesses
+} from "./chunk-MOZJECCW.js";
+
+// src/commands/update.ts
+import { isDeepStrictEqual } from "util";
 
 // src/semver.ts
 function parseSemver(value) {
@@ -68,7 +81,7 @@ function compareSemver(left, right) {
 // src/update/planner.ts
 import { access, readFile } from "fs/promises";
 import { join } from "path";
-var SETUP_COMMAND_PATH = ".agents/commands/setup-repo.md";
+var SETUP_COMMAND_PATH = ".agents/commands/update-bearings-setup.md";
 async function exists(path) {
   try {
     await access(path);
@@ -104,6 +117,18 @@ async function planFiles(input) {
     const templateContent = await readFile(join(source.templatesDir, entry.template), "utf8");
     const incomingHash = sha256(templateContent);
     const prevRecord = previous?.files.find((file) => file.path === entry.target);
+    if (!prevRecord && reconstruction && currentExists && entry.target.startsWith(".agents/skills/") && currentHash !== incomingHash) {
+      actions.push({ kind: "keep", record: {
+        path: entry.target,
+        template: entry.template,
+        templateVersion: source.bearingsVersion,
+        hash: isStarterSkillTarget(entry.target) ? currentHash : incomingHash,
+        owner: entry.owner,
+        ...isStarterSkillTarget(entry.target) ? { lastTemplateHash: incomingHash } : {},
+        skippedTemplate: { templateVersion: source.bearingsVersion, hash: incomingHash }
+      } });
+      continue;
+    }
     if (isStarterSkillTarget(entry.target)) {
       const prevOwner = prevRecord?.owner ?? entry.owner;
       const lastTemplateHash = prevRecord?.lastTemplateHash ?? prevRecord?.hash;
@@ -113,7 +138,8 @@ async function planFiles(input) {
         templateVersion: source.bearingsVersion,
         hash: incomingHash,
         owner: prevOwner === "agent" ? "agent" : entry.owner,
-        lastTemplateHash: incomingHash
+        lastTemplateHash: incomingHash,
+        ...prevRecord?.reconciliations ? { reconciliations: prevRecord.reconciliations } : {}
       };
       if (!currentExists) {
         actions.push({
@@ -146,16 +172,13 @@ async function planFiles(input) {
         actions.push({ kind: "keep", record: prevRecord });
         continue;
       }
-      if (currentHash === prevRecord.hash) {
+      if (currentHash === lastTemplateHash) {
         actions.push({
           kind: "write",
           reason: "replace",
           path: entry.target,
           content: templateContent,
-          record: {
-            ...incomingRecordBase,
-            ...prevRecord.reconciliations ? { reconciliations: prevRecord.reconciliations } : {}
-          }
+          record: incomingRecordBase
         });
         continue;
       }
@@ -182,7 +205,8 @@ async function planFiles(input) {
       template: entry.template,
       templateVersion: source.bearingsVersion,
       hash: incomingHash,
-      owner: entry.owner
+      owner: entry.owner,
+      ...prevRecord?.reconciliations ? { reconciliations: prevRecord.reconciliations } : {}
     };
     const canSkip = entry.target !== SETUP_COMMAND_PATH;
     if (!currentExists) {
@@ -325,7 +349,6 @@ async function resolveFilePlan(repoDir, draft, decisions) {
   }
   const actions = [];
   const files = [];
-  let setupRequired = draft.reconstruction;
   for (const action of draft.actions) {
     if (action.kind === "keep") {
       actions.push(action);
@@ -335,19 +358,16 @@ async function resolveFilePlan(repoDir, draft, decisions) {
     if (action.kind === "write") {
       actions.push(action);
       files.push(action.record);
-      setupRequired = true;
       continue;
     }
     if (action.kind === "delete") {
       actions.push(action);
-      setupRequired = true;
       continue;
     }
     if (action.kind === "untrack-missing") {
       actions.push(action);
       if (action.previous.reconciliations?.length) {
         files.push({ ...action.previous, retired: true });
-        setupRequired = true;
       }
       continue;
     }
@@ -375,7 +395,6 @@ async function resolveFilePlan(repoDir, draft, decisions) {
       };
       actions.push({ kind: "skill-handoff", path: action.path, content: action.content, backup, basePath, incomingPath, record: record2 });
       files.push(record2);
-      setupRequired = true;
       continue;
     }
     if (action.kind === "conflict") {
@@ -391,7 +410,6 @@ async function resolveFilePlan(repoDir, draft, decisions) {
         actions.push(resolved2);
         if (record2) files.push(record2);
       }
-      setupRequired = true;
       continue;
     }
     const decision = decisionsByPath.get(action.path);
@@ -400,13 +418,27 @@ async function resolveFilePlan(repoDir, draft, decisions) {
     const { resolved, record } = resolveRemovedConflict(action, decision);
     actions.push(resolved);
     if (record) files.push(record);
-    setupRequired = true;
   }
   if (decisionsByPath.size > 0) {
     const [leftoverPath] = decisionsByPath.keys();
     fail(`Unexpected decision for path: ${leftoverPath}`);
   }
-  return { actions, files, setupRequired };
+  const tasks = uniqueSetupTasks([
+    ...actions.flatMap((action) => {
+      if (action.kind !== "write" && action.kind !== "merge") return [];
+      const task = tailoringTask(action.record, action.content);
+      return task ? [task] : [];
+    }),
+    ...reconciliationTasks({ files })
+  ]);
+  if (draft.reconstruction) {
+    for (const action of actions) {
+      if (action.kind !== "keep") continue;
+      const task = tailoringTask(action.record, await readFile(join(repoDir, action.record.path), "utf8"));
+      if (task && PLACEHOLDER.test(await readFile(join(repoDir, action.record.path), "utf8"))) tasks.push(task);
+    }
+  }
+  return { actions, files, tasks: uniqueSetupTasks(tasks), setupRequired: tasks.length > 0 };
 }
 
 // src/update/adapter-plan.ts
@@ -514,7 +546,7 @@ async function preflightAdapters(repoDir, manifest) {
       }
       if (!adapterStat.isDirectory()) driftError(adapterRel);
       const expected = filesUnderRoot(manifest.files, kind, name);
-      const actualRelFiles = await listFilesRecursive(adapterAbs);
+      const actualRelFiles = (await listFilesRecursive(adapterAbs)).filter((path) => !isChecklistPayload(`.agents/${kind}/${name}/${path}`));
       if (actualRelFiles.length !== expected.length) driftError(adapterRel);
       for (const relFile of actualRelFiles) {
         const record = expected.find((file) => file.path === `.agents/${kind}/${name}/${relFile}`);
@@ -536,12 +568,16 @@ async function preflightAdapterCollisions(input) {
   const currentHarnessSet = new Set(currentHarnesses);
   for (const harness of desiredHarnesses) {
     for (const root of candidateRoots) {
-      if (currentHarnessSet.has(harness) && previousRootKeys.has(root)) continue;
       const [kind, name] = splitRoot(root);
       const adapterRel = join2(`.${harness}`, kind, name);
-      if (await lstat(join2(repoDir, adapterRel)).catch(() => null)) {
-        throw new Error(`Adapter collision: ${adapterRel} already exists and is not managed by bearings`);
+      const adapterAbs = join2(repoDir, adapterRel);
+      const existing = await lstat(adapterAbs).catch(() => null);
+      if (!existing) continue;
+      if (currentHarnessSet.has(harness) && previousRootKeys.has(root)) {
+        const matches = existing.isSymbolicLink() ? await readlink(adapterAbs) === join2("..", "..", ".agents", kind, name) : await entriesMatch(join2(repoDir, ".agents", kind, name), adapterAbs);
+        if (matches) continue;
       }
+      throw new Error(`Adapter collision: ${adapterRel} already exists and is not managed by bearings`);
     }
   }
 }
@@ -618,191 +654,9 @@ async function planAdapterActions(input) {
   return actions;
 }
 
-// src/update/transaction.ts
-import { randomUUID } from "crypto";
-import { cp, lstat as lstat2, mkdir, readFile as readFile3, readdir as readdir2, rename, rm, rmdir, symlink, writeFile } from "fs/promises";
-import { dirname, join as join3, relative, sep } from "path";
-var MANIFEST_RELATIVE = join3(".agents", "bearings.json");
-async function capture(repoDir, txDir, relativePath, snapshots) {
-  const target = join3(repoDir, relativePath);
-  const stat = await lstat2(target).catch(() => null);
-  if (!stat) {
-    snapshots.push({ target });
-    return;
-  }
-  const stored = join3(txDir, "snapshots", String(snapshots.length));
-  await mkdir(dirname(stored), { recursive: true });
-  await rename(target, stored);
-  snapshots.push({ target, stored });
-}
-async function captureToBackup(repoDir, txDir, relativePath, backupRelativePath, snapshots) {
-  await capture(repoDir, txDir, relativePath, snapshots);
-  const sourceSnapshot = snapshots.at(-1);
-  if (!sourceSnapshot?.stored) throw new Error(`Cannot back up missing path: ${relativePath}`);
-  await writeBackup(repoDir, relativePath, await readFile3(sourceSnapshot.stored), { path: backupRelativePath });
-  snapshots.push({ target: join3(repoDir, backupRelativePath) });
-}
-async function ensureDir(repoDir, absDir, createdDirs) {
-  const rel = relative(repoDir, absDir);
-  if (!rel || rel.startsWith("..")) return;
-  let current = repoDir;
-  for (const part of rel.split(sep)) {
-    current = join3(current, part);
-    const stat = await lstat2(current).catch(() => null);
-    if (!stat) {
-      await mkdir(current);
-      createdDirs.push(current);
-    }
-  }
-}
-async function writeContent(repoDir, txDir, relativePath, content, snapshots, createdDirs) {
-  await capture(repoDir, txDir, relativePath, snapshots);
-  const target = join3(repoDir, relativePath);
-  await ensureDir(repoDir, dirname(target), createdDirs);
-  await writeFile(target, content);
-}
-async function restore(snapshots, hooks, txDir) {
-  for (const snapshot of [...snapshots].reverse()) {
-    try {
-      await hooks.beforeRollbackRestore?.(snapshot.target);
-      await rm(snapshot.target, { recursive: true, force: true });
-      if (snapshot.stored) {
-        await mkdir(dirname(snapshot.target), { recursive: true });
-        await rename(snapshot.stored, snapshot.target);
-      }
-    } catch (error) {
-      throw new Error(
-        `Rollback failed while restoring ${snapshot.target}; transaction data retained at ${txDir}. Underlying error: ${error.message}`
-      );
-    }
-  }
-}
-async function removeEmptyDirs(createdDirs) {
-  for (const dir of [...createdDirs].reverse()) {
-    try {
-      const entries = await readdir2(dir);
-      if (entries.length === 0) await rmdir(dir);
-    } catch {
-    }
-  }
-}
-async function removeEmptyCanonicalParents(repoDir, paths) {
-  const skillsRoot = join3(repoDir, ".agents", "skills");
-  const candidates = /* @__PURE__ */ new Set();
-  for (const path of paths) {
-    let current = dirname(join3(repoDir, path));
-    while (current.startsWith(`${skillsRoot}${sep}`)) {
-      candidates.add(current);
-      current = dirname(current);
-    }
-  }
-  for (const dir of [...candidates].sort((a, b) => b.length - a.length)) {
-    try {
-      await rmdir(dir);
-    } catch (error) {
-      const code = error.code;
-      if (code !== "ENOENT" && code !== "ENOTEMPTY") throw error;
-    }
-  }
-}
-async function applyUpdate(repoDir, plan, hooks = {}) {
-  const txDir = join3(repoDir, ".agents", `.bearings-txn-${randomUUID()}`);
-  const snapshots = [];
-  const createdDirs = [];
-  const abs = (relativePath) => join3(repoDir, relativePath);
-  let opIndex = 0;
-  const afterOp = async () => {
-    const current = opIndex;
-    opIndex += 1;
-    await hooks.afterOperation?.(current);
-  };
-  try {
-    for (const action of plan.files) {
-      if (action.kind === "write") {
-        await writeContent(repoDir, txDir, action.path, action.content, snapshots, createdDirs);
-        if (isStarterSkillTarget(action.path)) {
-          await writeContent(
-            repoDir,
-            txDir,
-            skillBaselinePath(starterSkillNameFromTarget(action.path)),
-            action.content,
-            snapshots,
-            createdDirs
-          );
-        }
-        await afterOp();
-      } else if (action.kind === "merge") {
-        await captureToBackup(repoDir, txDir, action.path, action.backup, snapshots);
-        await writeFile(abs(action.path), action.content);
-        await afterOp();
-      } else if (action.kind === "skill-handoff") {
-        await writeBackup(repoDir, action.path, await readFile3(abs(action.path)), { path: action.backup });
-        snapshots.push({ target: abs(action.backup) });
-        await writeContent(repoDir, txDir, action.incomingPath, action.content, snapshots, createdDirs);
-        await afterOp();
-      } else if (action.kind === "delete") {
-        await capture(repoDir, txDir, action.path, snapshots);
-        await afterOp();
-      }
-    }
-    await removeEmptyCanonicalParents(
-      repoDir,
-      plan.files.filter((action) => action.kind === "delete").map((action) => action.path)
-    );
-    for (const action of plan.migrations ?? []) {
-      if (action.kind === "migrate-testplan") {
-        if (action.backup) await captureToBackup(repoDir, txDir, action.target, action.backup, snapshots);
-        else await capture(repoDir, txDir, action.target, snapshots);
-        await capture(repoDir, txDir, action.source, snapshots);
-        await ensureDir(repoDir, dirname(abs(action.target)), createdDirs);
-        await writeFile(abs(action.target), action.content);
-        await afterOp();
-      } else if (action.kind === "preserve-invalid-testplan") {
-        await captureToBackup(repoDir, txDir, action.source, action.backup, snapshots);
-        await afterOp();
-      } else {
-        const entries = await readdir2(abs(action.path));
-        if (entries.length === 0) await capture(repoDir, txDir, action.path, snapshots);
-        await afterOp();
-      }
-    }
-    for (const action of plan.adapters) {
-      if (action.kind === "write-symlink") {
-        await capture(repoDir, txDir, action.path, snapshots);
-        await ensureDir(repoDir, dirname(abs(action.path)), createdDirs);
-        await symlink(action.target, abs(action.path));
-        await afterOp();
-      } else if (action.kind === "write-copy") {
-        await capture(repoDir, txDir, action.path, snapshots);
-        await ensureDir(repoDir, dirname(abs(action.path)), createdDirs);
-        await cp(action.source, abs(action.path), { recursive: true });
-        await afterOp();
-      } else {
-        await capture(repoDir, txDir, action.path, snapshots);
-        await afterOp();
-      }
-    }
-    await capture(repoDir, txDir, MANIFEST_RELATIVE, snapshots);
-    await ensureDir(repoDir, dirname(abs(MANIFEST_RELATIVE)), createdDirs);
-    await writeFile(abs(MANIFEST_RELATIVE), JSON.stringify(plan.manifest, null, 2) + "\n");
-    await afterOp();
-  } catch (error) {
-    await restore(snapshots, hooks, txDir);
-    await removeEmptyDirs(createdDirs);
-    await rm(txDir, { recursive: true, force: true }).catch(() => {
-    });
-    throw error;
-  }
-  try {
-    await hooks.beforeCleanup?.();
-    await rm(txDir, { recursive: true, force: true });
-  } catch {
-  }
-}
-
 // src/update/testplan-migration.ts
-import { access as access2, readFile as readFile4, readdir as readdir3 } from "fs/promises";
-import { join as join4 } from "path";
+import { access as access2, readFile as readFile3, readdir as readdir2 } from "fs/promises";
+import { join as join3 } from "path";
 var LEGACY_NAME = /^(.+)\.testplan\.json$/;
 var SCOPE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 async function exists2(path) {
@@ -887,8 +741,8 @@ function convertLegacyPlan(plan) {
   return JSON.stringify(checklist, null, 2) + "\n";
 }
 async function planTestplanMigrations(repoDir) {
-  const dir = join4(repoDir, "testplans");
-  const entries = await readdir3(dir, { withFileTypes: true }).catch((error) => {
+  const dir = join3(repoDir, "testplans");
+  const entries = await readdir2(dir, { withFileTypes: true }).catch((error) => {
     if (error.code === "ENOENT") return null;
     throw error;
   });
@@ -902,7 +756,7 @@ async function planTestplanMigrations(repoDir) {
     const source = `testplans/${entry.name}`;
     const slug = match[1];
     const target = SCOPE.test(slug) ? `checklists/tests/${slug}.json` : void 0;
-    const raw = await readFile4(join4(repoDir, source), "utf8");
+    const raw = await readFile3(join3(repoDir, source), "utf8");
     let parsed;
     try {
       parsed = JSON.parse(raw);
@@ -922,9 +776,9 @@ async function planTestplanMigrations(repoDir) {
       continue;
     }
     const content = convertLegacyPlan(parsed);
-    if (await exists2(join4(repoDir, target))) {
+    if (await exists2(join3(repoDir, target))) {
       const backup = await freeBackupPath(repoDir, target);
-      const collided = await readFile4(join4(repoDir, target), "utf8");
+      const collided = await readFile3(join3(repoDir, target), "utf8");
       actions.push({ kind: "migrate-testplan", source, target, content, backup });
       reconciliations.push({
         kind: "testplan-collision",
@@ -953,7 +807,7 @@ function cancelUpdate(p) {
 async function chooseConflict(p, action) {
   const options = [
     { value: "replace", label: "Replace", hint: "discard current content" },
-    { value: "merge", label: "Merge", hint: "back up current content for /setup-repo" },
+    { value: "merge", label: "Merge", hint: "back up current content for /update-bearings-setup" },
     ...action.canSkip ? [{ value: "skip", label: "Skip", hint: "decline this template revision" }] : []
   ];
   const selected = await p.select({
@@ -1010,14 +864,21 @@ async function confirmUpdatePlan(p, message) {
 
 // src/commands/update.ts
 async function runUpdate(repoDir, flags, version, state) {
+  let normalizationChanged = false;
+  if (state.kind === "valid" && state.manifest.version === 2) {
+    const normalized = await normalizeSetup(repoDir, state.manifest);
+    normalizationChanged = !isDeepStrictEqual(normalized, state.manifest);
+    state = { kind: "valid", manifest: normalized };
+    if (normalized.setupPending) {
+      if (normalizationChanged) await saveManifest(repoDir, normalized);
+      return { manifest: normalized, report: pendingSetupReport(normalized) };
+    }
+  }
   if (!process.stdin.isTTY) {
     throw new Error("Updating an initialized repository requires an interactive terminal.");
   }
   const migratedFromV1 = state.kind === "valid" && state.manifest.version === 1;
   const current = state.kind === "valid" ? migratedFromV1 ? await migrateV1(repoDir, state.manifest) : state.manifest : null;
-  if (!migratedFromV1 && (current?.setupPending || current?.migrationReconciliations?.length || current?.files.some((file) => file.reconciliations?.length))) {
-    throw new Error("Finish the pending /setup-repo handoff before running bearings init again.");
-  }
   if (current && compareSemver(version, current.bearingsVersion) < 0) {
     throw new Error(`Refusing to downgrade bearings from ${current.bearingsVersion} to ${version}.`);
   }
@@ -1068,11 +929,11 @@ async function runUpdate(repoDir, flags, version, state) {
   const exposureUnchanged = current ? current.exposure === exposure : false;
   const noArtifactChanges = resolved.actions.every((a) => a.kind === "keep") && migrationPlan.actions.length === 0 && adapterActions.length === 0;
   const versionUnchanged = !!current && version === current.bearingsVersion;
-  if (!reconstruction && !migratedFromV1 && noArtifactChanges && versionUnchanged && harnessesUnchanged && exposureUnchanged) {
+  if (!reconstruction && !migratedFromV1 && !normalizationChanged && noArtifactChanges && versionUnchanged && harnessesUnchanged && exposureUnchanged) {
     return { manifest: current, report: "bearings init: already up to date." };
   }
-  const migratedAbsorbedBackup = migratedFromV1 && (current?.files.some((file) => file.reconciliations?.length) ?? false);
-  const setupRequired = resolved.setupRequired || migrationPlan.actions.length > 0 || adapterActions.length > 0 || migratedAbsorbedBackup;
+  const tasks = uniqueSetupTasks([...resolved.tasks, ...reconciliationTasks({ files: [...resolved.files], migrationReconciliations: [...migrationPlan.reconciliations] })]);
+  const setupRequired = tasks.length > 0;
   const finalManifest = {
     version: 2,
     bearingsVersion: version,
@@ -1082,7 +943,9 @@ async function runUpdate(repoDir, flags, version, state) {
       setupPending: {
         kind: reconstruction ? "reconstruction" : "update",
         ...current ? { fromVersion: current.bearingsVersion } : {},
-        toVersion: version
+        toVersion: version,
+        tasks,
+        protectedSkills: await protectSkills(repoDir, tasks, resolved.actions, setupArtifacts({ files: [...resolved.files], migrationReconciliations: [...migrationPlan.reconciliations] }))
       }
     } : {},
     ...migrationPlan.reconciliations.length > 0 ? { migrationReconciliations: [...migrationPlan.reconciliations] } : {},
@@ -1105,7 +968,7 @@ async function runUpdate(repoDir, flags, version, state) {
     adapters: adapterActions,
     manifest: finalManifest
   });
-  return { manifest: finalManifest, report: renderUpdateReport({ ...summaryInput, setupRequired }) };
+  return { manifest: finalManifest, report: renderUpdateReport({ ...summaryInput, setupRequired, manifest: finalManifest }) };
 }
 export {
   runUpdate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bearings",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Give your AI agents their bearings — scaffold an agent-friendly setup in any repository.",
   "type": "module",
   "engines": {

package/templates/AGENTS.md

@@ -1,9 +1,5 @@
 # <agent: project name> - Agent Seed
 
-## Setup Required
-
-Until this section is removed, do not inspect, modify, or run anything in this repository except `/setup-repo`. For every other request, respond only: Run `/setup-repo` to finalize bearings, then retry your request.
-
 ## Project
 
 <agent: fill during handoff — One sentence: problem, primary users, and outcome.>
@@ -22,4 +18,4 @@ Primary stack: <agent: fill during handoff — language/runtime/framework/platfo
 
 ## User-Facing Output
 
-Assume the user has ADHD and cannot comprehend long descriptions. Tailor all your responses to the user's reading ability.
+The user has ADHD and cannot comprehend long descriptions. Tailor all your responses to the user's reading ability.

package/templates/agents/commands/refresh-repo-map.md

@@ -1,5 +1,5 @@
 ---
-description: Reconcile the domain, architecture, current codebase map, and C4 component source when meaningful repository drift or staleness is detected
+description: Reconcile repository maps and C4 component source after meaningful drift, or only explicit map targets supplied by bearings setup
 ---
 
 # /refresh-repo-map
@@ -25,8 +25,25 @@ when the maps remain accurate.
 | `docs/CODEBASE_MAP.md` | this command |
 | `docs/diagrams/c4-component.puml` | this command |
 
-Always create `docs/diagrams/` and `c4-component.puml` when absent. Maintain
-source-only PlantUML: never render it and never modify another diagram.
+## Target Scope
+
+Ordinary developer-invoked refresh covers all four owned artifacts. In that
+mode, create `docs/diagrams/` and `c4-component.puml` when absent.
+
+Setup callers must supply an explicit list of target paths from their pending
+`reason: map` tasks. Select only those paths from the ownership table. An empty
+setup list means no refresh; a missing or inconsistent setup scope is a blocker,
+not a request for the ordinary full set. One map task selects one artifact.
+
+Read related repository evidence as needed, but edit or create only selected
+targets, including their sync markers. Do not create missing C4 source when
+it is outside the supplied scope. Apply supplied reconciliation choices through
+this command while retaining the selected artifact's contract. Report related
+out-of-scope drift without expanding setup's write scope.
+
+The contracts, mode selection, evidence rules, and validation below apply per
+selected artifact. Maintain source-only PlantUML: never render it and never
+modify another diagram.
 
 ## Artifact Contracts
 
@@ -75,9 +92,10 @@ existing map wording.
 ## Baselines and Mode Selection
 
 Each artifact records its own reconciliation baseline, so mode selection is
-independent per artifact:
+independent per selected artifact; full reconciliation never expands the
+selected target set:
 
-- Full reconciliation when the artifact (or the C4 source) is missing, its
+- Full reconciliation when the selected artifact is missing, its
   marker is missing, malformed, unavailable locally, or not an ancestor of
   pre-command `HEAD`, the user requests a full refresh, or incremental
   evidence reveals structural drift outside the expected impact closure.
@@ -95,8 +113,8 @@ independent per artifact:
 5. Trace implementations and tests for critical flows and hazards.
 6. Read accepted ADRs and confirmed domain/business intent that constrain
    current code.
-7. Reconcile the artifact's complete required output and the C4 component
-   model when its topology is in scope.
+7. Reconcile the selected artifact's complete required output. Reconcile the
+   C4 component model only when its path is selected.
 8. Set that artifact's sync marker to the captured pre-command `HEAD` only
    after its reconciliation succeeds.
 
@@ -116,8 +134,8 @@ its largest file.
    relationships to establish impact closure.
 5. Edit only the affected sections of that artifact and preserve unrelated
    verified content.
-6. Update the C4 model only when component boundaries or relationships
-   changed.
+6. Update the C4 model only when its path is selected and component boundaries
+   or relationships changed.
 7. Set that artifact's sync marker to the captured pre-command `HEAD` only
    after its reconciliation succeeds.
 8. Escalate that artifact to full reconciliation when impact closure cannot
@@ -127,10 +145,12 @@ its largest file.
 
 Before reporting completion:
 
-1. Validate every retained path, symbol, command, and relationship against
-   the repository.
+1. Validate every retained path, symbol, command, and relationship in each
+   selected artifact against the repository.
 2. Run these probes in fresh context that receives only the draft
-   artifacts and the scenario, never the source-reading context:
+   selected artifacts and the scenario, never the source-reading context.
+   Judge each probe against those artifacts' authority and required output;
+   do not require an unselected artifact's content:
    - Explain: select a critical behavior; identify entry point, flow,
      state/side effects, failure semantics, and targeted source.
    - Feature: select a plausible extension; identify owner, extension seam,
@@ -138,7 +158,10 @@ Before reporting completion:
    - Bug: select a plausible public symptom; narrow diagnosis to an owning
      flow, likely files, and regression-test location.
 3. Rerun any failed probe after adding the missing knowledge. A failed
-   probe blocks completion for the affected artifact.
+    probe blocks completion for the affected artifact.
+
+Keep probe fixes within selected targets. Report missing out-of-scope knowledge
+separately; probes do not authorize creating or refreshing other maps.
 
 ## Completion