aigroup-workflow 2.2.0 → 2.2.1

package/docs/workflow-pipeline.md

@@ -1,8 +1,9 @@
 # 工作流 Phase 心智模型
 
 > 8 个 phase 是**完整路径上限**，不是强制路径——主会话按任务复杂度和风险**裁剪**。
-> 状态真相源：`.orchestration/<session>/<worker>/status.md`。
-> **完结契约**：worker 转 `completed` 前必须调用 `session.cjs complete` 回写 handoff 标准四节（`Summary` / `Files Changed` / `Validation` / `Follow-ups`），否则视作"未真正完成"。`append` 仅记录过程（设计草稿/需求笔记），不替代 `complete`。
+> 状态真相源：`.orchestration/<session>/<worker>/status.json`（`state` 字段）。
+> **完结契约**：worker 转 `completed` 前必须调用 `session.cjs complete` 回写 handoff 标准字段（`summary` / `filesChanged` / `validation` / `followUps`，写入 `finalizedAt` 时间戳），否则视作"未真正完成"。`append` 仅追加过程记录（设计草稿/需求笔记 → `handoff.notes[]`），不替代 `complete`。
+> 产物全部以 JSON 为唯一格式，shape 由 `schemas/orchestration/*.schema.json` 约束；用 `session.cjs validate <session>` 校验。
 
 ## 完整路径
 
@@ -23,12 +24,12 @@
 |---|-------|-----------|--------|---------------------------|---------|
 | 1 | 需求收集 | `brainstorming`（前段） | 主会话 | `architect/requirements.md` | 需求文档包含目标 / 用户场景 / 成功标准 |
 | 2 | 需求验证 | `brainstorming`（中段：challenge） | 主会话 | 在 requirements.md 追加验证结论 | 无歧义、无矛盾、用户确认 |
-| 3 | 方案设计 | `brainstorming`（终段：spec 锁定） | `architect` | `architect/handoff.md`（ADR 格式） | 至少 2 个候选方案 + 推荐理由 |
-| 4 | 任务拆解 | `writing-plans` | `planner` | `planner/handoff.md` | 3–7 个阶段，每个含 agent / 验证命令 |
+| 3 | 方案设计 | `brainstorming`（终段：spec 锁定） | `architect` | `architect/handoff.json`（ADR 格式） | 至少 2 个候选方案 + 推荐理由 |
+| 4 | 任务拆解 | `writing-plans` | `planner` | `planner/handoff.json` | 3–7 个阶段，每个含 agent / 验证命令 |
 | 4→5 桥 | 隔离工作区 | `using-git-worktrees` | 主会话执行 git | session `README.md` 记录 worktree 路径 | worktree 创建、依赖装好、测试基线通过 |
-| 5 | 实施开发 | subagent 派遣（推荐）/ `executing-plans` | `tdd-guide`（TDD 路径）/ 语言专项 reviewer | `<agent>/handoff.md` 或直接改代码 | 改动文件清单 + 验证证据（typecheck / test） |
+| 5 | 实施开发 | subagent 派遣（推荐）/ `executing-plans` | `tdd-guide`（TDD 路径）/ 语言专项 reviewer | `<agent>/handoff.json` 或直接改代码 | 改动文件清单 + 验证证据（typecheck / test） |
 | 6a | 审查发起 | `requesting-code-review` | 主会话向 `code-reviewer` 派遣（敏感场景加 `security-reviewer`、关键路径加 `e2e-runner`、按栈加语言专项 reviewer） | `code-reviewer/request.md` | 审查范围 / 验收点 / 关注项清单完整 |
-| 6b | 审查反馈处理 | `receiving-code-review` | 主会话逐条决议 | `code-reviewer/handoff.md`（含决议） | 每条反馈有"采纳/反驳/记录"决议且证据闭环（Stage 1 规格 ✓ Stage 2 代码质量 ✓） |
+| 6b | 审查反馈处理 | `receiving-code-review` | 主会话逐条决议 | `code-reviewer/handoff.json`（含决议） | 每条反馈有"采纳/反驳/记录"决议且证据闭环（`handoff.stages.spec` ✓ `handoff.stages.quality` ✓） |
 | 7 | 文档更新 | （无强制 skill） | `doc-updater` 或主会话直接改 | 直接改 `docs/`；session `README.md` 留笔记 | docs/ARCHITECTURE / docs/PROJECT_CONTEXT / API 文档已同步 |
 | 8 | 分支收尾 | `finishing-a-development-branch` | 主会话 | session `README.md` 总结 | 集成 / PR / 归档 |
 
@@ -69,7 +70,7 @@
 | Discard 确认 | phase 8 选项 4 | 删除分支 + worktree 不可恢复 | 必须用户键入 `discard` 字面量；其他输入一律视为放弃 |
 | 审查反馈分歧 | phase 6b（`receiving-code-review` 中） | reviewer 与实施 agent 对同一问题给出冲突结论时 | 暂停，把分歧摘要呈给用户决议 |
 
