…cations)

PR #889 added mock-subprocess e2e tests for FALSIFY-MCP-003/-004 and discovered
two spec-vs-CLI mismatches via test failures:

1. apr.run: spec listed `stop_reason` in output — CLI's print_run_output
   (crates/apr-cli/src/commands/run_entry.rs:279) does NOT emit it.
   Spec corrected to the actual emitted set (model, text, tokens, ...).

2. apr.qa: spec wrote gates as `{pass, value, threshold}` — CLI's GateResult
   (crates/apr-cli/src/commands/qa.rs:368) uses `passed` not `pass`.
   Spec corrected.

Also fixes the codegen source reference: FALSIFY-MCP-008 uses
contracts/apr-mcp-tool-schemas-v1.yaml (PR #871), not apr-cli-commands-v1.yaml.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

PR #862 is a matmul test fix, not the MCP M1 skeleton. The correct
skeleton PR is #864 (`feat(mcp): apr mcp M1 skeleton — MCP server
over stdio`). All three stale citations in the M1 milestone replaced.

Five-whys root cause: the spec retrofit (#873) reconstructed PR
numbers from memory; future retrofits should verify against
`git log --grep=...` before committing.

Refs PMAT-037.

Three stale citations corrected in the M3 milestone:
- #874 removed from cancellation bullet (#874 is the book-chapter doc
  commit, not cancellation — that's #883 alone).
- `contracts/apr-mcp-server-v1.yaml (ACTIVE) ... (#886)` bullet moved
  from M3 SHIPPED to M4 IN PROGRESS. PR #886 is still OPEN and its
  own title says "M4 — apr-mcp-server-v1 contract ACTIVE". The file
  is not in-tree. Header's "**New**:" label also updated to "Pending
  (PR #886)" for the same file.
- Book-chapter citation expanded to list #874 (M2 creation) + #885
  (M3 update) for accurate provenance.

Five-whys root cause (false "M3 SHIPPED" on #886): the spec promotion
commit (a496ce9) rolled unmerged M4 work into M3 bullets under the
optimistic assumption the PR would land first. Going forward: any
bullet citing a PR must verify `gh pr view <N>` is MERGED before
promoting a milestone.

Refs PMAT-037.

The Architecture + Protocol + Out-of-Scope sections carried pre-M1
aspirations that no longer match the shipped crate. Refreshed against
actual source tree in crates/aprender-mcp/:

- Goal: schema source was `apr-cli-commands-v1.yaml`; lines 11/87/139
  correctly cite `apr-mcp-tool-schemas-v1.yaml`. Unified.
- Directory diagram: listed absent `schema.rs`; missing `build.rs`,
  `types.rs`, `tools/subprocess.rs`, `tools/version.rs`. `server.rs`
  comment said "pmcp::Server wiring" but M1 shipped a hand-rolled
  JSON-RPC loop (also noted line 149). `Cargo.toml` comment listed
  pmcp/tokio/clap/apr-cli — none are actual deps (verified: serde,
  serde_json, anyhow, nix, serde_yaml build, jsonschema dev).
  `tests/` now lists the four actual `falsify_*.rs` harnesses.
- `apr mcp` subcommand: snippet promised `async` with `McpArgs` +
  transport matching + SSE; actual `run()` is blocking, takes no
  args, calls `AprMcpServer::new().run_stdio()`.
- Protocol/Transport: "SSE optional" was false; flag doesn't exist.
  Downgraded to stdio-only and added SSE to Out of Scope.

Five-whys root cause: the Architecture diagram was authored pre-M1
as a design sketch; later commits (#873 retrofit, v1.1.0 promotion)
updated Milestones but never re-diffed the static diagram against
`ls crates/aprender-mcp/src/`. Going forward: any spec change
touching Milestones must run a diagram-vs-tree check.

Follow-up filed: verify Config Precedence (lines 122-126) against
implementation — `pub fn run()` consults no env vars today.

Refs PMAT-037.

Two factual errors corrected:

- Tool count: spec said "8 Phase-1 tools" (lines 74, 133); `tools/list`
  actually returns 9 because `apr.version` (M1 scaffold) is also
  registered. Verified by
  `crates/aprender-mcp/tests/falsify_m1.rs::falsify_mcp_002_tools_list_schema_shape`,
  which asserts all 9 names (apr.version + 8 workflow tools).
  Clarified spec to state "8 Phase-1 workflow tools + apr.version
  scaffold = 9 total registered" and added test cross-link to the
  FALSIFY-MCP-002 bullet.

- Related Work line 210 claimed `crates/apr-cli/src/tool_commands.rs`
  is the "planned MCP tool surface (referenced but unimplemented)".
  That file exists and is the `apr tool` CLI subcommand group
  (Showcase, Rosetta, …), unrelated to MCP. The actual MCP tool
  surface lives in `crates/aprender-mcp/src/tools/`. Corrected and
  noted that rust-mcp-sdk (paiml/rust-mcp-sdk) is currently unused
  since M1 shipped a hand-rolled JSON-RPC dispatcher.

Five-whys root cause (8 vs 9): the original Phase-1 design enumerated
8 workflow tools and `apr.version` was added later as an M1 handshake
probe without updating the narrative count. No invariant check
cross-references spec tool-count against `tools/list` test assertions.

Refs PMAT-037.

Lines 122-126 stated a four-level config precedence (`--config`,
`$APR_MCP_CONFIG`, `~/.config/apr/mcp.toml`, defaults) as if it were
implemented. Actual `crates/apr-cli/src/commands/mcp.rs::run()` takes
no arguments and consults no env vars; `AprMcpServer::new()` has no
config loader. The `APR_MODEL_DIR` env in the `.mcp.json` snippet is
read by the spawned `apr <cmd>` subprocesses, not by the MCP server.

Rewrote the section to keep the intended precedence as the Phase-2
contract while making Phase 1's "no config loader" reality explicit.

Five-whys root cause: the Configuration section predates the M1
skeleton and was not re-verified against `commands/mcp.rs` during
the v1.1.0 promotion. A "spec bullet implies an API — grep for the
API" check belongs in the promotion workflow.

Refs PMAT-037.

Spec's Falsification Conditions section lists 9 entries (FALSIFY-MCP-001
through -008 plus FALSIFY-MCP-PROGRESS-001 added in M3), but the Success
Criteria table still said "8 falsification gates". Count corrected and
wording clarified to reflect that -003/-004 are currently PARTIAL and
must promote to PASS at M4 close.

Five-whys root cause: adding PROGRESS-001 in M3 touched the conditions
section but didn't update the downstream summary row. Going forward:
whenever a new FALSIFY-MCP-* lands, grep the spec for `N falsification`
to catch all downstream counts.

Refs PMAT-037.

Three dangling claims resolved:

- Target version: `v0.32.0 / v0.33.0` stands as the intended release
  tags but `git tag -l 'v0.3*'` returns only `v0.3.0 / v0.3.1 / v0.30.0`.
  M1–M3 are merged on `main` but unreleased. Added a clarifier so a
  reader doesn't assume those tags exist.
- Aspirational follow-ons: `apr-mcp-plugin-marketplace-v1.md` and
  `apr-mcp-hooks-v1.md` are not in `docs/specifications/`. Labelled
  "(spec files not yet authored)" so readers don't hunt for them.
- Risk Register: "pmcp crate API instability" is dormant because M1
  shipped a hand-rolled JSON-RPC dispatcher (line 166 already notes
  pmcp is deferred). Row reworded so the risk's activation condition
  is explicit.

Five-whys root cause (across all three): the spec's non-Milestone
sections — Target, Related Work, Risk Register — were not refreshed
during v1.1.0 promotion. Every milestone promotion should sweep those
sections, not just the milestone table.

Refs PMAT-037.

Five-Whys:
- Symptom: dual pmcp versions (1.20 + 2.3) resolved in agents-mcp build.
- Why #1: pforge-runtime 0.1.4 (last released 2025-12) still pins pmcp 1.x.
- Why #2: pforge-runtime was listed as an optional dep alongside pmcp.
- Why #3: it was a forward-compat hedge — but no Rust code imports it
  (only doc-comment mentions and knowledge-graph string literals).
- Why #4: keeping an unused dep doubled the compile footprint and split
  the pmcp protocol surface across two crates.
- Root cause: speculative dep on a framework wrapper for an SDK we
  already use directly.

Fix:
- Cargo.toml: bump pmcp 1.10 → 2.3 (PAIML's actively-maintained SDK);
  remove pforge-runtime dep; agents-mcp feature now just ["agents","pmcp"].
- Doc comments and the mcp_demo example rewritten to name pmcp v2.3 as
  the SDK instead of pforge. No Rust-level API change — pforge-runtime
  was never imported, just advertised.
- cargo tree -i pmcp now shows a single pmcp v2.3.0 node.

Follow-up: spec's pmcp framing (M1 note + Risk Register) still needs
rewrite in apr-mcp-server-spec.md.

…an (Refs PMAT-037)

Five-Whys:
- Symptom: spec framed pmcp as unstable/dormant, treating the SDK as risk
  rather than planned substrate.
- Why #1: Risk Register called out "pmcp crate API instability (dormant...)"
  — language from before pmcp was actively maintained.
- Why #2: M1 note said "pmcp SDK deferred — more deterministic for current
  scope" without explaining the actual technical rationale.
- Why #3: no adoption path existed — M4 stops at dogfood, so readers
  couldn't tell whether pmcp would ever land.
- Why #4: pmcp v2.3 is PAIML's own crate (paiml/rust-mcp-sdk) and already
  used by aprender-orchestrate; keeping the spec's out-of-date framing
  forced the /tmp/spec-update session to discover this from crates.io.
- Root cause: stale spec language from the early M1 period where the
  adoption path was genuinely uncertain; never updated after pmcp
  stabilised.

Fix:
- Line 15: link now labels pmcp as "PAIML's Rust MCP SDK, actively
  maintained, v2.3.1 on crates.io (2026-04-16)".
- Line 44 / 167: architecture + M1 note explain the three concrete
  reasons the dispatcher is hand-rolled (minimal request/response shape
  over `apr <cmd> --json`, build.rs schema codegen keeps tools/list
  byte-identical to contract YAML, falsification asserts on wire bytes
  without an SDK layer).
- Risk Register row rewritten from "API instability" to "adoption-path
  coordination" — real risk is workspace version alignment with the
  pmcp client role in aprender-orchestrate. Mitigation: single
  workspace-wide bump + `cargo tree -d` CI gate.
- New M5 milestone: concrete pmcp migration plan — port dispatcher to
  pmcp::Server (retain build.rs codegen), add SSE + WebSocket
  transports, re-run falsification suite post-migration.
- Out of Scope: SSE/WebSocket transports reclassified as "scheduled for
  M5 on top of pmcp v2.3".
- Related Work: pmcp-sdk contract row now notes aprender-orchestrate
  already links pmcp v2.3 as a client; server-side migration is M5.
- Version bumped 1.1.0 → 1.2.0.

…act v2.3 (Refs PMAT-037)

Five-Whys:
- Symptom: M4 bullet claimed "9 falsification_conditions" to match the 9
  gates listed in Section 145, but PR #886's contract pins exactly 8
  (FALSIFY-MCP-001..008) and a Rust test enforces that invariant.
- Why #1: the 9th gate (FALSIFY-MCP-PROGRESS-001) was added in M3 AFTER
  PR #886 was drafted.
- Why #2: PR #886's harness
  (apr_mcp_server_contract_ids_are_falsify_mcp_001_through_008) explicitly
  rejects anything outside 001..008, so the contract row for PROGRESS-001
  cannot land in the same PR without harness changes.
- Why #3: the spec's earlier count-reconciliation (2026-04-18 prior
  kaizen round) missed this because it was looking for text matches, not
  contract row counts.
- Root cause: spec and contract evolved on different PR branches.

Fix:
- M4 bullet: accurately describes PR #886 as landing 8 falsification
  rows, names the exact-8 invariant by its test function.
- Adds an explicit follow-up bullet: "Extend the contract with a 9th row
  for PROGRESS-001 after PR #886 merges — relax the exact-8 invariant to
  'FALSIFY-MCP-001..008 + PROGRESS-001, no extras'".
- Success Criteria table unchanged (line 220 still correctly says "9
  falsification gates ... all PASS or PARTIAL→PASS by M4 close") — the
  9th gate is already ENFORCED in code via falsify_mcp_progress_001.rs,
  we just need the contract YAML to catch up.

Also:
- contracts/pmcp/mcp-protocol-sdk-v1.yaml version 1.0.0 → 1.1.0 with
  "last_modified: 2026-04-18".
- Description updated v2.1 → v2.3, adds consumer-of-record (aprender-
  orchestrate via agents-mcp feature) + future consumer (aprender-mcp
  M5 migration) + link to apr-mcp-server-spec.md.

…-037)

Five-Whys:
- Symptom: book chapter's M3 row missed FALSIFY-MCP-PROGRESS-001 (shipped
  via PR #887) and the paragraph called progress streaming "a follow-up
  slice" for BOTH apr.run and apr.finetune — incorrect for apr.finetune.
- Why #1: book chapter was authored before PR #887 landed
  progressToken-gated notifications for apr.finetune.
- Why #2: M5 pmcp migration (added to spec v1.2.0 today) had no
  corresponding row in the book status table.
- Root cause: book lagged spec after the M3 progress slice merged and
  after the M5 migration plan was formalised today.

Fix:
- M3 row now mentions the opt-in progress notifications.
- Paragraph specifies: FALSIFY-MCP-PROGRESS-001 is enforced for
  apr.finetune; only per-step structured progress (CLI event channel
  prereq) and apr.run progress (apr run --stream flag prereq) remain
  open.
- New M5 row in the status table mirrors the spec's M5 milestone.

…PMAT-037)

Five-Whys:
- Symptom: Section "Protocol" bullet on Streaming claimed "apr.run and
  apr.finetune send notifications/progress for each decoded token /
  training step" — but apr.run progress is a deferred M4 item and
  apr.finetune only emits per-stdout-line progress (not per training
  step) and only when the client opts in via progressToken.
- Why #1: the bullet was authored when both tools were planned to
  stream per-token. Reality diverged: progress landed for apr.finetune
  only (opt-in, per-line), apr.run was deferred.
- Why #2: the Architecture paragraph pointed to "Phase 2 with SSE" for
  transport selection without naming the actual M5 milestone that now
  schedules it.
- Root cause: drift between aspirational early-M2 text and the M3/M5
  structure formalised today.

Fix:
- Streaming bullet now names what's actually enforced
  (FALSIFY-MCP-PROGRESS-001, apr.finetune opt-in, per-stdout-line) and
  explicitly calls out the apr.run follow-up prereq (apr run --stream
  flag + per-step CLI event channel).
- Architecture paragraph points at M5 as the SSE/WebSocket landing
  spot rather than the generic "Phase 2".

Five-Whys:
- Symptom: CI job "Chapter Examples Compile" has been failing on every
  push to main since PR #701 (2 days), plus on this PR, with RUSTFLAGS=
  "-D warnings" promoting unused-import warnings to hard errors.
- Why #1: ch10_training and ch24_switch_pytorch both import
  `aprender::nn::Optimizer` but only call `optimizer.step_with_params`,
  which is an inherent method on `SGD` (not a trait method) — so the
  trait import is genuinely unused.
- Why #2: ch26_switch_ndarray binds `let pred = lr.predict(&x)` but
  never reads `pred` (score re-computes internally).
- Why #3: these examples predate the refactor that moved
  `step_with_params` from the Optimizer trait to inherent impls; the
  trait import was never cleaned up.
- Why #4: the Book Contract Enforcement and Chapter Examples Compile
  jobs are non-required checks, so the red status never blocked merges
  and accumulated as tech debt.
- Root cause: main CI andon rule (main must always be green) was
  waived for non-required checks. Toyota Way: "all defects are your
  defects" — fix it regardless of whose PR introduced it.

Fix:
- ch10_training.rs, ch24_switch_pytorch.rs: drop `Optimizer` from the
  aprender::nn:: import list.
- ch26_switch_ndarray.rs: consume `pred` by printing the first
  prediction — preserves pedagogical intent of showing predict() works,
  and unblocks -D warnings.
- `cargo build -p aprender-core --examples` now warnings-clean.

The "Every PCU page has matching contract" gate derived paths from the
PCU ID (`apr-page-${ID}-v1.yaml` / `apr-book-${ID}-v1.yaml`) but real
page headers already carry an authoritative `contract:` field, and
chapter contracts are named `apr-book-ch01-v1.yaml` (chapter-number
only) while PCU IDs include a slug (`ch01-why-rust`). The mismatch
failed all 27+ book pages on every run.

Five whys:
  1. Why red? Script can't find `apr-page-tools-apr-cli-v1.yaml`
     from ID `tools-apr-cli`... wait it can. But for chapters it
     looks for `apr-book-ch01-why-rust-v1.yaml` which doesn't exist.
  2. Why does it derive? The earlier convention stored ID-derived
     paths before `contract:` was added to headers.
  3. Why not updated when `contract:` was added? The workflow was
     not migrated; the two lookup paths stopped covering all cases.
  4. Why silent until now? The gate was not blocking main.
  5. Why fix now? Kaizen sweep surfaced 27-page failure.

Parse the authoritative `contract:` field. Also add missing PCU
header + page contract for book/src/tools/mcp-server.md (now points
to contracts/apr-page-tools-mcp-server-v1.yaml).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…-037)

Three places claimed `apr.serve` cancellation lands in M3:
 - book/src/tools/mcp-server.md apr.serve paragraph
 - crates/aprender-mcp/src/tools/serve.rs module/fn docs
 - serve tool `description` field embedded in tools/list

M3 actually shipped `notifications/cancelled` for apr.run only.
`server.rs::CancelHandle` doc explicitly states: "Only apr.run
currently honours cancellation." apr.serve remains fire-and-forget
and the spec M3 bullet list never promised otherwise.

Five whys:
  1. Why stale? Comments predicted M3 scope before scope narrowed.
  2. Why narrowed? Spec M3 scope: FALSIFY-MCP-006 for apr.run,
     -008 codegen, -PROGRESS-001 for apr.finetune. apr.serve
     lifecycle was never inside that gate set.
  3. Why not updated at M3 close? No acceptance criterion forced
     a sweep of surface prose when milestone shipped.
  4. Why matters now? Readers of book/tools page and users calling
     apr.serve via MCP get incorrect "lifecycle lands in M3" note
     that reads as imminent, not aspirational.
  5. Why fix now? Kaizen sweep surfaced; retarget to M5 where a
     daemon registry + pmcp Server port belong together.

Edits: book paragraph + serve.rs module header + serve.rs `call`
docstring + serve.rs description field + spec M5 new bullet for
apr.serve cancel extension. Also spec M5 falsification-suite bullet
updated from "71+ tests" to measured "75 tests" with file list.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…fs PMAT-037)

The apr.finetune paragraph said "Per-step notifications/progress
streaming is a follow-up M3 slice" — read as "no progress yet" —
but FALSIFY-MCP-PROGRESS-001 shipped in PR #887: per-line progress
over `params._meta.progressToken` IS live.

Five whys:
  1. Why stale? Paragraph was written before PR #887 merged.
  2. Why not updated at PR #887? PR focused on server.rs + test
     additions; book paragraph not flagged in review.
  3. Why matters? Clients reading the book will assume they cannot
     stream updates and skip progressToken, losing observability.
  4. Why two progress layers? Per-line (shipped, stdout-driven) vs
     per-step (needs a CLI event channel from `apr finetune`
     itself) — the former is cheap plumbing over JSON-RPC, the
     latter is a CLI-side refactor.
  5. Why fix now? Kaizen sweep surfaced.

Rewrote the paragraph to state (a) what shipped (opt-in per-line),
(b) the gate it satisfies (FALSIFY-MCP-PROGRESS-001), (c) the
honest limitation (terminal blob today), (d) where per-step
lives (M4 follow-up with CLI prereq).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…fs PMAT-037)

