@namewta/speculo 0.7.1 → 0.7.3

package/template/skills/migrate-runtime-state/scripts/migrate-runtime-state.mjs

@@ -8,6 +8,7 @@ import {
   mkdtemp,
   readFile,
   readdir,
+  readlink,
   rename,
   rm,
   writeFile,
@@ -26,7 +27,7 @@ function usage() {
     "  node migrate-runtime-state.mjs fingerprint --project-root <path> --target <relative-path>",
     "  node migrate-runtime-state.mjs apply --project-root <path> --plan <plan.json> --confirmed",
     "",
-    "inspect and fingerprint are read-only. apply requires an explicit confirmed schema-v1 plan.",
+    "inspect and fingerprint are read-only. apply requires an explicit confirmed schema-v2 plan.",
     "",
   ].join("\n"));
   return 2;
@@ -101,7 +102,7 @@ async function walk(root, current = root, options = {}) {
       values.push({ path: item, type: "directory" });
       values.push(...await walk(root, path, options));
     } else if (entry.isSymbolicLink()) {
-      values.push({ path: item, type: "symlink" });
+      values.push({ path: item, type: "symlink", target: await readlink(path) });
     } else if (entry.isFile()) {
       const stat = await lstat(path);
       values.push({ path: item, type: "file", bytes: stat.size, sha256: await sha256(path) });
@@ -164,6 +165,9 @@ async function validateBackup(ctx, checkMigrationWorkspace = true) {
       if (entry.type === "file" && (typeof entry.sha256 !== "string" || typeof entry.bytes !== "number")) {
         throw new Error("file manifest entry has no hash or size: " + item);
       }
+      if (entry.type === "symlink" && typeof entry.target !== "string") {
+        throw new Error("symlink manifest entry has no target: " + item);
+      }
       expected.set(item, entry);
     } catch (error) {
       issues.push(String(error));
@@ -177,8 +181,10 @@ async function validateBackup(ctx, checkMigrationWorkspace = true) {
       issues.push("undeclared backup entry: " + entry.path);
       continue;
     }
-    if (entry.type === "symlink" || declared.type === "symlink") {
-      issues.push("backup symlink requires manual recovery outside this command: " + entry.path);
+    if (entry.type !== declared.type) {
+      issues.push("backup entry type mismatch: " + entry.path);
+    } else if (entry.type === "symlink") {
+      if (entry.target !== declared.target) issues.push("backup symlink target mismatch: " + entry.path);
     } else if (entry.sha256 !== declared.sha256 || entry.bytes !== declared.bytes) {
       issues.push("backup hash or size mismatch: " + entry.path);
     }
@@ -244,51 +250,74 @@ function pathsOverlap(left, right) {
 }
 
 async function validatePlan(ctx, plan) {
-  if (plan.schema_version !== 1 || !Array.isArray(plan.source_decisions) || !Array.isArray(plan.actions)) {
-    throw new Error("Plan must use schema_version 1 and contain source_decisions and actions");
+  if (plan.schema_version !== 2 || !Array.isArray(plan.source_decisions) || !Array.isArray(plan.actions)) {
+    throw new Error("Plan must use schema_version 2 and contain source_decisions and actions");
   }
   if (plan.backup_manifest_sha256 !== await sha256(ctx.manifestPath)) throw new Error("Plan backup manifest fingerprint does not match");
   const install = await readJson(join(ctx.stateRoot, "install.json"));
   const workflows = Array.isArray(install.workflows) ? install.workflows.filter((item) => typeof item === "string") : [];
   const expectedSources = new Set(ctx.manifest.files.map((entry) => entry.path));
-  const seenSources = new Set();
+  const decisions = new Map();
   for (const [index, decision] of plan.source_decisions.entries()) {
     if (!decision || typeof decision !== "object" || !VALID_DECISIONS.has(decision.disposition)) {
       throw new Error(`source_decisions[${index}] has an invalid disposition`);
     }
     const source = safeRelative(decision.path, `source_decisions[${index}] path`);
     if (!expectedSources.has(source)) throw new Error(`source_decisions[${index}] is not in the backup manifest: ${source}`);
-    if (seenSources.has(source)) throw new Error(`source_decisions[${index}] repeats ${source}`);
+    if (decisions.has(source)) throw new Error(`source_decisions[${index}] repeats ${source}`);
     if (typeof decision.target !== "string" || !allowedDecisionTarget(decision.target, decision.disposition, workflows)) {
       throw new Error(`source_decisions[${index}] target is outside runtime ownership: ${decision.target}`);
     }
-    seenSources.add(source);
+    decisions.set(source, decision);
   }
   for (const source of expectedSources) {
-    if (!seenSources.has(source)) throw new Error("Plan has no decision for backup entry: " + source);
+    if (!decisions.has(source)) throw new Error("Plan has no decision for backup entry: " + source);
   }
+
+  const actionSources = new Set();
   const seenTargets = new Set();
   for (const [index, action] of plan.actions.entries()) {
     if (!action || typeof action !== "object" || !VALID_ACTIONS.has(action.kind)) throw new Error(`actions[${index}] has an invalid kind`);
-    if (!allowedTarget(action.to, workflows)) throw new Error(`actions[${index}] target is outside runtime ownership: ${action.to}`);
+    if (typeof action.source_decision !== "string") throw new Error(`actions[${index}] must explicitly name source_decision`);
+    const actionSource = safeRelative(action.source_decision, `actions[${index}] source_decision`);
+    const decision = decisions.get(actionSource);
+    if (!decision) throw new Error(`actions[${index}] source_decision is not in source_decisions: ${actionSource}`);
+    if (actionSources.has(actionSource)) throw new Error(`actions[${index}] duplicates source action: ${actionSource}`);
+    actionSources.add(actionSource);
+    if (typeof action.to !== "string" || !allowedTarget(action.to, workflows)) {
+      throw new Error(`actions[${index}] target is outside runtime ownership: ${action.to}`);
+    }
+    if (decision.target !== action.to) throw new Error(`actions[${index}] target must match source decision target`);
     for (const target of seenTargets) {
       if (pathsOverlap(target, action.to)) throw new Error(`actions[${index}] overlaps target ${target}`);
     }
     seenTargets.add(action.to);
     if (action.kind === "copy") {
-      const sourcePath = safeRelative(action.from, `actions[${index}] source`);
-      if (sourcePath !== "config.json" && !sourcePath.startsWith("state/")) throw new Error(`actions[${index}] source is outside backup data: ${action.from}`);
-      const source = inside(ctx.backupRoot, action.from);
-      if (!(await exists(source))) throw new Error(`actions[${index}] source does not exist: ${action.from}`);
-    }
-    if (action.kind === "replace-json") {
+      if (decision.disposition !== "restore") throw new Error(`actions[${index}] copy must implement a restore decision`);
+      if (action.from !== actionSource) throw new Error(`actions[${index}] copy source must match source_decision`);
+      const source = inside(ctx.backupRoot, actionSource);
+      if (!(await exists(source))) throw new Error(`actions[${index}] source does not exist: ${actionSource}`);
+    } else if (action.kind === "replace-json") {
+      if (!new Set(["merge-json", "replace-json"]).has(decision.disposition)) {
+        throw new Error(`actions[${index}] replace-json must implement a merge-json or replace-json decision`);
+      }
       if (!action.to.endsWith(".json") || action.value === undefined) throw new Error(`actions[${index}] replace-json needs a JSON target and value`);
       JSON.stringify(action.value);
+    } else if (action.kind === "keep-current") {
+      if (decision.disposition !== "keep-current") throw new Error(`actions[${index}] keep-current must implement a keep-current decision`);
+    } else if (decision.disposition !== "remove-current") {
+      throw new Error(`actions[${index}] remove-current must implement a remove-current decision`);
     }
     if (typeof action.expected_target !== "string") throw new Error(`actions[${index}] must contain expected_target`);
     const currentFingerprint = await fingerprint(inside(ctx.speculoRoot, action.to));
     if (currentFingerprint !== action.expected_target) throw new Error(`actions[${index}] target drifted: ${action.to}`);
   }
+
+  for (const [source, decision] of decisions) {
+    if (decision.disposition !== "keep-current" && !actionSources.has(source)) {
+      throw new Error(`source_decisions entry requires an action: ${source}`);
+    }
+  }
   return workflows;
 }
 
@@ -305,13 +334,265 @@ async function validateJsonTree(root) {
   return failures;
 }
 
+function isObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasExactKeys(value, expected) {
+  const actual = Object.keys(value).sort();
+  const wanted = [...expected].sort();
+  return actual.length === wanted.length && actual.every((key, index) => key === wanted[index]);
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+
+function stringOrNull(value) {
+  return value === null || typeof value === "string";
+}
+
+function stringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+const CHANGE_NAME_PATTERN = /^[0-9]{4}-[0-9]{2}-[0-9]{2}-[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const ARCHIVE_PATH_PATTERN = /^<Path>\{roots\.state\}\/specdev\/archive\/[^<]+<\/Path>$/;
+const EVIDENCE_PATH_PATTERN = /^<Path>\{roots\.state\}\/specdev\/changes\/[^<]+\/evidence\/T-[0-9]{2,}\.md<\/Path>$/;
+
+function validIntegrationV4(integration, worktreeStatus, sourceCheckpoint, change, ticketId) {
+  const required = [
+    "status", "parent_before_sha", "source_sha", "candidate_sha", "candidate_branch",
+    "candidate_workspace_ref", "result_sha", "method", "conflict_paths", "verification",
+    "e2e", "evidence", "attempts",
+  ];
+  if (!isObject(integration) || !hasExactKeys(integration, required)) return false;
+  if (!new Set(["pending", "candidate", "passed", "failed", "stale"]).has(integration.status)) return false;
+  if (!new Set([null, "fast-forward", "merge-commit"]).has(integration.method)) return false;
+  if (!new Set(["pending", "passed", "failed"]).has(integration.verification)) return false;
+  for (const key of ["parent_before_sha", "source_sha", "candidate_sha", "candidate_branch", "result_sha"]) {
+    if (!stringOrNull(integration[key])) return false;
+  }
+  if (
+    integration.candidate_workspace_ref !== null &&
+    (typeof integration.candidate_workspace_ref !== "string" ||
+      !/^specdev-worktree\/\.integration\/T-[0-9]{2,}$/.test(integration.candidate_workspace_ref))
+  ) return false;
+  if (!stringArray(integration.conflict_paths)) return false;
+  if (!Number.isInteger(integration.attempts) || integration.attempts < 0) return false;
+  if (
+    typeof integration.evidence !== "string" ||
+    !EVIDENCE_PATH_PATTERN.test(integration.evidence) ||
+    integration.evidence !== `<Path>{roots.state}/specdev/changes/${change}/evidence/${ticketId}.md</Path>`
+  ) return false;
+
+  const e2e = integration.e2e;
+  if (!isObject(e2e) || !hasExactKeys(e2e, ["required", "status", "evidence"])) return false;
+  if (typeof e2e.required !== "boolean" || !new Set(["not-required", "pending", "passed", "failed"]).has(e2e.status)) return false;
+  if (!stringOrNull(e2e.evidence)) return false;
+  if (e2e.required === false && e2e.status !== "not-required") return false;
+  if (e2e.required === true && e2e.status === "not-required") return false;
+  if (e2e.required === true && e2e.status === "passed" && !nonEmptyString(e2e.evidence)) return false;
+
+  if (new Set(["integrating", "integrated", "removed"]).has(worktreeStatus)) {
+    if (
+      !nonEmptyString(integration.parent_before_sha) ||
+      !nonEmptyString(integration.source_sha) ||
+      integration.source_sha !== sourceCheckpoint ||
+      !nonEmptyString(integration.candidate_sha) ||
+      integration.candidate_branch !== `speculo/integration/${change}/${ticketId}` ||
+      integration.candidate_workspace_ref !== `specdev-worktree/.integration/${ticketId}` ||
+      !new Set(["fast-forward", "merge-commit"]).has(integration.method) ||
+      !Number.isInteger(integration.attempts) ||
+      integration.attempts < 1
+    ) return false;
+  }
+  if (worktreeStatus === "integrating" && integration.status !== "candidate") return false;
+  if (new Set(["integrated", "removed"]).has(worktreeStatus)) {
+    if (
+      integration.status !== "passed" ||
+      integration.verification !== "passed" ||
+      !nonEmptyString(integration.result_sha) ||
+      integration.result_sha !== integration.candidate_sha ||
+      !new Set(["not-required", "passed"]).has(e2e.status)
+    ) return false;
+    if (integration.method === "fast-forward" && (integration.candidate_sha !== sourceCheckpoint || integration.conflict_paths.length > 0)) return false;
+    if (integration.method === "merge-commit" && (integration.candidate_sha === sourceCheckpoint || integration.candidate_sha === integration.parent_before_sha)) return false;
+  }
+  return true;
+}
+
+function validChangeStatusV4(status, expectedChange, expectedStatus) {
+  const required = [
+    "schema_version", "artifact", "change", "change_status", "current_work", "created_at",
+    "updated_at", "completed_at", "archived", "archive_path", "blockers", "deviations", "worktrees",
+  ];
+  if (
+    !isObject(status) ||
+    !hasExactKeys(status, required) ||
+    status.schema_version !== 4 ||
+    status.artifact !== "change-status" ||
+    status.change !== expectedChange ||
+    !CHANGE_NAME_PATTERN.test(String(status.change)) ||
+    !expectedStatus.has(status.change_status) ||
+    !(status.current_work === null || typeof status.current_work === "string") ||
+    !nonEmptyString(status.created_at) ||
+    !nonEmptyString(status.updated_at) ||
+    !(status.completed_at === null || nonEmptyString(status.completed_at)) ||
+    typeof status.archived !== "boolean" ||
+    !(status.archive_path === null || (typeof status.archive_path === "string" && ARCHIVE_PATH_PATTERN.test(status.archive_path))) ||
+    !stringArray(status.blockers) ||
+    !stringArray(status.deviations) ||
+    !Array.isArray(status.worktrees)
+  ) return false;
+  if (status.change_status === "archived") {
+    if (status.archived !== true || typeof status.archive_path !== "string" || !ARCHIVE_PATH_PATTERN.test(status.archive_path)) return false;
+  } else if (status.archived !== false) {
+    return false;
+  }
+
+  const seenTickets = new Set();
+  return status.worktrees.every((worktree) => {
+    const requiredWorktree = [
+      "ticket_id", "owner", "implementation_owner", "integration_owner", "provider", "base_sha",
+      "parent_branch", "branch", "workspace_ref", "source_checkpoint", "integration", "status", "updated_at",
+    ];
+    if (!isObject(worktree) || !hasExactKeys(worktree, requiredWorktree) || worktree.provider !== "git") return false;
+    if (typeof worktree.ticket_id !== "string" || !/^T-[0-9]{2,}$/.test(worktree.ticket_id)) return false;
+    if (seenTickets.has(worktree.ticket_id)) return false;
+    seenTickets.add(worktree.ticket_id);
+    for (const key of ["owner", "implementation_owner", "integration_owner", "base_sha", "parent_branch", "branch", "updated_at"]) {
+      if (!nonEmptyString(worktree[key])) return false;
+    }
+    if (worktree.parent_branch === worktree.branch) return false;
+    if (worktree.workspace_ref !== `specdev-worktree/${worktree.ticket_id}`) return false;
+    if (!new Set(["planned", "active", "review", "integrating", "integrated", "removed", "blocked"]).has(worktree.status)) return false;
+    const sourceRequired = new Set(["review", "integrating", "integrated", "removed"]).has(worktree.status);
+    if (sourceRequired ? !nonEmptyString(worktree.source_checkpoint) : !stringOrNull(worktree.source_checkpoint)) return false;
+    return validIntegrationV4(worktree.integration, worktree.status, worktree.source_checkpoint, expectedChange, worktree.ticket_id);
+  });
+}
+
+function validateChangeStatusV4(status, expectedChange, expectedStatus) {
+  return validChangeStatusV4(status, expectedChange, expectedStatus)
+    ? []
+    : ["invalid or incomplete change-status v4 contract: " + expectedChange];
+}
+
+function parseGoalPlanScalar(raw) {
+  const value = raw.trim();
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (/^-?\d+$/.test(value)) return Number(value);
+  if (value.startsWith("[") && value.endsWith("]")) {
+    const inner = value.slice(1, -1).trim();
+    return inner ? inner.split(",").map((item) => parseGoalPlanScalar(item)) : [];
+  }
+  if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) return value.slice(1, -1);
+  return value;
+}
+
+function parseGoalPlanFrontmatter(text) {
+  const lines = text.split(/\r?\n/);
+  if (lines[0]?.trim() !== "---") return null;
+  const end = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+  if (end < 0) return null;
+  const meta = {};
+  let currentListKey = null;
+  for (const line of lines.slice(1, end)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    if (currentListKey && /^\s+-\s+/.test(line)) {
+      meta[currentListKey].push(parseGoalPlanScalar(line.replace(/^\s+-\s+/, "")));
+      continue;
+    }
+    currentListKey = null;
+    const colon = line.indexOf(":");
+    if (colon < 1) return null;
+    const key = line.slice(0, colon).trim();
+    if (key in meta) return null;
+    const raw = line.slice(colon + 1).trim();
+    if (!raw) {
+      meta[key] = [];
+      currentListKey = key;
+    } else {
+      meta[key] = parseGoalPlanScalar(raw);
+    }
+  }
+  return meta;
+}
+
+function validGoalPlanV4(meta, change) {
+  const required = [
+    "schema_version", "artifact", "change", "status", "modes", "orchestration", "lead",
+    "implementation_agent_limit", "ticket_workspace_policy", "integration_gate", "ready_for_execution",
+  ];
+  if (!isObject(meta) || !hasExactKeys(meta, required)) return false;
+  if (
+    meta.schema_version !== 4 ||
+    meta.artifact !== "goal-plan" ||
+    meta.change !== change ||
+    !new Set(["draft", "ready", "in_progress", "completed", "blocked"]).has(meta.status) ||
+    meta.orchestration !== "lead-directed" ||
+    !nonEmptyString(meta.lead) ||
+    !Number.isInteger(meta.implementation_agent_limit) ||
+    meta.implementation_agent_limit < 1 ||
+    meta.implementation_agent_limit > 3 ||
+    meta.ticket_workspace_policy !== "required" ||
+    meta.integration_gate !== "candidate-merge" ||
+    typeof meta.ready_for_execution !== "boolean" ||
+    !Array.isArray(meta.modes)
+  ) return false;
+  return meta.modes.every((mode) => new Set(["migration", "high-assurance", "reference-conformance", "release-coordination"]).has(mode)) &&
+    new Set(meta.modes).size === meta.modes.length;
+}
+
+async function validateGoalPlanV4(changeRoot, change) {
+  const path = join(changeRoot, "goal-plan.md");
+  if (!(await exists(path))) return [];
+  const text = await readFile(path, "utf8");
+  return validGoalPlanV4(parseGoalPlanFrontmatter(text), change)
+    ? []
+    : ["Goal Plan is not the complete fixed Lead/candidate-integration v4 contract: " + change];
+}
+
+function validSpecdevConfigV4(config) {
+  const rootKeys = ["schema_version", "interaction_language", "artifact_language", "git", "execution", "verification", "planning"];
+  if (
+    !isObject(config) ||
+    !hasExactKeys(config, rootKeys) ||
+    config.schema_version !== 4 ||
+    !nonEmptyString(config.interaction_language) ||
+    !nonEmptyString(config.artifact_language) ||
+    !isObject(config.git) ||
+    !isObject(config.execution) ||
+    !isObject(config.verification) ||
+    !isObject(config.planning)
+  ) return false;
+  if (!hasExactKeys(config.git, ["default_branch"]) || !(config.git.default_branch === null || typeof config.git.default_branch === "string")) return false;
+  if (!hasExactKeys(config.execution, ["max_implementation_agents", "deep_ticket_human_approval", "shared_path_owner"])) return false;
+  if (
+    !Number.isInteger(config.execution.max_implementation_agents) ||
+    config.execution.max_implementation_agents < 1 ||
+    config.execution.max_implementation_agents > 3 ||
+    typeof config.execution.deep_ticket_human_approval !== "boolean" ||
+    !nonEmptyString(config.execution.shared_path_owner)
+  ) return false;
+  for (const key of ["test", "typecheck", "lint", "build"]) {
+    if (!(key in config.verification) || !stringOrNull(config.verification[key])) return false;
+  }
+  return new Set(["lite", "standard", "deep"]).has(config.planning.default_depth) &&
+    typeof config.planning.require_ready_gate === "boolean" &&
+    typeof config.planning.require_evidence === "boolean";
+}
+
 async function validateSpecdev(speculoRoot) {
   const statusPath = join(speculoRoot, ".speculo", "specdev", "status.json");
   if (!(await exists(statusPath))) return [];
   const failures = [];
   const status = await readJson(statusPath);
-  if (status.schema_version !== 4 || status.workflow !== "specdev" || !Array.isArray(status.active) || !Array.isArray(status.archived)) {
-    return [".speculo/specdev/status.json is not SpecDev global status v4"];
+  if (status.schema_version !== 5 || status.workflow !== "specdev" || !Array.isArray(status.active) || !Array.isArray(status.archived)) {
+    return [".speculo/specdev/status.json is not SpecDev global status v5"];
   }
   const active = new Set();
   for (const entry of status.active) {
@@ -326,12 +607,12 @@ async function validateSpecdev(speculoRoot) {
       failures.push("missing active change state: " + entry.change);
     } else {
       const changeStatus = await readJson(path);
-      if (
-        changeStatus.schema_version !== 3 ||
-        changeStatus.artifact !== "change-status" ||
-        changeStatus.change !== entry.change ||
-        !new Set(["active", "blocked", "completed"]).has(changeStatus.change_status)
-      ) failures.push("invalid active change state: " + entry.change);
+      failures.push(...validateChangeStatusV4(
+        changeStatus,
+        entry.change,
+        new Set(["active", "blocked", "completed"]),
+      ));
+      failures.push(...await validateGoalPlanV4(dirname(path), entry.change));
     }
   }
   const archived = new Set();
@@ -348,12 +629,7 @@ async function validateSpecdev(speculoRoot) {
       failures.push("missing archived change state: " + name);
     } else {
       const archivedStatus = await readJson(path);
-      if (
-        archivedStatus.schema_version !== 3 ||
-        archivedStatus.artifact !== "change-status" ||
-        archivedStatus.change !== name ||
-        archivedStatus.change_status !== "archived"
-      ) failures.push("invalid archived change state: " + name);
+      failures.push(...validateChangeStatusV4(archivedStatus, name, new Set(["archived"])));
     }
   }
   const changesRoot = join(speculoRoot, ".speculo", "specdev", "changes");
@@ -379,7 +655,7 @@ async function validateSpecdev(speculoRoot) {
   const configPath = join(speculoRoot, ".speculo", "specdev", "config.json");
   if (await exists(configPath)) {
     const config = await readJson(configPath);
-    if (config.schema_version !== 3) failures.push(".speculo/specdev/config.json is not schema v3");
+    if (!validSpecdevConfigV4(config)) failures.push(".speculo/specdev/config.json is not the complete schema-v4 execution contract");
   }
   return failures;
 }
@@ -438,6 +714,12 @@ async function validateActive(speculoRoot, allowPending = false) {
   if (failures.length) throw new Error("Migrated runtime validation failed:\n- " + failures.join("\n- "));
 }
 
+async function assertNoSymlinks(root) {
+  for (const entry of await walk(root)) {
+    if (entry.type === "symlink") throw new Error("Runtime contains a symbolic link: " + entry.path);
+  }
+}
+
 async function applyAction(ctx, stagedSpeculo, action) {
   if (action.kind === "keep-current") return;
   const destination = inside(stagedSpeculo, action.to);
@@ -451,7 +733,11 @@ async function applyAction(ctx, stagedSpeculo, action) {
     const source = inside(ctx.backupRoot, action.from);
     const stat = await lstat(source);
     await rm(destination, { recursive: true, force: true });
-    await cp(source, destination, { recursive: stat.isDirectory(), force: true });
+    await cp(source, destination, {
+      recursive: stat.isDirectory(),
+      force: true,
+      verbatimSymlinks: true,
+    });
     return;
   }
   await writeFile(destination, JSON.stringify(action.value, null, 2) + "\n", "utf8");
@@ -474,12 +760,15 @@ async function apply(projectRoot, planPath, confirmed) {
   try {
     await cp(ctx.speculoRoot, stagedSpeculo, { recursive: true, force: true });
     for (const action of plan.actions) await applyAction(ctx, stagedSpeculo, action);
+    await assertNoSymlinks(stagedSpeculo);
     await validateActive(stagedSpeculo, true);
     await rm(join(stagedSpeculo, ".speculo", "migration.json"), { force: true });
+    await assertNoSymlinks(stagedSpeculo);
     await rename(ctx.speculoRoot, rollbackRoot);
     oldMoved = true;
     await rename(stagedSpeculo, ctx.speculoRoot);
     newInstalled = true;
+    await assertNoSymlinks(ctx.speculoRoot);
     await validateActive(ctx.speculoRoot);
     const installedCtx = await contextWithCompletedMigration(ctx.projectRoot);
     const postIssues = await validateBackup(installedCtx, false);

package/template/skills/optimize-codex-config/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: optimize-codex-config
+description: 体检并优化本机 Codex 配置；当任务涉及 config.toml、auth.json、自定义模型供应商、权限、Agent、MCP、Hook、配置漂移，或 Codex 的 401、403、404、413、SSE、超时与 compaction 故障时使用。
+---
+
+# Optimize Codex Config
+
+以**体检**为主导词：先建立脱敏事实，再提出配置变更。默认只读；修改本机配置前必须向用户展示完整目标和脱敏 diff，并取得本次修改的明确确认。
+
+## 1. 锁定范围与权限
+
+1. 解析实际 `CODEX_HOME`；未显式设置时使用当前用户的 `~/.codex`。将它转成绝对路径并确认目标是目录且不是符号链接。
+2. 将请求归类为只读体检、故障诊断或配置修改。只读体检和诊断不取得写权限。
+3. 将本 skill 的写入边界限制为用户明确指定的本机 Codex 文件。CC Switch 数据库、远端 API、反向代理和 Nginx 只输出归因与交接建议。
+4. 在任何可能写入前记录 `config.toml` 的哈希、大小和修改时间，并检查目标文件是否存在已证明的可写句柄。普通 Codex CLI、ChatGPT/Codex 应用进程及其 helper 的存在不构成 writer 证据。
+
+**完成标准：** 实际 `CODEX_HOME`、任务类型、允许写入的文件和外部边界均已明确；符号链接、已证明的活跃 writer、不明确目标，或修改任务无法取得 writer 观测时已成为 blocker。只读任务可以把不可用探针记录为 unknown 后继续。
+
+## 2. 建立只读基线
+
+从本 `SKILL.md` 所在目录运行：
+
+```bash
+node scripts/audit-codex-config.mjs --codex-home <absolute-directory> --json
+```
+
+需要离线或可复现 fixture 时加入 `--no-command-probes`；需要缩小会话扫描范围时使用 `--since-days <N>`。先运行 `--help` 核对当前接口；CLI 不在导出的 `PATH` 中时，用 `command -v codex` 取得绝对路径并传给 `--codex-bin`。
+
+1. 保留审计脚本的结构化结果；不得把 `auth.json` 内容、提示词、工具输出、完整接口 URL 或 bearer token复制进报告。
+2. 直接查看配置时，先遮蔽 `experimental_bearer_token`、静态认证 header、环境变量值和 URL 主机。只检查 `auth.json` 的存在、文件类型、权限和 Codex 报告的认证模式，不读取或打印文件内容。
+3. 对配置、供应商、认证、权限、Agent、MCP、Hook 或历史设置提出判断前，读取 [configuration contract](references/configuration-contract.md)，并用已安装 CLI 与当前官方配置参考验证每个拟使用的键。
+4. 把用户提供的既有设置视为需要保留或评估的事实，不把个人模型、认证方式或权限策略提升为通用默认值。
+
+**完成标准：** 当前版本、配置指纹、认证存储模式、供应商契约、权限、Agent、MCP、Hook、会话故障和 writer 状态均有脱敏证据；无法取得的事实被标为 unknown。
+
+## 3. 归因故障
+
+当请求包含 HTTP 状态码、SSE、超时或 compaction 失败时，读取 [troubleshooting](references/troubleshooting.md)，按其中证据梯度完成归因。
+
+1. 关联错误发生前最近一次 `token_count`，但只保留 token 数和模型上下文窗口。
+2. 区分本机配置、认证、供应商 wire API、远端模型服务和前置代理。HTML 代理错误页属于代理证据，不归因给模型。
+3. 对外部问题给出可复现证据、影响、临时本机缓解和服务端交接项。本 skill 不探测或修改用户未授权的远端系统。
+
+**完成标准：** 每个错误只有一个主要归属域，证据与推断分开，所有本机缓解都标明质量、成本或频率代价。
+
+## 4. 设计目标状态
+
+只询问审计无法发现且会改变方案的偏好：模型与推理等级、认证存储、审批与沙箱、网络访问、Agent 并发、供应商认证方式、历史保留，以及 MCP/Hook 的保留意图。
+
+输出确认包：
+
+1. 当前状态和问题证据；
+2. 目标状态及每项理由；
+3. 逐文件脱敏 diff；
+4. 明确保留的未知项、MCP、Hook、profile 和兼容设置；
+5. 备份名、原子写入方法、验证命令和回滚条件；
+6. 不在本机范围内的外部 blocker。
+
+只采用当前官方参考与已安装 CLI 均能验证的键。项目级 `.codex/config.toml` 不承载 provider、auth 或其他被 Codex 忽略的机器级设置。
+
+**完成标准：** 用户无需猜测任何目标值；diff 不含 secret；未关联的现有设置不会被清理；外部问题不会伪装成本机可修复项。
+
+## 5. 确认后原子写入
+
+只有用户在看到确认包后明确同意本次变更，才执行以下动作：
+
+1. 重读指纹；若配置已变化、存在目标文件的可写句柄，或 writer 探针仍为 unknown，停止并重新体检。
+2. 为每个待改文件创建不覆盖的 `*.pre-optimize-<YYYYMMDD-HHMMSS>.bak`，并将包含凭据的文件权限设为 `0600`。
+3. 在同一目录写临时文件、解析或加载验证成功后 rename 到目标，保留与任务无关的表和注释。
+4. 仅在用户明确要求且已安装 Codex 能验证格式时处理 `auth.json`。文件存储是有效选择，不强制迁移钥匙串；不得自行发明认证 JSON schema。
+
+**完成标准：** 写入前后的指纹、备份和确认可对应；目标文件是原子替换结果；没有越出已确认文件集合。
+
+## 6. 验证与交付
+
+1. 运行 `codex doctor --json`，再核对 `codex features list` 和 `codex debug models --bundled` 中与目标相关的能力。
+2. 验证配置加载、认证模式、权限与沙箱、MCP、Hook、Agent 和旧会话恢复。只有用户授权可能计费的网络请求后，才执行最小第三方 API 请求。
+3. 任一必须验证项失败时恢复备份，重跑相同检查并报告原始失败与回滚结果。
+4. 报告已改变、已保留、已验证、未验证和外部 blocker；不回显任何 secret 或完整 URL。
+
+**完成标准：** 所有已确认变更通过本机验证，或已完整回滚；报告包含命令、退出码和关键脱敏证据。