#[v2.0.1] - 2026-03-22

#Features

• Implement EPIC-072 coaching stories and multi-story dev progress

#Chores

• remove pycache from git tracking
• remove duplicate STORY-553 (completed version in archive/)
• remove tgz build artifacts from repo and gitignore them
• add NPM-Publish.md to gitignore
• Add src/devforgeai/specs/business/ artifacts
• Sync operational folders with src/ tree and update QA/workflow state
• Checkpoint before STORY-536 development
• Checkpoint before STORY-536 development WIP state from STORY-468, STORY-469, STORY-471, STORY-535, STORY-544 and related QA/workflow artifacts.

#Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

#[Unreleased]

Post-3.0.0-beta.11 changes accumulate here. Per ADR-104 D1 §"3-release rollout window": the v3.0.0-beta.x line ships on the @beta dist-tag → v3.0.0 GA (@latest) → v3.1.0.

#[3.0.0-beta.11] - 2026-06-27

Status: Eleventh @beta pre-release. The window covers 58 PRs (#908–#1026) since the beta.10 tag (2026-06-21 → 2026-06-27). The bulk is the subagent handoff-pipeline port (a data-driven protected-dispatch registry plus per-unit onboarding), the incident-recurrence / merit-gate subsystem (fingerprint, ledger, recurrence check, prioritization), import-claude-skill analyzer evidence gates, continued /spec-sprint gate and contract hardening, and Codex-runtime parity. Tag v3.0.0-beta.11 to publish to the @beta dist-tag via .github/workflows/npm-publish.yml.

#Added

• Subagent handoff pipeline: build-subagent-handoff CLI with Phase-04 scoped-context gates (#910), generalized into a data-driven protected-dispatch registry (#911, #915); onboarded the handoff pipeline across dev Phase-03 (#959), unit2 (#961), unit3 QA (#963), system-architecture (#965), dev Phase-04 (#967), and unit6 dispatches (#971); spec-sprint Phase-04 handoff protection (#969) and phase-D subagent out-attestation enforcement (#973).
• Incident pipeline & recurrence (merit gate): incident-fingerprint and incident-ledger CLI commands (#924); incident-recurrence check CLI (B1 mechanism) wired into 4 producers with a gated count surface (#931, #934, #935); incident-prioritize hit-ratio ranking CLI (#987) and incident-prioritize-plan with a daily schedule workflow (#992).
• import-claude-skill analyzer: update-mode drift analysis (#977); Claude hook-settings parsing (#981); Claude agent-metadata parsing (#989); Claude command-conversion analysis (#999); import-strategy evidence (#1002); per-file remediation plans (#1023); analyzer evidence gates (#1026); the Codex Claude-skill import incident workflow (#939).
• /spec-sprint: backlog-readiness status (#975); Phase-00.5 merit triage (#976); Phase-04 custody commits (#953).
• CLI / framework: prose-quality standard for agent prompts and hook messages (#994); audit-overtrigger now detects COVERED via enforcement signals rather than a line registry (#995, #1011); added missing verify-source-ac-coverage test scenarios (#998).

#Changed

• Retired the spec-driven-research hand-maintained checkpoint in favor of CLI phase-state (#1013).
• Aligned the spec-sprint Phase-00.5 C1 verdict contract (#957) and clarified handoff test paths (#958).

#Fixed

• /spec-sprint: detect output-nested overall_status in completion Gates 3 and 4 (#922); harden dependencies and Phase-05 paths (#955); require evidence-backed closeout (#956); block Phase-06 when the CI-checks array is empty (#986); use --subagent coverage-analyzer not --cli-command in phase-05-qa Step 3b (#887, #919); remove the Phase-05 three-dot precheck (#1021); bound test-automator context to prevent first-dispatch overflow (#1024); guard non-string conviction payload text (#954).
• Incident pipeline: let symbol-bearing bugs reach exact_match in incident-fingerprint (#925, #927); incident-guard fails closed when the template guard cannot resolve the body (#926, #928); token-based --repo/--body-file extraction in the template guard (#932).
• Codex parity: refresh skill templates from Claude (#938); validate skill-loader metadata (#950); make spec-sprint dispatch reliable (#951); harden spec-sprint runtime gates (#952); fix spec-sprint lint wording (#1005).
• CLI / hooks: --project-root added to query-source-tree for argument parity (#914); dedupe velocity-monitor dual-path mirror writes to prevent false TOKEN-OPTIMIZATION-BIAS warnings (#916); coverage-record-result writes the full 64-char raw-bytes phase_state_checksum (#903, #918); allow source_refs, source_ac_ids, and command in the ac_list schema (#1000); relocate contract.schema.json to the shipped CLI package (#982, #1004); make pre-cli-staleness-guard.sh install-aware and exempt resolve-worktree-subcommand (#1019); correct stale extract_section ### claims in diagnose_dod_failure (#1017).

#Documentation

• Persist the subagent handoff-pipeline port plan (#908); correct the stale "parser stops at ###" justification post-#787 (#996); document spec-sprint source-tree regeneration (#1022).

#[3.0.0-beta.10] - 2026-06-21

Status: Tenth @beta pre-release. The window covers 108 PRs (#702–#904) since the beta.9 tag. The bulk is Codex-runtime parity, native worktree-isolation hooks, continued /spec-sprint gate/contract hardening (Phase-04 Red-before-Green, refactor-surface, dispatch-ledger), the conviction-evidence subsystem, per-story PR lifecycle, a configurable friction-reporting gate, and the ADR-145 anti-skip-ceremony retirement. Tag v3.0.0-beta.10 to publish to the @beta dist-tag via .github/workflows/npm-publish.yml.

#Added

• Codex parity & runtime: dispatch-ledger runtime (#739) and runtime pre-tool hook (#740) for Codex; collaborate response skill (#847); scripts-mirror guard registered for Codex commits (#841); spec-sprint completion gate registered for Codex hooks (#881).
• Worktree isolation: adopted native WorktreeCreate/WorktreeRemove hooks for session isolation (#859); Phase 05/06 worktree-anchoring guard added to /spec-sprint (#793); resolve-worktree-subcommand helper for self-developed CLI subcommands (#758).
• /spec-sprint gates & contracts: enforce Phase 04 Red-before-Green (#761, #775, #778); check-refactor-surface gate in Phase 04 (#759); gate mechanically-checkable ACs on test evidence not AC verdict (#902); dispatch-ledger gates phase-complete on mandated subagents via Condition C (#862); Phase 05 scanner dispatch gated on the source-code-changed predicate (#861).
• Conviction evidence: emit-conviction-worklog phase-05 emit path (#794) and self-injected identity fields (#898).
• CLI / framework: read-only audit-overtrigger subcommand for ADR-076 emphatic-prose classification (#901); pre-cli-staleness-guard to detect stale devforgeai-validate code (#899); derive-obs-id deterministic CLI subcommand (#823); render-sprint-board --init-board (#817); phase-record rejects the reserved --subagent=none sentinel (#804); incident-guard gates gh issue create on a recorded remote dup-scan (#904); severity-label resolution in github-incident-from-observation (#827); GitHub CLI added to the tech-stack.md Bash exception list (#883).
• Per-story PR lifecycle: Phase 08 Step 4.5, Phase 06 Step 6.6, story template 3.2 (#860).
• Friction reporting: configurable hook-enforced friction-reporting gate (#792).
• Architecture / stories: solarch enforces feature_decomposition tech-stack conformance at handoff (#863) and wires /create-ui as a conditional producer dependency (#743); spec-driven-system-architecture Step 0.4d remote-posture check (#857); spec-driven-stories Phase-00 optional worktree offer (#833) and RCA-007 pseudocode replaced with hook citations (#849).
• CI: source-tree drift guard + re-baseline artifact (#879).

#Changed

• lint-skill-ceremony.sh is now forbid-only (ADR-145). Removed the ADR-118 REQUIRE-citation rule (Rule 2) and the cite-once rule (Rule 4); kept the banned-marker, inert ## Reference Loading [MANDATORY], and SendUserFile rules; added a live-path FORBID that fails on any SKILL.md reference to the retired anti-skip-behavior.md. .github/workflows/hooks-lint.yml, tests/hooks/test_lint_skill_ceremony.sh, tests/devforgeai_cli/test_spec_sprint_phase_gate_emission.py, the spec-driven-agents skill template, and defer-classification-policy.md were updated to the new rule set. ADR-076 and ADR-118 remain unedited (append-only); their internal references are accurate historical record.
• Retired model: opus across subagent definitions for cost reduction (#783); conviction + board-render now run before the audit hook in PostToolUse[Bash] (#782); friction reporting enabled with detailed tone in feedback-config (#822); array tech-stack fields normalized (#736).

#Removed

• Retire anti-skip-behavior.md and the behavioral-admonition ceremony it anchored (ADR-145, supersedes ADR-076/ADR-118). Deleted the canonical .claude/rules/core/anti-skip-behavior.md rule file (and its src/claude/ mirror), removed the ## Execution Model citation blocks from every skill, and stripped the anti-skip-behavior.md pointer + ceremony prose from each ## Anti-Skip Enforcement Contract (the real deterministic-gate references are preserved). A single canonical home for unenforced behavioral admonition is still unenforced admonition; the audit record now lives in ADR-145 and the anti-regression mechanism in deterministic lints.
• Removed the unenforced Success-Criteria + Reasoning ceremony from subagent definitions (#729); untracked .claude/settings.local.json as a per-user local-settings file (#853).

#Fixed

• /spec-sprint: non-CODE exemption for the Phase-04 tdd-order gate (#900); Phase-04 doc-card branch dispatches/anchors test-automator to reconcile with the dispatch gate (#778, #816, #807, #803); Phase-03 worktree create gated on git-worktree-manager limit_reached (#767); Phase-03 VERIFY uses token-grammar grep (#766); Phase-06 gated on all non-skipped CI checks (#821); Phase-07 closeout notes gated (#744); doc-card exemption clarified contract-only (#784); false LLM-proof labels on Phase-05 Gates 3+4 corrected (#884); dangerouslyDisableSandbox clause stripped from Phase-03 Step 1b (#795, #806).
• QA / stories: dev-time vs qa-time qa-report routed to distinct paths (#836); .dev.md consumer + Codex parity repaired (#864); Phase-01 steps preserved across qa-setup/phase-init ordering (#829); unconditional RECORD stanzas added (#824); qa-cleanup requires gaps.json only for FAILED results (#791); detect-indicators cross-checked against tech-spec component types (#840); stories-inline-enforcement gates on active workflow not stale SC-* files (#831).
• run-tests / coverage: subprocess-invoked coverage measured via COVERAGE_PROCESS_START (#895); --cov target routed to the worktree source tree (#768); worktree-path installed-build warning (#811).
• Hooks / CLI: pre-tool-use blocks interpreter-mediated Bash writes to conviction-evidence dirs (#889); every phase-record invocation anchored in a batched Bash call (#789); observation_json_ref resolved against the active worktree (#796); source-code-changed detects uncommitted work via merge-base (#869); phase-complete writes through to the stories workflow checkpoint JSON (#843); completion-gate detects overall_status at root or .output.* (#842); resolve-worktree-subcommand forwards dash-prefixed flags via pre-parse argv split / parse_known_args (#858, #779); check-refactor-surface excludes markdown/prose files (#880); extract_section stops at ## not ### subsections (#897); render-sprint-board forwards --init-board flags (#837); validate-sprint-closeout verifies the Commit SHA exists in git (#850); sprint-resume worktree-liveness guard (#845) + contract gaps closed (#799); create-incident parses args via the CLI helper (#732).
• Release / installer: phase-09 manual-publish fallback gated on publish-step failure, not any CI run failure (#809); installer next-steps use the npx prefix for local installs (#810); stale OUTPUT goldens regenerated + _archive trimmed to restore the tarball budget (#868); set -o pipefail on the golden step (#855).

#Documentation

• RESEARCH-013 ceremony-vs-enforcement prompt-engineering study (#788); reusable ceremony-removal subagent prompt (#769); gh pr update-branch documented as a sandbox-safe PR base-update path in operational-safety (#876); issue #790 cross-reference in artifact-verification-gate.sh (#892); emit-conviction-worklog payload envelope and completion_record schema documented in phase dispatch prompts (#894, #896).

#[3.0.0-beta.9] - 2026-06-16

Status: Ninth @beta pre-release. The window covers 67 PRs (#569–#701) since the beta.8 tag (2026-06-13 → 2026-06-16). The bulk is continued /spec-sprint worktree-gate hardening, run-tests harness robustness, the gate-backed release-package workflow's own dogfooding fixes, and installer upgrade-path handling. Tag v3.0.0-beta.9 to publish to the @beta dist-tag via .github/workflows/npm-publish.yml.

#Added

• /spec-sprint worktree gates & contracts: deterministic worktree gates for phases 03–06 (#631, #512); untracked-collision recovery in Phase-00 ff-sync (#611); content-assertion test path for non-code phase-04 cards (#641); tests/hooks/ prescribed as the shell hook-test home in phase-04 (#574); spec-sprint checkpoint emission + sprint-resume rehydration entrypoint (#654, #557).
• run-tests harness: --test-command flag for shell-based test suites (#672); --expect-fail guarded against launch/collection failures (#660, #653); worktree sys.path.insert escape gated (#701, #601).
• Release workflow: README version-marker sync added to phase-09 (#665, #583); clean fast-forward worktree base allowed in the phase-03 gate (#691).
• Stories / architecture: recommended metadata derived from the DEVARCH seed in DEVARCH_SEED mode (#696, #594); Phase 00 VCS-posture check added to spec-driven-system-architecture (#606) and spec-driven-ui (#648).
• Framework / install: subagent-unavailable-fallback protocol (#604, #500); parallel.yaml.example deployed with copy-if-absent semantics (#700); mirror guard extended to settings.json and hooks/ (#650, #582); non-Tailwind React token-extraction patterns in mockup-extractor (#619, #519); incident-template byte-identity guard (#613).

#Fixed

• /spec-sprint: work contracts wired into phase-04 dispatches + gate consumption (#575); board-fill / card-id model reconciled to the PHASE_ORDER renderer (#662, #656, #647, #612); doc-card exemption narrowed to preserve the test-automator contract (#681, #668); Phase-03 fill VERIFY reconciled with hook-pre-render reality (#680); board filename pinned to issue-n.html (#645); completion_record append prescribed in phase-04 dispatches (#605); template-comment brace syntax stripped (#697).
• run-tests: no-tests-executed no longer accepted as a valid Red (#699); worktree-aware framework detection + Phase-04 --framework flag (#596); jest/vitest cwd scoped to the nearest package.json ancestor (#589); pytest duration canonicalized to stabilize the artifact sha256 (#607).
• Hooks: pre-dual-path-write-guard.sh made workflow-aware for spec-sprint Phase-04 worktree edits (#615); phase-complete gated on dispatch success via the PostToolUse ledger (#658, #639); Stop block scoped to the session-bound workflow (#669, #652); worktree-identity-guard.sh allows worktree-CWD → owning-main phase-state writes (#642); Phase-05 ac-verdict overwrite carve-out in feedback-artifact-write-gate.sh (#591); Phase-03 test-immutability narrowed to Red-snapshot-registered files (#632); session_id wired into the spec-sprint contract-consumption gate (#657, #644); story-self-validator allowed in Phase 07 of stories-inline-enforcement.sh (#676).
• CLI / contracts: bare integer step IDs auto-normalized to compound NN.N in phase-record (#670); nested tech-stack-detector output flattened in phase-set-tech-stack (#638); contract schema resolved from project root, fail-open when absent (#637, #624); AC parser extended for story-template v3.1 XML <given>/<when>/<then> (#635); single consolidated test_files_to_create entry for test-first mode (#649); test-file extension derived from test_framework (#590); extract_json_data_island made comment-aware (#587).
• Release / build: release-branch preflight guard added to phase-09 (d60c01c); package-route gates added to phases 01 and 03 + loop RECORD step fixed (#675); Step 9.1 rewritten to preserve the [Unreleased] placeholder during CHANGELOG promotion (#673, #586).
• Install / misc: existing-install detection offers Upgrade over E_TARGET_FOREIGN (#576); preflight error screen rendered in interactive --dry-run (#573); context-validator root-resolution contract made explicit (#572, #486); audit-gate falls back to empty-tree SHA on greenfield repos (#640); render-sprint-board idempotency / attribute-order / no-op-when-absent fixes (#682, #678, #661); self-excluding grep -v grep in Lock File Recovery (#663); stale index.lock pre-flight added to Phase 08 (#646); bundled devforgeai_cli test tree wired into the python-cli-tests gate (#602); github-incident BR-001 label sets reconciled with repo labels (#655, #634).

#Documentation

• generate-qa-recommendations input schema documented in --help and the authoring guide (#636); ai-companion-manifest.json schema documented in Phase-03 Step 3.2 (#597); README + website version markers synced to v3.0.0-beta.8 (#569).

#3.0.0-beta.8 - 2026-06-13

#Added

• Gate-backed release-package release workflow and verify-release-versions coherence gate, enabling /release --package X.Y.Z to drive npm releases through a deterministic 4-phase (01/02/03/09) gated sequence. (#567)

#3.0.0-beta.7 - 2026-06-12

Status: Seventh @beta pre-release. The window covers 85 PRs (#386–#563) since the beta.6 tag (2026-06-05 → 2026-06-12). The headline is the brand-new /spec-sprint issue-driven sprint workflow and the framework-wide hook generalization its dogfooding forced (workflow-aware gates, worktree/session-scoped state resolution), plus run-tests harness upgrades, a deterministic audit-fs engine, the archive quarantine lifecycle, and the /create-incident observation pipeline. Tag v3.0.0-beta.7 to publish to the @beta dist-tag via .github/workflows/npm-publish.yml.

#Added — /spec-sprint: issue-driven ad-hoc sprints (new skill)

• #391 (PR-1) + #402 (PR-2) — spec-driven-sprint skill + /spec-sprint command. Turns a single GitHub issue into a hook-enforced, resumable sprint: plan-mode research → self-contained HTML spec with work cards + embedded resumption prompt → isolated worktree off the remote default branch → TDD per card → QA iteration loop against the spec's ACs → PR. No story file required (distinct from /create-sprint, which plans story sprints from a backlog). PR-2 also closes #398 (phase-05 test-result anchoring).
• Dogfooding hardening wave (PR closes issue):
  • #417 (#416) — prose-duplication strip + gate wiring + ISSUE-* read tracking; #418 — phase-file-read telemetry coverage.
  • #460 (#448) — orchestrator owns Phase-03 worktree creation (git-worktree-manager is report-only); #509 (#490) — phase 04–06 file edits and commits anchored to the Phase-03 worktree; #545 (#536) — sprint worktrees relocated to {project-root}/worktrees/ and gitignored.
  • #529 (#494) — Phase 02 folded into Phase 01 (the harness plan-mode contract forces ExitPlanMode before the Phase-01 exit gate, leaving Phase 02 gate-only ceremony).
  • Work-contract pipeline: #457 (#453) — build-test-contract --workflow=spec-sprint for story-file-free sprints; #470 (#463) — contract builder + phase-set-tech-stack wired into the phase files; #424 (#423), #505 (#465), #534 (#507) — ISSUE-NNN work ids + the canonical AC-id grammar accepted across contract.schema.json and phase prose; #554 (#469) — SPRINT_VALID_PAIRS enumerated in the sprint mismatch error; #528 (#485) — emit-conviction-worklog accepts spec-sprint workflow ids.
  • Phase-05 verification: #532 (#489) — executable-AC evidence captured before verifier dispatch; #516 (#495) — run-tests path narrowed to tests/${ISSUE_ID}/; #517 (#497) — anti-pattern-scanner + coverage artifacts gate-enforced; #548 (#546) — Gate-1 aggregator suite prescribed for code cards that edit existing tests; #555 (#549) — run-tests --framework wired into the Step-1 command.
  • #488 (#479) — default-branch fallback chain + structured gh issue view (fixes failing prescribed detection commands); #550 (#544) — portable-core fallback dispatch requirement clarified.
  • #561 (#433) — backlog-triage mode + issue claim/release protocol (parallel sessions claim issues without colliding); #563 (#430) — the sprint HTML board is now rendered deterministically from phase-state by a PostToolUse hook, not hand-maintained; #562 (#474) — phase-04 Step 1b names the exact per-TDD-sub-phase contract pairs.

#Fixed — hooks made workflow-aware

Most enforcement hooks hardcoded the /dev workflow registry; spec-sprint and strategic RCA exposed it:

• #395 (#392) — Stop-gate discovers Sprint-*/RCA-*/MIG-* workflows (previously silently not Stop-gated); #429 (#425) then #496 (#476) — artifact-verification-gate skip-guards workflow-aware, generalized to all non-dev workflows; #434 (#426) + #537 (#510) — phase-gate-write permits spec-sprint Phase-04 test writes and Phase-06/07 src edits; #466 (#442) — phase-gate-commit; #491 (#478) — phase-context-injector; #552 (#539) — velocity-monitor phase-name lookup.
• Strategic RCA route: #409 (OBS-1) — rca-strategic workflow key registered so strategic /rca legally skips phase 03; #480 (#408) — rca-strategic block added to the phase-steps registry; #482 (#407) — RCA-* phase-state discovery in find_active_phase_state + RCA exempted from 3 enforcement gates.

#Fixed — worktree & session correctness (parallel-session safety)

• #420 (#414) — phase-state writes guarded against cross-worktree contamination; #455 (#450) + #456 (#452) — find_active_phase_state scoped to the editing worktree and resolved by session binding instead of global newest-mtime; #435 (#432) — subagent-dispatch-ledger attribution scoped by session; #467 (#436) — spec-sprint completion-gate Block-B correlated to the PR's own sprint, not all sprints; #441 (#427) — find_repo_root_for prefers .git over CLAUDE.md so worktree markers resolve to the worktree root.
• #458 (#451) + #504 (#471) — .claude/worktrees/ exempted from pre-test-target-guard and post-bash-test-check; #527 (#511) — pre-commit guards inspect the git -C target repo's staged index; #431 (#421) — conviction-postrecord evidence paths resolved from the project root, not CWD; #525 (#473) — loss-reason breadcrumbs added to subagent-dispatch-ledger silent-exit paths.

#Fixed — hook matcher anchoring (false-positive blocks)

• #445 (#399) — pre-test-target-guard runner matcher anchored to command-segment boundaries; #538 (#508) — post-bash-test-check operational-dir match anchored to the command verb; #551 (#542) — pre-tool-use ADR-062 hook-invocation deny anchored to the command-segment verb.

#Added — enforcement & conviction gates

• #404 (gh#393) — conviction-gate blocks /dev phase-complete on a non-PASS ac-compliance-verifier verdict (verdict-content gate gap); #412 (#405) — D6 attempts-log verdict coupled to every exit-2 path; #483 (#410) — CI lint enforcing that invariant.
• #419 (#413) — subagent dispatch ledger + reconcile gate: phase-record --subagent claims must be backed by real Task() dispatches (the RCA-070 record-fabrication class).
• #481 (#415) — phase-init gated on stale-main behind-count; #444 (#443) — safe Bash commands auto-approved via permissionDecision in pre-tool-use.sh; #464 (#459) — pre-commit guard for hook exec bits (100644 staged on WSL DrvFs); #454 (#449) — pre-commit src/claude/scripts ↔ .claude/scripts mirror-drift guard; #503 (#400) — gh issue create/edit gated to the incident-template schema.

#Added — tooling

• audit-fs engine: #447 (#437) — deterministic devforgeai-validate audit-fs CLI replaces the LLM-executed readonly-fs-scanner agent; #472 (#440) — --baseline delta mode with severity escalation; #446 (#438) — audit-wiring now detects dangling repo-local imports in test files as GROUNDED findings.
• run-tests harness: #468 (#422) — Bash .sh sub-runner; #547 (#428) — --framework override decoupling framework selection from glob-order detection; #556 (#530) — worktree PYTHONPATH injected for worktree test paths, so the Python SUT comes from the worktree under test, not main's editable install; #560 (#461) — --record-result fails fast (exit 2) instead of silently falling back to the global tests/ tree when the story test dir is missing and no --path was given.
• Archive quarantine lifecycle: #559 (#439) — archive/<date>/<original-path> quarantine layout, append-only ARCHIVE-MANIFEST.md schema, 30-day delete-eligibility window, and the read-only devforgeai-validate archive-sweep verdict CLI (see .claude/rules/workflow/archive-lifecycle.md).
• #522 (#401) — github-incident-from-observation skill + /create-incident command: spontaneous live-found bugs flow through the same templated incident pipeline.
• #484 (#406) — spec-driven-rca persists composition_state to a durable per-phase checkpoint (strategic RCA survives session loss).

#Fixed — other skills

• spec-driven-ui: #543 (#518) — single-batch mockup-extractor replaced with a per-cluster split so large mockups no longer overflow Phase 02a; #541 (#521) — Phase 08 check-hooks passes valid --status=success (feedback hooks now fire from /create-ui); #553 (#523) — design.md consumer count corrected from 6 to 4 (aspirational cross-skill prose removed).
• #492 (#475) — spec-driven-ideation PM-plan frontmatter keys aligned with ideation-output.schema.json v1.0; #487 (#477) — spec-driven-system-architecture phase-03 Step 3.1 writes context files via Bash heredoc, not native Write(); #540 (#531) — test-automator bash hook tests use BASH_SOURCE[0]-relative PROJECT_ROOT.

#Internal / chores / docs

• Python CLI version 0.1.0 → 0.2.0 — devforgeai-validate --version now reports 0.2.0, reflecting the window's CLI feature additions (audit-fs, run-tests --framework + .sh sub-runner, build-test-contract --workflow=spec-sprint). Bumped in devforgeai_cli/__init__.py (read by setup.py) + the cli.py argparse string, in both the src/claude/scripts/ and .claude/scripts/ copies.
• #558 (#462) — the 54-test build-test-contract suite (tests/STORY-647) added to the required Run Python CLI Tests CI gate; #397 (#396) — hook-test T1 real-corpus canary skips when the reference-reads corpus is absent (un-reddens every PR after #390); #390 — generated operational devforgeai/ runtime data untracked; #394 — stale src/devforgeai source mirror removed; #389 — disconnected dead-weight source silos pruned; #388 — unused vendored 20 MB bin/act binary removed; #403 — skills/commands pinned to the opus model alias (was claude-opus-4-7).
• #386 — beta.5/beta.6 provenance chain + Cause C (Python CLI install) + publish gotchas recorded in docs/installer/; #387 — installer wizard-gap remediation spec + live dashboard + gaps analysis; #411 — RCA-068 REC-2 linked to Issue-410.

#[3.0.0-beta.6] - 2026-06-05

Status: Sixth @beta pre-release. A focused fix release: the optional Python CLI now actually installs. This is the first @beta build where devforgeai-validate is usable after a fresh install. Single change since the beta.5 tag (#384).

#Fixed

• #384 (closes #383) — the Python CLI's scripts are now copied before pip; .claude/scripts/ was never created. The python-cli component declares sources: [{ from: "src/claude/scripts/", to: ".claude/scripts/" }] but its handler is python-venv-install (not file-copy), and the engine dispatches each component to its single handler — so the sources were never copied, and pip install -e .claude/scripts ran against a non-existent directory (is not a valid editable requirement). i.e. the Python CLI had never installed for any consumer; beta.5's #380 graceful-degrade made the failure visible and skippable, which surfaced this true cause.

  python-venv-install.execute() now delegates the source copy to the file-copy handler before venv/pip — creating .claude/scripts/ with setup.py (and exec bits on copied .py/.sh via file-copy's _effectiveMode), so pip install -e resolves. A genuinely missing source still surfaces loudly as E_SOURCE_MISSING. rollback() now reverses both the venv (rm -rf) and the copied scripts. Verified end-to-end: a real install populates .claude/scripts/ with the full devforgeai_cli tree (was empty). Every other src/claude/* directory already installed (they use file-copy); only scripts/ was affected.

#[3.0.0-beta.5] - 2026-06-05

Status: Fifth @beta pre-release. Makes npx devforgeai install actually work end-to-end after the distribution defects that made beta.3 un-installable from a clean npm download, then hardens the install experience — more recovery/conflict screens, in-wizard UX polish, graceful degradation when the optional Python CLI can't install, and the richer designed channel/component screens. 3.0.0-beta.4 was an interim installer-fix republish (the distribution/packaging fixes below, #369–#374) published with no separate changelog entry; beta.5 supersedes it and documents the whole window. Bundles PRs #342–#381 since the beta.3 tag (2026-06-04 → 2026-06-05). Tag v3.0.0-beta.5 to publish to the @beta dist-tag via .github/workflows/npm-publish.yml. (In-flow verify #300/#340, the Retry/Skip/Abort loop #305/#344, the A/B detectors #339, and C2/C1/D8 #318/#338 shipped inside the beta.3 tag — they are beta.3 content, not re-listed here.)

#Fixed — distribution & packaging (the reason a clean npm i → install failed on beta.3/beta.4)

• #369 — nested src/.npmignore stripped 4 manifest-required sources from the npm tarball. The nested ignore overrode the root files[] allow-list, so a fresh npx devforgeai install hit E_SOURCE_MISSING. Nested ignore removed; a pack-manifest-sources guard now asserts every manifest source is actually packed (packed == tracked).
• #370 — ~30 operational .py helpers were type-stripped from the tarball. The complete src/claude operational tree (incl. the devforgeai_cli helpers) now ships.
• #379 — removed an accidentally-committed 20 MB nektos/act binary from src/bin/ that was bloating the package.
• #374 — unblocked the beta.4 publish: trimmed dead weight and raised the ADR-100 tarball budget (+200 → +400 KB) so the publish gate stopped failing on size.
• #371 — quiet postinstall hint pointing at npx devforgeai install (later superseded by the #378 root-help CTA, since npm suppresses all postinstall output).

#Added — install resilience, recovery & conflict screens

• #349 (#334) — Category-B pre-flight conflict gates B3/B4/B7 wired to reachable terminal exits.
• #352 (#343) — Category-A per-screen recovery variants A3/A4/A7/A8.
• #361 (#350) — B8 component-drift preview on --switch-channel (shows what a channel switch would add/remove before committing).
• #365 (#356) — interactive D2/D3 recovery wiring for in-flow auto-rollback.
• #351 — flag-gated silent auto-rollback on an in-flow install failure.
• #348 (#322) — status S7/S9/S10 manifest fields captured + manifest-sbom.json emitted.

#Added — in-wizard UX

• #378 (#376) — pre-flight/input UX: a git-init pre-flight prompt for non-git targets, a plain-language pre-flight mutation summary (hook_installs → git_hook_installs rename), project-name auto-normalization to the npm package-name shape, and the root no-arg help now leads with the devforgeai install setup CTA.
• #381 — wizard fidelity chrome for Steps 4–5: the ratified channel screen (context line, ● non-stable markers, red "Unstable", "switch later via" hint) and dim per-component blurbs that the design specified but were never wired into the live flow. Interactive-only; silent NDJSON output unchanged.

#Changed

• #380 — E_PIP_INSTALL degrades gracefully. The optional python-cli component failing to pip install (offline/proxy/permissions) no longer hard-blocks the core install: it surfaces the pip stderr tail + an actionable hint, skips that one component (exit 0), and prints the single command to retry it later. Silent mode emits a warn (not error) event.
• #358 (#355) — --components is honored (unioned with the required set) instead of being ignored; #364 (#359) — unknown --components ids now warn instead of silently no-op'ing.
• #368 (#360) — standalone --verify scopes to the consumer-manifest installed components rather than the full framework set.
• #362 — ManifestManager.update now unions modules[] to stop the #322 manifest clobber; #367 (#363) — the migration test is scoped to migration semantics and records the modules[] last-run contract.
• #342 (ADR-137) — surgical reinstall install-mode + framework file-inventory (re-copy framework, remove stale framework files, keep customizations + devforgeai/).
• #347 (#323) — status --json emits update_available: null when the channel hasn't been checked (instead of a misleading false).

#Fixed — behavior

• #357 (#354) — non-TTY --interactive no longer hangs: the Step 7 pre-flight prompt is guarded behind isInteractiveTTY, so piped/CI invocations don't block on a prompt that can never be answered.

#Internal / docs / tests

• #353 (#329) — interactive NO_COLOR golden-screen gates (AC2 from the #278 dogfood gate).
• #366 — troubleshooting spec for the PR #349 v3 coverage gate.
• #375 — recorded the distribution/packaging troubleshooting + open follow-ups (docs/installer/installer-distribution-troubleshooting.md).
• #377 — README above-the-fold install block + beta.3 → beta.4 doc bump.
• #373 — interim 3.0.0-beta.4 version bump for the installer-fix republish.

#[3.0.0-beta.3] - 2026-06-04

Status: Third @beta pre-release. Completes the designed v3 installer wizard and makes it the default-and-only interactive installer, fixes the Pre-flight Summary file_additions: 0 preview bug (#270), removes the --legacy v2 installer, and validates the whole thing with a real-subprocess beta dogfood gate (#278). Bundles the installer-wizard completion program #269–#279 plus framework phase-state / hook / CI hardening that landed across PRs #267 through #337 since beta.2 (2026-06-03 → 2026-06-04). Tag v3.0.0-beta.3 (matching package.json) to publish to the @beta dist-tag via .github/workflows/npm-publish.yml.

#Installer wizard — rich designed flow (now the default and only installer)

• Pre-flight Summary file_additions: 0 fixed (#270 / #287) — src/cli/v3/planner.js now computes a real per-step file_count (walks each file-copy source at plan time via handlers/file-copy.js countFiles) and aggregates plan.files_total, so the Pre-flight Summary panel reports the true file count instead of always showing 0. Foundation A0/A1/A2 also lands the ADR-102/104 amendment and a 10-step design reconciliation.
• Screen-renderer foundation + silent-parity fence (A3 / #272 / #291) — the shared renderer underpinning the rich wizard, fenced so the --silent NDJSON contract stays byte-stable.
• Interactive input screens, Steps 1–7 (B1 / #273 / #298) — directory, detection, components, project name, channel, and confirmation screens.
• Install + completion screens, Steps 8–10 + copy.progress (B2 / #274 / #302) — live install-progress and completion-summary screens; per-file copy.progress events.
• Recovery screens — failure A1–A10 + pre-flight conflict B1–B8 (C1 / #275 / #306), channel/version C1–C6 + operational D1–D8 (C2 / #319), and the clean-verify success render (D2 / #276 / #320).
• Status / help / check-updates layouts, S1–S14 (D1 / #277 / #321).

#Installer — engine & CLI

• install --to-version → C6 version-pin conflict screen (#316 / #333).
• uninstall --purge removes .venv/ (D7 purge variant) (#317 / #331).
• v3 manifest + settings-merge result detail surfaced (#301 / #337).
• context-files / claude-md / claude-settings marked required so --exclude-components cannot drop the constitutional files (#295 / #336).
• output-formatter info() uses ›/--/meta glyphs per design Amendment A (#290 / #335).

#Removed

• --legacy flag and the v2 imperative installer removed (F1 / #279 / #332) — npx devforgeai install now runs the v3 declarative engine exclusively. Deleted src/cli/commands/install-legacy.js and its now-orphaned v2-only modules (install-wizard.js, installation-config.js, config.js, signal-handler.js, prompt-service.js, lib/banner.js, lib/copier.js, lib/components.js, lib/ide/). Shared modules reused by v3 (output-formatter.js, progress-service.js, lib/detector.js, lib/manifest.js, lib/claude-md-installer.js, lib/settings-merger.js) are preserved. Pulls the v3.1.0-scheduled removal forward into the beta cycle per ADR-104 D2 (#269/A0 amendment).

#Added — framework enforcement & CI hardening

• Real-subprocess beta dogfood gate (E1 / #278 / #330) — tests/npm-package/integration/v3/beta-dogfood-gate.test.js spawns the genuine CLI against a fresh dir and asserts NDJSON structural parity, non-TTY-no-hang, and real file_additions > 0 (guards the #270 regression). Runs in installer-testing.yml.
• Phase-state boundary gates wired across the front-of-pipeline skills — system-architecture (#280 / #289), development-architecture (#281 / #296), solution-architecture (#282 / #299), ideation (#283 / #307), and brainstorming (#284 / #308); real PreToolUse boundary-block enforcement (#293 / #303, ADR-132).
• Constitutional .yaml reference reads gated; dev-arch phase-06 promoted to [MANDATORY] (#297 / #310, ADR-135).

#Fixed

• npm publish gate unblocked (gh#268 / #286) — .github/workflows/npm-publish.yml Step 4 and scripts/release.sh now run the authoritative scoped test subset (npm run test:unit + npx jest tests/npm-package/integration/v3/) instead of the full npm test suite, which carried the gh#154 ~26% baseline-failure rate and permanently skipped the Publish to NPM step. Tag-triggered, --provenance-attested publishing now works without depending on the separate gh#154 full-suite cleanup.
• conviction-gate inline-string false-positive (#312 / #326 / #328, ADR-136) — the shared command_invokes() matcher now anchors to string-start, so a literal phase-complete/phase-record inside a quoted gh/git/echo argument no longer trips the gate and blocks the host command.
• phase-check --from=00 returns 0 entering a workflow's first phase (#311 / #327).
• Skill manifest / template cleanups — inert phase-state placeholders retired from the agents skill-template (#285 / #309); inert governance.json line removed from 4 [MANDATORY] manifests (#313 / #325).
• grep -c double-zero normalized + never-loaded boundary downgraded to WARN (#292); smoke-harness lib/ provisioning fixed (gh#314 / #324).

#3.0.0-beta.2 - 2026-06-02

Status: Second @beta pre-release. Bundles the complete v3.x declarative installer engine (ADR-100 through ADR-105, shipped in beta.1) plus the hardening, framework-rot tooling, hook-helper consolidation, and CI-gate work that landed across PRs #169 through #266 since beta.1 (2026-05-28 → 2026-06-02). This section continues to accumulate as open GitHub bug/enhancement issues are worked; tag v3.0.0-beta.2 (matching package.json) to publish to the @beta dist-tag via .github/workflows/npm-publish.yml.

#Installer (v3 engine) — carried + hardened

• Full v3 declarative install engine bundled — src/cli/v3/** (Parser → Validator → Planner → Executor → State Manager + Rollback), 8 handlers, JSON-Schema manifests (ADR-100 through ADR-105). Unchanged since beta.1; repackaged in this pre-release.
• install --help EXAMPLES block + --version channel annotation wired per ADR-102 D7/D9 (#214, gh#202).
• Operational paths resolve to the consumer root, not the src/ tree (#170).
• v3 install path-safety unit coverage (#209, gh#203), engine branch-coverage mock-isolation fix + un-skip (#208, gh#206), CLI startup perf threshold loosened to 500 ms + WSL-skip restored (#207, gh#205), orphaned v2 installer tests retired + installer-testing gate tightened (#204).
• @beta install instructions added to README + stale "in design" phrasing refreshed (#169).

#Added

• audit-wiring CLI + framework-rot-audit skill + /audit-rot command — file-level wiring-rot audit engine detecting orphans/dangling references (ADR-116; #229 PR-1, #230 PR-2).
• audit-wiring sub-audits — .py code-file unreferenced detection (5th sub-audit, ADR-120; #241); retired-artifact reference detection + registry (6th sub-audit, ADR-122; #245); consumer-configurable reference corpus via --corpus-root / --corpus-suffixes (ADR-121; #244, gh#236).
• Framework ceremony-to-gate CLI — verify-prerequisite-pr (Gate-1; #196), verify-deletion-safety (Gate-2; #197), and pre-commit-pr-scope-guard.sh hook (Gate-3, ADR-108; #199).
• pre-protected-path-write-guard.sh — Edit/Write guard for .git/hooks/ + system /tmp/, /var/tmp/ (ADR-113; #223).
• jq-required runtime contract (ADR-107) + lib/tool-input-helpers.sh::extract_file_path helper with 18 callers migrated (#186 PR-1, #187 PR-2, #188 PR-3; planning #184/#185; gh#141).
• Framework Incident Policy codified in CLAUDE.md + src/ mirror (#181).
• CI gates — python-cli-tests.yml running the green CLI-gate pytest suites (190 tests; #232) promoted to a required check + restructured always-run (#239, ADR-119, gh#220); skill --workflow value lint (#213) backed by full WORKFLOW_SCHEMAS registration (#210) incl. spec-driven-ui extract mode (#215, gh#180); devforgeai/**/*.sh exec-bit lint + chmod-fix of 36 scripts (#256, gh#254); forward-only ADR-number uniqueness lint (#228); skill-ceremony lint (#233) + Execution-Model citation requirement (#258, gh#247).

#Changed

• Anti-skip ceremony consolidation — 16 skills now cite .claude/rules/core/anti-skip-behavior.md instead of duplicating the ceremonial triad (#233, gh#221); verbose Anti-Skip Enforcement Contract blocks trimmed to a one-line pointer across 26 skills (#262, gh#248); redundant phase-loading "Do NOT skip" prose retired in 4 hook-backed skills (#257, ADR-124/126); 7 inert Reference-Loading [MANDATORY] manifests retired (#266, gh#259); stray propagating exhortations removed (#243, gh#221 follow-up).
• Completed ADR-071 source-tree.ai.md consumer migration (#231).
• Relocated spec-driven-architecture/assets to its spec-driven-system-architecture heir + fixed render-template portability (#249, gh#238).
• Hook tool-input extraction harmonized onto the shared extract_file_path / command-and-content helper (#217, gh#190).
• Hook output + context-token hygiene — a hook context-token usage audit with recommendations (#191) motivated routing PostToolUse warnings to additionalContext and block reasons to stderr (#193, gh#192).
• Claude Code Review CI gated behind an opt-in full-review label (#178).

#Fixed

• Pattern-A marker WSL DrvFs mtime-rounding bypass anomaly — -ge -5 floor (ADR-109; #201, with phase-gate-write/phase-gate-commit bypass marker, gh#179).
• render-ai-companion manifest drift repaired + --check CI gate added (#225, gh#189).
• epic-coverage parser now recognizes integer ### Feature N: headers (#260, gh#253).
• _validate_story_id accepts skill-identifier patterns (#219, gh#212).
• w3-compliance derives a per-run timestamp session id, ending W3-AUDIT collisions (#222, gh#218).
• stale-QA D8 drops only its own contribution, not global block state (#176); dev step-ratio block scoped to step-tracked phases (#174).
• 30 reds repaired across devforgeai_cli + commands suites, folded into the Python CLI gate (#255, gh#224/ADR-120); 11 obsolete tests retired + their suite folded into the gate (#250, gh#227); audit-module tests decoupled from a legacy story fixture (#194, gh#142).
• verify-deletion-safety --internal-callers-allowed exemption covered + caller-path semantics disambiguated (#216, gh#200).
• audit-wiring global-sorts matched corpus files to preserve cited_in order (#251).
• Dead Edit/Write branches removed from pre-tool-use.sh (#182, gh#140/ADR-106); diagnostic tracer stripped from pre-dual-path-write-guard.sh (#265); rc-reset lint for tests/hooks rc-bleed (#171, #177, gh#131-class).

#Deprecated / Removed

• Retired the _archive skill, scraper eval scratch, skill-creator, and a legacy site page (#172).
• Retired F-1 test-plan pipeline modules (#195, ADR-094 follow-up).

#Spike / Research

• audit-wiring TypeScript code-rot resolver feasibility → NO-GO — AST is sound, but no language-agnostic GROUNDED-vs-INCONCLUSIVE mention-routing sweet spot exists for glob-loaded source trees (#252, ADR-123 / RESEARCH-012).

#Architecture Decision Records

ADR housekeeping: concurrent-merge number collisions were renumbered — ADR-117 → ADR-118 (#237), ADR-124 → ADR-125/126 (#261, #263, #264) — and a forward-only ADR-number uniqueness lint added to prevent recurrence (#228).

#3.0.0-beta.1 - 2026-05-28

Status: First public pre-release of the v3.x installer modernization arc on the npm @beta dist-tag. The declarative install engine (ADR-100 through ADR-105) is implemented across phase PRs #155 through this PR. Tag a v3.0.0-beta.1 to publish via .github/workflows/npm-publish.yml.

#Highlights (Phase 10 — Integration + Release Prep)

• v3.x engine arc is COMPLETE. Schemas (Phase 2, PR #155), parser/validator (Phase 3, PR #156), engine core (Phase 4, PR #157), 8 handlers (Phases 5-6, PRs #158-#159), migration + back-compat (Phase 7, PR #160), channel detection (Phase 8, PR #163), dual-mode UX (Phase 9, PR #165), and integration + release prep (Phase 10, this PR).
• 5 end-to-end integration tests cover the full install flow: golden-install, resume-flow, rollback-flow, verify-flow, legacy-equivalence-final (per ADR-101 §Verification).
• CI enforces 90% coverage on src/cli/v3/** (all 4 metrics: statements / branches / functions / lines) per ADR-101 D8.
• STORY-048 Python contract runs on every PR (closes the PR #148 closeout addendum gap).
• Cross-platform CI matrix (Linux + macOS + native Windows) exercises the python-venv-install handler (ADR-103 §Verification).
• npm-publish workflow ships v3.x-beta.* tag pushes to the @beta dist-tag (stricter regex per ADR-104 D1).
• Tarball slimming — deleted src/claude/skills/spec-driven-web-scraper-seo/web-scraper-seo-workspace/ (~26 MB scraped fixtures) and tightened package.json files to exclude deprecated docs/Optimization/, docs/assets/, docs/demo.html, docs/index.html, docs/stories/. Tarball delta vs v2.0.2 baseline: -254 KB (within ADR-100 §Verification ≤ +200 KB budget).
• Capability flag wiring closed — Phase 10 wires the previously unwired --rollback, --resume, and --verify flags from install.js to the orchestrator entry points; replaces Phase 7 E_NOT_IMPLEMENTED stubs with real implementations honoring ADR-101 D2 + ADR-101 D10 + ADR-102 §"Exit code contract" codes 6 / 7 / 8 / 5.

#Highlights (Phase 9 — Dual-mode UX, PR #165)

• First-class --silent with NDJSON event stream (ADR-102 §"NDJSON event envelope" schema_version "3.0").
• First-class --interactive with bicameral 10-step footer (ADR-102 D1).
• Step 7 Pre-flight Summary confirm gate (ADR-102 D3).
• Per-component deterministic events (copy.start / copy.complete regardless of duration per ADR-102 D12).
• 30-second heartbeat cadence on long-running phases with 60-second liveness invariant (ADR-102 D13).
• 14-code exit contract (codes 0-12 + 130 SIGINT per ADR-102).
• Curated help-text style guide (ADR-102 D7): MODE / INPUT / CAPABILITY / PYTHON / UPDATE / OUTPUT / DEPRECATED ordering.
• One-time -y/--yes deprecation overlay (ADR-102 D8; removal v4.0).
• One-time -q/--quiet deprecation overlay (ADR-104 D8; removal v4.0).

#Highlights (Phase 8 — Channel detection, PR #163)

• version-detector module querying npm registry + GitHub releases + GitHub main HEAD with 24h cache + offline-safe fallback (ADR-105 §"Decision").
• channel-switcher handler orchestrates npm install -g devforgeai@<channel> + .venv/ rebuild on channel transitions (ADR-105 D9).
• 8 new install flags + 3 new status flags + standalone check-updates command surface (ADR-105 §Implementation).
• Exit code 12 (UPDATE_AVAILABLE) emitted by devforgeai status --check-updates --silent when install is stale (ADR-105 D8).
• 3 channels: stable (npm @latest), beta (npm @beta), edge (GitHub main HEAD) per ADR-105 D1.
• Privacy-first — no phone-home; checks happen only on explicit user command (ADR-105 D4).

#Highlights (Phase 7 — Migration + back-compat, PR #160)

• install-legacy.js — verbatim v2 imperative installer preserved behind --legacy (ADR-104 D2).
• install.js shim routes default path to v3 engine, --legacy path to v2 imperative.
• manifest-migrate-v1-to-v2 handler (9th handler) — runs early on FIRST v3 invocation against v2 consumers; backs up v2 manifest to .devforgeai-manifest.v1.backup.json, writes v3 schema with manifest_schema_version: 2, channel: "stable", source: "npm", channel_history: [], installed_at_v2: true (ADR-104 §Decision).
• engines.node bumped to ≥20.0.0, engines.npm to ≥9.0.0 (ADR-104 D7).
• --legacy flag emits one-time [DEPRECATED] warning per process; removed in v3.1.0 (ADR-104 D2).

#Highlights (Phases 5-6 — Handlers, PRs #158-#159)

• 8 handlers implementing the 4-method contract (plan / execute / verify / rollback) per ADR-101 D2:
  • file-copy (streaming-aware for >1 MB files including tree.json)
  • template-substitute ({{KEY}} substitution)
  • directory-create
  • settings-merge (wraps existing SettingsMerger; consumer-wins on conflicts)
  • claude-md-import (wraps existing claude-md-installer)
  • python-venv-install (per ADR-103: cross-platform path resolution, 5 structured error codes, python.mode: venv|global switch)
  • pre-commit-hook-install
  • manifest-write (v3 schema with all new fields)

#Highlights (Phase 4 — Engine core, PR #157)

• 5-layer engine architecture (Parser → Validator → Planner → Executor → State Manager) + Rollback engine per ADR-101 §Decision.
• State journal at tmp/devforgeai-install-${SESSION_ID}/state.json (project-scoped per operational-safety Rule 2).
• Pre-flight write-probe catches sandbox EROFS BEFORE handler.execute() runs (ADR-101 D12).
• Topological sort by depends_on (ADR-101 D5).
• Failure policy per component (required → fail-fast; non-required → handler's failure_policy per ADR-101 D11).

#Highlights (Phases 2-3 — Schemas + parser, PRs #155-#156)

• JSON Schema Draft 2020-12 framework manifest at src/cli/manifests/install-manifest.json + _schema/install-manifest.schema.json (ADR-100).
• schema_version: "1.0" strict equality enforced via Ajv const: "1.0" (ADR-100 D2; ports ADR-086/087 policy).
• additionalProperties: false at every object level (ADR-100 D3).
• YAML user-facing install config at .devforgeai-install.yaml (ADR-100 D1).
• Cross-reference validator detects cycles, missing handlers, immutable-path double-claims (ADR-101).
• NPM dependency count: 7 — added ajv@^8.x (~120 KB) + js-yaml@^4.x (~30 KB) per ADR-100 D10. Previously 5 (chalk, ora, cli-progress, inquirer, commander).

#Highlights (existing arc, unchanged)

(Unchanged from the prior "Unreleased (Proposed)" entry below — preserved for completeness.)

Earlier-arc status: This release covers PR #8 through PR #138 (2026-05-05 → 2026-05-25), the broader v3.x modernization arc covering Spec-Driven Pipeline + ceremony-to-hook conversion + source-tree decomposition. v3.0.0 will ship as v3.0.0-beta.1 on the npm @beta dist-tag, then GA on @latest. The installer engine rewrite (ADR-100 through ADR-105) is now IMPLEMENTED across PRs #155 through this PR (vs "in design" at the time the original entry was written).

#Highlights

• Spec-Driven Pipeline broken into 5 first-class skills — spec-driven-brainstorming (Business Analysis), spec-driven-ideation (Project Management), spec-driven-system-architecture, spec-driven-solution-architecture, spec-driven-development-architecture (ADRs 065-070).
• Ceremony-to-Hook conversion — ADR-076 codified the policy; ~12 new hooks now enforce what was previously prose-only across .claude/agents/, .claude/skills/, .claude/rules/, and ADR/manifest paths.
• v3.x Installer Modernization (in design) — Declarative install engine, dual-mode UX (interactive ↔ silent NDJSON), update channels (stable/beta/edge), cross-platform Python venv ownership. Documented in ADR-100 through ADR-105; not yet implemented.
• Source-tree as decomposed JSON artifact — source-tree.md monolith replaced by devforgeai/specs/context/source-tree/ (schema-validated JSON folder; ADR-071/072).
• 40+ new ADRs ratifying architectural decisions across ADR-065 through ADR-105.

#Added

#v3.x Installer Modernization (Design Only — Not Yet Implemented)

• Declarative install manifest schema (ADR-100) — JSON + JSON Schema Draft 2020-12 framework manifest at src/cli/manifests/install-manifest.json; YAML user-facing install config; Ajv + js-yaml dependency proposal.
• 5-layer install engine architecture (ADR-101) — Parser → Validator → Planner → Executor → State Manager + Rollback engine + 8 built-in handlers. 90% coverage target on src/cli/v3/.
• Dual-mode UX contract (ADR-102) — Interactive wizard and silent CI mode as co-equal first-class use cases; NDJSON event stream with schema_version: "3.0"; 14-code exit contract (0-12, 130); bicameral 10-step footer + 13-screen design catalog.
• Python end-to-end ownership (ADR-103) — Cross-platform venv management (POSIX bin/ + Windows Scripts/); 5 structured error codes (E_PYTHON_MISSING, E_PYTHON_VERSION, E_VENV_CREATE, E_PIP_INSTALL, E_ENTRY_POINT); python.mode: "venv" | "global" switch.
• Backwards compatibility & migration v2→v3 (ADR-104) — manifest_schema_version field, v1→v2 migration handler, --legacy flag with one-minor-cycle deprecation, engines.node bump from ≥18 to ≥20.
• Version detection & update channels (ADR-105) — Three channels (stable / beta / edge); version-detector module querying npm registry + GitHub releases + GitHub main HEAD; 24h cache at ~/.config/devforgeai/version-cache.json; offline-safe fallback; exit code 12 UPDATE_AVAILABLE; no-phone-home privacy guarantee.
• Design source-of-truth at devforgeai/specs/design/installer/ — 5 markdown files (260 KB) covering foundation tokens, 13 happy-path screens, 32 recovery/edge-case screens, 14 status/help layouts, NDJSON event sequences.
• Interactive visual prototype at docs/installer/preview/ — React/Babel canvas rendering all 75 designed screens with three rendering variants (default color, NO_COLOR=1, TERM=dumb ASCII fallback).
• Hand-off prompts at .claude/prompts/installer-wizard-design-*.md (5 design briefs) + .claude/prompts/installer-modernization-continuation-2026-05-26.md + .claude/prompts/website-readme-redesign-2026-05-26.md.

#Spec-Driven Pipeline Skills (PRs #55-#67)

• spec-driven-brainstorming rewritten as 11-phase Business Analysis skill (#55, ADR-065).
• spec-driven-ideation modernized into the Project Management phase (#57, ADR-066).
• spec-driven-system-architecture (#59, ADR-067) — System Architect skill producing the System Architecture Document + 6 constitutional context files.
• spec-driven-solution-architecture (#60, ADR-068) — Solution Architect skill producing feature decomposition.
• spec-driven-development-architecture (#61, ADR-069) — Development Architect skill producing DEVARCH documents whose paths populate story source_devarch frontmatter.
• test-plan.ai.yaml wired through system-architecture generation and QA validation (#62, STORY-634).
• DEVARCH story seeds wired through /create-story + backend-architect (#63, FU-1 / FU-2).
• Brainstorming Stream C methodology — Z14-Z18 additions (#29).

#Hooks & Enforcement

• Pattern A marker-file bypass mechanism for pre-dual-path-write-guard.sh (#85, #87, #90, #97, #112, #138; ADR-081). Single-shot, < 30s fresh, consumed on bypass, audit-logged to devforgeai/logs/post-edit-write.log.
• pre-tree-json-read-guard.sh — blocks wholesale Read of multi-megabyte source-tree/tree.json (#113, ADR-092).
• pre-tmp-path-block.sh — blocks writes to system /tmp/ (#115, ADR-093).
• pre-phase-record-reference-check.sh — phase-record reference validation hook (#105, #114, #129, ADR-091).
• pre-adr-append-only-guard.sh — blocks Edit/Write to existing ADRs without tmp/_adr-status-update.marker bypass (#122, ADR-096).
• post-audit-attempt-counter.sh — C11 audit-attempt escalation hook mechanizing diagnosis-before-fix.md item 5 (#125, ADR-098).
• pre-qa-recommendations-fidelity hook (#79, ADR-075).
• 3 enforcement hooks + git-ops completion — rules → deterministic gates (#52).
• SessionStart sandbox-state verifier hook (#19, RCA-067 REC-4 / Issue #12).
• Conviction-gate bypass user-approval gate (#21, RCA-067 REC-6).
• Single-line canonical JSON contract for evidence-log writers (#18, RCA-067 REC-3 / Issue #11).
• Conviction worklog Rule-16 validator (#88, ADR-083 PR-B).
• Hook test harness CI workflow + closes pre-dual-path-write-guard test gap (#133).
• Hook infrastructure refactoring — find_repo_root_for() extracted to lib/repo-root-helpers.sh (#134); 5 inline find_project_root copies migrated to phase-helpers.sh (#135); shared parse_flag + find_repo_root_for adoption (#136); ADR-081 marker-bypass extracted to lib/marker-bypass-helpers.sh (#137).
• Phase helpers infrastructure (phase-helpers.sh) + AI companion regeneration (#26).

#CLI Validators

• validate-devarch-seed CLI gate — H5 / ADR-082 — replaces prose-only Phase 01 structural validation in spec-driven-stories (#84).
• Architecture CLI gates — validate-pm-plan + validate-system-architecture-output + validate-solution-architecture-output + _schema_check.py helper (#92, ADR-084).
• H5 harmonization — devarch_seed_validator composed into _schema_check helper + schema_version == "1.0" strict equality (#96, ADR-086).
• CLI validator schema_version audit — closure-only audit, 0 in-scope drift (#99, ADR-087).
• verify-story-creation subcommand (#118, ADR-094).
• diagnose-dod-failure subcommand v1 (#120, ADR-095).
• dev-preflight exit 4 — source_devarch validation per B2 (#128, ADR-099).

#RCA & Feedback Modernization

• /rca + spec-driven-rca modernized with hook-backed enforcement (#75, ADR-074).
• rca-document-composer subagent for spec-driven-rca phases 04-07 (#47, OPP-8).
• github-incident-from-rca + create-stories-from-rca aligned with ADR-074 contract (#78).
• github-incident-from-feedback added; spec-driven-feedback modernized (#76, ADR-074).
• QA recommendations fidelity — /create-incident-from-recommendations + generator fidelity fix (#22, ADR-075); silently-blocked Edit replaced with posting-manifest link-back (#81); SKILL.md doc tables aligned with manifest pattern (#83).
• /recommendations-triage retired; /create-incident-from-queue added (recs → GitHub issues, not stories) (#98).
• /feedback-export-data folded into /DF:feedback export-data subcommand (#91).
• ADR-074 RCA traceability markers rendered into story Provenance (#80).

#Documentation Modernization (Coaching Entrepreneur Stream)

Original [Unreleased] content from prior CHANGELOG state:

• Coaching Entrepreneur — Emotional State Tracking (STORY-468)

  • Updated docs/api/API.md (session log schema, tone mapping, business rules BR-004/BR-005)
  • Updated docs/architecture/ARCHITECTURE.md (data flow, check-in flow diagram, design decisions)
  • Updated docs/guides/DEVELOPER-GUIDE.md (session log schema, extension points, STORY-468 tests)
  • Added troubleshooting entries 21-24 in docs/guides/TROUBLESHOOTING.md (session log, tone adaptation, override, enum validation)
  • Added roadmap section in docs/guides/ROADMAP.md (3 feature items)
  • Updated README.md module blurb with new doc links

• Coaching Entrepreneur (STORY-467) — API, architecture, developer guide, and module blurb updates.

• Assessing Entrepreneur (STORY-465, STORY-466) — 6 module docs covering README, API, architecture, developer guide, troubleshooting, roadmap; updated for adaptive profile generation, /assess-me command, recalibration support, and business rules.

• Hook-Based Phase Enforcement (EPIC-086, Sprint 22) — Phase Steps Registry (STORY-525), SubagentStop hook (STORY-526), TaskCompleted hook (STORY-527). Eliminates undetected phase skipping through automated validation.

#Source-Tree & Migration

• source-tree.md monolith replaced by devforgeai/specs/context/source-tree/ AI-optimized decomposed folder artifact (#68, ADR-071 / ADR-072).
• spec-driven-migration skill + 2 terminal-worker subagents (#69, ADR-073). Reference-sweep migration workflow.
• spec-driven-migration dogfood + sweep of source-tree.md residuals (#70).
• spec-driven-migration vacuous-pass dry-run pattern (#71).
• source-tree.md → source-tree/ via spec-driven-migration (#72).
• source-tree decomposed artifact regeneration — drift 1642 → 0 (#94); drift 324 → 0 (#104).
• migration-cluster-worker tool-whitelist expansion (#95, ADR-085).

#Subagents

• 8 reference-file frontmatter name: fixes (#30, Wave 1).
• Wave 2: qa-executor + spec-driven-rca + dead-code-detector + REF-002 hook (#32).
• Wave 3: readonly-fs-scanner + audit-orphans/budget + F07 documentation-writer reuse (#33).
• Wave 4a: mockup-extractor terminal subagent + phase-02a refactor (#35).
• Wave 4b: story-self-validator terminal subagent + phase-07 refactor (#36).
• Wave 4c: custody-chain-auditor terminal subagent + validate-stories refactor (#38).
• Wave 5: MISSING-004 + MISSING-005 placeholder renames (#39).
• story-requirements-analyst modernized (597 → 169 lines; #43, pilot).
• custody-chain-auditor trimmed under 600-line CI gate (655 → 572; #44).
• 4 pseudocode-dominant subagents modernized (2181 → 508 lines; #45).

#Other Skills

• spec-driven-qa prose reduction (~11%) matching sibling pattern (#74).
• spec-driven-ui PR-A modernization — canonical form + Phase 00 inline + /create-ui slim (#73, ADR-074).
• spec-driven-stories SKILL.md + 8 phase files modernized (#77, PR-A).
• spec-driven-stories honest C-1 prose audit (#101, ADR-088, closes ADR-080 §FU#3).
• spec-driven-stories references investigation (#102, ADR-089, closes ADR-080 §FU#1).
• spec-driven-stories defensive-wrappers investigation — H8-CLI ship + 7 drops (#103, ADR-090).
• spec-driven-dev ADR-076 ceremony-to-hook modernization (#106).

#Research

• RESEARCH-011 — fresh AI file-format evaluation, post-2026-05-20 evidence only (#89).
• RESEARCH-007 committed as superseded by RESEARCH-011 (#93).

#Other

• STORY-667 genesis epoch support for evidence chain verification (#16).
• PyYAML permitted for CLI use (#124, ADR-097).
• GitHub Workflow for Claude Code (#8).
• Template-version detection + spec-driven-remediation template upgrade (#25).
• Test-plan-generation thesis codified (#119, ADR-094); subagent-based implementation (#127).

#Changed

• Plan-file-archive policy + ADR-064 amendment (#24).
• DevForgeAI.md extracted as framework steering + installer auto-import (#31).
• Always-loaded session context reduced 41.7K → 19.2K (-54%) (#54).
• Operational-safety.md Rule 4 expanded — sandbox policy (#20, RCA-067 REC-5 / Issue #13).
• DEVARCH seed prerequisite documented for /dev (#117, PR #106 B2).
• coverage-analyzer + contract-spec load thresholds from test-plan.ai.yaml; document test_plan_subset (#121).
• Settings.json sync (#107 / #108 attempted CLAUDE_CODE_WORKFLOWS=1 then reverted — env var removed by Anthropic).
• Rules-hooks modernization — hook hygiene chunks 1-2 of 4 (#49); chunks 3-4 of 4 (#50); plan archived (#51).
• test-folder-protection.md HALT ceremony trimmed to hook pointer (#53).

#Deprecated

• spec-driven-architecture skill — superseded by 3 sibling skills (system / solution / development architecture) (#64, ADR-070).
• /recommendations-triage command — superseded by /create-incident-from-queue (recs → GitHub issues, not stories) (#98).
• /feedback-export-data standalone command — folded into /DF:feedback export-data subcommand (#91).
• source-tree.md monolith — replaced by source-tree/ decomposed JSON folder (#68, ADR-071).
• -y/--yes and -q/--quiet installer flags — aliased to --silent / --output=text --verbose=0 respectively in proposed v3.x; removal scheduled for v4.0 (ADR-102 D8, ADR-104 D8).
• Imperative src/cli/commands/install.js 9-phase wizard — proposed v3.x replaces with declarative engine; retained behind --legacy flag in proposed v3.0.0; removal scheduled for v3.1.0 (ADR-104 D2).

#Removed

• __pycache__ from git tracking.
• Duplicate STORY-553 completed version in archive (preserved before v2.0.1).
• devforgeai_cli.egg-info/ pre-existing .gitignore violation (#28).
• .claude/memory/Constitution/ deprecated mirrors (#41).
• Ephemeral STORY-*-session.md remnants untracked + gitignored (#37).
• Orphan internet-sleuth-integration/ completing ADR-045 (#40).
• .claude/memory/ files pruned 25 → 4 (#48).
• Dead Registry Drift block from pre-commit hook (#34).
• Retired skill/command references in research skill + framework context files (#67).
• Repointed retired spec-driven-architecture skill + command references (#66).

#Fixed

• spec-driven-ui validate_context.py — source-tree migration + path bug + folder handling + dual-path repo-root detection (#110).
• spec-driven-system-architecture phase-03 — source-tree generation + obsolete template retirement + noun-swap residuals (#116).
• Multi-match-safe hook flag parser implementation plan (#17 → impl across hook PRs).
• Pattern A marker repo-root resolution from editing file's path (#112) — closes the $CLAUDE_PROJECT_DIR env-propagation gap.
• pre-dual-path-write-guard.sh — removed silent DEVFORGEAI_DUAL_PATH_GUARD_ENFORCE gate that didn't propagate into hook subshells (#109); follow-up housekeeping (#111).
• PR-#114 diagnostic tracer — stripped after mystery closed (#129).
• spec-driven-cc-guide reference files — typo filenames + orphan duplicates (#56).
• subagent-size-check — set -e bug + orphan-audit tracking (#46).
• ADR-074/075/076 collisions renumbered to ADR-077/078/079/080 + ADR-081 bypass-mechanism proposal (#82).
• ADR-097 audit-attempt-hook renumbered to ADR-098 (collision with PR #124 PyYAML ADR) (#126).
• ADR-094 status flipped to Accepted post-merge (#123).

#Security

• Conviction-gate bypass requires user approval (#21, RCA-067 REC-6).
• Single-line canonical JSON contract for evidence-log writers — prevents log corruption / injection (#18, RCA-067 REC-3).
• SessionStart sandbox-state verifier — detects partial-state at boot and emits recovery commands (#19, RCA-067 REC-4).
• ADR append-only enforcement — pre-adr-append-only-guard.sh blocks ADR mutation without marker bypass (#122, ADR-096).
• No-phone-home guarantee in proposed v3.x version detection (ADR-100 + ADR-105) — user-initiated checks only, 24h cache, offline-safe.

#Architecture Decision Records

40+ ADRs ratified during this arc. Notable clusters:

See devforgeai/specs/adrs/ for the full ADR set.

#Notes & Open Items

• v3.0.0 ships as v3.0.0-beta on npm @beta dist-tag first, then GA on @latest. Beta window: ~4 weeks (per ADR-104 D1).
• The release/v2.5.0 branch was merged to main but never tagged or documented — intermediate state folded into this v3.0.0 entry.
• ADR-004 and ADR-009 received in-flight amendments during the v3.x design session (2026-05-26) that were subsequently reverted by user direction. The amendments documented post-publication discoveries (Python venv ownership, pre-commit hook auto-install, undocumented status/uninstall commands, the context-files AS-IS gap). These discoveries are still planned for documentation in the forthcoming INSTALL.md (PR-1 of v3.x docs work).
• Three v3.x installer ADRs (ADR-100 through ADR-105) remain in Proposed status pending implementation. Status flips will occur as implementation phases ship.

#1.0.0 - 2026-03-03

#Added

• Core Framework

  • 44 specialized subagents for architecture, testing, QA, security, documentation, and more
  • 26 inline skills covering the full software development lifecycle
  • 46 slash commands from /brainstorm through /release
  • 6 constitutional context files (tech-stack, source-tree, dependencies, coding-standards, architecture-constraints, anti-patterns)
  • 4 sequential quality gates blocking progression until standards are met

• TDD Workflow (/dev)

  • 10-phase development cycle with mandatory Red-Green-Refactor
  • Phase 04.5 and 05.5 AC compliance verification
  • Test folder write protection (only authorized agents in designated phases)
  • Coverage thresholds: 95% business logic, 85% application, 80% infrastructure

• Configuration Layer Alignment Protocol (CLAP)

  • 15 validation checks across contradiction, completeness, and ADR propagation categories
  • /audit-alignment command for on-demand validation

• Hook-Based Phase Enforcement (EPIC-086, Sprint 22)

  • STORY-525: Phase Steps Registry with 72 steps across 12 phases
  • STORY-526: SubagentStop hook for automatic invocation tracking
  • STORY-527: TaskCompleted hook for step validation gates
  • Eliminates undetected phase skipping through automated validation

• Root Cause Analysis System

  • /rca command with 5 Whys methodology
  • diagnostic-analyst subagent for cross-reference investigation
  • /create-stories-from-rca for converting findings into actionable stories

• Feedback System

  • 7 commands for capture, search, export, import, and reindex
  • AI analysis and observation extraction from subagent outputs

• Sprint Planning

  • /create-sprint with automated story selection and capacity planning
  • Dependency graph analysis with cycle detection

• Cross-AI Collaboration

  • /collaborate generates portable documents for sharing with external LLMs

• CLI Validation Tools

  • devforgeai-validate Python CLI for phase management, DoD validation, and story checks
  • Pre-commit hook integration for commit-time validation

• Documentation

  • API reference (docs/api/API.md)
  • Architecture guide (docs/architecture/ARCHITECTURE.md)
  • Troubleshooting guide (docs/guides/TROUBLESHOOTING.md)
  • Developer guide (DEVELOPER.md)