@esneiderbravo/speclaw 2.0.7 → 2.0.8

package/dist/cli/commands/cortex.js

@@ -41,6 +41,10 @@ export async function runCortex(flags) {
             note: typeof flags.note === "string" ? flags.note : undefined,
         });
         printHarnessWarnings(result);
+        // The human line goes to stderr so stdout stays one JSON document.
+        if (op === "status" && !flags.json && "summary" in result && result.summary) {
+            process.stderr.write(`  ${result.summary.line}\n`);
+        }
         console.log(JSON.stringify(result, null, 2));
     }
     catch (err) {

package/dist/modules/cortex/harness.js

@@ -11,6 +11,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { GATED_STAGES, compassGateError, compassGateWarning, evaluateCompassGate, readCompassGateMode, } from "./compass-gate.js";
+import { buildStatusSummary } from "./status.js";
 // Harness types live in the leaf `types.ts` so `compass-gate.ts` can use them
 // without importing this file back (no file-level import cycle).
 export { HARNESS_STAGES, } from "./types.js";
@@ -112,7 +113,8 @@ function allowedAdvance(from, level, verdict) {
     }
 }
 /**
- * Dispatch a harness op for a change.
+ * Dispatch a harness op for a change. `status` also returns the status
+ * summary (`req~cortex-status-summary~1`); other ops return the state.
  *
  * // Covers: req~harness-state~1
  */