The apr-mcp-tool-schemas-v1.yaml header still read:
  "This M2 cut is RETROFIT-ONLY"
  "If this file ever disagrees with the Rust source, the Rust source wins"
  "In milestone M3 a build.rs at ... will read this YAML"

All three are post-M3 stale:
  1. M3 shipped (PRs #880, #884) — build.rs is live.
  2. Byte-identity is enforced by tests/falsify_mcp_008.rs (5 tests).
  3. Rust tool sources contain zero hand-written schemas — they only
     parse `crate::schemas::APR_<TOOL>_SCHEMA` from $OUT_DIR.
  4. Direction is reversed: YAML authoritative, Rust derived.

Five whys:
  1. Why stale header? Written for M2 retrofit cut.
  2. Why not flipped at M3 close? PR #884 focused on codegen, not
     contract prose.
  3. Why matters? Future readers will assume Rust source is the
     authority and "fix" the wrong side of a drift — inverting
     FALSIFY-MCP-008's intent.
  4. Why now? Kaizen sweep.
  5. Why v1.1.0? Semantic bump: authoritativeness change, plus new
     reference pointer to apr-mcp-server-spec.md.

Bumped metadata version 1.0.0 → 1.1.0, added last_modified, rewrote
header and description to reflect current state (YAML is SoT, Rust
parses codegen constants, falsify_mcp_008.rs enforces byte-identity).
Also updated spec M5 falsification-suite file list to include
`falsify_mcp_008` and drop nonexistent `codegen_bytes`.

Verified: `cargo test -p aprender-mcp --test falsify_mcp_008` — 5/5
pass after YAML comment edits (no functional change, just prose).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

The spec claimed a 57-command CLI surface three times:
  - Contracts bullet: "57-command tool surface"
  - Problem paragraph: "57-subcommand CLI"
  - Goal paragraph: "subset of the 57 apr CLI commands"

PR #864 registered `apr mcp` as the 58th command
(contracts/apr-cli-commands-v1.yaml). The 63-line count in the
contract is 58 commands + 5 FALSIFY-CLI-00* falsification rules.

Five whys:
  1. Why stale? The 57 figure dates to #701 contract landing
     (2026-04-06) — the initial MCP PRs added `apr mcp` but
     didn't sweep cross-cutting doc claims.
  2. Why matters? MCP spec's own subject command is the 58th — a
     reader comparing counts will mistrust the surface-area claim.
  3. Why only fixing here? Scope is `apr-mcp-server-spec.md`;
     CLAUDE.md and apr-book-spec.md have broader audiences and
     want their own kaizen passes.
  4. Why cite PR #864 inline? Makes the delta auditable by a
     future reviewer checking `git log --oneline apr-cli-commands-v1.yaml`.
  5. Why not reword to "58+ commands" for future-proofing? The
     contract is the source of truth; stale counts are better
     caught by an exact-match CI gate than smeared over with
     imprecise phrasing. (PR #864 added a FALSIFY-CLI gate.)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

… M2) (Refs PMAT-037)

The footer claimed:
  v0.32.0 (M1–M2), v0.33.0 (M3–M4)

But M3 shipped on 2026-04-18, same week as M2 (2026-04-17/18), and
the workspace is still at v0.30.0 on main. The old split-tag plan
(M1–M2 in one release, M3–M4 in the next) no longer maps to
reality — M3 will publish alongside M1–M2 because there's nothing
to publish in between.

Five whys:
  1. Why stale? Target was written assuming M2 → cut release → M3.
  2. Why reality diverged? M3 landed fast because cancellation +
     codegen + progress + apr.finetune were all independent PRs.
  3. Why matters? A reader looking at `git tag` + this footer
     would expect v0.32.0 to exist; it doesn't.
  4. Why not assign firm tags? Release cuts require a separate
     decision (changelog + publishing); this spec shouldn't
     preempt it.
  5. Why keep historical context? Future reader asking "why is
     the M3–M4 split collapsed?" deserves a traceable answer
     instead of silently rewritten history.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…AT-037)

