@aipper/aiws 0.0.23 → 0.0.25

package/README.md

@@ -7,7 +7,10 @@ AI Workspace CLI：把 Claude Code / OpenCode / Codex / iFlow 对齐到同一套
 - 强门禁校验：`aiws validate`（可选证据落盘 `--stamp`）
 - 回滚：`aiws rollback`（从 `.aiws/backups/` 恢复）
 - 变更工件工作流（脱离 dotfiles）：`aiws change ...`
+- 本地治理看板：`aiws dashboard serve`
+- OpenCode/oMo 运行时探测：`aiws opencode status`
 - Git hooks：`aiws hooks install/status`
+- 跨工具 native 投影：Codex repo skills、Claude skills、OpenCode skills/commands
 - Codex：repo skills（推荐）+ 可选全局 skills 安装
 
 真值来源（SSOT）：`@aipper/aiws-spec`（模板与契约）。
@@ -41,25 +44,50 @@ aiws validate [path] [--stamp]
 aiws rollback [path] <timestamp|latest>
 
 aiws change <list|new|start|status|next|sync|validate|archive|templates>
+aiws dashboard serve [--host 127.0.0.1] [--port 3456]
+aiws opencode status [path]
 aiws hooks <install|status>
 aiws codex <install-skills|status-skills|uninstall-skills|install-prompts|status|uninstall-prompts>
 ```
 
+Dashboard 说明：
+- 读取本地 `changes/<id>/`、`.agentdocs/tmp/...` 与 spec 中的阶段契约 / governance / review-gate 真值，展示 phase、collaboration、strict blockers、review gates、next advice
+- 阶段治理视图会基于共享 change 状态细分 `ws-review` / `ws-commit` / `ws-deliver` / `ws-finish` / `ws-handoff`
+- 本地 API：
+  - `/api/changes`
+  - `/api/workflow-stages`
+  - `/api/change/<id>/validate?strict=1`
+
 ## Codex（repo skills 优先）
 
+- 若你不想先判断当前该走 plan、dev、review 还是 finish：先用 `$using-aiws`
 - `aiws init .` 会生成 `.agents/skills/`（随仓库共享），在 Codex 中可显式调用（示例）：`$ws-preflight` / `$ws-plan` / `$p-tasks-plan` / `$ws-handoff` / `$ws-dev` / `$ws-review` / `$ws-commit`
+- 现在也会生成默认 router 入口：`$using-aiws`（Claude/OpenCode 对应 `/using-aiws`）
+- `aiws init .` 也会同步投影 `Claude Code` native skills（`.claude/skills/`）与 `OpenCode` native skills / commands（`.opencode/skills/` / `.opencode/commands/`），并保留 `.claude/commands/`、`.opencode/command/` 兼容入口
+- 高风险改动或准备 finish 时，建议补跑：`$ws-spec-review`、`$ws-quality-review`、`$ws-verify-before-complete`
 - 交付收尾（submodules+superproject 分步提交 + 安全合并）：`$ws-deliver`
-- 收尾（安全合并回目标分支）：`$ws-finish`（底层调用 `aiws change finish`，默认 fast-forward）
-- 可选：安装全局 skills 到 `~/.codex/skills/`（或 `$CODEX_HOME/skills`）：
+- 收尾（安全合并回目标分支）：`$ws-finish`（底层调用 `aiws change finish`，默认 fast-forward；现在会硬阻断缺失的 review gate）
+- 可选：安装全局 skills 到 `~/.agents/skills/`：
   - `aiws codex install-skills`
   - `aiws codex status-skills`
   - `aiws codex uninstall-skills`
+- 测试/沙箱场景可用 `--dir <path>`；若设置 `CODEX_HOME`，全局 skills 会解析到 `$CODEX_HOME/.agents/skills`
 - legacy prompts（deprecated，仅兼容）：`aiws codex install-prompts`
 
+## OpenCode / oMo
+
+- `aiws init .` 会生成 `.opencode/skills/`、`.opencode/commands/` 与 `.opencode/oh-my-opencode.json.example`
+- `aiws opencode status .` 会检查当前项目是否真正启用了 `.opencode/oh-my-opencode.json`，并输出 `oMo-enabled` 或 `standard-opencode`
+- 若只存在 `.opencode/oh-my-opencode.json.example`，说明项目已具备建议配置，但还没有真正启用 oMo
+- 启用后，`using-aiws` / `ws-preflight` / `ws-plan` / `ws-review` 会优先按 `planner-sisyphus` / `explore` / `librarian` / `oracle` 路由；缺失时按 fallback 退回标准 OpenCode
+
 ## 证据落盘与协作
 
 - `aiws validate --stamp` 会写入：`.agentdocs/tmp/aiws-validate/*.json`（默认被 `.gitignore` 忽略）
 - `$ws-review` 会落盘：`.agentdocs/tmp/review/codex-review.md`（默认被 `.gitignore` 忽略）
+- `change status` / `change next` / dashboard 会显式显示：`spec_review` / `quality_review` / `validate_stamp` / `verify_before_complete`
+- `aiws change validate <id> --strict --check-scope` 会按计划文件的 `## Scope` / `### In Scope` 检查越界改动；最新结果也会显示在 `change status` / `change next` / dashboard
+- 交付前建议执行：`aiws change validate <id> --strict --check-evidence`；`aiws change finish <id>` 也会对同一套 gate 做硬阻断
 - 建议把“可协作/可审计”的内容放进 `changes/<change-id>/`（proposal/tasks/design）并提交；`.agentdocs/tmp/` 作为本地缓存更稳
 
 ## 运行要求

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@aipper/aiws",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "description": "AI Workspace CLI (init/update/validate) for Claude Code / OpenCode / Codex / iFlow.",
   "type": "module",
   "bin": {
     "aiws": "./bin/aiws.js"
   },
   "dependencies": {
-    "@aipper/aiws-spec": "0.0.23"
+    "@aipper/aiws-spec": "0.0.25"
   },
   "files": [
     "bin",

package/src/cli.js

@@ -14,6 +14,7 @@ import { codexStatusSkillsCommand } from "./commands/codex-status-skills.js";
 import { codexUninstallSkillsCommand } from "./commands/codex-uninstall-skills.js";
 import { hooksInstallCommand } from "./commands/hooks-install.js";
 import { hooksStatusCommand } from "./commands/hooks-status.js";
+import { opencodeStatusCommand } from "./commands/opencode-status.js";
 import { dashboardServeCommand } from "./commands/dashboard.js";
 import {
   changeArchiveCommand,
@@ -46,6 +47,10 @@ export async function cliMain(argv) {
     printHooksHelp();
     return 0;
   }
+  if (args[0] === "opencode" && (args.includes("-h") || args.includes("--help"))) {
+    printOpenCodeHelp();
+    return 0;
+  }
   if (args[0] === "dashboard" && (args.includes("-h") || args.includes("--help"))) {
     printDashboardHelp();
     return 0;
@@ -242,6 +247,23 @@ export async function cliMain(argv) {
           throw new UserError(`Unknown dashboard subcommand: ${sub}`, { details: "Use `aiws dashboard --help` to see available subcommands." });
       }
     }
+    case "opencode": {
+      const sub = args.shift();
+      if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+        printOpenCodeHelp();
+        return 0;
+      }
+      switch (sub) {
+        case "status": {
+          const { positionals } = parseArgs(args, {});
+          const targetPath = positionals[0] ?? ".";
+          await opencodeStatusCommand({ targetPath });
+          return 0;
+        }
+        default:
+          throw new UserError(`Unknown opencode subcommand: ${sub}`, { details: "Use `aiws opencode --help` to see available subcommands." });
+      }
+    }
     case "change": {
       const sub = args.shift();
       if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
@@ -370,12 +392,16 @@ export async function cliMain(argv) {
           const { positionals, options } = parseArgs(args, {
             into: { type: "string" },
             base: { type: "string" },
+            push: { type: "boolean" },
+            remote: { type: "string" },
           });
           const changeId = positionals[0];
           await changeFinishCommand({
             changeId,
             into: options.into,
             base: options.base,
+            push: options.push === true,
+            remote: options.remote,
           });
           return 0;
         }
@@ -429,6 +455,7 @@ Usage:
   aiws change <subcommand>
   aiws metrics <subcommand>
   aiws dashboard <subcommand>
+  aiws opencode <subcommand>
   aiws codex <subcommand>
   aiws hooks <subcommand>
 
@@ -454,7 +481,8 @@ Usage:
 Notes:
   - Prefer repo skills: .agents/skills (no install needed)
   - Prefer global skills over legacy prompts
-  - Default skills dir: ~/.codex/skills (or $CODEX_HOME/skills)
+  - Default skills dir: ~/.agents/skills
+  - Compatibility/test override: $CODEX_HOME/.agents/skills or --dir <path>
   - install-prompts is legacy (prompts are deprecated)
   - Default target dir: ~/.codex/prompts
   - If CODEX_HOME is set: $CODEX_HOME/prompts
@@ -474,6 +502,18 @@ Notes:
 `);
 }
 
+function printOpenCodeHelp() {
+  console.log(`aiws opencode
+
+Usage:
+  aiws opencode status [path]
+
+Notes:
+  - Detects project-local .opencode/ and oh-my-opencode (oMo) config.
+  - Helps verify whether AIWS OpenCode skills should prefer oMo agents or fallback to standard-opencode.
+`);
+}
+
 function printDashboardHelp() {
   console.log(`aiws dashboard
 
@@ -482,6 +522,8 @@ Usage:
 
 Notes:
   - Local-only dashboard, no external dependencies.
+  - Dashboard also exposes workflow governance data sourced from @aipper/aiws-spec:
+    /api/changes, /api/workflow-stages, /api/change/<id>/validate?strict=1
   - Recommended: run change quality gate first (AI tools: $ws-plan-verify):
     aiws change validate <change-id> --strict
 `);
@@ -493,7 +535,7 @@ function printChangeHelp() {
 Usage:
   aiws change list
   aiws change start <change-id> [--title <title>] [--no-design] [--hooks] [--no-switch] [--switch] [--allow-dirty] [--worktree] [--worktree-dir <path>]
-  aiws change finish [change-id] [--into <branch> | --base <branch>]
+  aiws change finish [change-id] [--into <branch> | --base <branch>] [--push] [--remote <name>]
   aiws change new <change-id> [--title <title>] [--no-design]
   aiws change status [change-id]
   aiws change next [change-id]
@@ -513,6 +555,7 @@ Notes:
     (equivalent to running $ws-plan-verify in AI tools).
   - status/next now prioritize quality-gate guidance before coding ($ws-dev).
   - start refuses to switch/create worktree with a dirty working tree (unless --allow-dirty).
+  - finish --push is submodule-aware: when .gitmodules exists it pushes submodules first, then the target branch, then safely cleans the separate change worktree if possible.
   - If .gitmodules exists and you didn't specify --switch/--no-switch/--worktree,
     start will prefer --worktree (fallback: --no-switch) to avoid switching the superproject branch.
   - archive runs strict validation and (by default) requires all tasks checked.

package/src/codex-skills.js

@@ -7,16 +7,16 @@ import { UserError } from "./errors.js";
 /**
  * Resolve Codex global skills directory:
  * - If `--dir` provided, use it directly.
- * - Else if `CODEX_HOME` is set, use `$CODEX_HOME/skills`.
- * - Else use `~/.codex/skills`.
+ * - Else if `CODEX_HOME` is set, use `$CODEX_HOME/.agents/skills` as a compatibility/test override root.
+ * - Else use `~/.agents/skills`.
  *
  * @param {string | undefined} dirOption
  */
 export function resolveCodexSkillsDir(dirOption) {
   if (dirOption) return path.resolve(dirOption);
   const envHome = String(process.env.CODEX_HOME || "").trim();
-  if (envHome) return path.join(path.resolve(envHome), "skills");
-  return path.join(os.homedir(), ".codex", "skills");
+  if (envHome) return path.join(path.resolve(envHome), ".agents", "skills");
+  return path.join(os.homedir(), ".agents", "skills");
 }
 
 function timestamp() {

package/src/commands/change-advice.js

@@ -0,0 +1,188 @@
+import path from "node:path";
+
+/**
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {{
+ *   listGitWorktrees: (gitRoot: string) => Promise<Array<{ worktree: string, branch: string }>>
+ * }} deps
+ */
+export async function resolveChangeWorktreeHint(gitRoot, changeId, deps) {
+  try {
+    const worktrees = await deps.listGitWorktrees(gitRoot);
+    const changeRef = `refs/heads/change/${changeId}`;
+    const changeWorktree = worktrees.find((worktree) => String(worktree.branch || "") === changeRef)?.worktree || "";
+    return changeWorktree && path.resolve(changeWorktree) !== path.resolve(gitRoot) ? changeWorktree : "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {{
+ *   computeChangeStatus: (gitRoot: string, changeId: string) => Promise<any>,
+ *   currentBranch: (gitRoot: string) => Promise<string>,
+ *   inferChangeIdFromBranch: (branch: string) => string,
+ *   listGitWorktrees: (gitRoot: string) => Promise<Array<{ worktree: string, branch: string }>>,
+ *   changeDirAbs: (gitRoot: string, changeId: string) => string,
+ *   governanceGuidanceLines: (status: any) => Promise<string[]>,
+ *   scopeGateFailureAction: (changeId: string) => string,
+ *   scopeGatePendingRecommendation: (changeId: string) => string,
+ *   scopeGatePassedRecommendation: () => string
+ * }} deps
+ */
+export async function computeChangeNextAdvice(gitRoot, changeId, deps) {
+  const status = await deps.computeChangeStatus(gitRoot, changeId);
+  const branch = await deps.currentBranch(gitRoot);
+  const inferred = deps.inferChangeIdFromBranch(branch);
+  const advice = {
+    changeId,
+    branch: branch || "",
+    inferredChangeId: inferred || "",
+    phase: status.phase,
+    governance: status.governance || null,
+    scopeGate: status.scopeGate || null,
+    blockersStrict: status.blockersStrict,
+    evidence: status.evidence?.counts || null,
+    collaboration: status.collaboration?.counts || null,
+    actions: [],
+    prohibitions: [],
+    recommended: [],
+  };
+
+  if (!branch) {
+    advice.actions.push("当前为 detached HEAD：建议切到 `change/<change-id>` 分支后再继续（或显式传入 `<change-id>`）");
+  } else if (inferred && inferred !== changeId) {
+    advice.actions.push(`当前分支为 \`${branch}\`（推断 change=${inferred}），但你在查看 change=${changeId}：建议先切换到 \`change/${changeId}\` 再执行开发/交付`);
+  } else if (!inferred) {
+    advice.actions.push(`当前分支为 \`${branch}\`（非 change 分支）：建议 \`aiws change start ${changeId} --hooks --switch\` 或 \`git switch change/${changeId}\``);
+  }
+
+  const changeWorktree = await resolveChangeWorktreeHint(gitRoot, changeId, deps);
+  if (changeWorktree) {
+    advice.actions.push(`change/${changeId} 分支在另一个 worktree：\`cd ${changeWorktree}\`（建议在该目录执行开发/交付相关命令）`);
+    advice.prohibitions.push("不要在当前 worktree 继续写代码（很可能不在 change 分支上）");
+  }
+
+  if (status.metaState !== "ok") advice.actions.push(`补齐元信息并建立真值基线：\`aiws change sync ${changeId}\``);
+  if (status.driftFiles.length > 0) {
+    advice.actions.push("真值/合同已变化：先对齐 `AI_PROJECT.md` / `AI_WORKSPACE.md` / `REQUIREMENTS.md` 与 proposal/tasks");
+    advice.actions.push(`确认后同步基线：\`aiws change sync ${changeId}\``);
+  }
+
+  const proposalPath = path.join(deps.changeDirAbs(gitRoot, changeId), "proposal.md");
+  const tasksPath = path.join(deps.changeDirAbs(gitRoot, changeId), "tasks.md");
+  if (status.blockersStrict.some((item) => item.includes("proposal.md") && item.includes("WS:TODO"))) {
+    advice.actions.push(`完善 proposal：\`$EDITOR ${proposalPath}\``);
+  }
+  if (status.blockersStrict.some((item) => item.includes("tasks.md") && item.includes("WS:TODO"))) {
+    advice.actions.push(`完善 tasks：\`$EDITOR ${tasksPath}\``);
+  }
+  if (status.blockersStrict.some((item) => item.includes("proposal.md missing attribution"))) {
+    advice.actions.push("补齐归因：在 proposal.md 填写非空 `Req_ID` 或 `Problem_ID`（严格校验需要）");
+  }
+  if (status.blockersStrict.some((item) => item.includes("missing Contract_Row"))) {
+    advice.actions.push("补齐绑定：在 proposal.md 填写非空 `Contract_Row`（严格校验需要）");
+  }
+  if (status.blockersStrict.some((item) => item.includes("Plan_File"))) {
+    advice.actions.push("补齐绑定：修正 proposal.md 的 `Plan_File`（严格校验需要；必须存在且仅 1 个）");
+  }
+  if (status.blockersStrict.some((item) => item.includes("missing Evidence_Path"))) {
+    advice.actions.push("补齐绑定：在 proposal.md 填写非空 `Evidence_Path`（严格校验需要；建议优先写 `changes/<id>/evidence/...`）");
+  }
+  if (status.scopeGate?.status === "failed") {
+    advice.actions.push(deps.scopeGateFailureAction(changeId));
+  }
+  if (status.tasks.unchecked > 0) advice.actions.push(`完成未勾选任务（${status.tasks.unchecked} 项）`);
+  if ((status.collaboration?.counts?.analysis || 0) > 0 && (status.collaboration?.counts?.review || 0) === 0) {
+    advice.actions.push("已有委托分析但还没有 review 汇总结论：建议在 `changes/<id>/review/` 落盘结论后再交付");
+  }
+  if ((status.collaboration?.counts?.patches || 0) > 0) {
+    advice.actions.push("存在委托 patch 草案：提交/交付前先人工审查 `changes/<id>/patches/`，不要直接无审查应用");
+  }
+
+  if (status.blockersStrict.length > 0 && advice.actions.length === 0) {
+    advice.actions.push("先修复 Blockers (strict) 后复跑质量门，再进入 `$ws-dev`");
+  }
+
+  if (status.blockersStrict.length === 0 && status.tasks.unchecked === 0) {
+    for (const line of await deps.governanceGuidanceLines(status)) advice.recommended.push(line);
+    if (advice.evidence && advice.evidence.persistent === 0) {
+      advice.recommended.push("交付前建议生成持久证据并回填：`aiws change evidence <change-id>`");
+    }
+    if (status.scopeGate?.status === "not_run") {
+      advice.recommended.push(deps.scopeGatePendingRecommendation(changeId));
+    } else if (status.scopeGate?.status === "passed") {
+      advice.recommended.push(deps.scopeGatePassedRecommendation());
+    }
+    if ((status.governance?.recommendedStage || "") === "ws-finish" || (status.governance?.currentStage || "") === "ws-commit") {
+      advice.recommended.push("交付前门禁（推荐落盘）：`aiws validate . --stamp`");
+    }
+    if ((status.collaboration?.counts?.review || 0) > 1) advice.recommended.push("存在多份 review：交付前建议在 handoff 或 review 汇总里收敛最终结论");
+  } else if (advice.actions.length === 0) {
+    advice.recommended.push("继续开发：在 AI 工具中运行 `$ws-dev`（小步实现 + 可复现验证）");
+    if ((status.collaboration?.counts?.analysis || 0) > 0) advice.recommended.push("已有委托分析：进入实现前先收敛 `changes/<id>/analysis/` 结论");
+    if ((status.collaboration?.counts?.patches || 0) > 0) advice.recommended.push("已有 patch 草案：应用前先人工审查 `changes/<id>/patches/`");
+  }
+
+  return advice;
+}
+
+/**
+ * @param {{
+ *   changeId: string,
+ *   gitRoot: string,
+ *   now: string,
+ *   status: any,
+ *   advice: any,
+ *   planVerifyLine: string
+ * }} input
+ */
+export function renderChangeStateMarkdown(input) {
+  /** @type {string[]} */
+  const lines = [];
+  lines.push(`# AIWS STATE: ${input.changeId}`);
+  lines.push("");
+  lines.push(`Generated: ${input.now}`);
+  lines.push("");
+  lines.push("## Context");
+  lines.push(`- Worktree: \`${input.gitRoot}\``);
+  lines.push(`- Branch: \`${input.advice.branch || "(detached)"}\``);
+  lines.push("");
+  lines.push("## Phase");
+  lines.push(`- Phase: \`${input.status.phase}\``);
+  lines.push(`- Tasks: ${input.status.tasks.done}/${input.status.tasks.total} (unchecked=${input.status.tasks.unchecked})`);
+  lines.push("");
+  lines.push("## Bindings");
+  if (input.status.reqId) lines.push(`- Req_ID: \`${input.status.reqId}\``);
+  if (input.status.probId) lines.push(`- Problem_ID: \`${input.status.probId}\``);
+  if (input.status.bindings?.contractRow) lines.push(`- Contract_Row: \`${input.status.bindings.contractRow}\``);
+  if (input.status.bindings?.planFile) lines.push(`- Plan_File: \`${input.status.bindings.planFile}\``);
+  lines.push("");
+  lines.push("## Evidence");
+  if (input.status.evidence?.counts) {
+    const counts = input.status.evidence.counts;
+    lines.push(
+      `- Declared: \`${counts.total}\` (exists=\`${counts.exists}\`, missing=\`${counts.missing}\`, persistent=\`${counts.persistent}\`, tmp=\`${counts.tmp}\`)`,
+    );
+  } else {
+    lines.push("- (unknown)");
+  }
+  lines.push("");
+  lines.push("## Blockers (strict)");
+  if (input.status.blockersStrict.length === 0) lines.push("- (none)");
+  else for (const blocker of input.status.blockersStrict) lines.push(`- ${blocker}`);
+  lines.push("");
+  lines.push("## Next");
+  lines.push(`- ${input.planVerifyLine}`);
+  for (const action of input.advice.actions) lines.push(`- ${action}`);
+  for (const recommendation of input.advice.recommended) lines.push(`- ${recommendation}`);
+  if (input.advice.prohibitions.length > 0) {
+    lines.push("");
+    lines.push("## Do Not");
+    for (const prohibition of input.advice.prohibitions) lines.push(`- ${prohibition}`);
+  }
+  return lines.join("\n") + "\n";
+}

package/src/commands/change-evidence-command.js

@@ -0,0 +1,242 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import {
+  buildDeliverySummary,
+  collectCollaborationArtifacts,
+  findLatestFileByMtime,
+  formatDeclaredValues,
+  mergeDeclaredValues,
+  relFromRoot,
+  upsertIdLine,
+  upsertProposalEvidencePath,
+} from "./change-evidence.js";
+import { TMP_REVIEW_FALLBACKS, tmpReviewFallbackPath } from "./change-review-gates.js";
+
+/**
+ * @param {{
+ *   gitRoot: string,
+ *   changeId: string,
+ *   changeDir: string,
+ *   proposalText: string,
+ *   options: { noValidate: boolean, allowFail: boolean }
+ * }} input
+ * @param {{
+ *   appendMetricsEvent: (gitRoot: string, changeId: string, type: string, payload: any) => Promise<void>,
+ *   computeChangeStatus: (gitRoot: string, changeId: string) => Promise<any>,
+ *   currentBranch: (gitRoot: string) => Promise<string>,
+ *   ensureDir: (path: string) => Promise<void>,
+ *   extractId: (label: string, text: string) => string,
+ *   nowIsoUtc: () => string,
+ *   nowStampUtc: () => string,
+ *   pathExists: (path: string) => Promise<boolean>,
+ *   planVerifyHint: (changeId: string) => string,
+ *   readText: (path: string) => Promise<string>,
+ *   splitDeclaredValues: (s: string) => string[],
+ *   validateChangeArtifacts: (gitRoot: string, changeId: string, options: any) => Promise<any>,
+ *   writeText: (path: string, content: string) => Promise<void>,
+ *   UserError: typeof import("../errors.js").UserError
+ * }} deps
+ */
+export async function runChangeEvidenceWorkflow(input, deps) {
+  const { gitRoot, changeId, changeDir, proposalText, options } = input;
+  const planDecl = deps.extractId("Plan_File", proposalText) || deps.extractId("Plan file", proposalText);
+  const planFiles = deps.splitDeclaredValues(planDecl).map((item) => String(item || "").replace(/^\.\//, ""));
+  const planRel = planFiles.length === 1 ? planFiles[0] : "";
+  const planAbs = planRel ? path.join(gitRoot, planRel) : "";
+  const planText = planAbs && (await deps.pathExists(planAbs)) ? await deps.readText(planAbs) : "";
+
+  const now = deps.nowStampUtc();
+  const evidenceDir = path.join(changeDir, "evidence");
+  const reviewDir = path.join(changeDir, "review");
+  const analysisDir = path.join(changeDir, "analysis");
+  const patchesDir = path.join(changeDir, "patches");
+  await deps.ensureDir(evidenceDir);
+  await deps.ensureDir(reviewDir);
+  await deps.ensureDir(analysisDir);
+  await deps.ensureDir(patchesDir);
+
+  /** @type {string[]} */
+  const created = [];
+  const branch = await deps.currentBranch(gitRoot);
+  const status = await deps.computeChangeStatus(gitRoot, changeId);
+
+  const statusPath = path.join(evidenceDir, `change-status-${now}.json`);
+  await deps.writeText(
+    statusPath,
+    JSON.stringify(
+      {
+        generated_at: deps.nowIsoUtc(),
+        ws_root: gitRoot,
+        change_id: changeId,
+        branch: branch || "",
+        phase: status.phase,
+        tasks: status.tasks,
+        bindings: status.bindings,
+        truth: {
+          baseline: { label: status.baselineLabel, at: status.baselineAt },
+          drift_files: status.driftFiles,
+        },
+        evidence: status.evidence?.counts || null,
+        collaboration: status.collaboration?.counts || null,
+        note: "aiws change evidence status snapshot; does not contain secrets.",
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+  created.push(relFromRoot(gitRoot, statusPath));
+
+  /** @type {any | null} */
+  let validateRes = null;
+  let validateFailed = false;
+  let validatePathForError = "";
+  if (!options.noValidate) {
+    validateRes = await deps.validateChangeArtifacts(gitRoot, changeId, { strict: true, allowTruthDrift: false });
+    const validatePath = path.join(evidenceDir, `change-validate-strict-${now}.json`);
+    await deps.writeText(validatePath, JSON.stringify(validateRes, null, 2) + "\n");
+    created.push(relFromRoot(gitRoot, validatePath));
+    validateFailed = validateRes.ok !== true;
+    validatePathForError = validatePath;
+  }
+
+  const validateStampDir = path.join(gitRoot, ".agentdocs", "tmp", "aiws-validate");
+  const latestValidateStamp = await findLatestFileByMtime(validateStampDir, (name) => name.endsWith(".json"));
+  if (latestValidateStamp) {
+    const dest = path.join(evidenceDir, `aiws-validate-stamp-${now}.json`);
+    await fs.copyFile(latestValidateStamp, dest);
+    created.push(relFromRoot(gitRoot, dest));
+  }
+
+  const syncStampDir = path.join(gitRoot, ".agentdocs", "tmp", "change-sync");
+  const latestSyncStamp = await findLatestFileByMtime(syncStampDir, (name) => name.endsWith(`-${changeId}.json`));
+  if (latestSyncStamp) {
+    const dest = path.join(evidenceDir, `change-sync-stamp-${now}.json`);
+    await fs.copyFile(latestSyncStamp, dest);
+    created.push(relFromRoot(gitRoot, dest));
+  }
+
+  for (const { fileName, persistentKind } of TMP_REVIEW_FALLBACKS) {
+    const src = tmpReviewFallbackPath(gitRoot, fileName);
+    if (!(await deps.pathExists(src))) continue;
+    const dest = persistentKind === "evidence" ? path.join(evidenceDir, fileName) : path.join(reviewDir, fileName);
+    if (!(await deps.pathExists(dest))) {
+      await fs.copyFile(src, dest);
+    }
+    const rel = relFromRoot(gitRoot, dest);
+    if (!created.includes(rel)) created.push(rel);
+  }
+
+  if (await deps.pathExists(reviewDir)) {
+    try {
+      const reviewEntries = await fs.readdir(reviewDir, { withFileTypes: true });
+      for (const entry of reviewEntries) {
+        if (!entry.isFile()) continue;
+        if (entry.name === "codex-review.md") continue;
+        if (!entry.name.endsWith(".md")) continue;
+        const rel = relFromRoot(gitRoot, path.join(reviewDir, entry.name));
+        if (!created.includes(rel)) created.push(rel);
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  const collaboration = await collectCollaborationArtifacts(gitRoot, changeDir);
+  const collaborationPath = path.join(evidenceDir, `collaboration-summary-${now}.json`);
+  await deps.writeText(
+    collaborationPath,
+    JSON.stringify(
+      {
+        generated_at: deps.nowIsoUtc(),
+        ws_root: gitRoot,
+        change_id: changeId,
+        counts: collaboration.counts,
+        dirs: collaboration.dirs,
+        note: "aiws collaboration summary; patch files are drafts and must be reviewed before apply.",
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+  created.push(relFromRoot(gitRoot, collaborationPath));
+
+  const summaryAbs = path.join(evidenceDir, `delivery-summary-${now}.md`);
+  await deps.writeText(
+    summaryAbs,
+    buildDeliverySummary({
+      gitRoot,
+      changeId,
+      branch: branch || "",
+      status,
+      collaboration,
+      created,
+      validateRes,
+      validateFailed,
+    }),
+  );
+  created.push(relFromRoot(gitRoot, summaryAbs));
+
+  const declaredEvidence = deps.extractId("Evidence_Path", proposalText) || deps.extractId("Evidence_Path(s)", proposalText);
+  const existingProposalEvidence = deps.splitDeclaredValues(declaredEvidence).map((item) => String(item || "").replace(/^\.\//, ""));
+  const mergedEvidence = mergeDeclaredValues(existingProposalEvidence, created);
+  const mergedEvidenceText = formatDeclaredValues(mergedEvidence);
+
+  const updatedProposal = upsertProposalEvidencePath(proposalText, mergedEvidenceText);
+  if (updatedProposal.changed) {
+    await deps.writeText(path.join(changeDir, "proposal.md"), updatedProposal.text);
+  }
+
+  let planUpdated = false;
+  if (planAbs && planText) {
+    const existingPlanEvidence = deps
+      .splitDeclaredValues(deps.extractId("Evidence_Path", planText) || deps.extractId("Evidence_Path(s)", planText))
+      .map((item) => String(item || "").replace(/^\.\//, ""));
+    const mergedPlanEvidence = mergeDeclaredValues(existingPlanEvidence, mergedEvidence);
+    const mergedPlanEvidenceText = formatDeclaredValues(mergedPlanEvidence);
+    const updatedPlan = upsertIdLine(planText, ["Evidence_Path", "Evidence_Path(s)"], mergedPlanEvidenceText, { insertAfterLabels: ["Plan_File", "Contract_Row"] });
+    if (updatedPlan.changed) {
+      await deps.writeText(planAbs, updatedPlan.text);
+      planUpdated = true;
+    }
+  }
+
+  await deps.appendMetricsEvent(gitRoot, changeId, "evidence", {
+    generated_at: deps.nowIsoUtc(),
+    created: created.length,
+    strict_validate: options.noValidate ? "skipped" : validateRes && validateRes.ok === true ? "ok" : "failed",
+    allow_fail: options.allowFail === true,
+  });
+
+  /** @type {string[]} */
+  const outputLines = [];
+  outputLines.push(`✓ aiws change evidence: ${changeId}`);
+  outputLines.push(`dir: ${path.relative(gitRoot, changeDir)}`);
+  if (planRel) outputLines.push(`Plan_File: ${planRel}`);
+  outputLines.push("created:");
+  if (created.length > 0) {
+    for (const item of created) outputLines.push(`- ${item}`);
+  } else {
+    outputLines.push("- (none)");
+  }
+  outputLines.push("updated:");
+  outputLines.push(`- ${path.relative(gitRoot, path.join(changeDir, "proposal.md"))} (Evidence_Path)`);
+  if (planRel && planText && planUpdated) outputLines.push(`- ${planRel} (Evidence_Path)`);
+  else if (planRel && planText) outputLines.push(`- ${planRel} (Evidence_Path)`);
+  outputLines.push("");
+  outputLines.push("next:");
+  outputLines.push(`- ${deps.planVerifyHint(changeId)}`);
+  if (validateFailed) outputLines.push("- fix validation errors, then re-run evidence (or run with --allow-fail to proceed)");
+  else outputLines.push(`- verify evidence gate: \`aiws change validate ${changeId} --strict --check-evidence\``);
+
+  let errorToThrow = null;
+  if (validateFailed && !options.allowFail) {
+    const details = (validateRes && validateRes.raw ? String(validateRes.raw) : "").trim() || "Validation failed (see evidence JSON for details).";
+    const hint = validatePathForError ? `\n\nevidence:\n- ${path.relative(gitRoot, validatePathForError)}` : "";
+    errorToThrow = new deps.UserError("Failed to generate evidence due to strict validation errors.", { details: `${details}${hint}` });
+  }
+
+  return {
+    output: outputLines.join("\n") + "\n",
+    errorToThrow,
+  };
+}