@windyroad/architect 0.15.6 → 0.15.7

package/.claude-plugin/plugin.json

@@ -123,5 +123,5 @@
     }
   },
   "name": "wr-architect",
-  "version": "0.15.6"
+  "version": "0.15.7"
 }

package/agents/agent.md

@@ -23,6 +23,23 @@ You are the Architect. You review proposed changes against the project's archite
 4. Determine if the change requires a new decision to be documented
 5. Report: PASS if compliant, or list issues requiring attention
 
+## Review Mode: Pre-edit / proposed-change vs. Post-edit / applied
+
+You operate in one of two review modes depending on the calling prompt's framing. Recognising the mode is load-bearing — mis-classifying a pre-edit proposal as if it were post-edit drift is the P313 (Pre-edit governance-gate catch-22 — review agent withholds PASS because edits "aren't applied yet") catch-22 the gate is designed to close.
+
+**Pre-edit mode (the default at a governance-gate firing).** The PreToolUse architect gate fires BEFORE a project-file edit lands on disk. The calling prompt describes a PROPOSED change, fix plan, RFC, ticket-body amendment, or about-to-be-made edit — the change is not yet on disk by design. Recognition signals (any one is sufficient): the prompt uses words like "proposed", "plan to", "about to", "PRE-EDIT", "PRE-EDIT alignment gate"; the prompt names the to-be-edited files but the edits are described in prose not yet applied; the prompt is an AFK orchestrator iter dispatch implementing a `## Fix Strategy` against a problem ticket; the prompt is a SKILL handing you an RFC body or story body before the implementation commit lands.
+
+In pre-edit mode:
+
+- If you receive a review request describing PROPOSED changes (not-yet-applied), classify alignment of the PROPOSAL itself. Not-yet-applied state of the proposed change is the EXPECTED baseline of a pre-edit gate. Do NOT treat "edits aren't applied yet" / "the residual old state is still live" / "the change isn't on disk yet" as ISSUES FOUND — that is the gate's design intent (P313 closes this catch-22).
+- The ground truth you classify against is the **proposal** as described in the calling prompt (the diff sketch, the fix-strategy prose, the file-edit plan). The disk state is the legitimate "old state" the proposal is about to replace.
+- PASS the review when the proposal aligns with existing decisions, the proposal does not require a new decision the user hasn't pinned, and the proposal's substance is sound. ISSUES FOUND on a pre-edit review must cite a problem with the **proposal**, not with the not-yet-applied-ness of the proposal.
+- All other review machinery below (Decision Staleness, Existing Decision Compliance, Confirmation Criteria, New Decision Detection, Runtime-Path Performance, Decision Quality, Unratified Dependency, Needs Direction) applies normally — pre-edit mode does not relax any of those substantive checks. It constrains only the verdict-grammar around the not-yet-applied baseline.
+
+**Post-edit mode (the explicit drift-detection or applied-change review).** The calling prompt asks you to verify already-applied edits against decisions — typically a `/wr-architect:review-design` invocation against staged changes and recent commits, or a release-gate audit. Recognition signals: the prompt names "staged changes", "recent commits", "the current diff", "verify compliance", or "review the applied changes against …". In post-edit mode you may flag drift between disk state and decisions exactly as the original verdict grammar describes — the change is on disk by construction; the not-yet-applied carve-out does not apply.
+
+**Default when ambiguous.** When the calling prompt does not name the mode explicitly, default to **pre-edit mode** if a PreToolUse gate context is plausible (the prompt was likely fired by `architect-detect.sh` or an AFK iter dispatch). The pre-edit default is the safer fail-mode: a true post-edit drift will still surface as ISSUES FOUND on the substance; a true pre-edit proposal mis-classified as post-edit fires the P313 catch-22.
+
 ## What You Check
 
 ### Decision Staleness Check

package/agents/test/architect-pre-edit-review-mode.bats

