@windyroad/architect 0.3.1 → 0.3.2

package/.claude-plugin/plugin.json

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

package/agents/agent.md

@@ -81,6 +81,10 @@ When a change includes a new or modified decision file in `docs/decisions/`:
 - Does it include reassessment criteria?
 - If it supersedes another decision, is the old decision properly updated?
 
+## Output Formatting
+
+When referencing decision IDs (ADR-<NNN>), problem IDs (P<NNN>), or JTBD IDs in prose output, always include the human-readable title on first mention. Use the format `ADR-013 (Skill manifest in package.json)`, not bare `ADR-013`.
+
 ## How to Report
 
 If the change is compliant and no new decision is needed:

package/agents/test/architect-output-formatting.bats

@@ -0,0 +1,26 @@
+#!/usr/bin/env bats
+# Doc-lint guard: architect agent.md must include the output formatting rule
+# requiring human-readable titles alongside bare IDs (P032).
+#
+# Structural assertion — Permitted Exception to the source-grep ban (ADR-005 / P011).
+#
+# Cross-reference:
+#   P032 (agent output uses opaque IDs without titles)
+#   @jtbd JTBD-001 (enforce governance without slowing down)
+
+setup() {
+  AGENT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  AGENT_FILE="${AGENT_DIR}/agent.md"
+}
+
+@test "agent.md contains output formatting section" {
+  run grep -n "## Output Formatting" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "agent.md output formatting rule requires titles with IDs (P032)" {
+  run grep -n "title" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+  run grep -n "Output Formatting" "$AGENT_FILE"
+  [ "$status" -eq 0 ]
+}

package/hooks/architect-detect.sh

@@ -35,7 +35,11 @@ REQUIRED ACTIONS:
 
 SCOPE: All project files including source code, configs, CI, hooks,
 scripts, and decisions.
-Does NOT apply to: CSS/SCSS files, image assets, lockfiles, font files.
+Does NOT apply to: CSS/SCSS files, image assets, lockfiles, font files,
+docs/problems/ (problem tickets), docs/BRIEFING.md, RISK-POLICY.md,
+.risk-reports/, .changeset/, memory files, plan files, docs/jtbd/,
+docs/JOBS_TO_BE_DONE.md, docs/PRODUCT_DISCOVERY.md, docs/VOICE-AND-TONE.md,
+docs/STYLE-GUIDE.md.
 HOOK_OUTPUT
 else
   cat <<'HOOK_OUTPUT'

package/hooks/test/architect-detect-scope.bats

@@ -0,0 +1,50 @@
+#!/usr/bin/env bats
+
+# Tests for architect-detect.sh (UserPromptSubmit) — verifies the injected
+# scope exclusion text lists governance docs that the PreToolUse gate already
+# exempts (P029). Without this, the LLM wastes time delegating to the
+# architect for files the edit gate would allow anyway.
+
+setup() {
+  SCRIPT_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  HOOK="$SCRIPT_DIR/architect-detect.sh"
+  ORIG_DIR="$PWD"
+  TEST_DIR=$(mktemp -d)
+  cd "$TEST_DIR"
+  mkdir -p docs/decisions
+}
+
+teardown() {
+  cd "$ORIG_DIR"
+  rm -rf "$TEST_DIR"
+}
+
+@test "detect: scope text mentions problem files exemption (P029)" {
+  run bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"docs/problems/"* ]] || [[ "$output" == *"problem tickets"* ]]
+}
+
+@test "detect: scope text mentions BRIEFING.md exemption (P029)" {
+  run bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"BRIEFING"* ]]
+}
+
+@test "detect: scope text mentions RISK-POLICY exemption (P029)" {
+  run bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"RISK-POLICY"* ]]
+}
+
+@test "detect: scope text mentions changeset exemption (P029)" {
+  run bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"changeset"* ]]
+}
+
+@test "detect: scope text mentions memory files exemption (P029)" {
+  run bash "$HOOK"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"memory"* ]] || [[ "$output" == *"MEMORY"* ]]
+}

package/package.json

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

package/skills/create-adr/SKILL.md

