@aipper/aiws 0.0.10 → 0.0.12

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@aipper/aiws",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "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.10"
+    "@aipper/aiws-spec": "0.0.12"
   },
   "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 { dashboardServeCommand } from "./commands/dashboard.js";
 import {
   changeArchiveCommand,
   changeFinishCommand,
@@ -42,6 +43,10 @@ export async function cliMain(argv) {
     printHooksHelp();
     return 0;
   }
+  if (args[0] === "dashboard" && (args.includes("-h") || args.includes("--help"))) {
+    printDashboardHelp();
+    return 0;
+  }
   if (args[0] === "change" && (args.includes("-h") || args.includes("--help"))) {
     printChangeHelp();
     return 0;
@@ -209,6 +214,27 @@ export async function cliMain(argv) {
           throw new UserError(`Unknown hooks subcommand: ${sub}`, { details: "Use `aiws hooks --help` to see available subcommands." });
       }
     }
+    case "dashboard": {
+      const sub = args.shift();
+      if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
+        printDashboardHelp();
+        return 0;
+      }
+      switch (sub) {
+        case "serve": {
+          const { options } = parseArgs(args, {
+            host: { type: "string" },
+            port: { type: "string" },
+          });
+          const host = options.host ?? "127.0.0.1";
+          const port = options.port ? Number.parseInt(String(options.port), 10) : 3456;
+          await dashboardServeCommand({ host, port });
+          return 0;
+        }
+        default:
+          throw new UserError(`Unknown dashboard subcommand: ${sub}`, { details: "Use `aiws dashboard --help` to see available subcommands." });
+      }
+    }
     case "change": {
       const sub = args.shift();
       if (!sub || sub === "help" || sub === "--help" || sub === "-h") {
@@ -356,6 +382,7 @@ Usage:
   aiws validate [path] [--stamp]
   aiws rollback [path] <timestamp|latest>
   aiws change <subcommand>
+  aiws dashboard <subcommand>
   aiws codex <subcommand>
   aiws hooks <subcommand>
 
@@ -401,6 +428,19 @@ Notes:
 `);
 }
 
+function printDashboardHelp() {
+  console.log(`aiws dashboard
+
+Usage:
+  aiws dashboard serve [--host 127.0.0.1] [--port 3456]
+
+Notes:
+  - Local-only dashboard, no external dependencies.
+  - Recommended: run change quality gate first (AI tools: $ws-plan-verify):
+    aiws change validate <change-id> --strict
+`);
+}
+
 function printChangeHelp() {
   console.log(`aiws change
 
@@ -421,6 +461,9 @@ Notes:
   - change-id must be kebab-case: ^[a-z0-9]+(-[a-z0-9]+)*$
   - If your git branch matches change/<change-id> (or changes/ws/ws-change prefixes),
     you can omit <change-id> for status/next/validate/sync/archive/finish.
+  - Execution quality gate first: aiws change validate [change-id] --strict
+    (equivalent to running $ws-plan-verify in AI tools).
+  - status/next now prioritize quality-gate guidance before coding ($ws-dev).
   - 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/commands/change.js

@@ -14,7 +14,7 @@ const CHANGE_ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /**
  * @param {string} changeId
  */
-function assertValidChangeId(changeId) {
+export function assertValidChangeId(changeId) {
   if (!changeId || !CHANGE_ID_RE.test(changeId)) {
     throw new UserError(`Invalid change id (use kebab-case): ${changeId}`);
   }
@@ -301,7 +301,7 @@ function escapeRegExp(s) {
  * @param {string} text
  */
 function extractId(label, text) {
-  const re = new RegExp(`^.*${escapeRegExp(label)}.*?[:=]\\s*(.+)$`, "m");
+  const re = new RegExp(`^.*${escapeRegExp(label)}.*?[:=][ \\t]*(.*)$`, "m");
   const m = re.exec(text);
   if (!m) return "";
   let v = String(m[1] || "").trim();
@@ -310,6 +310,205 @@ function extractId(label, text) {
   return v;
 }
 
+/**
+ * @param {string} s
+ */
+function splitDeclaredValues(s) {
+  return String(s || "")
+    .split(/[,;\n]+/g)
+    .map((x) => x.trim().replace(/^`+/, "").replace(/`+$/, "").trim())
+    .filter(Boolean);
+}
+
+/**
+ * @param {string} changeId
+ */
+function planVerifyHint(changeId) {
+  return `执行前质量门（优先）：\`aiws change validate ${changeId} --strict\`（AI 工具中等价于 \`$ws-plan-verify\`）`;
+}
+
+/**
+ * Compute change status as JSON-friendly object (used by dashboard and CLI).
+ *
+ * @param {string} gitRoot
+ * @param {string} changeId
+ */
+export async function computeChangeStatus(gitRoot, changeId) {
+  assertValidChangeId(changeId);
+  await ensureTruthFiles(gitRoot);
+
+  const changeDir = changeDirAbs(gitRoot, changeId);
+  if (!(await pathExists(changeDir))) throw new UserError(`Missing change dir: ${path.relative(gitRoot, changeDir)}`);
+
+  const proposal = await fileState(changeDir, "proposal.md");
+  const tasks = await fileState(changeDir, "tasks.md");
+  const design = await fileState(changeDir, "design.md");
+
+  const metaPath = path.join(changeDir, ".ws-change.json");
+  let metaState = "missing";
+  /** @type {any} */
+  let meta = null;
+  if (await pathExists(metaPath)) {
+    metaState = "ok";
+    try {
+      meta = JSON.parse(await readText(metaPath));
+    } catch {
+      metaState = "invalid";
+      meta = null;
+    }
+  }
+
+  const reqId = proposal.state === "ok" ? extractId("Req_ID", proposal.text) : "";
+  const probId = proposal.state === "ok" ? extractId("Problem_ID", proposal.text) : "";
+  const contractRow = proposal.state === "ok" ? extractId("Contract_Row", proposal.text) || extractId("Contract_Row(s)", proposal.text) : "";
+  const planFile = proposal.state === "ok" ? extractId("Plan_File", proposal.text) || extractId("Plan file", proposal.text) : "";
+  const evidencePath = proposal.state === "ok" ? extractId("Evidence_Path", proposal.text) || extractId("Evidence_Path(s)", proposal.text) : "";
+  const evidencePaths = splitDeclaredValues(evidencePath);
+  const taskProgress = tasks.state === "ok" ? checkboxStats(tasks.text) : { total: 0, done: 0, unchecked: 0, hasCheckboxes: false };
+
+  const curTruth = await snapshotTruthShaOnly(gitRoot);
+  const { baselineLabel, baselineAt, driftFiles } = meta ? truthDrift(curTruth, meta) : { baselineLabel: "-", baselineAt: "", driftFiles: [] };
+
+  /** @type {string[]} */
+  const blockersStrict = [];
+  /** @type {string[]} */
+  const blockersArchive = [];
+
+  if (metaState !== "ok") {
+    blockersStrict.push("missing/invalid .ws-change.json (run `aiws change sync <id>` to regenerate)");
+  }
+
+  for (const [rel, st] of [
+    ["proposal.md", proposal],
+    ["tasks.md", tasks],
+  ]) {
+    if (st.state !== "ok") {
+      blockersStrict.push(`missing/empty ${rel}`);
+      continue;
+    }
+    if (st.placeholders > 0) blockersStrict.push(`unrendered template placeholders in ${rel}`);
+    if (st.wsTodo > 0) blockersStrict.push(`WS:TODO markers remain in ${rel}`);
+  }
+
+  if (design.state === "ok") {
+    if (design.placeholders > 0) blockersStrict.push("unrendered template placeholders in design.md");
+    if (design.wsTodo > 0) blockersStrict.push("WS:TODO markers remain in design.md");
+  }
+
+  if (proposal.state === "ok" && !(reqId || probId)) {
+    blockersStrict.push("proposal.md missing attribution (Req_ID or Problem_ID)");
+  }
+
+  if (!taskProgress.hasCheckboxes) blockersStrict.push("tasks.md has no checkbox tasks ('- [ ]' or '- [x]')");
+  if (driftFiles.length > 0) blockersStrict.push(`truth drift vs ${baselineLabel} baseline (run \`aiws change sync ${changeId}\`)`);
+
+  blockersArchive.push(...blockersStrict);
+  if (taskProgress.unchecked > 0) blockersArchive.push(`tasks.md still has unchecked tasks (${taskProgress.unchecked} items)`);
+
+  return {
+    ok: true,
+    changeId,
+    dir: path.relative(gitRoot, changeDir),
+    metaState,
+    reqId,
+    probId,
+    bindings: {
+      contractRow,
+      planFile,
+      evidencePaths,
+    },
+    tasks: taskProgress,
+    baselineLabel,
+    baselineAt,
+    driftFiles,
+    blockersStrict,
+    blockersArchive,
+    hints: {
+      planVerify: planVerifyHint(changeId),
+      dev: "质量门通过后再进入编码：在 AI 工具中运行 `$ws-dev`",
+    },
+  };
+}
+
+function parseChangeCheckerOutput(stdout, stderr) {
+  const text = [String(stdout || ""), String(stderr || "")].filter(Boolean).join("\n");
+  /** @type {string[]} */
+  const errors = [];
+  /** @type {string[]} */
+  const warnings = [];
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (line.startsWith("error: ")) errors.push(line.replace(/^error:\s*/, ""));
+    else if (line.startsWith("warn: ")) warnings.push(line.replace(/^warn:\s*/, ""));
+  }
+  return { errors, warnings, raw: text.trim() };
+}
+
+function classifyCheckMessage(msg) {
+  const s = String(msg || "");
+  if (s.includes("truth file") || s.includes("truth drift") || s.includes("allow-truth-drift")) return "truth_drift";
+  if (s.includes("WS:TODO") || s.includes("unrendered template placeholders")) return "placeholders";
+  if (s.includes("missing:") || s.includes("empty:") || s.includes("Missing change dir")) return "missing_files";
+  if (s.includes("Change_ID") || s.includes("Req_ID") || s.includes("Problem_ID") || s.includes("Contract_Row") || s.includes("Plan_File") || s.includes("Evidence_Path")) return "bindings";
+  if (s.includes("missing required sections") || s.includes("has empty sections") || s.includes("Plan section") || s.includes("Verify section") || s.includes("scope is too broad") || s.includes("too abstract")) {
+    return "plan_quality";
+  }
+  return "other";
+}
+
+function groupCheckMessages(errors, warnings) {
+  const groups = {
+    truth_drift: { errors: [], warnings: [] },
+    missing_files: { errors: [], warnings: [] },
+    placeholders: { errors: [], warnings: [] },
+    bindings: { errors: [], warnings: [] },
+    plan_quality: { errors: [], warnings: [] },
+    other: { errors: [], warnings: [] },
+  };
+
+  for (const m of errors || []) {
+    const k = classifyCheckMessage(m);
+    groups[k].errors.push(m);
+  }
+  for (const m of warnings || []) {
+    const k = classifyCheckMessage(m);
+    groups[k].warnings.push(m);
+  }
+  return groups;
+}
+
+/**
+ * Run ws_change_check.py and return parsed results for dashboards/tools.
+ *
+ * @param {string} gitRoot
+ * @param {string} changeId
+ * @param {{ strict: boolean, allowTruthDrift: boolean }} options
+ */
+export async function validateChangeArtifacts(gitRoot, changeId, options) {
+  assertValidChangeId(changeId);
+  await ensureTruthFiles(gitRoot);
+
+  const checker = await resolveWsChangeChecker(gitRoot);
+  const args = [...checker.args, "--workspace-root", gitRoot, "--change-id", changeId];
+  if (options.strict) args.push("--strict");
+  if (options.allowTruthDrift) args.push("--allow-truth-drift");
+
+  const res = await runPython(gitRoot, ["-u", ...args]);
+  const parsed = parseChangeCheckerOutput(res.stdout, res.stderr);
+  return {
+    ok: res.code === 0,
+    changeId,
+    strict: options.strict === true,
+    allowTruthDrift: options.allowTruthDrift === true,
+    exitCode: res.code,
+    errors: parsed.errors,
+    warnings: parsed.warnings,
+    groups: groupCheckMessages(parsed.errors, parsed.warnings),
+    raw: parsed.raw,
+  };
+}
+
 /**
  * @param {string} text
  */
@@ -1089,90 +1288,35 @@ export async function changeStatusCommand(options) {
   await ensureTruthFiles(gitRoot);
 
   const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "status" });
-  assertValidChangeId(changeId);
+  const st = await computeChangeStatus(gitRoot, changeId);
 
-  const changeDir = changeDirAbs(gitRoot, changeId);
-  if (!(await pathExists(changeDir))) throw new UserError(`Missing change dir: ${path.relative(gitRoot, changeDir)}`);
-
-  const proposal = await fileState(changeDir, "proposal.md");
-  const tasks = await fileState(changeDir, "tasks.md");
-  const design = await fileState(changeDir, "design.md");
-
-  const metaPath = path.join(changeDir, ".ws-change.json");
-  let metaState = "missing";
-  /** @type {any} */
-  let meta = null;
-  if (await pathExists(metaPath)) {
-    metaState = "ok";
-    try {
-      meta = JSON.parse(await readText(metaPath));
-    } catch {
-      metaState = "invalid";
-      meta = null;
-    }
-  }
-
-  const reqId = proposal.state === "ok" ? extractId("Req_ID", proposal.text) : "";
-  const probId = proposal.state === "ok" ? extractId("Problem_ID", proposal.text) : "";
-  const taskProgress = tasks.state === "ok" ? checkboxStats(tasks.text) : { total: 0, done: 0, unchecked: 0, hasCheckboxes: false };
-
-  const curTruth = await snapshotTruthShaOnly(gitRoot);
-  const { baselineLabel, baselineAt, driftFiles } = meta ? truthDrift(curTruth, meta) : { baselineLabel: "-", baselineAt: "", driftFiles: [] };
-
-  /** @type {string[]} */
-  const blockersStrict = [];
-  /** @type {string[]} */
-  const blockersArchive = [];
-
-  if (metaState !== "ok") {
-    blockersStrict.push("missing/invalid .ws-change.json (run `aiws change sync <id>` to regenerate)");
-  }
-
-  for (const [rel, st] of [
-    ["proposal.md", proposal],
-    ["tasks.md", tasks],
-  ]) {
-    if (st.state !== "ok") {
-      blockersStrict.push(`missing/empty ${rel}`);
-      continue;
-    }
-    if (st.placeholders > 0) blockersStrict.push(`unrendered template placeholders in ${rel}`);
-    if (st.wsTodo > 0) blockersStrict.push(`WS:TODO markers remain in ${rel}`);
-  }
-
-  if (design.state === "ok") {
-    if (design.placeholders > 0) blockersStrict.push("unrendered template placeholders in design.md");
-    if (design.wsTodo > 0) blockersStrict.push("WS:TODO markers remain in design.md");
-  }
-
-  if (proposal.state === "ok" && !(reqId || probId)) {
-    blockersStrict.push("proposal.md missing attribution (Req_ID or Problem_ID)");
-  }
-
-  if (!taskProgress.hasCheckboxes) blockersStrict.push("tasks.md has no checkbox tasks ('- [ ]' or '- [x]')");
-  if (driftFiles.length > 0) blockersStrict.push(`truth drift vs ${baselineLabel} baseline (run \`aiws change sync ${changeId}\`)`);
-
-  blockersArchive.push(...blockersStrict);
-  if (taskProgress.unchecked > 0) blockersArchive.push(`tasks.md still has unchecked tasks (${taskProgress.unchecked} items)`);
-
-  console.log(`✓ aiws change status: ${changeId}`);
-  console.log(`dir: ${path.relative(gitRoot, changeDir)}`);
-  console.log(`meta: ${metaState}`);
-  if (reqId) console.log(`Req_ID: ${reqId}`);
-  if (probId) console.log(`Problem_ID: ${probId}`);
-  console.log(`tasks: ${taskProgress.done}/${taskProgress.total} (unchecked=${taskProgress.unchecked})`);
-  console.log(`baseline: ${baselineLabel}${baselineAt ? ` (at=${baselineAt})` : ""}`);
-  console.log(`drift: ${driftFiles.length > 0 ? driftFiles.join(", ") : "(none)"}`);
+  console.log(`✓ aiws change status: ${st.changeId}`);
+  console.log(`dir: ${st.dir}`);
+  console.log(`meta: ${st.metaState}`);
+  if (st.reqId) console.log(`Req_ID: ${st.reqId}`);
+  if (st.probId) console.log(`Problem_ID: ${st.probId}`);
+  console.log(`tasks: ${st.tasks.done}/${st.tasks.total} (unchecked=${st.tasks.unchecked})`);
+  console.log(`baseline: ${st.baselineLabel}${st.baselineAt ? ` (at=${st.baselineAt})` : ""}`);
+  console.log(`drift: ${st.driftFiles.length > 0 ? st.driftFiles.join(", ") : "(none)"}`);
 
   console.log("");
   console.log("Blockers (strict):");
-  if (blockersStrict.length === 0) console.log("- (none)");
-  else for (const b of blockersStrict) console.log(`- ${b}`);
+  if (st.blockersStrict.length === 0) console.log("- (none)");
+  else for (const b of st.blockersStrict) console.log(`- ${b}`);
 
   console.log("");
   console.log("Blockers (archive):");
-  if (blockersArchive.length === 0) console.log("- (none)");
-  else for (const b of blockersArchive) console.log(`- ${b}`);
+  if (st.blockersArchive.length === 0) console.log("- (none)");
+  else for (const b of st.blockersArchive) console.log(`- ${b}`);
+
+  console.log("");
+  console.log("Next (recommended):");
+  console.log(`- ${planVerifyHint(st.changeId)}`);
+  if (st.blockersStrict.length === 0) {
+    console.log("- 质量门通过后再进入编码：在 AI 工具中运行 `$ws-dev`（小步实现 + 可复现验证）");
+  } else {
+    console.log("- 先修复 Blockers (strict) 后复跑质量门，再进入 `$ws-dev`");
+  }
 }
 
 /**
@@ -1248,11 +1392,15 @@ export async function changeNextCommand(options) {
   }
 
   if (actions.length > 0) {
-    actions.push(`严格校验：\`aiws change validate ${changeId} --strict\``);
+    console.log(`- ${planVerifyHint(changeId)}`);
     for (const a of actions) console.log(`- ${a}`);
+    console.log(`- 修复后复跑质量门：\`aiws change validate ${changeId} --strict\``);
+    console.log("- 质量门通过后再进入编码：在 AI 工具中运行 `$ws-dev`");
     return;
   }
 
+  console.log(`- ${planVerifyHint(changeId)}`);
+  console.log("- 若仍需继续编码，先通过质量门，再在 AI 工具中运行 `$ws-dev`");
   console.log("- 生成交叉审计报告：在 AI 工具内运行 `/ws-review`（或按 AI_PROJECT.md 手工审计）");
   console.log(`- 归档：\`aiws change archive ${changeId}\``);
 }
@@ -1269,17 +1417,12 @@ export async function changeValidateCommand(options) {
   const changeId = await resolveChangeId(gitRoot, options.changeId, { command: "validate" });
   assertValidChangeId(changeId);
 
-  const checker = await resolveWsChangeChecker(gitRoot);
-  const args = [...checker.args, "--workspace-root", gitRoot, "--change-id", changeId];
-  if (options.strict) args.push("--strict");
-  if (options.allowTruthDrift) args.push("--allow-truth-drift");
-
-  const res = await runPython(gitRoot, ["-u", ...args]);
-  if (res.stdout) process.stdout.write(res.stdout);
-  if (res.stderr) process.stderr.write(res.stderr);
-  if (res.code !== 0) {
-    throw new UserError("");
-  }
+  const res = await validateChangeArtifacts(gitRoot, changeId, {
+    strict: options.strict === true,
+    allowTruthDrift: options.allowTruthDrift === true,
+  });
+  if (res.raw) process.stderr.write(res.raw + "\n");
+  if (!res.ok) throw new UserError("");
   console.log(`ok: change validated (${changeId})`);
 }
 

package/src/commands/codex-install-skills.js

@@ -1,3 +1,4 @@
+import fs from "node:fs/promises";
 import path from "node:path";
 import { loadTemplate } from "../spec.js";
 import { UserError } from "../errors.js";
@@ -16,6 +17,11 @@ export async function codexInstallSkillsCommand(options) {
   const skillsDir = resolveCodexSkillsDir(options.skillsDir);
   const dryRun = options.dryRun === true;
   if (!dryRun) await ensureDir(skillsDir);
+  const skillsDirIsSymlink = await fs
+    .lstat(skillsDir)
+    .then((st) => st.isSymbolicLink())
+    .catch(() => false);
+  const skillsDirReal = skillsDirIsSymlink ? await fs.realpath(skillsDir).catch(() => skillsDir) : skillsDir;
 
   const skillFiles = await listTemplateCodexSkills(tpl);
 
@@ -60,9 +66,9 @@ export async function codexInstallSkillsCommand(options) {
     }
   }
 
-  console.log(`${dryRun ? "✓ (dry-run)" : "✓"} aiws codex install-skills: ${skillsDir}`);
+  const header = skillsDirIsSymlink && skillsDirReal !== skillsDir ? `${skillsDir} -> ${skillsDirReal}` : skillsDir;
+  console.log(`${dryRun ? "✓ (dry-run)" : "✓"} aiws codex install-skills: ${header}`);
   if (created.length > 0) console.log(`created: ${created.join(", ")}`);
   if (updated.length > 0) console.log(`updated: ${updated.join(", ")}`);
   if (overwritten.length > 0) console.log(`overwritten: ${overwritten.join(", ")}`);
 }
-

package/src/commands/codex-status-skills.js

@@ -1,3 +1,4 @@
+import fs from "node:fs/promises";
 import path from "node:path";
 import { loadTemplate } from "../spec.js";
 import { normalizeNewlines } from "../hash.js";
@@ -13,6 +14,11 @@ export async function codexStatusSkillsCommand(options) {
   const tpl = await loadTemplate(templateId);
 
   const skillsDir = resolveCodexSkillsDir(options.skillsDir);
+  const skillsDirIsSymlink = await fs
+    .lstat(skillsDir)
+    .then((st) => st.isSymbolicLink())
+    .catch(() => false);
+  const skillsDirReal = skillsDirIsSymlink ? await fs.realpath(skillsDir).catch(() => skillsDir) : skillsDir;
   const skillFiles = await listTemplateCodexSkills(tpl);
 
   /** @type {Array<{ name: string, status: "ok" | "missing" | "unmanaged" | "outdated" }>} */
@@ -42,13 +48,16 @@ export async function codexStatusSkillsCommand(options) {
     /** @type {{ ok: number, missing: number, unmanaged: number, outdated: number }} */ ({ ok: 0, missing: 0, unmanaged: 0, outdated: 0 }),
   );
 
-  console.log(`✓ aiws codex status-skills: ${skillsDir}`);
+  const header = skillsDirIsSymlink && skillsDirReal !== skillsDir ? `${skillsDir} -> ${skillsDirReal}` : skillsDir;
+  console.log(`✓ aiws codex status-skills: ${header}`);
   console.log(`ok=${counts.ok} missing=${counts.missing} unmanaged=${counts.unmanaged} outdated=${counts.outdated}`);
   for (const r of rows) {
     console.log(`${r.status}\t${r.name}`);
   }
+  if (counts.ok === 0 && counts.missing === rows.length && skillsDirIsSymlink) {
+    console.log("Note: skills dir is a symlink; if you installed to a different dir, pass --dir (or set CODEX_HOME).");
+  }
   if (counts.missing > 0 || counts.outdated > 0) {
     console.log("Next: aiws codex install-skills");
   }
 }
-

package/src/commands/dashboard.js

@@ -0,0 +1,179 @@
+import fs from "node:fs/promises";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { UserError } from "../errors.js";
+import { runCommand } from "../exec.js";
+import { pathExists } from "../fs.js";
+import { computeChangeStatus, validateChangeArtifacts } from "./change.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+function send(res, status, headers, body) {
+  res.writeHead(status, headers);
+  res.end(body);
+}
+
+function sendJson(res, status, obj) {
+  send(res, status, { "content-type": "application/json; charset=utf-8" }, JSON.stringify(obj, null, 2));
+}
+
+function guessContentType(p) {
+  const ext = path.extname(p).toLowerCase();
+  if (ext === ".html") return "text/html; charset=utf-8";
+  if (ext === ".css") return "text/css; charset=utf-8";
+  if (ext === ".js") return "text/javascript; charset=utf-8";
+  if (ext === ".json") return "application/json; charset=utf-8";
+  return "application/octet-stream";
+}
+
+function safeJoin(baseDir, rel) {
+  const abs = path.resolve(baseDir, rel);
+  const baseAbs = path.resolve(baseDir);
+  if (!abs.startsWith(baseAbs + path.sep) && abs !== baseAbs) {
+    throw new UserError("Invalid path.", { exitCode: 1 });
+  }
+  return abs;
+}
+
+/**
+ * @param {string} absPath
+ */
+async function resolveGitRoot(absPath) {
+  let res;
+  try {
+    res = await runCommand("git", ["rev-parse", "--show-toplevel"], { cwd: absPath });
+  } catch (e) {
+    throw new UserError("git is required for aiws dashboard commands.", { details: e instanceof Error ? e.message : String(e) });
+  }
+  if (res.code !== 0) {
+    throw new UserError("Not a git repository.", { details: res.stderr || res.stdout });
+  }
+  const root = String(res.stdout || "").trim();
+  if (!root) throw new UserError("Failed to resolve git repository root.");
+  return root;
+}
+
+/**
+ * @param {string} gitRoot
+ */
+async function ensureTruthFiles(gitRoot) {
+  const required = ["AI_PROJECT.md", "AI_WORKSPACE.md", "REQUIREMENTS.md"];
+  const missing = [];
+  for (const f of required) {
+    if (!(await pathExists(path.join(gitRoot, f)))) missing.push(f);
+  }
+  if (missing.length > 0) {
+    throw new UserError("AI Workspace truth files missing.", {
+      details: `Root: ${gitRoot}\nMissing:\n${missing.map((m) => `- ${m}`).join("\n")}\n\nHint: run \`aiws init .\` (new) or \`aiws update .\` (migrate).`,
+      exitCode: 1,
+    });
+  }
+}
+
+async function listChangeIds(gitRoot) {
+  const dir = path.join(gitRoot, "changes");
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    return entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+  } catch {
+    return [];
+  }
+}
+
+function parseUrl(reqUrl) {
+  const u = new URL(reqUrl || "/", "http://127.0.0.1");
+  return { pathname: u.pathname, searchParams: u.searchParams };
+}
+
+export async function dashboardServeCommand(options) {
+  const gitRoot = await resolveGitRoot(process.cwd());
+  await ensureTruthFiles(gitRoot);
+
+  const host = String(options.host || "127.0.0.1").trim() || "127.0.0.1";
+  const port = Number.isFinite(options.port) ? options.port : Number.parseInt(String(options.port || "3456"), 10);
+  if (!Number.isFinite(port) || port < 0 || port > 65535) {
+    throw new UserError(`Invalid --port: ${options.port}`, { exitCode: 1 });
+  }
+
+  const dashboardDir = path.join(__dirname, "..", "dashboard");
+  const assetsDir = path.join(dashboardDir);
+
+  const server = http.createServer(async (req, res) => {
+    try {
+      const { pathname, searchParams } = parseUrl(req.url || "/");
+      if ((req.method || "GET") !== "GET") {
+        sendJson(res, 405, { ok: false, error: "method not allowed" });
+        return;
+      }
+
+      if (pathname === "/api/changes") {
+        const ids = await listChangeIds(gitRoot);
+        const changes = [];
+        for (const id of ids) {
+          try {
+            const st = await computeChangeStatus(gitRoot, id);
+            changes.push(st);
+          } catch (e) {
+            changes.push({ changeId: id, ok: false, error: e instanceof Error ? e.message : String(e) });
+          }
+        }
+        sendJson(res, 200, { ok: true, changes });
+        return;
+      }
+
+      const m = pathname.match(/^\/api\/change\/([^/]+)\/validate$/);
+      if (m) {
+        const changeId = decodeURIComponent(m[1] || "");
+        const strict = searchParams.get("strict") === "1" || searchParams.get("strict") === "true";
+        const allowTruthDrift = searchParams.get("allow_truth_drift") === "1" || searchParams.get("allow_truth_drift") === "true";
+        const result = await validateChangeArtifacts(gitRoot, changeId, { strict, allowTruthDrift });
+        sendJson(res, 200, result);
+        return;
+      }
+
+      if (pathname === "/" || pathname === "/index.html") {
+        const p = path.join(dashboardDir, "index.html");
+        const text = await fs.readFile(p);
+        send(res, 200, { "content-type": "text/html; charset=utf-8" }, text);
+        return;
+      }
+
+      if (pathname.startsWith("/assets/")) {
+        const rel = pathname.replace(/^\/assets\//, "");
+        const p = safeJoin(assetsDir, rel);
+        const buf = await fs.readFile(p);
+        send(res, 200, { "content-type": guessContentType(p) }, buf);
+        return;
+      }
+
+      sendJson(res, 404, { ok: false, error: "not found" });
+    } catch (e) {
+      sendJson(res, 500, { ok: false, error: e instanceof Error ? e.message : String(e) });
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen({ host, port }, () => resolve());
+  });
+
+  const addr = server.address();
+  const realPort = addr && typeof addr === "object" ? addr.port : port;
+  console.log(`✓ aiws dashboard serve`);
+  console.log(`root: ${gitRoot}`);
+  console.log(`url: http://${host}:${realPort}/`);
+  console.log("note: press Ctrl+C to stop");
+
+  await new Promise((resolve) => {
+    let stopping = false;
+    const stop = () => {
+      if (stopping) return;
+      stopping = true;
+      server.close(() => resolve());
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+  });
+}

package/src/dashboard/app.js

@@ -0,0 +1,168 @@
+async function fetchJson(url) {
+  const res = await fetch(url, { headers: { "Accept": "application/json" } });
+  const text = await res.text();
+  let data = null;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = { ok: false, error: "invalid json", raw: text };
+  }
+  if (!res.ok) {
+    return { ok: false, status: res.status, ...data };
+  }
+  return data;
+}
+
+function escapeHtml(s) {
+  return String(s || "")
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll("\"", "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+function blockersBadge(n) {
+  const cls = n === 0 ? "good" : n <= 2 ? "warn" : "bad";
+  return `<span class="badge"><span class="dot ${cls}"></span>${n === 0 ? "none" : `${n} blockers`}</span>`;
+}
+
+function driftBadge(n) {
+  const cls = n === 0 ? "good" : "warn";
+  return `<span class="badge"><span class="dot ${cls}"></span>${n === 0 ? "clean" : `${n} drift`}</span>`;
+}
+
+function tasksBadge(done, total, unchecked) {
+  const cls = unchecked === 0 && total > 0 ? "good" : unchecked === 0 ? "warn" : "warn";
+  const label = total > 0 ? `${done}/${total} (unchecked=${unchecked})` : "no tasks";
+  return `<span class="badge"><span class="dot ${cls}"></span>${label}</span>`;
+}
+
+function renderDetails(obj) {
+  return JSON.stringify(obj, null, 2);
+}
+
+function renderValidateGroups(groups) {
+  const order = [
+    ["truth_drift", "Truth drift"],
+    ["missing_files", "Missing files"],
+    ["placeholders", "Placeholders / WS:TODO"],
+    ["bindings", "Bindings"],
+    ["plan_quality", "Plan quality"],
+    ["other", "Other"],
+  ];
+  const g = groups && typeof groups === "object" ? groups : {};
+  const lines = [];
+  for (const [key, label] of order) {
+    const it = g[key] || { errors: [], warnings: [] };
+    const errs = Array.isArray(it.errors) ? it.errors : [];
+    const warns = Array.isArray(it.warnings) ? it.warnings : [];
+    if (errs.length === 0 && warns.length === 0) continue;
+    lines.push(`${label}:`);
+    for (const e of errs) lines.push(`  - error: ${e}`);
+    for (const w of warns) lines.push(`  - warn: ${w}`);
+    lines.push("");
+  }
+  return lines.join("\n").trim();
+}
+
+async function runStrictValidate(changeId) {
+  return fetchJson(`/api/change/${encodeURIComponent(changeId)}/validate?strict=1`);
+}
+
+async function refresh() {
+  const summaryEl = document.getElementById("summary");
+  const bodyEl = document.getElementById("changes-body");
+  const detailsTitleEl = document.getElementById("details-title");
+  const detailsEl = document.getElementById("details");
+
+  summaryEl.textContent = "Loading…";
+  bodyEl.innerHTML = "";
+
+  const data = await fetchJson("/api/changes");
+  if (!data || data.ok === false) {
+    summaryEl.textContent = "Failed";
+    detailsTitleEl.textContent = "Error";
+    detailsEl.textContent = renderDetails(data);
+    return;
+  }
+
+  const items = Array.isArray(data.changes) ? data.changes : [];
+  summaryEl.textContent = `${items.length} change(s)`;
+
+  bodyEl.innerHTML = items
+    .map((c) => {
+      const changeId = c.changeId || c.id || "";
+      const tasks = c.tasks || {};
+      const drift = Array.isArray(c.driftFiles) ? c.driftFiles.length : 0;
+      const blockers = Array.isArray(c.blockersStrict) ? c.blockersStrict.length : 0;
+      const bindings = c.bindings || {};
+      const planFile = bindings.planFile || "";
+      const evidencePaths = Array.isArray(bindings.evidencePaths) ? bindings.evidencePaths : [];
+      const pe = `${planFile ? `<div><code>${escapeHtml(planFile)}</code></div>` : `<div class="muted">(no Plan_File)</div>`}
+        <div class="muted">${evidencePaths.length} evidence path(s)</div>`;
+      return `<tr data-change="${escapeHtml(changeId)}">
+        <td><a class="link" href="#" data-open="${escapeHtml(changeId)}">${escapeHtml(changeId)}</a></td>
+        <td>${tasksBadge(tasks.done || 0, tasks.total || 0, tasks.unchecked || 0)}</td>
+        <td>${driftBadge(drift)}</td>
+        <td>${blockersBadge(blockers)}</td>
+        <td>${pe}</td>
+        <td>
+          <button class="btn secondary" data-validate="${escapeHtml(changeId)}">Validate --strict</button>
+        </td>
+      </tr>`;
+    })
+    .join("");
+
+  bodyEl.querySelectorAll("[data-open]").forEach((a) => {
+    a.addEventListener("click", (ev) => {
+      ev.preventDefault();
+      const changeId = a.getAttribute("data-open") || "";
+      const selected = items.find((x) => (x.changeId || x.id) === changeId) || null;
+      detailsTitleEl.textContent = changeId ? `change: ${changeId}` : "Details";
+      if (!selected) {
+        detailsEl.textContent = renderDetails(selected);
+        return;
+      }
+      const b = selected.bindings || {};
+      const evid = Array.isArray(b.evidencePaths) ? b.evidencePaths : [];
+      const lines = [];
+      lines.push(`changeId: ${selected.changeId || ""}`);
+      if (selected.reqId) lines.push(`Req_ID: ${selected.reqId}`);
+      if (selected.probId) lines.push(`Problem_ID: ${selected.probId}`);
+      if (b.planFile) lines.push(`Plan_File: ${b.planFile}`);
+      if (b.contractRow) lines.push(`Contract_Row: ${b.contractRow}`);
+      if (evid.length > 0) {
+        lines.push("Evidence_Path:");
+        for (const p of evid) lines.push(`- ${p}`);
+      }
+      if (Array.isArray(selected.blockersStrict) && selected.blockersStrict.length > 0) {
+        lines.push("");
+        lines.push("Blockers (strict):");
+        for (const x of selected.blockersStrict) lines.push(`- ${x}`);
+      }
+      lines.push("");
+      lines.push("Raw JSON:");
+      lines.push(renderDetails(selected));
+      detailsEl.textContent = lines.join("\n");
+    });
+  });
+
+  bodyEl.querySelectorAll("[data-validate]").forEach((btn) => {
+    btn.addEventListener("click", async () => {
+      const changeId = btn.getAttribute("data-validate") || "";
+      if (!changeId) return;
+      btn.disabled = true;
+      btn.textContent = "Running…";
+      detailsTitleEl.textContent = `validate --strict: ${changeId}`;
+      const res = await runStrictValidate(changeId);
+      const grouped = renderValidateGroups(res && res.groups ? res.groups : null);
+      detailsEl.textContent = grouped ? `${grouped}\n\nRaw JSON:\n${renderDetails(res)}` : renderDetails(res);
+      btn.disabled = false;
+      btn.textContent = "Validate --strict";
+    });
+  });
+}
+
+document.getElementById("refresh")?.addEventListener("click", refresh);
+refresh();

package/src/dashboard/index.html

@@ -0,0 +1,60 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>AIWS Dashboard</title>
+    <link rel="stylesheet" href="/assets/style.css" />
+  </head>
+  <body>
+    <header class="header">
+      <div class="brand">
+        <div class="logo">AIWS</div>
+        <div class="title">
+          <div class="h1">AIWS Dashboard</div>
+          <div class="sub">Local status for changes, quality gate, and evidence</div>
+        </div>
+      </div>
+      <div class="actions">
+        <button id="refresh" class="btn">Refresh</button>
+      </div>
+    </header>
+
+    <main class="main">
+      <section class="panel">
+        <div class="panel-head">
+          <div class="panel-title">Changes</div>
+          <div class="panel-meta" id="summary"></div>
+        </div>
+        <div class="table-wrap">
+          <table class="table" id="changes">
+            <thead>
+              <tr>
+                <th>Change</th>
+                <th>Tasks</th>
+                <th>Truth drift</th>
+                <th>Blockers (strict)</th>
+                <th>Plan & Evidence</th>
+                <th>Actions</th>
+              </tr>
+            </thead>
+            <tbody id="changes-body"></tbody>
+          </table>
+        </div>
+        <div class="hint">
+          建议：先运行执行前质量门 <code>aiws change validate &lt;id&gt; --strict</code>（等价 <code>$ws-plan-verify</code>），通过后再进入 <code>$ws-dev</code>。
+        </div>
+      </section>
+
+      <section class="panel" id="details-panel">
+        <div class="panel-head">
+          <div class="panel-title">Details</div>
+          <div class="panel-meta" id="details-title">Select a change</div>
+        </div>
+        <pre class="log" id="details"></pre>
+      </section>
+    </main>
+
+    <script type="module" src="/assets/app.js"></script>
+  </body>
+</html>

package/src/dashboard/style.css

@@ -0,0 +1,215 @@
+:root {
+  --bg: #0b1020;
+  --panel: rgba(255, 255, 255, 0.06);
+  --panel2: rgba(255, 255, 255, 0.03);
+  --text: rgba(255, 255, 255, 0.92);
+  --muted: rgba(255, 255, 255, 0.62);
+  --border: rgba(255, 255, 255, 0.12);
+  --good: #3ddc97;
+  --warn: #ffcc00;
+  --bad: #ff5c7a;
+  --link: #8ab4ff;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  font-family: ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, "Helvetica Neue", Arial, "Noto Sans", "Liberation Sans", sans-serif;
+  color: var(--text);
+  background: radial-gradient(1200px 800px at 20% 0%, rgba(138, 180, 255, 0.12), transparent 60%),
+    radial-gradient(900px 700px at 80% 10%, rgba(61, 220, 151, 0.10), transparent 55%),
+    var(--bg);
+}
+
+code {
+  background: rgba(255, 255, 255, 0.08);
+  padding: 0.15em 0.35em;
+  border-radius: 6px;
+}
+
+.header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 18px 22px;
+  border-bottom: 1px solid var(--border);
+  background: rgba(0, 0, 0, 0.2);
+  backdrop-filter: blur(10px);
+  position: sticky;
+  top: 0;
+  z-index: 10;
+}
+
+.brand {
+  display: flex;
+  align-items: center;
+  gap: 14px;
+}
+
+.logo {
+  width: 38px;
+  height: 38px;
+  border-radius: 10px;
+  display: grid;
+  place-items: center;
+  background: rgba(138, 180, 255, 0.16);
+  border: 1px solid rgba(138, 180, 255, 0.30);
+  font-weight: 700;
+}
+
+.h1 {
+  font-size: 16px;
+  font-weight: 700;
+}
+
+.sub {
+  font-size: 12px;
+  color: var(--muted);
+  margin-top: 2px;
+}
+
+.btn {
+  padding: 8px 12px;
+  border-radius: 10px;
+  border: 1px solid var(--border);
+  background: rgba(255, 255, 255, 0.06);
+  color: var(--text);
+  cursor: pointer;
+}
+
+.btn:hover {
+  background: rgba(255, 255, 255, 0.09);
+}
+
+.btn:disabled {
+  opacity: 0.55;
+  cursor: not-allowed;
+}
+
+.btn.secondary {
+  background: rgba(255, 255, 255, 0.03);
+}
+
+.btn.danger {
+  border-color: rgba(255, 92, 122, 0.4);
+}
+
+.main {
+  display: grid;
+  grid-template-columns: 1.6fr 1fr;
+  gap: 18px;
+  padding: 18px 22px;
+}
+
+@media (max-width: 1100px) {
+  .main {
+    grid-template-columns: 1fr;
+  }
+}
+
+.panel {
+  background: var(--panel);
+  border: 1px solid var(--border);
+  border-radius: 14px;
+  overflow: hidden;
+}
+
+.panel-head {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 14px 14px;
+  background: var(--panel2);
+  border-bottom: 1px solid var(--border);
+}
+
+.panel-title {
+  font-weight: 700;
+}
+
+.panel-meta {
+  color: var(--muted);
+  font-size: 12px;
+}
+
+.muted {
+  color: var(--muted);
+  font-size: 12px;
+}
+
+.table-wrap {
+  overflow: auto;
+}
+
+.table {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+.table th,
+.table td {
+  padding: 10px 12px;
+  border-bottom: 1px solid rgba(255, 255, 255, 0.08);
+  vertical-align: top;
+  font-size: 13px;
+}
+
+.table th {
+  text-align: left;
+  color: rgba(255, 255, 255, 0.78);
+  font-weight: 600;
+}
+
+.badge {
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 2px 8px;
+  border-radius: 999px;
+  border: 1px solid var(--border);
+  font-size: 12px;
+  color: var(--muted);
+}
+
+.dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: var(--muted);
+}
+
+.dot.good {
+  background: var(--good);
+}
+.dot.warn {
+  background: var(--warn);
+}
+.dot.bad {
+  background: var(--bad);
+}
+
+.link {
+  color: var(--link);
+  text-decoration: none;
+}
+.link:hover {
+  text-decoration: underline;
+}
+
+.hint {
+  padding: 12px 14px;
+  color: var(--muted);
+  font-size: 12px;
+}
+
+.log {
+  margin: 0;
+  padding: 12px 14px;
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+  font-size: 12px;
+  line-height: 1.45;
+  white-space: pre-wrap;
+}