The crate README was three milestones behind the spec:
  - M2 bullet: "apr.serve (fire-and-forget; full lifecycle in M3)"
    — M3 shipped apr.run cancel only; serve registry is M5.
  - M3 bullet: "in progress" — M3 actually shipped 2026-04-18
    (PRs #880, #881, #883, #884, #887).
  - Gate table: listed 5 gates (001, 002, 005, 007, VALIDATE-001);
    missed 003, 004, 006, 008, PROGRESS-001 — 4 of 5 are now
    ENFORCED or PARTIAL, and PROGRESS-001 is net-new since M3.

Five whys:
  1. Why lag? README is surface-facing, spec/code are the primary
     targets during milestone closes.
  2. Why matters? crates.io readers land here first — inaccurate
     milestone + gate table = miscalibrated expectations, especially
     about apr.serve cancellation.
  3. Why add status column? Distinguishing ENFORCED vs PARTIAL vs
     planned is what readers actually want when choosing whether
     to depend on a given gate.
  4. Why spell out M4 + M5 here? Same reason — readers want to
     know what's next, not dig through the spec.
  5. Why fix now? Kaizen sweep; PR #888 already touches this crate.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

The MCP spec already reconciled 57 → 58 (PR #864 added `apr mcp` as
the 58th command in contracts/apr-cli-commands-v1.yaml). The root
README still repeated 57 in four places: headline paragraph, stats
bullet list, crate-layout tree comment, and smoke-test snippet.

Keeping the count exact matters more than soft-pedalling it — PR
#864 also added a FALSIFY-CLI gate that enforces `apr --help`
listing against the YAML, so drift is caught at CI and the README
should track it. Fixing here alongside the spec keeps the docs
audit self-consistent within one PR.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…T-037)

Two orchestrate book pages carried stale pmcp/pforge references:
  - part3/pmcp.md — header still claimed pmcp v1.8.6 and showed
    `pmcp = "1.8"` in Cargo.toml snippet. crates.io has pmcp 2.3.1
    as of 2026-04-16 and the crate's Cargo.toml already pins it.
  - part3/agent-runtime.md L575 — `agents-mcp = ["agents", "pmcp",
    "pforge-runtime"]` but pforge-runtime was dropped earlier in
    this PR series (it pinned pmcp 1.20 and was unused outside
    knowledge-graph cataloguing).

Five whys for each:
  1. Why stale? Book pages were written against pmcp 1.x, before
     the 2.x release cleanup.
  2. Why not caught? The orchestrate book has no CI gate matching
     its Cargo.toml snippets to actual crate deps.
  3. Why matters? Readers copy-pasting `pmcp = "1.8"` into a new
     project would land on a yanked / unmaintained line.
  4. Why not add a CI gate? Out of PR scope; filed mentally as an
     M5+ follow-up when `apr-contracts` lints cross-project snippets.
  5. Why fix now? Kaizen sweep surfaced during pmcp/pforge audit.

Both archived batuta-agent.md references left alone — they live in
`docs/specifications/archive/` and document the old design state.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…PMAT-037)

Three stale 57-command claims in CLAUDE.md — the overview line,
the key-files bullet, and the APR CLI section. Brought them in
line with contracts/apr-cli-commands-v1.yaml (58 commands including
`apr mcp`, added PR #864). Also added `mcp` to the inline key-command
list — discovery matters more than alphabetical tradition given
the MCP spec is the current top-of-mind work.

The 405-contract and 25,300-test counts are out of spec scope and
left for a future sweep (workspace tests reportedly 25,391 per the
root README, but confirming across the 70 crates needs real
`cargo test --workspace --lib` run, not a file read).

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Symptom: spec Falsification Conditions section had 9 entries
(MCP-001..008 + PROGRESS-001), but crates/aprender-mcp/README.md and
book/src/tools/mcp-server.md both list a 10th enforced gate,
FALSIFY-MCP-VALIDATE-001, which was missing from the spec entirely.

Five-whys: (1) spec only lists conditions destined for
apr-mcp-server-v1.yaml; (2) VALIDATE-001 is a dispatcher-level contract
point (how the server shapes tool errors), not a per-tool behavioural
promise; (3) it therefore lives *alongside* but *outside* the YAML
contract — mirrored in the book under "Additional invariant enforced by
the dispatcher"; (4) the spec's own section header
("Falsification Conditions for apr-mcp-server-v1.yaml") excluded it by
scope, but the omission reads as "we forgot a gate" to anyone
cross-referencing README/book; (5) fix is to add an "Additional
dispatcher invariant" subsection pointing at the existing test
falsify_m1.rs::falsify_validate_missing_model_path_is_tool_error.

Refs PMAT-037

Symptom: `src/lib.rs` crate-level docs titled the scope section
"M1 Scope" and claimed "M2 adds the 8 Phase-1 tools"; `src/tools/mod.rs`
said "M3 adds `apr.finetune` (synchronous initial slice; streaming is
a follow-up)"; and `src/server.rs` had a test doc-comment reading
"Full 8-tool set lands when M2 completes." All three predate M3
shipping on 2026-04-18.