@@ -120,7 +122,8 @@ export function handleHarness(args) {
     const { projectPath, change, harnessOp } = args;
     requireChangeDir(projectPath, change);
     if (harnessOp === "status") {
-        return { state: readHarness(projectPath, change) };
+        const state = readHarness(projectPath, change);
+        return { summary: state ? buildStatusSummary(projectPath, state) : null, state };
     }
     if (harnessOp === "start") {
         const existing = readHarness(projectPath, change);

package/dist/modules/cortex/register.js

@@ -8,6 +8,7 @@ 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";
+import { fitStatusResult } from "./status.js";
 export const cortexActions = [...harnessOps, "brief"];
 /**
  * Register the canonical `cortex` MCP tool.
@@ -22,7 +23,7 @@ export function registerCortex(server, opts = {}) {
             return;
         defineTool(server, { name, description, inputSchema, handler });
     };
-    add("cortex", "Cortex multi-agent loop: status, start, advance, rework, brief for a change.", {
+    add("cortex", "Cortex multi-agent loop: status with summary, start, advance, rework, brief for a change.", {
         projectPath: z.string(),
         change: z.string(),
         action: z.enum(cortexActions),
@@ -36,7 +37,7 @@ export function registerCortex(server, opts = {}) {
             const brief = briefForStage(state?.stage ?? null);
             return text(JSON.stringify({ state, ...brief }, null, 2));
         }
-        return text(handleHarness({
+        const result = handleHarness({
             projectPath,
             change,
             harnessOp: action,
@@ -44,6 +45,8 @@ export function registerCortex(server, opts = {}) {
             verdict: verdict ?? null,
             openQuestions,
             pauseForQuestions,
-        }));
+        });
+        // `text()` cuts from the end; fit `status` so `summary` and valid JSON survive.
+        return text(action === "status" && "summary" in result ? fitStatusResult(result) : result);
     });
 }

package/dist/modules/cortex/status.js

@@ -0,0 +1,197 @@
+/**
+ * Per-change status summary for Cortex `status`: stage, active role, time in
+ * stage, task progress, rework, pending verdicts, and the configured interval
+ * at which the coordinator posts status updates.
+ *
+ * Cortex must not import from the lawbook module, so task checkboxes and the
+ * `cortex.statusIntervalMinutes` key are read with local text scans, like
+ * `readCompassGateMode`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { briefForStage } from "./brief.js";
+import { stageStartedAt } from "./compass-gate.js";
+import { OUTPUT_BUDGET, estimateTokens } from "../../shared/output-budget.js";
+/** Interval used when the key is missing or invalid. */
+export const DEFAULT_STATUS_INTERVAL_MINUTES = 5;
+/**
+ * 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.
+ */
+export const MAX_STATUS_INTERVAL_MINUTES = 60;
+const CHECKBOX = /^\s*[-*]\s+\[( |x|X)\]/;
+/**
+ * Count Markdown task-list items (`- [ ]`, `- [x]`, `* [X]`). Brackets outside
+ * a list item are ignored. This is a line scan, not a Markdown parser: items
+ * inside fenced code blocks are counted, and `+` bullets and numbered
+ * (`1. [ ]`) items are not.
+ *
+ * @param text - Markdown source.
+ * @returns Checked and total item counts.
+ */
+export function countTaskCheckboxes(text) {
+    let done = 0;
+    let total = 0;
+    for (const lineText of text.split(/\r?\n/)) {
+        const m = CHECKBOX.exec(lineText);
+        if (!m)
+            continue;
+        total++;
+        if (m[1] !== " ")
+            done++;
+    }
+    return { done, total };
+}
+/**
+ * Read `statusIntervalMinutes` from the top-level `cortex:` block of
+ * `lawbook/config.yaml`. Quotes and a trailing comment are allowed. A missing
+ * file, block, or key, or any value that is not a whole number ≥ 0, yields 5.
+ * Values above 60 are clamped to 60. Never throws.
+ *
+ * This is a line scan, not a YAML parser: the key is accepted at any
+ * indentation under `cortex:` (nested maps included), and flow style
+ * (`cortex: {statusIntervalMinutes: 3}`) is not read, so it yields 5.
+ *
+ * @param projectPath - Project root.
+ *
+ * // Covers: req~cortex-status-interval~1
+ */
+export function readStatusIntervalMinutes(projectPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(projectPath, "lawbook", "config.yaml"), "utf8");
+    }
+    catch {
+        return DEFAULT_STATUS_INTERVAL_MINUTES;
+    }
+    const lines = raw.split(/\r?\n/);
+    const start = lines.findIndex((l) => /^cortex:[ \t]*(?:#.*)?$/.test(l));
+    if (start < 0)
+        return DEFAULT_STATUS_INTERVAL_MINUTES;
+    for (let i = start + 1; i < lines.length; i++) {
+        const l = lines[i];
+        // The block ends at the next column-0 key; blank and comment lines are skipped.
+        if (/^\S/.test(l) && !l.startsWith("#"))
+            break;
+        const m = /^\s+statusIntervalMinutes:\s*(\S+)/.exec(l);
+        if (!m)
+            continue;
+        const value = m[1].replace(/#.*$/, "").replace(/^(["'])(.*)\1$/, "$2");
+        if (!/^\d+$/.test(value))
+            return DEFAULT_STATUS_INTERVAL_MINUTES;
+        return Math.min(Number(value), MAX_STATUS_INTERVAL_MINUTES);
+    }
+    return DEFAULT_STATUS_INTERVAL_MINUTES;
+}
+function readTaskCounts(projectPath, change) {
+    const dir = path.join(projectPath, "lawbook", "changes", change);
+    for (const file of ["tasks.md", "record.md"]) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, file), "utf8");
+        }
+        catch {
+            continue;
+        }
+        return countTaskCheckboxes(text);
+    }
+    return null;
+}
+function elapsedSince(startedAt, now) {
+    if (!startedAt)
+        return null;
+    const t = Date.parse(startedAt);
+    if (Number.isNaN(t))
+        return null;
+    return Math.max(0, Math.floor((now.getTime() - t) / 60000));
+}
+/**
+ * Build the status summary of a running change from its harness state, its
+ * task list, and the configured status interval.
+ *
+ * @param projectPath - Project root.
+ * @param state - Harness state of the change.
+ * @param now - Clock for `elapsedMinutes`; injectable for tests.
+ * @returns The structured summary and its one-line English rendering.
+ *
+ * // Covers: req~cortex-status-summary~1
+ */
+export function buildStatusSummary(projectPath, state, now = new Date()) {
+    const role = briefForStage(state.stage).role;
+    const startedAt = stageStartedAt(state);
+    const elapsedMinutes = elapsedSince(startedAt, now);
+    const tasks = readTaskCounts(projectPath, state.change);
+    const pendingVerdicts = [];
+    if (state.level >= 1 && state.verdicts.review !== "PASS")
+        pendingVerdicts.push("review");
+    if (state.verdicts.test !== "PASS")
+        pendingVerdicts.push("test");
+    const openQuestions = state.openQuestions.length;
+    const parts = [
+        state.change,
+        role ? `${state.stage} (${role})` : state.stage,
+        elapsedMinutes === null ? "elapsed n/a" : `${elapsedMinutes}m in stage`,
+        tasks ? `tasks ${tasks.done}/${tasks.total}` : "tasks n/a",
+        `rework ${state.iteration}/${state.maxRework}`,
+        `pending: ${pendingVerdicts.length ? pendingVerdicts.join(", ") : "none"}`,
+    ];
+    if (state.stage === "questions") {
+        parts.push(`waiting on human: ${openQuestions} question(s)`);
+    }
+    return {
+        change: state.change,
+        stage: state.stage,
+        role,
+        stageStartedAt: startedAt,
+        elapsedMinutes,
+        tasks,
+        iteration: state.iteration,
+        maxRework: state.maxRework,
+        pendingVerdicts,
+        openQuestions,
+        statusIntervalMinutes: readStatusIntervalMinutes(projectPath),
+        line: parts.join(" · "),
+    };
+}
+/**
+ * Fit a `status` result into the brief MCP output budget without ever cutting
+ * `summary`. `text()` truncates a payload from the end, which would yield
+ * invalid JSON and lose whatever comes last; this keeps the payload under the
+ * budget instead, by dropping the oldest `state.history` entries (newest
+ * kept) and recording how many were dropped in `historyOmitted`. If an empty
+ * history still does not fit, `state` becomes `null` with `stateOmitted`.
+ * Only the MCP rendering is trimmed: `harness.json` and the CLI keep the full
+ * history.
+ *
+ * @param result - The `handleHarness` `status` result.
+ * @param maxTokens - Token ceiling; defaults to the brief output budget.
+ * @returns A result whose pretty-printed JSON fits `maxTokens`.
+ *
+ * // Covers: req~cortex-status-summary~1
+ */
+export function fitStatusResult(result, maxTokens = OUTPUT_BUDGET.brief) {
+    const fits = (value) => estimateTokens(JSON.stringify(value, null, 2)) <= maxTokens;
+    const { summary, state } = result;
+    const full = { summary, state };
+    if (!state || fits(full))
+        return full;
+    const history = state.history;
+    const keepLast = (k) => ({
+        summary,
+        historyOmitted: history.length - k,
+        state: { ...state, history: k > 0 ? history.slice(-k) : [] },
+    });
+    // Fitting is monotone in the number of kept entries: binary-search the most.
+    let lo = 0;
+    let hi = history.length - 1;
+    if (!fits(keepLast(0)))
+        return { summary, stateOmitted: true, state: null };
+    while (lo < hi) {
+        const mid = Math.ceil((lo + hi) / 2);
+        if (fits(keepLast(mid)))
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return keepLast(lo);
+}

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

@@ -9,3 +9,5 @@ explorer → planner → implementer → reviewer → tester → archiver. Drive
 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).