@@ -0,0 +1,50 @@
+#!/usr/bin/env bats
+# Doc-lint guard: architect agent.md must carry an explicit pre-edit /
+# proposed-change review-mode carve-out so the agent classifies alignment
+# of the PROPOSAL when the calling prompt describes a not-yet-applied
+# change, instead of mis-classifying not-yet-applied state as ISSUES FOUND
+# (P313 catch-22: gate blocks edits; reviewer wants edits done first).
+#
+# tdd-review: structural-permitted (justification: P176 — agent behaviour is
+# prompt-driven with no skill-invocation harness to exercise the verdict
+# behaviourally; ADR-052 Surface 2 structural-justified case, NOT an ADR-005
+# Permitted Exception — ADR-052 narrows ADR-005 to exclude prose-doc greps).
+# When P176 lands, upgrade to a behavioural test that feeds the agent a
+# pre-edit proposal and asserts the PASS verdict.
+#
+# Cross-reference:
+#   P313 (Pre-edit governance-gate catch-22 — pass withheld pending edits)
+#   ADR-052 Surface 2 (structural-justified verdict) + P176 (harness gap)
+#   @jtbd JTBD-001 (Enforce Governance Without Slowing Down — preserves the
+#                   under-60-second review outcome by removing the redundant
+#                   re-delegation the catch-22 currently forces)
+
+setup() {
+  AGENT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  AGENT_FILE="${AGENT_DIR}/agent.md"
+}
+
+@test "agent.md carries a Review Mode section distinguishing pre-edit from post-edit (P313)" {
+  run grep -nE "^## Review Mode: Pre-edit / proposed-change vs\. Post-edit / applied" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md classifies alignment of the PROPOSAL in pre-edit mode (P313 verbatim core sentence)" {
+  run grep -nE "classify alignment of the PROPOSAL itself" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md treats not-yet-applied state as the EXPECTED baseline of a pre-edit gate (P313)" {
+  run grep -nE "EXPECTED baseline of a pre-edit gate" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md explicitly rejects 'edits aren't applied yet' as a valid ISSUES FOUND substance (P313)" {
+  run grep -nE "Do NOT treat .edits aren't applied yet" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md cites P313 as the catch-22 closure (audit-trail)" {
+  run grep -nE "P313" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/architect",
-  "version": "0.15.6",
+  "version": "0.15.7",
   "description": "Architecture decision enforcement for AI coding agents",
   "bin": {
     "windyroad-architect": "./bin/install.mjs"
@@ -25,6 +25,7 @@
     "skills/",
     "scripts/",
     ".claude-plugin/",
-    "lib/"
+    "lib/",
+    "!skills/*/eval/"
   ]
 }

package/skills/capture-adr/SKILL.md

@@ -49,6 +49,24 @@ 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).
 
+#### Title-as-outcome convention (P354)
+
+ADR titles must name the **decision outcome** as a short noun phrase, not the question being decided. The title is the skim-surface for `docs/decisions/` and the ADR-077 compendium — readers should resolve what was decided from the title alone, without opening the file. User direction 2026-06-03 (P354): *"ADR titles are supposed to be the short version of what was decided, so they are skimmable."*
+
+**GOOD** (outcome — short noun phrase; drawn from corpus): `marketplace-only-distribution`, `monorepo-per-plugin-packages`, `behavioural-tests-default-for-skill-testing`, `plugin-script-resolution-via-bin-on-path`, `every-fix-goes-through-an-rfc`.
+
+**BAD** (question / option-pair / deliberation): `<X>-vs-<Y>` (option-pair), `should-<Z>` (deliberation), `whether-<Z>` (open question), `<X>-or-<Y>` (pure option-set).
+
+In `capture-adr` the chosen Decision is pinned in `$ARGUMENTS` at invocation, so the caller SHOULD supply a Title already in outcome shape — the framework does not retitle here (the canonical-outcome short-name is the caller's to author, not the framework's to derive). If the parsed Title slug matches a question-shape pattern (`-vs-`, `should-`, `whether-`, `-or-`), emit an advisory in the I2-isomorphic shape via the shared `emit_stderr_advisory` helper:
+
+```
+capture-adr: derived title='<slug>' from $ARGUMENTS — slug appears question-shaped (matched <pattern>); the Decision is pinned in $ARGUMENTS so an outcome-shaped Title is recommended; re-invoke with an outcome-shaped Title or rename the file at canonical expansion.
+```
+
+The advisory is **advisory-only** (no halt, no retitle). The caller may proceed with the question-shaped slug if they choose; the subsequent `/wr-architect:create-adr <NNN>` canonical-expansion pass picks up the retitle in its Step 5a mechanical retitle-after-decision check.
+
+(Serves JTBD-001 — skimmable titles on the on-disk record; ADR-044 category-4 silent-framework — advisory, not ask.)
+
 ### 2. Compute the next ADR ID
 
 Same P056-safe `local_max + origin_max + 1` formula as `/wr-architect:create-adr` Step 3:

