@esneiderbravo/speclaw 1.0.1 → 2.0.1

package/dist/cli/index.js

@@ -2,7 +2,7 @@
 import { parseFlags } from "./lib/args.js";
 import { ui, header } from "./lib/ui.js";
 import { maybeNotifyUpdate } from "./lib/update-check.js";
-const HELP = `speclaw — spec-driven, agent-ready projects (foundation + Compass + Lawbook)
+const HELP = `speclaw — spec-driven, agent-ready projects (Foundation + Compass + Lawbook + Cortex)
 
 Usage: speclaw <command> [options]
 
@@ -12,8 +12,8 @@ Install globally so the command is always available:
 Setup
   init                     Interactive setup: pick agents, scaffold, index, get the prompt
                            (--minimal omits setup/lifecycle MCP tools)
-  update                   Upgrade speclaw and apply only what's new (no re-init)
-                           (--minimal persists minimal exposure; omit to keep prior)
+  update                   Apply project migrations (advisory if a newer binary exists)
+                           (--check reports version only; --minimal persists minimal exposure)
   agent list               Show which agents are configured
   agent add <id>           Configure another agent later (symlinks + MCP)
 
@@ -31,6 +31,9 @@ Compass (code intelligence — the same surface agents use via MCP)
   trace <from> <to>        A call path between two nodes
   visualize [node]         Interactive HTML graph → .speclaw/graph.html
 
+Cortex (One brain. Many agents. — multi-agent loop)
+  cortex <op>              status|start|advance|rework|brief — drive harness.json (--change)
+
 Lawbook (spec-driven workflow)
   quick <name>             Scaffold a level-0 change (record.md + reports)
   lawbook init             Create the lawbook/ workspace
@@ -41,6 +44,7 @@ Lawbook (spec-driven workflow)
   lawbook validate <c>     Validate a change's artifacts
   lawbook sync <c>         Promote delta specs to canonical
   lawbook archive <c>      Finalize and archive a change