-**自动决策**（不打断用户）：phase 间流转、handoff 文件生成、`status.md` 推进、worktree 路径分配、`session.cjs` 状态写入、phase 内的子 agent 派遣。
+**自动决策**（不打断用户）：phase 间流转、handoff 文件生成、`status.json` 推进、worktree 路径分配、`session.cjs` 状态写入、phase 内的子 agent 派遣。
 
 ## Session 存在条件
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aigroup-workflow",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "AI 团队协作框架 — 通过角色派遣、工作流管道和 Harness 传感器驱动 AI 协作开发",
   "type": "module",
   "bin": {

package/scripts/hooks/checks/orchestration-artifacts.cjs

@@ -5,8 +5,14 @@ const path = require('path');
 const { createReport, ROOT, relPosix, dirExists } = require('../lib/runner.cjs');
 
 const COORD_ROOT = path.join(ROOT, '.orchestration');
-const STAGE1_RE = /(stage.?1|阶段.?1|规格符合)/i;
-const STAGE2_RE = /(stage.?2|阶段.?2|代码质量)/i;
+
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (_error) {
+    return null;
+  }
+}
 
 function run() {
   const report = createReport();
@@ -22,37 +28,36 @@ function run() {
 
     for (const worker of workers) {
       const workerDir = path.join(sessionDir, worker.name);
-      const statusFile = path.join(workerDir, 'status.md');
-
-      // 轻量 worker：只要求 handoff + status，跳过 task.md
-      let lightweight = false;
-      try {
-        const raw = fs.readFileSync(statusFile, 'utf8');
-        lightweight = /^\s*-\s*Lightweight:\s*true/m.test(raw);
-      } catch (_error) { /* fall through */ }
+      const statusFile = path.join(workerDir, 'status.json');
+      const handoffFile = path.join(workerDir, 'handoff.json');
+      const taskFile = path.join(workerDir, 'task.json');
 
-      const required = lightweight
-        ? ['handoff.md', 'status.md']
-        : ['task.md', 'handoff.md', 'status.md'];
+      // JSON 化后所有 worker 三件套统一：task + handoff + status 都必须存在。
+      // 轻量与否通过 task.lightweight / status.lightweight 字段区分，不再靠文件缺失。
+      const required = [
+        ['task.json', taskFile],
+        ['handoff.json', handoffFile],
+        ['status.json', statusFile]
+      ];
 
-      for (const file of required) {
-        const full = path.join(workerDir, file);
+      for (const [name, full] of required) {
         if (!fs.existsSync(full)) {
           report.fail(
-            `${relPosix(workerDir)}/ 缺失 ${file}${lightweight ? '（轻量 worker）' : ''}`,
-            '用 node scripts/orchestration/session.cjs add-worker 创建（轻量加 --lightweight）'
+            `${relPosix(workerDir)}/ 缺失 ${name}`,
+            '用 `node scripts/orchestration/session.cjs add-worker` 创建（轻量加 --lightweight）'
           );
         }
       }
 
+      // code-reviewer 强制双阶段产物
       if (worker.name === 'code-reviewer') {
-        const handoff = path.join(workerDir, 'handoff.md');
-        if (fs.existsSync(handoff)) {
-          const content = fs.readFileSync(handoff, 'utf8');
-          if (!STAGE1_RE.test(content) && !STAGE2_RE.test(content)) {
+        const handoff = readJsonSafe(handoffFile);
+        if (handoff && handoff.finalizedAt) {
+          const stages = handoff.stages || {};
+          if (!stages.spec || !stages.quality) {
             report.fail(
-              `${relPosix(handoff)} 缺少阶段标识`,
-              '审查报告必须含 Stage 1 (规格符合性) 和 Stage 2 (代码质量)'
+              `${relPosix(handoffFile)} 缺少双阶段产物`,
+              '审查报告必须填 handoff.stages.spec (Stage 1 规格符合性) + handoff.stages.quality (Stage 2 代码质量)；用 `--stage-spec`/`--stage-quality` 传给 complete 命令'
             );
           }
         }

package/scripts/hooks/checks/workflow-state.cjs

@@ -4,7 +4,7 @@ const fs = require('fs');
 const path = require('path');
 const { createReport, ROOT, relPosix, dirExists } = require('../lib/runner.cjs');
 
-// 真相源：.orchestration/<session>/<worker>/status.md
+// 真相源：.orchestration/<session>/<worker>/status.json (state 字段)
 // 在 Stop 事件中：若任一 worker state=running，说明主会话要停但 worker 没走到终态。
 // 终态：completed | failed | blocked （完成、失败、主动阻塞都允许 Stop）
 
@@ -12,9 +12,8 @@ const TERMINAL_STATES = new Set(['completed', 'failed', 'blocked']);
 
 function readState(statusFile) {
   try {
-    const content = fs.readFileSync(statusFile, 'utf8');
-    const match = content.match(/^\s*-\s*State:\s*(\S+)/m);
-    return match ? match[1].toLowerCase() : null;
+    const data = JSON.parse(fs.readFileSync(statusFile, 'utf8'));
+    return typeof data.state === 'string' ? data.state.toLowerCase() : null;
   } catch (_error) {
     return null;
   }
@@ -35,7 +34,7 @@ function run() {
       .filter(entry => entry.isDirectory());
 
     for (const worker of workers) {
-      const statusFile = path.join(sessionDir, worker.name, 'status.md');
+      const statusFile = path.join(sessionDir, worker.name, 'status.json');
       const state = readState(statusFile);
       if (state === 'running') {
         stuck.push(relPosix(statusFile));

package/scripts/orchestration/lib/orchestrator.cjs

@@ -2,9 +2,17 @@
 
 const fs = require('fs');
 const path = require('path');
+const { validateAgainstSchema, loadSchema } = require('./validate.cjs');
 
 const ROOT = path.resolve(__dirname, '..', '..', '..');
 const COORDINATION_ROOT = path.join(ROOT, '.orchestration');
+const SCHEMAS_ROOT = path.join(ROOT, 'schemas', 'orchestration');
+const SCHEMA_VERSION = '1.0';
+
+const TERMINAL_STATES = new Set(['completed', 'failed', 'blocked']);
+const VALID_STATES = ['not_started', 'running', 'blocked', 'completed', 'failed'];
+
+// ─── Path helpers ───
 
 function toPosix(p) {
   return p.split(path.sep).join('/');
@@ -28,8 +36,7 @@ function timestamp() {
 }
 
 function sessionDir(sessionName) {
-  const slug = slugify(sessionName, 'session');
-  return path.join(COORDINATION_ROOT, slug);
+  return path.join(COORDINATION_ROOT, slugify(sessionName, 'session'));
 }
 
 function workerDir(sessionName, workerName) {
@@ -40,79 +47,142 @@ function workerArtifacts(sessionName, workerName) {
   const dir = workerDir(sessionName, workerName);
   return {
     dir,
-    task: path.join(dir, 'task.md'),
-    handoff: path.join(dir, 'handoff.md'),
-    status: path.join(dir, 'status.md')
+    task: path.join(dir, 'task.json'),
+    handoff: path.join(dir, 'handoff.json'),
+    status: path.join(dir, 'status.json')
   };
 }
 
+function sessionMetaPath(sessionName) {
+  return path.join(sessionDir(sessionName), 'session.json');
+}
+
+function sessionPlanPath(sessionName) {
+  return path.join(sessionDir(sessionName), 'plan.json');
+}
+
+// ─── IO ───
+
 function ensureDir(dirPath) {
   fs.mkdirSync(dirPath, { recursive: true });
 }
 
-function writeFile(filePath, content) {
+function readJson(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    throw new Error(`failed to parse ${relPosix(filePath)}: ${error.message}`);
+  }
+}
+
+function writeJson(filePath, data) {
   ensureDir(path.dirname(filePath));
-  fs.writeFileSync(filePath, content.endsWith('\n') ? content : content + '\n', 'utf8');
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
 }
 
-function buildTaskFile({ sessionName, workerName, agent, objective, context = [], deliverables = [] }) {
-  const ctx = context.length > 0 ? context.map(line => `- ${line}`).join('\n') : '- _无_';
-  const deliv = deliverables.length > 0 ? deliverables.map(line => `- ${line}`).join('\n') : '- 见 handoff.md 模板';
-  const artifacts = workerArtifacts(sessionName, workerName);
-  return [
-    `# Worker Task: ${workerName}`,
-    '',
-    `- Session: \`${sessionName}\``,
-    `- Agent: \`${agent}\``,
-    `- Created: ${timestamp()}`,
-    `- Handoff: \`${relPosix(artifacts.handoff)}\``,
-    `- Status: \`${relPosix(artifacts.status)}\``,
-    '',
-    '## Objective',
-    objective.trim(),
-    '',
-    '## Context',
-    ctx,
-    '',
-    '## Deliverables',
-    deliv,
-    '',
-    '## Completion Rules',
-    '- 不再向下派遣 subagent，结果写进最终响应',
-    '- 主会话负责把响应抄写进 `handoff.md`',
-    '- 主会话负责更新 `status.md`'
-  ].join('\n');
-}
-
-function buildHandoffFile({ workerName }) {
-  return [
-    `# Handoff: ${workerName}`,
-    '',
-    '## Summary',
-    '- Pending',
-    '',
-    '## Files Changed',
-    '- Pending',
-    '',
-    '## Validation',
-    '- Pending',
-    '',
-    '## Follow-ups',
-    '- Pending'
-  ].join('\n');
-}
-
-function buildStatusFile({ workerName, state = 'not_started', lightweight = false }) {
-  const lines = [
-    `# Status: ${workerName}`,
-    '',
-    `- State: ${state}`,
-    `- Updated: ${timestamp()}`
-  ];
-  if (lightweight) lines.push('- Lightweight: true');
-  return lines.join('\n');
+// ─── Session-level ───
+
+function readSessionMeta(sessionName) {
+  return readJson(sessionMetaPath(sessionName));
+}
+
+function writeSessionMeta(sessionName, meta) {
+  writeJson(sessionMetaPath(sessionName), meta);
 }
 
+function initSession(sessionName) {
+  const slug = slugify(sessionName, 'session');
+  const dir = sessionDir(sessionName);
+  ensureDir(dir);
+  const metaPath = sessionMetaPath(sessionName);
+  if (!fs.existsSync(metaPath)) {
+    const meta = {
+      schemaVersion: SCHEMA_VERSION,
+      name: slug,
+      label: sessionName,
+      createdAt: timestamp(),
+      workers: []
+    };
+    writeJson(metaPath, meta);
+  }
+  return dir;
+}
+
+function registerWorker(sessionName, workerName) {
+  const slug = slugify(workerName, 'worker');
+  const meta = readSessionMeta(sessionName) || {
+    schemaVersion: SCHEMA_VERSION,
+    name: slugify(sessionName, 'session'),
+    label: sessionName,
+    createdAt: timestamp(),
+    workers: []
+  };
+  if (!Array.isArray(meta.workers)) meta.workers = [];
+  if (!meta.workers.includes(slug)) meta.workers.push(slug);
+  meta.updatedAt = timestamp();
+  writeSessionMeta(sessionName, meta);
+}
+
+function touchSession(sessionName) {
+  const meta = readSessionMeta(sessionName);
+  if (!meta) return;
+  meta.updatedAt = timestamp();
+  writeSessionMeta(sessionName, meta);
+}
+
+// ─── Worker artifacts: builders ───
+
+function buildTask({ sessionName, workerName, agent, objective, context = [], deliverables = [], dependsOn = [], lightweight = false }) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    session: slugify(sessionName, 'session'),
+    worker: slugify(workerName, 'worker'),
+    agent,
+    createdAt: timestamp(),
+    objective: objective.trim(),
+    context: context.filter(Boolean),
+    deliverables: deliverables.filter(Boolean),
+    dependsOn: dependsOn.filter(Boolean),
+    lightweight: Boolean(lightweight),
+    completionRules: [
+      '不再向下派遣 subagent，结果写进最终响应',
+      '主会话负责把响应写进 handoff.json',
+      '主会话负责更新 status.json'
+    ]
+  };
+}
+
+function buildHandoff({ sessionName, workerName }) {
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    session: slugify(sessionName, 'session'),
+    worker: slugify(workerName, 'worker'),
+    summary: null,
+    filesChanged: [],
+    validation: null,
+    followUps: [],
+    notes: [],
+    finalizedAt: null
+  };
+}
+
+function buildStatus({ sessionName, workerName, state = 'not_started', lightweight = false, details = null }) {
+  const at = timestamp();
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    session: slugify(sessionName, 'session'),
+    worker: slugify(workerName, 'worker'),
+    state,
+    updatedAt: at,
+    lightweight: Boolean(lightweight),
+    details: details || null,
+    history: [{ state, at, details: details || null }]
+  };
+}
+
+// ─── Worker operations ───
+
 function createWorker(spec) {
   const { sessionName, workerName, lightweight = false } = spec;
   if (!sessionName) throw new Error('sessionName is required');
@@ -122,94 +192,251 @@ function createWorker(spec) {
 
   const artifacts = workerArtifacts(sessionName, workerName);
   ensureDir(artifacts.dir);
-  if (!lightweight) {
-    writeFile(artifacts.task, buildTaskFile(spec));
-  }
-  writeFile(artifacts.handoff, buildHandoffFile({ workerName }));
-  writeFile(artifacts.status, buildStatusFile({ workerName, lightweight }));
+  // task.json 总是写入（统一 shape）；轻量 worker 通过 task.lightweight=true 区分，
+  // 而非通过文件缺失。hook 与下游消费者按字段判断，不靠 fs.exists。
+  writeJson(artifacts.task, buildTask(spec));
+  writeJson(artifacts.handoff, buildHandoff({ sessionName, workerName }));
+  writeJson(artifacts.status, buildStatus({ sessionName, workerName, lightweight }));
+  registerWorker(sessionName, workerName);
   return { ...artifacts, lightweight };
 }
 
-function isLightweight(statusFile) {
-  try {
-    const raw = fs.readFileSync(statusFile, 'utf8');
-    return /^\s*-\s*Lightweight:\s*true/m.test(raw);
-  } catch (_error) {
-    return false;
-  }
+function isLightweight(sessionName, workerName) {
+  const status = readJson(workerArtifacts(sessionName, workerName).status);
+  return Boolean(status && status.lightweight);
 }
 
 function updateStatus(sessionName, workerName, state, details = '') {
+  if (!VALID_STATES.includes(state)) {
+    throw new Error(`invalid state '${state}'. Valid: ${VALID_STATES.join(' | ')}`);
+  }
   const artifacts = workerArtifacts(sessionName, workerName);
-  const lightweight = isLightweight(artifacts.status);
-  const body = [
-    `# Status: ${workerName}`,
-    '',
-    `- State: ${state}`,
-    `- Updated: ${timestamp()}`
-  ];
-  if (lightweight) body.push('- Lightweight: true');
-  if (details) body.push('', details.trim());
-  writeFile(artifacts.status, body.join('\n'));
+  const existing = readJson(artifacts.status) || buildStatus({ sessionName, workerName });
+  const at = timestamp();
+  const entry = { state, at, details: details ? String(details).trim() : null };
+  existing.state = state;
+  existing.updatedAt = at;
+  existing.details = entry.details;
+  if (!Array.isArray(existing.history)) existing.history = [];
+  existing.history.push(entry);
+  writeJson(artifacts.status, existing);
+  touchSession(sessionName);
   return artifacts.status;
 }
 
 function appendHandoff(sessionName, workerName, sectionTitle, content) {
+  if (!sectionTitle) throw new Error('section title required');
+  if (!content) throw new Error('content required');
   const artifacts = workerArtifacts(sessionName, workerName);
-  const existing = fs.existsSync(artifacts.handoff)
-    ? fs.readFileSync(artifacts.handoff, 'utf8')
-    : buildHandoffFile({ workerName });
-  const block = `\n## ${sectionTitle} (${timestamp()})\n${content.trim()}\n`;
-  writeFile(artifacts.handoff, existing.replace(/\s+$/, '') + block);
+  const existing = readJson(artifacts.handoff) || buildHandoff({ sessionName, workerName });
+  if (!Array.isArray(existing.notes)) existing.notes = [];
+  existing.notes.push({
+    section: String(sectionTitle).trim(),
+    content: String(content).trim(),
+    addedAt: timestamp()
+  });
+  writeJson(artifacts.handoff, existing);
+  touchSession(sessionName);
   return artifacts.handoff;
 }
 
-const STANDARD_SECTIONS = ['Summary', 'Files Changed', 'Validation', 'Follow-ups'];
+/**
+ * Finalize handoff. fields keys: summary, filesChanged, validation, followUps, stages.
+ * - summary: string
+ * - filesChanged: string[] | {path, action?, note?}[]
+ * - validation: string
+ * - followUps: string[]
+ * - stages: { spec?: string, quality?: string }   (code-reviewer only)
+ */
+function completeHandoff(sessionName, workerName, fields = {}) {
+  const artifacts = workerArtifacts(sessionName, workerName);
+  const existing = readJson(artifacts.handoff) || buildHandoff({ sessionName, workerName });
+
+  if (fields.summary !== undefined) existing.summary = String(fields.summary).trim() || null;
+  if (fields.validation !== undefined) existing.validation = String(fields.validation).trim() || null;
+  if (fields.filesChanged !== undefined) existing.filesChanged = normalizeFilesChanged(fields.filesChanged);
+  if (fields.followUps !== undefined) existing.followUps = normalizeFollowUps(fields.followUps);
+  if (fields.stages !== undefined) {
+    const stages = {};
+    if (fields.stages.spec) stages.spec = String(fields.stages.spec).trim();
+    if (fields.stages.quality) stages.quality = String(fields.stages.quality).trim();
+    if (Object.keys(stages).length > 0) existing.stages = stages;
+  }
 
-function replaceStandardSection(body, title, content) {
-  const trimmed = (content || '').trim() || '- _未提供_';
-  const escaped = title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const re = new RegExp(`(^|\\n)## ${escaped}\\n[\\s\\S]*?(?=\\n## |$)`);
-  const replacement = `$1## ${title}\n${trimmed}\n`;
-  if (re.test(body)) return body.replace(re, replacement);
-  return body.replace(/\s+$/, '') + `\n\n## ${title}\n${trimmed}\n`;
+  existing.finalizedAt = timestamp();
+  writeJson(artifacts.handoff, existing);
+  touchSession(sessionName);
+  return artifacts.handoff;
 }
 
-function completeHandoff(sessionName, workerName, fields = {}) {
-  const artifacts = workerArtifacts(sessionName, workerName);
-  let body = fs.existsSync(artifacts.handoff)
-    ? fs.readFileSync(artifacts.handoff, 'utf8')
-    : buildHandoffFile({ workerName });
-  const map = {
-    Summary: fields.summary,
-    'Files Changed': fields.files,
-    Validation: fields.validation,
-    'Follow-ups': fields.followUps
+function normalizeFilesChanged(input) {
+  if (Array.isArray(input)) return input;
+  if (typeof input !== 'string') return [];
+  // Accept newline- or comma-separated string for CLI ergonomics
+  return input
+    .split(/[\n,]/)
+    .map(s => s.trim())
+    .filter(Boolean);
+}
+
+function normalizeFollowUps(input) {
+  if (Array.isArray(input)) return input;
+  if (typeof input !== 'string') return [];
+  return input
+    .split(/\n/)
+    .map(s => s.replace(/^[-*]\s*/, '').trim())
+    .filter(Boolean);
+}
+
+// ─── Plan aggregation ───
+
+function listWorkers(sessionName) {
+  const dir = sessionDir(sessionName);
+  if (!fs.existsSync(dir)) return [];
+  return fs.readdirSync(dir, { withFileTypes: true })
+    .filter(e => e.isDirectory())
+    .map(e => e.name)
+    .sort();
+}
+
+function buildPlan(sessionName) {
+  const workers = listWorkers(sessionName).map(name => {
+    const artifacts = workerArtifacts(sessionName, name);
+    const task = readJson(artifacts.task);
+    const status = readJson(artifacts.status);
+    const handoff = readJson(artifacts.handoff);
+    return {
+      name,
+      agent: (task && task.agent) || (handoff && handoff.agent) || 'unknown',
+      state: (status && status.state) || 'not_started',
+      lightweight: Boolean(status && status.lightweight),
+      dependsOn: (task && Array.isArray(task.dependsOn)) ? task.dependsOn : [],
+      objective: (task && task.objective) || undefined,
+      finalizedAt: (handoff && handoff.finalizedAt) || null
+    };
+  });
+
+  const completedSet = new Set(workers.filter(w => w.state === 'completed').map(w => w.name));
+  const buckets = { ready: [], running: [], blocked: [], completed: [], failed: [], waiting: [] };
+  for (const w of workers) {
+    if (w.state === 'running') buckets.running.push(w.name);
+    else if (w.state === 'blocked') buckets.blocked.push(w.name);
+    else if (w.state === 'completed') buckets.completed.push(w.name);
+    else if (w.state === 'failed') buckets.failed.push(w.name);
+    else {
+      const allDepsDone = w.dependsOn.every(d => completedSet.has(d));
+      if (allDepsDone) buckets.ready.push(w.name);
+      else buckets.waiting.push(w.name);
+    }
+  }
+
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    session: slugify(sessionName, 'session'),
+    generatedAt: timestamp(),
+    workers,
+    buckets
   };
-  for (const title of STANDARD_SECTIONS) {
-    if (map[title] !== undefined && map[title] !== null) {
-      body = replaceStandardSection(body, title, map[title]);
+}
+
+function refreshPlan(sessionName) {
+  const plan = buildPlan(sessionName);
+  writeJson(sessionPlanPath(sessionName), plan);
+  return sessionPlanPath(sessionName);
+}
+
+// ─── Validation ───
+
+const SCHEMA_FILES = {
+  session: 'session.schema.json',
+  plan: 'plan.schema.json',
+  task: 'task.schema.json',
+  handoff: 'handoff.schema.json',
+  status: 'status.schema.json'
+};
+
+function getSchema(kind) {
+  const file = SCHEMA_FILES[kind];
+  if (!file) throw new Error(`unknown schema kind: ${kind}`);
+  return loadSchema(path.join(SCHEMAS_ROOT, file));
+}
+
+function validateArtifact(kind, data) {
+  const schema = getSchema(kind);
+  return validateAgainstSchema(data, schema);
+}
+
+function validateSession(sessionName) {
+  const errors = [];
+  const meta = readJson(sessionMetaPath(sessionName));
+  if (!meta) {
+    errors.push({ file: relPosix(sessionMetaPath(sessionName)), problems: ['file missing'] });
+  } else {
+    const r = validateArtifact('session', meta);
+    if (!r.valid) errors.push({ file: relPosix(sessionMetaPath(sessionName)), problems: r.errors });
+  }
+
+  const planFile = sessionPlanPath(sessionName);
+  if (fs.existsSync(planFile)) {
+    const plan = readJson(planFile);
+    const r = validateArtifact('plan', plan);
+    if (!r.valid) errors.push({ file: relPosix(planFile), problems: r.errors });
+  }
+
+  for (const worker of listWorkers(sessionName)) {
+    const a = workerArtifacts(sessionName, worker);
+    for (const kind of ['task', 'handoff', 'status']) {
+      const file = a[kind];
+      const data = readJson(file);
+      if (!data) {
+        errors.push({ file: relPosix(file), problems: ['file missing or unreadable'] });
+        continue;
+      }
+      const r = validateArtifact(kind, data);
+      if (!r.valid) errors.push({ file: relPosix(file), problems: r.errors });
     }
   }
-  const stamp = `\n<!-- finalized: ${timestamp()} -->\n`;
-  body = body.replace(/\n<!-- finalized: [^>]+ -->\n?/g, '');
-  writeFile(artifacts.handoff, body.replace(/\s+$/, '') + stamp);
-  return artifacts.handoff;
+
+  return errors;
 }
 
 module.exports = {
+  // constants
   COORDINATION_ROOT,
   ROOT,
+  SCHEMAS_ROOT,
+  SCHEMA_VERSION,
+  TERMINAL_STATES,
+  VALID_STATES,
+  // path helpers
   sessionDir,
   workerDir,
   workerArtifacts,
+  sessionMetaPath,
+  sessionPlanPath,
+  // session ops
+  initSession,
+  readSessionMeta,
+  writeSessionMeta,
+  registerWorker,
+  // worker ops
   createWorker,
+  isLightweight,
   updateStatus,
   appendHandoff,
   completeHandoff,
-  isLightweight,
+  // plan
+  listWorkers,
+  buildPlan,
+  refreshPlan,
+  // validation
+  validateArtifact,
+  validateSession,
+  // utils
   slugify,
   timestamp,
   relPosix,
-  toPosix
+  toPosix,
+  readJson,
+  writeJson
 };

package/scripts/orchestration/lib/validate.cjs

@@ -0,0 +1,145 @@
+'use strict';
+
+/**
+ * Minimal JSON Schema (Draft-07 subset) validator — zero deps.
+ *
+ * Supported keywords:
+ *   type, required, enum, const, pattern, format(date-time), additionalProperties,
+ *   properties, items, minLength, minItems, uniqueItems, default(passthrough), oneOf
+ *
+ * Not supported (out of scope for our schemas): $ref resolution across files, allOf,
+ * anyOf, not, dependencies, conditionals (if/then/else). If you add those to a schema,
+ * extend this file.
+ */
+
+const fs = require('fs');
+
+const ISO_DATETIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+
+function loadSchema(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  return JSON.parse(raw);
+}
+
+function jsTypeOf(value) {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  if (Number.isInteger(value)) return 'integer';
+  return typeof value; // string, number, boolean, object, undefined
+}
+
+function matchesType(value, type) {
+  if (Array.isArray(type)) return type.some(t => matchesType(value, t));
+  const actual = jsTypeOf(value);
+  if (type === 'integer') return actual === 'integer';
+  if (type === 'number') return actual === 'integer' || actual === 'number';
+  return actual === type;
+}
+
+function validate(value, schema, pathPrefix = '$') {
+  const errors = [];
+
+  if (schema === true) return errors;
+  if (schema === false) {
+    errors.push(`${pathPrefix}: schema explicitly forbids this value`);
+    return errors;
+  }
+  if (!schema || typeof schema !== 'object') return errors;
+
+  // type
+  if (schema.type !== undefined && !matchesType(value, schema.type)) {
+    errors.push(`${pathPrefix}: expected type ${JSON.stringify(schema.type)}, got ${jsTypeOf(value)}`);
+    return errors; // bail — downstream checks meaningless
+  }
+
+  // const
+  if (schema.const !== undefined && value !== schema.const) {
+    errors.push(`${pathPrefix}: expected const ${JSON.stringify(schema.const)}, got ${JSON.stringify(value)}`);
+  }
+
+  // enum
+  if (Array.isArray(schema.enum) && !schema.enum.includes(value)) {
+    errors.push(`${pathPrefix}: value not in enum ${JSON.stringify(schema.enum)}`);
+  }
+
+  // string-specific
+  if (typeof value === 'string') {
+    if (typeof schema.minLength === 'number' && value.length < schema.minLength) {
+      errors.push(`${pathPrefix}: shorter than minLength ${schema.minLength}`);
+    }
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) {
+      errors.push(`${pathPrefix}: does not match pattern /${schema.pattern}/`);
+    }
+    if (schema.format === 'date-time' && !ISO_DATETIME_RE.test(value)) {
+      errors.push(`${pathPrefix}: not a valid ISO-8601 date-time`);
+    }
+  }
+
+  // array-specific
+  if (Array.isArray(value)) {
+    if (typeof schema.minItems === 'number' && value.length < schema.minItems) {
+      errors.push(`${pathPrefix}: array shorter than minItems ${schema.minItems}`);
+    }
+    if (schema.uniqueItems === true) {
+      const seen = new Set();
+      for (const item of value) {
+        const key = JSON.stringify(item);
+        if (seen.has(key)) {
+          errors.push(`${pathPrefix}: array has duplicate items`);
+          break;
+        }
+        seen.add(key);
+      }
+    }
+    if (schema.items) {
+      for (let i = 0; i < value.length; i += 1) {
+        errors.push(...validate(value[i], schema.items, `${pathPrefix}[${i}]`));
+      }
+    }
+  }
+
+  // object-specific
+  if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+    if (Array.isArray(schema.required)) {
+      for (const key of schema.required) {
+        if (!(key in value)) errors.push(`${pathPrefix}.${key}: required field missing`);
+      }
+    }
+    if (schema.properties) {
+      for (const [key, propSchema] of Object.entries(schema.properties)) {
+        if (key in value) {
+          errors.push(...validate(value[key], propSchema, `${pathPrefix}.${key}`));
+        }
+      }
+    }
+    if (schema.additionalProperties === false && schema.properties) {
+      const allowed = new Set(Object.keys(schema.properties));
+      for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) errors.push(`${pathPrefix}.${key}: additionalProperties not allowed`);
+      }
+    }
+  }
+
+  // oneOf
+  if (Array.isArray(schema.oneOf)) {
+    const matches = schema.oneOf.filter(sub => validate(value, sub, pathPrefix).length === 0);
+    if (matches.length === 0) {
+      errors.push(`${pathPrefix}: matches none of oneOf branches`);
+    } else if (matches.length > 1) {
+      errors.push(`${pathPrefix}: matches ${matches.length} oneOf branches (must match exactly 1)`);
+    }
+  }
+
+  return errors;
+}
+
+function validateAgainstSchema(data, schema) {
+  const errors = validate(data, schema);
+  return { valid: errors.length === 0, errors };
+}
+
+module.exports = {
+  loadSchema,
+  validateAgainstSchema,
+  validate
+};

package/scripts/orchestration/session.cjs

@@ -8,39 +8,52 @@ const {
   ROOT,
   sessionDir,
   workerArtifacts,
+  initSession,
   createWorker,
   updateStatus,
   appendHandoff,
   completeHandoff,
+  refreshPlan,
+  buildPlan,
+  validateSession,
+  readJson,
   slugify,
   relPosix
 } = require('./lib/orchestrator.cjs');
 
-const COMMANDS = ['init', 'add-worker', 'status', 'set-status', 'append', 'complete', 'list', 'help'];
+const COMMANDS = ['init', 'add-worker', 'status', 'set-status', 'append', 'complete', 'plan', 'validate', 'list', 'help'];
 
 function usage() {
   console.log([
     'Usage:',
-    '  node scripts/orchestration/session.js init <session-name>',
+    '  node scripts/orchestration/session.cjs init <session>',
     '  node scripts/orchestration/session.cjs add-worker <session> <worker> --agent <name> --objective <text>',
-    '                                                       [--context <line>]... [--deliverable <line>]... [--lightweight]',
-    '  node scripts/orchestration/session.js set-status <session> <worker> <state> [--details <text>]',
-    '  node scripts/orchestration/session.js append <session> <worker> <section> --content <text>',
+    '                                                  [--context <line>]... [--deliverable <line>]...',
+    '                                                  [--depends-on <worker>]... [--lightweight]',
+    '  node scripts/orchestration/session.cjs set-status <session> <worker> <state> [--details <text>]',
+    '  node scripts/orchestration/session.cjs append <session> <worker> <section> --content <text>',
     '  node scripts/orchestration/session.cjs complete <session> <worker>',
-    '                                                       [--summary <md>] [--files <md>]',
-    '                                                       [--validation <md>] [--follow-ups <md>]',
-    '  node scripts/orchestration/session.js status <session>',
-    '  node scripts/orchestration/session.js list',
+    '                                                  [--summary <text>] [--validation <text>]',
+    '                                                  [--files <newline-or-comma-separated>]',
+    '                                                  [--follow-ups <newline-separated>]',
+    '                                                  [--stage-spec <text>] [--stage-quality <text>]',
+    '  node scripts/orchestration/session.cjs status <session>',
+    '  node scripts/orchestration/session.cjs plan <session>      # refresh and print plan.json',
+    '  node scripts/orchestration/session.cjs validate <session>  # validate all artifacts against schemas',
+    '  node scripts/orchestration/session.cjs list',
     '',
     'States: not_started | running | blocked | completed | failed',
-    `Coordination root: ${relPosix(COORDINATION_ROOT)}/`
+    `Coordination root: ${relPosix(COORDINATION_ROOT)}/`,
+    'Schemas:           schemas/orchestration/'
   ].join('\n'));
 }
 
 const BOOLEAN_FLAGS = new Set(['lightweight']);
+const REPEATABLE_FLAGS = new Set(['context', 'deliverable', 'depends-on']);
 
 function parseFlags(args) {
-  const flags = { context: [], deliverable: [] };
+  const flags = {};
+  for (const k of REPEATABLE_FLAGS) flags[k] = [];
   const positional = [];
   for (let i = 0; i < args.length; i += 1) {
     const arg = args[i];
@@ -51,7 +64,7 @@ function parseFlags(args) {
         continue;
       }
       const value = args[i + 1];
-      if (key === 'context' || key === 'deliverable') {
+      if (REPEATABLE_FLAGS.has(key)) {
         flags[key].push(value);
       } else {
         flags[key] = value;
@@ -65,17 +78,8 @@ function parseFlags(args) {
 }
 
 function cmdInit(name) {
-  if (!name) throw new Error('session-name is required');
-  const dir = sessionDir(name);
-  fs.mkdirSync(dir, { recursive: true });
-  const meta = path.join(dir, 'session.json');
-  if (!fs.existsSync(meta)) {
-    fs.writeFileSync(meta, JSON.stringify({
-      name: slugify(name, 'session'),
-      label: name,
-      createdAt: new Date().toISOString()
-    }, null, 2) + '\n', 'utf8');
-  }
+  if (!name) throw new Error('session name is required');
+  const dir = initSession(name);
   console.log(relPosix(dir));
 }
 
@@ -88,8 +92,9 @@ function cmdAddWorker(session, worker, flags) {
     workerName: worker,
     agent: flags.agent,
     objective: flags.objective,
-    context: flags.context,
-    deliverables: flags.deliverable,
+    context: flags.context || [],
+    deliverables: flags.deliverable || [],
+    dependsOn: flags['depends-on'] || [],
     lightweight: Boolean(flags.lightweight)
   });
   const out = {
@@ -116,37 +121,70 @@ function cmdAppend(session, worker, section, flags) {
 
 function cmdComplete(session, worker, flags) {
   if (!session || !worker) throw new Error('session and worker names are required');
-  const fields = {
-    summary: flags.summary,
-    files: flags.files,
-    validation: flags.validation,
-    followUps: flags['follow-ups']
-  };
-  const provided = Object.values(fields).some(v => v !== undefined && v !== null);
-  if (!provided) {
-    throw new Error('at least one of --summary | --files | --validation | --follow-ups is required');
+  const fields = {};
+  if (flags.summary !== undefined) fields.summary = flags.summary;
+  if (flags.validation !== undefined) fields.validation = flags.validation;
+  if (flags.files !== undefined) fields.filesChanged = flags.files;
+  if (flags['follow-ups'] !== undefined) fields.followUps = flags['follow-ups'];
+  const stages = {};
+  if (flags['stage-spec'] !== undefined) stages.spec = flags['stage-spec'];
+  if (flags['stage-quality'] !== undefined) stages.quality = flags['stage-quality'];
+  if (Object.keys(stages).length > 0) fields.stages = stages;
+
+  if (Object.keys(fields).length === 0) {
+    throw new Error('at least one of --summary | --validation | --files | --follow-ups | --stage-spec | --stage-quality is required');
   }
   const file = completeHandoff(session, worker, fields);
   console.log(relPosix(file));
 }
 
 function cmdStatus(session) {
-  if (!session) throw new Error('session-name is required');
+  if (!session) throw new Error('session name is required');
   const dir = sessionDir(session);
   if (!fs.existsSync(dir)) {
     console.log(`(no such session: ${session})`);
     return;
   }
-  const workers = fs.readdirSync(dir, { withFileTypes: true })
-    .filter(entry => entry.isDirectory())
-    .map(entry => entry.name);
-  const out = workers.map(worker => {
-    const statusPath = workerArtifacts(session, worker).status;
-    const content = fs.existsSync(statusPath) ? fs.readFileSync(statusPath, 'utf8') : '(missing)';
-    const stateLine = content.split('\n').find(line => line.startsWith('- State:'));
-    return `${worker}\t${stateLine ? stateLine.replace('- State:', '').trim() : '?'}`;
+  const plan = buildPlan(session);
+  if (plan.workers.length === 0) {
+    console.log('(no workers)');
+    return;
+  }
+  const lines = plan.workers.map(w => {
+    const lw = w.lightweight ? ' [lightweight]' : '';
+    const dep = w.dependsOn.length > 0 ? ` ⟵ ${w.dependsOn.join(',')}` : '';
+    return `${w.name}\t${w.state}${lw}${dep}`;
   });
-  console.log(out.join('\n') || '(no workers)');
+  console.log(lines.join('\n'));
+  console.log('');
+  console.log(`ready: ${plan.buckets.ready.join(', ') || '∅'}`);
+  console.log(`running: ${plan.buckets.running.join(', ') || '∅'}`);
+  console.log(`blocked: ${plan.buckets.blocked.join(', ') || '∅'}`);
+  console.log(`waiting: ${plan.buckets.waiting.join(', ') || '∅'}`);
+  console.log(`completed: ${plan.buckets.completed.join(', ') || '∅'}`);
+  if (plan.buckets.failed.length > 0) console.log(`failed: ${plan.buckets.failed.join(', ')}`);
+}
+
+function cmdPlan(session) {
+  if (!session) throw new Error('session name is required');
+  const file = refreshPlan(session);
+  console.log(relPosix(file));
+  console.log(JSON.stringify(readJson(file), null, 2));
+}
+
+function cmdValidate(session) {
+  if (!session) throw new Error('session name is required');
+  const errors = validateSession(session);
+  if (errors.length === 0) {
+    console.log(`✔ session '${slugify(session, 'session')}' artifacts conform to schemas/orchestration/*.schema.json`);
+    return;
+  }
+  console.error(`✖ ${errors.length} file(s) failed validation:`);
+  for (const e of errors) {
+    console.error(`  ${e.file}`);
+    for (const p of e.problems) console.error(`    - ${p}`);
+  }
+  process.exit(1);
 }
 
 function cmdList() {
@@ -187,6 +225,12 @@ function main() {
       case 'status':
         cmdStatus(positional[0]);
         break;
+      case 'plan':
+        cmdPlan(positional[0]);
+        break;
+      case 'validate':
+        cmdValidate(positional[0]);
+        break;
       case 'list':
         cmdList();
         break;