Changelog

v4.14.0 - 2026-10-24

Two guards, a faster gate, and a cockpit you see without opening it. A git command that switches the project’s hooks off is refused (CR-258), and a red test waved away as flaky without a ticket sends the turn back (CR-289). SEC001 covers JavaScript and Python with today’s key shapes (CR-257), files a Bash command changed are reviewed (CR-256), and a test run that tested nothing grants no evidence (CR-255). A write costs about half of what it did, a prompt a third, and a session start half (CR-278, CR-290). On Claude Code the cockpit now ships in the plugin: a line above the prompt says where the session stands, and each answer that changed it gets a receipt.

Upgrading can refuse a file that 4.13.1 let through: a credential literal in a .js, .jsx, .mjs, .cjs or .py file, and a key with a recent issuer prefix (sk-ant-, sk-proj-, glpat-, npm_) in any covered language. SEC001 is never ignorable: move the value to the environment and rotate it.

The cockpit now ships in the craftsman plugin. If you installed the separate craftsman-cockpit plugin, uninstall it: its 4.14.0 is empty, so updating it also removes the old module.

Added

• On Claude Code, a line above the prompt says where the session stands: the writes the gate judged, the blocks still open with their rule and file, the warnings, and what the tests say (red with the run that failed, verified, a run that tested nothing, not run). It appears once the session has something to report and is redrawn after every write the hooks judge; Ctrl+X then Ctrl+A folds it. Each answer that changed it gets one line under it, as in craftsman: 3 writes, 1 blocked, 0 warnings · 1 open: LAYER001 Order.php · tests not run; a turn that only read or talked gets none. Both read craftsman-helper session status, a JSON view of what the hooks keep for the session, and decide nothing (ADR-0031). Measured in a headless Claude Code 2.1.310 session on a synthetic project: the receipt line came from the real hooks through the real helper.
• SEC001 covers JavaScript and Python, and knows today’s key shapes. An Anthropic or OpenAI project key was written to a .ts file with no finding while the repository’s own secrets scanner knew both prefixes, and a .js or .py file got no SEC001 at all. The shapes now live in one list, hooks/lib/secret-patterns.sh, that every pack reads: Anthropic sk-ant-, OpenAI sk-proj-, sk-svcacct-, sk-admin- and legacy sk-, GitLab glpat-, npm npm_, Slack webhooks, GitHub ghs_, ghu_, ghr_, Stripe rk_live, AWS ASIA, a typed API_TOKEN: str = "...", and a *_KEY constant holding a 32-character key. Issuer prefixes match with case and never inside a longer word, so Asia/Kolkata, task-... ids and storage keys stay silent. An env read on the line no longer hides an issued key: process.env.KEY ?? "sk-ant-..." ships the key. This reverses the CR-231 choice to leave secrets out of JavaScript (CR-257).
• A turn no longer ends on a red test waved away. A new synchronous Stop hook, test-dismissal-guard.sh, sends the turn back when a test run that failed in the session is still outstanding and the last message calls it flaky, intermittent, known, pre-existing, unrelated, or green alone, with no ticket named (ORD-42, #123, an issue URL). A test red in the suite and green alone depends on shared state, order, time or the filesystem: a defect, not noise. Blocks in strict, warns in moderate, silent in relaxed; a second stop on the same excuse is shown to the user, never looped. The words are data, a TEST_DISMISSAL category of the bias patterns (English and French). /craftsman:debug and /craftsman:verify name the excuse among their red flags, with pre-existing deprecations reported instead of fixed (CR-289).
• The agent can no longer switch the project’s git hooks off. A new PreToolUse hook, git-bypass-guard.sh, refuses --no-verify on any git subcommand, git commit -n, -c core.hooksPath=..., git config core.hooksPath <dir>, HUSKY=0, SKIP=..., LEFTHOOK=0, and a git stash run in the same command as a commit, with the reason. A model has been seen committing six times in a row with --no-verify and git stash against rules forbidding it (anthropics/claude-code #40117): a rule the model reads is advice, a refusal is not. The command is read token by token, so --no-verify quoted in a commit message passes. It runs on the git subcommands Claude Code’s if filter sees, which is best effort (env git ... and sh -c are not seen), and fails closed. The user keeps the choice: run the command themselves, or set hooks.disabled: git-bypass-guard (CR-258).
• Files a Bash command changed are reviewed. Claude Code 2.1.269+ lists them in tool_response.bashEditDiff; post-write-check.sh now runs after every Bash call and judges each listed file as a Write, under its own path. A call that changed nothing leaves before any library loads. The host records the list in bypass and auto mode, elsewhere only with bashEditDiffEnabled in user or managed settings, and documents it as best effort: the pre-write gate remains the only refusal before the disk (CR-256).

Changed

• The latency suite’s ceilings follow the hooks down: post-write from 6.5 to 3.55 times the calibration baseline on macOS and from 11.4 to 4.9 on Linux, the other rows alike, from four CI runs on the final code and a maintainer’s laptop under load. Left where they were, they sat at twice what the hooks now cost, so a doubling would have passed.
• The cockpit moved into the craftsman plugin: one install, and /instincts finds the core at the plugin’s own root instead of through the session binding, the repository layout and PATH, the lookup two field failures came from (CR-279, CR-291). Codex and Grok never see the module: it is declared by hooks/claude-code.json, which only Claude Code’s manifest names, while hooks/hooks.json holds none. Measured: a module that fails to load leaves the command hooks running on 2.1.310, and Claude Code 2.1.218, the minimum, ignores the module file and runs the hooks (ADR-0031 amended).
• Every write costs less: a post-write about half, a pre-write about a third less (median of seven alternating runs against the previous code, 2043 to 1030 ms and 1421 to 905 ms on a loaded machine). Claude Code had started offering to disable the plugin’s slow hooks. Each hook now reads a pack manifest once instead of four times through subshells, a write reads the metrics schema stamp instead of running ten migration probes, and the craft config is read in one jq instead of five per custom rule (CR-278). A second pass, from a profile rather than a guess, took a further 16 percent off a post-write and 15 off a pre-write (CPU time, alternating runs against the previous code: 600 to 503 ms and 558 to 480 ms). The manifest memo of the first pass searched every pair for each question, 2,200 loop turns per hook; it now jumps to the key. The PHP root namespace lookup ran a process per directory up to /, the project root behind every metrics row ran git four times, and each pack manifest had its own stat; each is now done once or in-shell.
• A prompt waits less before the model sees it: the bias detector, which runs on every prompt, takes about 70 percent less CPU (alternating runs against the previous code under the same load: 478 to 144 ms on a prompt with no bias, 496 to 149 ms on a signal hit), and the latency suite reads it at 0.50x its baseline instead of 1.60x. The pattern registry derived each language’s variable suffix in a subshell, thirteen times for every pattern it was asked for: 221 subshells per prompt. It now derives them once, when it loads. The reported-speech check ran once per category instead of once per prompt, and the pending Sentry request was read by a Python start where jq does (CR-278).
• A session starts in about half the time: SessionStart, which Claude Code waits for before its first response, went from 1630 to 900 ms at startup and from 1680 to 950 ms after a compaction (alternating runs against the previous code, on a copy of a 26,000-violation metrics database), same banner. On macOS each pack skill cost a python3 start to compute a relative path; the known-language registry was rebuilt by each of eight subshells; the healthcheck and the routing table ran an awk and a grep per skill; and the metrics database ran its fourteen migration probes although it carried this version’s schema stamp. Each is now done once or in-shell. The cost: SessionStart no longer re-runs the migrations over a database damaged by hand whose stamp still matches, the same trade the write hooks already made (CR-290).
• SessionStart sweeps the files of sessions that ended without a SessionEnd once a day instead of on every start: what it takes is a week old, and it cost each start a find and a Python start (32 ms). The sweep had no test; it has three now.
• The structural ratchet records function-level debt only: worst-function complexity, longest function and suppression count. A file that grew with a feature failed the ratchet until someone raised its budget: on this repository 270 of 473 raises moved file_lines alone, while LOC001, the rule that owns file length, is advisory. file_lines and fan_out are still printed by ratchet.py measure and dropped from an older row on its next update. A raise keeps one reason, the newest (git keeps the history), and ratchet.py check --tight refuses a mark looser than its file or a touched file with no row, so a pipeline can require the tightened mark to be committed. ADR-0025 amended (CR-288).

Fixed

• A compaction no longer restarts the session’s metrics. SessionStart fires again after a compaction, with the same session id, and it rewrote the session’s start time and deleted its write and violation tallies: a session that ran five days and compacted five times was measured from its last compaction, with every earlier write gone. After a compaction the session now keeps both; a session that starts, resumes, forks or clears restarts them as before (CR-296).

• craftsman-ci scans a file once however it is spelled on macOS. The key that deduplicates the scan folds //, and under bash 3.2 that fold kept a backslash, so src//Order.php and src/Order.php were two files and their findings counted twice. Linux runners, on bash 5, were not affected (CR-297).

• Pack skills no longer disappear while a session starts. SessionStart deleted every pack skill and copied it back, and Claude Code’s hooks reference says skill discovery runs before SessionStart hooks finish, so a session that looked in between could start without them (deduced from that timing, never observed). A skill a loaded pack still serves is now refreshed in place (CR-290).

• The pack manifest identity list from the second CR-278 pass never answered under bash 3.2, the macOS shell: ${path//\/\//\/} keeps the backslash there, so no lookup matched and every manifest was stat’ed on its own. Answers were right, the saving was not there. A test now fails when a manifest the list holds is stat’ed (CR-290).

• A new interactive Claude Code session was taken for a Codex session: its SessionStart carries model and no prompt_id, which the host detection read as Codex. The session binding went under ~/.codex, the startup healthcheck talked about Codex, and the cockpit mod’s /instincts pane said “craftsman-helper not found”. Found on 32 sessions of one machine since 4.12.3. Claude Code’s scratchpad_dir now names it, and model means Codex on SessionStart only with Codex’s permission_mode; the interactive payload is captured as a fixture (CR-291).

• A test run that failed no longer has its failure erased by a narrower run that passes. The suite went red on one test, the agent ran that test alone, it passed, and post-bash-test-verify.sh granted the verification evidence and cleared the failure: the plugin endorsed “flaky, passes alone” instead of refusing it. Each red run now stays outstanding until a run that adds no argument to it passes (hooks/lib/test_scope.py): a filter, a path or a test name may narrow the run, and which flags narrow is each runner’s business, so any added argument counts. Another suite going green does not answer this one either. The cost of that doubt is one re-run of the red command (CR-289).

• The structural ratchet measured every PSR-12 method (opening brace on its own line) as complexity 0 over one line, and a multi-line signature as its signature only: it closed the function on the brace. It now finds the body after the header, so PHP methods and functions with long parameter lists are measured. The ruler changed (instrument 3): a mark taken by the previous one is re-taken on the next touch, without failing an untouched file (CR-288).

• Re-taking a mark after an instrument change erased the row’s reason and the rule baseline’s counts stored with it, so inherited rule findings would have blocked again after an upgrade. Only the measured numbers are re-taken now (CR-288).

• A test command that exits 0 no longer grants verification evidence when it tested nothing: an npm script that only echoes, a suite with every test skipped, PHPUnit with zero assertions. Packs declare the wording in a new empty_run_markers capability, each marker taken from a real capture in tests/fixtures/test-runs; the skill’s set-verified is refused until a run that tested something passes (CR-255).

• A plugin update inside a session left the session binding on the old plugin root, so the cockpit mod ran the previous version’s helper (/instincts printed a usage line in its pane). The binding now follows the root the hooks run from, and the pane names the helper it ran when it fails (CR-279).

Removed

• config/default-config.yml. It said it was copied to ~/.claude/.craft-config.yml on first run; no code has read it since the v4 configuration format, and it described that file in the pre-v4 one (version: "2.1", a packs: mapping). The configuration follows schemas/craft-config.schema.json and /craftsman:setup.

v4.13.1 - 2026-10-20

A refusal no longer offers a craftsman-ignore marker that the rule ignores (CR-230). LAYER004 recognises the Domain under any root namespace your composer.json declares, not only App\ (CR-244). The FAQ and both READMEs now say which PHP rules hold on any framework (CR-242).

Upgrading can refuse a file that 4.13.0 let through: raw SQL in a Domain namespace under a root other than App\, outside a /Domain/ path. To phase it in, set LAYER004: warn for that directory in its .craft-rules.yml.

Fixed

• LAYER004 (raw SQL or DQL inside the Domain) recognised a Domain namespace only as App\Domain, so a project whose composer.json declares another root (Acme\, a Slim or Laravel application, a monorepo package) passed it outside a /Domain/ path. It now reads the root from the psr-4 map, as LAYER001 to LAYER003 already did, through one shared reader in the PHP pack (CR-244).
• The FAQ said language rules “only activate for the packs you enable”. Every shipped pack judges its own files whatever the stack setting says, and the setup’s framework question and the pack’s Symfony name read as “Symfony only” to a PHP developer on Slim. The FAQ and both READMEs now say which PHP rules hold on any framework, which two rule behaviours know Doctrine, and that stack switches no shipped pack’s rule; tests/core/test-doc-claims.sh reads the pack manifests and the namespace reader before it reads the documents (CR-242).
• A refusal offered a way out the gate then refused: SEC001 ended on “Use // craftsman-ignore: <RULE_ID> to suppress”, a marker SEC001 to SEC003 never honour (never_ignorable: true), the post-write JSON and the project-wide pattern said the same, and post-write’s stderr claimed no SEC rule takes a marker, false for SEC004. rule_marker_advice now reads the manifest: the marker is offered only to the rules that honour it, the others are named as “No marker silences …: fix the code.”, in stderr, in the JSON, in the warning actions, and in the exported doctrine (no marker). The subagent gate let a marker hide SEC001; it honours the manifest like the write gates (CR-230).

v4.13.0 - 2026-10-19

JavaScript gets the craftsman rules (.js, .jsx, .mjs, .cjs, native JavaScript and jQuery included), SEC004 refuses unescaped values reaching an HTML sink in TypeScript and JavaScript, the instinct review pane ships as the craftsman-cockpit companion mod (ADR-0031), and the hooks follow Claude Code’s recent changes: background test runs, the Task tools, a write gate that fails (CR-218 to CR-220, CR-226, CR-231).

Upgrading can refuse a JavaScript file that 4.12.3 wrote without a word. To phase the rules in on an existing codebase, set them to warn for a directory in its .craft-rules.yml.

Fixed

• A test suite run in the background never counted as verification evidence: Claude Code 2.1.277 removed TaskOutput, the only event that carried its result. On 2.1.302 the run ends as a task notification and UserPromptSubmit fires on it, so post-bash-test-verify.sh now also listens there (async) and reads <task-id>, <status> and the exit code, tied to the Bash that started it by task id. Captured, not documented for shell tasks: see tests/fixtures/hosts/PROVENANCE.md (CR-218).

• /craftsman:team, /craftsman:plan and the team-lead agent required TaskCreate/TaskUpdate/TaskList, which Claude Code no longer offers on Opus 4.8, Sonnet 5, Fable 5 and newer without CLAUDE_CODE_ENABLE_TODO_TOOLS=1. Each now says what to do without the Task tools: coordinate through messages and keep the ledger in the reports, as the agent teams documentation prescribes (CR-219).

• A write gate that timed out, was killed or could not start let the write through. pre-write-check.sh and config-protection.sh now declare onFailure: "block" (Claude Code 2.1.295); older builds ignore the key (run on 2.1.294). pre-push-verify.sh stays advisory (CR-220).

• The PHP001 auto-fix wrote a file PHP refuses to compile when code shared the opening line: <?php echo 1; came back with declare(strict_types=1); below it (“strict_types declaration must be the very first statement”). The declare now goes right after the tag and that code moves below it; a first line that is not a real opening tag (<?phpx) is refused instead of rewritten. php -l judges the result (CR-226).

• On Grok, instincts approve refused .grok/skills, the one directory Grok reads skills from: instinct_skills.py kept its own list of host directories with Claude Code’s and Codex’s only. The destinations now come from hooks/host-capabilities.json, which declares user_skills_dir for Claude Code and Codex; global promotion on a host that declares none (Grok) is refused instead of guessed.

• The suite’s shared assertions could give the wrong verdict on a long text: echo "$text" | grep -q under pipefail reports the writer’s SIGPIPE when grep stops at the first match, so assert_contains failed on a text that held the needle (macOS CI) and assert_not_contains passed on one that held the forbidden text. Measured on a 1 MB text: 100 wrong verdicts out of 100, none with a here-string, which they read now (tests/core/test-assert-helpers.sh).

Added

• JavaScript gets the craftsman rules: .js, .jsx, .mjs and .cjs, native JavaScript and jQuery included. A src/domain/order.js importing ../infrastructure/db was written with no rule at all while the same file as .ts was refused. The javascript language of the react pack now runs LAYER001, LAYER004, SEC002 and SEC003 through the same function bodies as TypeScript, so the two cannot disagree, plus ESLint at Level 2, the protected linter configs and the test runners (mocha added). The TypeScript-only rules (TS001 to TS003) and SEC001 (secrets, repository security rather than code quality) stay out of it (CR-231).

• SEC004, TypeScript and JavaScript: an HTML sink fed by a value the code did not write as a literal (innerHTML, outerHTML, document.write, insertAdjacentHTML, jQuery .html(), dangerouslySetInnerHTML, and interpolated or concatenated markup passed to .append() and its siblings). DOMPurify.sanitize(...) is accepted. Unlike SEC001 to SEC003 it is ignorable with a stated craftsman-ignore: SEC004, because “a variable reaches a sink” is a heuristic.

• ADR-0031: function-hook mods are a companion surface for Claude Code, never a gate. A mod lives in mods/<name>/ as its own plugin, reads and writes through bin/craftsman-helper only, and registers no tool that could reach a decision reserved for a person.

• craftsman-cockpit mod: /instincts opens a pane listing the project’s candidate instincts with their evidence, in Wilson-bound order, with Approve and Reject buttons wired to instincts approve|reject (#45). Install: /plugin install craftsman-cockpit@ai-craftsman-superpowers.

• The instinct pane explains each candidate: the rule’s wording, pack and default severity, the acceptance rate with refusals split between craftsman-ignore and config, the last fix date, what Approve and Reject do, and a preview of the exact skill Approve writes.

• A learned skill whose corrections recorded no context carries the rule’s own wording as its pattern instead of “see the rule definition”.

• craftsman-helper instincts review (hooks/lib/instincts_review.py): the review queue as JSON (candidates with evidence, approved instincts), refreshed like candidates; repository text passes the same single-line filter a generated skill uses.

• tests/mods/test-mods.sh: the ADR-0031 rules on every mod, each proved able to fail on a fixture, plus claude plugin validate and claude plugin test when a claude binary is present.

Changed

• LAYER001 and LAYER004 also read require(...) and import(...), not only ESM from. A TypeScript domain file that reached infrastructure through require was let through before and is now refused.

• /craftsman:metrics step 9 reads instincts review and presents each candidate from its fields (wording, severity, refusal split, last fix, evidence, the exact skill Approve writes), the same data as the cockpit pane, on every host. Repository text in the queue is quoted as data.

• instincts approve, review and promote take the skills directory as an optional argument: left out, it is the current host’s, so the skill no longer spells a directory per host.

• scripts/native-manifests.py keeps only the root plugin in the Grok catalogue: no other host loads a mod.

• A mod’s version lives in its marketplace entry only, which scripts/bump-version.sh already carries.

v4.12.3 - 2026-09-28

Bugfix release: the PHP analysers report a run that gave no verdict, PHPStan never runs without its pinned configuration, and the CI comment heading agrees with the job’s exit (CR-211, CR-212). No rule changes.

Security

• PHPStan no longer runs when its pinned configuration cannot be written. The fallback ran it bare, and a bare PHPStan auto-discovers the repository’s phpstan.neon, whose bootstrapFiles run PHP (CR-212).

Fixed

• PHPStan and deptrac report a run that gave no verdict as ANALYSER001, like the ESLint, dependency-cruiser, errcheck and clippy adapters. A fatal PHPStan error, a deptrac run that failed before analysing (a missing depfile) and a run the budget stopped all left the gate as silent as a clean file. deptrac’s exit 1 counts as a verdict only when it printed a finding line. A clean deptrac run still declares no coverage of LAYER001 to LAYER004: exit 0 with nothing printed is also what a depfile that does not cover the boundary produces, and the regex keeps reporting then (CR-212).
• The CI comment heading agrees with the job’s exit. A report that scanned no file outside --changed-only read “Passed” while the job failed with exit 2; the heading now comes from adapter_compute_exit, and a zero-file comment says whether the diff held nothing to validate or the run did not happen (CR-211).

v4.12.2 - 2026-09-28

Bugfix release: the P2 findings M1 to M18 and I1 of the review of main eb54d13 (CR-171 to CR-178), and macOS latency ceilings set from measured spread (CR-179). One new advisory rule, ANALYSER001; no rule becomes stricter.

Upgrading

• Configuration: /craftsman:setup now writes a v4 file (v: 4, a scalar stack, strictness, guided). A pre-v4 file (version: "1.0" with a stack: mapping) was silently read as fullstack; the healthcheck now names it as a warning with the keys the resolver ignores. Rerun /craftsman:setup to migrate. A v4 file with an invalid value is an error.
• Custom rules declared in .craft-config.yml now run before the write as well as after it. A severity: block rule refuses the write instead of refusing the file once it has landed. An edit to a file that already violates such a rule is refused before the write, as pack rules already are; the rule baseline mark still demotes inherited occurrences. The hook message gains a line N: prefix.
• Rust with clippy trusted: a clean clippy run now supersedes RUST001 and RUST005 as packs/rust/pack.yml declares, so an unwrap is reported as the advisory CLIPPY001 instead of the blocking RUST001.

Security

• The secrets scan reads the repository it is given. .github/scripts/secrets-scan.sh listed tracked files relative to the target but let grep open them relative to the caller’s working directory, so a key in the target could come back SUCCESS. The target is now canonicalised and entered before any read (CR-177).
• Exported host gates run whatever the plugin root is called. The grok-hooks export spliced the raw root into the command body, so a root containing $, " or a backtick was expanded or split and the gate exited 127 without running. Each manifest command is rebuilt word by word with the root quoted; a manifest command that is more than plain words is refused at export instead of being written with another meaning (CR-177).

Added

• ANALYSER001 (advisory, rules/core.yml): an analyser that gave no verdict is reported. A crashed or stopped ESLint, dependency-cruiser, errcheck or clippy left the gate as silent as a clean file. The message names the tool and its exit status, never its stderr (CR-174).
• dashboard.py <db> --score [DAYS] (through craftsman-helper dashboard --score 7): the quality score over the last DAYS days, the DAYS before, and the trend.

Fixed

• Custom rules: one pass, rules_check_custom, shared by pre-write (on the would-be file), post-write and ci/craftsman-ci.sh. Each rule is reported once, at its first matching line, with severity resolved per file. tests/adapters/test-parity.sh checks the three front-ends at block, warn and ignore (CR-171).
• Rust: an external #[cfg(test)] mod tests; opened a test range that ran into the body of the next production function, whose .unwrap() lost RUST001 in the scanner, the hooks and the pipeline. The range ends on the item’s own ; or closing } (CR-172).
• Analyser coverage reaches the flush. errcheck and clippy declared the rules they answer for from inside a command substitution, and the declaration died with the subshell: an errcheck finding came out twice, a clean errcheck left GO006 standing, a clean clippy left RUST001 in place. Adapters now return an @covered <RULE> record that the hook and the pipeline apply before the flush (CR-172).
• errcheck runs under sa_timeout with the per-file budget. Only its two verdicts (exit 0 and 1) answer for GO004 and GO006; a fatal exit or a stopped run leaves them to the regex (CR-172).
• Semantic fix witness: the content hash that proves a file changed between two verdicts was looked up by directory, so a run on src/Domain/B.php became the witness for an unchanged src/Domain/A.php, and a CLEAN on A recorded a fix. haiku_runs records each run’s exact path (additive file_path column), and a finding with no recorded content for its own file stays open (CR-173).
• Quality score: one formula, quality_score in hooks/lib/dashboard.py (findings per write: blocked 1, warned 0.3, each fixed correction gives back 0.6). /craftsman:metrics computed its own score from action='fix', a value the corrections table never holds, so the fix bonus was always zero (CR-173).
• SubagentStop gate: rule severities are honoured. It never initialised the rules engine and add_warning bypassed rules_severity_for_file, so a rule set to ignore still reached the main loop and a block rule was filed as a warning (CR-174).
• Final review scope includes untracked files that .gitignore does not exclude. A class created during the session and never staged was absent from the review that looks for new classes without tests (CR-174).
• /craftsman:setup Step D takes the canonical baseline with craftsman-ci baseline, which records rule violations as well as structure, so inherited debt reports as warnings instead of blocking the first edit (CR-175).
• config_validate in hooks/lib/config.sh checks a config against the schema with the resolver’s own reader; the healthcheck config row uses it (CR-175).
• doc-writer and ui-ux-director no longer open on a shell command their tools allowlist refuses; they start from the context their caller provides. The turn-budget suite fails when an agent body prescribes a shell command without Bash in its tools (CR-176).
• security-pentester no longer isolates into a worktree, where the uncommitted changes it audits are absent. The turn-budget suite refuses worktree isolation on any agent that reviews or audits (CR-176).
• The Mikado method, the refactor and legacy skills, the legacy-surgeon agent and the characterization example no longer prescribe git reset --hard or a path checkout to undo an attempt. A mark taken before the attempt reverses exactly what the attempt changed, and the user’s uncommitted and untracked work survives. tests/core/test-attempt-revert.sh runs every documented sequence on a throwaway repository (CR-176). The skills exported to Hermes carry the same correction: the committed export was regenerated without a drift check, so it still prescribed git reset --hard, and tests/adapters/test-hermes-plugin.sh now fails when regenerating it changes a file.
• An unreadable CI report is never commented as Passed. The shared comment formatter fell back to zero counters while the job failed with exit 2; it now renders Craftsman Quality Gate -- Error, checked for github, gitlab, bitbucket, jenkins and generic (CR-177).
• The PHPStan diagnostic example checks the trust_project_tools consent and calls Level 2 active only after a probe shows a finding (CR-178).

Changed

• ADR-0023 gains an amendment recording what shipped: the test-failure wake-up, the evidence gate and its exemptions, a single monitor, and a pre-push hook that only warns (Hermes is the one host that refuses a push). README (both mirrors), SECURITY.md, references and guides are aligned (CR-178).
• macOS latency ceilings are set from 30 measured runs of the runner’s own spread instead of a guess, and tests/perf/test-hook-latency.sh fails when a ceiling exceeds 1.5 times its quiet reading, so a ceiling cannot drift into meaninglessness (CR-179).

v4.12.1 - 2026-09-27

Bugfix release: the Hermes gate findings B6 to B8 of the review of main eb54d13 (CR-170) and their Strix follow-up, a Python pack false positive, and a repository layout fix. No configuration or rule changes.

Security

• Hermes terminal gate: the command is read the way a shell runs it. echo ok;git push, env git push, sh -c "git push", eval git push, $(git push) and a git alias for push all went through while git push was refused. Operators count even glued to a word, wrappers and assignments are stripped, nested shell text is read, aliases are resolved, and a push or commit the reader cannot place is refused as unknown.
• Hermes terminal gate: a push is judged on what it publishes. After a pass on HEAD, git push origin unsafe published another branch’s tree. Every refspec source must carry the judged tree; --all, --mirror, --tags, glob refspecs, push.default=matching and remote.<name>.push rules are refused because their sources cannot be listed. Deleting a remote branch still passes.
• Hermes terminal gate: every gated git call of a compound command is judged (Strix review). Only the first was, so git push origin HEAD; git push origin unsafe published a tree nobody judged. Several pushes are each judged; a commit next to a push in one command is refused, since the commit the push would publish does not exist yet; a push naming a ref that does not exist says so.
• Hermes conclusion gate: a CI report is a verdict only when it parses, carries its summary, agrees with its exit status and covers the changed source files. An unparsable report or a zero-file report with exit 2 was read as no finding and recorded a pass; it is now an unknown verdict, and the conclusion waits. A turn that changed no file of a known language still passes. A language registry that cannot be read is an unknown verdict too, never a turn with nothing to judge.

Fixed

• The Python pack’s WARN-PY001 counted the commas of a return annotation as parameters: def resolve(verb, args, where) -> tuple[str, list[str]] was reported as a function with four or more parameters. The pattern now stops at the closing parenthesis.

Removed

• .codex/config.toml is no longer in the repository. It was a contributor’s own Codex project layer (it set a Claude Code flag in Codex shells) committed by mistake, next to .codex-plugin/, the manifest Codex actually installs. .codex/ is ignored like .grok/.

v4.12.0 - 2026-09-27

Native install on the three hosts that load plugins (Claude Code, Codex, Grok), a Grok write gate that actually runs, and per-host session isolation. Hermes keeps its own plugin manifest (plugin.yaml).

Upgrading

• Grok: run bin/craftsman-grok-install again (or craftsman-ci export --target grok-hooks --into ~/.grok/hooks). The gate that runs is now the global ~/.grok/hooks/craftsman.json; a project .grok/hooks file from 4.11.0 still needs grok --trust to run.
• Codex: install from the native entry point (codex plugin marketplace add BULDEE/ai-craftsman-superpowers, then codex plugin add craftsman@ai-craftsman-superpowers) and trust the handlers in /hooks. Installing never grants trust.
• Skills and scripts that read the metrics database from a shell: resolve it with bash "$(craftsman-path bin/craftsman-runtime)" metrics. The ~/.claude/craftsman-metrics-db-path bridge is a Claude Code fallback only; native Codex and Grok sessions never read it.
• /craftsman:healthcheck names the export command when a gate is missing, behind this install, or written by another install.

Added

• Grok native install (.grok-plugin/plugin.json, .grok-plugin/marketplace.json) and bin/craftsman-grok-install, which installs the plugin and writes the global gate. Grok lists a plugin’s hooks/hooks.json as hookType: file and runs none of it on a fresh process (measured on 1.0.34 and 1.0.40), so the gate is exported from the same manifest instead of typed twice. It judges write and search_replace before disk and keeps pre-push-verify.sh. When no other review CLI is installed, the semantic review falls back to grok -p.
• Codex native entry point (.codex-plugin/plugin.json, catalogue in .agents/plugins/marketplace.json). The native loader reads the 22 skills and 14 handlers without the Claude manifest. Codex 0.155.1 omits hooks from the portable root plugin.json format, so the package ships no competing root manifest.
• All 12 agent missions ship as ordinary files before the first session. scripts/native-manifests.py generates the Codex and Grok manifests and --check fails on drift between the six pack agent copies and their sources; scripts/bump-version.sh runs it.
• bin/craftsman-runtime: one resolver for the current host and session store (metrics), used by skills and one-off queries.
• Grok slash names: /name, except /plan, /loop and /workflow, which Grok already owns and which stay /craftsman:name.
• The shared hooks/hooks.json matchers also name Grok’s write tools, and the healthcheck gained a write-gate row: ok when the gate’s owner marker matches this install, the export command otherwise.

Changed

• Every session store is bound to its host and session. A validated binding from the hook payload wins over inherited environment variables, Grok bindings are recovered from all supported aliases after a hook reload, and an unbound native session reports missing state instead of reading another host’s data. Metrics and correction persistence never bypass validation when the store is unavailable: the write gate still judges the code.
• The session context is resolved in one Python process instead of several helper processes per hook.
• Host facts live in hooks/host-capabilities.json only. The gate exporter (ci/host_hooks.py) reads each host’s gate_file and gate_export row (timeout, native environment names, tool aliases, conditional handlers, data directory) and derives the events a host does not fire from its events_loaded. A test fails when a host name, host environment name or host tool name is typed in the exporter again.
• craftsman-ci export --target codex-hooks is refused and writes nothing. Codex runs the plugin’s hooks/hooks.json natively once trusted and reads user or project hooks only from hooks.json or config.toml next to a config layer (Codex hooks), never from .codex/hooks/*.json: the file this target wrote was read by nothing.
• bin/craftsman-grok-install reads grok plugin list --json to know whether this checkout is already installed, instead of matching the wording of an install error, and prints the checkout’s origin and commit before trusting it.

Fixed

• Grok’s default hook timeout is 5 seconds and fail-open. The Grok export alone sets timeout: 15 on every handler. hooks/hooks.json stays without a timeout, so Claude Code and Codex keep their 600 second default. The export sets each host’s own root and data variables (GROK_PLUGIN_* or PLUGIN_*) and still sets CLAUDE_PLUGIN_*, which the engine scripts read on every host. A Codex gate does not carry GROK_*. The gate file is replaced atomically (mkstemp in the same directory, then os.replace), keeping the existing mode.

• Each generated gate names the install that wrote it. The healthcheck is ok when the marker matches, and names craftsman-ci export --target <host>-hooks when the same install is behind. A 4.11.0 gate with no marker is a warning, and SessionStart adopts it, when its CLAUDE_PLUGIN_ROOT is this install. Any other root is an error that names both paths and the export command, and the file is left untouched. The export, the healthcheck and the refresh share one relative path, .<host>/hooks/craftsman.json. craftsman-grok-install still exports the gate when the plugin is already installed, and prints the installer’s own output on success.

• Session lifecycle stores are isolated per native session: start, write, verify, failure, compact and end read and write the same store, and a parent session’s sentinel is left intact (#103).

• Pre-write caches are scoped to the bound session. A cache filled for one store could answer for another after the store changed between two pack_loader_init calls.

• Grok config protection covers the host’s own hook configuration, so the model cannot relax the gate through an edit.

• Hermes exported skills expand the native helper paths.

• Hook libraries import their siblings under the Python 3.9 floor.

• The Linux latency ceilings in tests/perf/test-hook-latency.sh were inside the spread of one commit on ubuntu-latest. They are now 1.35x the quiet reading and at least 1.15x the fast one, still under twice the quiet reading, so a 50 percent regression still fails.

• /craftsman:healthcheck no longer warns about the write gate on every Claude Code session. The row warns only where the host’s capability row records a trust step (Codex: review the handlers in /hooks), and is ok where plugin hooks run on install.

Security

• Test evidence is granted from shell grammar, not from text separators. hooks/lib/command_grammar.py lexes the command with shlex, so a quoted or escaped runner (printf '%s\n' 'hello; ./run-tests.sh --quick') no longer sets verified, which gates a push. Runners after &&, by path, and through python -m or npx stay qualified.
• Redirections are part of the command, not separators. Before this release, pytest -q 2>&1 lexed as 2>, &, 1, so a failing run kept the evidence green; &>, >/dev/null 2>&1 had the same hole, and |& read as one word hid a pipe. < and > are now lexer punctuation, |& is a pipe, and a command sent to the background (pytest -q &) grants and revokes nothing, since its status is the shell’s.
• A runner fed by a pipe (echo n | ./run-tests.sh) no longer grants the evidence: it ran on input the model chose. A failure there still revokes.
• The Grok semantic review runs with the read-only allowlist of Grok’s headless guide (--tools read_file,grep,list_dir). The previous denylist named the shell tool run_terminal_cmd while hook payloads name it run_terminal_command; an allowlist with a wrong name fails closed.
• Config protection judges the file a write REACHES, whatever its spelling. A bare relative path, //, /./, an inner .., a symlinked parent directory and a case change (.Claude/Settings.json, PHPStan.neon, an upper-cased plugin path) all reached a protected file with exit 0 on Claude Code and Grok. Each path is now joined to the payload’s cwd, resolved physically, and classified case-insensitively.
• Under bypassPermissions the gate’s own configuration (.craft-config.yml, .craft-rules.yml, .craftsman-baseline.json) is denied instead of asked: in that mode an ask proceeds without the user seeing it, and one write of the global config could set hooks.disabled for every later session. In the default mode it is still put to the user. If you run /craftsman:setup in bypass mode, edit the file yourself or approve it outside bypass mode.
• The plugin’s own data is protected like its code: registry caches, session state, session bindings and the ~/.claude/craftsman-* bridges. A forged registry cache had turned a denied phpstan.neon into an allowed one. A shell command can still write there (see SECURITY.md).
• A registry that cannot be built refuses the write instead of judging it against an empty list of protected configs; an unwritable cache directory with no earlier cache compiles a private copy first.
• A skill’s set-verified is refused after a failing test run, until a passing run clears it: the evidence a failure revoked can no longer be restored by asking.
• Session bindings (~/.<host>/craftsman/sessions/*.json) are swept after 7 days with the other session files; nothing removed them before.
• A session started from another host’s shell carries both hosts’ ids; skills now resolve the innermost one (the most recent binding) instead of whichever host a fixed order named first.
• A gate is never written through a symlink: a symlinked gate file or gate directory is refused and its target left untouched. A first write honours the umask (0644 under 022) instead of the 0600 of a temporary file.
• SECURITY.md gains “Host limits that weaken the gate”: Grok’s fail-open hook timeout, Codex’s trust step, and shell-written files.

Fixed (test suite)

• A test whose cd fails inside the plugin repository now stops, and no test may run a git write there (tests/lib/test-helpers.sh). With /tmp unwritable, tests/core/test-hostile-repo.sh fell back to the repository and committed its fixtures on the current branch. Its work directory now comes from mktemp under $TMPDIR.

Documentation

• README and README.fr rewritten for adoption: one install block per host (Claude Code, Codex, Grok, Hermes), a “first ten minutes” path that provokes a refusal on purpose, and a host support table read from hooks/host-capabilities.json. The Codex and Grok badges read their qualified version from that matrix, so they cannot drift from it.
• New docs/guides/codex-quickstart.md and docs/guides/grok-quickstart.md (install, verify, limits, uninstall), on the model of the Hermes one.
• Every command now has a worked example: agent-design, ci, loop, mlops, rag, scaffold and spec had none. COMMANDS-QUICK-REF.md says who starts each command and links its example.
• tests/core/test-command-docs.sh fails when a skill has no example, when a document names a command that does not exist, when the quick reference misses a command or its example, when the README’s invocation split disagrees with the skills’ frontmatter, and when a host that runs no plugin hook lacks its gate command in either README.

v4.11.0 - 2026-09-20

Changed

• The verification evidence is revoked whenever a failing command ENDS on a test runner, not only when the runner is the whole command. A session that ran echo 1 > pytest.rc && ./bin/pytest -q, saw it exit 1 on a red suite, and kept verified true was measured on 2026-09-20; verified gates a push, so doubt revokes it. The session is still woken with “REGRESSED” only when the failure can be attributed to the runner alone; a compound failure revokes quietly and says how to grant the evidence again. If your habit is to chain a command before your test runner, expect to re-run the runner on its own to restore the evidence.

Added

• Host adapters, one core (ADR-0029, campaign of 2026-09-15). The write gates read a Codex apply_patch (V4A, multi-file, moves, @@ anchors, End of File) before it lands and refuse the gate’s own configuration with deny where the host cannot ask; test runs are decoded per host from the shapes the hosts actually send (hooks/lib/tool_result.py), and a host whose shell output carries no exit code grants and revokes nothing; every hook names its session from its payload (session_files_bind); the doctrine export owns one delimited block of AGENTS.md; pack skills ship as regular files and learned skills may land in .agents/skills; agents export as Codex roles (craftsman-ci export --target codex-agents); the challenge skill collects its context with craftsman-context review; the semantic review has a backend port (claude-cli, codex-cli, none) and each run row names its backend; a per-host event matrix (hooks/host-capabilities.json) and a host row in the healthcheck say what each host loads and observes; a Copilot adapter honours the documented contract, surfaces still to qualify; a fresh install from the built archive is tested; every handler carries a statusMessage. Fixtures under tests/fixtures/hosts/ are captured from the real CLIs with their provenance (tests/fixtures/hosts/PROVENANCE.md), which also records what each host was seen NOT to do.

• Codex qualified by Codex (2026-09-20): a Codex session installed this branch natively (codex plugin marketplace add, which reads the Claude marketplace manifest, then codex plugin add) and reported what it found. Four defects fixed, each with a witness seen red first. model without prompt_id names Codex and a string transcript path no longer names Claude Code: run through its app server, Codex 0.154.0 sends a REAL transcript path where a project hook of the same version sent null, so that session called itself claude-code and wrote Claude Code’s bridge. A shell with CODEX_SESSION_ID or CODEX_THREAD_ID names Codex, so craftsman-healthcheck no longer reports “unknown host” about its own host, and the session-bridge row is read per host instead of judging every host by ~/.claude. The rules store honours TMPDIR and the plugin data directory before /tmp, which a sandboxed Codex could not write, turning mktemp: mkdtemp failed into the refusal the model read. The Codex row of the capability matrix records twelve event kinds (Interrupt included), that installing and enabling a plugin does not trust its hooks, and that a background hook cannot force a continuation there. Two limits are now stated rather than implied (docs/reference/hooks.md, README): the gate judges the host’s write TOOLS, so a file written by a shell command the model runs is caught by CI and the pre-push gate, not before disk; and async delivery is the host’s, which Codex does not offer.

• A host’s hooks file is generated from the manifest, never typed twice: craftsman-ci export --target grok-hooks (and codex-hooks) writes the handlers with ${CLAUDE_PLUGIN_ROOT} expanded and carried in each handler’s environment, the events that host does not fire dropped, and the conditional handlers that are Claude Code’s dropped. Grok needs it because it discovers a plugin’s hooks/hooks.json and runs none of it; the generated file was replayed on the real CLI and gives the same refusals. /craftsman:healthcheck gained an agent-roles row: on Codex it counts the craftsman roles in that host’s home and names the export command when there are none, since installing the plugin does not write them and, written, all twelve are offered to spawn_agent. README documents the native install on both hosts, including the steps installing does not perform (trusting the hooks, exporting the roles) and what each host does not offer.

• Grok 1.0.30 as a host, measured (audit of 2026-09-15): the write gates judge its write and search_replace tools (they exited 0 in silence on the captured envelope), host_detect names grok from the envelope (workspaceRoot and a lowercase hookEventName; it was read as Copilot because both carry a timestamp) and from GROK_SESSION_ID, the capability matrix has a grok row and the healthcheck describes any host from that row instead of a case per host, and run_terminal_command results carry exit_code, so the verification loop is live there. The mirror now holds one table of host tool names to a kind of write (WRITE_TOOL_KINDS), and the pre-write gate no longer branches on a tool name. What Grok does NOT do is recorded too: it discovers a plugin’s hooks/hooks.json and loads none of its handlers (headless, project plugin enabled; tests/fixtures/hosts/PROVENANCE.md), so on Grok the engine runs only from a project or global hooks file, and “compatible Grok” is not claimed.

• Hermes: a git push between two conclusions waits for the conclusion gate. adapters/hermes/pre-tool-call.sh now reads terminal and refuses a push (and a commit under strict) unless pre-verify.sh’s last verdict is a pass on the tree that would be published; the verdict is recorded with that tree (terminal_gate.py, <git-dir>/craftsman-verdict), so a pass on one tree does not authorise another, and with no verdict at all the push waits. The matcher becomes ^(terminal|write_file|patch)$. tests/adapters/test-hermes-terminal-gate.sh covers no verdict, a refused turn, a pass, a different tree, a pipeline, git -C, and the two strictness levels; every refusal was seen red before the branch existed.

Fixed

• The engine holds no list of languages, as CLAUDE.md has said since the language registry: the FileChanged matcher carried a glob the event does not support (*.php|*.ts|*.tsx, so the hook never fired; it now watches the common source roots and the registry decides the language), the session banner found only composer.json and package.json (it now reads every pack’s entry_markers and compares pack names), the codemap and the write mirror kept their own extension and marker lists (they read the registry), the metrics extractor took a language name in place of the declared metrics_dialect (it takes a dialect only, and the symfony pack declares php-like, which is what it always received), the engine kept the one list of rule ids it says it must not hold (relaxed_in_tests: true is declared on the rule, compiled as the registry’s seventh column, and asked through rule_relaxed_in_tests), and the PHP namespace reader and the Python AST checker lived in hooks/lib (each is in its pack). tests/core/test-no-language-literals.sh scans hooks/ and ci/ and fails on any language name or extension outside a comment: fourteen hits before, zero after, two of them kept on an explicit allowlist with a backlog line each.
• A baseline row had two owners with two cadences: the structural mark tightened on every green pass, the rule counts were written once by craftsman-ci baseline and never moved. Debt that was paid kept its count, so the same debt coming back was reported as inherited on the very write the ratchet refused as a regression. A green pass now tightens the rule counts to what it observed (rule_baseline.py tighten), and a git mv keeps the file’s mark instead of photographing the renamed path at whatever state the first write left it in.
• Five session-state keys were read and written by nothing: design_used (the design-pass exemption in the bias detector never fired; a /craftsman:design prompt now sets it), writes_count (the TaskCompleted evidence gate saw zero writes; it counts the session-writes file), and agent_invocations, team_type, completed_tasks (sessions.agents_spawned held [] on every row; it carries the agent types the subagent gate records). The README rows saying the plugin blocks a design decision now say it warns, which is what it does.
• ci/craftsman-ci.sh exited 0 on a checkout missing rules-engine.sh, pack-loader.sh or precedence.sh: it scanned nothing and reported clean. The four libraries the gate is made of now load through one function that exits 2 naming the missing file; the standalone severity table and config parser, reachable only in that state, are gone.
• Five published claims the code contradicted: the Level 2/3 budget (15s per file, 30s per project, not <2s), pre-push-verify.sh warns and does not gate, Levels 2 and 3 are off until trust_project_tools, all eighteen CRAFTSMAN_* switches are named in SECURITY.md, and the rules table in docs/ci-integration.md (13 of 66) is replaced by the export command that prints the live list. tests/core/test-doc-claims.sh reads the code first and the document second.
• plugin.yaml, the Hermes manifest at the repository root, is now the fifth file scripts/bump-version.sh tracks, so --check and release-guard.sh refuse a release that leaves it behind. It was off the list, and 4.9.0 and 4.10.x shipped with hermes plugins reporting 4.8.1. The manifest is at 4.10.3 again and tests/meta/test-release.sh carries the drift fixture.

v4.10.3 - 2026-09-14

A security patch and the tail of the whole-plugin review.

Fixed

• never_ignorable held only on machines with PyYAML. On a machine without it (the macOS system python, the CI runners) the fallback reader hands the string true, the compiler compared it to the boolean, and SEC001, SEC002, SEC003 compiled as ignorable: an ignore marker silenced a hardcoded secret on the hook, the pipeline and the Hermes write gate alike. The compiler now reads the YAML boolean whichever reader produced it, and the registry test compiles the manifest both ways.
• A capability key the engine does not read is refused at compile time, with the key named on stderr, instead of being skipped silently.
• The ratchet is inert until a project opts in, and anchored on the file rather than on the shell’s directory: a hook fired from src/ of a marked project no longer skips it.
• The dogfood test walks every shipped script and judges each finding through the rules engine; seven functions over the structure thresholds in the Go and Rust packs and the GitHub adapter are split into named helpers.

v4.10.2 - 2026-09-14

The rest of the whole-plugin review’s blocking findings, each seen red first.

Fixed

• The Haiku verifier no longer grades itself. Any reply that was not the findings token was read as CLEAN and closed every earlier finding on the file as “fixed” with the file unchanged. Only the exact token is a clean verdict now; anything else is unavailable and closes nothing; a CLEAN closes a finding only when the file changed since the run that raised it.
• A secret cannot be silenced with a marker, on any front-end. SEC001, SEC002, SEC003 are declared never_ignorable in the manifest; every marker reader asks the registry first.
• An Edit is judged before it lands, like a Write, and a gate that cannot run refuses the write instead of letting it land with a warning.
• Session state is one file per session. A session’s end no longer deletes another’s pending findings, and one project’s patterns no longer surface in another.
• The pre-write gate judges through the packs. Its detectors were a fork (App hardcoded where the pack reads composer.json’s psr-4 root): an Acme\ project passed pre-write and was refused post-write. The would-be file is laid out under a mirror of the workspace and judged by the same validators post-write and CI run.
• One global configuration layer (~/.claude/.craft-config.yml) for the hooks and CI alike, and none for the Hermes gates: a layer the same uid can write outside the gated turn must not shape a verdict.
• Hermes: a gate file hidden from git is still the gate’s own, and a turn with no remote is scanned back to the root commit.

v4.10.1 - 2026-09-13

Added

• A finding can be judged right or wrong, and each rule’s acceptance is reported (#44). /craftsman:metrics reports acceptance per rule and proposes a relaxation under the threshold. A verdict is about a finding, not an outcome, so it lives in its own verdicts table with two human writers: the reason spelled out in the suppression at the moment of the decision (craftsman-ignore: RULE (wrong: why) or (debt: why)), and metrics_record_verdict from the review after the fact. No path writes a verdict the developer did not spell out.
• Hermes: the write-time promise, opt-in (#21). write_gate: on refuses a write_file or patch before it reaches disk on SEC001 (a hardcoded secret) and LAYER001 outside test paths. SEC002 and SEC003 stay at the conclusion gate: line-local regexes fire on the documented mitigations.

Fixed

• pre-push-verify.sh ran on every Bash call. hooks.json carried the if filter beside matcher, where Claude Code ignores it. Moved onto the handler; the schema job refuses any other key at matcher level.
• Documentation re-measured against the code. Agent count (12: 6 core plus 6 from the packs), ADR count (31), which skills the model may start (7 of 22), hook latency (measured, not “under 50ms”), analyser budgets (15s per file, 30s per project, not “under 2s”), pricing per model, the GitLab artifact shape, and a lesson that described a feature removed in ADR-0024.

v4.10.0 - 2026-09-13

Twenty-nine pull requests: the campaign that closed every open issue, then the fixes from a whole-plugin review by four reviewers crossed with the maintainer’s knowledge base on guardrails, evals and production feedback loops.

Fixed

• Every Haiku verification used to end the real session. The headless claude -p verifier fired the plugin’s own SessionStart and SessionEnd hooks: the real session’s state was deleted on every verification, and 1460 of 1599 sessions in 30 days had no write at all. The correction loop was measuring its own verifier. Both hooks step aside under the guard the verifier already sets; proven on the real consumer.
• agent_hooks: false never reached a hook. Claude Code exports an option as CLAUDE_PLUGIN_OPTION_<KEY> with the key uppercased; every reader read the lowercase spelling. The README’s “turn it off with agent_hooks: false” is true from this release.
• An approved instinct was written where Claude Code never looks. .claude/skills/craftsman-learned/<rule>/ is one level below the depth a project skill is loaded from. approve writes to .claude/skills/learned-<rule>/ and refuses any other depth.
• A scoping decision is no longer recorded as a fix. A directory .craft-rules.yml demoting a rule, or a baseline mark holding it, counted as fixed and three such files made a candidate for a learned skill. Recorded scoped and overridden now, which the instinct gate reads as rejection.
• The pre-write gate resolves severity through the rules engine. The same file, rule and .craft-rules.yml gave “BLOCKED” before the write and nothing after it. One authority now; the advisory list it held is gone.
• The gated party no longer reconfigures the gate. A Write to .craft-rules.yml, .craft-config.yml, .craftsman-baseline.json, .claude/settings.json or the plugin’s own code passed config-protection.sh. The gate’s own files go to the user’s permission prompt; Claude Code’s settings and the installed plugin are denied.
• The instinct gate counted directories, not files. MIN_DISTINCT_FILES compared directory globs; 23 fixes under one glob made no candidate.

Added

• An eval suite for the routing table (#48). evals/: eight cases over the six model-invocable skills, a counter-example where no skill may fire, a discrimination case, graded by tool_used and regex only. Run with scripts/run-evals.sh, never from tests/run-tests.sh: every case is a model call on your account.
• Packs validate their files whatever the stack says (#35), the advisory default is declared once in the manifest (#37), one brace walk for every brace-delimited pack (#38), --changed-only in CI (#50), per-environment latency ceilings, the structural ratchet re-taken once.

v4.9.0 - 2026-08-27

Added

• Bias detection language cascade. Bias patterns moved out of the hook into one data file per language, loaded by a registry. English is the single curated language and keeps its direct warning; twelve others sit at one same tier behind it, carrying recall-oriented lexeme lists whose hits are not warnings. The hook prints an adjudication note and the model already reading your prompt, holding the whole session, either surfaces the warning in your language or drops the note silently. No second model, no subprocess, no network call on the prompt path. A false positive there is invisible, which is what makes high recall affordable, and adding a language is two data files and zero code. Language tags follow BCP 47, so fr-CA or zh-Hant register like any other; before this, such a file registered nothing while the hook still exited 0.

• Actionable verdicts. Measured on 18748 real violations: twelve rules fired 5624 times in 30 days and produced zero corrections, in either direction. Two causes, both fixed. A rule now names what it found, because the rule that named an identifier was acted on 167 times while the one that named nothing was acted on never. And both output paths now offer scoping before silencing: the blocking path had named suppression as the only way out, so a rule wrong for a whole directory was suppressed once per file instead of scoped once, and the advisory path carried no action at all.

• scoped and open outcomes in the metrics. Scoping a rule was indistinguishable from giving up on it, and a verdict that reached the end of a session with no outcome was invisible. Both are now recorded, which is what makes the two fixes above measurable rather than merely plausible.

• Verifying the instrument, in the knowledge bundle. Five instrument failures were observed in one session and none was a defect in the code under test: a check that read a comment instead of the emitted message, a pattern that matched inside the corrected name and reported the fix as the defect, a fixture that never triggered the rule it tested, an all-time aggregate that described a problem solved a month earlier, and a verification whose output was piped away unread. Code is exercised constantly and fails loudly; an instrument is exercised once, silently, and its failure looks like success.

v4.8.1 - 2026-08-11

Changed

• tests/core/test-config.sh split into 21 section functions. The last whole-file span in the top three structural offenders: complexity 102 to 10, longest span 505 to 30 lines, 90 assertions before and after. Two oversized intermediate functions were blocked during the campaign and both were re-split instead of suppressed.

v4.8.0 - 2026-08-11

Changed

• Structural debt campaign, first production run of /craftsman:loop. The two worst production offenders in the ratchet baseline were extracted under their marks with behaviour intact (full suite green at every iteration): hooks/session-metrics.sh worst-span complexity 37 to 8 and longest span 131 to 16 lines (duration, write counter, violation counter and summary builder each became a function); hooks/lib/dispatch-context.sh complexity 28 to 11 and longest span 97 to 27 (one emitter function per context section, early returns instead of nesting). The file_lines rises (131 to 149, 97 to 110) are the function boilerplate paid for it and are recorded in the baseline with that reason; every other mark tightened one-way.

v4.7.0 - 2026-08-11

Added

• /craftsman:loop, a bounded verification loop. The repeat layer on top of the existing gates, with a stated bound rather than an open-ended retry.
• tests/core/test-gate-independence.sh. Auto mode becomes the default, and the test asserts each gate still decides on its own.
• A context footprint guide. What the plugin injects per session, measured rather than estimated.

Changed

• The advisory Haiku layer respects the effort dial, so a low-effort turn no longer pays for a review it did not ask for.
• /craftsman:team offers the native Workflow tool explicitly, and /craftsman:workflow documents how it maps onto the native /goal.
• /craftsman:challenge states its position against the native reviewers instead of leaving the overlap implicit.
• /craftsman:metrics publication is explicit, never a side effect.
• Three skills removed: agent-design, mlops and rag. The plugin ships 19 skills.

v4.6.4 - 2026-08-10

Fixed

• /craftsman:challenge returned nothing at all, one run in two. The skill forked into an agent capped at 20 turns. When the cap lands on a tool call the loop stops there and returns no text, and Claude Code substitutes the literal string Command completed for the missing result. No error, no partial, no retry: 23 of the agent’s first 38 recorded runs ended that way. The review now runs in the main session and fans out to reviewer subagents when the scope is large.
• The review could not see what it was reviewing. A forked skill carries neither the conversation nor the attachments. A review invoked with seven screenshots received seven [Image #14] tokens and zero images.
• The architect agent reviewed a tree in which the diff did not exist. It declared an isolated worktree, which is a clean checkout of a commit, so the uncommitted changes its injected git diff HEAD pointed at were absent from it.

Added

• Every agent that caps its turns now carries a delivery contract: emit the deliverable as soon as the evidence justifies it, reserve the last third of the budget for writing, name what was not covered, never end on a tool call. The cap was never the whole defect: an agent that keeps no budget for writing fails at any cap.

v4.6.3 - 2026-08-09

Fixed

• The deptrac adapter had never produced a single verdict. It called a formatter that exists in no version of deptrac. The call failed, the output was swallowed by 2>/dev/null and || true, and DEPTRAC001 was never emitted once. Every layer violation this plugin ever reported came from the import regex. Nothing caught it because no test asserted that the analyser produced output, only that the code path ran.
• A project could not configure the severity of a layer verdict. deptrac findings arrived under a code no .craft-config.yml addressed, so block, warn and ignore all produced the same outcome.

v4.6.2 - 2026-08-09

Fixed

• /craftsman:team gated native teams on a tool Claude Code had removed, so every session silently degraded to parallel subagent dispatch.

Added

• Level precedence between validation levels. A rule a static analyser owns is deferred, never dropped: if the analyser times out, crashes, or is configured to ignore the rule, the regex finding is re-emitted. No verdict is not a clean verdict.

v4.6.0 - 2026-08-08

Added

• Packs own the rules they enforce, instead of a central export holding every rule for every stack.

v4.5.0 - 2026-08-08

Added

• Initialising a ratchet baseline requires a written reason, and records it. A scoped exemption with no stated cause is how a ratchet quietly stops ratcheting.

Fixed

• The structural metrics measured the gap between functions, not the functions.

v4.4.0 - 2026-08-08

Changed

• Packs declare the languages they cover, and the engine holds no list of its own. Breaking for pack authors.

Fixed

• The python and bash packs never ran in CI. The scan walked paths neither of them lives in.
• One PHP file silenced the empty-gate guard for every other language.

v4.3.0 - 2026-07-29

Fixed

• The orchestrator told the model to run skills the model cannot run.
• The subagent quality gate validated nothing. Its header claimed it validated; it did not.
• A review could silently run a model tier below what the docs promise.

v4.2.0 - 2026-07-28

An audit release. Every finding below was reproduced before it was fixed, and each carries a test that fails when the fix is removed. The recurring shape is one defect wearing different clothes: a control that reports success when it did not run, and a measurement that reports a number the code does not have.

Security

• A cloned repository could write anywhere the developer could. ratchet.py wrote its baseline with write_text, which follows a symlink, so a repo shipping that path as a link to ~/.claude/settings.json had the target overwritten on the first edit. Writes now go through a sibling temp file and land with os.replace, which acts on the link and never on its target.
• A cloned repository could switch the gates off. hooks.disabled resolved from the project file first, so a clone could open its first session with every gate silent. A repository may tune what the gates check, never whether they run.
• A psr-4 key could disarm the layer rules. _layer_ns_regex escaped backslashes only, so a root such as A(pp\ made every layer grep exit 2, which reads as “not this layer”. LAYER001 to LAYER003 stopped firing repository-wide, in the hook and in CI.
• A file name could address the reviewer. Names from git diff and tool_input were spliced verbatim into the Haiku review prompts. Names outside a plain-path charset are dropped, and the drop is reported.
• A learned skill carried unsanitised text into the model’s context. A newline in pattern_summary or file_pattern opened a second YAML frontmatter block in the generated skill. Both are collapsed, capped and stripped of the fence character, and the skills destination is confined to the project or ~/.claude.

Fixed

• CI reported a pass on a pipeline that inspected nothing. The default scan path was src/, so a Laravel app/, a monorepo packages/ or a Next.js app/ matched nothing and the run exited 0 with files_scanned: 0. Every common source root is scanned now, discovery is counted separately from scanning, and an empty discovery fails loudly.
• Three blocking rules reported findings the code did not have. SH002 and WARN-SH001 counted braces without knowing which were shell, so a 14 line function holding an embedded python snippet was reported as 128. PY001 grepped raw lines, so a docstring beginning with an English article blocked writes on prose. SH001 inspected the first 20 lines only. All four measure from a proper scanner now.
• The exported doctrine covered 15 of 38 rules and described three of them wrong. PHP003 was documented as “private constructor plus factory” while it enforces “no public setter”; PHP004 as “no setters” while it enforces “no new DateTime()”; TS002 as “readonly by default” while it enforces “no default export”. A teammate on Codex read one rule and was blocked by another.
• The test suite trained the learning loop on its own fixtures. tests/run-tests.sh set no CLAUDE_PLUGIN_DATA, so four months of runs recorded their fixtures as production violations: 3704 of 15588 violations sat on a path this repository does not have.
• Session counters were decorrelated from reality. SessionEnd re-queried the violations table over a window the length of the session, which counts every other session’s rows: 236 sessions in one day reported 16236 warnings against 1353 actually recorded.
• Level 2 and 3 could not run and said they were clean. Every analyser was capped at 2 seconds, below the cold start of all of them, and || true flattened the timeout into success.
• Rules vanished in silence without python3. Six checks shell out to it and each returned quietly, so the packs reported every file clean on a machine that has none. sqlite3 gets the same treatment in the metrics layer.
• Whole classes of file were never validated. post-write-check allow-listed the characters a path may contain, so every Next.js App Router dynamic route, every route group and any accented path went unchecked. The rule is inverted to refuse only what is dangerous.
• Bitbucket published a green PASSED on an unreadable report. The verdict now travels in the result field and its reason in the free-form details line.
• metrics_project_hash hashed $PWD, filing one repository under a different project for every subdirectory worked from, and metrics_file_pattern recorded absolute paths, including the developer’s home directory.

Added

• adapters/, a third front-end over the same core. hooks/ serves Claude Code, ci/craftsman-ci.sh serves pipelines, and adapters/<host>/ serves other agent runtimes. The first is adapters/hermes/: a pre_verify hook that refuses a conclusion rather than a write, because blocking a write assumes somebody can break the loop it creates, and an autonomous agent has nobody. It derives its scope from git rather than from the agent’s self-report.
• Test paths degrade the rules whose premise is production code. LOC001, NEST001, PARAM001, GOD001, CTRL001, SEC001 and SEC002 become warnings under tests/, spec/, __tests__/, __mocks__/, fixtures/ and factories/. A long setup and a credential in a fixture are the normal shape of a test, and blocking on them is what teaches a developer to reach for craftsman-ignore.
• A source column on violations and corrections, so the next contamination is a DELETE rather than an archaeology exercise.

---

v4.1.2 - 2026-07-27

CI duration, which on this project is CI cost.

Changed

• Adaptive polling in the portable timeout. The fallback slept a full second per call while almost every call finishes in milliseconds, adding 163s to the macOS job. It now polls at 50ms, backing off to 250ms after a second and 1s after ten. Measured over 50 fast calls: 972ms per call before, 64ms after.
• One timeout implementation instead of three. hooks/lib/portable-timeout.sh is the single source; the static-analysis dispatcher, the test helpers and the test runner all source it.
• The workflow cancels superseded runs. Without a concurrency block, pushing twice ran two full matrices for one answer that mattered.

Added

• A Python floor job. The test matrix used 3.12 on both runners, so it could not see a module that only parses on 3.10+. A separate job imports every hook library under 3.9.
• The runtime floor is stated in both READMEs: Python 3.9, no GNU coreutils required.

---

v4.1.1 - 2026-07-27

Every failure here was a “works on my machine” dependency the repository had been carrying unnoticed.

Fixed

• Level 2 and Level 3 static analysis never ran on a stock macOS. All five analyser invocations were wrapped in timeout, which comes from GNU coreutils and is not installed by default on macOS. The call failed with 127, the || true swallowed it, and the plugin reported a clean gate having run nothing. sa_timeout now uses timeout or gtimeout when present and falls back to a background job with a watchdog.
• The instinct pipeline was dead on a stock macOS. hooks/lib/instincts.py annotated a parameter with syntax Python evaluates at runtime from 3.10, and /usr/bin/python3 on a Mac without homebrew is 3.9. Fixed with from __future__ import annotations.
• sed -i '' is BSD syntax and GNU sed reads the empty string as the script. Fixed in the pack validator test, which failed on Linux, and in bump-version.sh, which would have silently skipped a version bump for any contributor on Linux.

---

v4.1.0 - 2026-07-27

Security fixes, rule calibration, and twenty test suites the runner never called.

Security

• The CI gate no longer fails open on a malformed report. It parsed the report with stderr discarded, so a report that was not valid JSON produced an empty summary and exit 0. It now fails closed.
• Command injection through a channel number closed. Config values landed in an arithmetic expansion where bash evaluates an array subscript as a command. Refused at the config boundary and again at each sink.
• Grep flag injection closed at three sites: a pattern beginning with - was read as an option.
• secrets-scan fails closed. It reported “no secrets found” for every condition that makes a scan produce nothing. It now proves it can enumerate tracked files, read their content and read history before any empty result counts as clean.
• Six credential shapes added to the scan, and every .env suffix rather than only .local and .production.
• hotspot_analysis.py bounded. A 400MB file with no newlines took 952MB of RSS. It now shares the write-time gate’s 2MB cap.

Changed

• TS002, TS003 and PHP003 default to advisory. Each has legitimate exceptions a regex cannot see, and blocking a write on those only teaches suppression.
• PHP002 skips Doctrine entities. A proxy extends the entity, so a final entity breaks lazy loading: the rule was asking Symfony projects to break their own persistence layer.
• TS002 skips files a framework resolves by default export (page, layout, route, middleware, and others), and both TS rules now take a line-level craftsman-ignore.
• The layer rules read the project’s root namespace from composer.json. They matched App\Domain literally, so every project that renamed its root namespace passed all three layer rules by construction.

Fixed

• The CI quality gate no longer hangs. Severity resolution walked from the file’s directory up to the project root, but both stop conditions are absolute paths and CI is handed relative ones.
• CI agrees with the hook on ignore, and resolves severity per file so a directory-level .craft-rules.yml applies in the pipeline as it does in the hooks.
• consolidate-metrics.sh reports its failures instead of reading a locked source as “0 rows to merge”.
• pack_sync_symlinks only removes what a pack put there.

Testing

• Twenty test suites the runner never called are now wired in, including the entire hostile-repository security suite. The suite reported 213 passing while a third of the files on disk sat unexecuted. test-runner-integrity.sh now fails when a test function is defined and not called.
• A failing subtest says why. All 26 wrappers used to discard their output.
• Guard tests can no longer pass against deleted code. Every absence assertion is gated on a positive control only a live tool can satisfy.

---

v4.0.1 - 2026-07-27

Corrects two settings that did not do what the repository believed.

Added

• Per-task model tiering, actually implemented. Every skill declares the cheapest model that can do its job (haiku for mechanical work, sonnet for bounded pattern application, opus for judgment spanning files) alongside its effort level. The tiering had been documented since v1 but never implemented: no skill declared a model, so every skill ran on whatever the session happened to be set to. Tiers are aliases rather than pinned model ids, so they follow model releases and a whole tier can be remapped with ANTHROPIC_DEFAULT_*_MODEL.

Fixed

• effort used values Claude Code does not recognise. Eleven of twenty-one skills declared quick or heavy, a project convention that predates the key.
• Skills reference was missing healthcheck, legacy and workflow. The table is now generated from the frontmatter it documents.
• Hooks reference documented 8 of the 13 wired events, omitting the TaskCompleted evidence gate.
• Installation and advanced guides still walked users through the knowledge-rag MCP server, removed in 4.0.0.
• CI validators required frontmatter keys Claude Code treats as optional, and read keys from the whole file so a YAML sample inside a skill body was mistaken for a declared field.

---

v4.0.0 - 2026-07-26

A clean break to a native-first, self-learning, security-hardened plugin. Requires Claude Code 2.1.218 or later. Rationale: ADRs 0016 to 0027.

Added

• Structural ratchet. A committed .craftsman-baseline.json holds each file’s structural high-water mark (approximated complexity, file lines, longest function, import fan-out, suppression count). A file you touch may improve or stay equal, never regress. The mark tightens automatically on a green pass and only loosens through a documented craftsman-ignore, itself counted and ratcheted. The hook and craftsman-ci run the identical check, and CI never writes the baseline. Untouched files and relaxed directories are never evaluated, so legacy is not punished for debt it already had. Ships advisory: set RATCHET001: block to make it a hard gate.
• Correction learning closes the loop. Recurring fixed corrections (3 or more across 3 or more files) become candidate instincts; /craftsman:metrics surfaces them for human review; approval generates a learned skill with provenance. Instincts stay project-scoped until the same rule is approved in 2 or more projects. Promotion is never automatic.
• Adversarial design panel. Three headless contradictors (YAGNI, invariants and aggregate boundaries, feasibility) attack the design during /craftsman:design phase 2, before any code exists. Every objection must land in a retained or dismissed table.
• Persistence craft. New knowledge pillar plus rules verified in hooks and CI: LAYER004 (raw SQL or a database client inside Domain), DB001 (SELECT *), DB002 (migration without down()), DB003 (query inside a loop).
• Security rules SEC001 to SEC003: hardcoded secrets, dynamic eval, and SQL built by concatenation, with doctrine routed automatically when one blocks.
• Knowledge as an OKF bundle. Every concept carries Open Knowledge Format v0.2 frontmatter, and a deterministic lookup routes a rule or tag to the concepts explaining it. Zero embeddings, zero index, zero external service.
• Level 1.5 semantic validation. .lsp.json activates a language server only when the binary is already installed on the machine.
• Deterministic verification loop. A failing test run revokes verification evidence and wakes the session on regression; a TaskCompleted gate requires evidence before a task can be marked complete.
• Situational onboarding and guided mode. Project init observes the repository, then asks at most four plain-language questions. With guided: true, every block explains its doctrine.
• Living legacy audit. LEGACY-AUDIT.md is committed and diffed between runs, with a mandatory “looks bad but is actually fine” section. Nothing is ever installed for you.
• Outcome contracts. Every skill states its outcome, its done-when condition, and the evidence that proves it. The validator enforces all three.
• Cross-harness doctrine export. craftsman-ci export renders the active rules as AGENTS.md, .cursor/rules/craftsman.mdc and .github/copilot-instructions.md.
• Local dashboard. /craftsman:metrics --dashboard aggregates every tracked repository into a self-contained page served on localhost.
• Context budgets and kill switches. Every injection is capped and every hook individually disableable.

Changed

• All workflows are skills. commands/*.md became skills/<name>/SKILL.md. User invocations are unchanged: /craftsman:design still works exactly as before.
• Semantic verification is headless. DDD verification moved from Stop (where it was dead) to PostToolUse and runs in a Haiku subprocess. Zero main-context cost, and agent_hooks: false still disables everything.

Security

Hardened against a hostile repository: opening or editing one must not execute its code. Each fix has a test in tests/core/test-hostile-repo.sh that reproduces the attack and asserts it fails.

• Level 2 static analysis is off by default (breaking). The gate resolved and executed vendor/bin/phpstan and node_modules/.bin/eslint from the working directory, so a shell script planted at that path in a cloned repository ran arbitrary code on the first PHP edit. Running a project’s analysers means running its code, so it is now consent: set trust_project_tools: true in your own global config. A repository cannot grant it to itself.
• External packs are declared by the machine owner only. Their validators are sourced as shell code, so reading that path from a project config meant opening a cloned repository executed its code at session start.
• No Python source splicing in the GitLab adapter: an attacker-chosen filename reached the source text of a python3 -c call.
• Rule ids are constrained. They are YAML keys from repository-controlled config and were used raw as filenames.
• Dashboard output is escaped and the server answers for exactly one file.
• Symlinks are refused. Git tracks symlinks as real entries, so src/Thing.php pointing at ~/.ssh/id_rsa is a legal commit and the audit followed it.
• Reads are bounded. Measuring a 94MB file cost 506MB of memory, and a size cap alone does not help because a symlink to /dev/zero reports size 0.
• Verification verdicts are parsed by shape before reaching the session. The headless verifiers read files the plugin did not write, and forwarding their reply verbatim is an indirect prompt-injection path.
• Shipped CI template hardened: actions pinned to verified commit SHAs, least-privilege permissions, anchored paths.

Removed

• commands/ flat command files, output-styles/, and the v3 agent hook wrappers.
• The knowledge-rag MCP server, its skill, the Ollama dependency, and 115MB of dependencies. Superseded by the OKF bundle.
• Support for Claude Code below 2.1.218.

---

v3.9.0 - 2026-07-14

Added

• Global config fallback. ~/.claude/.craft-config.yml written by /craftsman:setup is now actually read by hooks. Resolution order: project config, then plugin option env vars, then the global file, then hardcoded defaults.

Fixed

• CI executable-bit check no longer fails on sourced libraries.
• bump-version.sh exits 1 when a tracked file matches neither the old nor the new version, instead of printing a soft warning that let a file silently drift two releases behind.

---

v3.8.0 - 2026-07-14

Added

• Config protection hook. Blocks writes to single-purpose linter and architecture config files, so an agent cannot silently loosen a rule instead of fixing the flagged code. Multi-purpose files (pyproject.toml, package.json) are intentionally excluded.
• Hook profiles. Session-level opt-out of secondary and costed hooks. The core quality gate, bias detection and session bookkeeping deliberately do not support it.
• Security invariant tests. A sandbox and witness-marker suite proving the protection hooks never execute injected code, never touch files outside their contract, and fail open on malformed stdin.
• Prompt injection defense baseline: external content relayed by hooks is data, never instructions.
• French README, FAQ, migration guide, and troubleshooting guide.

Changed

• CI hardening: all actions pinned by commit SHA, least-privilege permissions, dynamic script discovery, and the test suite running on an Ubuntu plus macOS matrix.

---

v3.7.0 - 2026-07-06

Added

• /craftsman:legacy. Four modes for regaining control of an inherited codebase: audit (rank hotspots, produce LEGACY-AUDIT.md), cover (characterization net before touching anything), untangle (break dependencies), migrate (strangler fig). Consumes existing analysis-tool output via --from instead of recomputing a weaker signal.
• legacy-surgeon agent and the legacy-takeover team template.
• Zero-dependency hotspot ranking (churn times complexity), as a fallback for teams with no external analysis tool, not a competitor to one.
• Legacy and refactoring knowledge pillars: characterization testing, strangler fig, Mikado method, code smells, communicating technical debt.

---

v2.6.0 - 2026-03-29

Pack ecosystem expansion.

Added

• Pack validation script validating pack structure, manifest and hooks before publishing.
• External pack support loading community packs from arbitrary paths.
• Pack creation guide with examples.
• Pack skeletons for Go, Rust and Python, ready to fork.
• /craftsman:scaffold pack generates a pack skeleton interactively.

---

v2.5.0 - 2026-03-29

Knowledge-RAG MCP server migration. (This subsystem was later removed in v4.0.0, replaced by the OKF knowledge bundle.)

Added

• Knowledge-RAG MCP server moved to a standalone directory, with stdio and HTTP transport.
• /craftsman:scaffold api-resource for API Platform 4 resources.
• Pack-specific test suites, and CI pack-loader integration.

---

v2.4.0 - 2026-03-29

Core plus pack architecture.

Added

• Pack loader reading pack manifests and registering agents, commands and rules.
• API craftsman agent for API Platform 4 resources.
• Unified scaffold command replacing the separate entity, usecase, component and hook commands.

---

v2.3.0 - 2026-03-29

Distribution optimization.

Added

• Distribution ignore list, bringing the plugin under 1 MB.
• Startup dependency check for Python 3, jq and SQLite.
• Agent hooks opt-out.

Fixed

• Knowledge base is lazy-loaded instead of read at startup.

---

v2.2.0 - 2026-03-29

Security and quality.

Security

• All database writes use parameterized queries.
• Hook entries in .claude/settings.json are schema-validated at startup.

Added

• Atomic commit enforcement: the Stop hook warns above 15 staged files.
• Monorepo sampling: above 100 changed files, a representative sample per directory is validated instead of every file.

---

v2.1.0 - 2026-03-29

Rules engine and CI adapters.

Added

• Custom rule engine with 3-level inheritance (global, project, directory).
• Short-form rules and long-form custom rules with regex and per-language targeting.
• CI adapter system for 4 providers: GitHub Actions, GitLab CI, Bitbucket Pipelines, Jenkins.
• /craftsman:ci to export CI config and check status.
• Circuit breaker with 3 states, protecting the plugin’s own external service calls.
• Pack template variants.

---

v2.0.0 - 2026-03-28

Teams and onboarding.

Added

• Teams system with built-in templates for code review, feature implementation and security audit.
• Session onboarding with config summary and cost estimate.
• Pre-push verification on the Stop hook.

---

v1.5.0 - 2026-03-28

Agent fleet expansion.

Added

• 5 specialized core agents: architect, doc-writer, security-pentester, ui-ux-director, team-lead.
• Parallel agent execution via /craftsman:parallel.
• Pack agents: backend-craftsman (Symfony), frontend-craftsman (React), ai-engineer (AI/ML).

---

v1.4.0 - 2026-03-28

Sentry integration.

Added

• Sentry context fetching with a channel lifecycle and automatic cleanup.

---

v1.3.0 - 2026-03-28

Semantic intelligence and correction learning.

Added

• Agent hooks analyzing code changes for DDD and Clean Architecture compliance.
• Correction learning system: SQLite tracks when Claude corrects a violation.
• Metrics database, the foundation for 7-day and 30-day trend analysis.

---

v1.2.0 - 2026-03-28

Validation levels and metrics.

Added

• Multi-level code validation: regex (under 50ms), static analysis, architecture.
• Blocking hooks: the write is refused until the violation is fixed.
• Pre-write validation, so the check runs before the write rather than after.
• /craftsman:metrics quality dashboard.
• craftsman-ignore inline suppression syntax.

---

v1.1.1 - 2025-02-06

Added

• /craftsman:setup implementation, with a DISC mini-assessment in the wizard.

---

v1.1.0 - 2025-02-05

Fixed

• Version synchronization between manifest files.

---

v1.0.0 - 2025-02-04

Initial release.

Added

• 20 commands: 10 core, 2 PHP, 2 TypeScript, 4 AI/ML, 1 CI, 1 utility.
• 5 specialized agents.
• Hooks system: PreToolUse, PostToolUse and Stop validation pipeline.
• Knowledge base covering DDD, Clean Architecture, TDD and framework specifics.
• Optional Knowledge-RAG MCP server via Ollama for vector search.
• 3 built-in packs: symfony, react, ai-ml.