@xcraftmind/mastermind 0.27.0 → 0.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xcraftmind/mastermind",
-  "version": "0.27.0",
+  "version": "0.28.0",
   "description": "Mastermind workflow CLI + mmcg codegraph for AI coding agents — verify-spec / audit-spec gates, MCP server, multi-language tree-sitter indexer (Python, TypeScript, JavaScript, Rust, C#, Go, Java, PHP, C/C++). Prebuilt native binaries via optional platform packages — no Rust toolchain required.",
   "license": "MIT",
   "author": "xcraftmind",
@@ -38,12 +38,12 @@
     "mastermind"
   ],
   "optionalDependencies": {
-    "@xcraftmind/mmcg-darwin-arm64": "0.27.0",
-    "@xcraftmind/mmcg-darwin-x64": "0.27.0",
-    "@xcraftmind/mmcg-linux-x64-gnu": "0.27.0",
-    "@xcraftmind/mmcg-linux-arm64-gnu": "0.27.0",
-    "@xcraftmind/mmcg-linux-x64-musl": "0.27.0",
-    "@xcraftmind/mmcg-linux-arm64-musl": "0.27.0",
-    "@xcraftmind/mmcg-win32-x64-msvc": "0.27.0"
+    "@xcraftmind/mmcg-darwin-arm64": "0.28.0",
+    "@xcraftmind/mmcg-darwin-x64": "0.28.0",
+    "@xcraftmind/mmcg-linux-x64-gnu": "0.28.0",
+    "@xcraftmind/mmcg-linux-arm64-gnu": "0.28.0",
+    "@xcraftmind/mmcg-linux-x64-musl": "0.28.0",
+    "@xcraftmind/mmcg-linux-arm64-musl": "0.28.0",
+    "@xcraftmind/mmcg-win32-x64-msvc": "0.28.0"
   }
 }

package/share/agents/mastermind-auditor.md

@@ -157,6 +157,42 @@ A markdown audit report:
 
 If verdict is anything other than `contract held`, the planner must address each `❌` / `⚠️` / critical-deferred item before telling the user "done".
 
+### Structured audit tail (REQUIRED)
+
+After the prose verdict, emit a fenced-YAML structured audit tail wrapped in
+`<!-- mastermind:audit-begin -->` / `<!-- mastermind:audit-end -->` sentinels.
+The planner reads this for mechanical routing — discrepancies must use the
+`kind:` vocabulary from the `defect-taxonomy.md` reference in the
+`mastermind-task-planning` skill (auditor-discrepancy section). The full schema
+lives in that same skill's references as `structured-report-schema.md`. The
+agent has both loaded — no path lookup needed.
+
+Minimal template:
+
+````markdown
+<!-- mastermind:audit-begin -->
+```yaml
+spec: <absolute path to spec.md>
+verdict: held | drift | broken
+files_in_scope: <N>
+files_in_diff: <M>
+scope_match: <bool>
+discrepancies: []
+snapshot_drift:
+  - symbol: <name>
+    pre_callers: <N>
+    post_callers: <M>
+    delta: none | gained | lost | signature_changed
+verifications_rerun:
+  - cmd: "<command>"
+    result: pass
+```
+<!-- mastermind:audit-end -->
+````
+
+Even on `verdict: held` the tail is REQUIRED — with `discrepancies: []` and
+`scope_match: true`. The planner relies on the sentinel block existing.
+
 ## Capture the lesson (institutional memory)
 
 When the verdict is `⚠️ partial drift` or `❌ contract broken`, append a **one-line lesson** to `.mastermind/tasks/_lessons.md` (shared file at the top of `tasks/`, not inside any task folder) so the next planner can learn from this audit. Skip on clean `✅ contract held` verdicts — that's just normal operation, not a lesson.

package/share/agents/mastermind-task-executor.md

