@windyroad/architect 0.5.2 → 0.6.0-preview.279

package/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "wr-architect",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Architecture decision enforcement for Claude Code"
 }

package/README.md

@@ -35,6 +35,14 @@ Once installed, the plugin works automatically. You don't need to invoke it -- i
 
 This walks you through creating an ADR in [MADR 4.0](https://adr.github.io/madr/) format. It examines your existing decisions, asks about the problem and options, and writes a properly formatted record to `docs/decisions/`.
 
+**Capture an architecture decision in the background while staying in the main turn:**
+
+```
+/wr-architect:capture-adr
+```
+
+The `capture-adr` skill is the foreground-lightweight aside-invocation variant of `create-adr` (per ADR-032 background-capture pattern). Use it when an architecture decision surfaces mid-conversation and you want the ADR scaffold drafted without losing the operational thread.
+
 ## How It Works
 
 | Hook | Trigger | What it does |
@@ -44,6 +52,7 @@ This walks you through creating an ADR in [MADR 4.0](https://adr.github.io/madr/
 | `architect-plan-enforce.sh` | ExitPlanMode | Ensures plans are reviewed before execution |
 | `architect-mark-reviewed.sh` | Agent completes | Marks the review as done (TTL: 3600s) |
 | `architect-refresh-hash.sh` | After edit | Refreshes the content hash so the next edit triggers a fresh review |
+| `architect-slide-marker.sh` | Agent or Bash | Slides the review marker forward across non-edit operations so an active review session is not invalidated by intervening Bash or sub-agent calls |
 
 ## Agent
 
@@ -53,6 +62,26 @@ The `wr-architect:agent` reviews proposed changes against existing decisions in
 - Whether a new ADR should be created
 - Whether existing decisions are stale and need reassessment
 
+## Jobs to be Done
+
+This plugin serves the [Jobs to be Done](../../docs/jtbd/) below. Per [ADR-051](../../docs/decisions/051-jtbd-anchored-readme-with-drift-advisory.proposed.md), the persona-grouped JTBD anchor is the canonical source of truth for the README's value framing.
+
+### Tech lead / consultant
+
+- **[JTBD-202 Run Pre-Flight Governance Checks Before Release or Handover](../../docs/jtbd/tech-lead/JTBD-202-pre-flight-governance-check.proposed.md)** — architect review is available via `/wr-architect:review-design` for on-demand pre-flight, and via `wr-architect:agent` for automatic review on every edit.
+
+### Solo developer
+
+- **[JTBD-001 Enforce Governance Without Slowing Down](../../docs/jtbd/solo-developer/JTBD-001-enforce-governance.proposed.md)** — architecture decisions are reviewed automatically; the agent reads the project's existing ADRs without needing to be told what to look for.
+
+### Plugin developer
+
+- **[JTBD-101 Extend the Suite with New Plugins](../../docs/jtbd/plugin-developer/JTBD-101-extend-suite.proposed.md)** — `/wr-architect:create-adr` is the canonical surface for documenting structural decisions in MADR 4.0 format so contributors learn the "why" behind existing patterns.
+
+### Plugin user
+
+- **[JTBD-302 Trust That the README Describes the Plugin I Just Installed](../../docs/jtbd/plugin-user/JTBD-302-trust-readme-describes-installed-behaviour.proposed.md)** — this README is anchored on current JTBD job IDs; drift between prose and shipped behaviour is detectable at retro time per ADR-051.
+
 ## Updating and Uninstalling
 
 ```bash

package/hooks/architect-detect.sh

@@ -58,6 +58,11 @@ docs/problems/ (problem tickets), docs/BRIEFING.md, docs/briefing/, RISK-POLICY.
 .risk-reports/, .changeset/, memory files, plan files, docs/jtbd/,
 docs/PRODUCT_DISCOVERY.md, docs/VOICE-AND-TONE.md,
 docs/STYLE-GUIDE.md.
+NOTE: these exclusions are READ tolerance — the architect gate skips
+user edits to these paths. They are NOT agent write targets. Never
+write project-generated artefacts (plans, audits, scratch state) under
+.claude/ — that is user-controlled config space. Project-generated
+content belongs under docs/ or directly in problem-ticket bodies (P131).
 HOOK_OUTPUT
     mark_announced "architect" "$SESSION_ID"
   fi

package/hooks/architect-enforce-edit.sh

@@ -54,6 +54,9 @@ case "$FILE_PATH" in
     exit 0 ;;
   */MEMORY.md|*/.claude/projects/*/memory/*)
     exit 0 ;;
+  # READ tolerance only — gate skips user edits to .claude/plans/. NOT a write
+  # target for agents. .claude/ is user-controlled config space; agents must not
+  # write project-generated artefacts here. See P131.
   */.claude/plans/*.md|*.claude/plans/*.md)
     exit 0 ;;
   */RISK-POLICY.md)

package/package.json

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

package/skills/capture-adr/REFERENCE.md

@@ -0,0 +1,175 @@
+# `/wr-architect:capture-adr` Reference
+
+This file hosts the rationale, edge cases, contract trade-offs, and ADR cross-references for the `/wr-architect:capture-adr` skill. SKILL.md is the runtime contract (~190 lines, on-topic per ADR-038 progressive disclosure); this REFERENCE.md is the on-demand expansion for maintainers and curious users.
+
+## Why a separate skill?
+
+The `/wr-architect:create-adr` flow is ~10-15 turns of agent work for a full new-ADR intake: Step 1 discovery, Step 2 AskUserQuestion gathering (Title + Options ≥2 + Pros/Cons + Decision-makers + Consequences), Step 2b decision-boundary AskUserQuestion, Step 3 next-ID, Step 4 file write with full frontmatter + body, Step 5 confirm-with-user AskUserQuestion review pass, optional Step 6 supersession handling.
+
+That cost is correct for the canonical new-ADR path — the user wants to walk the flow, see the option-comparison prompts, and codify the full MADR shape immediately.
+
+It is wrong for the **aside-invocation** use case. P156 surfaced three repeating patterns where the heavyweight cost is load-bearing friction:
+
+1. **Mid-AFK-iter design decisions**: agent or user lands on a design choice during a foreground iter (e.g. iter 17 P137 Option C namespace-prefix; iter 19 ADR-056 Phase 2a back-channel write contract). The 10-15 turn ceremony breaks iter cadence — decisions get buried inline in commit bodies or RCA sections.
+2. **Architect-review verdict capture**: a `wr-architect:agent` review yields a substantive verdict (PASS-WITH-NOTES / ISSUES-FOUND) whose rationale deserves an ADR-shaped record. Today the verdict + rationale lands in commit messages and rots — future readers grep history but lose the structured trace.
+3. **User-driven design conversations**: user resolves options (a)/(b)/(c) during conversational work; the settlement currently lives in a problem-ticket RCA section instead of a discoverable ADR.
+
+`/wr-architect:capture-adr` is the source-side fix: a lightweight skill with a deferred-placeholder pattern that captures the decision in ~3-4 turns and routes the deferred canonical expansion through `/wr-architect:create-adr` at a time of the user's choosing.
+
+## Contract trade-offs
+
+### Skeleton-MADR validity at status `proposed`
+
+Architect Q1 verdict (P156 review): the architect-agent's review prompt tolerates skeleton ADRs at `status: proposed`. It checks "does the proposed change conflict with the decision's outcome?" not "does every section have prose?" The deferred-flag pattern is the load-bearing signal that downstream tooling and any future canonical-expansion auto-detect path keys off (mirrors capture-problem's `(deferred — re-rate at next /wr-itil:review-problems)` literal).
+
+Status `proposed` (not `accepted`) is the right cover for skeleton state. The architect-agent enforces the MADR ≥2-options requirement at **acceptance review**, not at `proposed.md` skeleton time. Each deferred section carries the literal pointer string `(deferred to /wr-architect:create-adr canonical review)` so canonical-expansion tooling can detect and expand mechanically.
+
+### Considered Options skeleton — `1. Option A (chosen)` + `2. (deferred — see ...)`
+
+Architect Q2 verdict: write a literal numbered placeholder so the file parses cleanly under any doc-lint asserting ≥2 numbered options. The placeholder pattern:
+
+```markdown
+1. **Option A (chosen)** — <one-line summary>
+2. (deferred — see /wr-architect:create-adr canonical review)
+```
+
+Avoids tripping future structural lint while preserving the lightweight-capture promise (no AskUserQuestion gathering of alternatives at capture time).
+
+### Frontmatter sentinel values vs. truly minimal
+
+Architect Q5 verdict: full minimum frontmatter with sentinel values is friendlier than absent fields:
+
+```yaml
+---
+status: "proposed"
+date: <YYYY-MM-DD>
+decision-makers: [unspecified — fill at canonical review]
+consulted: []
+informed: []
+reassessment-date: <YYYY-MM-DD + 3 months>
+---
+```
+
+The architect-agent flags missing required frontmatter fields; sentinel-with-flag carries the deferral signal explicitly, which is more discoverable than absence at canonical-expansion time.
+
+`reassessment-date` defaults to 3 months from today (matches `create-adr` Step 4) — the criteria themselves remain deferred-flagged in body.
+
+### Deferred-canonical-expansion contract
+
+Capture-adr skips the architect-agent review handoff that `/wr-architect:create-adr` Step 5 (confirm-with-user) implicitly performs. The trade-off:
+
+| Surface | Inline canonical (create-adr) | Deferred canonical (capture-adr) |
+|---------|-------------------------------|----------------------------------|
+| Architect-agent review at write-time | Yes (Step 5 confirm pass) | No (deferred to canonical expansion) |
+| Capture-time turn cost | ~10-15 turns | ~3-4 turns |
+| MADR conformance at write-time | Full | Skeleton (status: proposed covers) |
+| Audit trail (commit) | One commit covers full ADR | One commit covers skeleton |
+| Acceptance window | Same session | Bounded by next canonical-expansion invocation |
+
+The deferred contract is acceptable because:
+
+1. **Status `proposed` is the explicit covering signal** that the ADR is not accepted yet. The architect-agent reviews `.proposed.md` files and can flag deferred-skeleton state for expansion before any downstream consumer treats it as accepted.
+2. **The trailing pointer in Step 6 is the user-visible signal** that canonical expansion is needed. The user has explicit instructions for how to reconcile.
+3. **Auto-detect-and-expand is a follow-up** (Q3 verdict — out of scope for P156). When `/wr-architect:create-adr` is later invoked on a captured `<NNN>`, it can detect the existing skeleton and expand the deferred sections rather than writing a new ADR. P156 does not ship this auto-detect path; the manual workflow is `/wr-architect:create-adr` invoked with the captured ID + body context.
+
+### No AskUserQuestion at all
+
+Architect Q4 + JTBD review confirmed: capture-adr is a **mechanical-stage skill** per ADR-044's framework-resolution boundary. Every potentially-interactive decision is framework-mediated:
+
+- **Considered Options**: skeleton placeholder; defer ≥2-options requirement to canonical review.
+- **Decision Drivers / Consequences / Confirmation**: framework-policy deferred flag; canonical review fills.
+- **Reassessment date**: framework-policy default 3 months from today.
+- **Decision-makers / consulted / informed**: framework-policy sentinel `[unspecified — fill at canonical review]`.
+- **Multi-decision split**: out of scope. The user invoking capture-adr with a multi-decision payload gets one ADR with the full payload; they re-route to `/wr-architect:create-adr` for the structured Step 2b decision-boundary split.
+
+This mirrors the mechanical-stage carve-out pattern documented in CLAUDE.md (P132 / inverse-P078 trap): when a SKILL contract names a stage as mechanical, do not ask. Per-action consent gates re-ask decisions the user already made and silently undo the load-bearing UX investment.
+
+## Edge cases
+
+### Empty `$ARGUMENTS`
+
+Halt-with-stderr-directive. capture-adr requires Title + 1-line Context + 1-line Decision; without payload there is nothing to capture. The directive points the user to `/wr-architect:create-adr`, which has Step 2 AskUserQuestion gathering for full intake.
+
+AFK orchestrators MUST NOT invoke capture-adr with empty arguments — caller-side contract. The Rule 6 audit makes this explicit so AFK-iter writers don't accidentally introduce a halt mid-loop.
+
+### Partial `$ARGUMENTS` (Title only / Title + Decision)
+
+If only Title is supplied, write the skeleton with deferred placeholders in Context + Decision Outcome. If Title + Decision (no Context), defer Context only. The deferred-flag literal pointer string preserves the canonical-expansion signal.
+
+This is a graceful-degradation case — real captures carry Title + Context + Decision — but the partial-payload path prevents a halt when only some context is available.
+
+### Title slug collision
+
+If two captures land on the same kebab-slug (different IDs but identical title fragments), the file paths differ by ID prefix so no collision occurs at the filesystem layer. The next-ID formula guarantees ID uniqueness against local + origin.
+
+### ID collision with origin
+
+The next-ID formula uses `git ls-tree origin/main` to read the remote-tracking ref without requiring a fetch. If a parallel session minted the same ID for a different decision and pushed it before this session captures, the local read sees the higher origin ID and increments past it.
+
+If the local session has not fetched recently and origin has captures the local doesn't see, the formula may still collide. The renumber audit log line in Step 6 captures the resolution. P040 incident applies.
+
+`--name-only` is required (P056): without it, default `git ls-tree` output carries the 40-char blob SHA which can contain three-digit runs that the digit-extraction regex false-matches. Same fix as create-adr Step 3 / manage-problem Step 3.
+
+### Captured ADR never expanded
+
+If the user captures and never invokes canonical expansion, the `.proposed.md` skeleton remains with deferred-flagged sections. Acceptable failure mode: the architect-agent flags `.proposed.md` files during compliance review and surfaces stale skeletons for expansion. The skeleton is more useful than no record at all (P156 line 19 driver: "decisions not captured drift; future iters reinvent the same design space").
+
+### Architect-review verdict capture
+
+Use case: a `wr-architect:agent` review yields PASS-WITH-NOTES with substantive rationale. Pattern:
+
+1. User invokes capture-adr with `$ARGUMENTS = "Title from review topic\nContext: review of <change>\nDecision: <one-line verdict + rationale>"`.
+2. Skeleton lands at `docs/decisions/<NNN>-<kebab-title>.proposed.md` with status `proposed`.
+3. Trailing pointer reminds user to canonical-expand.
+4. Canonical expansion via `/wr-architect:create-adr <NNN>` fleshes out Considered Options (the alternatives the architect weighed) + Consequences + Confirmation + Reassessment.
+
+This pattern preserves architect-review verdicts as first-class ADR-shaped records instead of letting them rot in commit-message bodies.
+
+### Cross-namespace consistency with capture-problem
+
+The `capture-` verb is consistent across `/wr-itil:capture-problem` and `/wr-architect:capture-adr`. Same dispatch shape (~3-4 turns), same deferred-placeholder pattern, same single-commit-per-capture grain, same trailing-pointer signal. Users learn one mental model that spans both. ADR-032 amendment names this symmetry.
+
+## Composition with the rest of the suite
+
+### `/wr-architect:create-adr`
+
+Heavyweight intake counterpart. The two skills share the `docs/decisions/*.proposed.md` directory and the next-ID formula. Cross-skill ordering: capture-adr writes a skeleton at `<NNN>`; later `/wr-architect:create-adr <NNN>` (or direct Edit) expands the deferred sections in place. The auto-detect-and-expand path (where `/wr-architect:create-adr` mechanically detects a captured skeleton at the requested ID and expands rather than writes) is a follow-up ticket (architect Q3 verdict — out of scope for P156).
+
+### `wr-architect:agent`
+
+The review surface that processes ADR review delegations. capture-adr does not invoke the architect-agent inline; the deferred-canonical-expansion contract routes review through `/wr-architect:create-adr`'s Step 5 confirm pass. The architect-agent reviewing a `.proposed.md` skeleton sees `status: proposed` + deferred-flag literals and treats it as a not-yet-accepted ADR; reviews focus on whether the captured Decision conflicts with existing accepted ADRs.
+
+### `/wr-itil:manage-problem` / `/wr-itil:capture-problem`
+
+Compose with capture-adr when an iter surfaces both a problem AND a related decision. The user fires `/wr-itil:capture-problem <observation>` + `/wr-architect:capture-adr <decision>` in sequence (~6-8 turns total) instead of ~20-30 turns through the heavyweight pair.
+
+### `/wr-itil:work-problems` (AFK orchestrator)
+
+Iter subprocesses can invoke capture-adr to capture mid-iter design decisions without breaking iter cadence. The AFK carve-out in ADR-032 (line 85) excludes the **background-capture** variant from AFK contexts; the **foreground-lightweight-capture** variant introduced by P156 is fine inside iter subprocesses because it has no `Agent(run_in_background: true)` invocation — it is a normal foreground-synchronous skill that happens to do less work than create-adr.
+
+### `/wr-architect:capture-adr` callers
+
+The intended invocation surface is `/wr-architect:capture-adr <Title>\n<Context>\n<Decision>`. The payload must be non-empty; the skill does not branch on payload shape beyond the partial-payload graceful-degradation path documented under Edge cases.
+
+## Related ADRs
+
+- **ADR-009** — gate-marker-lifecycle (capture-adr does not write `/tmp` markers; ADR-009 referenced for pattern lineage only).
+- **ADR-013** — structured user interaction (Rule 6 fail-safe; capture-adr has no AskUserQuestion branches so Rule 6 is trivially satisfied).
+- **ADR-014** — governance skills commit their own work (capture-adr owns its commit).
+- **ADR-019** — AFK orchestrator preflight (next-ID formula uses origin-tracking ref per ADR-019 confirmation criterion 2).
+- **ADR-032** — governance skill invocation patterns (this skill's parent ADR; foreground-lightweight-capture variant amendment 2026-05-03 for capture-adr).
+- **ADR-038** — progressive disclosure (SKILL.md + REFERENCE.md split shape).
+- **ADR-044** — decision-delegation contract (framework-mediated mechanical-stage carve-outs).
+- **ADR-049** — bin/ on PATH (capture-adr is self-contained; no new shim required, same as create-adr).
+- **ADR-052** — behavioural-tests-default for skill testing (capture-adr's bats fixtures exercise primitives, not SKILL.md prose).
+- **ADR-056** (`docs/decisions/056-...md` if present) — example of an inline-shipped substantive ADR that capture-adr could have skeleton-captured first.
+
+## Related problems
+
+- **P014** — parent / master tracker (ADR-032 children).
+- **P088** — settled the user-direction-scoped decision: capture-problem + capture-adr are shippable; capture-retro is deferred.
+- **P155** — sibling capture-problem skill (just shipped 2026-05-03).
+- **P156** — driver ticket.
+- **P157** — sibling pending-questions-surface hook.
+- **P056** — ticket-creator next-ID lookup blob-SHA false-match (capture-adr's next-ID formula uses the `--name-only` fix).
+- **P040** — origin-collision incident referenced in Edge cases.

package/skills/capture-adr/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: wr-architect:capture-adr
+description: Lightweight ADR-capture skill for aside-invocation during foreground work — single-option skeleton, deferred-flagged sections (Considered Options / Decision Drivers / Consequences / Confirmation / Reassessment), single commit, no inline architect-review handoff. Defers full canonical expansion to /wr-architect:create-adr. Use this when the user (or agent mid-iter) wants to record a decision quickly without the ~10-15 turn ceremony of /wr-architect:create-adr. For full-intake new ADR creation with options + drivers + consequences + confirmation, use /wr-architect:create-adr.
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Capture ADR Skill
+
+Capture an Architecture Decision Record quickly during foreground work. Lightweight aside-invocation surface that complements the heavyweight `/wr-architect:create-adr` flow. See `REFERENCE.md` in this directory for rationale, edge cases, contract trade-offs, and the ADR-032 foreground-lightweight-capture amendment.
+
+This skill is the foreground-lightweight-capture variant of `/wr-architect:create-adr`'s new-ADR path per ADR-032 (P156 amendment, 2026-05-03). The deferred background-capture variant named in ADR-032's original taxonomy remains deferred per P088 settlement.
+
+## When to invoke
+
+- **Mid-iter design decision**: agent or user lands on a design choice during foreground work and cannot afford the ~10-15 turn ceremony of `/wr-architect:create-adr`.
+- **Architect-review verdict capture**: a `wr-architect:agent` review yields a substantive PASS-WITH-NOTES / ISSUES-FOUND verdict whose rationale deserves an ADR-shaped record (today the verdict lands in commit messages and the rationale rots).
+- **User-driven design conversations**: user resolves options (a)/(b)/(c) during conversational work; today the settlement gets buried in a problem-ticket RCA section instead of codified.
+
+**Use `/wr-architect:create-adr` instead** when:
+- The user wants to walk the full intake flow (Considered Options ≥2, Decision Drivers, full Consequences, Confirmation criteria, Pros/Cons of Options).
+- The decision is large enough that the deferred-placeholder pattern is unhelpful (the user already has the canonical-shape content).
+- The decision needs immediate architect review + acceptance (capture-adr writes `.proposed.md`; canonical acceptance is a follow-up via `/wr-architect:create-adr` or direct architect-agent review).
+
+## Rule 6 audit (per ADR-032 + ADR-013)
+
+This skill has **zero AskUserQuestion branches** by design. Each potentially-interactive decision is framework-mediated per ADR-044:
+
+| Decision | Resolution |
+|----------|-----------|
+| Considered Options ≥2 | Mechanical: skeleton writes `1. Option A (chosen) — <one-line>` + `2. (deferred — see /wr-architect:create-adr canonical review)`. The MADR ≥2-options requirement is enforced at acceptance, not at skeleton time; status `proposed` covers skeleton state. |
+| Decision drivers | Framework-policy: flag `(deferred to /wr-architect:create-adr canonical review)`. Drivers are typically discovered during canonical expansion. |
+| Consequences | Framework-policy: flag `(deferred to /wr-architect:create-adr canonical review)`. Consequences require trade-off analysis the lightweight path does not perform. |
+| Confirmation criteria | Framework-policy: flag `(deferred to /wr-architect:create-adr canonical review)`. Testable confirmation is a canonical-review concern. |
+| Reassessment criteria | Framework-policy default: 3 months from today (matches `create-adr` Step 4 default); flag `(deferred — refine at canonical review)` for the criteria themselves. |
+| Decision-makers / consulted / informed | Framework-policy: write `[unspecified — fill at canonical review]` sentinel + flag at canonical review. |
+| Empty `$ARGUMENTS` | Halt-with-stderr-directive: print "capture-adr requires Title + 1-line Context + 1-line Decision in $ARGUMENTS — invoke /wr-architect:create-adr instead for the full intake flow" and exit. AFK orchestrators MUST NOT invoke capture-adr with empty arguments — caller-side contract. |
+
+Per ADR-013 Rule 6 fail-safe: every branch above resolves without user input, so AFK and interactive contexts behave identically.
+
+## Steps
+
+### 1. Parse Title + 1-line Context + 1-line Decision from `$ARGUMENTS`
+
+The expected `$ARGUMENTS` shape is free-text describing **(a) Title**, **(b) one-line Context** (the problem being solved), and **(c) one-line Decision** (the chosen option in one sentence).
+
+Parsing heuristic: split on the first newline (Title) and second newline (Context); the rest is Decision. If only one line is supplied, treat it as Title and use deferred-flag placeholders for Context + Decision. If two lines, treat as Title + Decision and defer Context.
+
+Empty `$ARGUMENTS` halts per the Rule 6 audit above.
+
+Derive a kebab-case title slug from the first 8-10 non-stopword tokens of the Title (matching the existing `create-adr` slug derivation pattern).
+
+### 2. Compute the next ADR ID
+
+Same P056-safe `local_max + origin_max + 1` formula as `/wr-architect:create-adr` Step 3:
+
+```bash
+local_max=$(ls docs/decisions/*.md 2>/dev/null | sed 's/.*\///' | grep -oE '^[0-9]+' | sort -n | tail -1)
+origin_max=$(git ls-tree --name-only origin/main docs/decisions/ 2>/dev/null | sed 's|^docs/decisions/||' | grep -oE '^[0-9]+' | sort -n | tail -1)
+next=$(printf '%03d' $(( $(echo -e "${local_max:-0}\n${origin_max:-0}" | sort -n | tail -1) + 1 )))
+```
+
+`--name-only` is required (P056): without it, each `git ls-tree` line includes the 40-char blob SHA which can contain three-digit runs that the digit-extraction regex false-matches.
+
+Log the renumber decision in the operation report if origin and local diverged.
+
+### 3. Skeleton-fill the MADR template
+
+**File path**: `docs/decisions/<NNN>-<kebab-title>.proposed.md`
+
+**Template** (deferred-placeholder pattern — flag every section the capture didn't fill, with the literal pointer string `(deferred to /wr-architect:create-adr canonical review)` so canonical-expansion tooling can detect and expand mechanically):
+
+```markdown
+---
+status: "proposed"
+date: <YYYY-MM-DD>
+decision-makers: [unspecified — fill at canonical review]
+consulted: []
+informed: []
+reassessment-date: <YYYY-MM-DD + 3 months>
+---
+
+# <Title>
+
+> Captured via /wr-architect:capture-adr (foreground-lightweight aside-invocation per ADR-032 P156 amendment). Run /wr-architect:create-adr on this ID to expand the deferred sections canonically.
+
+## Context and Problem Statement
+
+<one-line Context from $ARGUMENTS, or "(deferred to /wr-architect:create-adr canonical review)" if not supplied>
+
+## Decision Drivers
+
+- (deferred to /wr-architect:create-adr canonical review)
+
+## Considered Options
+
+1. **Option A (chosen)** — <one-line summary derived from Decision in $ARGUMENTS>
+2. (deferred — see /wr-architect:create-adr canonical review)
+
+## Decision Outcome
+
+Chosen option: **"Option A"**, because <one-line Decision from $ARGUMENTS, or "(deferred to /wr-architect:create-adr canonical review)" if not supplied>.
+
+## Consequences
+
+### Good
+
+- (deferred to /wr-architect:create-adr canonical review)
+
+### Neutral
+
+- (deferred to /wr-architect:create-adr canonical review)
+
+### Bad
+
+- (deferred to /wr-architect:create-adr canonical review)
+
+## Confirmation
+
+(deferred to /wr-architect:create-adr canonical review)
+
+## Pros and Cons of the Options
+
+### Option A
+
+- (deferred to /wr-architect:create-adr canonical review)
+
+## Reassessment Criteria
+
+(deferred to /wr-architect:create-adr canonical review — default reassessment-date 3 months from capture)
+```
+
+The deferred-placeholder pattern is load-bearing — `/wr-architect:create-adr` (and any future canonical-expansion auto-detect path) keys off the literal pointer string `(deferred to /wr-architect:create-adr canonical review)` to surface captured ADRs for expansion.
+
+The numbered-options placeholder (`1. Option A (chosen) ...` + `2. (deferred ...)`) preserves the MADR ≥2-options surface for any doc-lint that asserts numbered-option presence; status `proposed` covers the skeleton state for canonical-acceptance review.
+
+### 4. Write the file
+
+Single `Write` to `docs/decisions/<NNN>-<kebab-title>.proposed.md`.
+
+### 5. Commit per ADR-014 — single commit, no architect-review handoff
+
+**Stage list**: ONLY the new ADR file.
+
+```bash
+git add docs/decisions/<NNN>-<kebab-title>.proposed.md
+```
+
+Satisfy the commit gate per ADR-014 — same two-path pattern as `manage-problem` Step 11 / `capture-problem` Step 6:
+
+- **Primary**: delegate to subagent type `wr-risk-scorer:pipeline` via the Agent tool.
+- **Fallback**: invoke `/wr-risk-scorer:assess-release` via the Skill tool when the subagent type is unavailable in the current tool surface.
+
+Commit message:
+
+```
+docs(decisions): capture ADR-<NNN> <title>
+```
+
+The `capture` verb is the audit signal that this ADR landed via the lightweight aside path (vs. `add` / `accept` for canonical create-adr's full intake). The status remains `proposed` until canonical review accepts it.
+
+### 6. Report
+
+After the commit, report:
+
+- The new ADR file path and ID.
+- Trailing pointer: `Run /wr-architect:create-adr <NNN> next to expand the deferred sections canonically (Considered Options ≥2, Decision Drivers, Consequences, Confirmation, Reassessment Criteria).`
+- Note any renumber-from-origin-collision log line from Step 2.
+
+The trailing pointer is **not optional** — it is the user-visible signal that the skeleton needs canonical expansion before acceptance review.
+
+## Composition with create-adr
+
+| Concern | create-adr | capture-adr |
+|---------|------------|-------------|
+| Considered Options | AskUserQuestion gathering ≥2 options + pros/cons | Single-option skeleton with chosen flagged + deferred placeholder |
+| Decision Drivers | AskUserQuestion gathering | Deferred flag |
+| Consequences | AskUserQuestion gathering Good/Neutral/Bad | Deferred flag (Good/Neutral/Bad sections present, content deferred) |
+| Confirmation | AskUserQuestion gathering testable criteria | Deferred flag |
+| Reassessment criteria | AskUserQuestion gathering | 3-month default date + deferred-flag criteria |
+| Frontmatter | Full populated frontmatter | Sentinel values (`unspecified — fill at canonical review`) + 3-month reassessment |
+| Decision-boundary check (Step 2b) | Multi-decision split via AskUserQuestion | Out of scope (one ADR per invocation) |
+| Supersession (Step 6) | Handles `git mv .accepted.md → .superseded.md` | Out of scope (capture is creation only) |
+| Confirm-with-user (Step 5) | AskUserQuestion review pass | Out of scope |
+| Commit grain | One commit per intake | One commit per capture |
+| Use case | Full-intake new ADR; user wants to walk the flow | Aside-invocation; capture-and-continue |
+
+The two skills share the `docs/decisions/*.proposed.md` directory and the next-ID formula. Cross-skill ordering: capture-adr writes a skeleton at `<NNN>`; later `/wr-architect:create-adr <NNN>` (or direct Edit) expands the deferred sections in place. Auto-detect-and-expand path is a follow-up (see "Composition" in REFERENCE.md).
+
+## Related
+
+- **P156** (`docs/problems/156-ship-capture-adr-skill.open.md`) — driver ticket.
+- **P014** (`docs/problems/014-aside-invocation-for-governance-skills.open.md`) — parent / master tracker.
+- **P155** (`docs/problems/155-ship-capture-problem-skill.verifying.md`) — sibling capture-problem skill.
+- **P157** — sibling pending-questions-surface hook.
+- **ADR-032** (`docs/decisions/032-governance-skill-invocation-patterns.proposed.md`) — foreground-lightweight-capture variant amendment (P156 amendment, 2026-05-03).
+- **ADR-038** — progressive-disclosure pattern (SKILL.md + REFERENCE.md split).
+- **ADR-044** — decision-delegation contract (framework-mediated mechanical-stage carve-outs).
+- **ADR-049** — bin/ on PATH (capture-adr is self-contained; no shim required, same as create-adr).
+- **ADR-052** — behavioural-tests-default for skill testing.
+- `packages/architect/skills/create-adr/SKILL.md` — heavyweight intake counterpart.
+- `packages/architect/agents/agent.md` — wr-architect:agent review surface; reviews `.proposed.md` skeletons during canonical-expansion delegation.
+
+$ARGUMENTS

package/skills/capture-adr/test/capture-adr.bats

@@ -0,0 +1,319 @@
+#!/usr/bin/env bats
+# Behavioural fixtures for /wr-architect:capture-adr (P156).
+#
+# Per ADR-052 (Behavioural-tests-default for skill testing), these tests
+# exercise the load-bearing primitives the skill dispatches and assert
+# observable state — NOT the prose contents of SKILL.md.
+#
+# Behavioural surfaces under test:
+#   1. Next-ID computation — capture-adr reuses create-adr Step 3 P056-safe
+#      local_max + origin_max formula. Test runs the formula against a
+#      fixture decisions directory and asserts the computed next ID
+#      matches the expected zero-padded value (including the empty-dir
+#      first-ADR base case).
+#   2. Skeleton-fill MADR shape — captured ADR has Title + status proposed
+#      + deferred-flag literal pointer string + numbered-options
+#      placeholder (1. chosen + 2. deferred). Tests execute the
+#      skeleton-fill template against fixture inputs and assert the
+#      resulting file's load-bearing fields.
+#   3. Default reassessment-date — 3 months from today is computed
+#      correctly and lands in frontmatter.
+#   4. Frontmatter sentinel values — decision-makers: [unspecified — fill
+#      at canonical review] is the framework-policy default.
+#
+# Structural assertions are limited to existence/wiring (file presence +
+# frontmatter name + allowed-tools surface) per the precedent set by the
+# capture-problem bats fixtures (P155). Anything else asserts behaviour.
+#
+# @problem P156
+# @jtbd JTBD-001 (enforce governance without slowing down — lightweight
+#                  ADR-capture path)
+# @jtbd JTBD-005 (invoke governance assessments on demand — discoverable
+#                  via / autocomplete)
+# @jtbd JTBD-006 (progress backlog while AFK — mid-iter design-decision
+#                  capture in iter subprocesses)
+# @jtbd JTBD-101 (extend the suite — symmetric with capture-problem on
+#                  the architect plugin namespace)
+# @adr ADR-032 (governance skill invocation patterns — foreground-
+#                lightweight-capture variant for capture-adr)
+# @adr ADR-038 (progressive disclosure — SKILL.md + REFERENCE.md split)
+# @adr ADR-044 (decision-delegation contract — framework-mediated
+#                mechanical-stage carve-outs; no AskUserQuestion)
+# @adr ADR-049 (bin/ on PATH — capture-adr is self-contained, no shim
+#                required, same as create-adr)
+# @adr ADR-052 (behavioural-tests-default — these tests exercise
+#                primitives, not SKILL.md prose)
+
+setup() {
+  REPO_ROOT="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../../../.." && pwd)"
+  SKILL_DIR="${REPO_ROOT}/packages/architect/skills/capture-adr"
+  SKILL_FILE="${SKILL_DIR}/SKILL.md"
+  REF_FILE="${SKILL_DIR}/REFERENCE.md"
+
+  # Fresh per-test scratch directory.
+  TMPROOT=$(mktemp -d)
+}
+
+teardown() {
+  rm -rf "$TMPROOT"
+}
+
+# ---------------------------------------------------------------------------
+# Existence / wiring tests — minimum surface required for the skill to be
+# discoverable. Not structural prose-greps; these assert artefacts exist.
+# ---------------------------------------------------------------------------
+
+@test "capture-adr: SKILL.md and REFERENCE.md both exist (ADR-038 split)" {
+  [ -f "$SKILL_FILE" ]
+  [ -f "$REF_FILE" ]
+}
+
+@test "capture-adr: SKILL.md frontmatter declares wr-architect:capture-adr name" {
+  # Discoverable on / autocomplete depends on the canonical name.
+  # ADR-032 names this skill at line 81 + P156 amendment block.
+  run grep -E '^name: wr-architect:capture-adr$' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Next-ID computation — capture-adr reuses create-adr Step 3 formula.
+# P056-safe via `git ls-tree --name-only` to avoid blob-SHA false-match.
+# ---------------------------------------------------------------------------
+
+@test "capture-adr: next-ID formula is P056-safe (origin/local max + 1)" {
+  # Build a fixture decisions directory with mixed status suffixes.
+  # The formula must pick the max ID across all suffixes and zero-pad.
+  mkdir -p "$TMPROOT/docs/decisions"
+  : > "$TMPROOT/docs/decisions/001-foo.accepted.md"
+  : > "$TMPROOT/docs/decisions/032-bar.proposed.md"
+  : > "$TMPROOT/docs/decisions/057-baz.proposed.md"
+  : > "$TMPROOT/docs/decisions/123-qux.superseded.md"
+
+  # Mirror create-adr Step 3 / capture-adr Step 2 local-max formula exactly.
+  local_max=$(ls "$TMPROOT/docs/decisions"/*.md 2>/dev/null \
+              | sed 's/.*\///' \
+              | grep -oE '^[0-9]+' \
+              | sort -n | tail -1)
+  [ "$local_max" = "123" ]
+
+  # No origin available in the fixture; default to 0 then increment.
+  next=$(printf '%03d' $(( $(echo -e "${local_max:-0}\n0" | sort -n | tail -1) + 1 )))
+  [ "$next" = "124" ]
+}
+
+@test "capture-adr: next-ID handles empty decisions dir (first ADR)" {
+  mkdir -p "$TMPROOT/docs/decisions"
+  local_max=$(ls "$TMPROOT/docs/decisions"/*.md 2>/dev/null \
+              | sed 's/.*\///' \
+              | grep -oE '^[0-9]+' \
+              | sort -n | tail -1)
+  next=$(printf '%03d' $(( $(echo -e "${local_max:-0}\n0" | sort -n | tail -1) + 1 )))
+  [ "$next" = "001" ]
+}
+
+@test "capture-adr: next-ID prefers origin_max when origin > local (collision guard)" {
+  # Simulate the case where origin has a higher ADR number than local
+  # (parallel session pushed a new ADR before this session captures).
+  mkdir -p "$TMPROOT/docs/decisions"
+  : > "$TMPROOT/docs/decisions/050-local.proposed.md"
+  local_max=50
+  origin_max=175   # parallel session pushed ADR-175
+
+  next=$(printf '%03d' $(( $(echo -e "${local_max:-0}\n${origin_max:-0}" | sort -n | tail -1) + 1 )))
+  [ "$next" = "176" ]
+}
+
+# ---------------------------------------------------------------------------
+# Skeleton-fill MADR shape — capture-adr writes a deferred-placeholder ADR
+# at status: proposed. Load-bearing primitives:
+#   - Title at H1
+#   - status: proposed in frontmatter
+#   - decision-makers sentinel
+#   - reassessment-date 3 months from today
+#   - Numbered-options placeholder (1. chosen + 2. deferred) — preserves
+#     MADR ≥2-options surface for any doc-lint assertion.
+#   - Literal pointer string `(deferred to /wr-architect:create-adr
+#     canonical review)` — this is the canonical-expansion detection key.
+# ---------------------------------------------------------------------------
+
+@test "capture-adr: skeleton-filled ADR carries deferred-flag literal pointer string" {
+  # The literal `(deferred to /wr-architect:create-adr canonical review)`
+  # is the load-bearing canonical-expansion detection signal. Any future
+  # auto-detect-and-expand path will key off this string.
+  mkdir -p "$TMPROOT/docs/decisions"
+  TITLE="example-mid-iter-decision"
+  ID="200"
+  TODAY=$(date -u +%Y-%m-%d)
+  REASSESS=$(date -u -v+3m +%Y-%m-%d 2>/dev/null || date -u -d "+3 months" +%Y-%m-%d)
+  CONTEXT_LINE="Iter-bound design choice that needs codification."
+  DECISION_LINE="Adopt Option A because it preserves invariants X and Y."
+
+  # Mirror the SKILL.md skeleton-fill template.
+  cat > "$TMPROOT/docs/decisions/${ID}-${TITLE}.proposed.md" <<EOF
+---
+status: "proposed"
+date: ${TODAY}
+decision-makers: [unspecified — fill at canonical review]
+consulted: []
+informed: []
+reassessment-date: ${REASSESS}
+---
+
+# ${TITLE}
+
+> Captured via /wr-architect:capture-adr (foreground-lightweight aside-invocation per ADR-032 P156 amendment). Run /wr-architect:create-adr on this ID to expand the deferred sections canonically.
+
+## Context and Problem Statement
+
+${CONTEXT_LINE}
+
+## Decision Drivers
+
+- (deferred to /wr-architect:create-adr canonical review)
+
+## Considered Options
+
+1. **Option A (chosen)** — ${DECISION_LINE}
+2. (deferred — see /wr-architect:create-adr canonical review)
+
+## Decision Outcome
+
+Chosen option: **"Option A"**, because ${DECISION_LINE}
+
+## Consequences
+
+### Good
+
+- (deferred to /wr-architect:create-adr canonical review)
+
+### Neutral
+
+- (deferred to /wr-architect:create-adr canonical review)
+
+### Bad
+
+- (deferred to /wr-architect:create-adr canonical review)
+
+## Confirmation
+
+(deferred to /wr-architect:create-adr canonical review)
+
+## Pros and Cons of the Options
+
+### Option A
+
+- (deferred to /wr-architect:create-adr canonical review)
+
+## Reassessment Criteria
+
+(deferred to /wr-architect:create-adr canonical review — default reassessment-date 3 months from capture)
+EOF
+
+  ADR="$TMPROOT/docs/decisions/${ID}-${TITLE}.proposed.md"
+  [ -f "$ADR" ]
+
+  # Behavioural assertions: load-bearing fields present.
+  run grep -F 'status: "proposed"' "$ADR"
+  [ "$status" -eq 0 ]
+  # Decision-makers sentinel for canonical-review fill.
+  run grep -F 'decision-makers: [unspecified — fill at canonical review]' "$ADR"
+  [ "$status" -eq 0 ]
+  # Title from input lands at H1.
+  run grep -F "# ${TITLE}" "$ADR"
+  [ "$status" -eq 0 ]
+  # Context survives verbatim from input.
+  run grep -F "$CONTEXT_LINE" "$ADR"
+  [ "$status" -eq 0 ]
+  # Decision survives verbatim from input.
+  run grep -F "$DECISION_LINE" "$ADR"
+  [ "$status" -eq 0 ]
+  # Deferred-flag literal pointer string — canonical-expansion detection key.
+  run grep -F '(deferred to /wr-architect:create-adr canonical review)' "$ADR"
+  [ "$status" -eq 0 ]
+}
+
+@test "capture-adr: skeleton has numbered-options placeholder (1. chosen + 2. deferred)" {
+  # MADR ≥2-options surface preserved at skeleton time so any doc-lint
+  # asserting numbered-option presence does not fire on capture-adr output.
+  # Architect Q2 verdict: write literal placeholder, defer enforcement.
+  mkdir -p "$TMPROOT/docs/decisions"
+  ID="201"
+  TITLE="another-decision"
+
+  cat > "$TMPROOT/docs/decisions/${ID}-${TITLE}.proposed.md" <<'EOF'
+## Considered Options
+
+1. **Option A (chosen)** — One-line summary
+2. (deferred — see /wr-architect:create-adr canonical review)
+EOF
+
+  ADR="$TMPROOT/docs/decisions/${ID}-${TITLE}.proposed.md"
+  # Numbered option 1 with chosen marker.
+  run grep -F '1. **Option A (chosen)**' "$ADR"
+  [ "$status" -eq 0 ]
+  # Numbered option 2 with deferred marker.
+  run grep -F '2. (deferred — see /wr-architect:create-adr canonical review)' "$ADR"
+  [ "$status" -eq 0 ]
+}
+
+@test "capture-adr: default reassessment-date is 3 months from today (matches create-adr)" {
+  # The 3-month default matches create-adr Step 4 default and is
+  # framework-policy per ADR-044. Computed value lands in frontmatter.
+  TODAY=$(date -u +%Y-%m-%d)
+  # Compute 3 months from today using BSD date or GNU date.
+  REASSESS=$(date -u -v+3m +%Y-%m-%d 2>/dev/null || date -u -d "+3 months" +%Y-%m-%d)
+
+  # The reassess date is non-empty and parseable as YYYY-MM-DD.
+  [ -n "$REASSESS" ]
+  echo "$REASSESS" | grep -qE '^[0-9]{4}-[0-9]{2}-[0-9]{2}$'
+
+  # The reassess date is strictly later than today (3 months ahead).
+  [ "$REASSESS" \> "$TODAY" ]
+}
+
+# ---------------------------------------------------------------------------
+# Skill-allowed-tools surface contract — capture-adr MUST NOT carry
+# AskUserQuestion (per design Q4 + ADR-044 framework-mediated mechanical-
+# stage decisions). This is observable from the frontmatter declaration
+# the runtime consumes.
+# ---------------------------------------------------------------------------
+
+@test "capture-adr: allowed-tools omits AskUserQuestion (no interactive branches)" {
+  # The skill's contract is NO AskUserQuestion at all — Considered Options
+  # / Decision Drivers / Consequences / Confirmation / Reassessment are
+  # framework-mediated mechanical stages per ADR-044. AskUserQuestion in
+  # allowed-tools would let future drift sneak prompts back in.
+  run grep -E '^allowed-tools:' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+  run grep -E '^allowed-tools:.*AskUserQuestion' "$SKILL_FILE"
+  [ "$status" -ne 0 ]
+}
+
+@test "capture-adr: allowed-tools includes Bash (for next-ID + commit primitives)" {
+  # next-ID via git ls-tree | grep | sort + commit gate via Bash invocation.
+  run grep -E '^allowed-tools:.*Bash' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "capture-adr: allowed-tools includes Write (for new ADR file)" {
+  run grep -E '^allowed-tools:.*Write' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+# ---------------------------------------------------------------------------
+# Deferred-canonical-expansion contract — distinguishing capture-adr from
+# create-adr. capture-adr must NOT invoke the architect-agent inline; it
+# writes status: proposed and defers review to canonical expansion.
+# This is the contract distinction from create-adr Step 5 (confirm-with-user).
+# ---------------------------------------------------------------------------
+
+@test "capture-adr: SKILL.md prescribes deferred canonical expansion (no inline review handoff)" {
+  # The contract distinction from create-adr: capture-adr does NOT invoke
+  # the wr-architect:agent review inline; it writes status: proposed and
+  # routes review through the canonical-expansion path. A future
+  # maintainer who copies create-adr's Step 5 confirm pass into capture-adr
+  # would break the lightweight-capture promise.
+  # Asserts the SKILL.md names the deferred contract explicitly.
+  run grep -F '/wr-architect:create-adr' "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}