+  lawbook harness <op>     Deprecated alias for \`speclaw cortex\` (compat)
 
 Other
   doctor                   Verify the installation (--json, --offline, --strict)
@@ -84,6 +88,7 @@ const HEADER_COMMANDS = new Set([
     "index",
     "watch",
     "lawbook",
+    "cortex",
     "quick",
 ]);
 /**
@@ -116,6 +121,8 @@ function maybeHeader(cmd, flags) {
         return;
     if (cmd === "lawbook" && flags.json && flags._[0] === "draft")
         return;
+    if (cmd === "cortex" && flags.json)
+        return;
     header();
 }
 /** Run the handler for a single command. Returns when the command completes. */
@@ -160,6 +167,8 @@ async function dispatch(cmd, flags) {
             return (await import("./commands/visualize.js")).runVisualize(flags);
         case "quick":
             return (await import("./commands/quick.js")).runQuick(flags);
+        case "cortex":
+            return (await import("./commands/cortex.js")).runCortex(flags);
         case "lawbook":
             return (await import("./commands/lawbook.js")).runSpec(flags);
         case "doctor":

package/dist/cli/lib/update-check.js

@@ -102,15 +102,16 @@ export function npmPackageUrl(name) {
 /**
  * Build the two-line "update available" notice. The latest version is rendered
  * as a clickable link to the package's npm page, so a capable terminal lets the
- * user open the release with a single click while `speclaw update` remains the
- * command that performs the upgrade.
+ * user open the release with a single click. Project migrations stay
+ * `speclaw update`; the binary is upgraded separately (prefer npx).
  *
  * @param current - The installed version.
  * @param latest - The newest published version.
  * @returns The formatted, styled notice (no leading/trailing blank lines).
  */
 export function upgradeNotice(current, latest) {
-    const latestLink = c.cyan(link(latest, npmPackageUrl(pkgName())));
+    const name = pkgName();
+    const latestLink = c.cyan(link(latest, npmPackageUrl(name)));
     return ("  " +
         c.amber("⬆ speclaw ") +
         c.muted(current + " → ") +
@@ -118,9 +119,11 @@ export function upgradeNotice(current, latest) {
         c.muted(" available") +
         "\n" +
         "  " +
-        c.muted("run ") +
+        c.muted("prefer ") +
+        c.cyan(`npx ${name}@latest update`) +
+        c.muted(" — or ") +
         c.cyan("speclaw update") +
-        c.muted(" — upgrades and applies only what's new"));
+        c.muted(" to migrate this project"));
 }
 /**
  * Print the "update available" notice to stderr when a newer version exists.

package/dist/modules/cortex/brief.js

@@ -0,0 +1,75 @@
+/**
+ * Stage → role brief for Cortex coordinators.
+ *
+ * // Covers: req~cortex-module~1
+ */
+/**
+ * Map a harness stage to the role the coordinator should dispatch.
+ *
+ * @param stage - Current harness stage, or null when not started.
+ */
+export function briefForStage(stage) {
+    switch (stage) {
+        case "exploring":
+            return {
+                role: "explorer",
+                agentPath: "ai-specs/agents/explorer.md",
+                skillHints: ["explore"],
+                nextOps: ["advance"],
+            };
+        case "planning":
+            return {
+                role: "planner",
+                agentPath: "ai-specs/agents/planner.md",
+                skillHints: ["draft"],
+                nextOps: ["advance", "pauseForQuestions"],
+            };
+        case "questions":
+            return {
+                role: "planner",
+                agentPath: "ai-specs/agents/planner.md",
+                skillHints: ["draft"],
+                nextOps: ["advance"],
+            };
+        case "implementing":
+            return {
+                role: "implementer",
+                agentPath: "ai-specs/agents/implementer.md",
+                skillHints: ["build"],
+                nextOps: ["advance"],
+            };
+        case "reviewing":
+            return {
+                role: "reviewer",
+                agentPath: "ai-specs/agents/reviewer.md",
+                skillHints: [],
+                nextOps: ["advance", "rework"],
+            };
+        case "testing":
+            return {
+                role: "tester",
+                agentPath: "ai-specs/agents/tester.md",
+                skillHints: ["test"],
+                nextOps: ["advance", "rework"],
+            };
+        case "archiving":
+            return {
+                role: "archiver",
+                agentPath: "ai-specs/agents/archiver.md",
+                skillHints: ["sync", "archive"],
+                nextOps: ["advance"],
+            };
+        case "done":
+        case null:
+            return {
+                role: null,
+                agentPath: null,
+                skillHints: [],
+                nextOps: [],
+            };
+        default: {
+            const _exhaustive = stage;
+            throw new Error(`unknown stage ${String(_exhaustive)}`);
+        }
+    }
+}

package/dist/modules/cortex/harness.js

@@ -0,0 +1,270 @@
+/**
+ * Deterministic multi-agent harness state for a lawbook change.
+ *
+ * Speclaw does not spawn LLMs. This module only persists stage transitions;
+ * the host agent (Cursor/Claude/…) follows the Cortex skill and calls these
+ * ops via `speclaw cortex` or the `cortex` MCP tool.
+ *
+ * Cortex must not import from the lawbook module (no cycles). Ceremony level
+ * is read locally from `change.json` `confirmedLevel` (default 3).
+ */
+import fs from "node:fs";
+import path from "node:path";
+export const HARNESS_STAGES = [
+    "exploring",
+    "planning",
+    "questions",
+    "implementing",
+    "reviewing",
+    "testing",
+    "archiving",
+    "done",
+];
+export const harnessOps = ["status", "start", "advance", "rework"];
+const DEFAULT_MAX_REWORK = 3;
+function specRoot(projectPath) {
+    return path.join(projectPath, "lawbook");
+}
+function changeDir(projectPath, change) {
+    return path.join(specRoot(projectPath), "changes", change);
+}
+function harnessPath(projectPath, change) {
+    return path.join(changeDir(projectPath, change), "harness.json");
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+function requireChangeDir(projectPath, change) {
+    const dir = changeDir(projectPath, change);
+    if (!fs.existsSync(dir)) {
+        throw new Error(`change "${change}" not found under lawbook/changes/`);
+    }
+    return dir;
+}
+/**
+ * Read confirmed ceremony level from change.json without importing lawbook.
+ * Missing file or field → 3.
+ */
+function readConfirmedLevel(projectPath, change) {
+    const p = path.join(changeDir(projectPath, change), "change.json");
+    if (!fs.existsSync(p))
+        return 3;
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, "utf8"));
+        const n = raw.confirmedLevel;
+        if (n === 0 || n === 1 || n === 2 || n === 3)
+            return n;
+    }
+    catch {
+        /* default */
+    }
+    return 3;
+}
+/** Read harness.json or return null when absent. */
+export function readHarness(projectPath, change) {
+    requireChangeDir(projectPath, change);
+    const p = harnessPath(projectPath, change);
+    if (!fs.existsSync(p))
+        return null;
+    return JSON.parse(fs.readFileSync(p, "utf8"));
+}
+function writeHarness(projectPath, change, state) {
+    const p = harnessPath(projectPath, change);
+    fs.writeFileSync(p, JSON.stringify(state, null, 2) + "\n");
+}
+function nextAfterExplore(level) {
+    return level === 0 ? "implementing" : "planning";
+}
+function nextAfterImplement(level) {
+    return level === 0 ? "testing" : "reviewing";
+}
+/**
+ * Legal one-step advances (not rework). Rework is handled separately.
+ */
+function allowedAdvance(from, level, verdict) {
+    switch (from) {
+        case "exploring":
+            return nextAfterExplore(level);
+        case "planning":
+            return "implementing";
+        case "questions":
+            return "planning";
+        case "implementing":
+            return nextAfterImplement(level);
+        case "reviewing":
+            if (verdict === "FAIL") {
+                throw new Error(`harness advance from reviewing with FAIL requires op "rework" (not advance)`);
+            }
+            if (verdict !== "PASS") {
+                throw new Error(`harness advance from reviewing requires verdict PASS or FAIL`);
+            }
+            return "testing";
+        case "testing":
+            if (verdict === "FAIL") {
+                throw new Error(`harness advance from testing with FAIL requires op "rework"`);
+            }
+            if (verdict !== "PASS") {
+                throw new Error(`harness advance from testing requires verdict PASS or FAIL`);
+            }
+            return "archiving";
+        case "archiving":
+            return "done";
+        case "done":
+            throw new Error(`harness already done — no further advance`);
+        default: {
+            const _exhaustive = from;
+            throw new Error(`unknown stage ${String(_exhaustive)}`);
+        }
+    }
+}
+/**
+ * Dispatch a harness op for a change.
+ *
+ * // Covers: req~harness-state~1
+ */
+export function handleHarness(args) {
+    const { projectPath, change, harnessOp } = args;
+    requireChangeDir(projectPath, change);
+    if (harnessOp === "status") {
+        return { state: readHarness(projectPath, change) };
+    }
+    if (harnessOp === "start") {
+        const existing = readHarness(projectPath, change);
+        if (existing && existing.stage !== "done") {
+            throw new Error(`harness already started for "${change}" (stage=${existing.stage}); use status/advance/rework`);
+        }
+        const level = readConfirmedLevel(projectPath, change);
+        const state = {
+            version: 1,
+            change,
+            stage: "exploring",
+            level,
+            iteration: 0,
+            maxRework: DEFAULT_MAX_REWORK,
+            verdicts: { review: null, test: null },
+            openQuestions: [],
+            history: [
+                {
+                    at: nowIso(),
+                    from: "exploring",
+                    to: "exploring",
+                    op: "start",
+                    note: args.note,
+                },
+            ],
+        };
+        writeHarness(projectPath, change, state);
+        return state;
+    }
+    const current = readHarness(projectPath, change);
+    if (!current) {
+        throw new Error(`no harness.json for "${change}" — run cortex start first`);
+    }
+    if (harnessOp === "advance") {
+        // Planner may pause for questions instead of advancing to implement.
+        if (current.stage === "planning" && args.pauseForQuestions) {
+            const questions = args.openQuestions ?? [];
+            if (questions.length === 0) {
+                throw new Error(`pauseForQuestions requires at least one openQuestions entry`);
+            }
+            const next = {
+                ...current,
+                stage: "questions",
+                openQuestions: questions,
+                history: [
+                    ...current.history,
+                    {
+                        at: nowIso(),
+                        from: "planning",
+                        to: "questions",
+                        op: "advance",
+                        note: args.note,
+                    },
+                ],
+            };
+            writeHarness(projectPath, change, next);
+            return next;
+        }
+        const to = allowedAdvance(current.stage, current.level, args.verdict ?? undefined);
+        const verdicts = { ...current.verdicts };
+        if (current.stage === "reviewing" && args.verdict)
+            verdicts.review = args.verdict;
+        if (current.stage === "testing" && args.verdict)
+            verdicts.test = args.verdict;
+        const next = {
+            ...current,
+            stage: to,
+            verdicts,
+            openQuestions: current.stage === "questions" ? [] : current.openQuestions,
+            history: [
+                ...current.history,
+                {
+                    at: nowIso(),
+                    from: current.stage,
+                    to,
+                    op: "advance",
+                    note: args.note,
+                },
+            ],
+        };
+        writeHarness(projectPath, change, next);
+        return next;
+    }
+    if (harnessOp === "rework") {
+        if (current.stage !== "reviewing" && current.stage !== "testing") {
+            throw new Error(`rework only allowed from reviewing or testing (now ${current.stage})`);
+        }
+        if (args.verdict !== "FAIL") {
+            throw new Error(`rework requires verdict FAIL`);
+        }
+        if (current.iteration >= current.maxRework) {
+            throw new Error(`max rework (${current.maxRework}) reached — coordinator must ask the human before continuing`);
+        }
+        const verdicts = { ...current.verdicts };
+        if (current.stage === "reviewing")
+            verdicts.review = "FAIL";
+        if (current.stage === "testing")
+            verdicts.test = "FAIL";
+        const next = {
+            ...current,
+            stage: "implementing",
+            iteration: current.iteration + 1,
+            verdicts,
+            history: [
+                ...current.history,
+                {
+                    at: nowIso(),
+                    from: current.stage,
+                    to: "implementing",
+                    op: "rework",
+                    note: args.note,
+                },
+            ],
+        };
+        writeHarness(projectPath, change, next);
+        return next;
+    }
+    throw new Error(`unknown harnessOp '${String(harnessOp)}'`);
+}
+/**
+ * Archive blockers derived from harness verdicts.
+ *
+ * // Covers: req~harness-archive-gate~1
+ */
+export function harnessArchiveBlockers(projectPath, change) {
+    const state = readHarness(projectPath, change);
+    if (!state) {
+        return [`missing harness.json — run \`speclaw cortex start --change ${change}\``];
+    }
+    const blockers = [];
+    if (state.verdicts.test !== "PASS") {
+        blockers.push(`harness test verdict is not PASS (got ${String(state.verdicts.test)})`);
+    }
+    if (state.level >= 1 && state.verdicts.review !== "PASS") {
+        blockers.push(`harness review verdict is not PASS (got ${String(state.verdicts.review)})`);
+    }
+    if (state.stage !== "archiving" && state.stage !== "done") {
+        blockers.push(`harness stage is ${state.stage} — advance to archiving before archive`);
+    }
+    return blockers;
+}