package/dist/modules/lawbook/assets/skills/cortex/steps/01-load-or-start.md

@@ -22,4 +22,31 @@ Stage → role:
 | archiving | archiver (`sync` + `archive`) |
 | done | stop — report success |
 
+## Status updates
+
+- Read `summary.statusIntervalMinutes` from the `status` result (after
+  `start`, run `status` once). `0` disables unsolicited updates; never parse
+  `lawbook/config.yaml` yourself.
+- Create the timer only when the summary is non-null and the stage is not
+  `done`, the interval is greater than 0, and the host has a session timer
+  (Claude Code `CronCreate`, session-only, at least 1 minute). Then create
+  **one** recurring timer every `statusIntervalMinutes` minutes:
+  - schedule: for 1–59 minutes use `*/N * * * *`; for 60 (the engine caps the
+    interval at 60) use an hourly expression such as `7 * * * *`;
+  - prompt: the timer firing is a fresh prompt, so it must carry its context.
+    Name the change and the rules: run `cortex` action `status` for that
+    change and post the update in the session's language; skip the ping while
+    the stage is `questions`; when the stage is `done` or the run was stopped,
+    delete this timer (`CronDelete`) and post nothing.
+- Remember the id that `CronCreate` returns; it is the run's status timer.
+  Before creating one, check that no status timer exists for this change
+  (your remembered id, or `CronList`), so there is exactly one per run.
+  `CronDelete` always targets that id.
+- Create the timer only inside a Cortex run, never a second one per run, and
+  none when the interval is 0.
+- Prefer background role dispatch: the timer fires only while the session is
+  idle, not during a blocking dispatch.
+- On a host without a session timer, the after-op and before-dispatch updates
+  of the dispatch loop stand in for it.
+
 Next: read `steps/02-dispatch-loop.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/cortex/steps/02-dispatch-loop.md

@@ -34,5 +34,20 @@ For the current Cortex stage (`cortex` action `brief` or `status`):
 4. Max rework is 3; if the engine rejects further rework, **ask the human**.
 5. Coordinator never edits `src/`, never archives, never pushes, never runs
    `laws accept`.
+6. **Status updates.** Unless `summary.statusIntervalMinutes` is 0, post a
+   compact update after every Cortex op and just before every blocking role
+   dispatch, built from the `status` summary fields:
+   - the change, the stage and active role, the elapsed time in the stage;
+   - tasks done/total, rework iteration/max, and the pending verdicts;
+   - in `questions`, that the human owes answers.
+
+   Write it in the session's language (the language of the human's most
+   recent messages); keep stage, role, and tool names, file paths, and change
+   names in English. `summary.line` is English-only; use it as is only in an
+   English session. Skip timer pings while the stage is `questions` (the
+   question round already speaks to the human). When the human asks to stop
+   the updates, delete the timer (`CronDelete` with the id `CronCreate`
+   returned) and post no further unsolicited update for this run. An explicit
+   request for status is always answered.
 
 Next: read `steps/03-complete.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/cortex/steps/03-complete.md