@@ -83,6 +83,47 @@ A markdown execution report:
 <Anything you noticed but didn't fix because it was out of scope. Hand back to planner.>
 ```
 
+### Structured tail (REQUIRED)
+
+After the prose report, emit a fenced-YAML structured tail wrapped in
+`<!-- mastermind:report-begin -->` / `<!-- mastermind:report-end -->` sentinels.
+The planner extracts and parses this block mechanically — the prose above is for
+humans, the tail is for routing.
+
+The full schema with field meanings lives in the `mastermind-task-planning`
+skill's references as `structured-report-schema.md`. The closed set of
+`defect.kind` values lives in the same skill's references as
+`defect-taxonomy.md`. The agent has both loaded — no path lookup needed.
+
+Minimal template (populate every field, even on a clean run):
+
+````markdown
+<!-- mastermind:report-begin -->
+```yaml
+spec: <absolute path to spec.md>
+status: complete | partial | failed
+phases:
+  - id: "1.1"
+    status: done
+  - id: "1.2"
+    status: done
+files_modified:
+  - <relative path>
+defects: []
+verifications:
+  - cmd: "<command>"
+    result: pass
+```
+<!-- mastermind:report-end -->
+````
+
+When you stop on a defect:
+- Populate `defects[]` with one entry whose `kind:` is from the taxonomy (or
+  `unclassified` if nothing matches — be honest about it).
+- Set the corresponding phase's `status` to `stopped_here`.
+- Set the top-level `status:` to `partial` (some phases done) or `failed`
+  (Phase 1 didn't land).
+
 ## Companion skill
 
 This subagent is the runtime companion to [[mastermind-task-planning]] (the planner) and uses [[mastermind-task-executor]] (the skill body). The skill describes the process in detail; this subagent file defines the spawnable agent shape (tools, model, system prompt entry point).

package/share/skills/mastermind-task-executor/SKILL.md

@@ -120,6 +120,20 @@ Output a report in this exact shape:
 <Anything you noticed but didn't fix because it was out of scope. Hand back to the planner — they decide whether to add a follow-up task.>
 ```
 
+### Structured tail (REQUIRED)
+
+After the prose sections above, emit a fenced-YAML structured tail wrapped in
+`<!-- mastermind:report-begin -->` / `<!-- mastermind:report-end -->` sentinels.
+The planner reads this block to mechanically route on defect `kind:` — see
+[`structured-report-schema.md`](../mastermind-task-planning/references/structured-report-schema.md)
+for the full schema and
+[`defect-taxonomy.md`](../mastermind-task-planning/references/defect-taxonomy.md)
+for the closed `kind:` set.
+
+Even on a clean run (all phases done, every VERIFY passed) the tail is REQUIRED
+— with `status: complete` and `defects: []`. Planners rely on the sentinel block
+existing; absence is treated as a malformed reply.
+
 ## Failure modes — and how to handle them
 
 | Situation | What to do |

package/share/skills/mastermind-task-planning/SKILL.md

@@ -349,6 +349,99 @@ Each task lives in its own folder under `.mastermind/tasks/`:
 
 If `.mastermind/tasks/` doesn't exist, create it and optionally create `CONTEXT.md` with project info. `mmcg init` does this for you.
 
