Release history

Changelog

Every published version of @esneiderbravo/speclaw, newest first. The source is CHANGELOG.md in the library’s repository.

  1. 2.1.1

    Latest

    Fixed

    • harness.json no longer stamps every stage with the same second. Ship (and the Stop hook) writes each stage with the time its evidence shows: exploring at the first Compass lookup or edit since the branch was created, implementing at the first edit, planning when the level was confirmed, and testing/archiving from the gates' own run — never earlier than the entry before it. At level 1+ the stop records the work up to implementing; the review verdict stays with the PR.
  2. 2.1.0

    Removed — BREAKING

    • The 20 retired MCP tool aliases are gone: compass_search, compass_recall, compass_impact, compass_trace, compass_affected_tests, compass_hotspots, compass_coupling, compass_watch, lawbook_init, lawbook_list, lawbook_validate, lawbook_sync, lawbook_archive, lawbook_level, lawbook_coverage, lawbook_drift, init_project, configure_agent, list_packs, add_pack. Only the nine canonical tools register. A client calling a removed name gets "tool not found": run speclaw update and speclaw doctor, which lists every project file (now including ai-specs/skills and ai-specs/agents) that still names one, with its canonical call.
    • lawbook_change action harness and speclaw lawbook harness: use the cortex tool or speclaw cortex.
    • SPECLAW_NO_ALIASES no longer does anything.

    Added

    • cortex action brief at stage reviewing exports the branch diff to .speclaw/review/<change>.diff and returns a bounded review prompt: read the diff once, one compass_diff_context, changed hunks only, a ≤ 40-line review.md and a checklist of the defect classes reviews have caught. The reviewer agent follows the same procedure and pins no model, so it works in any agent. Measured with planted defects: 35 s median vs 66 s on 2.0.25, every defect caught, and a clean change passes 3/3 (2/3 on 2.0.25).
    • A failing test run (PostToolUseFailure, or a piped run whose output shows failures) points the agent at lawbook_investigate with the output as stackTrace.

    Changed

    • The stop no longer re-runs tests the agent already passed: the edit hook records green test runs, and the stop skips the planned test files a run covered after the last edit (same setup step, no name filter). The report cites that run and its output.
  3. 2.0.25

    Fixed

    • The edit hook tells a change's level while the agent works, not first at the stop: a diff that only grew is told from its last measurement (a floor for its level), and one background measurement runs at a time. Before, an agent adding files faster than a ~20 s measurement landed was never told.
    • HTTP endpoints count as a public API: changed route declarations (NestJS, Spring, FastAPI/Flask, Express-style routers, Go, Next.js route handlers), DTO code and contract files (OpenAPI, proto, GraphQL) raise the level, and at level 1+ owe reports/api.md.
    • Entry points come from the project's own package.json (main, bin) for the level signal and the Compass map; speclaw's own src/server.ts and src/cli/index.ts are no longer assumed in every repo.

    Changed

    • At level 2+, tests spanning several packages run one gate per package and ship writes one report per discipline (backend.md, frontend.md, e2e.md…) instead of one lumped change.md.
    • The Stop hook ends every ship with a one-line systemMessage for the user: the gates and their times, then the archive or what is left. Run speclaw update to reinstall the hook command that keeps its stdout.
  4. 2.0.24

    Fixed

    • Archiving no longer reads as new work: the Stop hook ignores the canonical specs an archive promotes (lawbook/specs/) and the anchors it seals (lawbook/anchors/), as it already ignored lawbook/changes/. Before, the stop after an archive re-ran every gate (~100 s) and rewrote the archived report.

    Changed

    • npm test runs the suite in parallel without coverage (~43 s, was ~90 s), so the agent's targeted runs and the Stop hook's gate stay fast; the coverage-gated serial suite moved to npm run test:ci, which CI and publish run.
  5. 2.0.23

    Changed

    • The Stop hook runs the gates once, on what the diff reaches: its test gate (npm test, npm run test, or the pnpm/yarn equivalent) runs only the test files the branch diff reaches and the report names that scope; the full suite runs in CI. It falls back to the full suite with no Compass index, a global file, or changed code no test reaches; ship.tests: full in lawbook/config.yaml keeps the full suite at the stop.
    • Generated CLAUDE.md, AGENTS.md and testing standards tell the agent to run only the tests covering its change and leave the gates to the hook; they used to tell it to run the full gates too, so the suite ran twice.
    • A diff of at most one source file and ten lines (tests and docs aside), with no public API or global file, measures level 0 however central the code it touches. In real agent runs these changes took speclaw from 1.37–1.80× an agent alone to 0.65–1.24×, with the same quality.

    Fixed

    • lawbook_change accepts the arguments agents actually send: archive dates the folder today when no date is given; archive and level-0 ship sync an unsynced delta themselves instead of refusing; validate, sync, archive, ship, level set/promote and harness infer the change when it is left out (the only active change, else the branch's); name reads as change; action create/new drafts; a comma-separated paths is a list. In real sessions these accounted for most of the 11 % of speclaw calls that failed and cost the agent a retry.
    • compass_explore given a search phrase and no node answers as a find instead of a validation error.
    • cortex on an undrafted change says to draft it first and lists the active changes.
  6. 2.0.22

    Fixed

    • A re-index no longer reads as the agent's work: the Stop hook ignores docs/compass.md when it differs from the merge base only inside its generated map block (line endings normalized), so a fresh branch no longer archives an empty change and a branch with work does not reship.
  7. 2.0.21

    Fixed

    • The documentation hint no longer stalls the agent on large diffs. It measured the branch diff inside the PostToolUse hook: on a 47-file change in a 1,211-file repo that took 12.9 s against the hook's 5 s timeout, so Claude Code cancelled it, the level-3 hint was lost, and the stop measured the same diff again. The hook now answers in ~35 ms and starts speclaw measure-diff in the background; the hint arrives on a later call (~14 s in that repo), ship reuses the cached measurement (stop overhead 12.6 s → 0.24 s), and a level counts as told only when its hint is returned.
    • The Compass nudge strips shell quotes and escapes from a searched pattern (rg "foo\" suggested compass_find "foo\").
  8. 2.0.20

    Fixed

    • The Stop hook sizes every change from its branch diff. It created each change with no targets, so the level was never measured and every change — multi-module fixes included — was archived at level 0 with no tasks, delta specs, proposal or design, and a record that only listed file names (wrongly "confirmed by: human"). Ship now measures the diff (a version-only bump of package.json does not count), records the level as measured, raises it when the diff grows (reopening a level-0 archive the branch outgrew, never one already merged), and lists what that level owes before any gate runs: the why — the branch's commit bodies count — checked tasks, the delta spec, proposal and design. The gates still run once. A PostToolUse hook names what the level owes as soon as an edit raises the diff to level 1+, so the agent writes it in the same turn instead of after a blocked stop. Level 0 never waits: its record takes the commit bodies, else the file list, so a trivial fix costs no extra turn.
    • A file counts as a hotspot only with 3+ commits in the window. The score is relative to the hottest file, so in a young repo any file was "the hottest" and a one-line fix scored level 1.
    • minimal projects kept their hooks but not the tool they call: speclaw_check was omitted from the minimal profile, so every law hook and the Compass-first nudge answered "Tool not found". Minimal now keeps speclaw_check and lawbook_investigate.
    • The Compass-first nudge also watches Bash: cat, sed, head, grep, rg and friends on indexed code get the same hint as Read/Grep/Glob (agents read through the shell far more often). Heredoc writes stay silent, and so does a repo under 40 indexed files, where a read beats a graph query (the index now records its totals in .speclaw/index-stats.json).
    • lawbook_investigate ranks only code the failing test reaches. It walks the call graph from the hinted test file or the trace's test frame, marks leaf computations, never lists the test itself or runtime frames, and returns 5 suspects by default; before, look-alike helpers anywhere in the repo outranked the real cause and a long result was cut mid-JSON.
    • Stack-trace paths resolve under a symlinked project root (macOS /tmp), where the runtime prints the real path.

    Added

    • compass_explore with maxDepth > 1 (and include: ["callees"]) returns the whole callee chain with each symbol's source, and to: <symbol> returns the path's sources: one call reads what took one file read per hop.
    • The MCP server sends instructions naming the tool for each job, and compass_find, compass_explore, compass_diff_context and lawbook_investigate load up front (_meta["anthropic/alwaysLoad"]), so agents no longer pay a tool-search turn before using them. Tool descriptions say when to use each tool.

    Changed

    • Ceremony cuts default to [5, 16, 25] (was [3, 8, 15]) and a public-API change weighs 5 (was 4), measured against this repo's last twelve PRs: a cross-module fix or any public-API change is level 1, a multi-module feature level 2, a sweeping refactor level 3. Projects whose lawbook/config.yaml sets cuts keep their values.
    • scripts/bench-workflow.sh installs the Stop hook in its Cortex fixture (speclaw agent add claude; since 2.0.16 init configures no IDE folder, so "Cortex" runs measured an agent alone), runs on macOS bash 3.2, and adds a two-module scenario. Results: docs/benchmarks/cortex-speed.md.
  9. 2.0.19

    Fixed

    • The Stop hook no longer re-ships work that was only committed. A branch that added new files changed its fingerprint on commit (the files moved from the untracked hash into the diff), so the next turn re-ran every gate and rewrote the archived report with nothing but new timings. Files now hash by name and contents whether untracked, staged or committed, and the report's file list includes new files before they are committed.
    • Every branded command, not only speclaw init, matches its palette to the terminal background, so speclaw update, doctor, ship and the rest are legible on light terminals.
  10. 2.0.18

    Fixed

    • The CLI is legible on light terminals. speclaw init detects the terminal background (an OSC 11 query, then the macOS appearance) and switches to a light palette whose every color holds at least 4.5:1 on white; before, the ink palette's text and cyan were near-invisible there. SPECLAW_THEME=light or dark forces a theme, and COLORFGBG is honored by every command.
  11. 2.0.17

    Fixed

    • The Stop hook (speclaw ship-on-stop) no longer re-ships work that was only committed: its fingerprint is the branch's diff against the merge base, not HEAD. Before, every commit after a ship looked like new work and rewrote the change's (archived) report.
    • The hook ships the change last shipped by name on the branch (speclaw ship <name>) instead of always the one named after the branch, so a second change on a branch no longer has its work written into the first change's archived report. The .speclaw/ship-last marker now records the branch and change; an older fingerprint-only marker still works.
    • Editing an untracked file counts as new work: the fingerprint hashes the contents of untracked files, not just their names.
  12. 2.0.16

    Fixed

    • A default speclaw init (only .agents/) now registers the speclaw MCP server in .mcp.json (gitignored). Before, the generic agent had no MCP entry, so a freshly initialized repo had no Compass or lawbook tools and the agent contract (Compass first) could not be followed.
    • speclaw agent add <id> and the configure-agent setup action now install the agent's hooks too (Claude Code: SessionStart, PostToolUse, Stop), recording the settings baseline so a later update treats it as speclaw's own. Before, adding Claude Code after init left it without the session-start reindex, the edit reindex, and the ship-on-stop hook, so finished work was never recorded in the lawbook.
    • The lawbook/config.yaml written by init no longer fails a host repo's prettier --check .: the EARS vagueWords list is emitted in the wrapped form Prettier produces, and still loads the same words.
    • change.json, harness.json, and spec anchor files are written in the layout Prettier gives them (short arrays on one line), so a committed lawbook/ stays green under prettier --check ..
    • .gitignore entries that share a comment (e.g. one agent's links) join one block instead of repeating the comment for every entry.

    Changed

    • The generated block in AGENTS.md now states the agent workflow — Compass first, Cortex for every change, the Stop hook (or speclaw ship) to record it in the lawbook — when the hand-written part of the file doesn't. update never edits the personalized AGENTS.md, so projects scaffolded before Cortex, or with a hand-written AGENTS.md, never learned to record their work.
  13. 2.0.15

    Fixed

    • speclaw init no longer asks which agents to use: it always creates only .agents/ (other folders via --agents or speclaw agent add).
    • A bare .claude/ or .cursor/ (created by Claude Code or Cursor on their own) is no longer taken as a configured agent, so update stops filling it with links, settings.json and rules/speclaw. An agent counts as configured only when its folder holds a speclaw link into ai-specs/.
    • When an explicitly chosen agent's folder already existed, the entries speclaw writes in it (links, rules/speclaw, a new hooks file) are now gitignored one by one.
  14. 2.0.14

    Changed

    • speclaw init creates a single agent-facing folder by default: .agents/, with symlinks to ai-specs/ (skills, commands, agents, rules). ai-specs/ stays the source of everything. .claude/, .cursor/, .codex/, .windsurf/ and .github/instructions/ are created only for an agent chosen explicitly (--agents claude, speclaw agent add cursor, …). Existing installs keep their folders.
    • Tool config is no longer committed: init adds .agents/ (and any agent folder it creates) and speclaw.lock to .gitignore, next to ai-specs/ and .speclaw/. Only the project's content is committed: LAWS.md, CLAUDE.md, AGENTS.md, docs/, and lawbook/.

    Removed

    • init no longer writes .github/workflows/speclaw.yml; the CI workflow template is gone.

    Fixed

    • speclaw drift --reseal re-stamps only the anchors whose sealed state changed. Unchanged anchors keep their archivedAt / commitSha, so an unchanged capability stays byte-identical and drift age counts from the real seal. On this repo a full reseal went from ~6,000 changed lines in 15 files to 6 lines in 1 file.
  15. 2.0.13

    Changed

    • Cortex is as fast as one agent: one brain does the critical path and the installed 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. Measured: 18.1 s median vs 15.8 s for an agent alone on the same bug, down from 74–154 s (docs/benchmarks/cortex-speed.md). Extra agents run only in parallel for large independent parts; review happens on the PR. Cortex status updates are off by default.

    Added

    • speclaw ship <change> / lawbook_change action ship: one call for finished work. It never records a review verdict.
    • scripts/bench-workflow.sh: reproducible agent benchmark.

    Fixed

    • compass_find (and the compass_search / compass_recall aliases) returns one compact JSON document that always parses and fits maxTokens as a whole (default 1500): hits carry only name, kind, file, line (no node ids, signatures, ranking signals, or route); tokens counts the emitted text; truncated: true appears only when hits, rendered blocks, nearest entries, or entries of focusIgnored / focus / terms were removed (a cut list reports its original length in focusIgnoredTotal / focusTotal / termsTotal), so a worktree with many changes or a long exact query no longer overflows the cap. speclaw search|recall --json keep their shape.
    • compass_explore and compass_diff_context with mode: "full" are no longer cut at the brief ceiling, and a full-mode truncation hint no longer tells you to use mode:"full". text() gains an opt-in budget (an output mode or { maxTokens }); its default stays brief.
    • Search focus keeps only indexed files: unindexed worktree changes and explicit focus paths no longer switch the budget and personalization to the focused defaults; compass_find lists them in focusIgnored.
    • Exact compass_find answers whether a name exists: hits are only symbols named exactly a query term (alpha beta is an OR, reported as terms); a missing name returns found: false, empty hits, and up to five nearest names.
    • Types now have callers: TS/JS type annotations and extends/implements clauses become ref edges, resolved only through the file's import binding or a same-file definition. compass_explore and speclaw explore list them with via: "ref" (calls carry via: "call"); impact, affected tests, PageRank, hotspots, coupling, the map, visualize, and deps/graph laws ignore them. Compass schema 12: the first index after upgrading re-extracts every file once (embeddings reused); speclaw 2.0.12 or older rebuilds a schema-12 index from scratch, so pin every speclaw and the MCP entry to 2.0.13.
    • speclaw lawbook draft --bug (and lawbook_change action draft with bug: true) without a level no longer confirms its own level: change.json carries no confirmedLevel/confirmedBy/confirmedAt, bugfix.md says Level: unconfirmed, and validate applies level-3 bug rules until a level is set.
    • Cortex advance and rework re-read the confirmed level from change.json (unconfirmed → 3), so a level set after start takes effect and an unconfirmed change never skips planning. pauseForQuestions outside stage planning is rejected with an error (exit 1 on the CLI) instead of advancing and dropping the questions.
    • An empty target set proposes no level (level: null, degraded: ["no-targets"]) instead of a measured level 0, and lawbook_change action level mode set / promote without paths or symbols keeps the proposal already stored in change.json. promote on a change with no confirmed level is rejected ("use mode 'set'") instead of recording a promotion from an undefined level.
    • A generic type parameter (<Props>) now hides a same-named type only inside its own declaration, not across the whole file.
  16. 2.0.12

    Fixed

    • speclaw laws scan and speclaw verify keep reporting injection findings when speclaw.lock is unreadable. laws scan names the lock error and exits 1; laws scan --json now exits 1 on a lock error or an error finding, like the text mode, and adds a lockError field.
    • --question on speclaw cortex advance (and lawbook harness) is truly repeatable: each flag is one open question, and commas no longer split it.
    • speclaw doctor suggests git checkout HEAD -- speclaw.lock for an unreadable lock, which also works during a conflicted merge.
  17. 2.0.11

    Added

    • Compass re-indexes each file an agent edits. For Claude Code, init / update add one PostToolUse command hook on Write|Edit|MultiEdit|NotebookEdit that runs the new speclaw reindex-file: it reads the hook payload from stdin, hands the edited path to a detached child and exits 0 at once (about 60 ms), silent, offline, and never logged as a Compass call. New symbols are findable mid-session without a manual compass_index. Binary resolution matches the session-start hook; an older speclaw rejects the unknown command and touches nothing. Hooks you added to PostToolUse are kept.
    • speclaw reindex-file <paths…> re-indexes specific files in the foreground. Per-file runs skip PageRank, cache eviction and the docs/compass.md map; they mark the index so the next full speclaw index (or session start) does the full pass.

    Fixed

    • Editing a file no longer drops or misattributes its cross-file callers in compass_impact / trace: edges are detached before a file's nodes are replaced, so a reused node id can't point at the wrong symbol.
    • A full speclaw index no longer fails or drops a file when a per-file reindex writes concurrently; it takes the write lock before reading stored state, keeps rows the walk would still yield, and always closes its connection on a busy lock. Removed files also drop their file-level coverage links.

    Changed

    • Existing installs see .claude/settings.json as refreshedDiverged once on speclaw update, as the reindex hook group is added.
  18. 2.0.10

    Fixed

    • Affected tests now find the tests that actually exercise a symbol. Calls inside test(...) / it(...) callbacks and imports in files with no declarations are owned by a hidden per-file node, multi-line imports are parsed in full, and tsconfig/jsconfig paths and baseUrl aliases resolve (nearest config, relative extends, JSONC). Pure re-export barrels (export * from …, Nx-style libraries) resolve too.
    • Method calls on package receivers (path.parse(), _.map()) and global builtins (test, fetch) no longer bind to same-named project functions, so they stop producing false callers, impact dependents, and coupling pairs. A receiver counts as a package only when its import does not resolve to a project file.
    • compass_explore callees list only resolved symbols; unresolved names are summarized in unresolvedCallees (count and sample) instead of crowding out real callees.
    • The affected-tests command is never a run-nothing command: it is null with a commandReason when nothing is affected. The runner is detected per nearest package.json (vitest, jest, node --test, inherited from a hoisted root), workspace-spanning selections get per-workspace commands, and node --test commands drop coverage flags and keep flag values.
    • Edges that pointed at deleted nodes after a file was re-extracted are reset and re-resolved, so compass_impact / trace no longer lose callers.

    Changed

    • Compass schema 11 (edges.is_member, edges.spec). The first speclaw index after upgrading migrates 10→11 and re-extracts every file once, reusing embeddings. A speclaw ≤2.0.9 (including a pinned MCP entry) rebuilds a schema-11 index from scratch — run speclaw update so the pinned MCP entry moves to 2.0.10.
    • Calls on local variables and parameters (svc.run()) no longer produce callers; impact and affected-test counts may rise because the graph is now accurate.
  19. 2.0.9

    Added

    • speclaw update upgrades itself. When npm reports a newer release during the run, it re-executes as npx -y @esneiderbravo/speclaw@<latest> update with the same flags (also in CI and on a non-TTY), so the latest release applies its own migrations, and exits with that run's code. It migrates with the installed binary instead when you opt out (--no-self-update or SPECLAW_NO_SELF_UPDATE=1), when the registry is unreachable (a cached version only), or when npx cannot be started. init still only advises.
    • --help / -h on every command prints that command's usage to stdout and exits 0. It writes nothing, contacts no registry, and starts no server or watcher (before, speclaw init --help ran init and speclaw mcp --help started a server).
    • speclaw laws lock --force lists each drifted strict file with its locked and on-disk digests, asks for confirmation (default No), then re-baselines them and records an accepted[] entry for each (--note adds the reason). Interactive TTY only: without a TTY, when declined, or when a file changed while the prompt was open, it exits 1 and leaves the lock untouched.

    Changed

    • The agent MCP entry is pinned to the installed version (npx -y @esneiderbravo/speclaw@<version> mcp) by init, agent add, and update. On the first speclaw update, an existing stock (unpinned) entry is re-pinned; a custom entry (e.g. a local node path) is kept.
    • The lawbook_change action archive result reports harnessCompleted, and the cortex MCP tool's status and brief read an archived change instead of failing. start, advance, and rework on an archived change are rejected without writing.

    Fixed

    • Security: a lock refresh (init, update, laws compile, laws lock) no longer re-baselines a strict file (CLAUDE.md, AGENTS.md, compiled rules) edited outside speclaw. The drifted file keeps its locked digest and the command warns run speclaw laws accept <path>, so verify keeps failing until a human accepts it. Clean and new strict files and advisory files are refreshed as before, and stale accepted[] entries are pruned.
    • An existing speclaw.lock that cannot be read (merge-conflict markers, a newer lockfileVersion, or valid JSON with the wrong structure) is never rebuilt: every refresh leaves it byte-identical and reports the error, and init, update, laws compile, laws lock, and laws accept exit 1. speclaw doctor suggests repairing or restoring it from git rather than a bare laws lock.
    • Archiving a change completes its Cortex harness. The archive moves the harness from archiving to done (one history entry) before it moves the change directory, and restores it if the move fails; the cortex skill and the archiver agent no longer call advance after an archive (it failed once the change had moved). The six archived changes of 2026-10-06 left stuck in archiving are repaired to done.
  20. 2.0.8

    Added

    • Cortex status summary. The cortex MCP tool's status action and speclaw cortex status return a summary before state: the stage, the active role, whole minutes in the stage, tasks done/total (from the tasks.md checkboxes, or record.md at level 0), the rework iteration/max, the pending verdicts, the open-question count, the configured interval, and a one-line English line. summary is null when the change has no harness yet. The MCP input schema is unchanged.
    • speclaw cortex status also prints summary.line to stderr; stdout stays one JSON document, and --json suppresses the stderr line.
    • Coordinator status updates. During a Cortex run the cortex skill posts a compact update after every Cortex op and before every blocking role dispatch, in the session's language (stage, role, and tool names, paths, and change names stay in English). Where the host has a session timer (Claude Code CronCreate) it also keeps exactly one recurring timer per run, skips pings while the run waits on the human's answers (questions), and deletes the timer at done, when the run stops, or when the human asks to stop.
    • cortex.statusIntervalMinutes in lawbook/config.yaml sets the update interval: default 5, 0 disables every unsolicited update, values above 60 are capped at 60, and a missing or invalid value means 5.

    Changed

    • On the MCP path (cortex and the deprecated lawbook_change harness alias), status is fitted to the output budget so the JSON stays valid and summary stays complete: the oldest state.history entries are dropped and counted in historyOmitted (state becomes null with stateOmitted if even an empty history does not fit). The CLI and harness.json keep the full history.
  21. 2.0.7

    Added

    • Session-start refresh for Claude Code. speclaw init / speclaw update add one SessionStart command hook (matcher startup|resume|clear|compact, 30 s timeout) that runs the new speclaw session-start command. It resolves the binary as node_modules/.bin/speclaw → speclaw on PATH → npm_config_update_notifier=false npm_config_offline=true npx --no-install @esneiderbravo/speclaw, so it never contacts a package registry. It is silent, always exits 0, and skips when .speclaw/index.db is absent — the first build stays compass_index / speclaw index. An older speclaw on PATH rejects the unknown command and touches nothing. Hooks you added to SessionStart are kept.
    • speclaw session-start refreshes an existing index without writing to the Compass call log, the branded header, or the update notice.

    Changed

    • speclaw index takes a no-op fast path when nothing changed (no file re-extracted or removed, root hash unchanged, no --force, --prune, or explicit --max-cache-mb): it skips dir_hashes, edge and import resolution, PageRank, and embedding-cache upkeep, still advances indexed_at, and leaves docs/compass.md alone unless its map block is empty. On this repo the unchanged-index median drops from ~385 ms to ~205 ms (M1 Max, Node 24).
    • Existing installs see .claude/settings.json as refreshedDiverged once on the first speclaw update, as the SessionStart group is added.

    Fixed

    • compass_explore returns the exact symbol source. It sliced the file as UTF-8 bytes with UTF-16 offsets, so any multibyte character before a symbol (—, «», ñ, emoji) shifted the snippet early and cut its end. Stored data was never affected: no reindex, schema bump, or drift reseal needed.
  22. 2.0.6

    Changed

    • The brand follows the speclaw site's design tokens. The CLI palette, the Compass HTML viewer, and every asset under brand/ take the dark ink theme (paper #131313, ink #f4f4f3, signal #00e3fd, deny #ff5c47); the light banner and mark take the bond theme (signal #00707f). Green and amber stay for success and warning, re-tuned to at least 4.5:1 on #131313. The c.* helpers keep their names.
    • The brand SVGs draw the site mark (a document whose last line, the law, runs past the page edge) and set text in Chivo / Chivo Mono instead of SF Mono / JetBrains Mono. The README badges use the bond signal (00707f on 131313).
    • npm run brand renders the PNGs with Chivo loaded from the new dev dependencies @fontsource/chivo and @fontsource/chivo-mono (decoded from WOFF2 by the dev dependency wawoff2), never from system fonts. A missing font file stops the render with a non-zero exit that names the file. None of these ship in the published package.
  23. 2.0.5

    Changed

    • The Publish to npm workflow also pushes the v<version> tag and creates the GitHub release from the version's CHANGELOG.md section. It skips a tag or release that already exists and fails before tagging if the section is missing.

    Fixed

    • speclaw.lock no longer pins the .claude/rules/speclaw symlink (it points into the gitignored ai-specs/), so speclaw update stops flipping symlinks between {} and that entry depending on whether the link exists locally. Locks written by older versions that still pin it only warn in speclaw verify when the link is missing or retargeted, instead of failing clean CI clones with "Managed symlink missing". The next speclaw update or speclaw laws lock drops a legacy entry once; after that the lock stays stable. Other managed symlinks still fail verify.
  24. 2.0.4

    Added

    • Compass-first evidence gate. cortex advance out of exploring or implementing checks for Compass calls (explore, find, diff-context and their aliases; compass_index does not count) logged to .speclaw/compass-calls.jsonl since the stage started. compassGate: off|warn|strict in lawbook/config.yaml (default warn); strict rejects the advance without touching harness.json.
    • Compass-first nudge: a PostToolUse Read|Grep|Glob hook adds context telling the agent to use compass_find / compass_explore when it reads indexed code without a recent Compass call. Context only — never a permission decision — and reads no longer evaluate laws.
    • speclaw lawbook draft <name> [--level N] [--capability C] and the lawbook_change action draft scaffold a feature change that validates out of the box. Placeholder deltas are refused by sync.
    • compass_index / speclaw index report graph totals and a nextStep.
    • scripts/bench/compass-first.mjs benchmarks main vs a branch (micro and headless agent runs, each against its own build).

    Changed

    • Packaged skills, agents, commands, rules and templates name only canonical MCP tools. The explore skill locates with compass_find first and indexes only when that returns nothing; the Cortex skill dispatches the explorer with symbols and questions and batches all human questions into one round.
    • Existing installs show the updated hooks as refreshedDiverged on speclaw update.
  25. 2.0.3

    Fixed

    • compass_explore and search resolve a repo-relative file path to a symbol in that file. An exact symbol name still wins. A path such as src/foo.ts no longer returns zero similar symbols.
  26. 2.0.2

    Changed

    • Cortex planning reuses a complete explorer brief. The packaged explore, cortex, and draft skills, and the planner agent, no longer tell the planner to re-locate the code or re-read standards the brief already covered. speclaw update refreshes ai-specs/skills and ai-specs/agents from this package.
  27. 2.0.1

    Fixed

    • speclaw update no longer runs npm install -g. It only applies project migrations and prints an advisory if a newer binary exists on npm (upgrade the CLI separately via npm i -g or npx @esneiderbravo/speclaw@latest).
  28. 2.0.0

    Added

    • Cortex (*One brain. Many agents.*) — multi-agent coordination module: durable harness.json, MCP tool cortex (status / start / advance / rework / brief), CLI speclaw cortex, skill /lawbook/cortex, and role agents (explorer → planner → implementer → reviewer → tester → archiver).
    • Archive gates on harness review/test verdicts; build skill hands off before final gates.
    • docs/cortex.md + README / brand art for the Cortex loop.
    • Nine canonical MCP tools (was eight).

    Changed

    • Package version 2.0.0; GitHub Action pin for consumers: esneiderbravo/speclaw@v2.
    • Domain agent packs removed; empty packs catalog by default.
  29. 1.0.1

    Fixed

    • Seed laws are adapted to the target repo instead of copying speclaw's own architecture laws. init, update, the compile merge, and the verify fallback include a seed law only when its paths exist, and scope the cycle law to the detected source roots (apps/*/src/**, packages/*/src/**, src/**, …), excluding tests and counting only import edges.
    • Existing manifest entries are never overwritten. Unmodified shipped laws whose paths do not exist are pruned.
    • The graph engine honours a law's scope: cycle detection only considers files matching its globs, so shared/ code and specs extending a base class no longer report false cycles.
    • The repo no longer ships dangling .claude/ and .cursor/ symlinks into the uncommitted ai-specs/, which broke extracting the GitHub Action (Could not find file .claude/skills).
  30. 1.0.0

    Added

    • Incremental Compass index (schema 9): embeddings preserved across reindex by a content-hash cache, unchanged files skipped by mtime/size, and no-op runs short-circuited by directory hashes. --force / --prune.
    • Hybrid retrieval in compass_find (schema 10): BM25 (FTS5), vector, and name matches fused with RRF and personalized PageRank; degrades softly without FTS5.
    • Laws compile into agent rule dialects: delimited AGENTS.md / CLAUDE.md blocks plus Claude, Cursor, Copilot, and CodeRabbit artifacts. rulesync rules import as draft laws that do not gate verify.
    • EARS linter for requirements and a property-coverage gate (Needs: ptest links to recognized runners).
    • speclaw.lock pins rule digests and verify scans for prompt injection, so a Rules File Backdoor edit fails CI. Accepting a new digest is human-only.
    • speclaw owners compiles team.owners in lawbook/config.yaml into a managed CODEOWNERS; doctor checks it.

    Changed

    • Engines raised to Node >=22.16.
    • README and brand art refreshed for ceremony levels 0–3, integrity, owners, and the eight canonical tools.
  31. 0.4.0

    Changed

    • The MCP surface is consolidated to eight canonical tools. compass_find merges compass_search and compass_recall (mode: exact | concept); compass_explore adds callers, callees, blast radius, affected tests, and hotspot; lawbook_change carries the lifecycle actions; speclaw_setup carries init, agent, and pack setup.
    • Tool output has a token budget (brief / full) with explicit truncated[] lists.
    • Retired tool names stay as deprecation aliases for two minor versions (SPECLAW_NO_ALIASES=1 to drop them).

    Added

    • compass_diff_context — changed symbols, blast radius, tests, and hotspots for a diff in one call.

    Removed

    • scaffold, doctor, and compass_visualize from MCP; they stay on the CLI.
  32. 0.3.13

    Added

    • A bug change type: draft --bug writes bugfix.md, and lawbook_investigate ranks suspects from the code graph for root-cause analysis instead of running feature ceremony.
  33. 0.3.12

    Added

    • Adaptive ceremony levels 0–3 from Compass signals (impact, affected-tests, hotspots); persisted in change.json. Missing file ⇒ level 3.
    • speclaw quick <name> — level-0 scaffold (record.md + reports/).
    • lawbook_level MCP + speclaw lawbook level (propose / set / promote / explain); listed in MINIMAL_OMIT.
    • Doctor checks for ceremony cuts validity and archived level distribution.
    • Optional ceremony: block in lawbook/config.yaml (cuts default [3, 8, 15]).

    Changed

    • Validate/archive gates follow the confirmed level (level 0 skips delta sync).
    • LAWS.md / docs/standards/lawbook.md describe level-based artifact volume.
  34. 0.3.11

    Added

    • compass_hotspots / speclaw hotspots — rank files by recent git activity (default 90 days) and AST health from node_metrics (LOC, nesting, branches). Two raw axes; sortBy: churn | complexity | combined.
    • compass_coupling / speclaw coupling <file> — temporal co-change partners with Jaccard strength, in_graph, and isTestPair. Giant commits (maxFilesPerCommit, default 50) are excluded from coupling math.
    • Compass schema 8: node_metrics (forced reindex). Richer fileActivity in shared git-history (commits / lines / authors).

    Notes

    • Descriptions stay honest: relative churn is a research signal, not a guarantee; coupling reports facts, not architecture verdicts.
    • Both new MCP tools are omitted under --minimal exposure.
  35. 0.3.10

    Added

    • compass_affected_tests / speclaw affected-tests — static reverse reachability into test files with a ready-to-run command (prefers package.json#scripts.test, else node --test). Supports --from-diff.
    • Optional .speclaw/affected.json (globals, test globs, named targets).
    • Compass schema 7: files.is_test, files.module (forced reindex).

    Changed

    • Breaking (MCP): compass_impact returns a grouped blast-radius report by default (module counts + top-N). Use format: "flat" for the prior list shape. Resolution is id-first (exact | by-name); default edges are call + import. Global config/lockfile matches report blastRadius: "repo" instead of an empty set.
    • CLI impact renders the grouped summary; --flat / --json available.
  36. 0.3.9

    Added

    • Spec↔code drift: dual body_hash / norm_hash on Compass nodes, committed anchors at lawbook/anchors/<capability>.json, speclaw drift (table / --json / --reseal / --reverse / --fail-on), MCP lawbook_drift, archive-time sealing, doctor check, and verify --ci SARIF findings for semantic/deleted drift.
    • Compass schema 6 (forced reindex); SQLite spec_anchors is a projection rehydrated from the committed JSON.

    Changed

    • Default interactive drift threshold is --fail-on semantic (exit 0/1/2).
    • Minimal exposure keeps lawbook_drift (agents can check drift before declaring done). Tool count in minimal profile is now 9.
  37. 0.3.8

    Added

    • Requirement coverage: stable ids (req~name~rev), // Covers: / # Covers: / @covers comment links, speclaw coverage (TAP / table / --json, --adopt), MCP lawbook_coverage, and an opt-in archive gate on direct defects.
    • Compass schema 5 with derived coverage_links rebuilt on index (spec items stay on disk, never in SQLite).
    • Dogfood: local-content capability carries ids + real Covers links.

    Changed

    • Minimal exposure keeps lawbook_coverage (agents can check coverage before declaring done). Tool count in minimal profile is now 9 (lawbook_drift stays available like coverage).
  38. 0.3.7

    Fixed

    • Claude Code mcp_tool hooks now include an input map (projectPath, event, payload, …) with ${cwd} / ${hook_event_name} / ${tool_input.file_path} substitution. Without it, Stop and other hooks called speclaw_check with empty args and failed MCP -32602.
    • speclaw update recompiles those hooks in already-scaffolded projects.
  39. 0.3.5

    Added

    • Context budget measurement, speclaw budget, --minimal exposure, JIT lawbook skill steps, compact map in docs/compass.md.
  40. 0.3.4

    Added

    • speclaw verify — CI gate over the declared laws. Text, JSON (schemaVersion: 1), SARIF 2.1.0, and markdown output; --ci, --sarif, --json, --format, --fail-on, --strict-engines. Exit codes 0–4 are public API; a shallow clone under --ci exits 3 asking for fetch-depth: 0.
    • init and update write .github/workflows/speclaw.yml when it is missing, and the package root ships an action.yml (uses: esneiderbravo/speclaw@v1).

    Fixed

    • On a clean clone (no .speclaw/laws-manifest.json), verify falls back to the seed laws instead of passing empty. scaffold appends seed laws whose id is absent and never overwrites an existing entry.
  41. 0.3.3

    Added

    • deps and graph law backends: file-level from/to import rules over the Compass index, and cycle / reachability checks (iterative Tarjan). An unresolved edge counts as unknown, never as a pass.
    • law_verify MCP tool and speclaw laws verify, reporting each law as passed, failed, skipped, or unknown. Without an index the result is skipped: no-index.
    • doctor reports whether the graph engines are available.
  42. 0.3.2

    Added

    • Laws compile into agent hooks: a blocking law is denied at the keystroke by a PreToolUse hook instead of relying on the model to recall LAWS.md.
    • speclaw_check MCP tool and speclaw check CLI (--dry-run, --hook-payload -, exit code 2 on deny). Verdicts are allow / warn / deny / escalate and the check fails open.
    • .speclaw/laws-manifest.json with a seed of starter laws, including a universal .env block. Hooks merge into the agent's settings without touching foreign entries; Claude Code only.
    • doctor reports context coverage and validates law globs.
  43. 0.3.1

    Added

    • A git-history layer (logForPath, churn, coChanges, lastTouch) for drift and hotspot features, with full-history scans cached in the Compass index per HEAD (schema 4). No CLI or MCP surface yet.
  44. 0.3.0

    Changed

    • Discipline reports are an open set: one reports/<discipline>.md per area a change touches (backend, frontend, api, database, infra, security, …). api.md is mandatory whenever a change touches an API surface. Shipped as the always-applied spec-reports-disciplines rule.
  45. 0.2.1

    Changed

    • ai-specs/ is regenerable, so init and update gitignore it and rebuild it locally. Agent directories (.claude/, .cursor/, …) are left to the user. A repo that already committed ai-specs/ gets the exact git rm -r --cached ai-specs command to run.
  46. 0.2.0

    Added

    • draft and explore refresh the index first, list the canonical capabilities, and reuse their exact names.
    • lawbook_validate warns (without blocking) about near-duplicate capability names and requirements dropped against the canonical spec.
    • lawbook_sync and lawbook_archive report each promoted spec as created or updated.
  47. 0.1.15

    Added

    • speclaw version (--version, -v) prints the installed version and, when interactive, a clickable npm link if a newer one exists.
    • A one-line brand header on interactive commands, suppressed for machine-read output and non-TTY runs, with an ASCII fallback for legacy Windows consoles.
  48. 0.1.14

    Changed

    • Verification must stay isolated (temp copy, in-memory or test store, rollback). Writing to a real data store during verification is a stop condition in the agent contracts, the build skill, and the testing standard.
  49. 0.1.13

    Changed

    • Discipline reports follow a fixed seven-part structure (header, gates table, tests added, scenario coverage, pre-existing failures, pending manual steps, verdict).
    • speclaw update overwrites diverged managed files in place (recover from git); --backup keeps a <file>.bak.
  50. 0.1.12

    Changed

    • speclaw update refreshes managed files (ai-specs/ skills, commands, rules, agents) to the current version. Personalized files (CLAUDE.md, AGENTS.md, LAWS.md, standards) are never edited; update prints an agent prompt with the cumulative migrations to apply.
  51. 0.1.11

    Added

    • Every change carries a reports/ folder for per-discipline test results.
    • Archive is a hard gate: it refuses while a task is unchecked, reports/ is empty, or the delta specs are not synced.
    • sync and archive reconcile the delta specs against what was built.

    Changed

    • Agent contracts make Compass mandatory first, before grep or reading files.
  52. 0.1.10

    Changed

    • design.md and tasks.md are always created for a change, never optional.
    • README: spec-driven workflow section with the loop diagram and artifacts table.
  53. 0.1.9

    Added

    • ESLint + Prettier quality gate (lint, format, check) run in CI.
  54. 0.1.8

    Changed

    • The per-agent MCP config (.mcp.json, .cursor/mcp.json, …) is added to .gitignore on init and agent add.
  55. 0.1.7

    Added

    • init warns before any prompt when a newer speclaw is available, and recommends speclaw update first.
  56. 0.1.6

    Fixed

    • An index database from an older version is detected as stale and rebuilt, instead of failing with errors like table edges has no column named src_node_id.
  57. 0.1.5

    Added

    • speclaw update: upgrades the global package, then applies only what is new to the project (--check, --migrate-only). Existing files are untouched.
    • A background update notifier, checked at most once a day; opt out with NO_UPDATE_NOTIFIER or SPECLAW_NO_UPDATE_NOTIFIER.
    • ai-specs/.speclaw.json records the installed version and packs.

    Changed

    • Docs lead with the global install (npm i -g @esneiderbravo/speclaw).
  58. 0.1.4

    Fixed

    • speclaw visualize no longer throws Cannot access 'dragging' before initialization in the browser.
  59. 0.1.3

    Changed

    • init no longer prompts for a ticket prefix or team language; both are inferred from the repo's commits, branches, and docs.
  60. 0.1.2

    Added

    • speclaw visualize and the compass_visualize MCP tool: an offline, interactive code graph in .speclaw/graph.html.

    Changed

    • The spec/ workspace is renamed lawbook/ (directory, lawbook_* tools, /lawbook: commands, speclaw lawbook CLI).
    • The handoff prompt prints as plain, copy-pasteable text.
  61. 0.1.1

    Fixed

    • README images render on npm.

    Changed

    • Published from CI with npm Trusted Publishing (OIDC).
  62. 0.1.0

    Added

    • First release of speclaw, as a CLI and an MCP server, under @esneiderbravo/speclaw.
    • Foundation: LAWS.md, granular standards, and CLAUDE.md / AGENTS.md.
    • Compass: a local tree-sitter code graph and vector store. No LLM, no external CLIs.
    • Spec: a draft → build → sync → archive workflow engine.
    • Tools: opt-in skill and agent packs.