@namewta/speculo 0.7.2 → 0.7.3

package/template/skills/migrate-runtime-state/SKILL.md

@@ -43,25 +43,25 @@ node scripts/migrate-runtime-state.mjs inspect --project-root <project-root>
 
 ### 3. 生成确定性计划
 
-生成 schema v1 JSON plan。`backup_manifest_sha256` 锁定 inspect 现场；`source_decisions` 必须逐项覆盖 manifest 中的每个文件且不得包含 `unresolved`；`actions` 仅使用脚本支持的动作：
+生成 schema v2 JSON plan。`backup_manifest_sha256` 锁定 inspect 现场；`source_decisions` 必须逐项覆盖 manifest 中的每个文件且不得包含 `unresolved`；每个 action 必须以 `source_decision` 显式引用唯一来源决策，且动作、decision disposition 与目标一一对应：
 
 ```json
 {
-  "schema_version": 1,
+  "schema_version": 2,
   "backup_manifest_sha256": "<inspect 返回的 sha256>",
   "source_decisions": [
     {"path": "config.json", "disposition": "merge-json", "target": "config.json"},
+    {"path": "state/specdev/context.md", "disposition": "restore", "target": ".speculo/specdev/context.md"},
     {"path": "state/workspace.json", "disposition": "keep-current", "target": ".speculo/workspace.json"}
   ],
   "actions": [
-    {"kind": "copy", "from": "state/specdev/context", "to": ".speculo/specdev/context", "expected_target": "absent"},
-    {"kind": "replace-json", "to": ".speculo/specdev/status.json", "value": {}, "expected_target": "file:<sha256>"},
-    {"kind": "keep-current", "to": "config.json", "expected_target": "file:<sha256>"}
+    {"kind": "copy", "source_decision": "state/specdev/context.md", "from": "state/specdev/context.md", "to": ".speculo/specdev/context.md", "expected_target": "absent"},
+    {"kind": "replace-json", "source_decision": "config.json", "to": "config.json", "value": {}, "expected_target": "file:<sha256>"}
   ]
 }
 ```
 
-`from` 必须相对 backup root；`to` 只能是 `config.json` 或 `.speculo/` 内非受保护路径。每个 action 都使用 `fingerprint` 输出锁定 `expected_target`；目标相互重叠时拆成不重叠动作。Plan 写入调用方声明的临时位置，报告保存等价 Markdown 表格；正式 state 不保存第二份 plan。
+`from` 必须与 `source_decision` 相同且相对 backup root；`copy ↔ restore`、`replace-json ↔ merge-json|replace-json`、`keep-current ↔ keep-current`、`remove-current ↔ remove-current`。只有 `keep-current` 决策可省略 action。`to` 只能是 `config.json` 或 `.speculo/` 内非受保护路径。每个 action 都使用 `fingerprint` 输出锁定 `expected_target`；目标相互重叠时拆成不重叠动作。Plan 写入调用方声明的临时位置，报告保存等价 Markdown 表格；正式 state 不保存第二份 plan。
 
 **完成标准**：计划可由脚本解析，路径均在授权边界内，受管理静态资产和 `back/` 不会成为目标。
 

package/template/skills/migrate-runtime-state/references/migration-contract.md

@@ -26,6 +26,11 @@
 - `active` 从仍位于 `changes/` 且 change 状态为 active/blocked/completed 的真实目录核对；不得创建虚假 change。
 - `archived` 从 `archive/YYYY-MM/<change>/` 核对，active/archived 不得重叠。
 - `config.json` 保留语言、Git、执行、验证与规划偏好，并补入当前 schema 的必需默认值。
+- SpecDev config v3 升级为 v4 时，`execution.max_parallel` 只作为旧并发偏好的输入，收敛到 `execution.max_implementation_agents: 1..3`；删除旧的自动提交和条件 worktree 开关，不把它们解释为授权。
+- change-status v3 只有在 `worktrees` 缺失或为空时才可确定性升级为 v4；存在旧 worktree 记录时，必须逐 Ticket 重建 implementation owner、source commit、candidate/result、E2E disposition 和父分支包含关系。v4 runtime 不得自动升级为 v5：旧状态无法可靠推断 execution authorization 或 Lead leadership，必须保持 pending 并显式对账。
+- active Goal Plan 不是 v5 时必须重新规划固定 Lead、Ticket worktree 和 candidate integration gate；不能只改 frontmatter 版本号。
+- 已声明为 v4 的 SpecDev config，以及已声明为 v5 的 global status、change-status 和 Goal Plan，必须完整满足当前 schema：必需字段、类型、枚举、嵌套对象和 `additionalProperties` 边界都通过后才能自动保留。不得为不完整状态静默补默认值，也不得只扫描少量标记字段。
+- worktree `removed` 只接受为 `integrated` 后的清理终态；source checkpoint、passed candidate/result、验证、E2E disposition 和 Evidence 必须完整保留。
 - `.config/`、`adr/`、`context/`、`research/`、`changes/`、`archive/` 和声明的 sidecar 都是持久项。
 - Command Markdown 报告和具有当前 owner 的 `state.json` 均迁移；未知 command state 保持 unresolved。
 
@@ -49,10 +54,11 @@
 
 ## 验证
 
-- backup manifest 的每个 file hash、size 和 symlink 条目与现场一致；存在 symlink 时阻塞。
-- plan 的 `backup_manifest_sha256` 与现场一致，`source_decisions` 恰好覆盖 manifest 全部条目，且每个 action 的 `expected_target` 与 active 现场一致。
+- backup manifest 的每个 file hash、size，以及每个 symlink 的类型和 link target 都必须与现场一致；link 本身保留为 pending 事实，不能被自动恢复到 active runtime。
+- plan 的 `backup_manifest_sha256` 与现场一致，`source_decisions` 恰好覆盖 manifest 全部条目；每个 action 必须显式 `source_decision`，且只可实现该 decision 的同目标、同 disposition 动作。除 `keep-current` 外，每个 decision 必须恰有一个 action；每个 action 的 `expected_target` 与 active 现场一致。
+- action 后、删除 staged marker 前、原子替换后都递归拒绝 active runtime 中的 symlink；任何失败均恢复原 active 安装。
 - 所有迁移后 JSON 可解析。
 - workspace、install manifest、项目配置和已安装 workflow 全局状态满足当前版本。
-- SpecDev active/archive 索引与目录一致；person 状态满足 schema v1。
+- SpecDev active/archive 索引与目录一致；SpecDev config 满足 v4 合同，global status、change-status 与 Goal Plan 满足 v5 合同；person 状态满足 schema v1。
 - pending marker 只在全部验证通过后从 staged 安装删除。
 - 执行后 backup manifest 与内容 hash 不变。

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);