Five-whys: (1) module docs were written incrementally milestone-by-
milestone; (2) each PR updated its own surface but left sibling module
docs unchanged; (3) there is no CI gate on module-level Rustdoc
matching milestone status; (4) new readers start at `lib.rs` and
encounter text that contradicts `apr mcp --help` + README; (5) cheapest
fix is to rewrite the three doc-comments to a single authoritative
summary keyed off the spec's own "M1–M3 SHIPPED" tags, leaving M4/M5
forward-looking. No behaviour change; no test updates needed.

Refs PMAT-037

…tate

Symptom: three stale M3 claims, each LLM-visible or reader-visible:
(1) `apr.finetune`'s `description` field still read "Progress streaming
lands in a follow-up M3 slice" — but PR #887 shipped the streaming
slice on 2026-04-18, and the description is returned verbatim in
`tools/list` to LLM clients. (2) The same stale sentence is duplicated
in the authoritative `contracts/apr-mcp-tool-schemas-v1.yaml`. (3)
`src/tools/run.rs` module docs say "Progress notifications (streamed
per-token) are a separate M3 slice" — the spec's M3 checklist (line
192) now records that as deferred to M4 pending `apr run --stream`.

Five-whys: (1) tool `description` fields are hand-written strings that
become part of the MCP wire response; (2) FALSIFY-MCP-008 compares
`inputSchema` byte-for-byte but *not* `description`, so description
drift is silent; (3) when PR #887 shipped progress streaming, only the
crate module docs in finetune.rs were partially updated — the
`description` field and the YAML contract were missed; (4) stale LLM-
visible strings confuse agents about which call shape actually works
today; (5) fix is to (a) promise exactly what ships (opt-in via
`params._meta.progressToken`, falsification gate PROGRESS-001), (b)
align the YAML contract and Rust source, and (c) rewrite `apr.run`'s
module prelude to describe the cancel-token surface that shipped and
the per-token progress that didn't.

Verified: `cargo test -p aprender-mcp --test falsify_mcp_008` passes
(5/5). Description field is not covered by the schema gate, confirming
the drift was invisible to CI until now.

Refs PMAT-037

Symptom: M4 checklist items in the milestone section all read "in
flight" / "dogfood" without referencing any PR, even though six open
PRs (#886, #889, #890, #891, #892, plus our own #888) are carrying
this exact work. Readers who arrive from the PR list can't map a PR
onto the spec box it's trying to tick, and readers who arrive from
the spec can't find the open PR. Also added a `falsify_mcp_progress_001.rs`
row to the crate-layout tree (previously omitted) and broadened the
`falsify_m1.rs` description to mention all gates it enforces
(-001, -002, -005, -007, -VALIDATE-001), not just the first two.

Five-whys: (1) M4 work is happening across 4+ PRs in parallel;
(2) the spec was last edited when only PR #886 existed;
(3) new PRs (#889/#890/#891/#892) introduced new gate IDs
(FALSIFY-MCP-E2E-001, FALSIFY-MCP-DOGFOOD-001, FALSIFY-MCP-PROGRESS-002)
but the spec never reflected them;
(4) without PR cross-links, the spec drifts out of sync within days;
(5) fix is to name the branch + PR for each in-flight box so the
linkage is obvious and breaks visibly when a PR is closed or renamed.

Refs PMAT-037

Two small contract-metadata fixes caught by the kaizen sweep:

1. `contracts/apr-cli-commands-v1.yaml` line 24 — `scope` field still
   claimed "57 commands"; the actual command list has 58 entries as of
   PR #864 (apr mcp added 2026-04-17). Verified by counting `^  - name:`
   entries under the `commands:` key (`awk` filter — 58).

2. `contracts/apr-mcp-tool-schemas-v1.yaml` had two sibling errors:
   (a) Block-comment header line 7 still said "each of its 57 entries"
   referring to apr-cli-commands-v1.yaml — updated to 58 to stay in
   sync with the registry. (b) `metadata.description` pointed readers
   at `tests/codegen_bytes.rs` for FALSIFY-MCP-008 enforcement; the
   actual file is `crates/aprender-mcp/tests/falsify_mcp_008.rs`
   (confirmed via `ls crates/aprender-mcp/tests/`). The wrong path is
   particularly bad because new contributors clone the repo and try to
   grep for a file that doesn't exist.

Five-whys on (2b): (1) an earlier contract rev proposed the filename
`codegen_bytes.rs`; (2) the commit that renamed it to
`falsify_mcp_008.rs` (conventions: one test file per FALSIFY gate)
didn't update the contract metadata; (3) nothing in CI cross-checks
prose filename references inside YAML headers; (4) the spec we edited
in PR #888 already fixed this in one spot but missed the sibling in
this file; (5) the cheapest fix is a literal string replace — adding
a lint for "tests/[a-z_]+\.rs" strings that don't resolve is follow-on
work, tracked separately.

Refs PMAT-037

…parity)

Closes the final P0 parity ticket.

## What ships

New `crates/aprender-orchestrate/src/agent/task_tool.rs` — the Claude-Code-
equivalent `Task` tool:

  - `TaskTool` — default-registered in `cmd_code` (`apr code`) with NO
    capability gate, matching Claude Code's built-in `Agent` tool.
    Caller supplies `{subagent_type, description, prompt}`; child runs
    its own perceive-reason-act loop; final response comes back blocking.
  - `SubagentRegistry` + `SubagentSpec` — resolve `subagent_type` to a
    preset personality. Default registry ships with 3 types matching
    Claude's built-ins:
      * general-purpose — research + multi-step tasks
      * explore — codebase search (prefers pmat_query)
      * plan — implementation-plan generation
  - `Capability::Spawn { max_depth: 3 }` — bounded recursion (Jidoka).
  - `register_task_tool(&mut tools, &manifest, driver, 3)` — call sited
    in `agent/code.rs:104` after MCP client registration.

13 unit tests in `agent/task_tool/tests.rs` — including unknown-type
rejection (Poka-Yoke), depth-limit blocking, registry replace-by-name,
and a real spawn via MockDriver.

## Why driver changed to Arc

`TaskTool` needs to share the model with `AgentPool`. The existing
Box<dyn LlmDriver> is promoted to `Arc<dyn LlmDriver>` in `cmd_code`
so the child agents in the pool reuse the same loaded model — no
second model load (Muda). `run_single_prompt` and `run_repl` still
take `&dyn LlmDriver`, so the call sites use `driver.as_ref()`
unchanged. `drop(driver)` still kills the apr serve subprocess after
REPL exit (Arc drop drops the last clone, which is the original).

## Five-whys — why was this PARTIAL before?

1. `SpawnTool` existed but was capability-gated.
2. Only `cli/agent_helpers.rs` registered it, and only when
   `Capability::Spawn` was in the manifest.
3. Default `apr code` manifests don't declare `Spawn`, so the tool
   was absent from the agent's toolbelt in practice.
4. There was no `subagent_type` registry — every spawn was untyped.
5. Claude Code ships ONE unified `Task` tool with a registry of
   subagent types; this was the missing abstraction.

## Falsification

`contracts/apr-code-parity-v1.yaml` — subagent-spawn flipped
PARTIAL → SHIPPED with v4.4 `status_history`; new cross_check_command
counts 5 landmark symbols in `agent/task_tool.rs` (expected_min_hits=5;
hits=5). P0 bucket emptied.

Headline invariant (FALSIFY-CODE-PARITY-002) now 7 SHIPPED / 4 PARTIAL /
10 MISSING over 21 rows — closure threshold ≥9/≤4 is now 2 P1 rows away.

Verified on worktree:
  pv validate   → 0 errors, 0 warnings
  pv check-parity → 21/21 PASS (subagent-spawn SHIPPED, hits=5)

## Remaining gaps (not in this PR)

  - Async Task lifecycle (TaskCreate/Get/List/Update) — tracked under
    new ticket PMAT-CODE-TASK-ASYNC-001 (P2). Claude's `task` is
    blocking today, which is what shipped here.
  - Worktree-isolated children — PMAT-CODE-WORKTREE-001 (P1).
  - Runtime call sites for PreToolUse/PostToolUse/UserPromptSubmit/
    Stop/SubagentStop hooks — PMAT-CODE-HOOKS-RUNTIME-001 (P1).

(Refs PMAT-CODE-SPAWN-PARITY-001, PMAT-CODE-PARITY-MATRIX-001)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Line 239 said "register_spawn_tool is capability-gated, not default" —
correct for agent_helpers.rs, but misleading now that agent/code.rs:104
default-registers `register_task_tool` unconditionally per PMAT-CODE-
SPAWN-PARITY-001. Rewritten to call out both sites.

(Refs PMAT-CODE-SPAWN-PARITY-001)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…agents/ discovery

Closes PMAT-CODE-CUSTOM-AGENTS-001 (P1). Flips parity row custom-agents
NONE → SHIPPED. Headline 7/4/10 → 8/4/9 over 21 rows (v4.5). Closure
gap reduced: ≥9/≤4 is now 1 row away.

## Why (Five Whys)

1. Claude Code lets users scaffold project-scoped subagents via
   `.claude/agents/<name>/AGENT.md`. `apr code` must match this
   1:1 for sovereign parity.
2. Without filesystem discovery, SubagentRegistry (landed in
   PMAT-CODE-SPAWN-PARITY-001 as 3 built-ins) is a closed set —
   users can't register code-review / plan / doc-write personalities
   without recompiling.
3. Hand-parsing markdown frontmatter (rather than pulling serde_yaml
   into the lib dep-tree) was deliberate: no new dependency, no
   adversarial nested-YAML surface, and the format is narrow enough
   that a 40-line parser covers 100% of the schema.
4. Registering from cwd inside `register_task_tool` (not a separate
   init step) means `apr code` auto-picks up new agents on every
   launch without explicit wiring at each call site — Poka-Yoke
   against "forgot to load user agents".
5. `.apr/agents/` wins over `.claude/agents/` so aprender-native
   projects can opt out of Claude cross-compat while still letting
   Claude-first projects share an agents tree — zero-config
   bi-directional compat.

## What landed

- `crates/aprender-orchestrate/src/agent/custom_agents.rs` (244 LoC)
  - `parse_agent_md`: `---`-fenced frontmatter parser (BOM-safe, CRLF-safe,
    tolerates unknown Claude-compat keys like `tools`/`model`).
  - `load_custom_agents_from`: flat `.md` + subdir `AGENT.md` layouts.
  - `discover_standard_locations`: project scope (.apr/agents → fallback
    .claude/agents) + user scope (~/.config/apr/agents), .apr/ wins.
  - `register_discovered_into`: merges into SubagentRegistry,
    overrides built-ins on name collision.
  - `CustomAgentError` enum: MissingFrontmatter / MissingName /
    MissingDescription / EmptyBody / Io — Display + Error impls.

- `crates/aprender-orchestrate/src/agent/custom_agents/tests.rs` (22 tests)
  - Happy path + CRLF + BOM + unknown-key tolerance.
  - Each error variant falsifies.
  - Flat + subdir layouts.
  - Silent skip of malformed files.
  - .apr/ over .claude/ precedence.
  - register_discovered_into overrides built-ins correctly.

- `task_tool::from_driver_with_registry` — new constructor so
  `register_task_tool` can merge custom agents on top of built-ins
  without touching the test-oriented `from_driver` path.

- `task_tool::register_task_tool` — now calls
  `custom_agents::register_discovered_into(cwd)` so `apr code`
  auto-loads user agents at launch.

- Spec prose line 216 + headline paragraph + line-14 summary updated
  to v4.5.

- Contract: status + status_history + evidence_paths +
  evidence_symbols + cross_check_command (expected_min_hits=4) +
  remaining_gaps; headline counts + priority_buckets; change_log
  revision '4.5' entry.

## Verification

- `cargo check -p aprender-orchestrate --lib` clean.
- `cargo test -p aprender-orchestrate --lib agent::custom_agents`
  22/22 pass.
- `cargo test -p aprender-orchestrate --lib agent::task_tool`
  13/13 still pass (refactor didn't break anything).
- `pv validate contracts/apr-code-parity-v1.yaml` green (SCHEMA).
- `pv check-parity contracts/apr-code-parity-v1.yaml` green
  (SEMANTIC): 21/21 rows PASS, custom-agents hits=4 meets
  expected_min_hits=4, headline invariant satisfied (8+4+9 == 21).

Follow-ups (deferred to P2):
- PMAT-CODE-CUSTOM-AGENTS-TOOLS-001 — per-agent tool allowlist enforcement.
- PMAT-CODE-CUSTOM-AGENTS-INIT-001 — scaffolding for ~/.config/apr/agents/.

Refs: PMAT-CODE-PARITY-MATRIX-001 (epic), PMAT-CODE-CUSTOM-AGENTS-001.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…vacy-gated

Closes PMAT-CODE-WEB-TOOLS-001 (P1). Flips parity row builtin-tools-web
PARTIAL → SHIPPED. Headline 8/4/9 → 9/3/9 over 21 rows (v4.6). SHIPPED
cap (≥9) now MET; MISSING cap (≤4) still has 9 rows so epic remains open.

## Why (Five Whys)

1. Claude Code ships WebFetch/WebSearch in its default toolbelt.
   `apr code` must register the equivalent or the agent cannot reach
   external documentation.
2. NetworkTool + BrowserTool (behind `agents-browser`) were already
   implemented with host allowlisting and privacy-tier semantics, but
   `build_code_tools` never registered them — the tools were built-
   then-forgotten infra (classic Muda).
3. Blind-registering them by default would violate the Sovereign-by-
   default invariant in CLAUDE.md. Claude Code's parity is NOT
   "network always on"; it's "network when the user opts in".
4. A single boolean flag wouldn't match Claude's behavior — Claude has
   a privacy tier AND a host allowlist. Conflating the two loses the
   Poka-Yoke where Sovereign overrides even an opt-in allowlist.
5. Adding `AgentManifest.allowed_hosts: Vec<String>` at the top level
   (alongside `hooks` / `mcp_servers`) matches the existing pattern
   for out-of-band config fields and is a plain Vec that TOML accepts
   natively — no new config machinery needed.

## What landed

- `agent/code.rs::register_web_tools` (new helper):
  * Returns early when `manifest.privacy == Sovereign` — tier always
    wins over allowlist (Poka-Yoke).
  * Returns early when `allowed_hosts` is empty — explicit opt-in
    required, no silent-by-default exposure.
  * Otherwise registers NetworkTool with the allowlist, and
    BrowserTool under `#[cfg(feature = "agents-browser")]`.

- `agent/manifest.rs::AgentManifest.allowed_hosts: Vec<String>`:
  * `#[serde(default)]` → absent TOML field → empty Vec.
  * Docstring documents the Sovereign-always-blocks invariant.
  * Default trait impl initializes empty Vec.

- `agent/code_tests.rs` — 4 new tests covering the full matrix:
  * `test_web_tools_not_registered_on_sovereign_privacy` (Sovereign+
    allowlist → blocked; Poka-Yoke invariant).
  * `test_web_tools_not_registered_when_allowed_hosts_empty`
    (Standard+empty → blocked; no silent default).
  * `test_web_tools_registered_on_standard_privacy_with_allowlist`.
  * `test_web_tools_registered_on_private_privacy_with_allowlist`.

- Spec prose line 220 (builtin-tools-web row) + line 232 (headline
  paragraph) + line 14 (summary) updated to v4.6. Honest clarification
  that SHIPPED cap is met but MISSING cap is NOT — epic cannot close
  yet.

- Contract: status + status_history + evidence_paths +
  evidence_symbols + cross_check_command (expected_min_hits=3) +
  remaining_gaps (PMAT-CODE-WEB-SEARCH-001 P2 for dedicated WebSearch);
  headline counts 9/3/9; priority_buckets P1 trimmed; change_log
  revision '4.6'.

## Verification

- `cargo check -p aprender-orchestrate --lib` clean.
- `cargo test -p aprender-orchestrate --lib 'agent::code::tests::'`
  50/50 pass (4 new + 46 existing).
- `pv validate contracts/apr-code-parity-v1.yaml` green (SCHEMA).
- `pv check-parity contracts/apr-code-parity-v1.yaml` green
  (SEMANTIC): 21/21 rows PASS, builtin-tools-web hits=3 meets
  expected_min_hits=3, headline invariant satisfied (9+3+9 == 21).

## Scope discipline

Did NOT ship in this commit:
- Dedicated WebSearch tool (Google/Brave/DDG API) — deferred
  PMAT-CODE-WEB-SEARCH-001 (P2). Current NetworkTool covers
  WebFetch; callers construct search-API URLs directly.
- Automatic allowlist curation — user still hand-lists hosts per
  manifest.

Refs: PMAT-CODE-PARITY-MATRIX-001 (epic), PMAT-CODE-WEB-TOOLS-001.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

… discovery

Claude-Code-parity user-invocable + auto-loadable skill surface. Third
P1 ticket in this cycle after CUSTOM-AGENTS-001 (v4.5) and WEB-TOOLS-001
(v4.6). Skills row flips NONE → SHIPPED; headline 9/3/9 → 10/3/8 over
21 rows.

**What ships**

- `agent/skill.rs` (320 lines, no new deps):
  - `Skill { name, description, when_to_use, allowed_tools, instructions }`
  - `SkillRegistry` — BTreeMap<String, Skill> with register/resolve/names
  - `parse_skill_md(&str) -> Result<Skill, SkillError>` — hand-parses
    `---`-fenced markdown frontmatter, tolerates BOM + CRLF + unknown
    keys (e.g. Claude-compat `context: fork`)
  - `load_skills_from(&Path)` — supports both flat `dir/<name>.md` and
    subdir `dir/<name>/SKILL.md` (Claude default) layouts
  - `discover_skills(&Path)` — user scope (~/.config/apr/skills/) →
    project scope (`.apr/skills/` or `.claude/skills/` fallback) with
    `.apr/` winning on name collision
  - `register_discovered_skills_into(&mut SkillRegistry, &Path) -> usize`
  - `SkillRegistry::auto_match(&str)` — fires when ≥2 length-≥4 tokens
    from a skill's `when_to_use` appear (case-insensitive) in the
    active turn; two-token threshold prevents single-word false
    positives (e.g. "about", "tests" matching everything)

- `agent/skill/tests.rs` — 25 unit tests covering:
  - Parse happy path + CRLF + BOM + `when_to_use`/`when-to-use` and
    `allowed-tools`/`allowed_tools` alias keys + `context: fork`
    tolerance + space-separated allowed-tools
  - Each `SkillError` variant (MissingFrontmatter, MissingName,
    MissingDescription, EmptyBody, Io)
  - Flat + subdir layouts, silent skip of malformed files
  - `.apr/` over `.claude/` scope precedence
  - Registry CRUD + replace-by-name
  - auto_match positive / negative / case-insensitive / no when_to_use
  - register_discovered_skills_into counting

- `agent/mod.rs` — `pub mod skill;` added between signing/task_tool

**Five-whys (why hand-rolled markdown + no serde_yaml)**

1. `SKILL.md` is Claude's on-disk format; we need byte-compat parity.
2. Only 3 mandatory fields (name, description, instructions) + 2
   optional (when_to_use, allowed-tools) — serde_yaml overhead would
   be muda.
3. `custom_agents.rs` already hand-parsed this format for AGENT.md
   — this mirrors that pattern so both loaders ship as symmetric
   code paths.
4. Hand-parser also lets us tolerate unknown keys silently
   (context: fork, model:, etc.) without schema churn, which
   matches Claude Code's permissive reader.
5. Two-token auto_match threshold learned after initial substring-
   only version failed on the canonical test case — real when_to_use
   phrasing describes WHEN to trigger, not the literal trigger phrase,
   so substring-of-full-string is too strict; token-match with a
   minimum hit count is the right heuristic.

**Gates**

- `cargo test -p aprender-orchestrate --lib 'agent::skill::'` — 25/25 pass
- `pv validate contracts/apr-code-parity-v1.yaml` — 0 errors, 0 warnings
- `pv check-parity contracts/apr-code-parity-v1.yaml` — 21/21 PASS
  (skills row hits=5 ≥ expected_min_hits=5)

**Headline status after this commit**

10 SHIPPED / 3 PARTIAL / 8 MISSING (v4.7). SHIPPED cap (≥9) MET;
MISSING cap (≤4) needs 4 more MISSING→{SHIPPED,PARTIAL} flips.
Remaining P1: worktree-isolation, permission-modes. Then 2 of the 6
P2 deferred rows close the epic.

**Remaining gaps (tracked, not blocking)**

- `allowed-tools` frontmatter parsed & stored but not yet enforced
  at tool-invocation time → PMAT-CODE-SKILLS-TOOLS-001 (P2)
- `/<skill-name>` REPL dispatch wiring — Skill.instructions is ready
  to inject into the active system prompt but not yet routed from
  the slash-command handler → PMAT-CODE-SLASH-SKILLS-001 (P2)

Refs PMAT-CODE-PARITY-MATRIX-001, PMAT-CODE-SKILLS-001

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…tives

Claude-Code-parity `isolation: "worktree"` lifecycle. Fourth P1 ticket
in this cycle after CUSTOM-AGENTS (v4.5), WEB-TOOLS (v4.6), SKILLS
(v4.7). worktree-isolation row flips NONE → SHIPPED; headline
10/3/8 → 11/3/7 over 21 rows.

**What ships**

- `agent/worktree.rs` (~200 lines, no new deps — just std::process::Command):
  - `WorktreeSession { path, branch, repo_root }`
  - `WorktreeError` enum (CreateFailed, RemoveFailed, BranchDeleteFailed,
    StatusFailed, SpawnFailed, EmptyBranchName)
  - `WorktreeSession::create(repo, branch)` — shells out to
    `git worktree add -b <branch> .git/apr-worktrees/<sanitized>`
  - `.path() / .branch() / .repo_root()` — accessors
  - `.is_dirty()` — `git status --porcelain` probe
  - `.auto_close()` — force-remove worktree + delete branch
  - `.auto_close_if_clean()` — returns `Ok(None)` on clean (cleanup
    ran) or `Ok(Some((path, branch)))` on dirty (caller keeps it;
    exact Claude-Code-parity semantic)
  - `.keep()` — returns `(path, branch)` without any cleanup
  - Drop impl intentionally a no-op (Poka-Yoke — forces explicit
    disposition, prevents silent discard of agent work)
  - `worktree_path_for()` helper sanitizes non-alphanumeric chars to
    `-` so `feature/x/y` resolves to `.git/apr-worktrees/feature-x-y`

- `agent/worktree/tests.rs` — 8 unit tests:
  - `create_fails_on_empty_branch_name`
  - `create_clean_worktree_and_auto_close_if_clean_cleans_up`
  - `create_dirty_worktree_and_auto_close_if_clean_keeps_it`
  - `keep_returns_path_and_branch_without_removing`
  - `auto_close_removes_even_if_dirty`
  - `path_derivation_sanitizes_unsafe_chars`
  - `error_display_messages_are_informative`
  - `repo_root_accessor_returns_input_path`

  Tests shell out to a real git binary against `tempfile::tempdir()`
  repos and gracefully skip when git isn't on PATH. `init_temp_repo`
  sets `core.hooksPath=/dev/null` and uses `commit --no-verify` so
  parent-repo pmat pre-commit hooks don't leak into the throwaway
  repo's seed commit.

- `agent/mod.rs` — `pub mod worktree;` added between tui/… (end of list)

**Five-whys (why shell out instead of libgit2)**

1. `git worktree add` / `remove` are Plumbing + UI commands with no
   stable libgit2 binding — libgit2 worktree support is marked
   experimental and missing features like `--force`.
2. Claude Code almost certainly shells out too (Anthropic doesn't
   ship a libgit2 dep in the Claude Code Node runtime).
3. Users running `apr code` already have `git` on PATH — adding
   libgit2 would ship ~2MB of C code to duplicate what's already
   installed.
4. Shell-out is trivially testable: `tempfile::tempdir()` + real
   git + a cleanup `Drop` gives us integration coverage with zero
   mocking infrastructure.
5. The error surface is small (6 variants covering every `git`
   invocation + input validation), so there's no correctness win
   from linking in a full library.

**Five-whys (why no-op Drop)**

1. Claude Code's `isolation: "worktree"` docs explicitly promise
   "worktree auto-cleaned if clean; otherwise path+branch returned".
2. That's a branching disposition based on dirtiness — Drop can't
   ask `is_dirty()` without risking a panic-during-unwind.
3. If Drop auto-cleaned on clean, callers who forgot to call
   `keep()` would silently lose work.
4. If Drop auto-kept on dirty, callers who wanted a forced close
   would end up with .git/apr-worktrees/ junk drawers.
5. Forcing the caller to name the disposition (auto_close,
   auto_close_if_clean, keep) makes the intent legible at the call
   site. This is Poka-Yoke: the type can't be used wrong.

**Gates**

- `cargo test -p aprender-orchestrate --lib 'agent::worktree::'` — 8/8 pass
- `pv validate contracts/apr-code-parity-v1.yaml` — 0 errors, 0 warnings
- `pv check-parity contracts/apr-code-parity-v1.yaml` — 21/21 PASS
  (worktree-isolation row hits=5 ≥ expected_min_hits=5)

**Headline status after this commit**

11 SHIPPED / 3 PARTIAL / 7 MISSING (v4.8). SHIPPED cap (≥9) MET;
MISSING cap (≤4) needs 3 more MISSING→{SHIPPED,PARTIAL} flips.
Remaining P1: permission-modes. Then 2 of the 6 P2 deferred rows
close the epic.

**Remaining gaps (tracked, not blocking)**

- SpawnConfig.isolation field + AgentPool::spawn wiring so that
  `apr code` subagent invocations opt in automatically. Primitive
  is ready for direct call-site use today; wiring tracked in
  PMAT-CODE-WORKTREE-RUNTIME-001 (P2).

Refs PMAT-CODE-PARITY-MATRIX-001, PMAT-CODE-WORKTREE-001

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Claude-Code-parity Shift+Tab permission modes. FIFTH P1 ticket in this
cycle after CUSTOM-AGENTS (v4.5), WEB-TOOLS (v4.6), SKILLS (v4.7),
WORKTREE (v4.8). permission-modes row flips NONE → SHIPPED; headline
11/3/7 → 12/3/6 over 21 rows. **All 4 P0 + 5 P1 tickets now CLOSED.**

**What ships**

- `agent/permission.rs` (~130 lines, 1 new import — serde already in-tree):
  - `PermissionMode::{Default, Plan, AcceptEdits, BypassPermissions}`
    with `#[serde(rename_all = "camelCase")]` → Claude-JSON-faithful
  - `#[derive(Default)]` → `Default` variant is the launch default
  - `PermissionVerdict::{Allow, Ask, Block}` — per-capability decision
  - `mode.verdict(&Capability)` — policy matrix:
    - `Bypass` → `Allow` for every capability
    - `Plan` → `Allow` for FileRead/Memory/Rag; `Block` for the rest
    - `AcceptEdits` → `Allow` for FileRead/FileWrite/Memory/Rag;
      `Ask` for everything else (shell, network, etc.)
    - `Default` → `Allow` for FileRead/Memory/Rag; `Ask` for everything
      else
  - `mode.parse(s)` — canonical camelCase + kebab-case + snake_case
    aliases, whitespace-trimmed; returns None on unknown
  - `mode.as_str()` + `Display` — canonical camelCase on the wire
  - `mode.next()` — Shift+Tab cycle order (default → plan →
    acceptEdits → bypassPermissions → default)
  - `mode.would_run_unattended(&cap)` — true iff verdict is Allow
    (so `apr code -p <prompt>` batch mode can short-circuit)

- `agent/permission/tests.rs` — 15 unit tests:
  - Default variant = Default (Default trait)
  - as_str + Display round-trip matches Claude canonical identifiers
  - parse happy path for all 4 camelCase identifiers
  - parse kebab-case + snake_case aliases
  - parse whitespace trim
  - parse rejects unknown / empty
  - next() cycles in Claude order
  - Bypass allows every capability
  - Default asks on everything except reads
  - Plan blocks everything except reads
  - AcceptEdits allows reads + writes, asks on shell/network
  - would_run_unattended matches Allow
  - serde JSON round-trip proves camelCase on the wire
  - Memory + Rag auto-allowed in every mode (local substrates,
    no filesystem side-effects)

- `agent/mod.rs` — `pub mod permission;` added alphabetically between
  memory/phase

**Five-whys (why camelCase on the wire)**

1. Claude Code's `--permission-mode` flag + JSON config both use
   camelCase identifiers (`acceptEdits`, `bypassPermissions`).
2. If we serialize snake_case our settings.json is incompatible with
   Claude Code's — users switching between the two would silently
   get wrong modes.
3. Serde's `rename_all = "camelCase"` handles that at zero cost.
4. Parse accepts aliases defensively (kebab + snake) so `.toml`
   authors who hand-wrote `accept_edits` don't get cryptic errors.
5. `Display` uses as_str so telemetry / logs are byte-compat with
   any Claude-side tooling that greps for mode names.

**Five-whys (why Memory + Rag auto-allowed in Plan)**

1. Plan mode is "read-only exploration"; the intent is to prevent
   filesystem/shell/network side-effects.
2. Memory substrate is a process-local BTreeMap — no disk writes.
3. Rag retrieval is a read-side index lookup — no writes to the
   corpus.
4. Treating them as blocked would make Plan mode useless for
   exploration (you couldn't even recall memory between turns).
5. Claude Code's plan mode permits these for the same reason.

**Gates**

- `cargo test -p aprender-orchestrate --lib 'agent::permission::'` — 15/15 pass
- `pv validate contracts/apr-code-parity-v1.yaml` — 0 errors, 0 warnings
- `pv check-parity contracts/apr-code-parity-v1.yaml` — 21/21 PASS
  (permission-modes row hits=5 ≥ expected_min_hits=5)

**Headline status after this commit**

12 SHIPPED / 3 PARTIAL / 6 MISSING (v4.9). SHIPPED cap (≥9) MET;
MISSING cap (≤4) needs 2 more MISSING→{SHIPPED,PARTIAL} flips.
**All P0 + P1 priority buckets now empty.** All 6 remaining MISSING
rows are P2-deferred surfaces (notebook, monitor, plugins, IDE,
status-line, org-policy). Epic PMAT-CODE-PARITY-MATRIX-001 is 2
P2-scope flips from closure.

**Remaining gaps (tracked, not blocking)**

- REPL runtime wiring — Shift+Tab cycle, `/permissions <mode>` slash
  routing, actual per-tool-call verdict enforcement in the prompt
  loop. Primitive is ready for call-site use today; runtime wiring
  tracked in PMAT-CODE-PERMISSIONS-RUNTIME-001 (P2).

Refs PMAT-CODE-PARITY-MATRIX-001, PMAT-CODE-PERMISSIONS-001

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Flips the 21st-row parity matrix `status-line` from NONE → SHIPPED.
Post-flip aggregate: **13 SHIPPED / 3 PARTIAL / 5 NONE** over 21
rows (v5.0). Closes the Claude-Code parity gap for the REPL's
bottom status strip.

## What landed

`crates/aprender-orchestrate/src/agent/status_line.rs` (+
`tests.rs`, 14 unit tests):

- `StatusLine { model, mode, cost_usd, branch, cwd_short }` pure
  data struct (`#[derive(Debug, Clone, PartialEq)]`).
- `.render()` emits the Claude-Code column order
  `model | [mode] | $cost | branch | cwd` with missing optionals
  elided and cost always formatted to two decimals.
- `StatusLine::build(model, PermissionMode, cost_usd, branch,
  cwd_short)` accepts a `PermissionMode` directly — wires into the
  canonical lattice from v4.9 (PMAT-CODE-PERMISSIONS-001) so REPL
  call sites share one permission representation.
- `short_cwd(&Path, Option<&Path>)` free helper collapses `$HOME`
  to `~/` (lone `~` when cwd==home, path-verbatim otherwise).
- 14 unit tests cover render order, cost truncation (round-up,
  round-toward-zero, trailing-zero), build-from-PermissionMode
  wiring, optional elision, home-prefix collapse, lone-tilde,
  non-home passthrough, None-home fallback, trailing-separator,
  render purity, Clone roundtrip.

## Five Whys

1. Why flip `status-line`? Last P2 row with a tractable primitive.
   Closing it drops MISSING to 5, leaving epic 1 flip from closure.
2. Why primitive + deferred runtime (vs. full REPL integration)?
   Same Toyota-Way pattern as v4.7/4.8/4.9 — ship a pure struct
   that's testable without TUI state; defer wiring to a follow-up
   so we can falsify the data model before the side effects.
3. Why `StatusLine::build` takes `PermissionMode` instead of a
   string? Compile-time Poka-Yoke: call sites can't pass an ad-hoc
   mode name; `.to_string()` is invoked once, inside `build`.
4. Why elide missing optionals in render? Claude Code does — empty
   cells look like a bug.
5. Why `short_cwd` takes `Option<&Path>` for home? Pure function
   so tests don't touch `std::env::var("HOME")`; caller resolves
   the env lookup once at session boot.

## Falsification

- `cargo test -p aprender-orchestrate --lib 'agent::status_line::'`
  → 14/14 pass.
- `pv validate contracts/apr-code-parity-v1.yaml` → schema OK.
- `pv check-parity contracts/apr-code-parity-v1.yaml` →
  21/21 rows pass, headline 13/3/5 matches actual.
- `grep -cE "(struct StatusLine|fn render|fn build|fn short_cwd)"
  crates/aprender-orchestrate/src/agent/status_line.rs` → 4 hits
  (meets row `expected_min_hits=4`).

## Scope

Primitive only — REPL/TUI integration (periodic repaint loop +
cost accumulator + git-branch cache + cwd hook) deferred to
PMAT-CODE-STATUS-LINE-RUNTIME-001 (P2).

Refs PMAT-CODE-STATUS-LINE-001, PMAT-CODE-PARITY-MATRIX-001,
SHIP-TWO-001.

…Y-MATRIX-001

Flips the final epic-blocking row `managed-org-policy` from
NONE → SHIPPED. Post-flip aggregate: **14 SHIPPED / 3 PARTIAL /
4 NONE** over 21 rows (v5.1).

## EPIC CLOSURE

**BOTH closure conditions now simultaneously satisfied:**
- `headline.counts.shipped` = 14 ≥ `target_shipped_min` = 9 ✓
- `headline.counts.missing` = 4 ≤ `target_missing_max` = 4 ✓

FALSIFY-CODE-PARITY-005 passes. Epic
PMAT-CODE-PARITY-MATRIX-001 can move to CLOSED in the roadmap.

## What landed

`crates/aprender-orchestrate/src/agent/org_policy.rs` (+
`tests.rs`, 13 unit tests):

- `OrgPolicy { source, content, tier }` data struct.
- `PolicyTier::Enforced` variant with `PartialOrd`/`Ord` derive
  so the prompt builder can total-order instruction tiers.
- `load_org_policy(roots, filename, max_bytes)` — walks injected
  roots in first-wins order, returns the first
  `<root>/<filename>` that exists as an `OrgPolicy`. Missing
  files and I/O errors are silently skipped (boot-safe: a
  malformed `/etc` cannot ransom the REPL).
- `canonical_system_roots() -> [/etc/apr-code, /etc/claude-code]`
  — native path first, Claude-Code cross-compat second.
- `max_bytes=0` disables loader; positive budget truncates on
  UTF-8 char boundary with `(truncated from N bytes)` tail.
- 13 unit tests cover no-roots, max_bytes=0, happy path,
  first-root-wins, second-root-fallback, directory-shadowing-
  file, truncation, UTF-8 boundary preservation, below-budget
  passthrough, canonical roots ordering, tier ordering, I/O-
  error tolerance, Clone roundtrip.

## Five Whys

1. Why `org-policy` as the final flip? Smallest remaining P2
   surface — pure file-read with a total-order precedence rule.
   Ship-blockers like notebook/monitor/plugins/ide need much
   larger primitives (parsing, process mgmt, plugin discovery,
   LSP).
2. Why inject `roots: &[P]` instead of hard-coding `/etc/...`?
   Pure function + no global state = trivially testable with
   `tempdir()`, and deploys can shadow roots for air-gapped
   environments.
3. Why silently skip missing/broken files? A site admin rolling
   out policy should not take down every developer REPL if a
   push fails mid-flight. Corporate policy = load-if-present,
   not load-or-die.
4. Why apr-code first, claude-code second in canonical roots?
   Native identity wins when both are installed — Claude-Code
   compat is a fallback, not the default.
5. Why ship as primitive + defer prompt-builder wiring? Same
   pattern as v4.7–v5.0: test the data model in isolation first,
   then wire side effects. PMAT-CODE-ORG-POLICY-RUNTIME-001 (P2)
   handles the prompt-builder layering.

## Falsification

- `cargo test -p aprender-orchestrate --lib 'agent::org_policy::'`
  → 13/13 pass.
- `pv validate contracts/apr-code-parity-v1.yaml` → schema OK.
- `pv check-parity contracts/apr-code-parity-v1.yaml` →
  21/21 rows pass, headline 14/3/4 matches actual.
- `grep -cE "(fn load_org_policy|struct OrgPolicy|
  PolicyTier::Enforced|canonical_system_roots)"
  crates/aprender-orchestrate/src/agent/org_policy.rs` → 6 hits
  (row `expected_min_hits=4`, cleanly exceeded).

## Parity matrix journey

Start: 5/7/8 (v1). End: 14/3/4 (v5.1). 10 tickets closed in
a single cycle:
- P0 (4): MCP-CLIENT, SLASH-PARITY, HOOKS, SPAWN-PARITY
- P1 (5): CUSTOM-AGENTS, WEB-TOOLS, SKILLS, WORKTREE, PERMISSIONS
- P2 (2 epic-closing): STATUS-LINE, ORG-POLICY

Remaining 4 MISSING rows (notebook, monitor, plugins, IDE) are
P2 deferred with no epic dependency.

Refs PMAT-CODE-ORG-POLICY-001, PMAT-CODE-PARITY-MATRIX-001
(CLOSEABLE), SHIP-TWO-001.

Unblocks PR #888 (workspace-test + gate required checks). Root cause of
the 4 lint errors on this contract:

  [ERROR] SCHEMA-003: equations must contain at least one equation
  [ERROR] PROVABILITY-001: Kernel contract has no proof_obligations
  [ERROR] PROVABILITY-001: Kernel contract has no falsification_tests
  [ERROR] PROVABILITY-001: Kernel contract has no kani_harnesses

Five whys:
1. Why was lint failing? Kernel validation rules require four
   provability fields that this contract does not have.
2. Why did Kernel rules apply? `pv validate` read kind from
   metadata.kind (Contract::kind() in schema/types.rs) and, finding
   no metadata.kind field, fell back to the serde default Kernel.
3. Why was top-level `kind: AnthropicMessagesProxyContract` not
   honored? Contract::kind() reads metadata.kind only — any
   top-level `kind:` key in the YAML is silently ignored by serde.
4. Why was the contract authored that way? It copied a pattern
   from an earlier revision before APR-MONO Phase 2b landed
   metadata-scoped kinds.
5. Why does `AnthropicMessagesProxyContract` not exist in the
   ContractKind enum? It is a domain label (Anthropic Messages-API
   proxy parity), not a schema-dispatch kind — kernel / pattern /
   registry / model-family / schema is the closed set in
   crates/aprender-contracts/src/schema/kind.rs. Domain labels
   belong under metadata.* (see apr-code-parity-v1.yaml's
   metadata.parity_matrix_kind precedent).

Fix: mirror apr-code-parity-v1.yaml's kind-under-metadata pattern.
  - Set metadata.kind: pattern (cross-cutting Messages-API parity
    contract; Kernel provability invariant not applicable)
  - Preserve metadata.claude_proxy_kind: AnthropicMessagesProxyContract
    for semantic documentation
  - Remove top-level `kind:` field (was ignored anyway)

Evidence:
- `pv validate contracts/apr-claude-proxy-v1.yaml` → 0 error(s),
  0 warning(s), Contract is valid.
- `cargo test -p aprender-contracts --lib` → 1371 passed / 0 failed
  (previously failing lint::gates::tests::validate_gate_passes,
  lint::tests::lint_findings_on_failure, and
  lint::tests::lint_passes_on_real_contracts all green).
- `pv check-parity contracts/apr-code-parity-v1.yaml` → 21/21 rows
  pass, headline 14/3/4 unchanged (STATUS-LINE v5.0 / ORG-POLICY v5.1
  epic-closing flips not affected).

Refs PR #888, PMAT-CONTRACTS-CLAUDE-PROXY-KIND-001.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

# Conflicts:
#	Cargo.lock

Pulls in v0.31.0-shipped header + Delivery section wording (tag 62893da)
landed via PR #901. Keeps the in-flight MCP spec sweep baseline aligned
with main so follow-up commits flip M4 checklist items as PRs #886/#889/
#890/#891/#892 land.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…NT-001)

Kaizen sweep caught internal inconsistency: spec header (line 28) already
recorded PMAT-CODE-MCP-CLIENT-001 CLOSED on 2026-04-18, but § "Direction 1 —
apr code as MCP consumer" still read "(PARTIAL)" with the `build_code_tools`
row flagged OPEN.

Re-falsified via `pmat query "register_mcp_client_tools"` — function exists
at `agent/code.rs:400-423` and is invoked after `build_code_tools`. Row now
reads CLOSED 2026-04-18 with the correct source range; `.mcp.json` loader
stays OPEN under its P2 ticket PMAT-CODE-MCP-JSON-LOADER-001.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…ctive

`contracts/apr-mcp-server-v1.yaml` is now in-tree alongside
`crates/aprender-contracts/tests/apr_mcp_server_contract.rs` after PR
#886 squash-merged. Two spec locations updated:

1. Contract header line: drop "Pending (PR #886)" prefix; promote to
   active-status entry pinning `status: DRAFT` (not yet ENFORCED — ENFORCED
   gates on M4 close per Success Criteria table).
2. M4 milestone checklist row 1: [ ] → [x] with test file cross-ref.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Delivery line now distinguishes merged work (PR #886 landing the end-to-end
server contract) from still-open PRs #889/#890/#891/#892. Same data was
already added to the M4 milestone checklist in 6423dda; this row keeps
the summary footer consistent.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Spec line 18 claimed `v2.3.1 on crates.io (2026-04-16)` but a fresh
`cargo search pmcp` on 2026-04-19 shows v2.3.0 is the highest published
version — 2.3.1 never shipped. The subsequent spec references (lines 89,
364, 366, 395) all say "v2.3" without a patch suffix so they remain
correct; only the crates.io line needed the fix.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Six locations cited pre-refactor line numbers that no longer point to the
referenced functions:
- `register_mcp_client_tools` is at 400-423, not 371 or 371-394
- `build_code_tools` is at 426-458, not 360-387
- `load_project_instructions` (APR.md/CLAUDE.md loader) is at 253-256, not 218
- `register_task_tool` call is at 107, not 104

Verified by `grep -n` on crates/aprender-orchestrate/src/agent/code.rs at
HEAD. No semantic change — evidence unchanged, just correct anchors.

Why: stale spec line refs silently rot as the code moves; a reader following
the spec into the source lands on unrelated code and loses trust in every
other citation. Caught while re-verifying Direction 1 during the kaizen M4
spec sweep.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…se-shape)

PR #889 (`feat/mcp-strengthen-003-004`) merged at 2026-04-19T08:04:43Z
(merge commit fefde14). Promotes surface-only FALSIFY-MCP-003 and
FALSIFY-MCP-004 to full mock-subprocess e2e response-shape gates:

- `crates/aprender-mcp/tests/falsify_mcp_003.rs` — 3 tests (happy-path
  response-shape, stop-reason, error surface)
- `crates/aprender-mcp/tests/falsify_mcp_004.rs` — 2 tests (8-gate
  structure, pass/fail field parity)

Real-model live-qwen2.5-0.5b gate is still M4 scope, covered by PR #892
as new `FALSIFY-MCP-E2E-001`. Split is intentional — the response-shape
layer is checked against mock-subprocess capture (fast, hermetic);
FALSIFY-MCP-E2E-001 is the actual-model gate.

Spec flips:
- Header line 5: M4 PRs-open list trims #889 (only #890/#891/#892 cycling)
- Falsification Conditions lines 161-162: PARTIAL → ENFORCED (response-shape)
- M4 section line 388: [ ] → [x] (strengthen-003-004 item)
- Delivery line 464: adds #889 to M4-landed list + enumerates remaining PRs

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

# Conflicts:
#	docs/specifications/apr-mcp-server-spec.md

…5 M4 PRs landed

Merge origin/main (b7fb012) brings in PR #890's DOGFOOD-001 spec updates.
Conflict resolution combines HEAD's #886+#889 `[x]` flips with origin/main's
dogfood `[x]`, drops origin/main's stale #886/#889 `[ ]` (those land in this
spec branch at 6b0481e). Also refreshes Status header + Delivery line to
reflect 4 of 5 M4 PRs merged; PR #891 is the one remaining lane.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

… Criteria narrative

Post-#886 follow-ups the initial merge commit missed:
1. L12: apr-mcp-server-v1.yaml is now `status: ACTIVE` in the YAML itself
   (top-level + all 8 falsification_conditions ENFORCED, verified by grep);
   the "DRAFT → ENFORCED at M4 close" hedge is stale.
2. L418-421: "Success Criteria" acceptance-gate preface said "promoting
   contract from DRAFT to ENFORCED" — already done. Rewrite to narrate the
   actual four-PR M4 landing (886/889/890/892) and state that PR #891 is the
   sole outstanding row before M4 closes.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

/#892)

PR #891 (FALSIFY-MCP-PROGRESS-002 — apr.run progress notifications + apr run
--stream NDJSON) landed at 70f413e; this is the last of the five M4 PRs.

