@kontextmind/kxm 0.7.121 → 0.7.123

package/plugins/kxm/dist/mcp-server.js

@@ -17313,7 +17313,7 @@ function sessionTokenFixHint(policy) {
 }
 
 // plugins/kxm/src/mcp-server.ts
-var VERSION = "0.7.121";
+var VERSION = "0.7.123";
 var CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 var inbox = /* @__PURE__ */ new Map();
 var notifiedInbox = /* @__PURE__ */ new Set();

package/plugins/kxm/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-plugin",
-  "version": "0.7.121",
+  "version": "0.7.123",
   "private": true,
   "type": "module",
   "engines": {

package/plugins/kxm/skills/kxm/SKILL.md

@@ -20,7 +20,7 @@ writers, or replace `.kxm/roster.yaml` trusted policy.
 | Delegate to or answer another agent | `kxm-peer` | `peer` (`peer await` is capped at 60 seconds) |
 | Work inside a durable workflow run, gates, signed callbacks | `kxm-workflow` | `workflow`, `gate` |
 | Role definitions, role hosts, model rosters | `kxm-definitions` | `role` |
-| Create, drive, inspect, or cancel a run, use a worktree lane, or land a branch | `kxm-runs` | `run`, `runs`, `lane`, `land` |
+| Create, drive, inspect, or cancel a run, use a worktree lane, land a branch, run the developer assignment loop, or build and serve the docs site | `kxm-runs` | `run`, `runs`, `lane`, `land`, `assign`, `docs` |
 | What we know or decided, recall, context footprint, Git memory | `kxm-context-memory` | `context`, `memory`, `explain` |
 | Turn a repeated practice into a governed skill | `kxm-skill-lifecycle` | `skills` |
 | What KXM learned, repeated asks, recorded route spend | `kxm-routing-improve` | `routing`, `improve` |

package/plugins/kxm/skills/kxm-runs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: kxm-runs
-description: Create, drive, and inspect local KXM runs, manage worktree lanes, and land a branch. kxm runs drive with --simulated executes a run model-free and settles it with a verified receipt. Use when asked to start a workflow run, check its status, read its receipt, cancel it, smoke-test a workflow, create a lane, or land the current branch.
+description: Create, drive, and inspect local KXM runs, manage worktree lanes, land a branch, and run the developer assignment loop. kxm runs drive with --simulated executes a run model-free and settles it with a verified receipt. Use when asked to start a workflow run, check its status, read its receipt, cancel it, smoke-test a workflow, create a lane, land the current branch, or call kxm assign (run, witness, plan-current, attribute, observe-cost, accept, change-report).
 ---
 
 # KXM runs
@@ -11,6 +11,11 @@ the Runtime supervisor. A created run stays `created` until
 an admitted model; `--simulated` is the model-free producer. Do not invent get,
 create, or logs verbs under `runs`.
 
+`kxm docs build` regenerates the docs site from the roadmap state by running
+`node plans/kxm-roadmap/update-dashboard.mjs` at the project root. `kxm docs
+serve` serves that site with `python3 ops/docs-site/serve.py` and passes
+`--port` through when it is set. Both require a KXM project.
+
 ## Commands
 
 | Command | Purpose | Options / arguments |
@@ -27,6 +32,15 @@ create, or logs verbs under `runs`.
 | `kxm lane drop <unit>` | Remove the worktree and the record. The branch is not deleted | `--force`, `--json` |
 | `kxm lane run <unit>` | Create the lane if needed, start a run from a brief, and drive it | `--brief <file>` (required), `--workflow <id>`, `--base <ref>`, `--wait`, `--timeout-ms <n>`, `--json` |
 | `kxm land` | Verify, regenerate docs, push, open or reuse a pull request, rebase, unblock, squash-merge, watch the release, and note a milestone | `--pr <n>`, `--stage <name>`, `--body-file <path>`, `--json`, `--dry-run` |
+| `kxm assign run` | Dispatch one assignment manifest. The runner performs every check | `--manifest <path>` |
+| `kxm assign witness` | Run the fixed witness for an existing record | `--record-dir <path>` |
+| `kxm assign plan-current` | Stamp or advance the current-plan pointer | `--task-dir <path>`, `--plan <path>`, `--sha256 <hex>`, `--base-commit <sha>`, `--expected-generation <n>` |
+| `kxm assign attribute` | Attach a private note. It is not proof | `--task-dir <path>`, `--record-dir <path>`, `--class <class>`, `--explanation-file <path>` |
+| `kxm assign observe-cost` | Import one cost-only observation | `--task-dir <path>`, `--input <path>` |
+| `kxm assign accept` | Bind a witnessed commit and two critic records | `--task-dir <path>`, `--commit <sha>`, `--record-dir <path>`, `--critic <path>` twice, optional `--observed-pr <id>`, `--observed-ci <id>` |
+| `kxm assign change-report` | Report attempts, rework, and spend | `--task-dir <path>` |
+| `kxm docs build` | Regenerate the docs site from roadmap state | `--dry-run`, `--json` |
+| `kxm docs serve` | Serve the built site on the tailnet address | `--port <port>`, `--dry-run`, `--json` |
 
 The run record and its events keep only the prompt's hash, but the full
 prompt text is kept in a local `run-events.db.run-prompts.json` file (mode
@@ -80,6 +94,7 @@ squash-merges. `release` waits for the tag and the npm publish. `milestone`
 reports `deep_review_required` when a phase flips to done or the body contains
 a `Milestone:` line, and does not run the review. `--dry-run` prints each
 stage's plan and does not mutate.
+`kxm assign` spawns `node scripts/assignment-run.mjs` from the project root and returns the child's exit code. Paths are passed through as given. `--dry-run` prints that argv and does not spawn. `--json` formats this command's own output and is not forwarded. The group does not load a working-directory `.env`. A project without `scripts/assignment-run.mjs` is refused with `assign_runner_missing`. Outside a KXM project the refusal is `project_required`. Witness, roster, and acceptance checks belong to the runner, documented in `docs/contributing/assignment-runner.md`.
 
 ## Refusals
 

package/plugins/kxm/src/cli/assign.ts

@@ -0,0 +1,144 @@
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { discoverKxmProjectRoot } from "../project-config.ts";
+import { CLI_RESULT_SCHEMA, print, type Runtime } from "./types.ts";
+
+export interface AssignSpawnOptions {
+  cwd: string;
+  stdio: "inherit";
+  env: NodeJS.ProcessEnv;
+}
+
+export interface AssignSpawnResult {
+  status: number | null;
+  error?: Error;
+}
+
+/** Test seam. Production leaves `spawn` unset and uses `spawnSync`. */
+export const kxmAssignCliSeams: {
+  spawn?: (command: string, args: readonly string[], options: AssignSpawnOptions) => AssignSpawnResult;
+} = {};
+
+export type AssignVerb =
+  | "run"
+  | "witness"
+  | "plan-current"
+  | "attribute"
+  | "observe-cost"
+  | "accept"
+  | "change-report";
+
+export interface AssignArgs {
+  manifest?: string;
+  recordDir?: string;
+  taskDir?: string;
+  plan?: string;
+  sha256?: string;
+  baseCommit?: string;
+  expectedGeneration?: string;
+  classification?: string;
+  explanationFile?: string;
+  input?: string;
+  commit?: string;
+  critics?: readonly string[];
+  observedPr?: string;
+  observedCi?: string;
+}
+
+const RUNNER_REL = "scripts/assignment-run.mjs";
+
+function refuse(runtime: Runtime, command: string, error: string, text: string): number {
+  print(runtime.io, runtime.json, { ok: false, command, error }, text);
+  return 1;
+}
+
+function flag(value: string | undefined): string {
+  if (value === undefined) throw new Error("assign invocation missing a parsed flag");
+  return value;
+}
+
+/** Argv after `node scripts/assignment-run.mjs`, in the recipe's flag order.
+ * The runner's usage text documents no `--json` flag. `accept` prints JSON
+ * and takes none, so the global `--json` flag stays on this command. */
+function runnerArgv(subcommand: AssignVerb, args: AssignArgs): string[] {
+  switch (subcommand) {
+    case "run":
+      return ["run", "--manifest", flag(args.manifest)];
+    case "witness":
+      return ["witness", "--record-dir", flag(args.recordDir)];
+    case "plan-current":
+      return [
+        "plan-current",
+        "--task-dir", flag(args.taskDir),
+        "--plan", flag(args.plan),
+        "--sha256", flag(args.sha256),
+        "--base-commit", flag(args.baseCommit),
+        "--expected-generation", flag(args.expectedGeneration),
+      ];
+    case "attribute":
+      return [
+        "attribute",
+        "--task-dir", flag(args.taskDir),
+        "--record-dir", flag(args.recordDir),
+        "--class", flag(args.classification),
+        "--explanation-file", flag(args.explanationFile),
+      ];
+    case "observe-cost":
+      return ["observe-cost", "--task-dir", flag(args.taskDir), "--input", flag(args.input)];
+    case "accept": {
+      const argv = [
+        "accept",
+        "--task-dir", flag(args.taskDir),
+        "--commit", flag(args.commit),
+        "--record-dir", flag(args.recordDir),
+      ];
+      for (const critic of args.critics ?? []) argv.push("--critic", critic);
+      if (args.observedPr !== undefined) argv.push("--observed-pr", args.observedPr);
+      if (args.observedCi !== undefined) argv.push("--observed-ci", args.observedCi);
+      return argv;
+    }
+    case "change-report":
+      return ["change-report", "--task-dir", flag(args.taskDir)];
+    default: {
+      const unreachable: never = subcommand;
+      throw new Error(`unknown assign verb ${String(unreachable)}`);
+    }
+  }
+}
+
+export async function cmdAssign(runtime: Runtime, subcommand: AssignVerb, args: AssignArgs): Promise<number> {
+  const command = `assign ${subcommand}`;
+  const root = discoverKxmProjectRoot(runtime.cwd);
+  if (!root) return refuse(runtime, command, "project_required", `${command} requires a KXM project (run kxm init first)`);
+  if (!existsSync(join(root, "scripts", "assignment-run.mjs"))) {
+    return refuse(runtime, command, "assign_runner_missing", `${command} requires scripts/assignment-run.mjs in the project root`);
+  }
+  const argv = ["node", RUNNER_REL, ...runnerArgv(subcommand, args)];
+  if (runtime.dryRun) {
+    // print() redacts every 64-hex string. plan-current passes a plan sha256
+    // through unchanged, so the dry-run argv is written directly.
+    const payload = { schema: CLI_RESULT_SCHEMA, ok: true, command, dryRun: true, argv };
+    runtime.io.stdout(runtime.json ? `${JSON.stringify(payload)}\n` : `${argv.join(" ")}\n`);
+    return 0;
+  }
+  // Never load a `.env` from the working directory. The justfile keeps
+  // `set dotenv-load` off for the same reason: a gitignored `.env` could set
+  // `NODE_OPTIONS`, and that value runs before the runner validates identity,
+  // tree, or roster. Pass the process environment through unchanged.
+  const spawn = kxmAssignCliSeams.spawn ?? ((commandName: string, commandArgs: readonly string[], options: AssignSpawnOptions): AssignSpawnResult => {
+    const result = spawnSync(commandName, commandArgs, {
+      cwd: options.cwd,
+      stdio: options.stdio,
+      env: options.env,
+      windowsHide: true,
+    });
+    return { status: result.status, ...(result.error ? { error: result.error } : {}) };
+  });
+  const result = spawn("node", argv.slice(1), { cwd: root, stdio: "inherit", env: runtime.env });
+  if (result.status === null) {
+    const detail = result.error?.message ?? "the assignment runner could not be started";
+    return refuse(runtime, command, "assign_spawn_failed", detail);
+  }
+  return result.status;
+}

package/plugins/kxm/src/cli/docs.ts

@@ -0,0 +1,78 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { discoverKxmProjectRoot } from "../project-config.ts";
+import { print, type Runtime } from "./types.ts";
+
+const GENERATOR = "plans/kxm-roadmap/update-dashboard.mjs";
+const SERVER = "ops/docs-site/serve.py";
+
+function requireProject(runtime: Runtime, command: string): string | number {
+  const root = discoverKxmProjectRoot(runtime.cwd);
+  if (!root) {
+    print(
+      runtime.io,
+      runtime.json,
+      { ok: false, command, error: "project_required" },
+      `kxm ${command} requires a KXM project (run kxm init first)`,
+    );
+    return 1;
+  }
+  return root;
+}
+
+function requireFile(runtime: Runtime, command: string, root: string, relative: string, error: string): string | number {
+  const file = join(root, relative);
+  if (existsSync(file)) return file;
+  print(
+    runtime.io,
+    runtime.json,
+    { ok: false, command, error, path: relative },
+    `kxm ${command} requires ${relative}`,
+  );
+  return 1;
+}
+
+function printCommand(runtime: Runtime, command: string, line: string): number {
+  print(
+    runtime.io,
+    runtime.json,
+    { ok: true, command, dryRun: true, detail: line },
+    line,
+  );
+  return 0;
+}
+
+function runInherited(command: string, args: readonly string[], cwd: string): Promise<number> {
+  return new Promise((resolveExit) => {
+    const child = spawn(command, [...args], { cwd, stdio: "inherit" });
+    child.once("error", () => resolveExit(1));
+    child.once("exit", (code) => resolveExit(code ?? 1));
+  });
+}
+
+/** Regenerate the docs site from the roadmap state. */
+export async function cmdDocsBuild(runtime: Runtime): Promise<number> {
+  const command = "docs build";
+  const root = requireProject(runtime, command);
+  if (typeof root === "number") return root;
+  const file = requireFile(runtime, command, root, GENERATOR, "docs_generator_missing");
+  if (typeof file === "number") return file;
+  const line = `node ${GENERATOR}`;
+  if (runtime.dryRun) return printCommand(runtime, command, line);
+  return runInherited(process.execPath, [file], root);
+}
+
+/** Serve the built site. `--port` is passed through when set. */
+export async function cmdDocsServe(runtime: Runtime, options: { port?: string } = {}): Promise<number> {
+  const command = "docs serve";
+  const root = requireProject(runtime, command);
+  if (typeof root === "number") return root;
+  const file = requireFile(runtime, command, root, SERVER, "docs_server_missing");
+  if (typeof file === "number") return file;
+  const args = [file];
+  if (options.port !== undefined && options.port !== "") args.push("--port", options.port);
+  const line = ["python3", SERVER, ...args.slice(1)].join(" ");
+  if (runtime.dryRun) return printCommand(runtime, command, line);
+  return runInherited("python3", args, root);
+}

package/plugins/kxm/src/cli.ts

@@ -120,6 +120,7 @@ cmdBackup,
 } from "./cli/project.ts";
 
 import { cmdPluginInstall } from "./cli/plugins.ts";
+import { cmdDocsBuild, cmdDocsServe } from "./cli/docs.ts";
 
 import {
   applyLane,
@@ -132,6 +133,7 @@ import {
 } from "./cli/lanes.ts";
 
 import { cmdLand } from "./cli/land.ts";
+import { cmdAssign } from "./cli/assign.ts";
 
 import {
   cmdStatus,
@@ -200,6 +202,8 @@ const DRY_RUN_COMMANDS: ReadonlySet<string> = new Set([
   "init", "backup", "restore", "run", "explain", "suggest", "update", "dash", "completion", "completion install",
   "lane create", "lane list", "lane status", "lane drop", "lane run",
   "land",
+  "assign run", "assign witness", "assign plan-current", "assign attribute",
+  "assign observe-cost", "assign accept", "assign change-report",
   "plugin install", "plugin",
   "runs status", "runs drive", "runs receipt", "runs cancel", "runs list",
   "tenant status", "models inventory-refresh", "harness list", "auth token",
@@ -224,6 +228,7 @@ const DRY_RUN_COMMANDS: ReadonlySet<string> = new Set([
   "goal create", "goal list",
   "task create", "task list", "task get", "task run", "task sync",
   "studio layout", "studio serve",
+  "docs build", "docs serve",
 ]);
 
 class DryRunRefused extends Error {
@@ -499,6 +504,74 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
         ...(options.bodyFile !== undefined ? { bodyFile: options.bodyFile } : {}),
       });
     });
+  const assignCmd = addGlobalOptions(program.command("assign").description("Run this repository's developer assignment runner"));
+  assignCmd.helpCommand("help", "Show assign help");
+  addGlobalOptions(assignCmd.command("run").description("Dispatch a bound assignment manifest"))
+    .requiredOption("--manifest <path>", "Absolute path to the assignment manifest")
+    .action(async function assignRunAction(this: Command, options: { manifest: string }) {
+      result.code = await cmdAssign(runtimeFrom(ctx, this), "run", { manifest: options.manifest });
+    });
+  addGlobalOptions(assignCmd.command("witness").description("Run the fixed verification witness for an existing assignment"))
+    .requiredOption("--record-dir <path>", "Absolute path to the assignment record directory")
+    .action(async function assignWitnessAction(this: Command, options: { recordDir: string }) {
+      result.code = await cmdAssign(runtimeFrom(ctx, this), "witness", { recordDir: options.recordDir });
+    });
+  addGlobalOptions(assignCmd.command("plan-current").description("Stamp or advance the current-plan pointer"))
+    .requiredOption("--task-dir <path>", "Absolute path to the task directory")
+    .requiredOption("--plan <path>", "Absolute path to the plan file")
+    .requiredOption("--sha256 <hex>", "SHA-256 of the plan file")
+    .requiredOption("--base-commit <sha>", "Base commit the pointer records")
+    .requiredOption("--expected-generation <n>", "Generation the pointer must currently have")
+    .action(async function assignPlanCurrentAction(this: Command, options: { taskDir: string; plan: string; sha256: string; baseCommit: string; expectedGeneration: string }) {
+      result.code = await cmdAssign(runtimeFrom(ctx, this), "plan-current", {
+        taskDir: options.taskDir,
+        plan: options.plan,
+        sha256: options.sha256,
+        baseCommit: options.baseCommit,
+        expectedGeneration: options.expectedGeneration,
+      });
+    });
+  addGlobalOptions(assignCmd.command("attribute").description("Attach a private attribution note"))
+    .requiredOption("--task-dir <path>", "Absolute path to the task directory")
+    .requiredOption("--record-dir <path>", "Absolute path to the assignment record directory")
+    .requiredOption("--class <class>", "orchestration, model, environment, or unclassified")
+    .requiredOption("--explanation-file <path>", "Absolute path to the note file")
+    .action(async function assignAttributeAction(this: Command, options: { taskDir: string; recordDir: string; class: string; explanationFile: string }) {
+      result.code = await cmdAssign(runtimeFrom(ctx, this), "attribute", {
+        taskDir: options.taskDir,
+        recordDir: options.recordDir,
+        classification: options.class,
+        explanationFile: options.explanationFile,
+      });
+    });
+  addGlobalOptions(assignCmd.command("observe-cost").description("Import one historical cost observation as cost-only"))
+    .requiredOption("--task-dir <path>", "Absolute path to the task directory")
+    .requiredOption("--input <path>", "Absolute path to the observation file")
+    .action(async function assignObserveCostAction(this: Command, options: { taskDir: string; input: string }) {
+      result.code = await cmdAssign(runtimeFrom(ctx, this), "observe-cost", { taskDir: options.taskDir, input: options.input });
+    });
+  addGlobalOptions(assignCmd.command("accept").description("Bind an exact witnessed commit and two critic PASS records"))
+    .requiredOption("--task-dir <path>", "Absolute path to the task directory")
+    .requiredOption("--commit <sha>", "Commit to accept")
+    .requiredOption("--record-dir <path>", "Absolute path to the writer record directory")
+    .requiredOption("--critic <path>", "Absolute path to a critic record directory; pass twice", (value: string, previous: string[]) => previous.concat(value), [] as string[])
+    .option("--observed-pr <id>", "Observed pull request id")
+    .option("--observed-ci <id>", "Observed CI run id")
+    .action(async function assignAcceptAction(this: Command, options: { taskDir: string; commit: string; recordDir: string; critic: string[]; observedPr?: string; observedCi?: string }) {
+      result.code = await cmdAssign(runtimeFrom(ctx, this), "accept", {
+        taskDir: options.taskDir,
+        commit: options.commit,
+        recordDir: options.recordDir,
+        critics: options.critic,
+        ...(options.observedPr !== undefined ? { observedPr: options.observedPr } : {}),
+        ...(options.observedCi !== undefined ? { observedCi: options.observedCi } : {}),
+      });
+    });
+  addGlobalOptions(assignCmd.command("change-report").description("Report attempts, rework, costs, and retained verification history"))
+    .requiredOption("--task-dir <path>", "Absolute path to the task directory")
+    .action(async function assignChangeReportAction(this: Command, options: { taskDir: string }) {
+      result.code = await cmdAssign(runtimeFrom(ctx, this), "change-report", { taskDir: options.taskDir });
+    });
 
   addGlobalOptions(program.command("run").description("Create a KXM run without executing steps; follow its prerequisites, then kxm runs drive <runId> --wait")
     .argument("[workflow]", "Workflow id to run")
@@ -554,6 +627,18 @@ function createProgram(ctx: CliContext, result: { code: number }): Command {
       result.code = await cmdKxmRunList(runtimeFrom(ctx, this));
     });
 
+  const docsCmd = addGlobalOptions(program.command("docs").description("Build and serve the tailnet docs site"));
+  docsCmd.helpCommand("help", "Show docs help");
+  addGlobalOptions(docsCmd.command("build").description("Regenerate the docs site from the roadmap state"))
+    .action(async function docsBuildAction(this: Command) {
+      result.code = await cmdDocsBuild(runtimeFrom(ctx, this));
+    });
+  addGlobalOptions(docsCmd.command("serve").description("Serve the built docs site on this machine's tailnet address"))
+    .option("--port <port>", "Port passed through to the docs server")
+    .action(async function docsServeAction(this: Command, options: { port?: string }) {
+      result.code = await cmdDocsServe(runtimeFrom(ctx, this), options);
+    });
+
   const tenantCmd = addGlobalOptions(program.command("tenant").description("Composed tenant reads for machine clients (portal)"));
   tenantCmd.helpCommand("help", "Show tenant help");
   addGlobalOptions(tenantCmd.command("status").description("Read hub metadata and authoritative Runtime run state as one labeled view"))

package/plugins/kxm/src/mcp-server.ts

@@ -11,7 +11,7 @@ import { deliverInboxNotification } from "./inbox.ts";
 import type { HubEvent, MessageRecord } from "./protocol.ts";
 import { sessionTokenFixHint } from "./session-token-hint.ts";
 
-const VERSION = "0.7.121";
+const VERSION = "0.7.123";
 const CONFIGURE_PLUGIN = "/plugin configure kxm@kxm";
 const inbox = new Map<string, MessageRecord>();
 const notifiedInbox = new Set<string>();

package/schemas/roadmap-state.schema.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.kxm.dev/roadmap-state.schema.json",
+  "title": "KXM roadmap state",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "updated", "goal", "phases"],
+  "properties": {
+    "schema": { "const": "kxm.roadmap.v1" },
+    "updated": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "goal": { "type": "string", "minLength": 1 },
+    "constraints": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "contacts": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/contact" }
+    },
+    "contacts_comment": { "type": "string" },
+    "history": {
+      "type": "array",
+      "description": "Oldest first. The generator keeps the newest 12 lines and drops the older ones (history_over_cap). That prune is not a schema refusal.",
+      "items": { "$ref": "#/$defs/historyLine" }
+    },
+    "architecture": { "$ref": "#/$defs/architecture" },
+    "improvements": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "phases": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/phase" }
+    }
+  },
+  "$defs": {
+    "date": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    "historyLine": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["date", "line"],
+      "properties": {
+        "date": { "$ref": "#/$defs/date" },
+        "line": { "type": "string", "minLength": 1, "maxLength": 240 }
+      }
+    },
+    "contact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["role", "confirmed"],
+      "properties": {
+        "role": { "type": "string", "minLength": 1 },
+        "name": { "type": "string", "minLength": 1 },
+        "confirmed": { "$ref": "#/$defs/date" }
+      }
+    },
+    "architecture": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "verified": {
+          "anyOf": [
+            { "type": "null" },
+            { "$ref": "#/$defs/date" }
+          ]
+        },
+        "docs": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "drift": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["claim", "page", "status"],
+            "properties": {
+              "claim": { "type": "string" },
+              "page": { "type": "string" },
+              "status": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "phase": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "slug", "title", "goal", "source", "tasks"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "slug": { "type": "string", "minLength": 1 },
+        "title": { "type": "string", "minLength": 1 },
+        "goal": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "minLength": 1 },
+        "priority": { "const": "later" },
+        "horizon": {
+          "description": "Derived by the generator from phase order and priority (next, soon, or later). Not hand-set. A stored value is ignored.",
+          "enum": ["next", "soon", "later"]
+        },
+        "blockers": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "questions": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "tasks": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/task" }
+        }
+      }
+    },
+    "task": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title", "status"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "title": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["open", "done"] },
+        "evidence": { "type": "string" },
+        "planSection": { "type": "string", "minLength": 1 },
+        "doneCriterion": { "type": "string", "minLength": 1 },
+        "evidenceNeeded": { "type": "string", "minLength": 1 },
+        "template": {
+          "enum": [
+            "feature",
+            "research",
+            "bug-fix",
+            "architecture",
+            "adr",
+            "test-plan",
+            "test-report",
+            "review",
+            "handoff",
+            "runbook",
+            "postmortem",
+            "none"
+          ]
+        },
+        "detail": { "enum": ["brief", "scoped", "ready"] }
+      }
+    }
+  }
+}