@windyroad/architect 0.15.5 → 0.15.7

package/.claude-plugin/plugin.json

@@ -123,5 +123,5 @@
     }
   },
   "name": "wr-architect",
-  "version": "0.15.5"
+  "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/hooks/architect-enforce-edit.sh

@@ -5,6 +5,7 @@
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 source "$SCRIPT_DIR/lib/architect-gate.sh"
+source "$SCRIPT_DIR/lib/marker-only-diff.sh"
 
 # P191 Phase 2: resolve the project root from the session signal, not the
 # hook's runtime CWD. Claude Code can launch the hook with a working directory
@@ -22,6 +23,7 @@ INPUT=$(cat)
 
 FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty') || true
 SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') || true
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty') || true
 
 if [ -z "$SESSION_ID" ]; then
   architect_gate_parse_error
@@ -114,6 +116,41 @@ case "$FILE_PATH" in
     exit 0 ;;
 esac
 
+# P301: marker-only-diff exemption for docs/decisions/*.md ADRs. An
+# Edit/Write that adds or updates ONLY the narrow oversight-marker
+# frontmatter grammar (`human-oversight:`, `oversight-date:`,
+# `decision-makers:`, `supersede-ticket:`) is the mechanical output of a
+# decision the user already substance-confirmed via AskUserQuestion
+# (ADR-066 contract); the architect review has nothing substantive to
+# assess. The architect-oversight-marker-discipline.sh hook remains the
+# safety net: marker-only diffs that introduce `human-oversight:
+# confirmed` still require the per-ADR session evidence marker (P348 /
+# ADR-066 amendment 2026-06-02). Mixed marker+body diffs, status:/date:
+# changes, and pure body changes fall through to the normal gate.
+case "$FILE_PATH" in
+  */docs/decisions/*.md|docs/decisions/*.md)
+    case "$TOOL_NAME" in
+      Edit)
+        _OLD=$(echo "$INPUT" | jq -r '.tool_input.old_string // empty') || _OLD=""
+        _NEW=$(echo "$INPUT" | jq -r '.tool_input.new_string // empty') || _NEW=""
+        if [ -n "$_OLD$_NEW" ] && is_marker_only_diff "$_OLD" "$_NEW"; then
+          exit 0
+        fi
+        ;;
+      Write)
+        _NEW=$(echo "$INPUT" | jq -r '.tool_input.content // empty') || _NEW=""
+        _OLD=""
+        if [ -f "$FILE_PATH" ]; then
+          _OLD=$(cat "$FILE_PATH" 2>/dev/null) || _OLD=""
+        fi
+        if [ -n "$_OLD$_NEW" ] && is_marker_only_diff "$_OLD" "$_NEW"; then
+          exit 0
+        fi
+        ;;
+    esac
+    ;;
+esac
+
 # Check gate
 if check_architect_gate "$SESSION_ID"; then
   exit 0

package/hooks/lib/marker-only-diff.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+# Shared helper: detect "oversight-marker-only" frontmatter diffs.
+#
+# P301: ADR-066/068 oversight-marker writes to docs/decisions/ ADRs trip the
+# full architect+JTBD edit gate each batch of an `/wr-architect:review-decisions`
+# drain, producing 2-3 no-op-PASS review round-trips per batch. The marker
+# add/update is the mechanical output of a decision the user already
+# substance-confirmed via AskUserQuestion (ADR-066 contract); the gate has
+# nothing substantive to assess.
+#
+# This helper exposes `is_marker_only_diff OLD NEW` returning 0 when every
+# added/removed non-empty line matches one of the oversight-marker frontmatter
+# patterns:
+#
+#   human-oversight:   confirmed | unconfirmed | rejected-pending-supersede
+#   oversight-date:    <date>
+#   decision-makers:   <name|email>
+#   supersede-ticket:  <ticket>
+#
+# When the predicate fires PASS, the calling gate short-circuits to exit 0
+# without requiring a fresh architect / JTBD review marker. The
+# architect-oversight-marker-discipline.sh (and JTBD sibling) hooks remain
+# active as the safety net: a marker-only diff that introduces
+# `human-oversight: confirmed` still requires the per-ADR session evidence
+# marker (P348 / ADR-066 amendment 2026-06-02).
+#
+# Conservative boundary: any non-empty line outside the marker grammar
+# (frontmatter delimiters that shift position, status:/date: changes, body
+# edits) fails the predicate. The exemption is exact so it cannot be used
+# to slip decision-content edits past the gate.
+#
+# Fail-safe: if python3 is unavailable or the diff parse errors, the function
+# returns 1 (NOT marker-only) and the gate proceeds with its normal review
+# requirement.
+
+is_marker_only_diff() {
+  local old="$1"
+  local new="$2"
+
+  command -v python3 >/dev/null 2>&1 || return 1
+
+  OLD_CONTENT="$old" NEW_CONTENT="$new" python3 - <<'PYEOF'
+import os, sys, re
+try:
+    import difflib
+except Exception:
+    sys.exit(1)
+
+old = os.environ.get('OLD_CONTENT', '')
+new = os.environ.get('NEW_CONTENT', '')
+
+if old == new:
+    sys.exit(0)
+
+old_lines = old.splitlines()
+new_lines = new.splitlines()
+
+marker_pat = re.compile(
+    r'^[ \t]*(human-oversight|oversight-date|decision-makers|supersede-ticket)[ \t]*:.*$'
+)
+
+def allowed(line: str) -> bool:
+    s = line.strip()
+    if s == '':
+        return True
+    if marker_pat.match(line):
+        return True
+    return False
+
+sm = difflib.SequenceMatcher(a=old_lines, b=new_lines, autojunk=False)
+for tag, i1, i2, j1, j2 in sm.get_opcodes():
+    if tag == 'equal':
+        continue
+    for line in old_lines[i1:i2]:
+        if not allowed(line):
+            sys.exit(1)
+    for line in new_lines[j1:j2]:
+        if not allowed(line):
+            sys.exit(1)
+
+sys.exit(0)
+PYEOF
+}

package/hooks/test/architect-marker-only-exempt.bats

@@ -0,0 +1,183 @@
+#!/usr/bin/env bats
+
+# P301: architect-enforce-edit.sh exempts marker-only frontmatter diffs to
+# docs/decisions/*.md ADRs from the full architect review gate. The
+# architect-oversight-marker-discipline.sh hook remains the safety net for
+# `human-oversight: confirmed` introductions; this exemption only short-
+# circuits the enforce-edit drift/TTL gate when the diff adds/modifies
+# nothing but the narrow oversight-marker grammar.
+#
+# Behavioural — exercises the full hook with constructed PreToolUse stdin
+# JSON payloads under a sandbox project dir; asserts on stdout+exit.
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$SCRIPT_DIR/architect-enforce-edit.sh"
+  ORIG_DIR="$PWD"
+  TEST_DIR=$(mktemp -d)
+  cd "$TEST_DIR"
+  # Engage the architect gate — only runs when docs/decisions/ exists.
+  mkdir -p docs/decisions
+  echo "# stub" > docs/decisions/001-stub.proposed.md
+  SID="marker-only-exempt-$$-$BATS_TEST_NUMBER"
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TEST_DIR"
+  rm -f "/tmp/architect-reviewed-${SID}" "/tmp/architect-reviewed-${SID}.hash"
+}
+
+# Helper: run the hook with constructed JSON. Echo to a file then pipe to
+# avoid heredoc / quote-escaping headaches with multi-line content.
+run_hook_json() {
+  local json_file="$1"
+  bash "$HOOK" < "$json_file"
+}
+
+# ── Marker-only ADD: should exempt ───────────────────────────────────────
+
+@test "P301: Edit adding only human-oversight + oversight-date is exempt (no architect marker required)" {
+  adr="$PWD/docs/decisions/100-some-adr.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+date: 2026-06-08
+---
+
+# 100 some adr
+
+Body content unchanged.
+EOF
+  old=$'---\nstatus: "proposed"\ndate: 2026-06-08\n---'
+  new=$'---\nstatus: "proposed"\ndate: 2026-06-08\nhuman-oversight: unconfirmed\noversight-date: 2026-06-08\n---'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "P301: Edit updating human-oversight value (unconfirmed → confirmed) is exempt" {
+  adr="$PWD/docs/decisions/101-promote.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+human-oversight: unconfirmed
+---
+
+# 101 promote
+EOF
+  old=$'human-oversight: unconfirmed'
+  new=$'human-oversight: confirmed\noversight-date: 2026-06-08'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+@test "P301: Edit adding rejected-pending-supersede + supersede-ticket is exempt" {
+  adr="$PWD/docs/decisions/102-rejected.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+---
+
+# 102 rejected
+EOF
+  old=$'status: "proposed"'
+  new=$'status: "proposed"\nhuman-oversight: rejected-pending-supersede\nsupersede-ticket: P999'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"BLOCKED"* ]]
+}
+
+# ── Mixed marker + body: must NOT exempt ─────────────────────────────────
+
+@test "P301: Edit changing body content along with markers still gates" {
+  adr="$PWD/docs/decisions/110-mixed.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+---
+
+# 110 mixed
+
+Original body.
+EOF
+  old=$'---\nstatus: "proposed"\n---\n\n# 110 mixed\n\nOriginal body.'
+  new=$'---\nstatus: "proposed"\nhuman-oversight: confirmed\noversight-date: 2026-06-08\n---\n\n# 110 mixed\n\nRewritten body with new policy claim.'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [[ "$output" == *"BLOCKED"* ]]
+}
+
+@test "P301: Edit changing status field (not a marker line) still gates" {
+  adr="$PWD/docs/decisions/111-status-change.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+---
+
+# 111
+EOF
+  old=$'status: "proposed"'
+  new=$'status: "accepted"\nhuman-oversight: confirmed\noversight-date: 2026-06-08'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [[ "$output" == *"BLOCKED"* ]]
+}
+
+# ── Pure body change: must still gate (no marker involvement) ────────────
+
+@test "P301: Edit changing only body content with no marker lines still gates" {
+  adr="$PWD/docs/decisions/120-body.proposed.md"
+  cat > "$adr" <<'EOF'
+---
+status: "proposed"
+---
+
+# 120 body
+
+Some text.
+EOF
+  old='Some text.'
+  new='Some text. And new text.'
+  json_file=$(mktemp)
+  jq -nc --arg p "$adr" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [[ "$output" == *"BLOCKED"* ]]
+}
+
+# ── Scope: exemption is narrow to docs/decisions/*.md ────────────────────
+
+@test "P301: marker-only diff to a NON docs/decisions/ path still gates (no path exemption)" {
+  mkdir -p "$PWD/src"
+  echo "// stub" > "$PWD/src/x.ts"
+  src="$PWD/src/x.ts"
+  old='// stub'
+  new='// stub'$'\n''human-oversight: confirmed'
+  json_file=$(mktemp)
+  jq -nc --arg p "$src" --arg s "$SID" --arg o "$old" --arg n "$new" \
+    '{tool_name:"Edit",session_id:$s,tool_input:{file_path:$p,old_string:$o,new_string:$n}}' > "$json_file"
+  run run_hook_json "$json_file"
+  rm -f "$json_file"
+  [[ "$output" == *"BLOCKED"* ]]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/architect",
-  "version": "0.15.5",
+  "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: