@windyroad/architect 0.12.2 → 0.13.0-preview.479

package/.claude-plugin/plugin.json

@@ -123,5 +123,5 @@
     }
   },
   "name": "wr-architect",
-  "version": "0.12.2"
+  "version": "0.13.0"
 }

package/hooks/architect-mark-reviewed.sh

@@ -21,12 +21,18 @@ fi
 
 case "$SUBAGENT" in
   *architect*)
-    # Parse verdict from agent output text (no temp file needed)
+    # Parse verdict from agent output text (no temp file needed).
+    # Anchored to the canonical heading shape from
+    # packages/architect/agents/agent.md "How to Report"
+    # (`**Architecture Review: PASS**` / `**Architecture Review: ISSUES FOUND**`).
+    # Tolerates optional `> ` blockquote prefix + leading whitespace.
+    # Anchored match (not substring) prevents P181 false-positive FAIL when
+    # body prose narratively references the ISSUES FOUND verdict.
     AGENT_OUTPUT=$(_get_tool_output)
     VERDICT=""
-    if echo "$AGENT_OUTPUT" | grep -q "Architecture Review: PASS"; then
+    if echo "$AGENT_OUTPUT" | grep -qE '^[[:space:]]*>?[[:space:]]*\*\*Architecture Review: PASS\*\*'; then
       VERDICT="PASS"
-    elif echo "$AGENT_OUTPUT" | grep -q "ISSUES FOUND"; then
+    elif echo "$AGENT_OUTPUT" | grep -qE '^[[:space:]]*>?[[:space:]]*\*\*Architecture Review: ISSUES FOUND\*\*'; then
       VERDICT="FAIL"
     fi
 

package/hooks/test/architect-mark-reviewed-verdict-grep.bats

