Release Notes

Finalize skill audit and fix

The /finalize skill was intermittently skipping the work-summary-writer agent before committing. Root causes identified and fixed: ambiguous "today's session file" lookup, no explicit check commands, vague process steps, no post-write verification, and fragile dependency ordering. The skill's Process section was rewritten with explicit bash commands and a hard gate.

Tuned for Claude Opus 4.7

DevArch's prompt surface — CLAUDE.md base template and agent definitions — has been tightened across the board to play well with Claude Opus 4.7's literal instruction following and verbosity profile. No new rules, no new agents — every change is a sharpening of existing language so 4.7 produces the right amount of output without padding or overreach.

Why a major bump

4.7 takes prompts more literally than 4.6. Rules with vague carve-outs ("use judgment") fire more aggressively; templates with required sections produce more verbose output by default. v3.0.0 retunes the surface for the new model. Behavior is preserved for 4.6 and earlier — the changes are strictly tighter, never looser.

Changes

• Prompt-literalism preamble added to CLAUDE.md.base and project CLAUDE.md. Sets the lens for every rule below: triggers fire unless overrides are explicit, templates collapse to one line per field when sparse, "use judgment" means prefer skipping.
• Rule 14 (mutation-verification trigger) — vague "use judgment: skip for documentation, config, or test-only changes" replaced with an explicit non-source-file exclusion list (*.md, *.yaml, *.json, etc.) plus a required-both-signals rule. 4.7 no longer fires the agent on docs that happen to mention "process" or "update."
• Rule 7a (Boundary Statements) — abstract noun list replaced with explicit path patterns (**/state/**, **/stores/**, **/reducers/**, **/projections/**, **/selectors/**, **/domain/**). Domain pattern gated on docs/ddd/notation.yaml existing.
• Rule 12 (test grading) — per-test RED/YELLOW/GREEN grading replaced with per-suite grading that mentions only failures. A session adding 30 tests no longer produces 30 grading blocks.
• work-summary-writer — adds an explicit short-form template for trivial sessions (≤2 files, ≤20 tool calls, no plan/ADR/blocker activity). Full template tightened: "one sentence per field" default, no padding, silent self-verification. capability-sniffer now invoked only when the summary contains domain-modeling vocabulary.
• mutation-verification — pick the 1–2 most likely domains for each file based on imports/path. Stop applying all seven domain treatments. Report format collapsed: clean scans get a one-line output; warnings list only the warnings.
• session-planner — "When DDD Doesn't Apply" carve-out moved to lead the DDD-Informed Planning section. Plain technical framing is now the default; DDD framing is a deliberate choice gated on the project actually using DDD.

Migration

Run devarch update in any project to pick up the new templates. No .devarch schema change. No CLI flags changed.

Multi-ADR review and the live event feed for screencasts

Multi-ADR review mode

/adr-review now accepts 2–4 ADRs in a single invocation. Single-ADR behavior (one arg) is unchanged. Multi-ADR mode adds nine cross-ADR checks that catch issues per-ADR review misses: cross-reference resolution, vocabulary census, "stable across" claim verification, open-question matrix, sequencing graph, AC coordination, seam walkthroughs, contradiction detection, and lifecycle/resource correctness. Capped at four because pair-check count grows quadratically.

/demo-events — live hook activity feed

A file-based event bus that visualizes DevArch's hook lifecycle in real time. Built for a Y Combinator screencast request.

• emit-event.sh — shared helper sourced by all hooks. No-op when .devarch-events.jsonl doesn't exist, so zero added overhead in normal sessions.
• Node SSE server on localhost:3377 with /events, /history, and /clear endpoints.
• Live timeline page — dark-themed full-page view, color-coded event types, auto-scroll, status bar.
• /demo-events skill — start/stop/clear commands for the demo server.
• All six hooks emit events at key transitions.

Hook fixes

• Session-start branch filter dropped — previous-session lookup was filtering by current branch and silently skipping sessions created on feature branches that had since merged to main. Now finds the most recent substantive session regardless of branch.
• git-commit.sh and git-assess.sh now cd to the repo root before doing anything, fixing failures when invoked from a subdirectory.

Rule 7b — Co-Located Wire-Type Sharing

When a client and a server share a wire protocol and live in the same repository under the same typed language, they MUST share the protocol's type definitions via direct import — not through duplication, hand-synchronized interfaces, runtime JSON schemas, or codegen.

The principle — Protocol drift between co-located client and server is mechanically preventable. A direct import makes a server-side type change either compile the client in the same commit or fail the type checker in the same commit. Any weaker coupling introduces a window in which one side is wrong and CI doesn't know.

Extraction guidance — Wire primitives (message envelopes, event shapes, discriminators, enums) live in a file with a documented invariant: no runtime-specific types (Buffer, fs.Stats, DOMException). Both sides import without dragging in a runtime they don't have.

Does not apply across repository boundaries (use a schema format), across language boundaries (use codegen), or to external-SDK public protocols where explicit versioning is the point. Promoted from a real incident in the Sharpee codebase where a shared types file dragged in Node-only types and broke the browser build.

Integration Reality (rule 12a) — the No-Stub-Under-Test rule

Closes a gap that let phases named after an integration ship with the integration deferred — the scaffolding was tested against a hand-written stub of the owned dependency, all tests passed green, and the real subsystem was never exercised.

• Rule 12a (Integration Reality Statement) — Before declaring an integration phase complete, the agent produces a statement: OWNED dependencies, EXTERNAL dependencies, REAL-PATH TEST per OWNED entry, and STUB JUSTIFICATION (each backed by a real-path test). Phases whose name contains integration, engine, runtime, sandbox, subprocess, database, migration, deploy require at least one REAL-PATH TEST executed against the production code path. "Carve-out" is never a valid modifier of "complete."
• work-summary-writer enforcement — When a session's phase name matches the keyword set, the writer scans the conversation for an Integration Reality Statement and refuses Status: COMPLETE if it is missing or if any REAL-PATH TEST entry is blank/deferred/carved-out.
• Distribution template sync — CLAUDE.md.base had drifted: it was missing rule 10 (ADR) added in v1.5.0 and rule 7a (Boundary Statements) added in v2.1.0. v2.2.0 syncs the template to the canonical numbering.

The principle — A test that drives a hand-written replacement for an owned dependency is a scaffolding test. Scaffolding tests cannot serve as the acceptance gate for a phase named after the integration. The system under test cannot be the thing you wrote to stand in for the system under test.

Boundary Statements (rule 7a) and the boundary-check hook

Adds rule 7a — a thinking step that precedes edits to cross-boundary modules (state projections, stores, reducers, domain modules, selectors). Analogous to Behavior Statements (rule 11) for side-effect functions, Boundary Statements force OWNER / SHARED / PROMISE / ALTERNATIVES articulation before per-consumer state quietly migrates into a shared module.

• boundary-check.sh and boundary-check.ps1 — new PreToolUse hooks that fire on Edit/Write to files matching state/store/domain/reducer/selector/projection patterns. Advisory (not blocking) — prompt the agent for a Boundary Statement before the edit proceeds.
• Session lifecycle SVG updated to show the new hook.

v2.1.0 shipped rule 7a to the project-root CLAUDE.md but missed the distribution template at CLAUDE.md.base. v2.2.0 corrected this. Re-run devarch update to pick up both rule 7a and rule 12a.

PowerShell 7+ hook support on Windows

DevArch hooks now run natively under PowerShell 7+ (pwsh), so Windows users no longer need WSL or git-bash at session runtime. All six bash hooks have PowerShell siblings with verified behavioral parity.

What's new

• Six new .ps1 hooks — session-start.ps1, post-tool-use.ps1, session-finalize.ps1, plan-gate-enter.ps1, plan-gate-check.ps1, plan-gate-exit.ps1. Each produces byte-identical session files, work logs, gate transitions, and stderr messages to its bash counterpart.
• jq dependency dropped on the PowerShell path. .ps1 hooks use built-in ConvertFrom-Json / ConvertTo-Json -Compress. Bash hooks continue to require jq.
• Parity harness (verify-parity.sh) drives both variants against 18 fixtures covering startup, resume, plan-gate transitions, work-log append, budget nudges, and the git-commit-without-summary warning.
• devarch install now detects host OS and deploys the correct hook set. On Windows, both .sh and .ps1 land in ~/.claude/hooks/; settings.json wires up exactly one variant.
• devarch switch-shell <pwsh|bash> — new command. Rewrites settings.json to the other variant without re-copying hook files.

Bash bugs fixed (uncovered during the port)

• session-finalize.sh: * glob inside double quotes never expanded — the hook was silently a no-op. Now unquoted.
• session-start.sh: grep "Tier" / grep "Budget" over the 8-line phase block matched the next phase's fields too. Added | head -1.
• session-start.sh, post-tool-use.sh: jq state-update calls were missing -c, producing pretty-printed JSON that diverged from the compact printf initial write.
• post-tool-use.sh: EDIT_COUNT=$(grep -c "…" || echo "0") produced "0\n0" when grep found zero matches, breaking the integer comparison. Rewritten.
• devarch CLI: for X in $(jq -r '.files | keys[]') on Windows git-bash included a trailing \r on every token because jq.exe emits CRLF, silently breaking uninstall/update/status. Loops now pipe through tr -d '\r'.

Breaking changes — None for existing Linux/macOS users. On Windows, devarch install now always copies both variants; prior .sh-only installs can be upgraded with devarch install (idempotent) or devarch update.

Trial license with IP protection

Adds a Trial License Agreement (docs/legal/TRIAL-LICENSE.md) covering two-week evaluation use with explicit IP protection clauses: no corporate reuse beyond the trial scope, no derivative works, and survival of confidentiality and IP terms beyond trial expiration. The website's license page surfaces trial terms alongside the full license. The full DevArch Methodology License continues to govern paid use.

Deprecate project-level hooks in favor of user-level hooks

devarch init and devarch update now detect and remove project-level hook entries in .claude/settings.json that overlap with DevArch's user-level hooks. Without this cleanup, both copies tried to fire and the project-level entry produced "No such file or directory" errors, since Claude Code stopped expanding ~ in hook commands. Project-level hooks remain supported for non-DevArch use cases — this only removes overlap.

Hook paths resolved at install time

Claude Code stopped expanding ~ in hook commands (likely a switch from shell invocation to direct spawn). DevArch now builds the hooks JSON dynamically using $HOME at install time so paths land absolute. Commit-agent script references updated to use $HOME for the same reason. Existing installs need a devarch update to pick up the new absolute paths.

ADR conversation gate and /architect-review

Rule 10 — ADR conversation gate

When a decision constrains future sessions — technology choice, boundary placement, pattern adoption, dependency direction, trade-off resolution — the agent asks "ADR-worthy?" and, on user confirmation, writes a four-section ADR (Context / Decision / Consequences / Session) to docs/adrs/NNNN-title.md. Numbered sequentially. Linked from the session summary's Key Decisions section. Trivial decisions (variable names, formatting, local refactors) are explicitly out of scope.

/architect-review skill

A 13-category architectural review tuned to the project's actual surface area, filtered by what's relevant. Categories: requirements, complexity, testing, documentation, security, dependencies, API surface, observability, data, CI/CD, cost, scalability, decision history.

Pre-session-audit context assessment

The audit agent now detects unorganized project context on first run (existing CHANGELOG, ADR folders, scattered notes) and offers a one-time assessment that seeds DevArch's structure without losing existing work.

Behavior Statements, Test Derivation, and Test Grading

Rules 10–11 rewritten — Replaced the "Functional and Behavioral Tests" policy directives with a three-step pattern: Behavior Statement, Test Derivation, and Test Grading. The old rules told Claude what to do ("write behavioral tests") but were routinely ignored, producing tautological and zero-mutation tests. The new rules give Claude a thinking process that makes bad tests structurally impossible.

• Behavior Statements — After writing side-effect code, Claude must articulate what the code DOES, WHEN, BECAUSE, and REJECTS WHEN in concrete, assertable terms. Each statement line becomes a test assertion.
• Test Grading — Every test is graded RED/YELLOW/GREEN before committing. RED (tautological, zero-assertion, mock-only) and YELLOW (asserts on return values or events instead of mutated state) must be rewritten. Only GREEN tests ship. (Per-suite in v3.0.0.)
• /dashboard skill — Generates a self-contained HTML project dashboard summarizing code health, test health, current and archived plans, session history, and open blockers.

Progressive Capability Activation

Tier model replaced with capability model. DevArch is now one product with progressive capabilities: base (always active), ddd-discovery, and domain-modeling. The three monolithic templates are replaced by CLAUDE.md.base plus two addons.

• devarch activate <capability> — New CLI command to activate DDD capabilities in a project. Appends the addon to CLAUDE.md and updates the .devarch capabilities array. domain-modeling requires ddd-discovery as a prerequisite.
• --tier flag removed from install, init, and init-all. devarch init always installs the base template.
• Capability-sniffer agent — New agent that runs after work summaries. Scans for DDD signals and suggests capability activation. Silent when nothing to suggest.
• New Coding Discipline section in the base template — invariants and variants, cohesive modularity, clear boundaries, documentation standards, command and event definition, functional and behavioral tests.

Audit and cleanup

Full audit of all DevArch components (skills, agents, hooks, CLAUDE.md directives, CLI). Removed duplicated lifecycle rules from the project-root CLAUDE.md, eliminating ~55 lines of redundancy. Updated project-profile.md to use current skill/agent names. Aligned docs/workflow/CLAUDE.md wording with the guardrails template.

Skills, hooks, and the plan-mode gate

An iterative series of releases that built out DevArch's skill surface, fixed work-summary skip logic, added the unified DevArch gate state machine, and recalibrated session-planner budgets for Claude Code's 1M context window.

• v1.1.9 — /finalize (/fin) renamed from /da-commit-remote. Session-planner phase budgets recalibrated: Small ~30→100, Medium ~75→250, Large ~120→400 tool calls.
• v1.1.6 — /ddd-assessment skill: scans a codebase for domain complexity and DDD readiness, recommends a capability tier with reasoning.
• v1.1.5 — /recap skill: on-demand recap of the previous session.
• v1.1.4 — Session-start hook now skips stub sessions and finds the last substantive session. All templates instruct Claude to present a 2–3 line recap at startup.
• v1.1.2 — Rewrote work-summary skip logic to eliminate ambiguous AND/OR conditions that allowed agents to invent fake skip reasons.
• v1.1.1 — Added /da-commit-remote, /da-commit-local, /da-status skills. Commit agents now evaluate the session for work summary needs, not just the current diff.
• v1.1.0 — Plan Mode Gate: Claude Code's EnterPlanMode/ExitPlanMode bypassed CLAUDE.md workflow rules. DevArch now enforces lifecycle compliance through three hooks and a unified .devarch-gate state file (session-init / planning / plan-review). Automatic plan archival from ~/.claude/plans/ to docs/work/ on Plan Mode exit. Read-only permission template auto-approves Read/Glob/Grep/Agent/WebSearch/WebFetch, leaving mutation tools requiring user approval.

Initial Release

• DevArch CLI with install, update, uninstall, init, init-all, status commands.
• Three tiers: guardrails, ddd-lite, full-ddd. (Replaced by progressive capabilities in v1.3.0.)
• Agent lifecycle rules via CLAUDE.md templates with session start/end workflows, planning, mutation verification, session checkpoints, and budget tracking.
• Agents: pre-session-audit, session-planner, work-summary-writer, session-checkpoint, mutation-verification, pattern-recurrence-detector, dev-context-detector, commit-local, commit-remote.
• Hooks: session-start.sh, post-tool-use.sh (work log + budget tracking), session-finalize.sh (pre-compact).
• Manifest-based deployment with SHA-256 tracking for safe updates.