@esneiderbravo/speclaw 2.0.12 → 2.0.13

package/dist/modules/compass/indexer.js

@@ -197,8 +197,9 @@ export const BUILTIN_SQL_LIST = BUILTIN_GLOBALS.map((n) => `'${n}'`).join(", ");
 /** Most bind parameters a scoped {@link resolveEdges} call uses before running unscoped. */
 const MAX_SCOPE_PARAMS = 10_000;
 /**
- * Resolve call and import edges to node ids — the one place edge resolution
- * lives, shared by the full index run and incremental re-indexing.
+ * Resolve call, import, and type-reference (`ref`) edges to node ids — the one
+ * place edge resolution lives, shared by the full index run and incremental
+ * re-indexing.
  *
  * - Edges whose `dst_node_id` points at a node that no longer exists (its file
  *   was re-extracted) are reset to unresolved first.
@@ -216,6 +217,10 @@ const MAX_SCOPE_PARAMS = 10_000;
  *   never call targets. An import of a symbol-less or re-exporting file (a
  *   barrel) resolves to that file's file-owner node, so member calls through
  *   it bind by name like this.
+ * - A `ref` resolves only to the definition its same-file import binding's
+ *   target file holds (barrel subtree as for calls), else to a same-file
+ *   definition; never by a bare global name (`ref` edges are not counted in
+ *   the returned stats).
  * - Imports resolve their specifier relative to the importing file, then
  *   through the nearest `tsconfig.json`/`jsconfig.json` `paths`/`baseUrl`, and
  *   point at the target file's file-owner node when it has one, otherwise at
@@ -287,6 +292,25 @@ export function resolveEdges(db, fileIds) {
             OR (is_member = 2 AND edges.spec IS NOT NULL AND ${importTarget} IS NOT NULL))
        ${callScope}`).run(...(narrow ? [...ids, ...importScope, ...ids] : []));
     const calls = resolvedCalls() - before;
+    // Covers: req~type-ref-edges~1
+    // A type reference resolves only through its own file: the definition its
+    // import binding's target file (or that barrel's subtree) holds, else a
+    // same-file definition. Never by a bare global name, so a generic `Props`
+    // in an unrelated file stays NULL. `is_member = 1` (`a.b.Type`, a
+    // non-import qualifier) never resolves.
+    db.prepare(`UPDATE edges SET dst_node_id = (
+       SELECT n.id FROM nodes n
+       WHERE n.name = edges.dst_name
+         AND n.kind <> '${FILE_NODE_KIND}'
+         AND ((edges.spec IS NOT NULL AND (n.file_id = ${importTarget} OR ${underTargetDir}))
+              OR (edges.is_member = 0 AND n.file_id = edges.src_file_id))
+       ORDER BY CASE WHEN n.file_id = ${importTarget} THEN 0
+                     WHEN edges.spec IS NOT NULL AND ${underTargetDir} THEN 1
+                     ELSE 2 END, n.id
+       LIMIT 1
+     )
+     WHERE kind = 'ref' AND dst_node_id IS NULL AND is_member <> 1
+       ${callScope}`).run(...(narrow ? [...ids, ...importScope, ...ids] : []));
     return { calls, imports };
 }
 /** Project root of an index database stored at `<root>/.speclaw/index.db`. */

package/dist/modules/compass/query.js

@@ -170,11 +170,37 @@ function pickPrimary(symbols) {
     }
     return symbols.find((s) => s.kind === "function") ?? symbols[0];
 }
