v5.0.0

First PyPI release since 3.1.2. Supersedes the tagged-but-never-published
4.0.0 (its CI publish failed on a __version__ drift, since fixed by reading
the canonical VERSION at runtime). 5.0.0 bundles all 4.0.0 content plus
everything below. See docs/MIGRATION-v4-v5.md for the breaking changes.

Changed — BREAKING

• Review is now OFF by default. The default /mb work path is execution
  (implement → verify → done) with no reviewer. The shipped
  references/pipeline.default.yaml stage_pipeline no longer contains a
  review step; the review policy moved to an opt-in top-level review: block
  (enabled: false). Restore review per-run with /mb work --review, persist it
  with review.enabled: true, or use a governed preset
  (--workflow governed-execution). Migration: docs/MIGRATION-v4-v5.md.
• mb-work-severity-gate.sh PASSes as a no-op when no review is configured
  (previously exit 2 "no 'review' step in stage_pipeline"). The gate now reads
  the review: block ▸ legacy stage_pipeline[review] ▸ active workflow
  loop.severity_gate, on both the PyYAML and no-PyYAML paths.
• full is now a first-class preset, not an alias. workflow.aliases.full
  (→ full-cycle) is removed; --workflow full now resolves to the complete
  8-stage chain discuss → sdd → plan → implement → verify → review → judge → done.
  The old 6-stage interactive flow is still available as --workflow full-cycle.
  A new everything alias points at full.

Added — composable /mb work pipeline

• 3-layer stage composition (precedence: launch flags > pipeline.yaml >
  built-in default), resolved in scripts/mb-workflow.sh into one canonically
  ordered stage list (discuss → sdd → plan → implement → verify → review → judge → done; fix stays an internal loop mechanic).
• Per-stage launch flags — --review/--no-review, --judge/--no-judge,
  --brainstorm/--no-brainstorm (alias of discuss), --sdd/--no-sdd,
  --plan/--no-plan; --stages a,b,c is an escape hatch that overrides the
  preset and every flag. Launch flags win over pipeline.yaml; pipeline.yaml
  per-stage <stage>.enabled: true adds a stage on top of the resolved preset.
• Deterministic merge — the composed set is re-sorted into canonical order
  only when composition changes it; an un-modified preset (or a legacy
  stage_pipeline-only project) keeps its own order verbatim (back-compat).
• full preset (workflows.full) spans the whole chain; per-stage opt-in
  enabled blocks for review/judge/discuss/sdd/plan ship in the
  default pipeline.yaml (all false).
• Fail-fast on invalid chains — scripts/mb-pipeline-validate.sh gains a
  --stages <csv> [--input …] mode and rejects judge without review and
  sdd/plan with no upstream input; the composer (mb-workflow.sh) enforces
  the judge⟹review rule before execution. commands/work.md documents the flags,
  the three-layer precedence, and the full preset.
• --review is the single-reviewer path (resolved via
  mb-reviewer-resolve.sh, gated by mb-work-severity-gate.sh); the heavyweight
  5-reviewer ensemble stays behind --workflow governed-execution.
• SDD-specified via the skill's own engine (dogfooding):
  .memory-bank/specs/composable-work-pipeline/. +29 tests (default-no-review
  contract, gate no-op, composer matrix, --stages validation, doc contract).

Added — code-graph intelligence layer (opt-in: wiki, surprising connections, semantic search, suggested questions)

• Module decomposition (behaviour-preserving): scripts/mb-codegraph.py 660 → 344 lines; extractors split into memory_bank_skill/codegraph_{common,python,treesitter}.py; shared codegraph_loader.py (one graph.json loader, both query/context cores delegate). Default output byte-identical.
• Git co-change edges — mb-codegraph.py --apply --cochange adds deterministic co_change file edges from git history (memory_bank_skill/codegraph_cochange.py).
• Suggested questions — mb-codegraph.py --apply --questions appends deterministic exploration questions to god-nodes.md (codegraph_questions.py), from god-nodes/bridges/communities/co-change. $0, no LLM.
• Semantic search — scripts/mb-semantic-search.py: pluggable Retriever port, pure-Python BM25 default ($0, zero deps), opt-in local embeddings (sentence-transformers, graceful fallback). Modules semantic_search.py + semantic_embeddings.py.
• LLM wiki + surprising connections — /mb wiki (commands/mb.md § wiki + scripts/mb-wiki.py): per-community articles via Haiku subagents, cross-cutting semantic edges via Sonnet — host subagents, no API key. Deterministic prep in wiki_evidence.py + wiki_store.py (validated, idempotent edge merge). Agents mb-wiki-author / mb-wiki-synthesizer.
• Optional dep sentence_transformers registered in mb-deps-check.sh. Default graph/search behaviour unchanged; all new capabilities opt-in with graceful degradation. Realizes backlog I-063.

