v5.3.1

Added — OpenSpec import adapter (/mb openspec)

• scripts/mb-openspec.sh + scripts/mb-openspec.py — one-way import adapter: an OpenSpec
  changes/<id>/ (proposal + delta specs ADDED/MODIFIED/REMOVED/RENAMED + tasks) is parsed
  directly (no openspec CLI dependency) and written as an MB spec triple under
  specs/<topic>/{requirements,design,tasks}.md. The OpenSpec tree is read-only; every write is
  asserted under .memory-bank/ (topic path-traversal + symlink-escape guarded). Deterministic core.
• Drift-aware list/status/sync — import records openspec_source/openspec_hash
  frontmatter; list [--all] reports imported/drifted/not-imported, status <topic> one
  topic, sync [<topic>] re-imports only on hash drift (a match is a pure no-op, no write).
• Re-import preserves work — REQ-NNN reused by requirement name (not document position),
  /mb work task check-state preserved by text, orphaned tasks appended to backlog.md (never
  silently dropped), crash-consistent write order (orphans durable first, hash written last).
• Opt-in --normalize — fills LLM text slots (prose-SHALL → EARS, missing scenario, Covers),
  cached by source-requirement hash so an unchanged requirement never regenerates, fail-open (LLM
  unavailable → deterministic fallback + warn). Omit for the byte-deterministic path (NFR-001).
• Spec .memory-bank/specs/openspec-adapter/ (20 REQs, 6 tasks); 81 pytest + 15 bats. Cleared a
  4-round Codex GPT-5.5 review + Opus verification gate (all findings fixed, round-4 APPROVED).

Added — Running list of agreements

• scripts/mb-agree.sh — the single writer for the canonical registry of confirmed
  decisions (<bank>/agreements.md): add [--supersedes N] [--adr NNN] [--source S] | defer | reject | question | resolve | list [--all] | sync. Monotonic never-reused AGR-NNN/Q-NNN
  IDs issued under an atomic owner-token mkdir lock (kill-0 PID-liveness stale-break), every
  write temp-file + mv. Lazy: nothing exists until the first add. Kill-switch MB_AGREEMENTS=off.