+## Defect-aware retry (mechanical routing on subagent reports)
+
+The executor and auditor subagents emit a fenced-YAML "structured tail" at the
+end of every report — full schema at
+[`references/structured-report-schema.md`](references/structured-report-schema.md),
+defect-kind vocabulary at
+[`references/defect-taxonomy.md`](references/defect-taxonomy.md).
+
+When you (planner) receive a subagent report that isn't `status: complete` /
+`verdict: held`, your routing flow is:
+
+1. Locate the sentinel block (`<!-- mastermind:report-begin -->` or
+   `<!-- mastermind:audit-begin -->`) at the end of the reply.
+2. Parse the YAML block. For each `defects[]` / `discrepancies[]` entry, read
+   `kind:`.
+3. Look up that `kind:` in the taxonomy doc. Apply the named fix template to
+   the spec (patch the offending phase, add a missing `expected_docs[]` entry,
+   add an authorization Rule, etc.).
+4. Re-spawn the executor with the patched spec, with a focused continuation
+   prompt that names which phases are already done and which need re-execution.
+
+When the structured tail's `kind:` is `unclassified`, you're in unknown
+territory:
+- Read the verbatim `details:` field
+- Design the fix manually
+- After the task lands, promote the new defect into a named entry in
+  `defect-taxonomy.md` (no separate spec needed for taxonomy edits — direct
+  doc commit is fine)
+
+The whole point of this routing is to **avoid re-reading prose reports**.
+Before this convention landed (tasks 001 + 002), the planner read 4 executor
+reports across two tasks and manually classified 6 defects. With the taxonomy +
+structured tail, the planner can route the same defects in a single YAML lookup.
+
+## Iteration budget (escalate, don't loop forever)
+
+If you've re-spawned the executor 3 times on the same spec and it keeps
+returning `status: partial` / `failed`, STOP. Don't issue a 4th respawn.
+Instead:
+- Surface the situation to the user with the cumulative defect list (all 3
+  rounds' `defects[]` entries flattened)
+- Suggest spec redesign rather than another patch
+- Append a one-line `[auto]` entry to `_lessons.md` of kind
+  `iteration_budget_exhausted` so future planners see this signal
+
+Three rounds is the empirically-calibrated bound from forge's
+`ErrorTracker.max_retries=3` default and from our task-002 experience (4 rounds
+to land, would have been 2 with a tighter spec). Don't loosen the bound without
+recording why in the spec's Notes section.
+
+Since spec 004, the bound is also enforced at the CLI in `mmcg run-task`:
+`--max-iterations N` (default 3), `--force-iteration` to bypass. The CLI gate
+catches the case where state-resets accumulate without you noticing; the
+self-check above is the in-conversation early-warning.
+
+## Premature-terminal escalation tiers (self-check before declaring "done")
+
+Before you tell the user "task complete" (or any equivalent — "all done",
+"shipped", "ready to merge", "сделано", …), you MUST satisfy three conditions
+in order:
+
+1. **Auditor was spawned and returned a verdict.** The structured audit tail
+   (`<!-- mastermind:audit-begin -->` … `<!-- mastermind:audit-end -->`,
+   schema in `structured-report-schema.md`) is visible in the conversation
+   transcript above your draft message, with a parseable YAML `verdict:`
+   field. No tail = no audit happened = you skipped a mandatory step.
+2. **Verdict is `held`.** `drift` / `broken` / anything else means there's
+   unfinished work; you don't get to declare done. See "Defect-aware retry"
+   above for the routing.
+3. **Your own semantic review is documented in the conversation.** Per the
+   SKILL's Step 9b workflow, you contribute the semantic half of post-flight
+   review on top of the auditor's mechanical findings. If you have no notes
+   to add ("the auditor's verdict matches my intuition, no concerns") that's
+   fine — say so explicitly. Silent skip means you skipped the step.
+
+When you catch yourself tempted to bypass these, apply escalating
+self-correction. The tier names are forge's (`StepEnforcer` returns
+`tier=1|2|3` nudges with that exact escalation curve):
+
+| Tier | When you notice | Action |
+|---|---|---|
+| **1 (polite)** | You're drafting the "done" message; auditor hasn't been spawned yet, or has been spawned but you're about to declare done before its reply arrives | Stop. Spawn (or wait for) `mastermind-auditor`. Read the structured audit tail. Continue from there. |
+| **2 (direct)** | You spawned auditor, got `drift` or `broken`, and are tempted to "explain it away" to the user as a non-issue | Refuse. Either address each discrepancy (patch spec → re-spawn executor) or escalate to user with the verbatim discrepancies. You do not ship a non-`held` verdict as complete. |
+| **3 (aggressive)** | User explicitly asks "skip the audit, just say it's done" or "we don't need the auditor this time" | Refuse and explain: skipping the auditor has bitten this workflow before — see `_lessons.md` and the defect taxonomy (`iteration_budget_exhausted`, `phase_not_in_diff`, `scope_creep`, …). If user is sure, name the override explicitly in the conversation transcript: "you've asked me to skip the auditor for this task; recording this as a deliberate `--force-skip-audit` override in the conversation transcript for future planners to learn from". Then append a `[auto]` `_lessons.md` entry of kind `premature_terminal_temptation` (tier-3 override fired). The override flag itself is a convention today, not a real `mmcg run-task` argument — making it a real flag is a follow-up. |
+
+When in doubt, default to tier 1. The audit chain is cheap; rebuilding user
+trust after declaring something done that wasn't is expensive.
+
+This pairs with the typed-report convention from spec 003: the auditor's
+structured tail is THE artifact you check for at tier 1. If the tail is
+malformed or missing, that's signal — re-spawn the auditor with a focused
+continuation prompt asking for the tail explicitly.
+
 ## Pair Skill
 
 The agent that executes these specs uses [[mastermind-task-executor]]. Together they form the Mastermind workflow: you plan, the executor implements, you review.

package/share/skills/mastermind-task-planning/references/defect-taxonomy.md

