Release history
Changelog
Every published version of @esneiderbravo/speclaw, newest first. The source is CHANGELOG.md in the library’s repository.
Fixed
harness.jsonno longer stamps every stage with the same second. Ship (and theStophook) 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 toimplementing; the review verdict stays with the PR.
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": runspeclaw updateandspeclaw doctor, which lists every project file (now includingai-specs/skillsandai-specs/agents) that still names one, with its canonical call. lawbook_changeactionharnessandspeclaw lawbook harness: use thecortextool orspeclaw cortex.SPECLAW_NO_ALIASESno longer does anything.
Added
cortexactionbriefat stagereviewingexports the branch diff to.speclaw/review/<change>.diffand returns a bounded review prompt: read the diff once, onecompass_diff_context, changed hunks only, a ≤ 40-linereview.mdand 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 atlawbook_investigatewith the output asstackTrace.
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.
- The 20 retired MCP tool aliases are gone:
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 ownsrc/server.tsandsrc/cli/index.tsare 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 lumpedchange.md. - The
Stophook ends every ship with a one-linesystemMessagefor the user: the gates and their times, then the archive or what is left. Runspeclaw updateto reinstall the hook command that keeps its stdout.
Fixed
- Archiving no longer reads as new work: the
Stophook ignores the canonical specs an archive promotes (lawbook/specs/) and the anchors it seals (lawbook/anchors/), as it already ignoredlawbook/changes/. Before, the stop after an archive re-ran every gate (~100 s) and rewrote the archived report.
Changed
npm testruns the suite in parallel without coverage (~43 s, was ~90 s), so the agent's targeted runs and theStophook's gate stay fast; the coverage-gated serial suite moved tonpm run test:ci, which CI and publish run.
- Archiving no longer reads as new work: the
Changed
- The
Stophook 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: fullinlawbook/config.yamlkeeps the full suite at the stop. - Generated
CLAUDE.md,AGENTS.mdand 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_changeaccepts the arguments agents actually send:archivedates the folder today when no date is given;archiveand level-0shipsync an unsynced delta themselves instead of refusing;validate,sync,archive,ship,level set/promoteandharnessinfer the change when it is left out (the only active change, else the branch's);namereads aschange; actioncreate/newdrafts; a comma-separatedpathsis a list. In real sessions these accounted for most of the 11 % of speclaw calls that failed and cost the agent a retry.compass_exploregiven a search phrase and nonodeanswers as a find instead of a validation error.cortexon an undrafted change says to draft it first and lists the active changes.
- The
Fixed
- A re-index no longer reads as the agent's work: the Stop hook ignores
docs/compass.mdwhen 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.
- A re-index no longer reads as the agent's work: the Stop hook ignores
Fixed
- The documentation hint no longer stalls the agent on large diffs. It measured the branch diff inside the
PostToolUsehook: 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 startsspeclaw measure-diffin 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\"suggestedcompass_find "foo\").
- The documentation hint no longer stalls the agent on large diffs. It measured the branch diff inside the
Fixed
- The
Stophook 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 ofpackage.jsondoes not count), records the level asmeasured, 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. APostToolUsehook 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.
minimalprojects kept their hooks but not the tool they call:speclaw_checkwas omitted from the minimal profile, so every law hook and the Compass-first nudge answered "Tool not found". Minimal now keepsspeclaw_checkandlawbook_investigate.- The Compass-first nudge also watches Bash:
cat,sed,head,grep,rgand 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_investigateranks 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_explorewithmaxDepth> 1 (andinclude: ["callees"]) returns the whole callee chain with each symbol's source, andto: <symbol>returns the path's sources: one call reads what took one file read per hop.- The MCP server sends
instructionsnaming the tool for each job, andcompass_find,compass_explore,compass_diff_contextandlawbook_investigateload 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 whoselawbook/config.yamlsetscutskeep their values. scripts/bench-workflow.shinstalls theStophook in its Cortex fixture (speclaw agent add claude; since 2.0.16initconfigures 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.
- The
Fixed
- The
Stophook 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, sospeclaw update,doctor,shipand the rest are legible on light terminals.
- The
Fixed
- The CLI is legible on light terminals.
speclaw initdetects 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=lightordarkforces a theme, andCOLORFGBGis honored by every command.
- The CLI is legible on light terminals.
Fixed
- The
Stophook (speclaw ship-on-stop) no longer re-ships work that was only committed: its fingerprint is the branch's diff against the merge base, notHEAD. 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-lastmarker 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.
- The
Fixed
- A default
speclaw init(only.agents/) now registers thespeclawMCP 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 theconfigure-agentsetup action now install the agent's hooks too (Claude Code:SessionStart,PostToolUse,Stop), recording the settings baseline so a laterupdatetreats it as speclaw's own. Before, adding Claude Code after init left it without the session-start reindex, the edit reindex, and theship-on-stophook, so finished work was never recorded in the lawbook.- The
lawbook/config.yamlwritten by init no longer fails a host repo'sprettier --check .: the EARSvagueWordslist 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 committedlawbook/stays green underprettier --check ...gitignoreentries 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.mdnow states the agent workflow — Compass first, Cortex for every change, theStophook (orspeclaw ship) to record it in the lawbook — when the hand-written part of the file doesn't.updatenever edits the personalizedAGENTS.md, so projects scaffolded before Cortex, or with a hand-writtenAGENTS.md, never learned to record their work.
- A default
Fixed
speclaw initno longer asks which agents to use: it always creates only.agents/(other folders via--agentsorspeclaw agent add).- A bare
.claude/or.cursor/(created by Claude Code or Cursor on their own) is no longer taken as a configured agent, soupdatestops filling it with links,settings.jsonandrules/speclaw. An agent counts as configured only when its folder holds a speclaw link intoai-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.
Changed
speclaw initcreates a single agent-facing folder by default:.agents/, with symlinks toai-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:
initadds.agents/(and any agent folder it creates) andspeclaw.lockto.gitignore, next toai-specs/and.speclaw/. Only the project's content is committed:LAWS.md,CLAUDE.md,AGENTS.md,docs/, andlawbook/.
Removed
initno longer writes.github/workflows/speclaw.yml; the CI workflow template is gone.
Fixed
speclaw drift --resealre-stamps only the anchors whose sealed state changed. Unchanged anchors keep theirarchivedAt/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.
Changed
- Cortex is as fast as one agent: one brain does the critical path and the installed
Stophook (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_changeactionship: one call for finished work. It never records a review verdict.scripts/bench-workflow.sh: reproducible agent benchmark.
Fixed
compass_find(and thecompass_search/compass_recallaliases) returns one compact JSON document that always parses and fitsmaxTokensas a whole (default 1500): hits carry onlyname,kind,file,line(no node ids, signatures, ranking signals, or route);tokenscounts the emitted text;truncated: trueappears only when hits, rendered blocks, nearest entries, or entries offocusIgnored/focus/termswere removed (a cut list reports its original length infocusIgnoredTotal/focusTotal/termsTotal), so a worktree with many changes or a long exact query no longer overflows the cap.speclaw search|recall --jsonkeep their shape.compass_exploreandcompass_diff_contextwithmode: "full"are no longer cut at the brief ceiling, and a full-mode truncation hint no longer tells you to usemode:"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_findlists them infocusIgnored. - Exact
compass_findanswers whether a name exists: hits are only symbols named exactly a query term (alpha betais an OR, reported asterms); a missing name returnsfound: false, emptyhits, and up to fivenearestnames. - Types now have callers: TS/JS type annotations and
extends/implementsclauses becomerefedges, resolved only through the file's import binding or a same-file definition.compass_exploreandspeclaw explorelist them withvia: "ref"(calls carryvia: "call"); impact, affected tests, PageRank, hotspots, coupling, the map, visualize, anddeps/graphlaws 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(andlawbook_changeactiondraftwithbug: true) without a level no longer confirms its own level:change.jsoncarries noconfirmedLevel/confirmedBy/confirmedAt,bugfix.mdsaysLevel: unconfirmed, and validate applies level-3 bug rules until a level is set.- Cortex
advanceandreworkre-read the confirmed level fromchange.json(unconfirmed → 3), so a level set afterstarttakes effect and an unconfirmed change never skips planning.pauseForQuestionsoutside stageplanningis 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, andlawbook_changeactionlevelmodeset/promotewithout paths or symbols keeps the proposal already stored inchange.json.promoteon 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.
- Cortex is as fast as one agent: one brain does the critical path and the installed
Fixed
speclaw laws scanandspeclaw verifykeep reporting injection findings whenspeclaw.lockis unreadable.laws scannames the lock error and exits 1;laws scan --jsonnow exits 1 on a lock error or an error finding, like the text mode, and adds alockErrorfield.--questiononspeclaw cortex advance(andlawbook harness) is truly repeatable: each flag is one open question, and commas no longer split it.speclaw doctorsuggestsgit checkout HEAD -- speclaw.lockfor an unreadable lock, which also works during a conflicted merge.
Added
- Compass re-indexes each file an agent edits. For Claude Code,
init/updateadd onePostToolUsecommand hook onWrite|Edit|MultiEdit|NotebookEditthat runs the newspeclaw 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 manualcompass_index. Binary resolution matches the session-start hook; an older speclaw rejects the unknown command and touches nothing. Hooks you added toPostToolUseare kept. speclaw reindex-file <paths…>re-indexes specific files in the foreground. Per-file runs skip PageRank, cache eviction and thedocs/compass.mdmap; they mark the index so the next fullspeclaw 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 indexno 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.jsonasrefreshedDivergedonce onspeclaw update, as the reindex hook group is added.
- Compass re-indexes each file an agent edits. For Claude Code,
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, andtsconfig/jsconfigpathsandbaseUrlaliases resolve (nearest config, relativeextends, 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_explorecallees list only resolved symbols; unresolved names are summarized inunresolvedCallees(count and sample) instead of crowding out real callees.- The affected-tests
commandis never a run-nothing command: it isnullwith acommandReasonwhen nothing is affected. The runner is detected per nearestpackage.json(vitest, jest,node --test, inherited from a hoisted root), workspace-spanning selections get per-workspacecommands, andnode --testcommands 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/traceno longer lose callers.
Changed
- Compass schema 11 (
edges.is_member,edges.spec). The firstspeclaw indexafter 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 — runspeclaw updateso 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.
- Affected tests now find the tests that actually exercise a symbol. Calls inside
Added
speclaw updateupgrades itself. When npm reports a newer release during the run, it re-executes asnpx -y @esneiderbravo/speclaw@<latest> updatewith 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-updateorSPECLAW_NO_SELF_UPDATE=1), when the registry is unreachable (a cached version only), or whennpxcannot be started.initstill only advises.--help/-hon 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 --helpraninitandspeclaw mcp --helpstarted a server).speclaw laws lock --forcelists each drifted strict file with its locked and on-disk digests, asks for confirmation (default No), then re-baselines them and records anaccepted[]entry for each (--noteadds 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) byinit,agent add, andupdate. On the firstspeclaw update, an existing stock (unpinned) entry is re-pinned; a custom entry (e.g. a localnodepath) is kept. - The
lawbook_changeactionarchiveresult reportsharnessCompleted, and thecortexMCP tool'sstatusandbriefread an archived change instead of failing.start,advance, andreworkon 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 warnsrun speclaw laws accept <path>, soverifykeeps failing until a human accepts it. Clean and new strict files and advisory files are refreshed as before, and staleaccepted[]entries are pruned. - An existing
speclaw.lockthat cannot be read (merge-conflict markers, a newerlockfileVersion, or valid JSON with the wrong structure) is never rebuilt: every refresh leaves it byte-identical and reports the error, andinit,update,laws compile,laws lock, andlaws acceptexit 1.speclaw doctorsuggests repairing or restoring it from git rather than a barelaws lock. - Archiving a change completes its Cortex harness. The archive moves the harness from
archivingtodone(one history entry) before it moves the change directory, and restores it if the move fails; thecortexskill and the archiver agent no longer calladvanceafter an archive (it failed once the change had moved). The six archived changes of 2026-10-06 left stuck inarchivingare repaired todone.
Added
- Cortex status summary. The
cortexMCP tool'sstatusaction andspeclaw cortex statusreturn asummarybeforestate: the stage, the active role, whole minutes in the stage, tasks done/total (from thetasks.mdcheckboxes, orrecord.mdat level 0), the rework iteration/max, the pending verdicts, the open-question count, the configured interval, and a one-line Englishline.summaryisnullwhen the change has no harness yet. The MCP input schema is unchanged. speclaw cortex statusalso printssummary.lineto stderr; stdout stays one JSON document, and--jsonsuppresses the stderr line.- Coordinator status updates. During a Cortex run the
cortexskill 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 CodeCronCreate) 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 atdone, when the run stops, or when the human asks to stop. cortex.statusIntervalMinutesinlawbook/config.yamlsets the update interval: default 5,0disables every unsolicited update, values above 60 are capped at 60, and a missing or invalid value means 5.
Changed
- On the MCP path (
cortexand the deprecatedlawbook_changeharnessalias),statusis fitted to the output budget so the JSON stays valid andsummarystays complete: the oldeststate.historyentries are dropped and counted inhistoryOmitted(statebecomesnullwithstateOmittedif even an empty history does not fit). The CLI andharness.jsonkeep the full history.
- Cortex status summary. The
Added
- Session-start refresh for Claude Code.
speclaw init/speclaw updateadd oneSessionStartcommand hook (matcherstartup|resume|clear|compact, 30 s timeout) that runs the newspeclaw session-startcommand. It resolves the binary asnode_modules/.bin/speclaw→speclawonPATH→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.dbis absent — the first build stayscompass_index/speclaw index. An older speclaw onPATHrejects the unknown command and touches nothing. Hooks you added toSessionStartare kept. speclaw session-startrefreshes an existing index without writing to the Compass call log, the branded header, or the update notice.
Changed
speclaw indextakes 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 skipsdir_hashes, edge and import resolution, PageRank, and embedding-cache upkeep, still advancesindexed_at, and leavesdocs/compass.mdalone 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.jsonasrefreshedDivergedonce on the firstspeclaw update, as theSessionStartgroup is added.
Fixed
compass_explorereturns 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.
- Session-start refresh for Claude Code.
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. Thec.*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 (
00707fon131313). npm run brandrenders the PNGs with Chivo loaded from the new dev dependencies@fontsource/chivoand@fontsource/chivo-mono(decoded from WOFF2 by the dev dependencywawoff2), 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.
- The brand follows the speclaw site's design tokens. The CLI palette, the Compass HTML viewer, and every asset under
Changed
- The Publish to npm workflow also pushes the
v<version>tag and creates the GitHub release from the version'sCHANGELOG.mdsection. It skips a tag or release that already exists and fails before tagging if the section is missing.
Fixed
speclaw.lockno longer pins the.claude/rules/speclawsymlink (it points into the gitignoredai-specs/), sospeclaw updatestops flippingsymlinksbetween{}and that entry depending on whether the link exists locally. Locks written by older versions that still pin it only warn inspeclaw verifywhen the link is missing or retargeted, instead of failing clean CI clones with "Managed symlink missing". The nextspeclaw updateorspeclaw laws lockdrops a legacy entry once; after that the lock stays stable. Other managed symlinks still fail verify.
- The Publish to npm workflow also pushes the
Added
- Compass-first evidence gate.
cortex advanceout ofexploringorimplementingchecks for Compass calls (explore, find, diff-context and their aliases;compass_indexdoes not count) logged to.speclaw/compass-calls.jsonlsince the stage started.compassGate: off|warn|strictinlawbook/config.yaml(defaultwarn);strictrejects the advance without touchingharness.json. - Compass-first nudge: a
PostToolUseRead|Grep|Globhook adds context telling the agent to usecompass_find/compass_explorewhen 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 thelawbook_changeactiondraftscaffold a feature change that validates out of the box. Placeholder deltas are refused by sync.compass_index/speclaw indexreport graphtotalsand anextStep.scripts/bench/compass-first.mjsbenchmarks 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_findfirst 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
refreshedDivergedonspeclaw update.
- Compass-first evidence gate.
Fixed
compass_exploreandsearchresolve a repo-relative file path to a symbol in that file. An exact symbol name still wins. A path such assrc/foo.tsno longer returns zero similar symbols.
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 updaterefreshesai-specs/skillsandai-specs/agentsfrom this package.
- 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.
Fixed
speclaw updateno longer runsnpm install -g. It only applies project migrations and prints an advisory if a newer binary exists on npm (upgrade the CLI separately vianpm i -gornpx @esneiderbravo/speclaw@latest).
Added
- Cortex (*One brain. Many agents.*) — multi-agent coordination module: durable
harness.json, MCP toolcortex(status/start/advance/rework/brief), CLIspeclaw 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.
- Cortex (*One brain. Many agents.*) — multi-agent coordination module: durable
Fixed
- Seed laws are adapted to the target repo instead of copying speclaw's own architecture laws.
init,update, the compile merge, and theverifyfallback 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 onlyimportedges. - 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 uncommittedai-specs/, which broke extracting the GitHub Action (Could not find file .claude/skills).
- Seed laws are adapted to the target repo instead of copying speclaw's own architecture laws.
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.mdblocks plus Claude, Cursor, Copilot, and CodeRabbit artifacts. rulesync rules import as draft laws that do not gateverify. - EARS linter for requirements and a property-coverage gate (
Needs: ptestlinks to recognized runners). speclaw.lockpins rule digests andverifyscans for prompt injection, so a Rules File Backdoor edit fails CI. Accepting a new digest is human-only.speclaw ownerscompilesteam.ownersinlawbook/config.yamlinto a managedCODEOWNERS;doctorchecks 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.
- 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.
Changed
- The MCP surface is consolidated to eight canonical tools.
compass_findmergescompass_searchandcompass_recall(mode: exact | concept);compass_exploreadds callers, callees, blast radius, affected tests, and hotspot;lawbook_changecarries the lifecycle actions;speclaw_setupcarries init, agent, and pack setup. - Tool output has a token budget (
brief/full) with explicittruncated[]lists. - Retired tool names stay as deprecation aliases for two minor versions (
SPECLAW_NO_ALIASES=1to drop them).
Added
compass_diff_context— changed symbols, blast radius, tests, and hotspots for a diff in one call.
Removed
scaffold,doctor, andcompass_visualizefrom MCP; they stay on the CLI.
- The MCP surface is consolidated to eight canonical tools.
Added
- A
bugchange type:draft --bugwritesbugfix.md, andlawbook_investigateranks suspects from the code graph for root-cause analysis instead of running feature ceremony.
- A
Added
- Adaptive ceremony levels 0–3 from Compass signals (
impact, affected-tests, hotspots); persisted inchange.json. Missing file ⇒ level 3. speclaw quick <name>— level-0 scaffold (record.md+reports/).lawbook_levelMCP +speclaw lawbook level(propose / set / promote / explain); listed inMINIMAL_OMIT.- Doctor checks for ceremony cuts validity and archived level distribution.
- Optional
ceremony:block inlawbook/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.mddescribe level-based artifact volume.
- Adaptive ceremony levels 0–3 from Compass signals (
Added
compass_hotspots/speclaw hotspots— rank files by recent git activity (default 90 days) and AST health fromnode_metrics(LOC, nesting, branches). Two raw axes;sortBy:churn|complexity|combined.compass_coupling/speclaw coupling <file>— temporal co-change partners with Jaccardstrength,in_graph, andisTestPair. Giant commits (maxFilesPerCommit, default 50) are excluded from coupling math.- Compass schema 8:
node_metrics(forced reindex). RicherfileActivityin 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
--minimalexposure.
Added
compass_affected_tests/speclaw affected-tests— static reverse reachability into test files with a ready-to-runcommand(preferspackage.json#scripts.test, elsenode --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_impactreturns a grouped blast-radius report by default (module counts + top-N). Useformat: "flat"for the prior list shape. Resolution is id-first (exact|by-name); default edges arecall+import. Global config/lockfile matches reportblastRadius: "repo"instead of an empty set. - CLI
impactrenders the grouped summary;--flat/--jsonavailable.
Added
- Spec↔code drift: dual
body_hash/norm_hashon Compass nodes, committed anchors atlawbook/anchors/<capability>.json,speclaw drift(table /--json/--reseal/--reverse/--fail-on), MCPlawbook_drift, archive-time sealing, doctor check, andverify --ciSARIF findings for semantic/deleted drift. - Compass schema 6 (forced reindex); SQLite
spec_anchorsis 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.
- Spec↔code drift: dual
Added
- Requirement coverage: stable ids (
req~name~rev),// Covers:/# Covers:/@coverscomment links,speclaw coverage(TAP / table /--json,--adopt), MCPlawbook_coverage, and an opt-in archive gate on direct defects. - Compass schema 5 with derived
coverage_linksrebuilt on index (spec items stay on disk, never in SQLite). - Dogfood:
local-contentcapability 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_driftstays available like coverage).
- Requirement coverage: stable ids (
Fixed
- Claude Code
mcp_toolhooks now include aninputmap (projectPath,event,payload, …) with${cwd}/${hook_event_name}/${tool_input.file_path}substitution. Without it, Stop and other hooks calledspeclaw_checkwith empty args and failed MCP-32602. speclaw updaterecompiles those hooks in already-scaffolded projects.
- Claude Code
Added
- Context budget measurement,
speclaw budget,--minimalexposure, JIT lawbook skill steps, compact map indocs/compass.md.
- Context budget measurement,
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--ciexits3asking forfetch-depth: 0.initandupdatewrite.github/workflows/speclaw.ymlwhen it is missing, and the package root ships anaction.yml(uses: esneiderbravo/speclaw@v1).
Fixed
- On a clean clone (no
.speclaw/laws-manifest.json),verifyfalls back to the seed laws instead of passing empty.scaffoldappends seed laws whose id is absent and never overwrites an existing entry.
Added
depsandgraphlaw 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_verifyMCP tool andspeclaw laws verify, reporting each law as passed, failed, skipped, or unknown. Without an index the result isskipped: no-index.doctorreports whether the graph engines are available.
Added
- Laws compile into agent hooks: a blocking law is denied at the keystroke by a
PreToolUsehook instead of relying on the model to recallLAWS.md. speclaw_checkMCP tool andspeclaw checkCLI (--dry-run,--hook-payload -, exit code 2 on deny). Verdicts are allow / warn / deny / escalate and the check fails open..speclaw/laws-manifest.jsonwith a seed of starter laws, including a universal.envblock. Hooks merge into the agent's settings without touching foreign entries; Claude Code only.doctorreports context coverage and validates law globs.
- Laws compile into agent hooks: a blocking law is denied at the keystroke by a
Added
- A git-history layer (
logForPath,churn,coChanges,lastTouch) for drift and hotspot features, with full-history scans cached in the Compass index perHEAD(schema 4). No CLI or MCP surface yet.
- A git-history layer (
Changed
- Discipline reports are an open set: one
reports/<discipline>.mdper area a change touches (backend, frontend, api, database, infra, security, …).api.mdis mandatory whenever a change touches an API surface. Shipped as the always-appliedspec-reports-disciplinesrule.
- Discipline reports are an open set: one
Changed
ai-specs/is regenerable, soinitandupdategitignore it and rebuild it locally. Agent directories (.claude/,.cursor/, …) are left to the user. A repo that already committedai-specs/gets the exactgit rm -r --cached ai-specscommand to run.
Added
draftandexplorerefresh the index first, list the canonical capabilities, and reuse their exact names.lawbook_validatewarns (without blocking) about near-duplicate capability names and requirements dropped against the canonical spec.lawbook_syncandlawbook_archivereport each promoted spec as created or updated.
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.
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.
Changed
- Discipline reports follow a fixed seven-part structure (header, gates table, tests added, scenario coverage, pre-existing failures, pending manual steps, verdict).
speclaw updateoverwrites diverged managed files in place (recover from git);--backupkeeps a<file>.bak.
Changed
speclaw updaterefreshes 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.
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. syncandarchivereconcile the delta specs against what was built.
Changed
- Agent contracts make Compass mandatory first, before grep or reading files.
- Every change carries a
Changed
design.mdandtasks.mdare always created for a change, never optional.- README: spec-driven workflow section with the loop diagram and artifacts table.
Added
- ESLint + Prettier quality gate (
lint,format,check) run in CI.
- ESLint + Prettier quality gate (
Changed
- The per-agent MCP config (
.mcp.json,.cursor/mcp.json, …) is added to.gitignoreoninitandagent add.
- The per-agent MCP config (
Added
initwarns before any prompt when a newer speclaw is available, and recommendsspeclaw updatefirst.
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.
- An index database from an older version is detected as stale and rebuilt, instead of failing with errors like
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_NOTIFIERorSPECLAW_NO_UPDATE_NOTIFIER. ai-specs/.speclaw.jsonrecords the installed version and packs.
Changed
- Docs lead with the global install (
npm i -g @esneiderbravo/speclaw).
Fixed
speclaw visualizeno longer throwsCannot access 'dragging' before initializationin the browser.
Changed
initno longer prompts for a ticket prefix or team language; both are inferred from the repo's commits, branches, and docs.
Added
speclaw visualizeand thecompass_visualizeMCP tool: an offline, interactive code graph in.speclaw/graph.html.
Changed
- The
spec/workspace is renamedlawbook/(directory,lawbook_*tools,/lawbook:commands,speclaw lawbookCLI). - The handoff prompt prints as plain, copy-pasteable text.
Fixed
- README images render on npm.
Changed
- Published from CI with npm Trusted Publishing (OIDC).
Added
- First release of speclaw, as a CLI and an MCP server, under
@esneiderbravo/speclaw. - Foundation:
LAWS.md, granular standards, andCLAUDE.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.
- First release of speclaw, as a CLI and an MCP server, under