package/dist/modules/cortex/register.js

@@ -0,0 +1,49 @@
+/**
+ * Cortex MCP registration — One brain. Many agents.
+ *
+ * // Covers: req~cortex-module~1
+ */
+import { z } from "zod";
+import { defineTool, text } from "../../shared/mcp.js";
+import { shouldExpose } from "../../shared/exposure.js";
+import { handleHarness, harnessOps, readHarness, } from "./harness.js";
+import { briefForStage } from "./brief.js";
+export const cortexActions = [...harnessOps, "brief"];
+/**
+ * Register the canonical `cortex` MCP tool.
+ *
+ * @param server - MCP server instance.
+ * @param opts - Exposure profile.
+ */
+export function registerCortex(server, opts = {}) {
+    const minimal = Boolean(opts.minimal);
+    const add = (name, description, inputSchema, handler) => {
+        if (!shouldExpose(name, minimal))
+            return;
+        defineTool(server, { name, description, inputSchema, handler });
+    };
+    add("cortex", "Cortex multi-agent loop: status, start, advance, rework, brief for a change.", {
+        projectPath: z.string(),
+        change: z.string(),
+        action: z.enum(cortexActions),
+        note: z.string().optional(),
+        verdict: z.enum(["PASS", "FAIL"]).optional(),
+        openQuestions: z.array(z.string()).optional(),
+        pauseForQuestions: z.boolean().optional(),
+    }, async ({ projectPath, change, action, note, verdict, openQuestions, pauseForQuestions }) => {
+        if (action === "brief") {
+            const state = readHarness(projectPath, change);
+            const brief = briefForStage(state?.stage ?? null);
+            return text(JSON.stringify({ state, ...brief }, null, 2));
+        }
+        return text(handleHarness({
+            projectPath,
+            change,
+            harnessOp: action,
+            note,
+            verdict: verdict ?? null,
+            openQuestions,
+            pauseForQuestions,
+        }));
+    });
+}

