bearings 0.3.2 → 0.3.4

package/README.md

@@ -50,7 +50,7 @@ docs/
   skills/*
 ```
 
-Every file carries an `owner` in the manifest. `bearings`-owned files (`CLAUDE.md`, the ADR template, commands, skills) are package-maintained — the incoming template is their canonical update source. `agent`-owned files (`AGENTS.md`, the three maps, the two indexes) are yours; bearings never overwrites them without an explicit per-file decision.
+Every file carries an `owner` in the manifest. `bearings`-owned files (`CLAUDE.md`, the ADR template, and commands) are package-maintained — the incoming template is their canonical update source. Starter skills begin bearings-owned, then `/setup-repo` adapts and claims them as agent-owned. `agent`-owned files (`AGENTS.md`, the three maps, the two indexes, and claimed starter skills) are yours; bearings never overwrites them without an explicit per-file decision except for the starter-skill update handling below.
 
 `/setup-repo` creates `docs/diagrams/c4-component.puml` (via `/refresh-repo-map`) once the repo is tailored; it is not part of the generated scaffold or the manifest.
 
@@ -93,6 +93,9 @@ State-aware entry point. With no manifest it scaffolds; with a manifest it runs
 | File no longer shipped, unchanged locally | Removed |
 | File no longer shipped, changed locally | You choose **Remove** or **Keep and untrack** |
 | New scaffold path already occupied | Conflict, resolved the same way |
+| Claimed starter skill unchanged locally, template changed | Replaced silently; its agent owner is retained and its baseline is refreshed |
+| Claimed starter skill and template both changed | No CLI prompt: local content is preserved with backup, base, and incoming artifacts; `/setup-repo` guides the developer through a three-way resolution when the base exists |
+| Legacy bearings-owned starter skill and template both changed, with no baseline | No CLI prompt and no auto-claim: local content is preserved with backup and incoming artifacts; `verify` warns about the missing base and `/setup-repo` offers Take new template, Keep local, or Freeform |
 
 Adapter changes (harness added/removed, symlink↔copy switch) are planned alongside. The full plan is shown and confirmed before any mutation, then applied as a single transaction — the manifest is written last, and any failure restores the exact prior state. A run that changes nothing reports `already up to date`.
 
@@ -111,9 +114,10 @@ Check the manifest and harness exposures for mechanical breakage. Exit code `0`
 | `broken-symlink` | fail | harness entry is a symlink whose target doesn't resolve |
 | `copy-drift` | fail | copy mode: harness file content differs from `.agents` source content |
 | `setup-pending` | warn | an update finished but `/setup-repo` hasn't run yet |
-| `unfilled-placeholder` | warn | a bearings-generated file still contains `<agent:` |
+| `unfilled-placeholder` | warn | an `owner: agent` file still contains a complete single-line agent placeholder marker (bearings-owned files are not checked) |
+| `missing-skill-baseline` | warn | an agent-owned starter skill or pending `skill-update` reconciliation has no skill baseline file |
 | `unreviewed-backup` | warn | manifest `backup` path still exists on disk |
-| `pending-reconciliation` | warn | a recorded backup from a collision or Merge is still unresolved |
+| `pending-reconciliation` | warn | a reconciliation artifact, including a skill-update backup or incoming file, is still unresolved |
 
 ## Development
 

package/dist/{chunk-VRWQ3OWC.js → chunk-GEIRG7UT.js}

@@ -6,12 +6,25 @@ import { dirname, join } from "path";
 function templatesDir() {
   return join(dirname(fileURLToPath(import.meta.url)), "..", "templates");
 }
-var SKILLS = [
+var STARTER_SKILL_NAMES = [
   "commit-convention",
   "defer-work",
   "resurface-deferred-work",
   "recording-decisions"
 ];
+var SKILLS = STARTER_SKILL_NAMES;
+function starterSkillNameFromTarget(targetPath) {
+  return STARTER_SKILL_NAMES.find((skillName) => targetPath === `.agents/skills/${skillName}/SKILL.md`);
+}
+function isStarterSkillTarget(targetPath) {
+  return starterSkillNameFromTarget(targetPath) !== void 0;
+}
+function skillBaselinePath(skillName) {
+  return `.agents/.bearings-baseline/skills/${skillName}/SKILL.md`;
+}
+function skillIncomingPath(skillName) {
+  return `.agents/.bearings-incoming/skills/${skillName}/SKILL.md`;
+}
 var SCAFFOLD = [
   { template: "AGENTS.md", target: "AGENTS.md", owner: "agent" },
   { template: "CLAUDE.md", target: "CLAUDE.md", owner: "bearings" },
@@ -48,7 +61,7 @@ var HASH = /^sha256:[0-9a-f]{64}$/;
 var HARNESSES = ["claude", "opencode"];
 var EXPOSURES = ["symlink", "copy"];
 var OWNERS = ["bearings", "agent"];
-var RECONCILIATION_REASONS = ["init-collision", "update-merge"];
+var RECONCILIATION_REASONS = ["init-collision", "update-merge", "skill-update"];
 var SETUP_PENDING_KINDS = ["update", "reconstruction"];
 function fail(message) {
   throw new Error(message);
@@ -81,7 +94,17 @@ function validateReconciliation(value, context) {
   const { backup, reason, sourceHash, incomingTemplateVersion, incomingHash } = value;
   if (!isSafeManifestPath(backup)) fail(`${context}.backup is unsafe: ${String(backup)}`);
   if (typeof reason !== "string" || !RECONCILIATION_REASONS.includes(reason)) {
-    fail(`${context}.reason must be "init-collision" or "update-merge"`);
+    fail(`${context}.reason must be "init-collision", "update-merge", or "skill-update"`);
+  }
+  if (reason === "skill-update") {
+    const { basePath, incomingPath, baseHash } = value;
+    if (!isSafeManifestPath(basePath)) fail(`${context}.basePath is unsafe: ${String(basePath)}`);
+    if (!isSafeManifestPath(incomingPath)) fail(`${context}.incomingPath is unsafe: ${String(incomingPath)}`);
+    if (!isHash(baseHash)) fail(`${context}.baseHash must match sha256 format`);
+    if (!isHash(sourceHash)) fail(`${context}.sourceHash must match sha256 format`);
+    if (!isNonEmptyString(incomingTemplateVersion)) fail(`${context}.incomingTemplateVersion must be a string`);
+    if (!isHash(incomingHash)) fail(`${context}.incomingHash must match sha256 format`);
+    return { backup, reason, basePath, incomingPath, baseHash, sourceHash, incomingTemplateVersion, incomingHash };
   }
   if (!isHash(sourceHash)) fail(`${context}.sourceHash must match sha256 format`);
   if (!isNonEmptyString(incomingTemplateVersion)) fail(`${context}.incomingTemplateVersion must be a string`);
@@ -116,12 +139,15 @@ function validateFileV1(value, index) {
 function validateFileV2(value, index) {
   const context = `files[${index}]`;
   if (!isPlainObject(value)) fail(`${context} must be an object`);
-  const { path, template, templateVersion, hash, owner, retired, skippedTemplate, reconciliations } = value;
+  const { path, template, templateVersion, hash, owner, lastTemplateHash, retired, skippedTemplate, reconciliations } = value;
   if (!isSafeManifestPath(path)) fail(`${context}.path is unsafe: ${String(path)}`);
   if (!isNonEmptyString(template)) fail(`${context}.template must be a string`);
   if (!isNonEmptyString(templateVersion)) fail(`${context}.templateVersion must be a string`);
   if (!isHash(hash)) fail(`${context}.hash must match sha256 format`);
   if (!isOwner(owner)) fail(`${context}.owner must be "bearings" or "agent"`);
+  if (lastTemplateHash !== void 0 && !isHash(lastTemplateHash)) {
+    fail(`${context}.lastTemplateHash must match sha256 format`);
+  }
   if (retired !== void 0 && retired !== true) fail(`${context}.retired must be true when present`);
   let normalizedSkippedTemplate;
   if (skippedTemplate !== void 0) {
@@ -145,6 +171,7 @@ function validateFileV2(value, index) {
     templateVersion,
     hash,
     owner,
+    ...lastTemplateHash !== void 0 ? { lastTemplateHash } : {},
     ...retired === true ? { retired: true } : {},
     ...normalizedSkippedTemplate ? { skippedTemplate: normalizedSkippedTemplate } : {},
     ...normalizedReconciliations ? { reconciliations: normalizedReconciliations } : {}
@@ -270,6 +297,7 @@ function categorizeActions(actions) {
     restored: [],
     replaced: [],
     merged: [],
+    skillHandoffs: [],
     skipped: [],
     removed: [],
     keptUntracked: []
@@ -281,6 +309,8 @@ function categorizeActions(actions) {
       else result.replaced.push(action.path);
     } else if (action.kind === "merge") {
       result.merged.push(`${action.path} -> ${action.backup}`);
+    } else if (action.kind === "skill-handoff") {
+      result.skillHandoffs.push(action.path);
     } else if (action.kind === "skip") {
       result.skipped.push(action.path);
     } else if (action.kind === "delete") {
@@ -302,6 +332,7 @@ function renderUpdatePlan(input) {
   pushSection(lines, "Restored", categories.restored);
   pushSection(lines, "Replaced", categories.replaced);
   pushSection(lines, "Merged", categories.merged);
+  pushSection(lines, "Skill handoff \u2192 /setup-repo", categories.skillHandoffs);
   pushSection(lines, "Skipped", categories.skipped);
   pushSection(lines, "Removed", categories.removed);
   pushSection(lines, "Kept and untracked", categories.keptUntracked);
@@ -325,6 +356,7 @@ function renderUpdateReport(input) {
   pushSection(lines, "Restored", categories.restored);
   pushSection(lines, "Replaced", categories.replaced);
   pushSection(lines, "Merged", categories.merged);
+  pushSection(lines, "Skill handoff \u2192 /setup-repo", categories.skillHandoffs);
   pushSection(lines, "Skipped", categories.skipped);
   pushSection(lines, "Removed", categories.removed);
   pushSection(lines, "Kept and untracked", categories.keptUntracked);
@@ -421,6 +453,14 @@ async function generate(repoDir, bearingsVersion) {
     if (await exists2(abs)) {
       currentContent = await readFile2(abs, "utf8");
       if (priorEntry && sha256(currentContent) === priorEntry.hash) {
+        const skillName2 = starterSkillNameFromTarget(entry.target);
+        if (skillName2) {
+          const baseline = join4(repoDir, skillBaselinePath(skillName2));
+          if (!await exists2(baseline)) {
+            await mkdir2(dirname2(baseline), { recursive: true });
+            await writeFile2(baseline, currentContent);
+          }
+        }
         result.skippedUnchanged.push(entry.target);
         result.files.push(priorEntry);
         continue;
@@ -433,6 +473,12 @@ async function generate(repoDir, bearingsVersion) {
     await writeFile2(abs, templateContent);
     result.written.push(entry.target);
     const incomingHash = sha256(templateContent);
+    const skillName = starterSkillNameFromTarget(entry.target);
+    if (skillName) {
+      const baseline = join4(repoDir, skillBaselinePath(skillName));
+      await mkdir2(dirname2(baseline), { recursive: true });
+      await writeFile2(baseline, templateContent);
+    }
     const reconciliation = backup && currentContent !== void 0 ? {
       backup,
       reason: "init-collision",
@@ -446,6 +492,7 @@ async function generate(repoDir, bearingsVersion) {
       templateVersion: bearingsVersion,
       hash: incomingHash,
       owner: entry.owner,
+      ...isStarterSkillTarget(entry.target) ? { lastTemplateHash: incomingHash } : {},
       ...reconciliation ? { reconciliations: [reconciliation] } : {}
     });
   }
@@ -597,7 +644,7 @@ async function runFreshInit(repoDir, flags, version) {
         if (p.isCancel(selectedHarnesses)) {
           cancelInit(p);
         }
-        harnesses = validateHarnesses(selectedHarnesses);
+        harnesses = validateHarnesses(selectedHarnesses) ?? [];
       }
       if (!exposure && s.symlinksSupported) {
         const selectedExposure = await p.select({
@@ -633,12 +680,16 @@ async function runFreshInit(repoDir, flags, version) {
 async function runInit(repoDir, flags, version) {
   const state = await inspectManifest(repoDir);
   if (state.kind === "absent") return runFreshInit(repoDir, flags, version);
-  const { runUpdate } = await import("./update-5F7TZEUH.js");
+  const { runUpdate } = await import("./update-XOUXGD2Z.js");
   return runUpdate(repoDir, flags, version, state);
 }
 
 export {
   templatesDir,
+  starterSkillNameFromTarget,
+  isStarterSkillTarget,
+  skillBaselinePath,
+  skillIncomingPath,
   SCAFFOLD,
   sha256,
   inspectManifest,

package/dist/cli.js

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 import {
   inspectManifest,
+  isStarterSkillTarget,
   renderVerifyReport,
   runInit,
   sha256,
+  skillBaselinePath,
+  starterSkillNameFromTarget,
   validateHarnesses
-} from "./chunk-VRWQ3OWC.js";
+} from "./chunk-GEIRG7UT.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -17,6 +20,7 @@ import { dirname as dirname2, join as join2 } from "path";
 import { access, lstat, readFile, readdir, readlink, stat } from "fs/promises";
 import { dirname, join, resolve } from "path";
 var KINDS = ["skills", "commands"];
+var PLACEHOLDER = /<agent:[^>\n]*>/;
 async function exists(p) {
   try {
     await access(p);
@@ -28,6 +32,12 @@ async function exists(p) {
 async function verify(repoDir) {
   const failures = [];
   const warnings = [];
+  const missingSkillBaselines = /* @__PURE__ */ new Set();
+  async function warnMissingSkillBaseline(baseline) {
+    if (missingSkillBaselines.has(baseline) || await exists(join(repoDir, baseline))) return;
+    missingSkillBaselines.add(baseline);
+    warnings.push({ code: "missing-skill-baseline", path: baseline, message: "run /setup-repo to repair skill baseline" });
+  }
   const state = await inspectManifest(repoDir);
   if (state.kind === "absent") {
     return { failures: [{ code: "no-manifest", path: ".agents/bearings.json", message: "run bearings init first" }], warnings };
@@ -47,19 +57,27 @@ async function verify(repoDir) {
         failures.push({ code: "missing-file", path: f.path, message: "managed file deleted" });
       } else {
         const content = await readFile(abs, "utf8");
-        if (f.owner === "agent" && content.includes("<agent:")) {
+        if (f.owner === "agent" && PLACEHOLDER.test(content)) {
           warnings.push({ code: "unfilled-placeholder", path: f.path, message: "run /setup-repo to fill" });
         }
       }
     }
+    if (!retired && f.owner === "agent" && isStarterSkillTarget(f.path)) {
+      const skillName = starterSkillNameFromTarget(f.path);
+      await warnMissingSkillBaseline(skillBaselinePath(skillName));
+    }
     if ("backup" in f && f.backup && await exists(join(repoDir, f.backup))) {
       warnings.push({ code: "unreviewed-backup", path: f.backup, message: "review during /setup-repo, then delete" });
     }
     if ("reconciliations" in f && f.reconciliations) {
       for (const r of f.reconciliations) {
+        if (r.reason === "skill-update") await warnMissingSkillBaseline(r.basePath);
         if (await exists(join(repoDir, r.backup))) {
           warnings.push({ code: "pending-reconciliation", path: r.backup, message: "review during /setup-repo, then delete" });
         }
+        if (r.reason === "skill-update" && await exists(join(repoDir, r.incomingPath))) {
+          warnings.push({ code: "pending-reconciliation", path: r.incomingPath, message: "review during /setup-repo, then delete" });
+        }
       }
     }
   }