package/skills/create-adr/SKILL.md

@@ -34,7 +34,7 @@ Resolve each field via the following dispatch. **The order is load-bearing** —
 
 | Field | Dispatch | ADR-044 category |
 |-------|----------|------------------|
-| **Title** | Derive silently. Kebab-case the first 8-10 non-stopword tokens of the user's prose problem-statement (same slug derivation as `/wr-itil:capture-problem` Step 1.4, `/wr-itil:manage-incident` Step 4, and `/wr-itil:manage-problem` Step 4 — uses the shared helper's `derive_kebab_slug` function). Emit stderr advisory: `create-adr: derived title='<slug>' from problem-statement; re-invoke with the desired title or rename the file if the slug is wrong`. Do NOT fire AskUserQuestion. | category-4 silent-framework |
+| **Title** | Derive silently. Kebab-case the first 8-10 non-stopword tokens of the user's prose problem-statement (same slug derivation as `/wr-itil:capture-problem` Step 1.4, `/wr-itil:manage-incident` Step 4, and `/wr-itil:manage-problem` Step 4 — uses the shared helper's `derive_kebab_slug` function). At intake the derived slug typically encodes the **question** (the problem-statement is question-shaped); the title-as-outcome convention in Step 2a below names the GOOD/BAD shapes, and Step 5a's mechanical retitle-after-decision check renames the file to the chosen-option's outcome shape after substance-confirm passes. Emit stderr advisory: `create-adr: derived title='<slug>' from problem-statement; re-invoke with the desired title or rename the file if the slug is wrong`. Do NOT fire AskUserQuestion. | category-4 silent-framework |
 | **status** (frontmatter) | Always `proposed` for new ADRs per Step 4 template convention. No ask, no advisory needed — SKILL convention is unambiguous. | category-4 silent-framework |
 | **date** (frontmatter) | Today's date (`date +%Y-%m-%d`) per Step 4 template. No ask, no advisory needed — wall-clock derivation is unambiguous. | category-4 silent-framework |
 | **reassessment-date** (frontmatter) | Today + 3 months (`date -v+3m +%Y-%m-%d` on BSD-date / `date -d '+3 months' +%Y-%m-%d` on GNU-date) per Step 4 template. Emit stderr advisory: `create-adr: derived reassessment-date='<YYYY-MM-DD>' from today+3-months default; re-invoke with --reassessment-date= or edit the frontmatter to override`. | category-4 silent-framework |
@@ -67,6 +67,30 @@ The advisory text shape is I2-isomorphic — same sentence structure across all
 
 If the user has already provided context in `$ARGUMENTS` or earlier conversation, use what they've given and only fire AskUserQuestion for the cat-1 fields still missing.
 