package/dist/modules/foundation/assets/AGENTS.template.md

@@ -22,23 +22,30 @@ Claude-specific notes: [`CLAUDE.md`](CLAUDE.md). The law: [`LAWS.md`](LAWS.md).
    after Compass returns nothing useful, the graph is missing (`compass_index`
    first), or the target isn't indexed code (stylesheets, config, logs). Cheat
    sheet: [`docs/compass.md`](docs/compass.md).
-3. **Follow the lawbook workflow** for every non-trivial change; archive
-   within the same PR. Rules:
+3. **Follow Cortex** (*One brain. Many agents.*) for every non-trivial change;
+   archive within the same PR. The primary agent is the **coordinator**
+   (`cortex` skill / `/lawbook/cortex`) — it MUST NOT implement
+   product code itself. It dispatches explorer → planner → implementer →
+   reviewer → tester → archiver (or adopts each role while obeying that
+   role's permission profile). Drive state with the `cortex` MCP tool or
+   `speclaw cortex`. Rules:
    [`docs/standards/lawbook.md`](docs/standards/lawbook.md).
 4. **Run the quality gates yourself** before declaring anything done — see
-   [`docs/standards/testing-standards.md`](docs/standards/testing-standards.md):
+   [`docs/standards/testing-standards.md`](docs/standards/testing-standards.md)
+   (owned by the **tester** role under Cortex):
    - Tests: `{{test_commands}}`
    - Lint / type-check: `{{lint_commands}}`
 5. **Respect the conventions** — branches `{{branch_pattern}}`, commits
    {{commit_style}}, code that reads like its neighbors. See
    [`docs/standards/base-standards.md`](docs/standards/base-standards.md) and
    [`docs/standards/conventions.md`](docs/standards/conventions.md).
-6. **Use the skills.** `ai-specs/` is the canonical home for skills, commands,
-   and subagents, mirrored to each IDE directory via symlinks.
+6. **Use the skills and role agents.** `ai-specs/` is the canonical home for
+   skills, commands, rules, and agents, mirrored to each IDE directory via
+   symlinks.
 7. **Ask before irreversible or outward-facing actions** — destructive commands;
    writing to a real data store (DB rows or files with real user data, including
    for tests — verify against an isolated/throwaway store); publishing
-   reviews/tickets/comments.
+   reviews/tickets/comments. Planner questions always go to the human.
 
 ## The standards (the law, in detail)
 

package/dist/modules/foundation/assets/CLAUDE.template.md

@@ -48,21 +48,24 @@ target is not indexed code — stylesheets, JSON/config, markdown, logs,
 generated files, lockfiles. Never skip Compass because grep "feels faster."
 See [`docs/compass.md`](docs/compass.md).
 
-## Rule 2 — Spec-driven, always
+## Rule 2 — Spec-driven Cortex loop, always
 
-No non-trivial change lands without a spec change (propose → implement →
-verify → archive). The rules are in
+No non-trivial change lands without a lawbook change (propose → implement →
+verify → archive) run through **Cortex** (*One brain. Many agents.*). You are the
+**coordinator** unless you were spawned as a role agent: use the `cortex`
+skill / `/lawbook/cortex` and the `cortex` MCP tool; do **not** implement product code yourself.
+Role agents live in `ai-specs/agents/`. The rules are in
 [`docs/standards/lawbook.md`](docs/standards/lawbook.md);
-the workflow skills live in `ai-specs/skills/` and the `/lawbook` commands wrap
-them. A change is not done until it is archived — archiving belongs in the PR.
+workflow skills live in `ai-specs/skills/` and `/lawbook` commands wrap them.
+A change is not done until it is archived — archiving belongs in the PR.
 
 ## Rule 3 — Quality gates are non-negotiable
 
 - Tests: `{{test_commands}}`
 - Lint / type-check: `{{lint_commands}}`
 
-Run them yourself and report real output. Never claim success you did not
-observe. Full rules:
+The **tester** role runs them and reports real output. Never claim success you
+did not observe. Full rules:
 [`docs/standards/testing-standards.md`](docs/standards/testing-standards.md).
 
 ## Rule 4 — Conventions
@@ -72,11 +75,11 @@ its neighbors, comments that carry constraints (never ticket IDs). Full rules:
 [`docs/standards/base-standards.md`](docs/standards/base-standards.md) and
 [`docs/standards/conventions.md`](docs/standards/conventions.md).
 
-## Rule 5 — Skills are law-adjacent
+## Rule 5 — Skills and role agents are law-adjacent
 
-Skills, commands, and subagents live in `ai-specs/` (symlinked into
-`.claude/`, `.cursor/`, `.codex/`, `.agents/`). When a skill matches the
-task, use it — do not improvise a parallel process.
+Skills, commands, rules, and agents live in `ai-specs/` (symlinked into
+`.claude/`, `.cursor/`, `.codex/`, `.agents/`). When a skill or role matches
+the task, use it — do not improvise a parallel process.
 
 ## Rule 6 — Stop conditions
 
@@ -85,3 +88,4 @@ schema drops), writing to a real data store (DB rows or files holding real user
 data — including to set up or tear down test data; verification runs against an
 isolated/throwaway store instead), publishing anything outward-facing (PR
 reviews, tickets, comments), or any action that contradicts a standard.