package/dist/{update-5F7TZEUH.js → update-XOUXGD2Z.js}

@@ -4,13 +4,17 @@ import {
   SCAFFOLD,
   canonicalAdapterEntries,
   entriesMatch,
+  isStarterSkillTarget,
   migrateV1,
   renderUpdatePlan,
   renderUpdateReport,
   sha256,
+  skillBaselinePath,
+  skillIncomingPath,
+  starterSkillNameFromTarget,
   templatesDir,
   validateHarnesses
-} from "./chunk-VRWQ3OWC.js";
+} from "./chunk-GEIRG7UT.js";
 
 // src/semver.ts
 function parseSemver(value) {
@@ -102,6 +106,80 @@ async function planFiles(input) {
     const currentHash = currentContent !== void 0 ? sha256(currentContent) : void 0;
     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 (isStarterSkillTarget(entry.target)) {
+      const prevOwner = prevRecord?.owner ?? entry.owner;
+      const lastTemplateHash = prevRecord?.lastTemplateHash ?? prevRecord?.hash;
+      const incomingRecordBase = {
+        path: entry.target,
+        template: entry.template,
+        templateVersion: source.bearingsVersion,
+        hash: incomingHash,
+        owner: prevOwner === "agent" ? "agent" : entry.owner,
+        lastTemplateHash: incomingHash
+      };
+      if (!currentExists) {
+        actions.push({
+          kind: "write",
+          reason: prevRecord ? "restore" : "add",
+          path: entry.target,
+          content: templateContent,
+          record: incomingRecordBase
+        });
+        continue;
+      }
+      if (!prevRecord && reconstruction && currentHash === incomingHash) {
+        actions.push({ kind: "keep", record: incomingRecordBase });
+        continue;
+      }
+      if (!prevRecord) {
+        actions.push({
+          kind: "conflict",
+          reason: "new-path",
+          path: entry.target,
+          content: templateContent,
+          currentHash,
+          record: incomingRecordBase,
+          stats: lineDiffStats(currentContent, templateContent),
+          canSkip: entry.target !== SETUP_COMMAND_PATH
+        });
+        continue;
+      }
+      if (prevRecord.skippedTemplate?.hash === incomingHash || lastTemplateHash === incomingHash) {
+        actions.push({ kind: "keep", record: prevRecord });
+        continue;
+      }
+      if (currentHash === prevRecord.hash) {
+        actions.push({
+          kind: "write",
+          reason: "replace",
+          path: entry.target,
+          content: templateContent,
+          record: {
+            ...incomingRecordBase,
+            ...prevRecord.reconciliations ? { reconciliations: prevRecord.reconciliations } : {}
+          }
+        });
+        continue;
+      }
+      actions.push({
+        kind: "skill-handoff",
+        path: entry.target,
+        content: templateContent,
+        currentHash,
+        previous: prevRecord,
+        baseHash: prevRecord.hash,
+        record: {
+          ...prevRecord,
+          template: entry.template,
+          templateVersion: source.bearingsVersion,
+          owner: prevRecord.owner === "agent" ? "agent" : prevRecord.owner,
+          lastTemplateHash
+        },
+        stats: lineDiffStats(currentContent, templateContent)
+      });
+      continue;
+    }
     const incomingRecord = {
       path: entry.target,
       template: entry.template,
@@ -109,7 +187,6 @@ async function planFiles(input) {
       hash: incomingHash,
       owner: entry.owner
     };
-    const prevRecord = previous?.files.find((file) => file.path === entry.target);
     const canSkip = entry.target !== SETUP_COMMAND_PATH;
     if (!currentExists) {
       actions.push({
@@ -277,6 +354,33 @@ async function resolveFilePlan(repoDir, draft, decisions) {
       }
       continue;
     }
+    if (action.kind === "skill-handoff") {
+      const skillName = starterSkillNameFromTarget(action.path);
+      const backup = await freeBackupPath(repoDir, action.path);
+      const basePath = skillBaselinePath(skillName);
+      const incomingPath = skillIncomingPath(skillName);
+      const reconciliation = {
+        reason: "skill-update",
+        backup,
+        basePath,
+        incomingPath,
+        baseHash: action.baseHash,
+        sourceHash: action.currentHash,
+        incomingTemplateVersion: action.record.templateVersion,
+        incomingHash: sha256(action.content)
+      };
+      const record2 = {
+        ...action.record,
+        owner: action.previous.owner === "agent" ? "agent" : action.record.owner,
+        hash: action.previous.hash,
+        lastTemplateHash: action.previous.lastTemplateHash ?? action.previous.hash,
+        reconciliations: [...action.previous.reconciliations ?? [], reconciliation]
+      };
+      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") {
       const decision2 = decisionsByPath.get(action.path);
       if (!decision2) fail(`Missing decision for path: ${action.path}`);
@@ -519,7 +623,7 @@ async function planAdapterActions(input) {
 
 // src/update/transaction.ts
 import { randomUUID } from "crypto";
-import { cp, lstat as lstat2, mkdir, readdir as readdir2, rename, rm, rmdir, symlink, writeFile } from "fs/promises";
+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) {
@@ -554,6 +658,16 @@ async function ensureDir(repoDir, absDir, createdDirs) {
     }
   }
 }
+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 writeCopy(repoDir, txDir, fromRelativePath, toRelativePath, snapshots, createdDirs) {
+  const content = await readFile3(join3(repoDir, fromRelativePath));
+  await writeContent(repoDir, txDir, toRelativePath, content, snapshots, createdDirs);
+}
 async function restore(snapshots, hooks, txDir) {
   for (const snapshot of [...snapshots].reverse()) {
     try {
@@ -593,14 +707,26 @@ async function applyUpdate(repoDir, plan, hooks = {}) {
   try {
     for (const action of plan.files) {
       if (action.kind === "write") {
-        await capture(repoDir, txDir, action.path, snapshots);
-        await ensureDir(repoDir, dirname(abs(action.path)), createdDirs);
-        await writeFile(abs(action.path), action.content);
+        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, action.path, action.backup, snapshots);
         await writeFile(abs(action.path), action.content);
         await afterOp();
+      } else if (action.kind === "skill-handoff") {
+        await writeCopy(repoDir, txDir, action.path, action.backup, snapshots, createdDirs);
+        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();

package/package.json

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

package/templates/AGENTS.md

@@ -20,7 +20,9 @@ Primary stack: <agent: fill during handoff — language/runtime/framework/platfo
 | A consequential domain or technical decision | `docs/adr/INDEX.md` | Read the index first, then only matching ADRs. |
 | Planning a new capability | `docs/deferred/INDEX.md` | Read the index first, then only matching deferred details. |
 
-## Response Style
+## User-Facing Output
+
+Write all user-facing output for a reader with ADHD. Keep it concise, concrete, easy to scan, and in ASD-STE100 Simplified Technical English.
 
 - Lead with the answer; omit preamble and restatement.
 - Use the shortest clear structure: line, bullets, table, tree, or flow.

package/templates/agents/commands/setup-repo.md

@@ -11,14 +11,14 @@ answer per question — and explore the code before asking anything the code
 can answer.
 
 This is the only operation the temporary `## Setup Required` gate in
-`AGENTS.md` permits. Do not remove the gate until step 10 below.
+`AGENTS.md` permits. Do not remove the gate until step 11 below.
 
 ## Post-update reconciliation
 
 When `.agents/bearings.json` is manifest v2 and has `setupPending`:
 
 1. Read every file record's ordered `reconciliations`.
-2. For each reconciliation, read its Backup File and current target, summarize
+2. For each non-`skill-update` reconciliation, read its Backup File and current target, summarize
    the differences, and ask which backed-up changes to apply to the target.
 3. Apply the developer's choice directly to the target regardless of owner,
    delete the resolved Backup File, and remove its reconciliation record.
@@ -32,6 +32,35 @@ When `.agents/bearings.json` is manifest v2 and has `setupPending`:
    manifest.
 7. Run `bearings verify` again and finish only at zero failures and warnings.
 
+### Starter skill updates (`skill-update`)
+
+For each file record with a `skill-update` reconciliation:
+
+1. Read `basePath`, the live skill path (local), and `incomingPath`. Check
+   whether `basePath` exists before attempting any diff.
+2. If `basePath` is missing, explain that Three-way merge is not available
+   without a historical base. Do not fabricate one. Offer exactly these
+   options (one skill at a time):
+   - **Take new template**, **Keep local**, and **Freeform**. Apply the same
+     manifest and baseline updates described below for the selected outcome.
+3. If `basePath` exists, diff local vs base and incoming vs base; summarize
+   both for the developer. If `basePath` exists, offer exactly these four options
+   (one skill at a time), mark a recommendation:
+   - **Take new template** — replace live skill with incoming; set manifest
+     `hash` and `lastTemplateHash` to incoming hash; `owner: agent`.
+   - **Keep local** — leave live skill; set `hash` to current content hash;
+     keep `lastTemplateHash`; set `skippedTemplate` to the incoming
+     version/hash; `owner: agent`.
+   - **Three-way merge** (Recommended when both diffs are non-empty) — merge
+     both sides into the live skill; then set `hash` to result hash and
+     `lastTemplateHash` to incoming hash; `owner: agent`.
+   - **Freeform** — developer/agent writes the resolved file; same baselining
+     as merge (hash = result, `lastTemplateHash` = incoming hash) unless they
+     explicitly choose to decline the template (then same as Keep local).
+4. Refresh `.agents/.bearings-baseline/skills/<name>/SKILL.md` to match the
+   new content hash.
+5. Delete backup, incoming file, and the reconciliation entry.
+
 ## Required workflow
 
 1. Read `AGENTS.md` and `.agents/bearings.json`.
@@ -47,31 +76,50 @@ When `.agents/bearings.json` is manifest v2 and has `setupPending`:
 4. Fill only the `AGENTS.md` project-purpose and primary-stack placeholders.
    Keep `AGENTS.md` a thin router — do not add a skill table, invariants
    section, or always-on rules block.
-5. Create a project-specific skill only when native skill discovery has no
-   adequate existing match. Every starter skill is bearings-owned — leave
-   them untouched.
-6. Run the `/refresh-repo-map` workflow to initialize `docs/DOMAIN.md`,
+5. Adapt every starter skill:
+   - `.agents/skills/commit-convention/SKILL.md`
+   - `.agents/skills/defer-work/SKILL.md`
+   - `.agents/skills/resurface-deferred-work/SKILL.md`
+   - `.agents/skills/recording-decisions/SKILL.md`
+   - Explore the repo for format, lint-fix, lint, typecheck, test, build,
+     and docs verification commands.
+   - Replace every `<agent: fill during handoff — …>` marker with a real
+     command or explicit `not configured`.
+   - Light project tailoring only — do not remove the skill's safety workflow.
+6. Claim starter skills in `.agents/bearings.json` (allowed manifest edit):
+   - Set each starter skill `owner` to `agent`.
+   - Set `hash` to the sha256 of the file contents (use the same algorithm as
+     bearings: UTF-8 body, `sha256:` + hex).
+   - Set `lastTemplateHash` to the hash of the skill template as shipped in the
+     installed bearings package (read from the package templates if needed;
+     if the adapted file still matches the package template byte-for-byte,
+     `lastTemplateHash` equals `hash`).
+   - Write `.agents/.bearings-baseline/skills/<name>/SKILL.md` equal to the
+     live file bytes.
+7. Run the `/refresh-repo-map` workflow to initialize `docs/DOMAIN.md`,
    `docs/ARCHITECTURE.md`, `docs/CODEBASE_MAP.md`, and
    `docs/diagrams/c4-component.puml`.
-7. Expose any newly created skills into each configured harness using the
+8. Expose any newly created skills into each configured harness using the
    manifest's existing symlink/copy mode.
-8. Run `bearings verify`. Fix every failure and every warning.
-9. Confirm the run reports zero failures and zero warnings before
-   proceeding.
-10. Remove the `## Setup Required` section from `AGENTS.md` — only after
-    step 9 confirms zero failures and zero warnings.
-11. Run `bearings verify` again and report the completed setup to the
+9. Run `bearings verify`. Fix every failure and every warning.
+10. Confirm the run reports zero failures and zero warnings before
+    proceeding.
+11. Remove the `## Setup Required` section from `AGENTS.md` — only after
+    step 10 confirms zero failures and zero warnings.
+12. Run `bearings verify` again and report the completed setup to the
     developer.
 
 ## Rules
 
 - Do not overwrite developer decisions silently — every merge/keep/discard
   of a Backup File is the developer's call.
-- Do not edit `.agents/bearings.json` except where this workflow requires
-  it.
-- Do not change bearings-owned starter commands or skills. The one exception:
-  a reconciliation that records an explicit Merge decision permits applying
-  that Backup File's changes directly to its bearings-owned target.
+- Do not edit bearings-owned **commands** except when a recorded Merge
+  reconciliation explicitly permits applying backup changes.
+- Do edit starter **skills** during setup (adapt + claim). After claim they
+  are agent-owned; maintainers may edit them freely.
+- Manifest edits are limited to: skill `owner` / `hash` / `lastTemplateHash` /
+  `skippedTemplate` / `reconciliations`, deleting resolved backups/incoming,
+  and clearing `setupPending`.
 - Do not add a skill registry row to `AGENTS.md` — native skill discovery
   replaces it.
 - Do not invent domain or technical constraints — every stated constraint

package/templates/agents/skills/commit-convention/SKILL.md

@@ -3,96 +3,29 @@ name: commit-convention
 description: Commit changes through a deterministic commit gate. Use when an agent is about to create a git commit.
 ---
 
-# Commit Gate
+# Commit Convention
 
 ## Project Commands
 
-- Format intended files: `<agent: fill during handoff — formatter command accepting explicit file paths>`
-- Fix lint errors in intended files: `<agent: fill during handoff — lint-fix command accepting explicit file paths>`
-- Check lint: `<agent: fill during handoff — complete lint command>`
-- Typecheck: `<agent: fill during handoff — typecheck command or "not configured">`
-- Test suite: `<agent: fill during handoff — complete test-suite command>`
-- Build: `<agent: fill during handoff — build command or "not configured">`
-
-## Required Workflow
-
-1. Establish the intended change set.
-   - Inspect `git status`, `git diff`, and `git diff --cached`.
-   - The current task defines the commit allowlist; repository dirtiness does not expand it.
-   - Classify every changed hunk as intended or unrelated.
-   - Preserve unrelated staged and unstaged changes exactly.
-   - For a mixed file, proceed only when tools and hunk staging can leave unrelated changes untouched.
-   - Completion: every hunk is classified and the intended changes can be isolated safely.
-
-2. Format and lint-fix the intended files.
-   - Pass explicit intended file paths to each configured tool.
-   - Repository-wide auto-fixes are prohibited.
-   - Reinspect the diff after each command and require unrelated hunks to remain unchanged.
-   - Completion: every intended file is formatted and has no lint errors.
-
-3. Run the quality gates.
-   - Run the complete lint check.
-   - Run typecheck when configured.
-   - Run the complete test suite.
-   - Run the build when configured.
-   - Completion: every configured gate must exit successfully.
-
-4. Review and stage the intended changes.
-   - Reject secrets, debug code, generated noise, and unrelated changes.
-   - Stage explicit intended paths or hunks; `git add .` and `git add -A` are prohibited.
-   - Review `git diff --cached`.
-   - Completion: every staged hunk belongs to the current task.
-
-5. Write the commit message.
-   - Follow the Conventional Commits policy below.
-   - Describe the staged change rather than the broader task or conversation.
-   - Completion: the message satisfies the documented grammar and rules.
-
-6. Create and verify the commit.
-   - Commit without bypassing hooks.
-   - Amend only when the developer explicitly requests it.
-   - Verify the resulting commit hash and message.
-   - Report the commit and any unrelated changes left untouched.
-   - Completion: the commit exists with the intended tree and message.
-
-## Conventional Commits
-
-Use `<type>[optional scope][!]: <imperative summary>`.
-
-| Type | Use |
-|---|---|
-| `feat` | New user-visible behavior |
-| `fix` | Defect correction |
-| `docs` | Documentation only |
-| `style` | Formatting with no behavior change |
-| `refactor` | Internal change with no feature or fix |
-| `perf` | Performance improvement |
-| `test` | Tests only |
-| `build` | Build system or dependency changes |
-| `ci` | CI configuration |
-| `chore` | Maintenance not covered above |
-| `revert` | Revert a previous commit |
-
-Message rules:
-
-- Use a short, imperative summary beginning with lowercase text.
-- Keep the complete subject line at or below 72 characters and omit a trailing period.
-- Use a stable package or subsystem name as the optional scope.
-- Mark breaking changes with `!` and add a `BREAKING CHANGE:` footer.
-- Add a body only when the reason or migration impact is not clear from the subject.
-- Add issue references as footers when applicable.
-- Add co-author or agent attribution only when explicitly requested.
-
-Examples:
-
-- `feat(cli): add copy-mode verification`
-- `fix(adapter): preserve unrelated staged changes`
-- `docs: clarify setup workflow`
-- `refactor(generator)!: replace manifest ownership model`
-
-## Stop Conditions
-
-- Unsafe change isolation -> report the overlap and create no commit.
-- A required gate fails because of intended changes -> fix it and rerun that gate.
-- A required gate fails for an unrelated or pre-existing reason -> report it and create no commit.
-- A commit hook fails -> treat it as a required gate; keep the hook enabled.
+- Format intended files: `<agent: fill during handoff — formatter command accepting explicit file paths, or "not configured">`
+- Fix lint errors in intended files: `<agent: fill during handoff — lint-fix command accepting explicit file paths, or "not configured">`
+- Check lint: `<agent: fill during handoff — complete lint command, or "not configured">`
+- Typecheck: `<agent: fill during handoff — typecheck command, or "not configured">`
+- Other quality gates: `<agent: fill during handoff — remaining quality commands such as dependency-cruiser, tests, or build, or "not configured">`
+
+## Workflow
+
+1. Inspect the worktree and staged diff. The current task defines the commit
+   allowlist; leave unrelated changes untouched. Stop if safe isolation is
+   impossible.
+2. On the intended files, run the format and lint-fix commands, then run the
+   lint and typecheck commands to verify. If any check reports errors, fix them
+   and re-run that check; repeat until it passes clean. Then run the remaining
+   quality gates and resolve any failures the same way before continuing.
+3. Stage only intended paths or hunks, then review the staged diff.
+4. Write a Conventional Commit describing the staged change. Use an
+   imperative lowercase subject of at most 72 characters with no trailing
+   period. Add a body only for rationale or migration impact. Add attribution
+   only when explicitly requested.
+5. Commit without bypassing hooks. Amend only when explicitly requested.
+   Verify the resulting commit and report unrelated changes left untouched.