bearings 0.4.0 → 0.5.0

package/dist/{update-TBMTUJUT.js → update-QTWNGAGX.js}

@@ -4,6 +4,7 @@ import {
   SCAFFOLD,
   canonicalAdapterEntries,
   entriesMatch,
+  freeBackupPath,
   isStarterSkillTarget,
   migrateV1,
   renderUpdatePlan,
@@ -13,8 +14,9 @@ import {
   skillIncomingPath,
   starterSkillNameFromTarget,
   templatesDir,
-  validateHarnesses
-} from "./chunk-KQPOIH7N.js";
+  validateHarnesses,
+  writeBackup
+} from "./chunk-5D5YO3E3.js";
 
 // src/semver.ts
 function parseSemver(value) {
@@ -75,11 +77,6 @@ async function exists(path) {
     return false;
   }
 }
-async function freeBackupPath(repoDir, target) {
-  let candidate = `${target}.bkp`;
-  for (let i = 1; await exists(join(repoDir, candidate)); i++) candidate = `${target}.bkp.${i}`;
-  return candidate;
-}
 function lineDiffStats(current, incoming) {
   const left = current.split("\n");
   const right = incoming.split("\n");
@@ -562,12 +559,12 @@ async function planAdapterActions(input) {
   for (const action of fileActions) {
     const root = parseAdapterRoot(actionPath(action));
     if (!root) continue;
-    if (action.kind === "delete") {
+    if (action.kind === "delete" || action.kind === "untrack-missing") {
       if (!desiredRootState.has(root)) desiredRootState.set(root, false);
     } else {
       desiredRootState.set(root, true);
     }
-    if (action.kind === "write" || action.kind === "merge" || action.kind === "delete") {
+    if (action.kind === "write" || action.kind === "merge" || action.kind === "delete" || action.kind === "untrack-missing") {
       affectedRootKeys.add(root);
     }
   }
@@ -638,12 +635,12 @@ async function capture(repoDir, txDir, relativePath, snapshots) {
   await rename(target, stored);
   snapshots.push({ target, stored });
 }
-async function captureToBackup(repoDir, relativePath, backupRelativePath, snapshots) {
-  const target = join3(repoDir, relativePath);
-  const stored = join3(repoDir, backupRelativePath);
-  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);
@@ -664,10 +661,6 @@ async function writeContent(repoDir, txDir, relativePath, content, snapshots, cr
   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 {
@@ -693,6 +686,25 @@ async function removeEmptyDirs(createdDirs) {
     }
   }
 }
+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 = [];
@@ -720,11 +732,12 @@ async function applyUpdate(repoDir, plan, hooks = {}) {
         }
         await afterOp();
       } else if (action.kind === "merge") {
-        await captureToBackup(repoDir, action.path, action.backup, snapshots);
+        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 writeCopy(repoDir, txDir, action.path, action.backup, snapshots, createdDirs);
+        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") {
@@ -732,6 +745,27 @@ async function applyUpdate(repoDir, plan, hooks = {}) {
         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);
@@ -766,6 +800,151 @@ async function applyUpdate(repoDir, plan, hooks = {}) {
   }
 }
 
+// src/update/testplan-migration.ts
+import { access as access2, readFile as readFile4, readdir as readdir3 } from "fs/promises";
+import { join as join4 } from "path";
+var LEGACY_NAME = /^(.+)\.testplan\.json$/;
+var SCOPE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+async function exists2(path) {
+  return access2(path).then(() => true, () => false);
+}
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function optionalString(value) {
+  return value === void 0 || typeof value === "string";
+}
+function validPairs(value) {
+  return value === void 0 || Array.isArray(value) && value.every((pair) => Array.isArray(pair) && pair.length === 2 && pair.every((part) => typeof part === "string"));
+}
+function hasOnlyKeys(value, keys) {
+  const allowed = new Set(keys);
+  return Object.keys(value).every((key) => allowed.has(key));
+}
+function isValidLegacyPlan(value) {
+  if (!isObject(value) || !nonEmptyString(value.scope) || !SCOPE.test(value.scope)) return false;
+  if (!hasOnlyKeys(value, ["scope", "title", "subtitle", "intro", "callout", "conventions", "sections"])) return false;
+  if (!nonEmptyString(value.title)) return false;
+  if (!["subtitle", "intro", "callout", "conventions"].every((field) => optionalString(value[field]))) return false;
+  if (!Array.isArray(value.sections) || value.sections.length === 0) return false;
+  const ids = /* @__PURE__ */ new Set();
+  for (const section of value.sections) {
+    if (!isObject(section) || !nonEmptyString(section.n) || !nonEmptyString(section.title)) return false;
+    if (!hasOnlyKeys(section, ["n", "title", "kind", "intro", "tests"])) return false;
+    if (!["checklist", "info"].includes(section.kind) || !optionalString(section.intro)) return false;
+    if (!Array.isArray(section.tests) || section.tests.length === 0) return false;
+    for (const test of section.tests) {
+      if (!isObject(test) || !nonEmptyString(test.id) || !nonEmptyString(test.title) || ids.has(test.id)) return false;
+      if (!hasOnlyKeys(test, ["id", "title", "note", "expect", "optional", "code", "subs"])) return false;
+      ids.add(test.id);
+      if (!optionalString(test.note) || !optionalString(test.expect)) return false;
+      if (test.optional !== void 0 && typeof test.optional !== "boolean") return false;
+      if (!validPairs(test.code) || !validPairs(test.subs)) return false;
+      for (const pair of test.subs ?? []) {
+        if (!nonEmptyString(pair[0]) || ids.has(pair[0])) return false;
+        ids.add(pair[0]);
+      }
+    }
+  }
+  return true;
+}
+function convertLegacyPlan(plan) {
+  const checklist = {
+    title: plan.title,
+    summary: nonEmptyString(plan.subtitle) ? plan.subtitle : plan.title,
+    ...plan.intro !== void 0 ? { intro: plan.intro } : {},
+    ...plan.callout !== void 0 ? { callout: plan.callout } : {},
+    ...plan.conventions !== void 0 ? { conventions: plan.conventions } : {},
+    sections: plan.sections.map((section) => ({
+      number: section.n,
+      title: section.title,
+      kind: section.kind,
+      ...section.intro !== void 0 ? { intro: section.intro } : {},
+      items: section.tests.map((test) => ({
+        id: test.id,
+        title: test.title,
+        ...test.note !== void 0 ? { instruction: test.note } : {},
+        ...test.expect !== void 0 ? { expectedResult: test.expect } : {},
+        ...test.code !== void 0 ? {
+          codeBlocks: test.code.map(([language, content]) => ({
+            language: nonEmptyString(language) ? language : "text",
+            content
+          }))
+        } : {},
+        ...test.optional !== void 0 ? { optional: test.optional } : {},
+        ...test.subs !== void 0 ? {
+          subItems: test.subs.map(([id, title]) => ({
+            id,
+            title: nonEmptyString(title) ? title : id
+          }))
+        } : {}
+      }))
+    }))
+  };
+  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) => {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  });
+  if (entries === null) return { actions: [], reconciliations: [] };
+  const actions = [];
+  const reconciliations = [];
+  let canRemoveDirectory = entries.length === 0;
+  for (const entry of entries) {
+    const match = entry.isFile() ? LEGACY_NAME.exec(entry.name) : null;
+    if (!match) continue;
+    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");
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      parsed = void 0;
+    }
+    if (!target || !isValidLegacyPlan(parsed)) {
+      const backup = await freeBackupPath(repoDir, source);
+      actions.push({ kind: "preserve-invalid-testplan", source, backup });
+      reconciliations.push({
+        kind: "invalid-testplan",
+        source,
+        ...target ? { target } : {},
+        backup,
+        sourceHash: sha256(raw)
+      });
+      continue;
+    }
+    const content = convertLegacyPlan(parsed);
+    if (await exists2(join4(repoDir, target))) {
+      const backup = await freeBackupPath(repoDir, target);
+      const collided = await readFile4(join4(repoDir, target), "utf8");
+      actions.push({ kind: "migrate-testplan", source, target, content, backup });
+      reconciliations.push({
+        kind: "testplan-collision",
+        source,
+        target,
+        backup,
+        sourceHash: sha256(collided),
+        incomingHash: sha256(content)
+      });
+    } else {
+      actions.push({ kind: "migrate-testplan", source, target, content });
+    }
+  }
+  if (entries.length > 0) {
+    canRemoveDirectory = entries.every((entry) => entry.isFile() && LEGACY_NAME.test(entry.name) && actions.some((action) => action.kind === "migrate-testplan" && action.source === `testplans/${entry.name}`));
+  }
+  if (canRemoveDirectory) actions.push({ kind: "remove-empty-testplan-dir", path: "testplans" });
+  return { actions, reconciliations };
+}
+
 // src/update/prompts.ts
 function cancelUpdate(p) {
   p.cancel("Init cancelled.");
@@ -836,7 +1015,7 @@ async function runUpdate(repoDir, flags, version, state) {
   }
   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?.files.some((file) => file.reconciliations?.length))) {
+  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) {
@@ -876,6 +1055,7 @@ async function runUpdate(repoDir, flags, version, state) {
     else if (action.kind === "removed-conflict") decisions.push(await chooseRemovedConflict(p, action));
   }
   const resolved = await resolveFilePlan(repoDir, draft, decisions);
+  const migrationPlan = await planTestplanMigrations(repoDir);
   const adapterActions = await planAdapterActions({
     repoDir,
     currentHarnesses,
@@ -886,13 +1066,13 @@ async function runUpdate(repoDir, flags, version, state) {
   });
   const harnessesUnchanged = current ? current.harnesses.length === harnesses.length && current.harnesses.every((h) => harnesses.includes(h)) : false;
   const exposureUnchanged = current ? current.exposure === exposure : false;
-  const noArtifactChanges = resolved.actions.every((a) => a.kind === "keep") && adapterActions.length === 0;
+  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) {
     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 || adapterActions.length > 0 || migratedAbsorbedBackup;
+  const setupRequired = resolved.setupRequired || migrationPlan.actions.length > 0 || adapterActions.length > 0 || migratedAbsorbedBackup;
   const finalManifest = {
     version: 2,
     bearingsVersion: version,
@@ -905,10 +1085,12 @@ async function runUpdate(repoDir, flags, version, state) {
         toVersion: version
       }
     } : {},
+    ...migrationPlan.reconciliations.length > 0 ? { migrationReconciliations: [...migrationPlan.reconciliations] } : {},
     files: [...resolved.files]
   };
   const summaryInput = {
     actions: resolved.actions,
+    migrationActions: migrationPlan.actions,
     adapterActions,
     fromVersion: current?.bearingsVersion,
     toVersion: version,
@@ -917,7 +1099,12 @@ async function runUpdate(repoDir, flags, version, state) {
     reconstruction
   };
   await confirmUpdatePlan(p, renderUpdatePlan(summaryInput));
-  await applyUpdate(repoDir, { files: resolved.actions, adapters: adapterActions, manifest: finalManifest });
+  await applyUpdate(repoDir, {
+    files: resolved.actions,
+    migrations: migrationPlan.actions,
+    adapters: adapterActions,
+    manifest: finalManifest
+  });
   return { manifest: finalManifest, report: renderUpdateReport({ ...summaryInput, setupRequired }) };
 }
 export {

package/package.json

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

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

@@ -11,26 +11,29 @@ 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 11 below.
+`AGENTS.md` permits. Do not remove the gate until step 12 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 non-`skill-update` reconciliation, read its Backup File and current target, summarize
+1. Read every file record's ordered `reconciliations` and every top-level
+   `migrationReconciliations` record.
+2. Resolve every `migrationReconciliations` record through **Migrated checklist
+   repairs** below.
+3. 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,
+4. Apply the developer's choice directly to the target regardless of owner,
    delete the resolved Backup File, and remove its reconciliation record.
-4. A `skippedTemplate` records a declined template revision.
+5. A `skippedTemplate` records a declined template revision.
    Do not apply the declined template — normal project maintenance may
    still update that file.
-5. Run only setup steps supported by current drift; do not reset completed
+6. Run only setup steps supported by current drift; do not reset completed
    project tailoring.
-6. Run `bearings verify`. Resolve every failure and warning except the
+7. Run `bearings verify`. Resolve every failure and warning except the
    expected `setup-pending` warning, then remove `setupPending` from the
    manifest.
-7. Run `bearings verify` again and finish only at zero failures and warnings.
+8. Run `bearings verify` again and finish only at zero failures and warnings.
 
 ### Starter skill updates (`skill-update`)
 
@@ -61,6 +64,52 @@ For each file record with a `skill-update` reconciliation:
    new content hash.
 5. Delete backup, incoming file, and the reconciliation entry.
 
+### Migrated checklist repairs (`migrationReconciliations`)
+
+Resolve each record through the generic checklist workflow. Invoke the
+`checklist` skill directly, or delegate one record to a subagent that loads and
+follows `.agents/skills/checklist/SKILL.md`.
+
+1. For `testplan-collision`, read the current `target` and the pre-existing
+   checklist in `backup`. Summarize their authored content and ask the developer
+   whether to keep either version or combine them. Write the choice to `target`.
+2. For `invalid-testplan`, read `backup`, explain each contract problem, and
+   repair its useful authored content into `target`. When the record has no
+   `target`, ask the developer to choose a safe
+   `checklists/<category...>/<slug>.json` path first. Do not discard content
+   that cannot be repaired without the developer's decision.
+3. Follow the checklist skill's schema, validation, and full-library build
+   steps for the resolved target. Continue only after validation and build both
+   pass.
+4. Delete the resolved `backup` and remove its
+   `migrationReconciliations` record. Remove the top-level property when no
+   records remain.
+
+## Checklist opener
+
+Add or reuse one project-native command that runs `npx bearings checklist` (or
+the repository's established local bearings invocation). This command builds
+the checklist payload and opens the static previewer.
+
+1. Search existing automation and documentation for an existing equivalent
+   runner command that already builds and opens the checklist previewer. Reuse
+   it and report its exact invocation without editing its runner.
+2. Otherwise, select the first existing safe automation home in this exact
+   priority: `justfile`, `Makefile`, `Taskfile.yml`, `mise.toml`, then
+   `package.json`.
+3. Before editing an existing automation file, show the proposed command and
+   ask the developer for approval. Edit it only after approval. If approval is
+   declined, leave it unchanged and continue through the priority order.
+4. If no existing home is safe and approved, ask the developer to choose
+   between creating one missing automation file from the list above and using
+   the direct fallback. Create a missing file only after the developer selects
+   that strategy and file.
+5. When no automation file is selected, make no automation edit and report the
+   stack-agnostic direct build-and-open fallback: `npx bearings checklist`.
+6. Run the selected command, or the direct fallback, and confirm that it builds
+   successfully and opens the static previewer. Report its exact invocation for
+   future use.
+
 ## Required workflow
 
 1. Read `AGENTS.md` and `.agents/bearings.json`.
@@ -96,17 +145,18 @@ For each file record with a `skill-update` reconciliation:
      `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`.
-8. Expose any newly created skills into each configured harness using the
-   manifest's existing symlink/copy mode.
-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
+7. Complete the **Checklist opener** workflow above.
+8. Run the `/refresh-repo-map` workflow to initialize `docs/DOMAIN.md`,
+    `docs/ARCHITECTURE.md`, `docs/CODEBASE_MAP.md`, and
+    `docs/diagrams/c4-component.puml`.
+9. Expose any newly created skills into each configured harness using the
+    manifest's existing symlink/copy mode.
+10. Run `bearings verify`. Fix every failure and every warning.
+11. Confirm the run reports zero failures and zero warnings before
+     proceeding.
+12. Remove the `## Setup Required` section from `AGENTS.md` — only after
+    step 11 confirms zero failures and zero warnings.
+13. Run `bearings verify` again and report the completed setup to the
     developer.
 
 ## Rules
@@ -118,8 +168,9 @@ For each file record with a `skill-update` reconciliation:
 - 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`.
+  `skippedTemplate` / `reconciliations`, resolving
+  `migrationReconciliations`, 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/checklist/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: checklist
+description: Create a generic executable checklist for human-run procedures. Use when work needs an operational checklist for setup, deployment, release, verification, maintenance, or another process a person must perform.
+---
+
+# Checklist
+
+Create one evidence-backed checklist for a human operator. The JSON contains
+authored instructions; the static previewer owns execution state.
+
+## Workflow
+
+1. Read `.agents/skills/checklist/schema.reference.json` and inspect the
+   repository sources that define the requested procedure. Resolve every
+   mechanic, command, URL, prerequisite, expected result, and hazard from
+   running code, configuration, authoritative documentation, or developer
+   confirmation. Ask the developer about any required detail the evidence does
+   not establish.
+2. Choose a lowercase slug path under `checklists/`. The final segment is the
+   checklist slug and every preceding segment is its category. Use nested
+   categories when useful, for example `checklists/operations/servers/rotate-keys.json`
+   has category `operations/servers` and identity `operations/servers/rotate-keys`.
+3. Write exactly one JSON file at `checklists/<category...>/<slug>.json`.
+   Category identity and slug come only from the path; omit them from the JSON.
+4. Run
+   `node .agents/skills/checklist/scripts/validate.mjs checklists/<category...>/<slug>.json`.
+   Fix every reported violation until it exits zero and prints `OK`.
+5. From the repository root, run
+   `node .agents/skills/checklist/scripts/build.mjs`. Fix every reported
+   checklist-library error until the build exits zero.
+6. Open `.agents/skills/checklist/previewer/index.html` with the environment's
+   browser-opening tool. If opening fails, report the absolute file path so the
+   developer can open it. The command must finish; the static previewer needs
+   no server process.
+
+## Content Policy
+
+- Organize sections in execution order and keep each checklist item to one
+  primary action or verification. Use `info` sections for concise context that
+  the operator does not mark as executed.
+- Give every executable item exact, evidence-backed mechanics and an observable
+  `expectedResult`. Put commands in `codeBlocks`; distinguish literal values
+  from placeholders and state where each command runs.
+- Use `links` for authoritative background material instead of expanding the
+  checklist into a manual. Include only verified, safe destination URLs and
+  clear labels.
+- Put a `warning` before destructive, irreversible, privileged,
+  security-sensitive, externally visible, data-changing, or access-loss
+  actions. State the concrete hazard and any prerequisite that preserves
+  operator control.
+- Add `failureGuidance` when an item can fail or block progress. Give an
+  evidence-backed next action such as stop, retry, diagnose, roll back, or
+  escalate, plus the observable recovered state when recovery applies.
+- Refer to credentials through the repository's established secret mechanism
+  or documented location. Keep passwords, tokens, private keys, and other
+  secret values out of checklist content.
+- Keep authored content only in the JSON. Statuses such as `not-started`,
+  `complete`, `failed`, `blocked`, and `not-applicable`, and all operator
+  progress, belong to browser-local previewer state.
+- Treat absent evidence as an unresolved input. Ask for it or state a verified
+  limitation; do not invent mechanics, URLs, commands, credentials, expected
+  behavior, warnings, or recovery steps.
+
+## Completion
+
+Finish only when exactly one authored checklist file exists for this request,
+its mechanics and outcomes trace to evidence, its validator prints `OK`, the
+full library build succeeds, and the static previewer opens or its absolute path
+is reported after an opening failure.

package/templates/agents/skills/checklist/previewer/index.html

@@ -0,0 +1,38 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta http-equiv="Content-Security-Policy" content="default-src 'none'; script-src 'self'; style-src 'self'; img-src 'self' data:; base-uri 'none'; form-action 'none'">
+  <title>Checklist library</title>
+  <link rel="stylesheet" href="./viewer.css">
+</head>
+<body>
+  <header class="masthead">
+    <div class="masthead-inner">
+      <p class="eyebrow">Bearings / local checklist library</p>
+      <h1 id="title">Choose a checklist</h1>
+      <p id="summary" class="summary">Browse the checklists generated from this repository.</p>
+    </div>
+  </header>
+  <div class="toolbar">
+    <div class="toolbar-inner">
+      <label class="picker-label" for="checklist-picker">Checklist</label>
+      <select id="checklist-picker"><option value="">Loading...</option></select>
+      <div class="progress" aria-live="polite">
+        <span id="progress-copy">0 / 0 resolved</span>
+        <span class="progress-track" aria-hidden="true"><span id="progress-fill"></span></span>
+      </div>
+      <button id="export-progress" type="button">Export</button>
+      <button id="import-progress" type="button">Import</button>
+      <input id="import-file" type="file" accept="application/json,.json" hidden>
+      <button id="reset-progress" type="button">Reset</button>
+    </div>
+  </div>
+  <p id="storage-warning" class="storage-warning" role="status" hidden></p>
+  <p id="status" class="status" role="status" aria-live="polite"></p>
+  <main id="content"></main>
+  <script src="./data.generated.js"></script>
+  <script src="./viewer.js"></script>
+</body>
+</html>