feat(dev-auto): detect intent-alignment gaps in planning and review (#2560)

- Ready standard: ACs must observe the outermost surface the intent
  references, never an internal proxy
- step-02: divergent defensible readings of the intent are an intent
  gap; never resolved by picking a reading
- step-03: retire the post-implementation AC/checkbox ritual; run the
  spec's Verification commands instead, and leave acceptance judgment
  to the independent review panel
- customize.toml: add Intent Alignment Auditor as a fourth default
  review layer, fed the verbatim invocation intent plus the diff,
  descriptive only; step-04 defines the {verbatim_intent} placeholder
- step-04: out-of-scope dispositions require the intent as authority;
  spec scope language, plan, and diff shape are inadmissible

Author: alexeyv

src/bmm-skills/4-implementation/bmad-dev-auto/SKILL.md

@@ -42,6 +42,7 @@ A specification is "Ready for Development" when:
 - **Actionable**: Every task has a file path and specific action.
 - **Logical**: Tasks ordered by dependency.
 - **Testable**: All ACs use Given/When/Then.
+- **Surface-anchored**: ACs observe the outermost surface the intent references — never a more internal proxy for it (e.g. the API response, not the database row behind it).
 - **Complete**: No placeholders or TBDs.
 - **Sufficient**: No known requirement, acceptance, dependency, or implementation gaps remain unresolved.
 - **Coherent**: No unresolved ambiguities or internal contradictions.

src/bmm-skills/4-implementation/bmad-dev-auto/customize.toml

@@ -70,3 +70,20 @@ Launch a subagent with no prior conversation context, with this prompt:
 >
 > {diff_output}
 """
+
+[[workflow.review_layers]]
+id = "intent-alignment"
+name = "Intent Alignment Auditor"
+instruction = """
+Launch a subagent with no prior conversation context, with this prompt:
+
+> You are an intent-alignment auditor. You have no other context about how this change was produced. Here is the verbatim intent this work started from:
+>
+> {verbatim_intent}
+>
+> Here is the diff:
+>
+> {diff_output}
+>
+> Your task is strictly descriptive — do not prescribe additional work. Report: (1) the defensible readings of the intent, enumerated; (2) which reading this diff implements; (3) where the readings and the diff diverge — specifically, which surface the intent's expectations live at versus which surface the diff's changes and its tests exercise.
+"""

src/bmm-skills/4-implementation/bmad-dev-auto/spec-template.md

@@ -60,7 +60,7 @@ warnings: [] # optional: machine-readable warnings for orchestration, e.g. overs
 <!-- AC covers system-level behaviors not captured by the I/O Matrix. Do not duplicate I/O scenarios here. -->
 
 **Execution:**
-- [ ] `FILE` -- ACTION -- RATIONALE
+- `FILE` -- ACTION -- RATIONALE
 
 **Acceptance Criteria:**
 - Given PRECONDITION, when ACTION, then EXPECTED_RESULT

src/bmm-skills/4-implementation/bmad-dev-auto/step-02-plan.md

@@ -15,7 +15,7 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 2. Investigate codebase. _Read the code yourself for narrow, localized tasks. Isolate deep exploration in subagents: instruct them to give you distilled summaries only, and plan from those summaries._
 3. Read `./spec-template.md` fully. Fill it out based on the intent and investigation. If `{preserved_intent_contract}` is non-empty, substitute it for the `<intent-contract>` block in your filled spec before writing. Write the result to `{spec_file}`.
 4. Self-review against READY FOR DEVELOPMENT standard.
-5. If intent gaps exist, do not fantasize and do not leave open questions. HALT with status `blocked`, blocking condition `intent gaps`, and include the unanswered questions and evidence gathered.
+5. If intent gaps exist, do not fantasize and do not leave open questions. Multiple defensible readings of the intent that lead to observably different outcomes, with nothing in the intent to select between them, are an intent gap — do not resolve one by picking a reading. HALT with status `blocked`, blocking condition `intent gaps`, and include the unanswered questions and evidence gathered.
 6. Warning check. If step-01 carried `multiple-goals`, add it to `{spec_file}` frontmatter `warnings`. If `{spec_file}` exceeds 1600 tokens, add `oversized` to frontmatter `warnings`. Continue either way.
 
 ### READY-FOR-DEVELOPMENT GATE

src/bmm-skills/4-implementation/bmad-dev-auto/step-03-implement.md

@@ -25,13 +25,13 @@ Change `{spec_file}` status to `in-progress` in the frontmatter before starting
 
 If `{spec_file}` has a non-empty `context:` list in its frontmatter, load those files before implementation begins. When handing to a subagent, include them in the subagent prompt so it has access to the referenced context.
 
-Hand `{spec_file}` to an implementation subagent. Invoke it **synchronously** and wait for it to return in this same turn — do not background/detach it (`run_in_background`) or end your turn to await a notification (see SKILL.md → Subagents). Resume at "Tasks & Acceptance Verification" only after it returns.
+Hand `{spec_file}` to an implementation subagent. Invoke it **synchronously** and wait for it to return in this same turn — do not background/detach it (`run_in_background`) or end your turn to await a notification (see SKILL.md → Subagents). Resume at "Verify" only after it returns.
 
 **Path formatting rule:** Any markdown links written into `{spec_file}` must use paths relative to `{spec_file}`'s directory so they are clickable in VS Code. Any file paths displayed in terminal/conversation output must use CWD-relative format with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/` in either case.
 
-### Tasks & Acceptance Verification
+### Verify
 
-After the implementation subagent returns, verify every task in the `## Tasks & Acceptance` section of `{spec_file}` is complete and every acceptance criterion is satisfied. Mark each finished task `[x]`. If any task is not done or any acceptance criterion is not satisfied, finish the missing work before proceeding. If the missing work cannot be completed, HALT with status `blocked`, blocking condition `implementation verification failed`, and include the unfinished task or failing acceptance criterion and reason.
+After the implementation subagent returns: if it reported unfinished work, finish it before proceeding. Run the commands in `{spec_file}`'s `## Verification` section (or perform its manual checks). If verification fails and the failure cannot be fixed, HALT with status `blocked`, blocking condition `implementation verification failed`, and include the failing command or check and reason. Acceptance criteria are judged at review, not here.
 
 ### Matrix Test Audit
 

src/bmm-skills/4-implementation/bmad-dev-auto/step-04-review.md

@@ -26,6 +26,8 @@ The review layers are `{workflow.review_layers}`, resolved during activation.
 
 Skip every layer whose `instruction` is empty or missing — that is how an override disables a default layer — and every layer whose `when` condition (if present) does not hold in the current context. If no layers remain, HALT with status `blocked` and blocking condition `no active review layers`.
 
+Runtime placeholders: `{diff_output}` is the diff constructed above. `{verbatim_intent}` is the invocation intent exactly as this run received it at step-01; if the run started from an existing spec file rather than a fresh intent, it is the spec's `<intent-contract>` block instead.
+
 Execute all remaining layers in parallel wherever their execution methods allow: substitute the runtime placeholders (e.g. `{diff_output}`) into each layer's `instruction`, then follow it verbatim.
 
 ### Classify
@@ -37,6 +39,7 @@ Execute all remaining layers in parallel wherever their execution methods allow:
    - `medium`: tolerable
    - `high`: intolerable
 3. Route each finding into exactly one triage category. The first three categories are **this story's problem** — caused or exposed by the current change. The last two are **not this story's problem**.
+   Scope authority: a finding may be routed to defer or reject *as out of scope* only on the authority of the intent itself. The spec's scope language, the plan, and the diff's own shape are not admissible scope authorities — if only they exclude a finding, treat it as evidence against the chosen reading (intent_gap or bad_spec), not as out of scope.
    - **intent_gap** — caused by the change; cannot be resolved from the spec because the captured intent is incomplete. Do not infer intent unless there is exactly one possible reading.
    - **bad_spec** — caused by the change, including direct deviations from spec. The spec should have been clear enough to prevent it. When in doubt between bad_spec and patch, prefer bad_spec — a spec-level fix is more likely to produce coherent code.
    - **patch** — caused by the change; trivially fixable without human input. Just part of the diff.