@@ -32,12 +32,51 @@ Ask the user:
 
 If the user has already provided this context in the conversation (e.g., as arguments), use what they've given and only ask about what's missing.
 
+### 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).
+
+**Self-check**: Read the context gathered in step 2. Answer: "How many distinct decisions are present? If each could be independently accepted, rejected, or superseded without affecting the others, they are distinct."
+
+- **Single decision** (one coherent question with one chosen option): proceed directly to step 3.
+- **Multiple decisions** (two or more distinct questions, different components, or different decision drivers that do not share the same trade-off): present a split prompt.
+
+**Split prompt** — use `AskUserQuestion`:
+- `header: "Multi-decision input"`
+- `multiSelect: false`
+- Options:
+  1. `Split into separate ADRs (Recommended)` — description: "Create one ADR per distinct decision, with consecutive IDs. Each ADR can be accepted, rejected, or superseded independently."
+  2. `Keep as a single ADR` — description: "Create one ADR covering all decisions. Use this only if the decisions are so tightly coupled that they cannot be made independently."
+
+**Non-interactive fallback**: When `AskUserQuestion` is unavailable (e.g., non-interactive/AFK mode), automatically split into separate ADRs with consecutive IDs and note the auto-split in output. Do not block creation.
+
+**Split implementation**: When splitting, assign consecutive IDs. Cross-reference each ADR in the other's Related section or as a linked decision in the consequences.
+
+**Scope**: Scoped to new ADR creation only (steps 2–5). Does not apply to supersession handling (step 6), where the scope of the new decision is already known and bounded.
+
 ### 3. Determine sequence number and filename
 
-- Next number = highest existing decision number + 1 (or 001 if none exist)
+- Next number = **max of the local and origin highest decision numbers**, plus 1 (or 001 if none exist).
 - Filename: `NNN-decision-title-in-kebab-case.proposed.md`
 - Pad the number to 3 digits (001, 002, ... 010, 011, etc.)
 
+**Why compare against origin?** Per ADR-019 confirmation criterion 2, ticket-creator skills MUST re-check next-number assignment against `git ls-tree origin/<base>` before assigning. Without it, parallel sessions can mint the same ADR number for different decisions, causing a destructive surgical rebase on push (this was the failure mode that motivated ADR-019 itself).
+
+```bash
+# Local-max number
+local_max=$(ls docs/decisions/*.md 2>/dev/null | sed 's/.*\///' | grep -oE '^[0-9]+' | sort -n | tail -1)
+
+# Origin-max number — reads remote-tracking ref; no fetch needed here
+# because `wr-architect:agent` upstream callers (e.g. work-problems) run
+# the Step 0 preflight that does the fetch.
+origin_max=$(git ls-tree origin/main docs/decisions/ 2>/dev/null | grep -oE '[0-9]{3}' | sort -n | tail -1)
+
+# Take the max of the two and increment.
+next=$(printf '%03d' $(( $(echo -e "${local_max:-0}\n${origin_max:-0}" | sort -n | tail -1) + 1 )))
+```
+
+If the local choice would have collided with an origin ADR created since the last fetch, the `git ls-tree origin/<base>` lookup catches it here and the renumber is automatic. Log the renumber in the user-facing report (e.g. "Bumped next ADR number from 020 → 021 to avoid collision with origin").
+
 ### 4. Write the ADR
 
 Write the file to `docs/decisions/` with this structure:

package/skills/create-adr/test/create-adr-decision-boundary.bats