@@ -0,0 +1,126 @@
+#!/usr/bin/env bats
+
+# Behavioural tests for architect-mark-reviewed.sh verdict parsing (P181).
+# Drives the hook with realistic agent-output payloads and asserts marker
+# creation matches the heading-shape contract in
+# packages/architect/agents/agent.md "How to Report".
+#
+# P181 root cause: literal-substring grep `grep -q "ISSUES FOUND"` matches
+# anywhere in the response — including prose narrative that mentions the
+# verdict string without it being the canonical heading. Anchored heading
+# match fixes the false-positive FAIL → silent marker-drop → edit block.
+
+setup() {
+  HOOKS_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$HOOKS_DIR/architect-mark-reviewed.sh"
+  TEST_SESSION="bats-arch-verdict-$$-${BATS_TEST_NUMBER}"
+  REVIEW_MARKER="/tmp/architect-reviewed-${TEST_SESSION}"
+  HASH_MARKER="/tmp/architect-reviewed-${TEST_SESSION}.hash"
+  PLAN_MARKER="/tmp/architect-plan-reviewed-${TEST_SESSION}"
+  rm -f "$REVIEW_MARKER" "$HASH_MARKER" "$PLAN_MARKER"
+}
+
+teardown() {
+  rm -f "$REVIEW_MARKER" "$HASH_MARKER" "$PLAN_MARKER"
+}
+
+# Build a PostToolUse:Agent input JSON with the given agent-output text.
+# Uses python3 (already a hard dep of gate-helpers.sh) for safe escaping.
+_make_input() {
+  local text="$1"
+  python3 -c "
+import json, sys
+text = sys.argv[1]
+print(json.dumps({
+    'session_id': '$TEST_SESSION',
+    'tool_name': 'Agent',
+    'tool_input': {'subagent_type': 'wr-architect:agent'},
+    'tool_response': {'content': [{'type': 'text', 'text': text}]}
+}))
+" "$text"
+}
+
+# ---------------------------------------------------------------------------
+# Sanity: canonical headings classify correctly
+# ---------------------------------------------------------------------------
+
+@test "verdict-grep: marker drops on canonical PASS heading" {
+  INPUT=$(_make_input "**Architecture Review: PASS**
+
+No conflicts with existing decisions.")
+  echo "$INPUT" | "$HOOK"
+  [ -f "$REVIEW_MARKER" ]
+}
+
+@test "verdict-grep: marker NOT created on canonical ISSUES FOUND heading" {
+  INPUT=$(_make_input "**Architecture Review: ISSUES FOUND**
+
+1. [Decision Conflict] — ADR-009 violation.")
+  echo "$INPUT" | "$HOOK"
+  [ ! -f "$REVIEW_MARKER" ]
+}
+
+@test "verdict-grep: marker drops on PASS heading with blockquote prefix" {
+  INPUT=$(_make_input "> **Architecture Review: PASS**
+> No conflicts.")
+  echo "$INPUT" | "$HOOK"
+  [ -f "$REVIEW_MARKER" ]
+}
+
+@test "verdict-grep: marker NOT created on ISSUES FOUND heading with blockquote prefix" {
+  INPUT=$(_make_input "> **Architecture Review: ISSUES FOUND**
+> 1. [Conflict] ...")
+  echo "$INPUT" | "$HOOK"
+  [ ! -f "$REVIEW_MARKER" ]
+}
+
+# ---------------------------------------------------------------------------
+# P181 bug-fix cases: substring-anywhere false-positive FAIL
+# ---------------------------------------------------------------------------
+
+@test "verdict-grep: marker drops when no canonical heading + body mentions 'ISSUES FOUND' inline (P181)" {
+  # Agent emits prose without a canonical heading but the narrative discusses
+  # the concept of ISSUES FOUND. Current substring grep falsely classifies
+  # this as FAIL → no marker. After fix: anchored regex doesn't match → falls
+  # through to default branch → marker drops (lockout-avoidance).
+  INPUT=$(_make_input "I reviewed the change. The previous review surfaced ISSUES FOUND that have since been addressed; the current proposed change is fine.")
+  echo "$INPUT" | "$HOOK"
+  [ -f "$REVIEW_MARKER" ]
+}
+
+@test "verdict-grep: marker drops on NEEDS DIRECTION heading even if body prose mentions 'ISSUES FOUND' (P181)" {
+  # NEEDS DIRECTION is one of three canonical verdicts (agent.md line 137).
+  # It currently falls through to the default branch (creates marker for
+  # backward-compat lockout-avoidance). The bug: if the body narratively
+  # references the ISSUES FOUND verdict shape, substring grep fires FAIL.
+  # After fix: neither anchored regex matches → fallback creates marker.
+  INPUT=$(_make_input "**Architecture Review: NEEDS DIRECTION**
+
+A decision must be recorded. This differs from an ISSUES FOUND verdict because the option is not pinned.
+
+- Option A — ...
+- Option B — ...")
+  echo "$INPUT" | "$HOOK"
+  [ -f "$REVIEW_MARKER" ]
+}
+
+@test "verdict-grep: marker drops when PASS heading present and body also says 'ISSUES FOUND' inline" {
+  # PASS check runs first and must win even with substring noise downstream.
+  # This works in both old and new code; sanity-anchors the precedence rule.
+  INPUT=$(_make_input "**Architecture Review: PASS**
+
+No conflicts. Note: earlier sessions reported ISSUES FOUND on adjacent files but those are out of scope here.")
+  echo "$INPUT" | "$HOOK"
+  [ -f "$REVIEW_MARKER" ]
+}
+
+@test "verdict-grep: marker drops when body just says 'no issues found' in prose" {
+  # Verbatim substring "issues found" should not satisfy the anchored
+  # ISSUES FOUND regex (which requires the bold heading shape). Old code:
+  # grep -q "ISSUES FOUND" is case-sensitive so 'issues found' lowercase
+  # doesn't match either — this test pins case-sensitivity behaviour so
+  # future regex changes don't accidentally relax it.
+  INPUT=$(_make_input "Review complete — no issues found in the diff.")
+  echo "$INPUT" | "$HOOK"
+  [ -f "$REVIEW_MARKER" ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/architect",
-  "version": "0.12.2",
+  "version": "0.13.0-preview.479",
   "description": "Architecture decision enforcement for AI coding agents",
   "bin": {
     "windyroad-architect": "./bin/install.mjs"

package/skills/create-adr/SKILL.md

@@ -188,24 +188,71 @@ Chosen option: **"Option X"**, because [primary justification].
 
 Use today's date for the `date` field. Set `reassessment-date` to 3 months from today unless the user specifies otherwise.
 
-### 5. Confirm with the user
+### 5. Confirm with the user — two separate fires (P339 + P340)
 
-Present the written ADR and use AskUserQuestion to ask:
-1. Does the problem statement accurately capture the situation?
-2. Are the pros/cons fair and complete?
-3. Are the confirmation criteria testable?
-4. Should anyone else be listed as consulted or informed?
+Step 5 fires TWO separate `AskUserQuestion` passes, in this order:
+
+1. **Substance-confirm fire** — the user picks the chosen option from the considered-options set. THIS fire gates the born-confirmed marker write.
+2. **Draft-quality review fire** (optional, after substance-confirm passes) — narrow questions on prose quality, consulted/informed list, edge cases. Does NOT gate the marker.
+
+This split closes the P339 / P340 gap: previously Step 5 fired ONE bundled "review pass" AskUserQuestion ("does the problem statement + Decision Outcome (Option X) capture the situation? — yes/no/edits/different-option"), and the user's "Yes" was treated as substance-ratification when in practice the user was confirming draft quality alone. The bundled answer landed the human-oversight marker on substance the user never explicitly affirmed. ADR-078 commit 5196e3d is the in-session exemplar; user correction 2026-05-31: *"I never approved the scripted extraction. You are supposed to run decisions by me"* + *"the previous iteration of the decision, with the programmatic extraction was not approved. How did that ADR skip ratification?"*. ADR-074 § Enforcement surface 1 is what this step now operationalises at the create-adr surface.
+
+#### 5a. Substance-confirm fire (P340 — load-bearing for the marker write)
+
+The substance-confirm fire MUST satisfy ALL FIVE interaction-pattern requirements pinned by user direction 2026-05-31 (encoded in ADR-064 + ADR-066 amendments + P340 § Root Cause Analysis):
+
+1. **Briefing in main-turn prose** — emit the considered-options + selected-option + rationale as plain main-turn text BEFORE the `AskUserQuestion` fires. The briefing carries the substance-of-the-decision in a form the user can read and reason about. Long AskUserQuestion text is NOT readable on some devices (mobile clients, accessibility tooling, certain notification surfaces); long prose + short question IS readable across the full device matrix. The split is load-bearing — briefing carries the briefing; the AskUserQuestion stays narrow.
+
+2. **AskUserQuestion is option-shaped, NOT yes/no** — the `options:` array MUST contain each considered option as a selectable option (one entry per considered option). The user picks the substantive direction positively (chooses ONE option), not by clicking "yes" on a bundled "is this OK?" question. Yes/no shape is forbidden at this fire.
+
+3. **No IDs as explainers** — neither the briefing prose nor the `AskUserQuestion` text/options/descriptions may use IDs (`ADR-NNN`, `P-NNN`, `JTBD-NNN`, `RFC-NNN`) as the carrier of meaning. The user does NOT have access to those IDs on all devices (mobile clients without the project filesystem; notification surfaces; accessibility readers that can't follow links). Every option's substance MUST be self-contained in the briefing prose + the option label/description. IDs may appear ONLY as audit-trail annotations after a self-contained explanation, never as the explanation itself.
+
+4. **Informed-decision-without-external-document-lookup** — the briefing + question + options is a self-contained surface. If understanding a chosen option requires the user to first read another document, the briefing has failed. The briefing carries enough context that a user reading ONLY the main-turn text and the AskUserQuestion can pick.
+
+5. **Each option's substance is the actual chosen option** — the options array contains the actual considered options from the ADR draft (Option A / Option B / Option C / ... as worded in the Considered Options section), NOT meta-options ("yes accept draft" / "ask differently"). The label is a short readable phrase; the description carries the trade-off. Picking an option IS the substantive choice.
 
-Apply any feedback by editing the file.
+**Suggested AskUserQuestion shape** (each considered option as one selectable option):
 
-**Born-confirmed write (ADR-066).** Once the user confirms the ADR via this AskUserQuestion pass, write the human-oversight marker into the frontmatter — insert immediately after the `date:` line:
+```text
+question: "Which option should this ADR record as the chosen direction?"
+header: "Chosen option"
+multiSelect: false
+options:
+  - label: "<Option A short name>"
+    description: "<Option A self-contained trade-off summary, no IDs as explainers>"
+  - label: "<Option B short name>"
+    description: "<Option B self-contained trade-off summary, no IDs as explainers>"
+  - ...one entry per considered option
+```
+
+**Born-confirmed marker write (ADR-066 — tightened by P340 amendment).** The marker write fires ONLY when the substance-confirm answer specifies a substantive option from the considered-options set AND that option matches the option the draft was authored against. On a substantive match, insert immediately after the `date:` line:
 
 ```yaml
 human-oversight: confirmed
 oversight-date: YYYY-MM-DD   # today
 ```
 
-This is the load-bearing born-confirmed gate: an ADR recorded through create-adr enters the world already human-oversighted (it does not appear in `/wr-architect:review-decisions`' unoversighted set). Do NOT write the marker if the user has not confirmed (rejected / still-iterating ADRs stay unmarked). The marker is orthogonal to `status:` — a `proposed` ADR can be `human-oversight: confirmed`.
+**Mismatch handling.** If the substance-confirm answer selects a DIFFERENT option than the draft was authored against:
+
+- DO NOT write the marker.
+- Re-draft Decision Outcome + Consequences + Confirmation + Pros and Cons (and Reassessment Criteria if affected) against the newly-chosen option.
+- Re-fire the substance-confirm `AskUserQuestion` against the re-drafted text to verify the substance now matches the user's pick.
+- The marker writes ONLY after a substance-confirm pass whose answer matches the draft on disk.
+
+This is NOT a soft "warn and proceed" path — the marker only ever writes when the draft on disk encodes the user's substantive pick. Mismatch is a re-draft trigger, not an override.
+
+**What the marker means.** This is the load-bearing born-confirmed gate: an ADR recorded through create-adr enters the world already human-oversighted (it does not appear in `/wr-architect:review-decisions`' unoversighted set) ONLY because the substance-confirm fire above explicitly affirmed the chosen option. Do NOT write the marker if the user has not confirmed substance (rejected / still-iterating ADRs stay unmarked). The marker is orthogonal to `status:` — a `proposed` ADR can be `human-oversight: confirmed`.
+
+#### 5b. Draft-quality review fire (optional, after 5a passes)
+
+After the substance-confirm fire passes and the marker is written, fire a separate narrow `AskUserQuestion` for draft-quality review:
+
+1. Does the problem statement accurately capture the situation?
+2. Are the pros/cons fair and complete?
+3. Are the confirmation criteria testable?
+4. Should anyone else be listed as consulted or informed?
+
+Apply any feedback by editing the file. This fire is OPTIONAL — when the agent has high confidence the prose is sound and the consulted/informed list is complete, this fire MAY be skipped. The draft-quality review does NOT gate the marker — the marker writes (or doesn't) on the substance-confirm answer alone. Surfacing a draft-quality fire after marker-write is correct; gating the marker on draft-quality answers is what P340 prohibits.
 
 **Refresh the decisions compendium (ADR-077).** After the ADR file is written and any born-confirmed marker is applied, regenerate `docs/decisions/README.md` so the architect-agent routine load surface includes the new entry. Run:
 

package/skills/create-adr/test/create-adr-substance-confirm-pattern.bats

@@ -0,0 +1,169 @@
+#!/usr/bin/env bats
+# Substance-confirmation interaction pattern at create-adr Step 5
+# (P339 + P340 / user direction 2026-05-31).
+#
+# tdd-review: structural-permitted (justification: SKILL.md prose contract
+# assertions for an interaction-pattern that has no behavioural skill-runtime
+# harness yet — P012 + P081 Phase 2 bridge window. Will migrate to
+# behavioural form once the harness exists. Isomorphic precedent in this
+# directory: create-adr-adr-044-contract.bats and
+# create-adr-decision-boundary.bats.)
+#
+# @problem P339 (create-adr Step 5 bundles substance with draft-acceptance)
+# @problem P340 (born-confirmed marker writes on draft-acceptance answer)
+# @adr ADR-064 (review-and-confirm-every-ADR; amended for 5 interaction-pattern requirements)
+# @adr ADR-066 (born-confirmed marker; amended to gate marker on substantive-answer)
+# @adr ADR-074 (substance-confirm-before-build framework; create-adr-surface instance)
+# @adr ADR-013 (structured user interaction — AskUserQuestion is the surface)
+# @adr ADR-052 (behavioural-by-default with structural bridge window)
+# @jtbd JTBD-001 (enforce governance without slowing down — primary)
+# @jtbd JTBD-202 (run pre-flight governance checks before release or handover)
+
+setup() {
+  SKILL_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SKILL_FILE="${SKILL_DIR}/SKILL.md"
+  [ -f "$SKILL_FILE" ]
+}
+
+# ----------------------------------------------------------------------
+# Step 5 substance-confirm fire — separate from draft-quality fire.
+# ----------------------------------------------------------------------
+
+@test "SKILL.md Step 5 names a substance-confirm fire distinct from draft-quality review (P339)" {
+  # P339 root cause: Step 5 currently fires ONE bundled AskUserQuestion that
+  # confounds substance-of-decision (which option was chosen) with
+  # draft-quality (is the prose well-written). The amend SHOULD prescribe
+  # TWO separate firings: substance-confirm first; draft-quality optional.
+  run awk '/^### 5\. /,/^### 6\. /' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"substance-confirm"* ]] || [[ "$output" == *"substance confirm"* ]]
+  [[ "$output" == *"draft-quality"* ]] || [[ "$output" == *"draft quality"* ]] || [[ "$output" == *"draft review"* ]]
+}
+
+@test "SKILL.md Step 5 prescribes prose briefing in main-turn text BEFORE the substance-confirm AskUserQuestion fires (P340)" {
+  # User direction 2026-05-31: long AskUserQuestion text is NOT readable on
+  # some devices (mobile clients, accessibility tooling, certain notification
+  # surfaces). Long prose + short question IS readable across the full
+  # device matrix. The split is load-bearing — the briefing MUST live in
+  # main-turn prose, NOT inside AskUserQuestion text.
+  run awk '/^### 5\. /,/^### 6\. /' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"main-turn"* ]] || [[ "$output" == *"main turn"* ]] || [[ "$output" == *"prose briefing"* ]]
+  [[ "$output" == *"before"* ]] || [[ "$output" == *"BEFORE"* ]]
+}
+
+@test "SKILL.md Step 5 prescribes each-considered-option as a selectable option (not yes/no shape) (P340)" {
+  # User direction 2026-05-31: the AskUserQuestion MUST NOT be a yes/no
+  # shape. It MUST present each considered option as a selectable option in
+  # the AskUserQuestion options array. The user picks the substantive
+  # direction positively (chooses an option), not by clicking "yes" on a
+  # bundled "is this OK?" question.
+  run awk '/^### 5\. /,/^### 6\. /' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"selectable option"* ]] || [[ "$output" == *"each considered option"* ]] || [[ "$output" == *"each option"* ]]
+  [[ "$output" == *"not yes/no"* ]] || [[ "$output" == *"not a yes/no"* ]] || [[ "$output" == *"NOT yes/no"* ]] || [[ "$output" == *"NOT a yes/no"* ]]
+}
+
+@test "SKILL.md Step 5 prescribes no-IDs-as-explainers in briefing prose or option labels (P340)" {
+  # User direction 2026-05-31: the briefing prose, the question, and the
+  # options MUST NOT use IDs as explainers. The user does NOT have access
+  # to those IDs on all devices. Every option's substance MUST be
+  # self-contained in the prose + the option label/description.
+  run awk '/^### 5\. /,/^### 6\. /' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"no IDs as explainers"* ]] || [[ "$output" == *"NOT use IDs"* ]] || [[ "$output" == *"without IDs"* ]] || [[ "$output" == *"no ID"* ]] || [[ "$output" == *"self-contained"* ]]
+}
+
+@test "SKILL.md Step 5 prescribes informed-decision-without-external-document-lookup (P340)" {
+  # User direction 2026-05-31: the user MUST be able to make an informed
+  # decision without looking up other documents. The briefing +
+  # AskUserQuestion is a self-contained surface.
+  run awk '/^### 5\. /,/^### 6\. /' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"without external"* ]] || [[ "$output" == *"without looking up"* ]] || [[ "$output" == *"self-contained"* ]] || [[ "$output" == *"without document lookup"* ]]
+}
+
+# ----------------------------------------------------------------------
+# Born-confirmed marker write — gated on substantive-answer.
+# ----------------------------------------------------------------------
+
+@test "SKILL.md Step 5 gates born-confirmed marker write on substance-confirm answer specifying a substantive option (P340)" {
+  # P340 mechanism fix: the marker MUST be written ONLY in response to an
+  # AskUserQuestion answer that selects ONE specific substantive option from
+  # the considered-options set. NOT on draft-acceptance / problem-statement-
+  # OK / bundled answers.
+  run awk '/^### 5\. /,/^### 6\. /' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"human-oversight: confirmed"* ]] || [[ "$output" == *"born-confirmed"* ]] || [[ "$output" == *"oversight marker"* ]]
+  [[ "$output" == *"ONLY"* ]] || [[ "$output" == *"only when"* ]] || [[ "$output" == *"only if"* ]]
+  [[ "$output" == *"substantive"* ]] || [[ "$output" == *"substance-confirm"* ]] || [[ "$output" == *"considered options"* ]] || [[ "$output" == *"considered-options"* ]]
+}
+
+@test "SKILL.md Step 5 prescribes re-draft + re-fire when user picks a different option than the draft authored (P340)" {
+  # User direction 2026-05-31: if the substance-confirm answer selects a
+  # DIFFERENT option than the one the draft was authored against, the SKILL
+  # MUST re-draft Decision Outcome (+ Consequences + Confirmation +
+  # Pros and Cons) against the new choice and re-fire substance-confirm.
+  # NOT a soft "warn and proceed" — the marker only ever writes when the
+  # draft authored matches the user's substantive pick.
+  run awk '/^### 5\. /,/^### 6\. /' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  shopt -s nocasematch
+  [[ "$output" == *"re-draft"* ]] || [[ "$output" == *"redraft"* ]] || [[ "$output" == *"re-author"* ]]
+  [[ "$output" == *"re-fire"* ]] || [[ "$output" == *"refire"* ]] || [[ "$output" == *"re-run"* ]]
+  shopt -u nocasematch
+}
+
+@test "SKILL.md Step 5 names draft-quality review fire as OPTIONAL and not gating the marker (P340)" {
+  # The draft-quality review fire (prose quality, consulted/informed list,
+  # edge cases) is a follow-up to the substance-confirm fire. It MUST NOT
+  # gate the born-confirmed marker write — that gate sits on the
+  # substance-confirm answer alone.
+  run awk '/^### 5\. /,/^### 6\. /' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"does NOT gate"* ]] || [[ "$output" == *"does not gate"* ]] || [[ "$output" == *"NOT gate the marker"* ]] || [[ "$output" == *"not gate the marker"* ]]
+}
+
+# ----------------------------------------------------------------------
+# No-IDs-as-explainers regression guard — Step 5 prose itself MUST NOT
+# require the user to look up IDs to understand the prescribed interaction.
+# The PRESCRIPTIVE Step 5 prose is allowed to cite IDs as audit-trail
+# annotations (ADR-064, ADR-066, ADR-074, P339, P340 etc.), but the
+# EXAMPLE briefing the SKILL prescribes for the agent to emit MUST be
+# ID-free. This test checks the prescription, not the prose itself.
+# ----------------------------------------------------------------------
+
+@test "SKILL.md Step 5 prescribes example briefing shape is ID-free (P340 — load-bearing for device matrix)" {
+  # The Step 5 prose MUST explicitly prescribe that the BRIEFING the agent
+  # emits (the prose surfacing options + selected option + rationale) is
+  # ID-free. This is the prescription, not a check on the SKILL prose
+  # itself.
+  run awk '/^### 5\. /,/^### 6\. /' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  # Must call out at least one banned ID-shape in the prescription so the
+  # contract is unambiguous.
+  [[ "$output" == *"ADR-"* ]] || [[ "$output" == *"P-NNN"* ]] || [[ "$output" == *"JTBD-"* ]] || [[ "$output" == *"RFC-"* ]] || [[ "$output" == *"identifier"* ]]
+}
+
+# ----------------------------------------------------------------------
+# Cross-reference to P339 + P340 and ADR-074 for audit trail.
+# ----------------------------------------------------------------------
+
+@test "SKILL.md cites P339 + P340 in Step 5 amend prose or Related section (audit trail)" {
+  run grep -nE "P339|P340" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md cites ADR-074 in Step 5 amend prose (substance-confirm-before-build framework)" {
+  run grep -nE "ADR-074" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ----------------------------------------------------------------------
+# P081 + P132 bridge marker
+# ----------------------------------------------------------------------
+
+@test "bats file carries the tdd-review: structural-permitted marker" {
+  run grep -nE "tdd-review:[[:space:]]+structural-permitted" "${BATS_TEST_FILENAME}"
+  [ "$status" -eq 0 ]
+}