@esneiderbravo/speclaw 1.0.0 → 2.0.0

package/dist/modules/foundation/laws.js

@@ -1,13 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { z } from "zod";
-import { assetsDir } from "../../shared/paths.js";
-// The machine-readable law model and its manifest. This is the contract seam
-// (`.speclaw/laws-manifest.json`) between where laws come from and how they are
-// enforced: check-dispatcher owns the schema and the single `path` verification
-// backend; executable-laws extends the same model with `ast`/`deps`/`process`
-// backends by filling in more `verification.kind` cases — it never rewrites it.
-const ASSETS = assetsDir(import.meta.url);
+import { adaptedLaws, catalogLaws, mergeAdaptedSeed } from "./seed-laws.js";
 const depsRuleSchema = z.object({
     name: z.string().optional(),
     from: z.string(),
@@ -144,46 +138,50 @@ export function writeLawManifest(projectPath, manifest) {
     fs.writeFileSync(p, JSON.stringify(validated, null, 2) + "\n");
 }
 /**
- * The starter law manifest shipped with speclaw, seeded from a speclaw-style
- * project's own `path`-verifiable Project-specific laws. It is the source the
- * MVP compiles into `.speclaw/laws-manifest.json`; once executable-laws lands,
- * laws are authored in `docs/standards/*` and compiled here instead. Laws whose
- * scope does not match a given repo are simply inert there.
+ * The full shipped catalog as persistable laws (adapter metadata stripped).
+ * Prefer {@link seedManifestFor} at init/verify time so consumer repos do not
+ * inherit speclaw-dogfood paths that do not exist there.
  *
- * @returns The validated seed manifest read from the module's assets.
- * @throws If the seed asset is missing or fails validation.
+ * @returns The validated catalog.
+ * @throws If the catalog fails the law schema.
  */
 export function seedManifest() {
-    const raw = JSON.parse(fs.readFileSync(path.join(ASSETS, "laws", "laws-manifest.json"), "utf8"));
-    return manifestSchema.parse(raw);
+    return manifestSchema.parse({ version: 1, laws: catalogLaws() });
+}
+/**
+ * Catalog laws adapted to `projectPath`: only laws whose `requires` paths exist,
+ * with the cycle law scoped to detected source roots.
+ *
+ * @param projectPath - Project root whose tree is inspected.
+ * @returns The validated adapted manifest.
+ */
+export function seedManifestFor(projectPath) {
+    // Covers: req~adapt-seed-to-repo~1
+    return manifestSchema.parse({ version: 1, laws: adaptedLaws(projectPath) });
 }
 /**
  * The manifest the batch verifier should use: the project's file when present,
- * otherwise the shipped seed (so a clean CI clone does not silently pass).
+ * otherwise the **adapted** seed (so a clean CI clone does not silently pass,
+ * and does not evaluate inapplicable dogfood laws).
  *
  * @param projectPath - Project root to read from.
  */
 export function loadManifestForVerify(projectPath) {
-    return readLawManifest(projectPath) ?? seedManifest();
+    return readLawManifest(projectPath) ?? seedManifestFor(projectPath);
 }
 /**
- * Append shipped seed laws whose `id` is not already in `existing`. Existing
- * entries are never overwritten — a curated law keeps its prose, scope, and
- * enforcement across `update`.
+ * Merge an on-disk manifest with the adapted catalog. Existing curated entries
+ * (title or prose differs from the catalog) are never overwritten. Unmodified
+ * shipped laws whose required paths are absent are removed; unmodified cycle
+ * laws are replaced with the adapted scope.
  *
  * @param existing - The project's current manifest.
- * @returns The merged manifest and the ids that were added.
+ * @param projectPath - Project root used to adapt the catalog.
+ * @returns The merged manifest and the ids that were added or removed.
  */
-export function mergeSeedLaws(existing) {
-    const seed = seedManifest();
-    const have = new Set(existing.laws.map((l) => l.id));
-    const extra = seed.laws.filter((l) => !have.has(l.id));
-    if (extra.length === 0)
-        return { manifest: existing, added: [] };
-    return {
-        manifest: { ...existing, laws: [...existing.laws, ...extra] },
-        added: extra.map((l) => l.id),
-    };
+export function mergeSeedLaws(existing, projectPath) {
+    const { manifest, added, removed } = mergeAdaptedSeed({ version: existing.version, laws: existing.laws }, projectPath);
+    return { manifest: manifestSchema.parse(manifest), added, removed };
 }
 // ─── Glob matching (the `path` backend) ──────────────────────────────────────
 /**

package/dist/modules/foundation/scaffold.js

@@ -8,7 +8,7 @@ import { installWorkflow } from "../lawbook/register.js";
 import { installPack, loadPacks } from "../tools/packs.js";
 import { readManifest, writeManifest } from "../../shared/manifest.js";
 import { pkgVersion } from "../../shared/version.js";
-import { mergeSeedLaws, readLawManifest, seedManifest, writeLawManifest, } from "./laws.js";
+import { mergeSeedLaws, readLawManifest, seedManifestFor, writeLawManifest, } from "./laws.js";
 import { installHooks } from "./hooks.js";
 import { compileLaws } from "./compile-laws.js";
 import { refreshLockfile } from "./lock.js";
@@ -28,19 +28,22 @@ const FOUNDATION_DEFAULTS = {
     documentation_extra: "",
 };
 /**
- * Ensure the project has a law manifest. Missing → seed. Present → append any
- * shipped seed law whose `id` is absent (never overwrite a curated entry).
+ * Ensure the project has a law manifest. Missing → adapted seed for this tree.
+ * Present → merge the adapted catalog (never overwrite a curated entry; prune
+ * unmodified dogfood laws whose required paths are absent).
  */
 function ensureLawManifest(projectPath, report) {
     const existing = readLawManifest(projectPath);
     if (!existing) {
-        const seed = seedManifest();
+        const seed = seedManifestFor(projectPath);
         writeLawManifest(projectPath, seed);
         report.written.push(path.join(projectPath, ".speclaw", "laws-manifest.json"));
         return seed;
     }
-    const { manifest, added } = mergeSeedLaws(existing);
-    if (added.length > 0) {
+    const { manifest, added, removed } = mergeSeedLaws(existing, projectPath);
+    if (added.length > 0 ||
+        removed.length > 0 ||
+        JSON.stringify(manifest.laws) !== JSON.stringify(existing.laws)) {
         writeLawManifest(projectPath, manifest);
         report.written.push(path.join(projectPath, ".speclaw", "laws-manifest.json"));
     }

package/dist/modules/foundation/seed-laws.js

@@ -0,0 +1,263 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assetsDir } from "../../shared/paths.js";
+// Catalog adapter: the shipped JSON is speclaw's own architecture plus a few
+// portable laws. Consumer repos get only what their tree can actually host —
+// never compass/foundation/ATTRIBUTION rules copied from this package.
+//
+// Types are declared here (not imported from laws.ts) so the adapter and the
+// schema do not form a file-level import cycle.
+const ASSETS = assetsDir(import.meta.url);
+const CATALOG_PATH = path.join(ASSETS, "laws", "laws-manifest.json");
+/** Globs that drop test doubles from the cycle-law graph. */
+export const TEST_SCOPE_EXCLUSIONS = [
+    "!**/*.{spec,test}.{ts,tsx,js,jsx}",
+    "!**/test/**",
+    "!**/__tests__/**",
+];
+let cachedCatalog = null;
+/**
+ * Read the shipped law catalog (including adapter metadata). Cached for the
+ * process; tests that mutate the asset are not a supported path.
+ *
+ * @returns The parsed catalog.
+ * @throws If the asset is missing or not an object with a `laws` array.
+ */
+export function readLawCatalog() {
+    if (cachedCatalog)
+        return cachedCatalog;
+    const raw = JSON.parse(fs.readFileSync(CATALOG_PATH, "utf8"));
+    if (!raw || !Array.isArray(raw.laws)) {
+        throw new Error(`invalid law catalog at ${CATALOG_PATH}`);
+    }
+    cachedCatalog = raw;
+    return raw;
+}
+/** Drop adapter-only fields so the result is a persistable law. */
+export function asLaw(entry) {
+    const law = {
+        id: entry.id,
+        title: entry.title,
+        severity: entry.severity,
+        scope: [...entry.scope],
+        prose: entry.prose,
+        verification: structuredClone(entry.verification),
+        enforcement: entry.enforcement,
+        source: { ...entry.source },
+    };
+    if (entry.rationale !== undefined)
+        law.rationale = entry.rationale;
+    if (entry.status !== undefined)
+        law.status = entry.status;
+    return law;
+}
+/**
+ * Whether `req` names an existing file, directory, or glob under `projectPath`.
+ *
+ * @param projectPath - Project root.
+ * @param req - Relative path or glob (`*` / `**` in a segment).
+ */
+export function pathRequirementExists(projectPath, req) {
+    const trimmed = req.replace(/^!/, "").replace(/\/\*\*$/, "");
+    return globExists(projectPath, trimmed.split("/").filter(Boolean));
+}
+function globExists(dir, parts) {
+    if (parts.length === 0)
+        return fs.existsSync(dir);
+    if (!fs.existsSync(dir))
+        return false;
+    const head = parts[0];
+    const rest = parts.slice(1);
+    if (head === "**") {
+        if (globExists(dir, rest))
+            return true;
+        let st;
+        try {
+            st = fs.statSync(dir);
+        }
+        catch {
+            return false;
+        }
+        if (!st.isDirectory())
+            return false;
+        for (const name of fs.readdirSync(dir)) {
+            if (name.startsWith("."))
+                continue;
+            if (globExists(path.join(dir, name), parts))
+                return true;
+        }
+        return false;
+    }
+    if (head === "*") {
+        let st;
+        try {
+            st = fs.statSync(dir);
+        }
+        catch {
+            return false;
+        }
+        if (!st.isDirectory())
+            return false;
+        for (const name of fs.readdirSync(dir)) {
+            if (name.startsWith("."))
+                continue;
+            if (globExists(path.join(dir, name), rest))
+                return true;
+        }
+        return false;
+    }
+    return globExists(path.join(dir, head), rest);
+}
+function childSrcExists(projectPath, parent) {
+    const dir = path.join(projectPath, parent);
+    try {
+        if (!fs.statSync(dir).isDirectory())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    for (const name of fs.readdirSync(dir)) {
+        if (name.startsWith("."))
+            continue;
+        try {
+            if (fs.statSync(path.join(dir, name, "src")).isDirectory())
+                return true;
+        }
+        catch {
+            /* skip */
+        }
+    }
+    return false;
+}
+/**
+ * Source-root globs inferred from a repository layout.
+ *
+ * @param projectPath - Project root.
+ * @returns Globs covering app/package `src` trees, plus top-level `src/` or `lib/`, when they exist.
+ */
+export function detectSourceRootGlobs(projectPath) {
+    const out = [];
+    if (childSrcExists(projectPath, "apps"))
+        out.push("apps/*/src/**");
+    if (childSrcExists(projectPath, "packages"))
+        out.push("packages/*/src/**");
+    if (pathRequirementExists(projectPath, "src"))
+        out.push("src/**");
+    if (pathRequirementExists(projectPath, "lib"))
+        out.push("lib/**");
+    return out;
+}
+function positivesSatisfied(projectPath, scope) {
+    const positives = scope.filter((g) => !g.startsWith("!"));
+    if (positives.length === 0)
+        return true;
+    return positives.some((g) => pathRequirementExists(projectPath, g));
+}
+function withTestExclusions(scope) {
+    const have = new Set(scope);
+    const out = [...scope];
+    for (const g of TEST_SCOPE_EXCLUSIONS) {
+        if (!have.has(g))
+            out.push(g);
+    }
+    return out;
+}
+function adaptCycleLaw(projectPath, entry) {
+    const law = asLaw(entry);
+    const catalogHits = positivesSatisfied(projectPath, entry.scope);
+    const roots = catalogHits
+        ? entry.scope.filter((g) => !g.startsWith("!"))
+        : detectSourceRootGlobs(projectPath);
+    if (roots.length === 0)
+        return null;
+    law.scope = withTestExclusions(roots);
+    if (law.verification.kind === "graph") {
+        law.verification = {
+            kind: "graph",
+            rule: { ...(law.verification.rule ?? {}), circular: true, edgeKinds: ["import"] },
+        };
+    }
+    return law;
+}
+function isApplicable(projectPath, entry) {
+    const reqs = entry.requires ?? [];
+    return reqs.every((r) => pathRequirementExists(projectPath, r));
+}
+/**
+ * Catalog laws stripped of adapter metadata — the full shipped set, unfiltered.
+ *
+ * @returns Persistable laws in catalog order.
+ */
+export function catalogLaws() {
+    return readLawCatalog().laws.map(asLaw);
+}
+/**
+ * Laws from the catalog that apply to `projectPath`, with cycle-law scope
+ * rewritten to the repo's real source roots when needed.
+ *
+ * @param projectPath - Project root whose tree is inspected.
+ * @returns Persistable laws; adapter fields omitted.
+ */
+export function adaptedLaws(projectPath) {
+    // Covers: req~adapt-seed-to-repo~1
+    const out = [];
+    for (const entry of readLawCatalog().laws) {
+        if (!isApplicable(projectPath, entry))
+            continue;
+        if (entry.adaptScope === "source-roots") {
+            const adapted = adaptCycleLaw(projectPath, entry);
+            if (adapted)
+                out.push(adapted);
+            continue;
+        }
+        out.push(asLaw(entry));
+    }
+    return out;
+}
+/** True when `existing` is still the shipped catalog text (title + prose). */
+export function isUnmodifiedCatalogLaw(existing, catalog) {
+    return existing.title === catalog.title && existing.prose === catalog.prose;
+}
+/**
+ * Merge an on-disk manifest with the adapted catalog: append applicable ids,
+ * rewrite unmodified cycle-law scope, drop unmodified inapplicable dogfood.
+ *
+ * @param existing - The project's current manifest.
+ * @param projectPath - Project root used to adapt the catalog.
+ * @returns The merged manifest and the ids that were added or removed.
+ */
+export function mergeAdaptedSeed(existing, projectPath) {
+    const catalog = readLawCatalog();
+    const byId = new Map(catalog.laws.map((l) => [l.id, l]));
+    const adapted = adaptedLaws(projectPath);
+    const adaptedById = new Map(adapted.map((l) => [l.id, l]));
+    const added = [];
+    const removed = [];
+    const result = [];
+    const seen = new Set();
+    for (const law of existing.laws) {
+        const cat = byId.get(law.id);
+        if (!cat || !isUnmodifiedCatalogLaw(law, cat)) {
+            result.push(law);
+            seen.add(law.id);
+            continue;
+        }
+        const next = adaptedById.get(law.id);
+        if (next) {
+            result.push(next);
+            seen.add(law.id);
+        }
+        else {
+            removed.push(law.id);
+        }
+    }
+    for (const law of adapted) {
+        if (seen.has(law.id))
+            continue;
+        result.push(law);
+        added.push(law.id);
+        seen.add(law.id);
+    }
+    return { manifest: { ...existing, laws: result }, added, removed };
+}

package/dist/modules/foundation/setup-tool.js

@@ -64,12 +64,13 @@ export function handleSpeclawSetup(args) {
             return {
                 instructions: [
                     "1. Analyze the repository at projectPath and fill profile fields from the real codebase.",
-                    "2. Call speclaw_setup with action configure-agent / add-pack as needed.",
+                    "2. Call speclaw_setup with action configure-agent as needed (packs catalog may be empty).",
                     "3. Run lawbook_change action init and compass_index when scaffold completes via CLI if needed.",
+                    "4. Non-trivial work uses Cortex: cortex skill / speclaw cortex (MCP tool cortex).",
                 ],
                 profileFields: profileFieldHelp,
                 packs: loadPacks(),
-                note: "Full scaffold runs via CLI: speclaw init — not MCP.",
+                note: "Full scaffold runs via CLI: speclaw init — not MCP. Role agents install with the lawbook workflow.",
             };
         case "configure-agent": {
             if (!args.agent)

package/dist/modules/foundation/verify.js

@@ -17,8 +17,8 @@ export { underPaths } from "./verify-model.js";
  *
  * When the project has no index, every selected batch law is reported as
  * `skipped` with reason `no-index` (never silently passed). When the gitignored
- * manifest file is missing, the shipped seed is used so a clean clone does not
- * report an empty pass. Each evaluated law lands in exactly one of `passed` /
+ * manifest file is missing, the adapted seed is used so a clean clone does not
+ * report an empty pass or inherit inapplicable dogfood laws. Each evaluated law lands in exactly one of `passed` /
  * `failed` / `unknown`: it fails when the engine produced a finding, is
  * `unknown` when it produced none but rests on unresolved edges (which could
  * hide a violation), and passes otherwise.

package/dist/modules/lawbook/assets/agents/archiver.md

@@ -0,0 +1,19 @@
+---
+name: archiver
+description: Reconcile specs, sync, and archive a change when Cortex stage is archiving. No new feature implementation.
+tools: Read, Grep, Glob, Write, Edit, Bash, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__lawbook_change, mcp__speclaw__lawbook_validate, mcp__speclaw__lawbook_sync, mcp__speclaw__lawbook_archive, mcp__speclaw__cortex
+---
+
+You are the **archiver** role in speclaw's **Cortex** (One brain. Many agents.).
+
+## Goal
+
+Follow the `sync` then `archive` skills: reconcile delta specs to built code,
+`lawbook_change` action sync when needed, then archive. Advance Cortex to
+`done` after a successful archive.
+
+## Hard constraints
+
+- Do **not** start new feature work outside reconciliation.
+- If archive is gated, report blockers to the coordinator — do not bypass the
+  engine.

package/dist/modules/lawbook/assets/agents/explorer.md

@@ -0,0 +1,24 @@
+---
+name: explorer
+description: Read-only codebase investigation for a lawbook change. Use when the Cortex stage is exploring (or investigate for bugs). Compass-first; writes nothing under lawbook/ or src/.
+tools: Read, Grep, Glob, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_find, mcp__speclaw__compass_impact, mcp__speclaw__compass_trace, mcp__speclaw__compass_index, mcp__speclaw__lawbook_investigate
+disallowedTools: Write, Edit, MultiEdit, Bash, NotebookEdit
+---
+
+You are the **explorer** role in speclaw's **Cortex** (One brain. Many agents.).
+
+## Goal
+
+Investigate the idea or bug with Compass **before** any grep/read. Produce a
+short brief for the planner: relevant symbols, blast radius, risks, and open
+questions. Do **not** draft change artifacts or edit source.
+
+## Skill
+
+Follow the `explore` skill (or `investigate` when `changeType` is bug).
+
+## Hard constraints
+
+- No Write / StrReplace / git writes / draft / archive / Cortex advance to
+  implementing.
+- When finished, return the brief to the coordinator and stop.

package/dist/modules/lawbook/assets/agents/implementer.md

@@ -0,0 +1,20 @@
+---
+name: implementer
+description: Implement drafted lawbook tasks in source and tests. Use when Cortex stage is implementing. Does not run final quality gates, review, sync, or archive.
+tools: Read, Grep, Glob, Write, Edit, Bash, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_find, mcp__speclaw__compass_impact, mcp__speclaw__compass_index, mcp__speclaw__lawbook_change, mcp__speclaw__cortex
+disallowedTools: NotebookEdit
+---
+
+You are the **implementer** role in speclaw's **Cortex** (One brain. Many agents.).
+
+## Goal
+
+Work `tasks.md` in order using the `build` skill through implementation only.
+Keep code and delta specs in agreement. Check off completed tasks.
+
+## Hard constraints
+
+- Do **not** archive, push, or `laws accept`.
+- Do **not** skip the reviewer by "quietly fixing" after a FAIL — wait for
+  Cortex `rework` from the coordinator.
+- Stop after implementation hand-off; tester owns gates and discipline reports.

package/dist/modules/lawbook/assets/agents/planner.md

@@ -0,0 +1,27 @@
+---
+name: planner
+description: Draft lawbook change artifacts and ceremony level. Use when Cortex stage is planning. Asks clarifying questions via the coordinator; never edits src/.
+tools: Read, Grep, Glob, Write, Edit, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_find, mcp__speclaw__lawbook_change, mcp__speclaw__lawbook_level
+disallowedTools: Bash, NotebookEdit
+---
+
+You are the **planner** role in speclaw's **Cortex** (One brain. Many agents.).
+
+## Goal
+
+Turn the explorer brief + user intent into a reviewable change under
+`lawbook/changes/<name>/` at the confirmed ceremony level. Prefer `draft` /
+`quick` skills.
+
+## Questions
+
+If anything material is ambiguous, **stop**. Return numbered questions to the
+coordinator (do not invent answers). The coordinator advances Cortex with
+`pauseForQuestions`. After human answers, continue drafting.
+
+## Hard constraints
+
+- May write only under `lawbook/changes/<name>/` (and related lawbook paths).
+- Do **not** edit `src/`, run archive, or implement code.
+- When the draft is complete, tell the coordinator to `cortex advance` toward
+  implementing.

package/dist/modules/lawbook/assets/agents/reviewer.md

@@ -0,0 +1,25 @@
+---
+name: reviewer
+description: Deep review of implemented change without patching code. Writes reports/review.md with PASS or FAIL. Use when Cortex stage is reviewing.
+tools: Read, Grep, Glob, Write, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_find, mcp__speclaw__compass_impact, mcp__speclaw__compass_trace, mcp__speclaw__lawbook_change, mcp__speclaw__cortex
+disallowedTools: Edit, MultiEdit, Bash, NotebookEdit
+---
+
+You are the **reviewer** role in speclaw's **Cortex** (One brain. Many agents.).
+
+## Goal
+
+Review the branch/diff against proposal, tasks, delta specs, and
+`docs/standards/*`. Write `lawbook/changes/<name>/reports/review.md` with:
+
+- Verdict: `PASS` or `FAIL`
+- Findings anchored to file paths / symbols
+- Rework guidance if FAIL
+
+You may create/overwrite **only** `reports/review.md` (and read everything else).
+
+## Hard constraints
+
+- Do **not** patch application source to "make it pass".
+- Return the verdict to the coordinator for `cortex advance` (PASS) or
+  `cortex rework` (FAIL).

package/dist/modules/lawbook/assets/agents/tester.md

@@ -0,0 +1,21 @@
+---
+name: tester
+description: Run quality gates and manual verification; write discipline reports. Use when Cortex stage is testing. May add missing tests only — not features.
+tools: Read, Grep, Glob, Write, Edit, Bash, CallMcpTool, mcp__speclaw__compass_explore, mcp__speclaw__compass_affected_tests, mcp__speclaw__lawbook_change, mcp__speclaw__cortex
+---
+
+You are the **tester** role in speclaw's **Cortex** (One brain. Many agents.).
+
+## Goal
+
+Follow the `test` skill: quality gates, manual verification, discipline
+reports. Record verdict PASS or FAIL for the coordinator.
+
+You MAY add or fix **tests** that are missing for covered requirements. You
+MUST NOT implement new product features.
+
+## Hard constraints
+
+- Do not archive or sync.
+- On FAIL, return findings for Cortex `rework`; on PASS, coordinator advances
+  to archiving.

package/dist/modules/lawbook/assets/commands/cortex.md

@@ -0,0 +1,11 @@
+---
+description: Coordinate Cortex (One brain. Many agents.) for a lawbook change until archive.
+---
+
+Cortex the change: $ARGUMENTS
+
+Follow the `cortex` skill. You are the coordinator — spawn or adopt
+explorer → planner → implementer → reviewer → tester → archiver. Drive state
+with the `cortex` MCP tool (`status`/`start`/`advance`/`rework`/`brief`) or
+`speclaw cortex …`. Surface planner questions to the human. Do not implement
+product code yourself.

package/dist/modules/lawbook/assets/rules/spec-tasks-mandatory-steps.md

@@ -1,5 +1,5 @@
 ---
-description: Enforce the mandatory steps from lawbook/config.yaml when creating tasks.md, and ensure the agent executes all manual verification itself.
+description: Enforce the mandatory steps from lawbook/config.yaml when creating tasks.md, and ensure the tester role executes all manual verification itself.
 alwaysApply: true
 ---
 
@@ -19,7 +19,7 @@ steps, branch convention, and testing/documentation requirements.
 - Review and update the affected tests.
 - Run the quality gates and verify they pass
   (see `docs/standards/testing-standards.md`).
-- Perform manual verification of the behavior — **the agent executes this
+- Perform manual verification of the behavior — **the tester role executes this
   itself, never the user.**
 - Produce the discipline reports under `reports/` — one per discipline the change
   touched, from an open set (`backend.md`, `frontend.md`, `api.md`, `database.md`,
@@ -28,13 +28,13 @@ steps, branch convention, and testing/documentation requirements.
   for what the feature touched.
 - Update the technical documentation the change touches.
 - Archive the change within the same PR (the `archive` command / `lawbook_archive`
-  tool).
+  tool) after Cortex review/test PASS.
 
-## 3. Manual verification — the agent must execute it
+## 3. Manual verification — the tester must execute it
 
-The coding agent performs all manual testing itself (exercise the endpoint, UI,
-or CLI). Never delegate it to the user. A task that requires verification is
-not complete until the agent has verified it.
+Under Cortex, the **tester** role performs all manual testing
+(exercise the endpoint, UI, or CLI). Never delegate it to the user. A task that
+requires verification is not complete until the tester has verified it.
 
 ## 4. Archiving is part of the change
 
@@ -42,6 +42,7 @@ A change is not done until it is archived with `lawbook_archive` (never a manual
 `mv`). The archive lands in the same PR that implements the change.
 
 `lawbook_archive` is gated: it refuses to archive while any task is unchecked,
-while `reports/` has no discipline report, or while the delta specs are not yet
-synced into the canonical specs. Resolve those first — the gate is enforced in
-the engine, so a manual `mv` only hides an incomplete change.
+while `reports/` has no discipline report, while the delta specs are not yet
+synced into the canonical specs, or while harness review/test verdicts are not
+PASS. Resolve those first — the gate is enforced in the engine, so a manual `mv`
+only hides an incomplete change.

package/dist/modules/lawbook/assets/skills/build/steps/03-implement.md

@@ -8,4 +8,4 @@
   spec, update the spec in the change (not silently) — the two must agree.
 - Check off each task in `tasks.md` as you complete it.
 
-Next: read `steps/04-quality-gates.md` and do only what it says.
+Next: read `steps/04-hand-off.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/build/steps/04-hand-off.md

@@ -0,0 +1,17 @@
+# Hand off to review / test
+
+Implementation for this role stops here. Do **not** run the full quality-gate
+suite, write discipline reports, sync, or archive — those belong to the
+**tester** and **archiver** roles under Cortex.
+
+Tell the coordinator:
+
+1. Which tasks are done
+2. Notable spec reconciliations still needed
+3. To `cortex advance` from `implementing` (→ reviewing at level ≥1, or
+   testing at level 0)
+
+The **tester** role follows the `test` skill for gates, manual verification,
+and discipline reports.
+
+No further steps remain — build workflow complete.

package/dist/modules/lawbook/assets/skills/cortex/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: cortex
+description: Coordinate Cortex — One brain. Many agents. Spawn or adopt explorer, planner, implementer, reviewer, tester, archiver until archive. Use for non-trivial work: "build X", "implement the change", "run cortex", "orchestrate X".
+---
+
+# Cortex — One brain. Many agents.
+
+You are the **coordinator**. Do not implement product code yourself.
+
+Drive state with the `cortex` MCP tool (`status` / `start` / `advance` /
+`rework` / `brief`) or `speclaw cortex …`. Command: `/lawbook/cortex`.
+
+Read `steps/01-load-or-start.md` and do only what it says.