@@ -1,6 +1,8 @@
 # Complete
 
-When Cortex stage is `done` (or the human stops the run), summarize:
+When Cortex stage is `done` (or the human stops the run), first delete the
+status timer if one exists (`CronDelete` with the id `CronCreate` returned,
+or the id `CronList` shows for this change), then summarize:
 
 - Change name and final stage
 - Review/test verdicts and iteration count

package/dist/modules/lawbook/change-tool.js

@@ -6,6 +6,7 @@ import { scaffoldFeature } from "./scaffold-change.js";
 import { buildCoverageReport, loadCoverageConfig, renderCoverageAgent } from "./coverage.js";
 import { buildDriftReport, renderDriftAgent } from "./drift.js";
 import { handleHarness, harnessOps } from "../cortex/harness.js";
+import { fitStatusResult } from "../cortex/status.js";
 export const lawbookChangeActions = [
     "init",
     "list",
@@ -111,7 +112,7 @@ export function handleLawbookChange(args) {
             if (!args.harnessOp) {
                 throw new Error(`lawbook_change: action 'harness' requires 'harnessOp'`);
             }
-            return handleHarness({
+            const result = handleHarness({
                 projectPath: args.projectPath,
                 change: requireField(args, "change"),
                 harnessOp: args.harnessOp,
@@ -120,6 +121,8 @@ export function handleLawbookChange(args) {
                 pauseForQuestions: args.pauseForQuestions,
                 note: args.note ?? args.reason,
             });
+            // MCP-only path: fit `status` to the output budget like the `cortex` tool.
+            return args.harnessOp === "status" && "summary" in result ? fitStatusResult(result) : result;
         }
         default:
             throw new Error(`lawbook_change: unknown action '${String(args.action)}'`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "2.0.7",
+  "version": "2.0.8",
   "publishConfig": {
     "access": "public"
   },