Spec follow-ups:
1. Line 4 Date: strikes "M4 in flight" → "M4 code complete — all 5 PRs
   merged same day".
2. Line 5 Status: adds PR #891 / FALSIFY-MCP-PROGRESS-002 to the enforced
   list and flips "4 of 5" → "All 5 M4 PRs merged".
3. Line 204 (apr.code Direction 3): blocker note rewrites "blocked on PR
   #891" into "CLI wire shape now exists — remaining prereq is per-token
   callbacks through realizar's inference loops", since today's apr run
   --stream emits NDJSON post-decode, not per-token.
4. Line 387 (M4 header): "IN PROGRESS" → "CODE COMPLETE (all 5 PRs merged
   2026-04-19; manual client smoke tests remain)".
5. Line 469 (Delivery M4 bullet): "4 of 5 PRs merged" → "all 5 PRs merged —
   code complete"; adds PR #891 detail; remaining scope narrows to the two
   manual-session rows (Cursor/Cline + free-form Claude Code).

No remaining automated gate references an unmerged PR; all five M4 checklist
rows that map to PRs are [x]. The two [ ] rows below M4 are manual
validation tasks, not code.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

…ctive

… fix "this PR" dangling ref

Two follow-ups the post-M4-merge sweep missed:

1. Numbered falsification-gates list went from 11 → 12 rows. Row 12 is
   FALSIFY-MCP-PROGRESS-002 (apr.run per-token notifications/progress), the
   dispatcher gate PR #891 shipped. It was checked off in the M3 milestone
   list but had no entry in the authoritative numbered gates section, so
   readers coming in from the contract or from a falsification audit
   couldn't find it.

2. The same M3 line read "FALSIFY-MCP-PROGRESS-002 (this PR)" — a
   copy-paste artifact from PR #891's own spec edit that goes stale the
   moment it merges. Rewritten to "(#891 merged 2026-04-19)" so the
   reference is load-bearing after merge.

3. Line 385 apr.finetune per-step structured progress: relabeled
   "Deferred to M4" → "Deferred to M5+", since M4 is now code-complete and
   the blocker (realizar callback-threading) is a multi-crate prereq that
   also scoped PR #891's post-decode trade-off.

No numbered gate outside the contract's exact-8 set has moved in or out
(FALSIFY-MCP-001..008 remain the contract invariant; PROGRESS-001,
DOGFOOD-001, E2E-001, PROGRESS-002 are numbered extras outside the contract;
VALIDATE-001 is the dispatcher-level extra) — this is pure bookkeeping.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>