+Planner clarifying questions always go to the human via the coordinator.

package/dist/modules/foundation/assets/docs/standards/lawbook.template.md

@@ -6,38 +6,35 @@ mechanical steps are speclaw MCP tools).
 
 ## The loop
 
-No non-trivial change lands without a spec change:
-
-1. **explore** — think an idea through before committing (writes nothing).
-2. **draft** — create `lawbook/changes/<name>/`: `proposal.md`, delta specs under
-   `specs/<capability>/spec.md`, `design.md`, `tasks.md`, and a `reports/`
-   folder.
-3. **build** — implement the tasks in order, keeping code and spec in
-   agreement, and write the discipline reports under `reports/`.
-4. **sync** — reconcile the delta specs against what was actually built, then
-   promote them into the canonical `lawbook/specs/` (`lawbook_sync`). The tool
-   is a deterministic copy; the agent does the code↔spec reconciliation first.
-5. **archive** — finalize: reconcile, sync, then move the change to
-   `lawbook/changes/archive/` (`lawbook_archive`), **within the same PR** —
-   never a post-merge chore. The archive is gated (see below).
+No non-trivial change lands without a lawbook change. The default execution
+model is **Cortex** (*One brain. Many agents.*): the host primary agent is the
+**coordinator** (`cortex` skill / MCP `cortex`) and dispatches explorer → planner →
+implementer → reviewer → tester → archiver. State:
+`lawbook/changes/<name>/harness.json` (`speclaw cortex`). Lawbook owns specs
+and ceremony; Cortex owns the multi-agent loop.
+
+1. **explore** (explorer) — think an idea through before committing (writes nothing).
+2. **draft** / **quick** (planner) — create `lawbook/changes/<name>/` artifacts
+   for the confirmed ceremony level; questions go to the human via the
+   coordinator.
+3. **build** (implementer) — implement tasks; hand off before final gates.
+4. **review** (reviewer) — `reports/review.md` PASS/FAIL (skipped at level 0).
+5. **test** (tester) — quality gates, manual verification, discipline reports.
+6. **sync** / **archive** (archiver) — reconcile, sync when needed, archive
+   within the same PR. Gated on Cortex verdicts plus tasks/reports/sync.
 
 ## Mandatory task steps
 
 `tasks.md` MUST include the steps defined in `lawbook/config.yaml` and the