+/** Rows de-duplicated on every field (the call-only caller list, as before refs). */
+function uniqueRows(rows) {
+    const seen = new Set();
+    return rows.filter((r) => {
+        const key = `${r.name}\0${r.kind}\0${r.file}\0${r.line}`;
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/**
+ * One caller entry per owner node with `via`: `call` (at its first call line)
+ * when the node calls the symbol, else `ref` (at its first reference line).
+ */
+// Covers: req~type-ref-edges~1
+function callersWithVia(rows) {
+    const byNode = new Map();
+    for (const r of rows) {
+        const prev = byNode.get(r.id);
+        if (!prev || (prev.via === "ref" && r.via === "call")) {
+            byNode.set(r.id, { name: r.name, kind: r.kind, file: r.file, line: r.line, via: r.via });
+        }
+    }
+    return [...byNode.values()].sort((a, b) => a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1);
+}
 /**
  * Source, callers, and callees for one definition. `others` are the
  * `otherMatches` (same-name siblings, or the rest of a file).
  */
-function assembleExplore(db, projectPath, best, others) {
+function assembleExplore(db, projectPath, best, others, includeRefs = false) {
     // Covers: req~compass-mcp-surface~1
     // Resolved callees only, one row per target node at its first call line, so
     // unresolved names (builtins, member calls) never crowd out project callees.
@@ -199,19 +225,25 @@ function assembleExplore(db, projectPath, best, others) {
     // builtin global name (`test`, `fetch`) matches by name only within the
     // definition's own file. A caller outside any definition is its file-owner
     // node (`kind: "file"`).
-    const callers = db
-        .prepare(`SELECT DISTINCT owner.name AS name, owner.kind AS kind, f.path AS file, e.line
+    // A `ref` edge (type reference) counts only through its resolved id, never by name.
+    const kinds = includeRefs ? "e.kind IN ('call', 'ref')" : "e.kind = 'call'";
+    const rows = db
+        .prepare(`SELECT DISTINCT owner.id AS id, owner.name AS name, owner.kind AS kind, f.path AS file,
+              e.line, e.kind AS via
        FROM edges e
        JOIN nodes owner ON owner.id = e.src_node_id
        JOIN files f ON f.id = owner.file_id
-       WHERE (e.dst_node_id = ? OR (
-               e.dst_name = ? AND e.is_member = 0
+       WHERE ${kinds}
+         AND (e.dst_node_id = ? OR (
+               e.kind = 'call' AND e.dst_name = ? AND e.is_member = 0
                AND (e.dst_name NOT IN (${BUILTIN_SQL_LIST})
                     OR e.src_file_id = (SELECT file_id FROM nodes WHERE id = ?))
              ))
-         AND e.kind = 'call'
        ORDER BY f.path, e.line`)
         .all(best.id, best.name, best.id);
+    const callers = includeRefs
+        ? callersWithVia(rows)
+        : uniqueRows(rows.map(({ name, kind, file, line }) => ({ name, kind, file, line })));
     return {
         found: true,
         symbol: {
@@ -247,7 +279,7 @@ function assembleExplore(db, projectPath, best, others) {
  * file one); a file with no node at all reports that it has no symbols. A non-unique suffix falls through to {@link search}, which also
  * matches `files.path`.
  */
-function exploreWhenNameMisses(db, projectPath, query) {
+function exploreWhenNameMisses(db, projectPath, query, includeRefs) {
     // Covers: req~explore-file-path~2
     const resolved = resolveIndexedFile(db, projectPath, query);
     if (resolved.status === "one") {
@@ -255,7 +287,7 @@ function exploreWhenNameMisses(db, projectPath, query) {
         const owner = symbols.length === 0 ? fileSymbols(db, resolved.file, true)[0] : undefined;
         if (owner) {
             return {
-                ...assembleExplore(db, projectPath, owner, []),
+                ...assembleExplore(db, projectPath, owner, [], includeRefs),
                 message: `Path "${resolved.file}" declares no symbols; resolved to its file-owner node.`,
             };
         }
@@ -268,7 +300,7 @@ function exploreWhenNameMisses(db, projectPath, query) {
             };
         }
         const primary = pickPrimary(symbols);
-        const result = assembleExplore(db, projectPath, primary, symbols.filter((s) => s.id !== primary.id));
+        const result = assembleExplore(db, projectPath, primary, symbols.filter((s) => s.id !== primary.id), includeRefs);
         return {
             ...result,
             message: `Path "${resolved.file}" resolved to ${primary.name}.`,
@@ -301,10 +333,14 @@ function exploreWhenNameMisses(db, projectPath, query) {
  *
  * @param projectPath - Absolute path to the indexed project.
  * @param query - Exact node name, or a file path when no symbol has that name.
+ * @param opts - `includeRefs` (default false) also lists type-reference
+ *   (`ref`) callers and tags every caller with `via`; the MCP and CLI explore
+ *   opt in, investigation and ceremony signals keep the call-only list.
  * @returns The explore result; `found` is `false` when no single symbol is selected.
  * @throws If no index exists for the project.
  */
-export function explore(projectPath, query) {
+export function explore(projectPath, query, opts = {}) {
+    const includeRefs = opts.includeRefs ?? false;
     requireIndex(projectPath);
     const db = openDb(projectPath);
     try {
@@ -317,8 +353,8 @@ export function explore(projectPath, query) {
          LIMIT 10`)
             .all(query);
         if (matches.length === 0)
-            return exploreWhenNameMisses(db, projectPath, query);
-        return assembleExplore(db, projectPath, matches[0], matches.slice(1));
+            return exploreWhenNameMisses(db, projectPath, query, includeRefs);
+        return assembleExplore(db, projectPath, matches[0], matches.slice(1), includeRefs);
     }
     finally {
         db.close();

package/dist/modules/compass/register.js

@@ -11,6 +11,7 @@ import { hotspots, coupling } from "./hotspots.js";
 import { startWatch, stopWatch, watchStatus } from "./watcher.js";
 import { exploreRich, findSymbols, formatExploreRich, } from "./explore-rich.js";
 import { diffContext, formatDiffContext } from "./diff-context.js";
+import { formatFindResponse } from "./find-output.js";
 const includeEnum = z.array(z.enum(["source", "callers", "callees", "blast_radius", "tests", "hotspot"]));
 /** Register Compass MCP tools on the given server. */
 export function registerCompass(server, opts = {}) {
@@ -43,7 +44,7 @@ export function registerCompass(server, opts = {}) {
             mode: (mode ?? "brief"),
             maxDepth,
         });
-        return text(formatExploreRich(result, (mode ?? "brief")));
+        return text(formatExploreRich(result, (mode ?? "brief")), mode ?? "brief");
     });
     add("compass_find", "Hybrid search over the index: BM25, vectors, and name match. mode sets weights; pass focus for edited files.", {
         projectPath: z.string(),
@@ -52,7 +53,10 @@ export function registerCompass(server, opts = {}) {
         limit: z.number().optional(),
         focus: z.array(z.string()).optional(),
         maxTokens: z.number().int().min(256).max(32_000).optional(),
-    }, async ({ projectPath, query, mode, limit, focus, maxTokens }) => text(JSON.stringify(await findSymbols(projectPath, query, mode, limit, { focus, maxTokens }), null, 2)));
+    }, async ({ projectPath, query, mode, limit, focus, maxTokens }) => {
+        const found = await findSymbols(projectPath, query, mode, limit, { focus, maxTokens });
+        return text(formatFindResponse(found), { maxTokens: found.cap });
+    });
     add("compass_diff_context", "Graph context of changes in one call: symbols, blast radius, tests, hotspots. Default: working tree.", {
         projectPath: z.string(),
         rev: z.string().optional(),
@@ -67,7 +71,7 @@ export function registerCompass(server, opts = {}) {
             mode: (mode ?? "brief"),
             maxDepth,
         });
-        return text(formatDiffContext(result, (mode ?? "brief")));
+        return text(formatDiffContext(result, (mode ?? "brief")), mode ?? "brief");
     });
     add("compass_index", "Build or refresh the code graph index; optional watch action for live re-index.", {
         projectPath: z.string(),
@@ -94,8 +98,9 @@ export function registerCompass(server, opts = {}) {
         handler: async ({ projectPath, query, limit }) => {
             logDeprecatedCall(projectPath, "compass_search");
             recordCompassCall(projectPath, "compass_search");
-            const body = JSON.stringify(await findSymbols(projectPath, query, "exact", limit), null, 2);
-            return text(prefixDeprecated("compass_search", body));
+            const found = await findSymbols(projectPath, query, "exact", limit);
+            const prefix = prefixDeprecated("compass_search", "");
+            return text(formatFindResponse(found, { prefix }), { maxTokens: found.cap });
         },
     });
     defineAliasTool(server, {
@@ -105,8 +110,9 @@ export function registerCompass(server, opts = {}) {
         handler: async ({ projectPath, query, limit }) => {
             logDeprecatedCall(projectPath, "compass_recall");
             recordCompassCall(projectPath, "compass_recall");
-            const body = JSON.stringify(await findSymbols(projectPath, query, "concept", limit), null, 2);
-            return text(prefixDeprecated("compass_recall", body));
+            const found = await findSymbols(projectPath, query, "concept", limit);
+            const prefix = prefixDeprecated("compass_recall", "");
+            return text(formatFindResponse(found, { prefix }), { maxTokens: found.cap });
         },
     });
     defineAliasTool(server, {

package/dist/modules/cortex/harness.js

@@ -6,7 +6,8 @@
  * 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).
+ * is read locally from `change.json` `confirmedLevel` (default 3) at start and
+ * again on every advance and rework.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -166,9 +167,18 @@ export function handleHarness(args) {
     if (!current) {
         throw new Error(`no harness.json for "${change}" — run cortex start first`);
     }
+    // Covers: req~harness-level-current~1
+    // The level is re-read on every mutating op, so a `level set` after start
+    // governs the next route; unconfirmed or missing → 3 (never skips planning).
+    const level = readConfirmedLevel(projectPath, change);
     if (harnessOp === "advance") {
-        // Planner may pause for questions instead of advancing to implement.
-        if (current.stage === "planning" && args.pauseForQuestions) {
+        // Covers: req~harness-pause-questions~1
+        // Only the planner may pause for questions; anywhere else the pause would
+        // be dropped silently, so it is rejected before any write.
+        if (args.pauseForQuestions && current.stage !== "planning") {
+            throw new Error(`pauseForQuestions is only valid from stage planning (current: ${current.stage})`);
+        }
+        if (args.pauseForQuestions) {
             const questions = args.openQuestions ?? [];
             if (questions.length === 0) {
                 throw new Error(`pauseForQuestions requires at least one openQuestions entry`);
@@ -176,6 +186,7 @@ export function handleHarness(args) {
             const next = {
                 ...current,
                 stage: "questions",
+                level,
                 openQuestions: questions,
                 history: [
                     ...current.history,
@@ -191,7 +202,7 @@ export function handleHarness(args) {
             writeHarness(projectPath, change, next);
             return next;
         }
-        const to = allowedAdvance(current.stage, current.level, args.verdict ?? undefined);
+        const to = allowedAdvance(current.stage, level, args.verdict ?? undefined);
         // Compass-first gate: runs before any write, so a strict rejection leaves
         // harness.json byte-identical.
         let compassEvidence;
@@ -213,6 +224,7 @@ export function handleHarness(args) {
         const next = {
             ...current,
             stage: to,
+            level,
             verdicts,
             openQuestions: current.stage === "questions" ? [] : current.openQuestions,
             history: [
@@ -249,6 +261,7 @@ export function handleHarness(args) {
         const next = {
             ...current,
             stage: "implementing",
+            level,
             iteration: current.iteration + 1,
             verdicts,
             history: [

package/dist/modules/cortex/status.js

@@ -14,7 +14,7 @@ import { stageStartedAt } from "./compass-gate.js";
 import { OUTPUT_BUDGET, estimateTokens } from "../../shared/output-budget.js";
 import { resolveChangeDir } from "./paths.js";
 /** Interval used when the key is missing or invalid. */
-export const DEFAULT_STATUS_INTERVAL_MINUTES = 5;
+export const DEFAULT_STATUS_INTERVAL_MINUTES = 0;
 /**
  * Largest interval reported. A session timer is a cron expression, and
  * an every-N-minutes step only exists for N ≤ 59; 60 is the hourly ping.

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

@@ -23,17 +23,18 @@ Claude-specific notes: [`CLAUDE.md`](CLAUDE.md). The law: [`LAWS.md`](LAWS.md).
    first; Claude Code sessions refresh an existing index at start), or the
    target isn't indexed code (stylesheets, config, logs). Cheat
    sheet: [`docs/compass.md`](docs/compass.md).
-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:
+3. **Cortex, always — one brain on the critical path** (*One brain. Many
+   agents.*). Branch `<type>/<slug>`, locate with Compass, implement the
+   change and its test yourself, run the tests, finish. The `Stop` hook
+   (`speclaw ship-on-stop`) — or `speclaw ship <change> --summary "<what and
+   why>"` as your last step on agents without hooks — records the change, runs
+   the gates once, writes the report from their real output, and archives
+   level-0 work. Review happens on the PR and never blocks the agent. Add
+   agents only to run three or more large, independent parts in parallel.
+   Details: the `cortex` skill and
    [`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)
-   (owned by the **tester** role under Cortex):
+   [`docs/standards/testing-standards.md`](docs/standards/testing-standards.md):
    - Tests: `{{test_commands}}`
    - Lint / type-check: `{{lint_commands}}`
 5. **Respect the conventions** — branches `{{branch_pattern}}`, commits

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

@@ -50,16 +50,19 @@ 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 Cortex loop, always
-
-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);
-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 2 — Cortex, always — one brain on the critical path
+
+Every change is built with **Cortex** (*One brain. Many agents.*), and Cortex
+costs no more time than working alone: branch `<type>/<slug>`, locate with
+Compass, implement the change and its test yourself, run the tests, finish.
+Then stop: the `Stop` hook (`speclaw ship-on-stop`) records the change, runs
+the gates once, writes the report from their real output, and archives
+level-0 work with no agent turns; a failing gate comes back to you. Do not run
+`speclaw ship` yourself, check the hook, open the archive, edit the generated
+report, read the process docs, or drive the harness by hand. Review happens on the PR, never blocking the
+agent. Add agents only to run three or more large, independent parts in
+parallel. Details: the `cortex` skill and
+[`docs/standards/lawbook.md`](docs/standards/lawbook.md).
 
 ## Rule 3 — Quality gates are non-negotiable
 

package/dist/modules/foundation/assets/docs/compass.template.md

@@ -30,7 +30,7 @@ a request, not whole files.
 | Tool | Use it to |
 |------|-----------|
 | `compass_index` | Build/refresh the graph (`.speclaw/index.db`). Incremental — unchanged files are skipped by hash. Run once after init and after significant edits. |
-| `compass_find` | Find code: `mode: exact` by name/keyword, `mode: concept` by meaning in natural language. |
+| `compass_find` | Find code: `mode: exact` by exact name (one or more identifiers; a missing name returns `found: false` and up to five `nearest` names), `mode: concept` by meaning in natural language. Returns compact hits (`name`, `kind`, `file`, `line`) in one JSON document that fits `maxTokens` (default 1500); `truncated: true` only when it trimmed. |
 | `compass_explore` | Read a node's verbatim source plus its callers and callees. The default before editing. Add `include: ["blast_radius"]` for what could break, or `to: <symbol>` for the call path between two nodes. |
 | `compass_diff_context` | Symbols, blast radius, and tests for a diff (working tree or a rev). |
 
@@ -46,9 +46,16 @@ project method, so they do not appear as callers. Calls through an imported
 re-export barrel (`index.ts` holding `export * from "./lib/core"`) bind by
 name, preferring a definition under the barrel's directory.
 
-Compass uses index schema 11. speclaw 2.0.9 or older, including an MCP entry
-pinned at `@2.0.9`, rebuilds a schema-11 index from scratch (losing the
-embedding cache). Run `speclaw update` so the pinned MCP entry moves to 2.0.10.
+Explore callers carry `via`: `call` for calls, `ref` for type references
+(annotations and `extends`/`implements` clauses that resolve through the file's
+own import or a same-file definition). Type references never change blast
+radius, affected tests, or ranking. `compass_find` keeps only indexed files in
+`focus` and lists the others in `focusIgnored`.
+
+Compass uses index schema 12 (11→12 forces one reindex; embeddings reused).
+speclaw 2.0.12 or older, including an MCP entry pinned at `@2.0.12`, rebuilds a
+schema-12 index from scratch (losing the embedding cache). Pin every speclaw to
+2.0.13: run `speclaw update` so the pinned MCP entry moves to 2.0.13.
 
 `compass_index` also takes `action: start|stop|status` to keep the index fresh
 automatically (a debounced incremental re-index on file change).

package/dist/modules/foundation/deps.js

@@ -1,3 +1,4 @@
+import { DEFAULT_EDGE_KINDS } from "./laws.js";
 import { underPaths } from "./verify-model.js";
 /** Substitute `$1`, `$2`, … in a pattern with capture groups from a match. */
 function applyGroups(pattern, match) {
@@ -5,9 +6,10 @@ function applyGroups(pattern, match) {
 }
 /** The `IN (?, ?)` clause and params for an optional edge-kind filter. */
 function edgeKindClause(edgeKinds) {
-    if (!edgeKinds || edgeKinds.length === 0)
-        return { sql: "", params: [] };
-    return { sql: ` AND e.kind IN (${edgeKinds.map(() => "?").join(", ")})`, params: edgeKinds };
+    // Type-reference (`ref`) edges feed explore callers only; a law without
+    // explicit kinds keeps reading calls and imports, as before refs existed.
+    const kinds = edgeKinds && edgeKinds.length > 0 ? edgeKinds : DEFAULT_EDGE_KINDS;
+    return { sql: ` AND e.kind IN (${kinds.map(() => "?").join(", ")})`, params: [...kinds] };
 }
 /** Load resolved file→file edges (earliest line per pair) from the index. */
 function resolvedEdges(db, edgeKinds) {

package/dist/modules/foundation/graph.js

@@ -1,10 +1,10 @@
-import { matchesScope } from "./laws.js";
+import { DEFAULT_EDGE_KINDS, matchesScope } from "./laws.js";
 import { underPaths } from "./verify-model.js";
 /** Build the cross-file dependency graph, restricted to `paths` and `scope`. */
 function buildGraph(db, paths, edgeKinds, scope) {
-    const kindFilter = edgeKinds && edgeKinds.length > 0
-        ? ` AND e.kind IN (${edgeKinds.map(() => "?").join(", ")})`
-        : "";
+    // No explicit kinds: calls and imports only (`ref` edges never form a law cycle).
+    const kinds = edgeKinds && edgeKinds.length > 0 ? edgeKinds : DEFAULT_EDGE_KINDS;
+    const kindFilter = ` AND e.kind IN (${kinds.map(() => "?").join(", ")})`;
     const rows = db
         .prepare(`SELECT DISTINCT sf.path AS src, df.path AS dst
        FROM edges e
@@ -12,7 +12,7 @@ function buildGraph(db, paths, edgeKinds, scope) {
        JOIN nodes dn ON dn.id = e.dst_node_id
        JOIN files df ON df.id = dn.file_id
        WHERE e.dst_node_id IS NOT NULL AND sf.path <> df.path${kindFilter}`)
-        .all(...(edgeKinds && edgeKinds.length > 0 ? edgeKinds : []));
+        .all(...kinds);
     const adj = new Map();
     for (const { src, dst } of rows) {
         if (!underPaths(src, paths) || !underPaths(dst, paths))

package/dist/modules/foundation/hooks.js

@@ -41,6 +41,21 @@ export const REINDEX_FILE_MARKER = "speclaw reindex-file";
  * than the command rejects it as unknown (exit 1) before touching the index.
  */
 export const REINDEX_FILE_COMMAND = speclawCommand("reindex-file");
+/**
+ * Substring every ship-on-stop command contains, in each of its resolution
+ * branches. It is the merge identity of the `Stop` ship hook.
+ */
+export const SHIP_ON_STOP_MARKER = "speclaw ship-on-stop";
+/**
+ * The POSIX `sh` command the `Stop` hook runs: when the agent finishes a turn
+ * with new changes on a feature branch, speclaw records the change, runs the
+ * gates once, writes the report from their real output, and archives level-0
+ * work — with no agent turn. Guarded on `lawbook/` instead of the index. Its
+ * stderr is kept so a failing gate reaches the agent (exit 2).
+ */
+export const SHIP_ON_STOP_COMMAND = speclawCommand("ship-on-stop");
+/** Seconds the Stop hook may run: the project's own gates run inside it. */
+const SHIP_ON_STOP_TIMEOUT = 600;
 /** Seconds the edit hook may run; the command returns once it has spawned the work. */
 const REINDEX_TIMEOUT_SECONDS = 10;
 /**
@@ -53,11 +68,17 @@ const REINDEX_TIMEOUT_SECONDS = 10;
  */
 export function speclawCommand(sub) {
     // Covers: req~edit-reindex-hook~1
-    return ('cd "${CLAUDE_PROJECT_DIR:-.}" 2>/dev/null && [ -f .speclaw/index.db ] && { ' +
-        `if [ -x node_modules/.bin/speclaw ]; then node_modules/.bin/speclaw ${sub}; ` +
+    const ship = sub === "ship-on-stop";
+    const run = `if [ -x node_modules/.bin/speclaw ]; then node_modules/.bin/speclaw ${sub}; ` +
         `elif command -v speclaw >/dev/null 2>&1; then speclaw ${sub}; ` +
-        `else npm_config_update_notifier=false npm_config_offline=true npx --no-install @esneiderbravo/speclaw ${sub}; fi; ` +
-        "} >/dev/null 2>&1 || true");
+        `else npm_config_update_notifier=false npm_config_offline=true npx --no-install @esneiderbravo/speclaw ${sub}; fi; `;
+    // The ship hook keeps its exit code (2 feeds a failing gate back to the
+    // agent) and its stderr; stdout is discarded like the other hooks.
+    return ship
+        ? 'cd "${CLAUDE_PROJECT_DIR:-.}" 2>/dev/null && [ -d lawbook ] && { ' + run + "} >/dev/null"
+        : 'cd "${CLAUDE_PROJECT_DIR:-.}" 2>/dev/null && [ -f .speclaw/index.db ] && { ' +
+            run +
+            "} >/dev/null 2>&1 || true";
 }
 /** `SessionStart` matcher covering every session source Claude Code reports. */
 const SESSION_START_MATCHER = "startup|resume|clear|compact";
@@ -113,6 +134,7 @@ export function isSpeclawHook(h) {
     return (o?.type === "command" &&
         typeof o?.command === "string" &&
         (o.command.includes(SESSION_START_MARKER) ||
+            o.command.includes(SHIP_ON_STOP_MARKER) ||
             o.command.includes(REINDEX_FILE_MARKER) ||
             o.command.includes(LEGACY_SESSION_START_MARKER)));
 }
@@ -161,6 +183,10 @@ export function compileHooks(manifest) {
     });
     if (hasGate)
         byEvent.Stop = [{ hooks: [{ ...SPECLAW_HOOK }] }];
+    // Covers: req~ship-on-stop-hook~1
+    (byEvent.Stop ??= []).push({
+        hooks: [{ type: "command", command: SHIP_ON_STOP_COMMAND, timeout: SHIP_ON_STOP_TIMEOUT }],
+    });
     if (valid.length > 0)
         byEvent.InstructionsLoaded = [{ hooks: [{ ...SPECLAW_HOOK }] }];
     // Covers: req~session-start-hook~1

package/dist/modules/foundation/laws.js

@@ -2,6 +2,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { z } from "zod";
 import { adaptedLaws, catalogLaws, mergeAdaptedSeed } from "./seed-laws.js";
+/**
+ * Edge kinds a `deps`/`graph` law reads when it names none: calls and
+ * imports. Compass type-reference (`ref`) edges only feed explore callers.
+ */
+export const DEFAULT_EDGE_KINDS = ["call", "import"];
 const depsRuleSchema = z.object({
     name: z.string().optional(),
     from: z.string(),

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

@@ -10,4 +10,4 @@ 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.
 The run posts status updates every `cortex.statusIntervalMinutes` minutes
-(`lawbook/config.yaml`, default 5, `0` disables, at most 60).
+(`lawbook/config.yaml`, default 0, `0` disables, at most 60).

package/dist/modules/lawbook/assets/rules/spec-reports-disciplines.md

@@ -5,6 +5,12 @@ alwaysApply: true
 
 # Spec Reports: Discipline Coverage
 
+> **Scope.** This rule governs spec-lane changes — the ones that carry a
+> `tasks.md` (level 2+, or the Cortex fan-out lane). In the default Cortex lane,
+> `speclaw ship` (or the `Stop` hook) writes the record and the report from the
+> gates' real output: do not hand-write, edit, or restructure them, and do not
+> re-run ship or archive yourself.
+
 A change's evidence of testing lives under `lawbook/changes/<name>/reports/`, as
 **one file per discipline the change actually touched**, named for that
 discipline (`<discipline>.md`) — never a single lumped report.

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

@@ -5,6 +5,12 @@ alwaysApply: true
 
 # Spec Tasks: Mandatory Steps
 
+> **Scope.** This rule governs spec-lane changes — the ones that carry a
+> `tasks.md` (level 2+, or the Cortex fan-out lane). In the default Cortex lane,
+> `speclaw ship` (or the `Stop` hook) writes the record and the report from the
+> gates' real output: do not hand-write, edit, or restructure them, and do not
+> re-run ship or archive yourself.
+
 When creating or updating a `tasks.md` inside a `lawbook/changes/<name>/`, you MUST:
 
 ## 1. Read lawbook/config.yaml first

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

@@ -1,13 +1,25 @@
 ---
 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".
+description: Cortex — One brain. Many agents. The standard way to build any change, as fast as one agent: Compass + laws as guardrails, evidence shipped by hook, extra agents only in parallel.
 ---
 
 # Cortex — One brain. Many agents.
 
-You are the **coordinator**. Do not implement product code yourself.
+One brain does the critical path; mechanical work costs no agent turns.
 
-Drive state with the `cortex` MCP tool (`status` / `start` / `advance` /
-`rework` / `brief`) or `speclaw cortex …`. Command: `/lawbook/cortex`.
+1. Branch `<type>/<slug>` (the slug is the change name).
+2. Locate with Compass (`compass_find` / `compass_explore`). Do not read
+   LAWS.md, config, standards, or `--help` to learn the process — this is it.
+3. Implement the change and its test yourself; ask the human only when blocked.
+4. Run the tests once.
+5. Stop. In Claude Code the `Stop` hook (`speclaw ship-on-stop`) records the
+   change, runs the gates once, writes the report from real output, and
+   archives level-0 work; a failing gate comes back to you. Do not run ship,
+   check the hook, or edit its output. Agents without hooks run `speclaw ship
+   <change> --summary "<what and why>"` once, last.
 
-Read `steps/01-load-or-start.md` and do only what it says.
+Never drive the harness by hand, write proposal/design/reports for small work,
+or post status updates. Review happens on the PR and never blocks you.
+
+Only when the work splits into three or more large, independent parts, read
+`steps/01-load-or-start.md` (fan-out lane: parallel agents, never a chain).

package/dist/modules/lawbook/bugfix.js

@@ -125,7 +125,7 @@ function bugfixTemplate(name, level, seed) {
         "<Run compass_impact on the confirmed root cause; list modules and call sites.>";
     return `# Bugfix: ${name}
 
-**Level:** ${level} · **Type:** bug · **Severity:** normal
+**Level:** ${level ?? "unconfirmed"} · **Type:** bug · **Severity:** normal
 
 ## 1. Observed symptom
 ${symptom}
@@ -150,18 +150,26 @@ ${blast}
 `;
 }
 /**
- * Scaffold a bug change: `bugfix.md`, `change.json`, and `reports/`.
+ * Scaffold a bug change: `bugfix.md`, `tasks.md` (level ≥ 1 or unconfirmed),
+ * `design.md` (level ≥ 2), `change.json`, and `reports/`.
+ *
+ * A supplied `level` is recorded as the confirmed level. Without one the draft
+ * stays unconfirmed: `change.json` holds the proposal and `changeType` only, so
+ * validate and Cortex treat it as level 3 until a human sets a level.
  */
+// Covers: req~bug-draft-unconfirmed~1
 export function scaffoldBugfix(projectPath, name, opts = {}) {
     const r = scaffoldChange(projectPath, name, {
         changeType: "bug",
         targets: opts.targets,
-        level: (proposal) => opts.level ?? (proposal.level !== null && proposal.level <= 1 ? proposal.level : 1),
+        level: opts.level,
         reportsReadme: `# Reports — ${name}\n\nBug reports MUST include the regression test **failing before the fix**.\n`,
         artifacts: ({ level }) => {
+            // Unconfirmed: the level-1 set (bugfix.md + tasks.md); design.md only
+            // once a level of 2 or more is confirmed.
             const lvl = level ?? 1;
             const files = {
-                "bugfix.md": bugfixTemplate(name, lvl, opts.seed),
+                "bugfix.md": bugfixTemplate(name, level, opts.seed),
             };
             if (lvl >= 1) {
                 files["tasks.md"] =