+### 2a. Title-as-outcome convention (P354)
+
+ADR titles must name the **decision outcome** as a short noun phrase, not the question / option-pair being decided. The title is the skim-surface — a reader scanning `docs/decisions/` or the ADR-077 compendium should resolve what was decided from the title alone, without opening the file. User direction 2026-06-03 (P354): *"ADR titles are supposed to be the short version of what was decided, so they are skimmable. Titles like this force the reader to read the document to find the details of what was decided."*
+
+**GOOD** (outcome — short noun phrase naming the decided thing; drawn from corpus):
+
+- `marketplace-only-distribution`
+- `monorepo-per-plugin-packages`
+- `progressive-disclosure-for-governance-tooling-context`
+- `behavioural-tests-default-for-skill-testing`
+- `plugin-script-resolution-via-bin-on-path`
+- `every-fix-goes-through-an-rfc`
+
+**BAD** (question / option-pair / deliberation — reader must open file to learn outcome):
+
+- `npm-release-auth-stored-token-vs-oidc` (option-pair pattern `-vs-`)
+- `should-we-adopt-oidc-for-npm-release-auth` (deliberation pattern `should-`)
+- `whether-to-monorepo-or-polyrepo` (open-question pattern `whether-`)
+- `marketplace-or-direct-distribution` (pure option-set pattern `-or-`)
+
+**At intake the derived title is acceptable in either shape**: Step 2's `derive_kebab_slug` runs against the problem-statement, which is typically question-shaped. The title-as-outcome convention is enforced at Step 5a's mechanical retitle-after-decision check (post substance-confirm, when the chosen option is locked in). The title need not be outcome-shaped before the decision is made.
+
+(Serves JTBD-001 — skimmable titles speed the read path for the governance-enforcement persona.)
+
 ### 2b. Decision-boundary analysis (multi-decision check)
 
 Before writing the ADR file, perform a decision-boundary analysis on the gathered context to prevent conflated ADRs that block independent status transitions and weaken auditability (P017).
@@ -253,6 +277,20 @@ This is NOT a soft "warn and proceed" path — the marker only ever writes when
 
 **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`.
 
+**Retitle-after-decision check (P354 — ADR-044 category-4 silent-framework).** After the marker write lands, check the on-disk filename slug for a question-shape pattern (`-vs-`, `should-`, `whether-`, `-or-`). If matched, the title was derived at intake against a question-shaped problem-statement and must be retitled to the chosen-option's outcome shape now that the substance is locked in. The convention is named in Step 2a above.
+
+This step is **mechanical — no AskUserQuestion fires** (per P132 inverse-P078 guard). The chosen option is now known from the substance-confirm answer just above; derive the outcome slug from the chosen-option short name via the same `derive_kebab_slug` helper Step 2's Title derivation uses (`packages/architect/lib/derive-first-dispatch.sh`). Sequence (ordered to preserve marker-discipline hook semantics — the marker-introducing Edit must land BEFORE `git mv`):
+
+1. Derive `new_slug = derive_kebab_slug "<chosen option short name>"`.
+2. Edit the H1 in the on-disk file to the new outcome shape (H1 stays human-readable Title Case; the slug is for the filename). The `human-oversight: confirmed` line is already in `OLD_CONTENT` so `architect-oversight-marker-discipline.sh` allows this Edit per its "old content already had the marker" branch.
+3. `git mv docs/decisions/<NNN>-<old-slug>.proposed.md docs/decisions/<NNN>-<new-slug>.proposed.md` (Bash command — no Edit/Write hook fires; rename is captured as a rename in git history).
+4. Emit the I2-isomorphic stderr advisory: `create-adr: retitled <NNN>-<old-slug>.proposed.md -> <NNN>-<new-slug>.proposed.md from chosen-option '<short-name>'; git mv reversible via inverse rename.`
+5. The subsequent compendium regen below picks up the new filename automatically.
+
+If the on-disk slug does NOT match a question-shape pattern (already outcome-shaped at intake), skip this step silently — no advisory needed.
+
+(Serves JTBD-001 — outcome-shaped on-disk title; category-4 silent-framework per ADR-044.)
+
 #### 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: