coding-agent-harness 1.0.2 → 1.0.5

package/scripts/harness.mjs

@@ -6,26 +6,19 @@ import path from "node:path";
 import { createInterface } from "node:readline/promises";
 import {
   addCapability,
-  buildMigrationPlan,
   buildStatus,
-  confirmTaskReview,
-  createTask,
   doctorUserSkill,
   installUserSkill,
-  listLifecycleTasks,
   normalizeLocale,
-  promoteLessonCandidate,
-  runMigration,
+  rebuildGovernanceIndexes,
   serveDashboardWorkbench,
   validateSourcePackageBoundary,
-  updateModuleStep,
-  updateTaskPhase,
-  updateTaskLifecycle,
-  verifyMigrationSession,
-  writeDashboardFolder,
-  writeDashboardSingleFile,
   writeInitFiles,
 } from "./lib/harness-core.mjs";
+import { runDashboardCommand } from "./commands/dashboard-command.mjs";
+import { runMigrationCommand } from "./commands/migration-command.mjs";
+import { runPresetCommand } from "./commands/preset-command.mjs";
+import { runTaskCommand } from "./commands/task-command.mjs";
 
 const args = process.argv.slice(2);
 const command = args.shift() || "help";
@@ -94,24 +87,53 @@ Usage:
   harness init [--dry-run] [--locale zh-CN|en-US] [--capabilities core,dashboard] [--add-npm-scripts] [target]
   harness add-capability <name> [--dry-run] [--locale zh-CN|en-US] [target]
   harness migrate-plan [--json] [--limit n] [target]
+  harness migrate-task-audit-index [--plan] [--apply] [--json] [target]
   harness migrate-run [--locale zh-CN|en-US] [--assume-locale] [--allow-dirty] [--plan-only] [--out-dir folder] [--session-dir folder] [target]
   harness migrate-verify [--json] [--full-cutover] <session.json>
-  harness new-task <task-id> [--module key] [--budget simple|standard|complex] [--preset legacy-migration] [--from-session session.json] [--long-running] [--title title] [--locale zh-CN|en-US] [--dry-run] [target]
+  harness governance rebuild [--dry-run] [--archive] [--apply] [target]
+  harness preset list [--json] [target]
+  harness preset inspect <id> [--json] [target]
+  harness preset check <id> [--json] [target]
+  harness preset install <folder|zip|builtin-id> [--project] [--force] [--json] [target]
+  harness preset seed [--project] [--force] [--dry-run] [--json] [target]
+  harness preset uninstall <id> [--project] [--json] [target]
+  harness new-task [task-id] [--module key] [--budget simple|standard|complex] [--preset id] [--from-session session.json] [--long-running] [--title title] [--locale zh-CN|en-US] [--dry-run] [target]
   harness task-start <task-id> [--message text] [target]
   harness task-phase <task-id> <phase-id> [--state done] [--completion 100] [--evidence present] [target]
   harness task-log <task-id> --message text [--evidence type:PATH:summary] [target]
   harness task-block <task-id> [--message text] [target]
   harness task-review <task-id> [--message text] [target]
   harness review-confirm <task-id> --confirm task-id [--reviewer name] [--message text] [target]
-  harness lesson-promote <task-id> <candidate-id> [--dry-run] [target]
+  harness lesson-promote <task-id> <candidate-id> [--dry-run|--apply] [target]
+  harness lesson-sediment <task-id> <candidate-id> [--dry-run] [--title title] [target]
   harness task-complete <task-id> [--message text] [target]
-  harness task-list [--json] [--state state] [--module key] [target]
+  harness task-list [--json] [--state state] [--module key] [--queue queue] [--preset id] [--review status] [--lesson status] [--missing-materials] [--search text] [target]
+  harness task-index [--json] [target]
+  harness task-supersede <old-task-id> --by <new-task-id> [--reason text] [target]
+  harness task-delete <task-id> --soft [--reason text] [target]
+  harness task-archive <task-id> [--reason text] [target]
+  harness task-reopen <task-id> [--reason text] [target]
   harness module-step <module-key> <step-id> [--state done|in-progress|blocked] [target]
-  harness install-user [--agent codex|claude|gemini|openclaw|agents|all] [--home dir] [--dry-run] [--force] [--yes]
+  harness install-user [--agent codex|claude|gemini|openclaw|agents|all] [--home dir] [--dry-run] [--force] [--skip-presets] [--yes]
   harness doctor-user [--agent codex|claude|gemini|openclaw|agents|all] [--home dir]
 
 If init runs in an interactive terminal and --locale is omitted, it asks for a
 language. Non-interactive init defaults to en-US.
+
+Preset discovery:
+  Project presets live in <target>/.coding-agent-harness/presets/<preset-id>/.
+  User presets live in ~/.coding-agent-harness/presets/<preset-id>/.
+  Harness discovers project presets first when a target is supplied, then user
+  presets, then bundled package presets under presets/<preset-id>/.
+  "harness init" seeds bundled presets into the target project. "harness
+  install-user" and npm postinstall seed bundled presets into the user root.
+  Use "harness preset seed" to repair or re-run preset seeding.
+  Use "harness preset install" with a local preset folder, .zip archive, or
+  bundled preset id. Preset archives must contain preset.yaml at the archive
+  root or inside one top-level folder.
+  Use "harness preset list --json" to see available presets, their source,
+  purpose, compatible budgets, and manifest path. Use "harness preset inspect
+  <id> --json" for the full preset manifest summary.
 `);
 }
 
@@ -123,6 +145,8 @@ function exitWithReport(report) {
 
 if (command === "help" || command === "--help" || command === "-h") {
   printHelp();
+} else if (args[0] === "help" || args.includes("--help") || args.includes("-h")) {
+  printHelp();
 } else if (command === "check") {
   const profile = takeOption("--profile", "target-project");
   const strict = takeFlag("--strict");
@@ -166,8 +190,9 @@ if (command === "help" || command === "--help" || command === "-h") {
   const port = takeOption("--port", "0");
   const localeOverride = takeOption("--locale", "");
   const target = targetArg();
+  const usesDefaultOutDir = !outDir;
   const dashboardOutDir = outDir || defaultDevOutDir(target);
-  const opts = localeOverride ? { localeOverride } : {};
+  const opts = { ...(localeOverride ? { localeOverride } : {}), recoverGeneratedDashboard: usesDefaultOutDir };
   try {
     await serveDashboardWorkbench(dashboardOutDir, target, { ...opts, host, port, autoRefresh: true, open, label: "harness dev" });
   } catch (error) {
@@ -175,63 +200,7 @@ if (command === "help" || command === "--help" || command === "-h") {
     process.exit(1);
   }
 } else if (command === "dashboard") {
-  const watch = takeFlag("--watch");
-  const workbench = takeFlag("--workbench");
-  const out = takeOption("--out", "harness-dashboard.html");
-  const outDir = takeOption("--out-dir", "");
-  const host = takeOption("--host", "127.0.0.1");
-  const port = takeOption("--port", "0");
-  const localeOverride = takeOption("--locale", "");
-  const opts = localeOverride ? { localeOverride } : {};
-  if (workbench) {
-    if (!outDir) {
-      console.error("dashboard --workbench requires --out-dir so regenerated data has a stable folder");
-      process.exit(2);
-    }
-    try {
-      await serveDashboardWorkbench(outDir, targetArg(), { ...opts, host, port });
-    } catch (error) {
-      console.error(error.message);
-      process.exit(1);
-    }
-  }
-  if (watch) {
-    if (!outDir) {
-      console.error("dashboard --watch requires --out-dir so updates are written to a stable folder");
-      process.exit(2);
-    }
-    const target = targetArg();
-    const docsRoot = path.basename(path.resolve(target)) === "docs" ? path.resolve(target) : path.join(path.resolve(target), "docs");
-    const regenerate = () => {
-      try {
-        console.log(writeDashboardFolder(outDir, target, opts));
-        console.log(`dashboard regenerated: ${new Date().toISOString()}`);
-      } catch (error) {
-        console.error(`dashboard regeneration failed: ${error.message}`);
-      }
-    };
-    regenerate();
-    let timer = null;
-    const watcher = fs.watch(docsRoot, { recursive: true }, () => {
-      clearTimeout(timer);
-      timer = setTimeout(regenerate, 300);
-    });
-    const close = () => {
-      watcher.close();
-      clearTimeout(timer);
-      process.exit(0);
-    };
-    process.on("SIGINT", close);
-    process.on("SIGTERM", close);
-    console.log(`watching ${docsRoot}`);
-    await new Promise(() => {});
-  }
-  if (outDir) {
-    console.log(writeDashboardFolder(outDir, targetArg(), opts));
-  } else {
-    console.log(writeDashboardSingleFile(out, targetArg(), opts));
-  }
-  process.exit(0);
+  await runDashboardCommand({ takeFlag, takeOption, targetArg });
 } else if (command === "init") {
   const dryRun = takeFlag("--dry-run");
   const addNpmScripts = takeFlag("--add-npm-scripts");
@@ -239,7 +208,7 @@ if (command === "help" || command === "--help" || command === "-h") {
   const capabilities = takeOption("--capabilities", "core").split(",").map((item) => item.trim()).filter(Boolean);
   try {
     const result = writeInitFiles(targetArg(), capabilities, { dryRun, locale, addNpmScripts });
-    console.log(JSON.stringify({ dryRun, locale: result.locale, capabilities: result.capabilities, changes: result.changes, nextCommands: result.nextCommands, report: result.report }, null, 2));
+    console.log(JSON.stringify({ dryRun, locale: result.locale, capabilities: result.capabilities, changes: result.changes, presetSeed: result.presetSeed, nextCommands: result.nextCommands, report: result.report }, null, 2));
   } catch (error) {
     console.error(error.message);
     process.exit(1);
@@ -259,202 +228,32 @@ if (command === "help" || command === "--help" || command === "-h") {
     console.error(error.message);
     process.exit(1);
   }
-} else if (command === "migrate-plan") {
-  const json = takeFlag("--json");
-  const limit = Number.parseInt(takeOption("--limit", "20"), 10) || 20;
-  try {
-    const plan = buildMigrationPlan(targetArg(), { limit });
-    if (json) {
-      console.log(JSON.stringify(plan, null, 2));
-    } else {
-      console.log(`Migration Plan: ${plan.target}`);
-      console.log(`mode: ${plan.mode}`);
-      console.log(`warnings: ${plan.summary.warnings}`);
-      console.log(`task actions: ${plan.summary.taskActions}`);
-      console.log(`visual map actions: ${plan.summary.visualMapActions}`);
-      console.log(`legacy visual-only tasks: ${plan.summary.legacyVisualOnly}`);
-      console.log(`weak briefs: ${plan.summary.weakBrief}`);
-      console.log(`unknown classifications: ${plan.summary.unknownClassification}`);
-      console.log(`full cutover eligible: ${plan.summary.fullCutoverEligible ? "yes" : "no"}`);
-      console.log(`review actions: ${plan.summary.reviewSchemaGaps}`);
-      console.log(`legacy actions: ${plan.summary.legacyReferenceGaps}`);
-      console.log(`legacy residuals: ${plan.summary.legacyResiduals}`);
-      console.log(`recommended capabilities: ${plan.summary.recommendedCapabilities.join(", ") || "none"}`);
-      console.log("\nPhases:");
-      for (const phase of plan.phases) console.log(`- ${phase.id}: ${phase.title}`);
-      console.log("\nTop task actions:");
-      for (const action of plan.taskActions) console.log(`- ${action.taskId}: add ${action.files.join(", ")}`);
-      console.log("\nTop review actions:");
-      for (const action of plan.reviewActions) console.log(`- ${action.path}: add ${action.missing.join(", ")}`);
-      console.log("\nTop legacy residuals:");
-      for (const action of plan.legacyResiduals) console.log(`- ${action.taskId}: ${action.missing} (${action.reason})`);
-      console.log("\nNext commands:");
-      for (const next of plan.nextCommands) console.log(`- ${next}`);
-    }
-  } catch (error) {
-    console.error(error.message);
-    process.exit(1);
-  }
-} else if (command === "migrate-run") {
-  const locale = takeOption("--locale", "");
-  const assumeLocale = takeFlag("--assume-locale");
-  const allowDirty = takeFlag("--allow-dirty");
-  const planOnly = takeFlag("--plan-only");
-  const outDir = takeOption("--out-dir", "");
-  const sessionDir = takeOption("--session-dir", "");
-  try {
-    console.log(
-      JSON.stringify(
-        runMigration(targetArg(), {
-          locale,
-          assumeLocale,
-          allowDirty,
-          planOnly,
-          outDir,
-          sessionDir,
-        }),
-        null,
-        2,
-      ),
-    );
-  } catch (error) {
-    console.error(error.message);
-    process.exit(1);
-  }
-} else if (command === "migrate-verify") {
-  const json = takeFlag("--json");
-  const fullCutover = takeFlag("--full-cutover");
-  const sessionPath = args.shift();
-  if (!sessionPath) {
-    console.error("Missing session.json path");
+} else if (["migrate-plan", "migrate-run", "migrate-verify", "migrate-task-audit-index"].includes(command)) {
+  runMigrationCommand(command, { args, takeFlag, takeOption, targetArg });
+} else if (command === "governance") {
+  const subcommand = args.shift() || "";
+  if (subcommand !== "rebuild") {
+    console.error(`Unknown governance subcommand: ${subcommand || "(missing)"}`);
     process.exit(2);
   }
-  const result = verifyMigrationSession(sessionPath, { fullCutover });
-  if (json) {
-    console.log(JSON.stringify(result, null, 2));
-  } else {
-    for (const failure of result.failures) console.error(`Failure: ${failure}`);
-    for (const warning of result.warnings) console.log(`Warning: ${warning}`);
-    console.log(`Migration verify ${result.status}: ${result.sessionPath}`);
-  }
-  process.exit(result.status === "pass" ? 0 : 1);
-} else if (command === "new-task") {
   const dryRun = takeFlag("--dry-run");
-  const locale = takeOption("--locale", "");
-  const title = takeOption("--title", "");
-  const moduleKey = takeOption("--module", "");
-  const budget = takeOption("--budget", "standard");
-  const preset = takeOption("--preset", "");
-  const fromSession = takeOption("--from-session", "");
-  const longRunning = takeFlag("--long-running");
-  const taskId = args.shift() || (fromSession ? "harness-v1-migration" : "");
-  if (!taskId) {
-    console.error("Missing task id");
-    process.exit(2);
-  }
-  try {
-    console.log(JSON.stringify(createTask(targetArg(), taskId, { title, locale, dryRun, moduleKey, budget, longRunning, preset, fromSession }), null, 2));
-  } catch (error) {
-    console.error(error.message);
-    process.exit(1);
-  }
-} else if (command === "task-phase") {
-  const state = takeOption("--state", "");
-  const completion = takeOption("--completion", "");
-  const evidenceStatus = takeOption("--evidence", "");
-  const taskId = args.shift();
-  const phaseId = args.shift();
-  if (!taskId || !phaseId) {
-    console.error("Missing task id or phase id");
-    process.exit(2);
-  }
-  try {
-    console.log(JSON.stringify(updateTaskPhase(targetArg(), taskId, phaseId, { state, completion, evidenceStatus }), null, 2));
-  } catch (error) {
-    console.error(error.message);
-    process.exit(1);
-  }
-} else if (["task-start", "task-log", "task-block", "task-review", "task-complete"].includes(command)) {
-  const message = takeOption("--message", "");
-  const evidence = takeOption("--evidence", "");
-  const taskId = args.shift();
-  if (!taskId) {
-    console.error("Missing task id");
-    process.exit(2);
-  }
-  const lifecycle = {
-    "task-start": { event: "task-start", state: "in_progress" },
-    "task-log": { event: "task-log", state: "" },
-    "task-block": { event: "task-block", state: "blocked" },
-    "task-review": { event: "task-review", state: "review" },
-    "task-complete": { event: "task-complete", state: "done" },
-  }[command];
-  try {
-    console.log(JSON.stringify(updateTaskLifecycle(targetArg(), taskId, { ...lifecycle, message, evidence }), null, 2));
-  } catch (error) {
-    console.error(error.message);
-    process.exit(1);
-  }
-} else if (command === "review-confirm") {
-  const reviewer = takeOption("--reviewer", "Human Reviewer");
-  const message = takeOption("--message", "");
-  const evidence = takeOption("--evidence", "");
-  const confirmText = takeOption("--confirm", "");
-  const taskId = args.shift();
-  if (!taskId) {
-    console.error("Missing task id");
-    process.exit(2);
-  }
-  try {
-    console.log(JSON.stringify(confirmTaskReview(targetArg(), taskId, { reviewer, message, evidence, confirmText }), null, 2));
-  } catch (error) {
-    console.error(error.message);
-    process.exit(1);
-  }
-} else if (command === "lesson-promote") {
-  const dryRun = takeFlag("--dry-run");
-  const taskId = args.shift();
-  const candidateId = args.shift();
-  if (!taskId || !candidateId) {
-    console.error("Missing task id or candidate id");
-    process.exit(2);
-  }
-  try {
-    console.log(JSON.stringify(promoteLessonCandidate(targetArg(), taskId, candidateId, { dryRun }), null, 2));
-  } catch (error) {
-    console.error(error.message);
-    process.exit(1);
-  }
-} else if (command === "task-list") {
-  const json = takeFlag("--json");
-  const state = takeOption("--state", "");
-  const moduleKey = takeOption("--module", "");
-  const result = listLifecycleTasks(targetArg(), { state, moduleKey });
-  if (json) {
-    console.log(JSON.stringify(result, null, 2));
-  } else {
-    for (const task of result.tasks) {
-      console.log(`${task.id}\t${task.state}\t${task.completion}%\t${task.title}`);
-    }
-  }
-} else if (command === "module-step") {
-  const state = takeOption("--state", "done");
-  const moduleKey = args.shift();
-  const stepId = args.shift();
-  if (!moduleKey || !stepId) {
-    console.error("Missing module key or step id");
-    process.exit(2);
-  }
+  const archive = takeFlag("--archive");
+  const apply = takeFlag("--apply");
   try {
-    console.log(JSON.stringify(updateModuleStep(targetArg(), moduleKey, stepId, { state }), null, 2));
+    console.log(JSON.stringify(rebuildGovernanceIndexes(targetArg(), { dryRun, archive, apply }), null, 2));
   } catch (error) {
     console.error(error.message);
     process.exit(1);
   }
+} else if (command === "preset") {
+  runPresetCommand({ args, takeFlag, targetArg });
+} else if (["new-task", "task-phase", "task-start", "task-log", "task-block", "task-review", "task-complete", "review-confirm", "lesson-promote", "lesson-sediment", "task-list", "task-index", "task-supersede", "task-delete", "task-archive", "task-reopen", "module-step"].includes(command)) {
+  runTaskCommand(command, { args, takeFlag, takeOption, targetArg });
 } else if (command === "install-user") {
   const dryRun = takeFlag("--dry-run");
   const force = takeFlag("--force");
   const yes = takeFlag("--yes") || takeFlag("-y");
+  const skipPresets = takeFlag("--skip-presets");
   takeFlag("--global");
   const agent = takeOption("--agent", "codex");
   const home = takeOption("--home", "");
@@ -463,7 +262,7 @@ if (command === "help" || command === "--help" || command === "-h") {
     process.exit(2);
   }
   try {
-    console.log(JSON.stringify(installUserSkill({ agent, home, dryRun, force }), null, 2));
+    console.log(JSON.stringify(installUserSkill({ agent, home, dryRun, force, seedPresets: !skipPresets }), null, 2));
   } catch (error) {
     console.error(error.message);
     process.exit(1);

package/scripts/lib/capability-registry.mjs

@@ -10,11 +10,14 @@ import {
   exists,
   existsInDocs,
   readFileSafe,
+  readJsonSafe,
   readBundledTemplate,
   walkFiles,
   normalizeLocale,
   localizedTemplateSource,
+  userPresetRootForHome,
 } from "./core-shared.mjs";
+import { listBundledPresetIds, seedBundledPresets } from "./preset-registry.mjs";
 
 export const capabilityDefinitions = {
   core: {
@@ -94,8 +97,9 @@ export function readCapabilityRegistry(target) {
     };
   }
 
-  try {
-    const raw = JSON.parse(fs.readFileSync(registryPath, "utf8"));
+  let readError = null;
+  const raw = readJsonSafe(registryPath, null, { onError: (error) => { readError = error; } });
+  if (raw) {
     const locale = normalizeLocale(raw.locale);
     const capabilities = Array.isArray(raw.capabilities)
       ? raw.capabilities.map((entry) =>
@@ -105,9 +109,8 @@ export function readCapabilityRegistry(target) {
         )
       : [];
     return { mode: "declared-capability", path: registryPath, capabilities, raw, locale, errors: [] };
-  } catch (error) {
-    return { mode: "declared-capability", path: registryPath, capabilities: [], raw: null, errors: [error.message] };
   }
+  return { mode: "declared-capability", path: registryPath, capabilities: [], raw: null, errors: [readError?.message || "invalid .harness-capabilities.json"] };
 }
 
 export function normalizeCapabilityName(name) {
@@ -124,12 +127,53 @@ export function validateSourcePackageBoundary(targetInput = ".") {
     .split("\0")
     .filter(Boolean)
     .filter((file) => file === "AGENTS.md" || file === "CLAUDE.md" || file === "docs" || file.startsWith("docs/") || file === ".harness-private" || file.startsWith(".harness-private/"));
+  const tracked = spawnSync("git", ["-C", root, "ls-files", "-z", "--", "harness-dashboard.html"], { encoding: "utf8" });
+  const generatedRootDashboard = tracked.status === 0
+    ? tracked.stdout.split("\0").filter(Boolean)
+      .filter((file) => fs.existsSync(path.join(root, file)))
+    : [];
+  const internalScripts = ["scripts/test-harness.mjs", "scripts/smoke-dashboard.mjs"]
+    .filter((file) => fs.existsSync(path.join(root, file)));
+  const dashboardAppDrift = validateDashboardAppAssembly(root);
+  const dashboardCssDrift = validateDashboardAssetAssembly(root, "app.css.manifest.json", "app.css", "dashboard assets/app.css does not match css-src manifest assembly");
   return {
-    failures: localOnly.map((file) => `private local-only file staged: ${file}`),
-    warnings: [],
+    failures: [
+      ...localOnly.map((file) => `private local-only file staged: ${file}`),
+      ...generatedRootDashboard.map((file) => `generated dashboard file tracked in source root: ${file}`),
+      ...internalScripts.map((file) => `internal test/smoke file in publishable scripts directory: ${file}`),
+      ...dashboardAppDrift,
+      ...dashboardCssDrift,
+    ],
+    warnings: tracked.status === 0 ? [] : [`could not inspect tracked generated dashboard files: ${tracked.stderr.trim() || tracked.status}`],
   };
 }
 
+function validateDashboardAppAssembly(root) {
+  return validateDashboardAssetAssembly(root, "app.manifest.json", "app.js", "dashboard assets/app.js does not match app-src manifest assembly");
+}
+
+function validateDashboardAssetAssembly(root, manifestName, assetName, driftMessage) {
+  const assetsDir = path.join(root, "templates/dashboard/assets");
+  const manifestPath = path.join(assetsDir, manifestName);
+  const assetPath = path.join(assetsDir, assetName);
+  if (!fs.existsSync(manifestPath) || !fs.existsSync(assetPath)) return [];
+  try {
+    const manifest = readJsonSafe(manifestPath, null);
+    if (!Array.isArray(manifest) || manifest.length === 0) {
+      return [`dashboard asset manifest must list source files: ${manifestName}`];
+    }
+    const assembled = `${manifest.map((relativePath) => {
+      const source = path.join(assetsDir, relativePath);
+      if (!fs.existsSync(source)) throw new Error(`missing ${relativePath}`);
+      return fs.readFileSync(source, "utf8").trimEnd();
+    }).join("\n\n")}\n`;
+    const trackedAsset = fs.readFileSync(assetPath, "utf8");
+    return trackedAsset === assembled ? [] : [driftMessage];
+  } catch (error) {
+    return [`could not validate dashboard asset assembly (${assetName}): ${error.message}`];
+  }
+}
+
 export function detectCapabilities(target) {
   const detected = new Set(["core"]);
   if (existsInDocs(target, "09-PLANNING/Module-Registry.md")) detected.add("module-parallel");
@@ -164,6 +208,7 @@ export function buildInstallReport({ target, locale, capabilities, changes, dryR
     agentInstructions: [
       "Agents must choose locale during Decide and pass --locale zh-CN|en-US explicitly in non-interactive installs.",
       "Use core for every install; add optional capabilities only when their selectWhen rule is true.",
+      "Bundled presets are seeded during init; use harness preset list --json before choosing task presets.",
       "After scaffold, run Configure before marking capabilities configured or verified.",
       "Run harness check/status/dashboard and record residuals before delivery.",
     ],
@@ -177,7 +222,7 @@ export function buildInstallReport({ target, locale, capabilities, changes, dryR
 
 function packageVersion() {
   try {
-    const pkg = JSON.parse(fs.readFileSync(path.join(repoRoot, "package.json"), "utf8"));
+    const pkg = readJsonSafe(path.join(repoRoot, "package.json"), {});
     return pkg.version || "";
   } catch {
     return "";
@@ -209,6 +254,7 @@ function skillPackageEntries() {
     "references",
     "templates",
     "templates-zh-CN",
+    "presets",
     "scripts",
     "docs-release",
     "examples",
@@ -216,19 +262,14 @@ function skillPackageEntries() {
 }
 
 function listPackageFiles() {
-  const files = [];
-  function walk(relativePath) {
-    const full = path.join(repoRoot, relativePath);
-    if (!fs.existsSync(full)) return;
-    const stat = fs.statSync(full);
-    if (stat.isDirectory()) {
-      for (const entry of fs.readdirSync(full)) walk(path.join(relativePath, entry));
-      return;
-    }
-    if (stat.isFile()) files.push(toPosix(relativePath));
-  }
-  for (const entry of skillPackageEntries()) walk(entry);
-  return files.sort();
+  return skillPackageEntries()
+    .flatMap((entry) => {
+      const fullPath = path.join(repoRoot, entry);
+      if (!fs.existsSync(fullPath)) return [];
+      if (fs.statSync(fullPath).isFile()) return [toPosix(path.relative(repoRoot, fullPath))];
+      return walkFiles(fullPath).map((file) => toPosix(path.relative(repoRoot, file)));
+    })
+    .sort();
 }
 
 function copySkillPackage(targetRoot, { dryRun = false, force = false } = {}) {
@@ -246,7 +287,7 @@ function copySkillPackage(targetRoot, { dryRun = false, force = false } = {}) {
   return changes;
 }
 
-export function installUserSkill({ agent = "codex", home = "", dryRun = false, force = false } = {}) {
+export function installUserSkill({ agent = "codex", home = "", dryRun = false, force = false, seedPresets = true } = {}) {
   const agents = normalizeUserAgent(agent);
   const targets = agents.map((targetAgent) => {
     const target = targetForUserAgent(targetAgent, home);
@@ -260,8 +301,11 @@ export function installUserSkill({ agent = "codex", home = "", dryRun = false, f
       skipped: changes.filter((change) => change.action === "skip-existing").length,
     };
   });
-  const changed = targets.some((target) => target.created > 0 || target.overwritten > 0);
-  const onlySkipped = targets.every((target) => target.created === 0 && target.overwritten === 0 && target.skipped > 0);
+  const presetSeed = seedPresets ? seedBundledPresets({ scope: "user", home, dryRun, force }) : null;
+  const changed = targets.some((target) => target.created > 0 || target.overwritten > 0) || (presetSeed && (presetSeed.created > 0 || presetSeed.overwritten > 0));
+  const onlySkipped =
+    targets.every((target) => target.created === 0 && target.overwritten === 0 && target.skipped > 0) &&
+    (!presetSeed || presetSeed.presets.every((preset) => preset.action === "skip-existing"));
   return {
     operation: "install-user",
     status: dryRun ? "dry-run" : changed ? "installed" : onlySkipped ? "already-present" : "no-op",
@@ -269,13 +313,14 @@ export function installUserSkill({ agent = "codex", home = "", dryRun = false, f
     force,
     version: packageVersion(),
     source: repoRoot,
+    presets: presetSeed,
     targets,
   };
 }
 
 function readInstalledVersion(targetRoot) {
   try {
-    const pkg = JSON.parse(fs.readFileSync(path.join(targetRoot, "package.json"), "utf8"));
+    const pkg = readJsonSafe(path.join(targetRoot, "package.json"), {});
     return pkg.version || "";
   } catch {
     return "";
@@ -301,6 +346,7 @@ export function doctorUserSkill({ agent = "codex", home = "" } = {}) {
     "references",
     "templates",
     "templates-zh-CN",
+    "presets",
     "scripts/harness.mjs",
     "docs-release/guides/agent-installation.md",
   ];
@@ -315,12 +361,20 @@ export function doctorUserSkill({ agent = "codex", home = "" } = {}) {
       missing,
     };
   });
+  const presetRoot = userPresetRootForHome(home);
+  const missingPresets = listBundledPresetIds().filter((id) => !fs.existsSync(path.join(presetRoot, id, "preset.yaml")));
+  const presets = {
+    root: presetRoot,
+    status: missingPresets.length === 0 ? "pass" : "fail",
+    missing: missingPresets,
+  };
   const harnessCommand = commandOnPath("harness");
   return {
     operation: "doctor-user",
-    status: targets.every((target) => target.status === "pass") ? "pass" : "fail",
+    status: targets.every((target) => target.status === "pass") && presets.status === "pass" ? "pass" : "fail",
     version: packageVersion(),
     harnessCommand: harnessCommand || null,
+    presets,
     targets,
   };
 }
@@ -399,7 +453,6 @@ export function plannedInitFiles(capabilities = ["core"], { locale = "en-US" } =
     ["docs/09-PLANNING/TASKS/_task-template/review.md", "templates/planning/review.md"],
     ["docs/05-TEST-QA/Regression-SSoT.md", "templates/ssot/Regression-SSoT.md"],
     ["docs/05-TEST-QA/Cadence-Ledger.md", "templates/regression/Cadence-Ledger.md"],
-    ["docs/01-GOVERNANCE/Lessons-SSoT.md", "templates/ssot/Lessons-SSoT.md"],
     ["docs/10-WALKTHROUGH/_walkthrough-template.md", "templates/walkthrough/walkthrough-template.md"],
     ["docs/10-WALKTHROUGH/Closeout-SSoT.md", "templates/walkthrough/Closeout-SSoT.md"],
     ["docs/11-REFERENCE/external-source-intake-standard.md", "templates/reference/external-source-intake-standard.md"],
@@ -464,8 +517,9 @@ export function writeInitFiles(targetInput, capabilities, { dryRun = true, local
     const registryPath = path.join(target.projectRoot, ".harness-capabilities.json");
     if (!fs.existsSync(registryPath)) fs.writeFileSync(registryPath, `${JSON.stringify(registry, null, 2)}\n`);
   }
+  const presetSeed = seedBundledPresets({ scope: "project", targetInput: target.projectRoot, dryRun });
   const report = buildInstallReport({ target, locale: normalizedLocale, capabilities: normalizedCapabilities, changes, dryRun, operation: "init" });
-  return { target, capabilities: normalizedCapabilities, locale: normalizedLocale, changes, nextCommands: initNextCommands(), report };
+  return { target, capabilities: normalizedCapabilities, locale: normalizedLocale, changes, presetSeed, nextCommands: initNextCommands(), report };
 }
 
 function initNextCommands() {
@@ -478,7 +532,7 @@ function initNextCommands() {
 function writeNpmScripts(target, { dryRun = true } = {}) {
   const packagePath = path.join(target.projectRoot, "package.json");
   if (!fs.existsSync(packagePath)) throw new Error("init --add-npm-scripts requires an existing package.json");
-  const pkg = JSON.parse(fs.readFileSync(packagePath, "utf8"));
+  const pkg = readJsonSafe(packagePath, {});
   const scripts = { ...(pkg.scripts || {}) };
   const additions = {
     "harness:dev": "coding-agent-harness dev .",