Added — global-rules provisioning of the intelligence layer + session-memory packaging

• Installer source-of-truth now ships the intelligence layer. rules/RULES.md (→ ~/.claude/RULES.md), rules/CLAUDE-GLOBAL.md (→ ~/.claude/CLAUDE.md block) and references/claude-md-template.md (→ project CLAUDE.md) gained the opt-in graph layer (suggested questions / co-change / semantic search / /mb wiki), the co_change + semantic edge kinds in the jq schema, the code-agent routing one-liner, and cross-chat session-memory (/mb recall) guidance. Previously these lived only in hand-edited ~/.claude/* and were lost on every install/upgrade (Step 1 overwrites RULES.md). New contract test test_rules_cover_intelligence_layer.py keeps rules from drifting behind features.
• Session-memory subsystem now installs out of the box. The four hooks (mb-session-turn.sh, mb-session-end.sh, mb-session-start.sh, mb-recall.sh) + hooks/lib/{session-common,extract-tools-files}.sh are now git-tracked; install.sh copies hooks/lib/ beside the hooks; settings/hooks.json registers them (new SessionStart event + Stop/SessionEnd entries, all marker-tagged). Documented in SKILL.md ## Hooks. New contract test test_session_memory_packaging.py. A fresh clone/install now gets cross-chat memory; previously all five files were untracked WIP and never registered.

Changed — compact rules/CLAUDE-GLOBAL.md (always-in-context block)

• rules/CLAUDE-GLOBAL.md (injected into ~/.claude/CLAUDE.md on every install) trimmed 145 → 81 lines: the always-on core is kept intact (Mandatory first-response guard, the CRITICAL RULES compaction block, Session Pipeline, Codebase Map + opt-in layers + /mb recall), while the verbose Coding/Testing/Reasoning/Planning bullets and the full /mb command table are condensed to pointers into ~/.claude/RULES.md (read on demand). Cuts per-message context cost without losing any rule. All guard/contract tests stay green (test_global_prompt_guard, test_rules_cover_intelligence_layer, test_runtime_contract); the localizable Language line is preserved verbatim.

Changed — rules/RULES.md context economy (Code Graph + MB reference → on-demand)

• rules/RULES.md trimmed 1073 → 801 lines (−25%) without losing any rule. The full Code Graph cookbook (jq query library, graph.json schema incl. the co_change / semantic edge kinds, the opt-in intelligence layer, benchmark-grounded semantic-search routing, /mb recall session memory) moved to a new on-demand reference references/code-graph.md (installed via the references/ dir copy; linked from SKILL.md ## References). The Subagents roster, the full /mb command reference, and the .memory-bank/ structure tables — verbatim duplicates of SKILL.md §Agents/§Tools, /mb help (commands/mb.md), and references/structure.md — were compressed to pointer sections (heading anchors preserved). Genuine rules kept inline: verify-before-done, no-delegate-plan/architecture/ML, checklist-update-immediately, progress.md append-only. The intelligence-layer contract test (test_rules_cover_intelligence_layer.py) re-points to references/code-graph.md; CLAUDE-GLOBAL.md pointers follow. All guard / doc-count / graph-rag / install contract tests stay green (pytest 1135, bats 669 / 0 fail). Plan: .memory-bank/plans/2026-06-07_refactor_rules-context-economy.md.

Changed — dev-agent strengthening via engineering-core composition

• New shared partial agents/mb-engineering-core.md — role-neutral, stack-agnostic engineering
  discipline lifted to a single source of truth: TDD (Red→Green→Refactor), Contract-First (+ contract-drift),
  Clean Architecture direction table, SOLID/DRY/KISS/YAGNI thresholds, production-wiring awareness,
  evidence-before-claims Iron Law (no "tests pass" without the command output), escalation rules
  (3 attempts → STOP, no thrashing), STATUS contract (DONE / DONE_WITH_CONCERNS / BLOCKED /
  NEEDS_CONTEXT, evidence-backed), and an anti-rationalization table. Marked partial: true —
  excluded from the ~/.claude/agents/ registry by install.sh, delivered via the skill symlink.
• /mb work composition — the implement-step now inlines mb-engineering-core ahead of the
  resolved role agent (prompt = core + "\n---\n" + role + body). Previously the specialist files said
  "Inherit all mb-developer principles" but the orchestrator inlined only the role file, so that
  discipline never reached the subagent. The prepend fixes the broken inheritance.
• 9 dev-role agents refactored to thin deltas — mb-developer (down to a generic-fallback delta)
  and the 8 specialists (mb-backend, mb-frontend, mb-ios, mb-android, mb-devops, mb-qa,
  mb-analyst, mb-architect): removed the non-functional "Inherit…" reference, kept the domain
  principles, replaced thin "same shape as mb-developer" outputs with explicit STATUS-led contracts
  that require the test-run output.
• Controllers hardened — mb-reviewer and plan-verifier gained an adversarial default
  ("assume the diff is wrong until the rubric is demonstrably upheld; an invariant with no test that
  forces the failure mode is unproven = a finding"); plan-verifier reports now include a
  "Verified positively" section (positive proof, not just absence of findings). mb-reviewer's
  strict-JSON contract is unchanged (parser verified intact).
• Validation — before/after behavioural test on the same trap task (sonnet, sandboxed): both
  mb-backend and mb-developer went from claiming "tests pass" with no command output to leading
  with STATUS: DONE and pasting the actual pytest output; rubric ~3.0 → ~4.6. See
  .memory-bank/reports/2026-06-02_subagent-baseline.md.

Added — rule profiles & stack presets (Sprint 3)

• Configurable rule profiles with immutable safety baseline. Profiles personalize Memory Bank rules across local / global / rules-only modes without weakening protected-files / no-placeholders / verification-before-completion / DRY/KISS/YAGNI guarantees.
• memory_bank_skill/rules_profile.py — stdlib-only Python module with parse_profile, parse_profile_safe, validate_profile, resolve_profile. Frozen dataclasses Profile, ResolvedProfile, ValidationError. Built-in defaults plus layered precedence: built-in → user → project → task (task can only tighten, never weaken).
• scripts/mb-profile.sh — shell CLI with subcommands init / show / path / validate / set. --scope=user|project, --role, --stack, --architecture, --delivery, --strictness, --agent, --mb. JSON-only persistence. User-scope profile path resolves through Sprint 1 mb_agent_config_dir; project-scope through mb_resolve_path.
• 22 built-in presets under references/rules-presets/:
  • Roles: backend, frontend, mobile.
  • Stacks: go, python, javascript, typescript, java, generic.
  • Architectures: clean, hexagonal, modular-monolith, microservices, ddd, fsd, mobile-udf, event-driven.
  • Delivery: tdd, contract-first, api-first, sdd, legacy-safe, exploratory.
  • Each preset is declarative JSON (rule_id, severity, guidance, see_also) with unique global rule_id and ≤200-char guidance.
• Rules-check integration — scripts/mb-rules-check.sh now reads the resolved profile, emits a profile block in JSON output (role/stack/architecture/delivery/strictness/sources/prompt_summary), tags violations with rule_id + profile_source, and honours strictness: block exits non-zero on CRITICAL, warn is backward-compatible, advisory never blocks.
• Stack-aware deterministic checks (added to mb-rules-check.sh):
  • stack.go.context-propagation (warn), stack.go.goroutine-context (advisory)
  • stack.python.type-hints (advisory), stack.python.no-business-mocks (warn)
  • stack.typescript.no-any (warn), stack.javascript.strict-equality (advisory)
  • stack.java.repository-interface (advisory)
  • architecture.fsd.import-direction (warn) fires only when architecture=fsd.
• /mb profile command surface — new commands/profile.md (init/show/path/validate/set with copy-paste recipes), routed from commands/mb.md (now 25 commands). /mb init flow documents optional profile setup after storage choice.
• Docs — new docs/rule-profiles.md (precedence model, schema, all 22 presets listed, 5 copy-paste recipes, immutable baseline table, JSON canonical / YAML docs-only). README adds "Rule profiles & stack presets" section; SKILL.md ## Tools table gains mb-profile.sh and ## References links references/rules-profile.schema.md.
• Contract coverage — tests/pytest/test_rules_profile_schema.py (26 cases: parser/validator/resolver/precedence/4 KB cap), tests/pytest/test_rules_presets.py (12 cases: schema validation across all 22 presets + composition snapshots + immutable-baseline guards), tests/bats/test_mb_profile.bats (10 CLI cases), tests/bats/test_rules_check_profile.bats (8 integration cases incl. fsd/strictness).

Added — global-storage agent support (Sprint 2)

• Resolver-aware hooks — hooks/session-end-autosave.sh, hooks/mb-compact-reminder.sh, hooks/mb-session-start-context.sh now honour an MB_PATH env override for global-storage mode. Tiering: MB_PATH env → local <cwd>/.memory-bank/ → registry lookup via scripts/_lib.sh when MB_AGENT is set. _lib.sh is sourced in a subshell so its set -euo pipefail does not bleed into the hook.
• Git-hooks fallback — adapters/git-hooks-fallback.sh post-commit body honours MB_PATH env so commits in global-storage projects append to the external bank.
• OpenCode plugin — adapters/opencode.sh JS plugin reads process.env.MB_PATH instead of hard-coding path.join(app.path.cwd, '.memory-bank').
• Cursor / Codex / Pi / Windsurf / Cline / Kilo adapters — generated runtime hooks and inline scripts honour MB_PATH; AGENTS/rules snippets mention the resolver so users discover global mode.
• Codex global AGENTS.md — install.sh codex_agents_section now embeds the full engineering baseline (TDD / SOLID / Clean Architecture / DRY / KISS / YAGNI / [MEMORY BANK: ABSENT]) via sed-merge from rules/CLAUDE-GLOBAL.md, matching the Pi pattern. Codex global installs get the same rules-only surface as Claude and Pi.
• Storage-modes docs — SKILL.md, README.md, docs/install.md, docs/cross-agent-setup.md describe three modes:
  • Local (default): /mb init or /mb init --storage=local — bank in the repo (team-shared).
  • Global (opt-in personal storage): /mb init --storage=global --agent=<agent> — bank under ~/.<agent>/memory-bank/projects/<id>/.memory-bank/, never committed.
  • Rules-only: no /mb init — global engineering rules still apply; Memory Bank commands remain inactive.
• Contract & E2E coverage — tests/pytest/test_global_storage_contract.py (11 cases) locks hook resolver-aware contract, OpenCode plugin contract, git-hooks fallback contract, and Codex global rules-only surface; tests/e2e/test_global_storage.bats (4 cases) covers cross-cutting story (context without local bank, uninstall preserves external bank, local mode default, install never creates a bank).
• Adapter uninstall safety — adapter manifests never list the resolved Memory Bank path; uninstall removes only adapter-owned files. Verified by E2E "uninstall preserves external bank data" case.

Added — Cursor adapter remediation

• adapters/cursor.sh registers the full 10-hook Cursor contract (matcher-aware PreToolUse/PostToolUse, project + global installs, idempotent append builder).
• hooks/mb-session-start-context.sh — sessionStart hook injects capped .memory-bank/ context (MB_AUTOLOAD_CONTEXT=off to disable).
• memory_bank_skill.__version__ reads canonical VERSION (wheel metadata fallback); pyproject.toml uses Hatch version source.
• Cursor User Rules paste file uses <!-- memory-bank:start vX.Y.Z --> markers; TTY installs offer clipboard helper.

Added — Pi Code first-class global support

• memory-bank install now registers Pi globally under ~/.pi/agent/: managed AGENTS.md, skills/memory-bank alias, and prompt templates in prompts/*.md (/mb, /start, /done, /plan, etc.).
• memory-bank uninstall removes Pi managed sections, prompts, and skill alias while preserving user content.
• adapters/pi.sh now uses the native ~/.pi/agent/skills path; MB_PI_MODE=skill no longer needs MB_EXPERIMENTAL_PI_SKILL, and default agents-md mode works outside git repos.
• memory-bank init CLI help is client-neutral and reminds Pi users to run /reload after installing into an already-open session.

Fixed

• memory_bank_skill.__version__ reads the canonical VERSION at runtime, so the
  tag == VERSION == __version__ publish gate no longer drifts (the failure that
  blocked the 4.0.0 PyPI publish). This is what unblocks the 5.0.0 release.
• CI green — .shellcheckrc (disable=SC1091, since shellcheck won't follow
  sourced libs without -x); adapters/pi.sh SRP split → adapters/_lib_pi_global.sh
  (351 → 236 lines); ruff import-sort normalization across hooks/; SKILL.md
  reviewer/tooling table refresh.
• Reinstalling refreshes the managed Claude/Pi Memory Bank sections instead of repeatedly localizing every quoted critical rule as a language rule.
• Installer symlink replacement now safely replaces symlink aliases without following or backing up external symlink targets, preserving the symlink-attack guard for file targets.
• Existing Pi skill directory backups are stored under ~/.pi/agent/.memory-bank-backups/ instead of ~/.pi/agent/skills/, avoiding duplicate memory-bank skill discovery conflicts.
• MB_PI_MODE=skill leaves an existing global Pi skill symlink unchanged, preventing accidental overwrite of the canonical bundled SKILL.md.

Added — I-004 (auto-commit hook for /mb done)

• scripts/mb-auto-commit.sh — opt-in (MB_AUTO_COMMIT=1 env or --force flag) auto-commit of .memory-bank/ changes after /mb done. 4 safety gates: bank clean → no-op; dirty source outside bank → skip with warning; rebase/merge/cherry-pick in progress → skip; detached HEAD → skip. Commit subject derives from the last ### heading in progress.md (truncated to 60 chars); fallback chore(mb): session-end YYYY-MM-DD. Never pushes — push remains an explicit user action.
• Wired into commands/done.md step 7 (between index.json regen and final report).
• 13 new tests (test_mb_auto_commit.py 10 + test_i004_registration.py 3). pytest 615 → 628.