-`spec-tasks-mandatory-steps` rule: feature branch first, tests reviewed and
-run, manual verification executed by the agent, discipline reports produced,
-docs updated, archive within the PR. The agent performs the manual testing
-itself — never delegates it.
+`spec-tasks-mandatory-steps` rule. The **tester** role performs manual
+verification — never the user; the coordinator must not archive without a
+test PASS.
 
 ## Reports
 
-Every change carries a `reports/` folder. `build` writes one report per
-discipline it touched, named for that discipline — an open set (`backend.md`,
-`frontend.md`, `api.md`, `database.md`, `infra.md`, … — `api.md` required
-whenever the change touches an API surface) recording what was tested
-and the real results — unit, integration, and end-to-end as applicable — with
-the commands run and their output. It is evidence of testing that travels with
-the change; the archive is blocked until at least one discipline report exists.
+Every change carries a `reports/` folder. The tester writes discipline reports;
+the reviewer writes `review.md`. Archive is blocked until evidence and harness
+verdicts are complete.
 
 ## Delta specs
 
@@ -51,18 +48,8 @@ the change; the archive is blocked until at least one discipline report exists.
 ## Archiving discipline
 
 Always archive with the `archive` command / `lawbook_archive` tool, never a manual
-`mv` — the tool performs the spec promotion and validation a manual move skips.
-
-Before archiving, the agent runs a reconciliation review: it compares what was
-built against the delta specs and, when the code has drifted past the original
-contracts, shows short insights and reconciles the delta specs.
-
-`lawbook_archive` is then **gated in the engine** — it refuses to archive (and
-reports the reason) while any task is unchecked, while `reports/` holds no
-discipline report, or while the delta specs are not yet synced into the
-canonical specs. Because the gate covers both the tool and the CLI, a change
-reaches the archive only when it is genuinely complete: reconcile, `sync`, then
-archive.
+`mv`. The engine refuses archive while tasks are unchecked, reports are missing,
+specs are out of sync when required, or harness review/test verdicts are not PASS.
 
 ## Amendments to the law