@@ -0,0 +1,49 @@
+#!/usr/bin/env bats
+# Doc-lint guard: create-adr SKILL.md must include a decision-boundary
+# analysis step for new ADR creation.
+#
+# Structural assertion — Permitted Exception to the source-grep ban (ADR-005 / P011).
+# These tests assert that the skill specification document conforms to the
+# decision-boundary splitting contract introduced by P017.
+#
+# Cross-reference:
+#   P017: docs/problems/017-create-adr-should-split-multi-decision-records.open.md
+#   ADR-013: docs/decisions/013-structured-user-interaction-for-governance-decisions.proposed.md
+#   Sibling: packages/itil/skills/manage-problem/test/manage-problem-concern-boundary.bats (P016)
+#   @jtbd JTBD-001 (enforce governance without slowing down)
+#   @jtbd JTBD-101 (extend the suite with clear patterns)
+
+setup() {
+  SKILL_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SKILL_FILE="${SKILL_DIR}/SKILL.md"
+}
+
+@test "SKILL.md includes a decision-boundary analysis step for new ADR creation" {
+  # P017: Before writing an ADR file, the skill must check whether the input
+  # contains multiple distinct decisions, and offer to split if it does.
+  # Conflated ADRs damage auditability and block independent status transitions.
+  run grep -in "decision.boundary\|decision-boundary\|decision boundary\|boundary.*decision\|split.*decision\|multi.decision\|single.*decision\|distinct.*decision\|decision.*distinct" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md decision-boundary step uses AskUserQuestion for split decision (ADR-013)" {
+  # ADR-013 Rule 1: all branch points must use AskUserQuestion, not prose options.
+  # The "split into separate ADRs" option must be presented via AskUserQuestion.
+  # Match: AskUserQuestion appearing in context of "split" ADR instruction.
+  run grep -in "Split into separate\|split into.*ADR\|ADR.*split\|split.*ADR" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md decision-boundary step specifies non-interactive auto-split fallback" {
+  # ADR-013 Rule 6: non-interactive fail-safe — when AskUserQuestion is unavailable,
+  # the skill must auto-split (not block/hang) for creation workflows.
+  run grep -in "auto.split\|automatically split" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md decision-boundary step is scoped to new ADR creation (not supersession)" {
+  # P017 fix must only fire during new ADR creation, not during supersession handling.
+  # Checks for explicit scope language excluding supersession from the boundary check.
+  run grep -in "not.*supersession\|supersession.*not\|new ADR creation only\|creation only\|does not apply.*supersession\|Scoped to" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}

package/skills/create-adr/test/create-adr-id-collision-guard.bats

@@ -0,0 +1,35 @@
+#!/usr/bin/env bats
+# Doc-lint guard: create-adr SKILL.md step 3 (Determine sequence number)
+# must include the next-ID collision guard against origin per ADR-019
+# confirmation criterion 2.
+#
+# Structural assertion — Permitted Exception to the source-grep ban (ADR-005 / P011).
+# These tests assert that the skill specification document instructs the
+# ADR creator to compare next-number against origin/<base> before
+# assigning, so parallel sessions don't produce colliding ADR numbers.
+#
+# Cross-reference:
+#   P043 (next-ID collision guard in ticket-creator skills)
+#   ADR-019 (AFK orchestrator preflight, including next-ID guard)
+
+setup() {
+  SKILL_DIR="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  SKILL_FILE="${SKILL_DIR}/SKILL.md"
+}
+
+@test "SKILL.md cites ADR-019 (next-ID collision guard)" {
+  run grep -n "ADR-019" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md step 3 references git ls-tree origin for next-number lookup" {
+  # ADR-019 mechanism: the ADR creator MUST re-check next-number against
+  # `git ls-tree origin/<base>` before assigning.
+  run grep -n "git ls-tree origin" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}
+
+@test "SKILL.md mentions taking the max of local and origin numbers" {
+  run grep -niE "max of (the )?(two|local and origin)|max\(.*origin" "$SKILL_FILE"
+  [ "$status" -eq 0 ]
+}

package/skills/review-design/SKILL.md

@@ -17,6 +17,10 @@ This skill is **read-only**. It does not commit, push, or modify files.
 - When proposing a structural change: get a review before editing architecture-bearing files
 - Any time the hook gate is not convenient: e.g., planning mode, exploratory spikes
 
+## Output Formatting
+
+When referencing decision IDs (ADR-<NNN>), problem IDs (P<NNN>), or JTBD IDs in prose output, always include the human-readable title on first mention. Use the format `ADR-013 (Skill manifest in package.json)`, not bare `ADR-013`.
+
 ## Steps
 
 ### 1. Parse arguments