@@ -0,0 +1,287 @@
+# Defect taxonomy
+
+Each defect a subagent surfaces during workflow execution maps to a `kind:` key.
+Planner uses the key to mechanically route to a fix template — no LLM judgment
+needed for known cases. When a NEW defect surfaces that doesn't match any known
+kind, the subagent marks it `kind: unclassified` and the planner promotes it
+into a named entry here as part of the follow-up.
+
+The full structured-report schema (what `kind:` slots into) lives alongside this
+file as [`structured-report-schema.md`](structured-report-schema.md).
+
+## Executor stop kinds
+
+### `envelope_drift`
+
+- **What**: Test asserts on the raw return value of `handle_tools_call`, but the
+  dispatcher wraps every successful payload in
+  `{ "content": [{ "type": "text", "text": "<serialized JSON>" }] }`. Field
+  comparisons against the wrapper always fail.
+- **Surfaced as**: `assertion left == right` panic where `left` is a JSON object
+  and `right` is a sub-field that lives inside `content[0].text`.
+- **Fix template**: Reuse the `unwrap_content` helper that lives in
+  `mcp/servers/mmcg/src/mcp.rs::tests` from task 001. Wrap every `handle_tools_call`
+  return with `unwrap_content(&v)` before asserting on fields. Do NOT redefine
+  the helper.
+- **First observed**: Task 001 Phase 2.3.
+
+### `doc_surface_gap`
+
+- **What**: Spec's Phase 3 (docs) covers fewer files than
+  `scripts/validate.py::validate_mmcg_tool_drift` enforces. Validator finds tool
+  names in `mcp.rs` but missing from one or more of: mmcg README, repo README,
+  `.claude-plugin/marketplace.json`, `plugins/mmcg/.claude-plugin/plugin.json`.
+- **Surfaced as**: `python3 scripts/validate.py` exits non-zero with
+  `tool 'mmcg_X' missing — declared in mcp/servers/mmcg/src/mcp.rs but absent
+  from this file` (one error per missing surface).
+- **Fix template**: Add the three missing surfaces to `expected_docs[]` in the
+  spec frontmatter, then add three Phase 3.x sub-steps with FIND/CHANGE TO blocks.
+  Pattern: `marketplace.json` and `plugin.json` each carry ONE prose `description`
+  string with the comma-separated tool list and `N tools` count; the repo
+  `README.md` carries TWO occurrences (table cell + standalone-crate paragraph).
+  Insert the new tool name before the trailing `status` entry in each list and
+  bump the count by 1.
+- **First observed**: Task 001 Phase 4.
+
+### `zero_filter_verify`
+
+- **What**: VERIFY command uses `cargo test --lib <module>::` (trailing `::`)
+  which cargo treats as a literal path that no test matches. Command exits 0
+  with zero tests run — false-positive "pass".
+- **Surfaced as**: `cargo test ... <module>::` output reads `0 passed; 0 failed;
+  N filtered out` even though the module HAS tests.
+- **Fix template**: Drop the trailing `::`. Use the bare module name as the
+  substring filter: `cargo test --lib <module>`. Cargo matches any test whose
+  path contains the substring.
+- **First observed**: Task 001 Phase 1.3.
+
+### `verify_grep_false_positive`
+
+- **What**: A VERIFY command pipes test output into `grep -q "test result: ok"`
+  (or similar benign-line match) to gate pass/fail. But that line can co-exist
+  with a failure: a module with both unit tests AND doctests prints one
+  `test result: ok` per harness, so a `grep -q "ok"` can match the passing
+  doctest summary while a unit-test `FAILED` line sits elsewhere in the output.
+  The gate reports pass even though a test failed. Most dangerous in stress
+  loops (`for i in seq …; grep -q ok`) where one masked failure per iteration
+  is invisible.
+- **Surfaced as**: An auditor independently re-running the loop with an explicit
+  `grep "FAILED"` / non-zero-exit check finds failures the spec's own loop
+  missed; or a flaky test "passes" the loop but fails in CI.
+- **Fix template**: Gate on the ABSENCE of failure, not the presence of a
+  benign line. Prefer `cargo test … && echo ok || fails=$((fails+1))` (uses
+  cargo's own exit code — non-zero on any failure), or grep for the failure
+  marker: `cargo test … 2>&1 | grep -q "FAILED" && fails=$((fails+1))`. Never
+  gate a loop solely on a positive `grep -q "ok"`.
+- **First observed**: Task 006 Phase 3 (planner's stress loop used
+  `grep -q "test result: ok"`; auditor caught the maskability and re-verified
+  with an explicit FAILED-marker hunt — fix held, but the VERIFY pattern was
+  latently unsound).
+
+### `stale_pre_edit_snapshot`
+
+- **What**: Spec's Pre-edit symbol snapshot or a Phase's FIND block claims a
+  function has visibility / signature X, but the on-disk function already has
+  visibility / signature Y. The FIND text doesn't appear in the file.
+- **Surfaced as**: Executor returns `find_block_mismatch: <file> doesn't contain
+  the FIND text` for a phase that's nominally just a visibility change or
+  signature tweak.
+- **Fix template**: Either (a) drop the phase entirely if the change is already
+  in place (the more common case — re-check whether the goal is satisfied by
+  the current state), or (b) update the FIND/CHANGE TO blocks to match the
+  actual current state. Re-capture the snapshot via
+  `./mcp/servers/mmcg/target/debug/mmcg query symbols-in-file <path>` before
+  rewriting.
+- **First observed**: Task 002 Phase 1.5.
+
+### `seed_extractor_mismatch`
+
+- **What**: Integration test hand-crafts an intermediate type (e.g. `PendingFile`
+  with placeholder `kind: "fn"`, hand-written `signature: "fn foo()"`) to seed
+  storage. The consumer-under-test re-derives the same type from real input via
+  a parser (e.g. tree-sitter via `extractor_for_path` + `parse_one`), which
+  produces a structurally-equivalent but byte-different shape
+  (`kind: "function"`, fully-qualified signature). Hash/compare assertions fail
+  even on semantically-identical input.
+- **Surfaced as**: A round-trip test that should be a no-op returns a
+  "structural change" / "different" verdict; classifier or comparator is
+  correct, the seeding path is the bug.
+- **Fix template**: Seed via the same pipeline the consumer uses. For mmcg
+  fingerprint / structural tests, call `crate::indexer::extractor_for_path`
+  followed by `crate::indexer::parse_one` on a real on-disk fixture, then pass
+  the resulting `PendingFile` to `commit_file`. Never construct intermediate
+  parser-output types by hand.
+- **First observed**: Task 002 Phase 2.4.
+
+### `fmt_tension`
+
+- **What**: Spec's verbatim Rust code blocks are line-wrapped for documentation
+  readability (e.g. multi-line `Vec::with_capacity(…)` calls, broken-out
+  `std::fs::write(…)` arg lists). Rustfmt collapses these. `cargo fmt --check`
+  fails even though `cargo test` passes — the diffs are cosmetic only.
+- **Surfaced as**: `cargo fmt --check` exits non-zero with format-only diffs in
+  files the executor just wrote from spec FIND/CHANGE TO blocks; no semantic
+  divergence.
+- **Fix template**: Default to (b) — add an explicit Rule to the spec
+  authorizing one `cargo fmt` normalization pass on touched files, with a note
+  that fmt may only collapse/expand whitespace and must not change logic. Use
+  (a) — re-author the spec blocks in rustfmt style preemptively — only for
+  surgical edits to a single function. Future planners SHOULD include the fmt
+  authorization Rule from the start on any spec that emits >50 LOC of Rust.
+- **First observed**: Task 002 Phase 2.4.
+
+## Auditor discrepancy kinds
+
+### `scope_creep`
+
+- **What**: `git diff --name-only HEAD` shows files NOT in the spec's `touches[]`
+  + `expected_docs[]` union.
+- **Surfaced as**: Auditor's diff-vs-spec check enumerates files outside scope.
+- **Fix template**: Either revert the out-of-scope edits or extend the spec's
+  scope (with rationale) and re-spawn the audit. Zero tolerance unless the
+  planner explicitly excepted (e.g. authorized `cargo fmt` normalize affects
+  format-only).
+- **First observed**: (none — all 001/002 audits clean. Listed for completeness.)
+
+### `phase_not_in_diff`
+
+- **What**: Executor marked Phase X as `[x]` complete but the phase's CHANGE TO
+  content isn't present in the file.
+- **Surfaced as**: Auditor greps for canonical anchor strings from the CHANGE TO
+  block and finds nothing.
+- **Fix template**: Investigate whether the executor lied or a later phase
+  reverted the change. Re-run that phase's VERIFY command in isolation.
+
+### `verify_failed_on_rerun`
+
+- **What**: Auditor re-ran a VERIFY command that the executor reported as passing,
+  and it now fails.
+- **Surfaced as**: Discrepancy entry with the verbatim re-run output.
+- **Fix template**: Snapshot the environment diff (env vars, working directory,
+  locked dependencies). Almost always a flake or env-specific behavior; if not,
+  the executor's claim is suspect.
+
+### `snapshot_caller_drift`
+
+- **What**: Pre-edit snapshot in spec said symbol X had N callers; post-execution
+  `mmcg query callers X` returns M ≠ N.
+- **Surfaced as**: Auditor's drift check enumerates the delta.
+- **Fix template**: Either the executor changed something out of scope (check
+  the diff for new call sites involving X), or the snapshot was wrong to start
+  with. If the latter, drop the snapshot's per-symbol claim and re-run the audit.
+
+### `snapshot_signature_drift`
+
+- **What**: Symbol X's signature changed but the spec didn't authorize it (e.g.
+  spec said "public signature stays unchanged" but the diff shows a parameter
+  added).
+- **Surfaced as**: Auditor compares pre-edit `mmcg query search X` signature
+  against post-edit.
+- **Fix template**: Almost always a real contract violation. Stop, revert the
+  signature change, re-issue the phase preserving the original signature.
+
+### `validator_link_policy_gap`
+
+- **What**: Spec's CHANGE TO content adds a relative markdown link from an
+  installable artifact (e.g. `agents/subagents/foo.md`) to a target that
+  escapes its installable package (e.g. `../../skills/workflow/bar/refs/x.md`).
+  `scripts/validate.py` warns: `installable file escapes package — link goes
+  N levels up (max 0 for this file class). Reference the artifact by name
+  instead`. Subagents and CLAUDE.md templates are flat-installed to
+  `~/.claude/agents/` and can't follow `../`-style paths there.
+- **Surfaced as**: `python3 scripts/validate.py` exits 0 (errors clean) but
+  emits one warning per offending link. The spec's Phase 5 / Phase N VERIFY
+  treats `≥ 1 warning` as a failure depending on the spec's strictness rule.
+- **Fix template**: Replace each cross-package relative markdown link with a
+  bare-name reference using the convention from
+  `feedback_artifact_references.md` in user memory: subagent → `name`, skill →
+  `/name`, doc reference → "X.md in <skill>'s references" or similar prose.
+  The LLM agent has the referenced artifact loaded; no path lookup needed.
+  Same-package relative links (within one skill tree, e.g.
+  `../mastermind-task-planning/references/…` from `mastermind-task-executor/SKILL.md`)
+  stay inside the installable package and pass the validator — only links
+  CROSSING the `agents/`↔`skills/` boundary or going > 0 levels up from a
+  subagent fall foul.
+- **First observed**: Task 003 Phase 5.1 (executor stopped, planner promoted
+  the kind into the taxonomy in the same flight).
+
+### `verify_grep_window_too_small`
+
+- **What**: Spec's VERIFY command uses `grep -A N "anchor" file | grep -c "phrase"`
+  to confirm a phrase landed inside an "anchor + first few lines" window, but
+  `N` is sized for the spec author's mental layout (e.g. "header, blank, heading,
+  one bullet" = 4 lines) while the on-disk file has more pre-existing content
+  between the anchor and the new phrase (e.g. multiple prior bullets in the
+  same group). The phrase is correctly added to the file but lives outside the
+  `-A N` window.
+- **Surfaced as**: `grep -c` prints `0` even though the file contains the
+  phrase exactly as specified. `grep <phrase> <file>` confirms presence.
+- **Fix template**: Drop the windowed grep and use the bare
+  `grep -c "<unique phrase>" <file>` form. Pick a phrase that's unique to the
+  new content so the count remains 1 even on whole-file scan. Only keep `-A N`
+  when the anchor → phrase distance is short AND constant across spec authors
+  (e.g. immediately-following H2 with first paragraph).
+- **First observed**: Task 003 Phase 6.1 (planner sized `-A 4` for 2 bullets;
+  by execution time there were already 2 prior bullets pushing the new one to
+  line 6).
+
+### `verify_count_vs_change_to_mismatch`
+
+- **What**: Spec's VERIFY command expects N occurrences of a phrase
+  (e.g. `grep -c "foo" file ≥ 2`), justified by a comment like "one in the
+  heading, one in the body". But the spec's prescribed CHANGE TO body
+  actually contains the phrase fewer times — the body refers to it
+  pronoun-style (`this kind:`, `it`, `the same`) instead of respelling. After
+  verbatim application, grep returns < N and VERIFY fails on a self-consistency
+  bug.
+- **Surfaced as**: `grep -c` count is less than spec's claimed minimum;
+  CHANGE TO body was applied byte-for-byte; planner-side prose self-mismatch.
+- **Fix template**: Prefer (a) — edit the CHANGE TO body to spell the phrase
+  explicitly where the VERIFY count assumed it would appear (e.g. swap
+  `with this \`kind:\`` for `of kind \`foo\``). That's also more useful for
+  taxonomy / doc consumers grepping for the literal term. Alternative (b) —
+  relax the VERIFY count to match the actual prescribed body. Default to (a)
+  for taxonomy / reference docs where literal grep-ability is valuable.
+- **First observed**: Task 005 Phase 2.1 (planner wrote "this `kind:`" in
+  Fix template body but VERIFY expected 2 occurrences of the kind name).
+
+### `premature_terminal_temptation`
+
+- **What**: Planner is drafting a "task done" / "shipped" / "сделано"
+  message to the user without first ensuring (a) `mastermind-auditor` was
+  spawned, (b) verdict tail is in conversation with `verdict: held`, and
+  (c) planner's semantic review is documented. Often paired with the
+  rationalization "the executor's report looks clean, the audit will
+  surely pass".
+- **Surfaced as**:
+  - Planner catches themselves mid-draft (tier 1)
+  - Planner has Drift/Broken verdict and is tempted to "explain it away"
+    as a non-issue to user (tier 2)
+  - User explicitly asks the planner to skip the auditor and just declare
+    done (tier 3 — refusal + explicit override recording)
+- **Fix template**: Apply the SKILL's `Premature-terminal escalation tiers`
+  section. Tier 1 → just spawn the auditor and wait. Tier 2 → refuse, fix
+  the discrepancies, re-audit. Tier 3 → refuse, explain `_lessons.md`
+  precedent, name the override explicitly in the conversation transcript,
+  and append a `[auto]` `_lessons.md` entry of kind `premature_terminal_temptation`.
+- **First observed**: Workflow convention — pre-emptively named in task 005
+  ahead of real instances, so planners have a routing key on the day they
+  catch themselves. If you (future planner) ARE the first real instance,
+  update `First observed` here to your task number.
+
+### `unclassified`
+
+- **What**: A defect that doesn't match any kind above.
+- **Surfaced as**: Subagent emits `kind: unclassified` with a verbatim `details:`
+  description.
+- **Fix template**: Read the verbatim details, design the fix manually. After
+  the task lands, promote this defect into a named entry in this taxonomy via a
+  follow-up spec (or a direct doc PR — taxonomy edits don't need their own
+  spec). The `[auto]` `_lessons.md` entry from `mmcg audit-spec` is a good
+  starting point for the writeup.
+
+## Status (no defect)
+
+When NO defect applies → `kind: clean` and the workflow proceeds normally.
+Empty `defects: []` / `discrepancies: []` arrays in the structured tail also
+indicate the clean case.

package/share/skills/mastermind-task-planning/references/structured-report-schema.md

@@ -0,0 +1,141 @@
+# Structured report schema
+
+Every `mastermind-task-executor` and `mastermind-auditor` reply emits a
+fenced-YAML "structured tail" alongside its markdown prose. The tail is wrapped
+in HTML-comment sentinels so the planner can extract it deterministically with
+a single regex.
+
+The defect `kind:` vocabulary is the closed set defined in
+[`defect-taxonomy.md`](defect-taxonomy.md). Subagents MUST pick a listed kind
+or use `kind: unclassified` as the escape hatch.
+
+## Executor tail
+
+Emitted at the very end of the executor's reply, after the prose sections
+(Phases completed / Verification results / Files modified / Stopped because /
+What I did NOT do). Format:
+
+````markdown
+<!-- mastermind:report-begin -->
+```yaml
+spec: .mastermind/tasks/<NNN>-<name>/spec.md
+status: complete | partial | failed
+phases:
+  - id: "1.1"
+    status: done            # done | pending | stopped_here | skipped
+  - id: "1.2"
+    status: done
+  - id: "2.4"
+    status: stopped_here
+files_modified:
+  - mcp/servers/mmcg/src/store.rs
+  - mcp/servers/mmcg/src/fingerprint.rs
+defects:
+  - kind: envelope_drift
+    phase: "2.4"
+    details: |
+      Test asserted on the raw `handle_tools_call` return, but the dispatcher
+      wraps every payload in `{ "content": [{ "type": "text", "text": <json> }] }`.
+      `cosmetic["class"]` is therefore not the field the assertion expects.
+    remediation_hint: |
+      Reuse `unwrap_content` from `mcp.rs::tests` (task 001). Replace
+      `let cosmetic = read_env;` with `let cosmetic = unwrap_content(&read_env);`.
+verifications:
+  - cmd: "cd mcp/servers/mmcg && cargo test --locked --lib"
+    result: pass
+  - cmd: "cd mcp/servers/mmcg && cargo test --locked --lib change_class"
+    result: fail
+    output_excerpt: "thread '...' panicked at ..."
+```
+<!-- mastermind:report-end -->
+````
+
+### Field meanings
+
+- `spec`: absolute path to the spec file the executor is implementing.
+- `status`:
+  - `complete` — every phase landed, every Final-verification command exited 0
+  - `partial` — at least one phase done, executor stopped before reaching Phase N
+  - `failed` — Phase 1 couldn't even start (FIND mismatch on the first
+    sub-step, environment broken, etc.)
+- `phases[].status`:
+  - `done` — phase's CHANGE TO content is in the file AND its VERIFY exited 0
+  - `pending` — not yet attempted in this execution
+  - `stopped_here` — the executor halted at this phase; populate the matching
+    `defects[]` entry with details
+  - `skipped` — planner explicitly dropped this phase mid-flight (e.g. Phase
+    1.5 in task 002); list it for traceability
+- `files_modified`: every path the executor's edits touched, relative to repo
+  root. Must match `git diff --name-only HEAD` + untracked-new-files; this is
+  the auditor's scope-creep anchor.
+- `defects[]`: zero or more defects. Empty array = clean run. Each entry MUST
+  populate `kind` from the closed set in `defect-taxonomy.md` (or
+  `unclassified`), `phase` of the failure, verbatim `details`, and a
+  `remediation_hint` the planner can apply.
+- `verifications[]`: every VERIFY command run, in execution order. Truncate
+  `output_excerpt` to ~5 lines of the relevant error/diff.
+
+## Auditor tail
+
+Emitted at the very end of the auditor's reply. Format:
+
+````markdown
+<!-- mastermind:audit-begin -->
+```yaml
+spec: .mastermind/tasks/<NNN>-<name>/spec.md
+verdict: held | drift | broken
+files_in_scope: 7
+files_in_diff: 7
+scope_match: true
+discrepancies:
+  - kind: snapshot_caller_drift
+    symbol: SessionStore
+    spec_says: 45
+    index_says: 38
+    evidence: "git diff shows 7 callsites removed in src/api/*"
+snapshot_drift:
+  - symbol: commit_file
+    pre_callers: 2
+    post_callers: 2
+    pre_signature: "pub fn commit_file(&mut self, pending: PendingFile) -> SqlResult<()>"
+    post_signature: "pub fn commit_file(&mut self, pending: PendingFile) -> SqlResult<()>"
+    delta: none
+verifications_rerun:
+  - cmd: "cd mcp/servers/mmcg && cargo test --locked --lib"
+    result: pass
+```
+<!-- mastermind:audit-end -->
+````
+
+### Field meanings
+
+- `verdict`:
+  - `held` — every claim in the executor report survived independent
+    verification; zero discrepancies
+  - `drift` — partial drift; at least one discrepancy, none critical (warnings,
+    minor scope creep, snapshot deltas with explanation)
+  - `broken` — at least one critical discrepancy (scope creep without
+    explanation, verify failed on re-run, signature drift that contradicts the
+    spec's stated invariants)
+- `discrepancies[]`: every finding that contributed to a non-`held` verdict.
+  Each MUST use a `kind:` from the auditor section of `defect-taxonomy.md`.
+- `snapshot_drift[]`: one entry per symbol in the spec's Pre-edit symbol
+  snapshot, with pre/post caller counts and signatures and a `delta:` summary
+  (`none` | `gained` | `lost` | `signature_changed`).
+
+## Planner consumption
+
+The planner (running `mastermind-task-planning` SKILL) extracts the tail with a
+simple regex on the chat reply:
+
+```text
+<!-- mastermind:report-begin -->\n```yaml\n(?P<body>.*?)\n```\n<!-- mastermind:report-end -->
+```
+
+Then parses `body` as YAML. For each `defects[]` entry, the planner reads the
+`kind:`, looks up the matching entry in `defect-taxonomy.md`, applies the named
+fix template, and re-spawns the executor with the patched spec. This replaces
+the manual prose-reading the planner did in tasks 001 and 002.
+
+When `defects: []` and `status: complete`, the planner proceeds to spawn the
+auditor.