• Managed-block sync — after every mutation the active one-liners are rendered into a
  <!-- mb-agreements:start/end --> block in project-root CLAUDE.md/AGENTS.md (replace between
  markers only, surrounding bytes preserved; distinct from the adapters' memory-bank:* block), so
  a fresh session sees the full canon with no extra tooling. > 25 active warns, never truncates.
• /mb agree + /mb verify integration — router entry in commands/mb.md + commands/agree.md;
  the Plan Verifier classifies every active agreement as satisfied / violated / not-applicable and
  fails the verdict on any violation (agents/plan-verifier.md, Step 3.7). Rules trigger in
  rules/RULES.md + rules/CLAUDE-GLOBAL.md; full protocol in references/agreements.md.
• Spec triple .memory-bank/specs/agreements/{requirements,design,tasks}.md (16 REQs, 8 tasks);
  70 bats across test_mb_agree.bats + test_mb_agree_docs.bats, green on bash 3.2 and default.

Added — SessionStart "newer release?" notice + opt-in auto-update

• scripts/mb-version-check.sh — the single resolver for "is a newer release out?":
  compares the local VERSION against the latest GitHub Release (PyPI JSON as fallback),
  TTL-cached (MB_UPDATE_CHECK_TTL, default 86400), strict JSON output, fail-open on every
  network/parse error.
• hooks/mb-update-notify.sh — SessionStart hook rendering that answer: silent when
  up to date, otherwise a ≤3-line notice naming current -> latest and the exact upgrade
  command for the detected install flavor (git/pipx/pip/brew). Reads the cache only
  (--cache-only, no network from the hook path itself) and fires a detached background
  refresh when the cache is cold. MB_UPDATE_CHECK=off disables the check entirely.
• Opt-in auto-update (MB_AUTO_UPDATE=on, default off): applies the update automatically
  via mb-upgrade.sh --force, but only for a git clone install with a clean working tree — a
  dirty tree refuses, and pipx/pip/brew installs are never auto-run, only named in the notice.
  Fail-open: a stuck or failing auto-update attempt never blocks the session.
• Docs: commands/mb.md upgrade section, SKILL.md hooks table, README.md "Staying up to
  date" section, and references/structure.md control envelopes cover the three new env vars
  (MB_UPDATE_CHECK, MB_UPDATE_CHECK_TTL, MB_AUTO_UPDATE).

v5.3.0

Fixed — a broken main reached PyPI; this release is the repair

• templates/ were missing from the published 5.2.0 wheel
  (#2): a fresh
  pipx/pip install could not run /mb init at all — mb-init-bank.sh exited
  3 (missing template bundle) for every locale, blocking the very first
  onboarding step. The packaging fix landed on main after 5.2.0 was cut, so it
  never reached users; 5.2.0 cannot be re-uploaded to PyPI. This release is the
  first one that actually ships the locale bundles. Guarded by
  tests/pytest/test_wheel_ships_templates.py, which asserts the built wheel
  contains templates/locales/<lang>/.memory-bank/.
• scripts/_lib.sh shipped with a bash syntax error — an unterminated
  heredoc quote (<<'PY instead of <<'PY'). _lib.sh is sourced by every
  mb-*.sh, so the whole toolchain was dead: mb-adr.sh exited 2, mb-review.sh --emit-payload failed, and the install/calibration suites went red.
• hooks/mb-session-turn.sh shipped with raw merge-conflict markers —
  unparseable, so every turn-capture path was dead and each deploy re-installed
  the broken copy. Resolved by merging both sides: the Live-log splice + bullet
  cap + stale-summary invalidation, and sc_strip_private (the I-082 control
  that keeps <private>…</private> spans off disk — picking either side alone
  would have silently reverted a shipped security fix).
• Repeat installs were not idempotent: the paired-marker branch backed up a
  CLAUDE.md that install.sh itself had written, minting a fresh
  .pre-mb-backup.* on every re-run and making the install manifest's backups
  list differ run to run. A backup is now taken only when real user content lives
  outside the managed block (A13's guarantee is unchanged).
• Capture test suites were not hermetic: they inherited MB_AUTO_CAPTURE
  from the developer's shell, so a dev with it exported to off saw six false
  reds that were written off as a "known baseline". setup() now normalizes the
  MB_* environment.

Added — cross-session coordination

• references/coordination.md — the append-only COORDINATION.md board
  protocol for two or more agent sessions sharing one working tree (read the
  board before stages/commits/shared-file edits, scoped git add only, FREEZE
  entries need an ACK). Wired into CLAUDE.md, rules/, agents/, and
  commands/{start,commit,work}.md. The docs referenced this file before it
  existed; it now ships.

Added — Reviewer 2.0 (calibrated, tests-aware review)

• scripts/mb-review.sh — a deterministic review-payload orchestrator
  (--emit-payload): assembles the single markdown payload the reviewer
  judges (plan context, diff, calibration examples, prior test evidence, and
  an auto-generated tests blocker when touched-file tests are red) without
  ever dispatching an LLM itself. Supports --input <case-dir> so the same
  production code path can run offline against a fixture (see the calibration
  suite below).
• scripts/mb-review-cache.sh — the touched-file test-evidence cache
  (.memory-bank/tmp/last-tests.json): TTL-bounded HIT/MISS keyed on a
  touched-files sha, with --refresh-tests as the manual force-MISS escape
  hatch.
• Layered calibration examples — scripts/mb-review-examples.sh resolves
  few-shot rubric examples from references/rubric-examples/{common,python, go,typescript,frontend,mobile,backend}.md, with an optional project
  override at .memory-bank/rubric-examples/ taking precedence on
  example_id collision. Every stack ships >=3 examples per category
  (logic/code_rules/security/scalability/tests).
• --require-tests-blocker (scripts/mb-work-review-parse.sh) — the
  REQ-103 "cannot drop" safety net: if a reviewer output drops or downgrades
  the auto-injected tests/blocker finding for a known-red touched-file
  test run, the parser restores it and forces CHANGES_REQUESTED. Opt-in —
  only ever passed when touched-file tests are already known to be failing.
• Golden calibration suite (tests/calibration/) — a runnable regression
  harness against reviewer verdict drift: 5 case fixtures (one red-tests
  case), an offline --emit-payload smoke path (no LLM/network, exercised by
  tests/bats/test_calibration_suite.bats), the full PASS/WARN/FAIL match
  metric, and a documented (not yet added — see tests/calibration/README.md)
  non-blocking weekly workflow_dispatch/schedule CI job.

Compatibility. Additive and opt-in throughout — default /mb work
behavior is unchanged unless a project explicitly wires the new review
orchestrator or opts into --require-tests-blocker (REQ-105). Existing
pipeline.yaml files without the new keys keep working via resolver
defaults.

Migration. None required. Projects that want project-specific calibration
examples may optionally add .memory-bank/rubric-examples/{common,<stack>}.md
overrides (same example_id/stack/category/severity front-matter +
### Bad / ### Expected verdict fragment block format as the bundled
references/rubric-examples/ baseline); everything else keeps using the
skill-bundled baseline unchanged.

Added — work-loop-v2: sprint contracts, progress trend, strategic pivoting (REQ-110/111/112/114)

• scripts/mb-work-contract.sh — per-work-item sprint contract: create scaffolds
  <bank>/contracts/<plan-topic>_stage-<N>.md (idempotent — never clobbers an existing draft),
  read/path resolve it, validate checks all 7 frontmatter keys and 6 body sections (In scope /
  Plan of attack / Test plan / DoD checkpoints / Out of scope / Open risks) are present. Paired with
  templates/contract.md and a new review_mode: contract toggle documented in agents/mb-reviewer.md
  (4-category rubric: scope/dod/test_plan/out_of_scope; a silent/empty out-of-scope section is a
  blocker). Opt-in — /mb work --contract for one run, or a project's own
  pipeline.yaml:review.require_contract: true to make it mandatory; capped at 3 contract-review cycles
  before a hard stop for human. Off by default; existing /mb work runs are unaffected.
• scripts/mb-work-trend.sh — key derives a stable sha256 item key from (plan, stage, item);
  compute reads a normalized reviewer verdict (mb-work-review-parse.sh output) and prints this
  cycle's progress_trend (improving / stagnant / regressing / null on the first cycle),
  maintaining the previous-cycle cache at <bank>/tmp/last-verdict-<item-key>.json
  (weighted_score = 10*blocker + 3*major + 1*minor). This is the signal mb-work-pivot.sh consumes
  to decide whether the loop is actually making progress.
• scripts/mb-work-pivot.sh — decide turns a tracked consecutive_stagnant count and the current
  cycle number into refine / pivot_in_role / pivot_via_architect, thresholds resolved from
  pipeline.yaml:review.pivot_after_cycles (default 2) and review.pivot_escalate_to_architect_on
  (default 4, both already present in references/pipeline.default.yaml). prompt-prefix emits the
  re-dispatch instruction text (discard-and-restart for pivot_in_role; the two-step
  architect-then-role-agent escalation for pivot_via_architect). Every non-refine decision appends
  one JSONL telemetry line (ts/item_id/cycle/mode/rationale_hash) to
  <bank>/tmp/pivot-log.jsonl (not git-tracked — local analysis data only).
• commands/work.md — new "Sprint contracts, progress trend, and strategic pivoting" section wires
  all three scripts into the existing implement→verify→review→judge→fix loop: the contract phase runs
  before the implement step, trend is computed every review cycle from the normalized verdict, and a
  stagnant trend routes the fix-cycle into a pivot dispatch instead of an indefinite refine loop. All
  three scripts only emit decisions/strings — dispatch stays the host agent's job (agent-native, same
  as the rest of /mb work).

Compatibility. Fully additive and opt-in. A project that never sets --contract /
require_contract never runs the contract phase; trend/pivot only change behavior once a review cycle
actually reports CHANGES_REQUESTED with a stagnant trend for pivot_after_cycles consecutive cycles —
until then the loop's existing refine behavior is unchanged byte-for-byte.

Known gap (backlog I-099). scripts/mb-review.sh reserves a last_verdict_cache_path() hook for the
same cache file but does not yet write to it and derives the key differently from
mb-work-trend.sh key; callers must always derive the item key through mb-work-trend.sh key until the
two are reconciled.

Changed — work-loop-v2: fail-fast on_max_cycles default (REQ-113)

• on_max_cycles now defaults to stop_for_human (was
  continue_with_warning) in the bundled references/pipeline.default.yaml
review: block. When a project's pipeline.yaml omits on_max_cycles
  entirely, the resolver (scripts/mb-workflow.sh) falls back to this new,
  stricter default instead of quietly continuing past an exhausted fix loop.

Migration. Existing <bank>/pipeline.yaml files are never rewritten by
install/upgrade — the only writer, scripts/mb-pipeline.sh init, creates the
file solely when absent and refuses to overwrite an existing one without
--force. Projects that already explicitly set on_max_cycles: continue_with_warning keep that behavior untouched. Projects that prefer
the old soft behavior — including any relying on the previous default rather
than an explicit setting — must add on_max_cycles: continue_with_warning to
their pipeline.yaml explicitly.

v5.2.0

Added

• Context-window statusline (scripts/mb-statusline.py): a Claude Code
  statusline that shows how much of the context window is filled (used/limit,
  1M-aware) alongside model · git branch · project. Reads Claude Code's status
  JSON on stdin, counts the latest main-chain usage, and skips sidechain
  (subagent) usage so subagent tokens never inflate the count. /mb statusline
  (→ mb-statusline.py --install) wires it into ~/.claude/settings.json with
  a backup and refuses to clobber an existing statusLine unless --force.

v5.1.0

Consolidated 5.1.0. The tier1 graph/session-intelligence layer ships
together with handoff-v2 persistence, the dynamic-flow firewall + router,
named pipelines, capability-aware dispatch, and the session-lifecycle
catch-up/summarizer. First PyPI publish since 5.0.1.

Added — dynamic-flow, session-lifecycle, SDD

• Dynamic-flow firewall + closure (Phase 1): scripts/mb-flow-verify.sh is
  the sole exit-code authority (0=pass / 1=fail / 2=broke); Stop-hook
  (mb-flow-closure-guard.sh) + git-hooks closure guards gated on a goal.md
  predicate; AGENTS.md firewall contract; goal primitive + validator. Shipped
  through the governed dual-review (Codex + lead) + judge pipeline. (REQ-DF-010..062)
• Dynamic-flow router + patterns (Phase 2): analyze-task deterministic
  router, five-route catalogue, six workflow pattern templates, stateless
  mb-fanout.sh agent-invoke + per-agent sub-invoke contract with
  parallel-fence write-once discipline. (REQ-DF-070..084)
• Session-lifecycle: mb-session-catchup.sh (SessionStart lazy-summarize of
  sessions left summarized:false by a SIGKILLed SessionEnd), extracted DRY
  mb-session-summarize.sh, mb-session-prune.sh (archive contentless stubs),
  mb-settings-ensure-timeout.py (inject the SessionEnd timeout). All fail-safe.
• SDD hybrid requirements: requirements.md now pairs Kiro User Stories with
  EARS acceptance criteria; mb-ears-validate.sh is case-insensitive and
  validates only the REQ bullets; mb-plan.sh plan template gains YAML
  frontmatter (type/topic/status/depends_on/parallel_safe/linked_specs/created).
• Cursor extension finished — sessionEnd registry auto-capture.

handoff-v2. A persistence layer that lets a long-running agent survive
context compaction and session boundaries: a small handoff capsule written
before compaction and restored at the next session, mandatory /mb done
gates that run even without an active plan, and a sha256 hash chain that makes
tampering of historic progress.md entries a CRITICAL drift. Shipped through
the governed dual-review (Codex + lead) + judge pipeline, with a fix-cycle per
task.

Added

• Handoff capsule (scripts/mb-handoff.sh + memory_bank_skill/handoff_capsule.py).
  --actualize/--read/--rotate a ≤1500-byte capsule under
  .memory-bank/handoff/. The five sections (Now / Done / Open blockers / Next
  concrete step / Pointers) always survive truncation — the skeleton is reserved
  first and only the bullet lists are byte-fit, so the most important section is
  never dropped. UTF-8-safe byte cap; colon-free archive names;
  copy-then-atomic-rename so a capsule is never lost on interrupt; owner-token
  mkdir lock for single-writer safety. (REQ-120)
• PreCompact actualize (hooks/mb-pre-compact.sh, renamed from
  mb-compact-reminder.sh). On preCompact, refreshes the capsule within a ~2s
  portable budget and never blocks compaction — on timeout/failure/no-bank it
  WARNs and exits 0, killing the whole actualize process tree (no orphans). Opt
  out with MB_PRECOMPACT_HANDOFF=off. (REQ-120, REQ-121)
• SessionStart capsule consumption (hooks/mb-session-start-context.sh).
  Prepends the capsule only when it is newer than the most recent progress.md
  date heading; otherwise the normal context is unchanged. (REQ-121)
• Mandatory /mb done gates (scripts/mb-done-gates.sh). Tests + rules
  (with --diff-files so the CRITICAL TDD-delta check runs) + placeholder scan,
  honouring done_gates.required. --force requires a single-line --reason
  (newline-injection rejected), records a NOTE in progress.md + a failure JSON,
  and fails closed when allow_force:false or a project pipeline.yaml
  cannot be parsed. Configurable via pipeline.yaml:done_gates. (REQ-122, REQ-123)
• Append-only hash chain (scripts/mb-progress-chain.sh +
  memory_bank_skill/progress_chain.py). --rebuild-tail/--verify a sha256
  chain of the last 20 progress.md entries in index.json:progress_chain;
  mb-drift.sh raises CRITICAL on a mismatch, deletion, ambiguous match, or a
  malformed index.json. Canonical-form hashing (LF-normalised, trailing
  separators excluded) keeps legitimate appends stable while in-body content and
  whitespace edits remain tamper. (REQ-124)
• scripts/mb-rules-check.sh --placeholders-only — scan-only mode for the
  done-gate, with tests/-path and # mb-rules-check: allow-placeholder
  exemptions.
• Docs — docs/handoff-2.0.md (capsule lifecycle, done-gate + force
  semantics, hash-chain limits).

Changed — defaults

• /mb done now runs the done-gate set as step 0 (enabled by default; failures
  require --force --reason). Existing plan/spec verification is unaffected.
• settings/hooks.json registers mb-pre-compact.sh on preCompact (replacing
  the old weekly compact reminder, which remains available in adapters/cline.sh
  via MB_COMPACT_REMIND). Re-registration stays idempotent.

tier1-graph-memory (Phase 5) — 2026-06-14

tier1-graph-memory. Sharper code-graph retrieval (RRF fusion, import-aware
Python call resolution, PageRank god-nodes), richer session memory
(progressive-disclosure recall, per-turn outcomes, structured summaries), and
three new $0 memory-hygiene commands (/mb recap, /mb conflicts,
/mb consolidate). Every new opt-in layer keeps base output byte-identical.

Changed — defaults

• RRF fusion is the default auto-backend in code search. With embeddings
  installed, mb-semantic-search.py --backend auto now fuses the embeddings and
  BM25 rankings via Reciprocal Rank Fusion (rrf_merge, by_id built at index
  time, O(k) query fusion) instead of using embeddings alone. auto without
  embeddings stays pure BM25 (byte-identical to before); explicit --backend bm25/embeddings are regression-locked. (REQ-001/REQ-002)
• Import-aware call resolution for Python. call edges in .py files now
  resolve through the file's actual imports — binding order is: local def wins

  explicit import (relative level + as-alias aware) > single star-import
  match > unique project-wide fallback > suppress homonyms. Dotted dst
  namespacing via the new codegraph_binding.py. Non-.py edges pass through
  verbatim; the graph cache is bumped to CACHE_VERSION=2. Resolution for the
  tree-sitter languages (Go/JS/TS/Rust/Java) stays name-based. (REQ-003/REQ-004)

• god-nodes.md is ranked by PageRank, with degree as a secondary column
  (was degree-only). Pure-stdlib power iteration (networkx.pagerank semantics,
  no numpy/scipy) in codegraph_rank.py, full-precision sort with 6-dp display,
  cross-process deterministic. Without networkx the report degrades to
  degree-only and prints a one-line install hint. (REQ-005/REQ-006)

Added

• rrf_merge(rankings, k=60) — standalone Reciprocal Rank Fusion module
  (memory_bank_skill/rrf.py), the single source of truth for rank fusion across
  code search and /mb recall. (REQ-001)
• churn_30d ranking signal under /mb graph --cochange. Per-file 30-day
  churn is derived from the same git-log pass as co-change mining (one
  subprocess, asserted) and emitted as additive {"type":"node-attr"} JSONL
  rows only under --cochange; semantic search applies a 1+0.1·log1p(churn)
  boost after ranking/fusion over the full candidate set, then truncates. No
  churn attrs → ranking byte-identical. (REQ-007)
• Community-summary retrieval in code search. When a /mb wiki article lands
  in the top-3 final hits, mb-semantic-search.py appends a labeled
  community_files block (member files from .wiki-packs.json, sorted, capped
  at 10). Fail-open: missing/malformed packs or non-article hits → byte-identical
  no-wiki output. (REQ-008)
• Per-turn capture upgrade — outcome + diffstat. Each session Live-log
  bullet now records an ok | err(N) outcome (turn-scoped is_error count) and
  an aggregate +A/-B diffstat from a single git diff --numstat; fails closed
  outside work trees / bare repos. (REQ-009)
• Structured summary schema v2. The session-end Haiku summarizer now consumes
  the session's own distilled Live log (never the raw transcript tail) and is
  prompted for exactly four sections — What changed / Decisions / Open questions
  / Files. summary_schema: v2 is stamped only after a strict in-order heading
  validation passes (duplicate/out-of-order headings are rejected, see I-069);
  non-conforming output is stored unflagged. (REQ-010/REQ-011)
• Progressive-disclosure /mb recall. Default output is now a compact index
  — one id · age · summary · source line per hit (~15 tokens/line, no chunk
  bodies). --expand <id> returns one full chunk (exit 3 on unknown id),
  --full keeps the legacy bodies. Semantic + lexical hits are fused via RRF
  when the semantic backend is available (fail-open to lexical-only otherwise);
  [SUPERSEDED] chunks sort last with a ⊘ label. (REQ-001/REQ-016–019)
• /mb recap <sid> — rebuild a full progress.md entry from a session stub
  via one Haiku call (scripts/mb-recap.sh). Surgically replaces only that
  session's auto-capture stub (atomic temp→mv, neighbors byte-identical),
  idempotent via recapped frontmatter; strict no-write refuse paths with pinned
  exit codes (missing session/progress → 2, no claude → 3, no stub → 4,
  error-shaped output → 5); ambiguous prefix → refuse and list candidates.
  (REQ-020/REQ-021)
• /mb conflicts [--judge] [--threshold N] — surface memory entries with
  high lexical overlap and opposing/replacement assertions (en+ru negation
  markers) as conflict candidates over notes/ + lessons.md + recent
  progress.md. $0 default pass (token-set Jaccard > N, default 0.3, zero
  LLM calls); --judge confirms/rejects each candidate via one Sonnet call and
  prints a suggested `[SUPERSEDED: YYYY-MM-DD -> <re...

v5.0.1

Fixed

• pipx / pip / Homebrew installs no longer abort. The memory-bank CLI now
  exports MB_PYTHON=sys.executable (plus MB_SKILL_BUNDLE), and
  install.sh/uninstall.sh run every embedded Python step through it. A bare
  system python3 cannot import memory_bank_skill from a pipx/venv install
  and — under set -euo pipefail — aborted the whole install. Direct
  bash install.sh from a git checkout is unaffected (falls back to python3).
• /mb wiki merge on Python 3.11/3.12. merge_semantic_edges() used
  Path.read_text(newline=...), which only exists on Python 3.13; replaced
  with open(newline="") so supported interpreters don't raise TypeError.
• mb-semantic-search.py argument order. The optional mb_path positional
  is now accepted after options (query --json <mb_path>) via
  parse_intermixed_args.

Changed

• README redesigned (centered hero + banner, nav anchors, v5 callout, stats
  table, Diátaxis-grouped docs section, star-history footer); stale v4-era
  claims fixed.
• Landing page: og-image.png + favicon.svg, Open Graph / Twitter-card /
  canonical metadata, refreshed documentation links.
• PyPI metadata: Development Status :: 5 - Production/Stable + expanded
  keywords.

Added

• New docs: docs/first-feature.md (worked end-to-end example),
  docs/troubleshooting.md, docs/agents-reference.md (all 29 subagents).
• SECURITY_AUDIT_REPORT.md archived to docs/security/audit-2026-04-21.md
  with a historical-snapshot note; SECURITY.md supported-versions table
  refreshed.

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, ke...

v4.0.0 — Skill v2 major release

Skill v2 — major architectural refactor

Phases 3 + 4 + I-033 ship the executable engine. Tests grew 335 → 615 (+280) across the v2 work.

Highlights

/mb config + pipeline.yaml — declarative engine config (references/pipeline.default.yaml). 11 roles, 3-step stage_pipeline (implement → review → verify), severity gates, budget thresholds, 6 default protected_paths, sprint context guard at 150k/190k, 5-section review rubric, SDD knobs.

/mb work execution engine — 5-form target resolution, range parsing (plan stages or phase sprints), JSON-Lines stage emission with role auto-detection (ios → android → frontend → backend → devops → qa → architect → analyst → developer fallback), per-stage implement → review → fix-cycle → verify loop, --auto autopilot with hard stops on max-cycles / verify-FAIL / protected-paths / budget / context guard.

9 role-agents + reviewer + verifier — mb-developer, mb-backend, mb-frontend, mb-ios, mb-android, mb-architect, mb-devops, mb-qa, mb-analyst, plus production-grade mb-reviewer (rubric walk + JSON schema + fix-cycle behavior) and plan-verifier (7 checks).

5 critical Claude Code hooks — protected-paths-guard (PreToolUse Write/Edit), plan-sync-post-write (PostToolUse Write chain to roadmap-sync + traceability-gen), ears-pre-write (requirements/context EARS validation), context-slim-pre-agent (PreToolUse Task; emits trimmed prompt as additionalContext), sprint-context-guard (PreToolUse Task; cumulative session token spend with soft/hard thresholds).

--slim/--full end-to-end — mb-context-slim.py extracts active stage block + DoD bullets + covers_requirements + optional git diff --staged. mb-session-spend.sh companion CLI tracks chars→tokens via /4 estimate.

Installer auto-registration — settings/hooks.json carries 5 v2 entries with [memory-bank-skill] markers; merge-hooks.py strips/re-appends idempotently. install.sh step 6.5 probes ~/.claude/skills/superpowers/. scripts/mb-reviewer-resolve.sh honours pipeline.yaml:roles.reviewer.override_if_skill_present so /mb work review step routes to superpowers:requesting-code-review when present.

I-033 — checklist hard-cap enforcement — scripts/mb-checklist-prune.sh collapses fully-✅+plans/done sections to one-liners with pre-write backup. ≤120-line hard cap enforced in CI (tests/pytest/test_checklist_cap.py). Wired into commands/done.md, mb-plan-done.sh, mb-compact.sh. Closes the spec §3 / §13 rotating-artifact gap.

Breaking change

~/.claude/settings.json now includes 5 new mb--prefixed hook commands. Existing installs auto-merge via merge-hooks.py. Re-run bash install.sh to apply.

Full scope

See CHANGELOG.md [4.0.0] section.

v3.1.2

Review findings hardening + installer boundary refactor. Seven stages
closing three classes of problems surfaced by the full-repo review and
security audit: P0 security risks around path traversal and manifest
poisoning, architectural debt in install.sh / adapter layer, and
contract / maintainability drift in CLI, manifests, and shared helpers.
All 3 High findings from SECURITY_AUDIT_REPORT.md closed; 601/601 bats

• 246/246 pytest green.

Added

• Safe path helpers in scripts/_lib.sh — canonicalization and subtree
  validation reused by install.sh / uninstall.sh / adapters. Traversal
  payloads in .claude-workspace, uninstall manifest paths, and adapters/pi.sh
pi_skill_dir all fail closed.
• MB_ALLOW_METRICS_OVERRIDE=1 opt-in gate for .memory-bank/metrics.sh
  execution. Default blocks user-supplied overrides with an actionable hint.
• -y / --non-interactive flags on uninstall.sh and the Python
  memory-bank uninstall CLI. Both skip the prompt for CI/automation usage.
• schema_version + deterministic file/backup ordering in the global
  install manifest. Unblocks safe tooling that reasons over manifests.
• memory_bank_skill/_io.py — shared atomic-write helper; replaces four
  duplicated _atomic_write() implementations in Python scripts.
• memory_bank_skill/_texttools.py — shared strip_marked_section /
  localize_language_rule / etc.; replaces four near-identical Python
  heredoc blocks in uninstall.sh with one shared call path.
• adapters/_framework.sh + adapters/_contract.sh — shared adapter
  entrypoints (install/uninstall), manifest writing, hook JSON merge, and
  contract invariants. Sourced by all 7 adapters.
• references/adapter-manifest-schema.md — documented manifest schema
  (schema_version, adapter, installed_at, files, optional keys).
• Direct bats coverage for mb-note.sh, mb-plan.sh, _lib_agents_md.sh
  refcount/atomic-write behavior, 10 MB hook-log rotation boundary, and
  run_shell() subprocess failure path — closes review-cited test gaps.
• test_texttools.py pytest coverage for atomic write rollback,
  marker-strip, and language-rule localization.

Changed

• install.sh no longer contains client-specific Cursor global helpers —
  hooks / AGENTS / user-rules logic moved into adapters/cursor.sh. The
  universal installer is now orchestration only (argument parsing + shared
  install + adapter invocation). install.sh: 1 reference vs
  adapters/cursor.sh: 8 references post-refactor.
• uninstall.sh delegates adapter cleanup instead of relying solely on
  the global manifest. Adapter artifacts round-trip cleanly; user content
  preserved.
• adapters/_lib_agents_md.sh writes owner state atomically with an
  explicit jq preflight that fails clearly when the binary is missing.
• All 7 adapters migrated to the shared framework without changing their
  public CLI. OpenCode/Codex/Pi shared AGENTS.md coexistence preserved.
• mb-compact.sh is narrowed back to archival decay. Structural migration
  of checklist.md done-sections and plan.md deferred/declined bullets now
  lives in mb-migrate-structure.sh, which keeps compaction and migration on
  separate boundaries again.
• settings/merge-hooks.py now strips only Memory Bank-owned hook items
  within mixed entries, preserving unrelated user commands in the same event.
• Pi's native MB_PI_MODE=skill path is no longer part of the supported
  default surface. Normal installs stay on agents-md; native-skill probing
  requires the explicit MB_EXPERIMENTAL_PI_SKILL=1 gate.

Fixed

• Traversal payloads in .claude-workspace, uninstall manifest paths, and
  adapters/pi.sh pi_skill_dir now reject external targets before any
  destructive operation.
• install.sh::backup_if_exists() refuses symlink targets that escape
  managed directories; safe regular-file idempotency preserved.
• memory-bank install fails early on unknown --clients values with a
  clear error before install.sh runs.
• settings/merge-hooks.py no longer drops mixed user/MB hook entries when
  the first hook item happens to be MB-owned.

Docs

• README.md, docs/install.md, docs/release-process.md, SECURITY.md
  now document memory-bank uninstall -y, MB_ALLOW_METRICS_OVERRIDE=1
  opt-in, and Pi's experimental native skill gate.

v3.1.1

i18n infrastructure release. Memory Bank now ships locale-aware
.memory-bank/ template bundles. Existing English users are unaffected —
this is a pure capability addition.

Added

• Locale template bundles under templates/locales/{en,ru,es,zh}/.memory-bank/.
  en and ru ship as full translations; es and zh ship as scaffolds
  (EN copy + TODO(i18n-<lang>) banner) that the community can complete via
  PR — see docs/i18n.md.
• New scripts/mb-config.sh — 4-tier locale resolver:
  1. MB_LANG env var
  2. $MB_ROOT/.memory-bank/.mb-config (lang=XX)
  3. Heuristic auto-detect from existing bank content (Cyrillic → ru) with
     write-back for determinism
  4. Default en
• New scripts/mb-init-bank.sh — deterministic, locale-aware bank
  scaffolder. Respects --lang=XX, MB_LANG, existing .mb-config; never
  overwrites user-authored files.
• memory-bank init --lang=XX CLI flag and /mb init --lang=XX
  command form.
• install.sh --language {en|ru|es|zh} — expanded whitelist (was en|ru).
• docs/i18n.md — contributor guide for adding a new locale.

Contract

• Canonical English anchors (<!-- mb-active-plans -->,
  <!-- mb-recent-done -->, ## Ideas, ## ADR) remain English in every
  locale bundle — every mb-* script depends on them.
• commands/mb.md, script CLI output, and the main English docs stay English.

Coverage

• 216 pytest + 14 skipped (pytest suite)
• 14/14 mb-config bats
• 9/9 mb-init-bank bats
• 28/28 install/uninstall e2e bats

v3.1.0

Major refactor of core Memory Bank files (STATUS.md, plan.md, checklist.md, BACKLOG.md) with stricter formats, multi-active plan support, monotonic idea IDs, and a dedicated mb-compact.sh extension that prunes stale checklist.md / plan.md entries.

Breaking-ish (auto-migrated)

• plan.md / STATUS.md now carry multi-active plan blocks. The singular <!-- mb-active-plan --> / <!-- /mb-active-plan --> markers are upgraded to plural <!-- mb-active-plans --> / <!-- /mb-active-plans --> and the heading ## Active plan → ## Active plans. STATUS.md gains a new <!-- mb-recent-done --> / <!-- /mb-recent-done --> block (default-trimmed to 10 entries via MB_RECENT_DONE_LIMIT).
• BACKLOG.md now has a fixed skeleton — ## Ideas (with ### I-NNN — title [PRIO, STATUS, DATE] entries) + ## ADR (with ### ADR-NNN — title [date] entries). IDs are monotonic project-wide.
• Migration is automatic. Run bash scripts/mb-migrate-structure.sh --apply .memory-bank (or /mb migrate-structure --apply). The script creates a timestamped .pre-migrate/YYYYMMDD_HHMMSS/ backup before touching anything, upgrades marker names, and ensures the skeleton is present. Rerunning is a no-op (idempotent). See docs/MIGRATION-v3-v3.1.md.

Added

• scripts/mb-idea.sh — capture a new idea in BACKLOG.md ## Ideas with an auto-assigned I-NNN ID (monotonic, project-wide). Usage: bash scripts/mb-idea.sh "title" [HIGH|MED|LOW]. Wired as /mb idea.
• scripts/mb-idea-promote.sh — promote an existing idea (I-NNN) to a plan file. Validates idea is in NEW/TRIAGED state, calls mb-plan.sh <type>, flips idea status to PLANNED, adds **Plan:** cross-link, and runs mb-plan-sync.sh to register the new plan in plan.md + STATUS.md. Wired as /mb idea-promote.
• scripts/mb-adr.sh — capture a new ADR in BACKLOG.md ## ADR with an auto-assigned ADR-NNN ID and a standard skeleton (Context / Options / Decision / Rationale / Consequences). Wired as /mb adr.
• scripts/mb-migrate-structure.sh — one-shot v3.0 → v3.1 structural migration tool (dry-run by default; --apply to execute). Wired as /mb migrate-structure.

Changed

• scripts/mb-plan-sync.sh is now multi-active-plan aware. Upserts the same plan into <!-- mb-active-plans --> blocks in both plan.md and STATUS.md (deduped by basename). Auto-upgrades legacy singular markers on first run. Stage sections are appended to checklist.md with exact-heading matching so two active plans never collide on identical stage titles.
• scripts/mb-plan-done.sh is fully redesigned. Instead of just ticking checkboxes, it now (1) removes the plan's stage sections from checklist.md entirely, (2) removes its entry from the active-plans blocks in plan.md + STATUS.md, (3) prepends the completed plan to <!-- mb-recent-done --> in STATUS.md (trimmed to MB_RECENT_DONE_LIMIT, default 10), (4) flips any linked BACKLOG.md idea from PLANNED → DONE and appends an **Outcome:** placeholder, and (5) moves the plan file to plans/done/.
• scripts/mb-compact.sh extended with checklist.md + plan.md compaction:
  • CHECKLIST_AGE_DAYS (default 14) — fully-done checklist sections that link to a plans/done/ file older than this threshold are removed on --apply.
  • Bullets inside plan.md ## Отложено / ## Deferred (and ## Отклонено / ## Declined) are migrated into BACKLOG.md as new ideas with status DEFERRED (or DECLINED) and removed from plan.md. Section headings are preserved empty for future use.
• templates/.memory-bank/ — STATUS.md, plan.md, checklist.md, BACKLOG.md redesigned around the new marker blocks and ID schemes. Header comments explain each file's role, size recommendations, and script contracts (deliberately avoid mentioning literal marker names to prevent regex false-positives in format-invariant tests).
• references/structure.md — rewritten as the v3.1 specification. Defines format invariants, lifecycle (NEW → TRIAGED → PLANNED → DONE / DEFERRED / DECLINED), ID schemes (I-NNN, ADR-NNN, H-NNN, EXP-NNN), control env vars (MB_RECENT_DONE_LIMIT, MB_COMPACT_CHECKLIST_DAYS, MB_COMPACT_AGE_DAYS), and per-file / per-directory contracts.
• commands/mb.md — new subcommands /mb idea, /mb idea-promote, /mb adr, /mb migrate-structure documented in the routing table and body sections.

Fixed

• Python regex deprecation warnings — replaced POSIX [[:space:]]* with \s* in the Python snippets embedded in scripts/mb-compact.sh and scripts/mb-migrate-structure.sh.
• BSD/GNU awk portability — mb-idea.sh ID generation now uses grep -Eo | awk -F- | sort -n | tail -1 || true instead of GNU-only awk match(..., arr). mb-adr.sh multiline skeleton is written to a temp file and pulled into awk via getline to avoid awk: newline in string on macOS.
• mb-idea-promote.sh Unicode-aware parsing — title/status extraction switched from sed -E / tr -d (which failed on multibyte —) to Python re.match.

Tests (TDD RED→GREEN)

• 8 new BATS suites, 1 new pytest suite:
  • test_plan_sync_multi.bats (8 tests) — multi-active plan upsert, idempotency, legacy-marker upgrade.
  • test_plan_done_multi.bats (7 tests) — completion flow: recent-done prepend/trim, checklist section removal, BACKLOG status flip.
  • test_idea.bats (7 tests) — monotonic I-NNN IDs, priority handling, idempotency, invalid-input validation.
  • test_idea_promote.bats (6 tests) — plan creation from idea, NEW → PLANNED flip, plan cross-link, active-plans registration.
  • test_adr.bats (6 tests) — monotonic ADR-NNN, skeleton sections, date format.
  • test_compact_checklist.bats (6 tests) — fully-done section removal linked to old plans/done/, env-var override.
  • test_compact_plan_md.bats (7 tests) — Отложено → DEFERRED, Отклонено → DECLINED, English alias support.
  • test_migrate_structure.bats (8 tests) — dry-run / apply modes, backup creation, marker upgrade, skeleton injection, idempotency.
  • test_templates_format.py — format invariants for all four core templates.
• test_plan_sync.bats (legacy) updated to the v3.1 contract (single-plan edge cases + error handling); multi-plan behaviour lives in the new suites.
• tests/e2e/test_install_uninstall.bats grew one assertion verifying the new v3.1 scripts (mb-idea.sh, mb-idea-promote.sh, mb-adr.sh, mb-migrate-structure.sh, mb-compact.sh) are installed and executable.

Migration guide

See docs/MIGRATION-v3-v3.1.md for the step-by-step upgrade. TL;DR:

# 1. Install the new version
pipx upgrade memory-bank-skill       # or brew upgrade memory-bank
# 2. Run the automatic structural migration
bash ~/.claude/skills/memory-bank/scripts/mb-migrate-structure.sh --apply .memory-bank
# 3. Verify backup was created
ls .memory-bank/.pre-migrate/