@windyroad/architect 0.21.1 → 0.21.2-preview.1078
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.claude-plugin/plugin.json +1 -1
- package/.codex-plugin/plugin.json +1 -1
- package/README.md +2 -2
- package/agents/agent.md +23 -24
- package/hooks/architect-compendium-update-entry.sh +11 -1
- package/hooks/architect-detect.sh +1 -1
- package/hooks/architect-dispatch.sh +93 -0
- package/hooks/architect-oversight-marker-discipline.sh +1 -1
- package/hooks/architect-readme-pairing-check.sh +1 -1
- package/hooks/hooks.json +4 -13
- package/hooks/lib/architect-gate.sh +1 -1
- package/package.json +3 -1
- package/scripts/generate-decisions-compendium.sh +9 -3
- package/scripts/mark-oversight-confirmed.sh +1 -1
- package/skills/capture-adr/REFERENCE.md +39 -39
- package/skills/capture-adr/SKILL.md +34 -34
- package/skills/create-adr/SKILL.md +57 -56
- package/skills/review-decisions/SKILL.md +28 -28
- package/skills/review-design/SKILL.md +4 -4
- package/scripts/sync-codex-skills.mjs +0 -85
|
@@ -19,9 +19,9 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
|
|
|
19
19
|
|
|
20
20
|
Create a new ADR in `docs/decisions/` following MADR 4.0 format. The wr-architect:agent reviews these files to enforce architectural compliance.
|
|
21
21
|
|
|
22
|
-
## Needs-Direction handoff + confirm-every-ADR (
|
|
22
|
+
## Needs-Direction handoff + confirm-every-ADR (the Needs-Direction handoff rule)
|
|
23
23
|
|
|
24
|
-
When a `wr-architect:agent` review returns a **NEEDS DIRECTION** verdict (a new decision with 2+ viable options and no pinned direction, per
|
|
24
|
+
When a `wr-architect:agent` review returns a **NEEDS DIRECTION** verdict (a new decision with 2+ viable options and no pinned direction, per the Needs-Direction handoff rule), the option choice is the user's, not the agent's — this skill is the translation surface. The architect's named question + options become the Step 2 cat-1 `request_user_input` calls (Considered Options / Decision Outcome), and the Step 5 confirm is the load-bearing **review-and-confirm-every-ADR** gate: an ADR must not stand as a human-oversighted decision (reach `accepted`) without that confirm pass. A `/wr-architect:capture-adr` ADR — zero-ask, with its decision pre-pinned in `$ARGUMENTS` and its remaining sections silently DERIVED at capture per the governance-skill invocation rule derived-substance amendment (the full-substance capture implementation design) — must still have its derived substance human-ratified (via `/wr-architect:review-decisions` or this skill's confirm) before promotion to `accepted`. When direction IS already pinned (same-turn / same-session / accepted ADR / RISK-POLICY.md / CLAUDE.md mandatory rule), act on it — do not re-ask (the inverse over-ask guard).
|
|
25
25
|
|
|
26
26
|
## Steps
|
|
27
27
|
|
|
@@ -33,26 +33,26 @@ Scan for existing ADRs:
|
|
|
33
33
|
- Read any decisions related to the topic being discussed (if the user has mentioned a topic)
|
|
34
34
|
- If `docs/decisions/` does not exist, create it
|
|
35
35
|
|
|
36
|
-
### 2. Gather context (
|
|
36
|
+
### 2. Gather context (the mechanical-stage over-asking failure derive-first; the decision-delegation rule category-4 silent-framework on derivable fields; category-1 direction-setting only on user-judgment fields)
|
|
37
37
|
|
|
38
|
-
**Shared dispatch helper**: this surface invokes `<architect-plugin-root>/lib/derive-first-dispatch.sh` for the canonical slug derivation (Title) and I2-isomorphic stderr advisory format. The canonical source-of-truth lives at `packages/shared/derive-first-dispatch.sh`; the architect package carries a synced per-package copy at `<architect-plugin-root>/lib/derive-first-dispatch.sh` per
|
|
38
|
+
**Shared dispatch helper**: this surface invokes `<architect-plugin-root>/lib/derive-first-dispatch.sh` for the canonical slug derivation (Title) and I2-isomorphic stderr advisory format. The canonical source-of-truth lives at `packages/shared/derive-first-dispatch.sh`; the architect package carries a synced per-package copy at `<architect-plugin-root>/lib/derive-first-dispatch.sh` per the synced per-package shared-code rule. The same helper is sourced by `/wr-itil:capture-problem` Step 1.5, `/wr-itil:manage-incident` Step 4, and `/wr-itil:manage-problem` Step 4 (each from its own per-package `packages/itil/lib/` copy); drift in the advisory shape across the four surfaces re-opens the mechanical-stage over-asking failure.
|
|
39
39
|
|
|
40
40
|
**Derive-first dispatch.** ADR creation is fundamentally user-judgment-bound — only the user knows the decision space, the alternatives considered, and the chosen-option rationale. But the **declaration-skeleton fields** (Title, status, date, reassessment-date, context-and-problem-statement) carry observable evidence in the user's prose, the working tree, and the wall-clock — the framework can resolve them without firing `request_user_input`. The retained `request_user_input` surfaces (Decision Drivers, Considered Options, Decision Outcome, Consequences, Confirmation, decision-makers) are the genuine **category-1 direction-setting** fields.
|
|
41
41
|
|
|
42
|
-
The
|
|
42
|
+
The mechanical-stage over-asking failure inverse missed strong-correction capture failure trap (`docs/problems/known-error/132-...md`) is the load-bearing motivation. create-adr Step 2 is the **fourth declaration-skill surface** under Phase 2a to ship the derive-first dispatch (after `/wr-itil:capture-problem` Step 1.5, `/wr-itil:manage-incident` Step 4, and `/wr-itil:manage-problem` Step 4). The pattern is I2-isomorphic across all four — the stderr advisory shape `<skill>: derived <field>=<value> from <source>; <reversibility>` is identical beyond substituted values per the helper's `emit_stderr_advisory` function (architect verdict 2026-05-16 the mechanical-stage over-asking failure Phase 2a-iii-B: pattern lock-in across the 4-surface set).
|
|
43
43
|
|
|
44
44
|
Resolve each field via the following dispatch. **The order is load-bearing** — every derivable field resolves silently with a stderr advisory citing the source; only user-judgment fields fire `request_user_input`.
|
|
45
45
|
|
|
46
|
-
| Field | Dispatch |
|
|
46
|
+
| Field | Dispatch | the decision-delegation rule category |
|
|
47
47
|
|-------|----------|------------------|
|
|
48
48
|
| **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 request_user_input. | category-4 silent-framework |
|
|
49
49
|
| **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 |
|
|
50
50
|
| **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 |
|
|
51
51
|
| **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 |
|
|
52
52
|
| **Context and Problem Statement** | Pull verbatim from `$ARGUMENTS` prose into the Step 4 template's `## Context and Problem Statement` section. **Fallback**: when `$ARGUMENTS` carries NO problem prose (only flags or empty body), fire request_user_input as the genuine category-1 direction-setting surface — *"only the user knows the problem being solved."* Question text: *"What problem does this ADR solve? Why is a decision needed now?"* This is the prose-fallback path; the typical maintainer invocation carries the problem-statement in arguments. | category-1 direction-setting (fallback only; category-4 silent-framework on the typical path where prose is present) |
|
|
53
|
-
| **decision-makers** | Retain request_user_input. Architect verdict 2026-05-16: silent derivation from `git config user.name` would conflate "who committed the ADR" with "who made the decision" — a multi-party decision is one of the canonical mis-attribution risks
|
|
53
|
+
| **decision-makers** | Retain request_user_input. Architect verdict 2026-05-16: silent derivation from `git config user.name` would conflate "who committed the ADR" with "who made the decision" — a multi-party decision is one of the canonical mis-attribution risks the structured governance interaction rule's identity model rejects. Once-per-ADR ask is low-friction in absolute terms. Question text: *"Who are the decision-makers?"* | category-1 direction-setting |
|
|
54
54
|
| **Decision Drivers** | Retain request_user_input. Only the user knows which factors weighted the decision. This is the create-adr-equivalent of manage-problem Step 4's Description (the user-judgment surface). | category-1 direction-setting |
|
|
55
|
-
| **Considered Options** | Retain request_user_input. Only the user knows the alternatives evaluated.
|
|
55
|
+
| **Considered Options** | Retain request_user_input. Only the user knows the alternatives evaluated. the decision-delegation rule cat-5 (taste) would only apply if the framework could offer 2+ valid options — but the alternative space is genuinely user-knowledge (the framework can offer "do nothing" + a status-quo option but the actual alternatives are the user's). Architect verdict 2026-05-16: confirmed cat-1 over cat-5. Per MADR 4.0: ≥2 alternatives including "do nothing" where applicable. | category-1 direction-setting |
|
|
56
56
|
| **Decision Outcome** / **Rationale** | Retain request_user_input. The chosen option + primary reason for the choice. | category-1 direction-setting |
|
|
57
57
|
| **Consequences** (Good / Neutral / Bad) | Retain request_user_input. Only the user knows the expected consequences of the decision. | category-1 direction-setting |
|
|
58
58
|
| **Confirmation** | Retain request_user_input. Testable verification criteria. | category-1 direction-setting |
|
|
@@ -60,7 +60,7 @@ Resolve each field via the following dispatch. **The order is load-bearing** —
|
|
|
60
60
|
|
|
61
61
|
**Inferred fields (no ask, no advisory needed)**:
|
|
62
62
|
|
|
63
|
-
- **supersedes** (frontmatter): empty list by default; populated only via Step
|
|
63
|
+
- **supersedes** (frontmatter): empty list by default; populated only via Step 5c supersession handling when the user explicitly cites a superseded decision.
|
|
64
64
|
|
|
65
65
|
**Stderr advisory contract**: each derived field emits a SINGLE line to stderr (NOT stdout, NOT in the ADR body) via the shared helper's `emit_stderr_advisory` function in `<architect-plugin-root>/lib/derive-first-dispatch.sh`. The canonical format produced by the helper:
|
|
66
66
|
|
|
@@ -68,19 +68,19 @@ Resolve each field via the following dispatch. **The order is load-bearing** —
|
|
|
68
68
|
create-adr: derived <field>=<value> from <source>; <reversibility-clause>
|
|
69
69
|
```
|
|
70
70
|
|
|
71
|
-
The advisory text shape is I2-isomorphic — same sentence structure across all four derive-first declaration-skill surfaces (`capture-problem`, `manage-incident`, `manage-problem`, `create-adr`) beyond substituted values + source names. The helper is the single source-of-truth for this format; drift here re-opens
|
|
71
|
+
The advisory text shape is I2-isomorphic — same sentence structure across all four derive-first declaration-skill surfaces (`capture-problem`, `manage-incident`, `manage-problem`, `create-adr`) beyond substituted values + source names. The helper is the single source-of-truth for this format; drift here re-opens the mechanical-stage over-asking failure. Embedding the advisory in stdout would risk machine-readers parsing it as an ADR-body line; embedding it in the ADR body would violate the MADR 4.0 schema. Stderr is the correct channel — visible to interactive maintainers in the terminal; invisible to ADR consumers; loggable by orchestrators that capture subprocess stderr.
|
|
72
72
|
|
|
73
|
-
**
|
|
73
|
+
**the grounded agent-output rule cost-source grounding**: each derived field cites its source in the advisory (problem-statement token sequence for Title; today's date for date / reassessment-date; default convention for status). The `re-invoke or update if mis-rated` clause carries the reversibility marker the grounded agent-output rule mandates for ungrounded outputs.
|
|
74
74
|
|
|
75
|
-
**AFK fail-safe (
|
|
75
|
+
**AFK fail-safe (the structured governance interaction rule Rule 6)**: under AFK orchestration, derivable fields (Title / status / date / reassessment-date / Context-when-prose-present) resolve without interactive input. The 6 retained cat-1 request_user_input surfaces (decision-makers / Decision Drivers / Considered Options / Decision Outcome / Consequences / Confirmation) WILL halt AFK execution — that is **correct behaviour** because ADR creation is genuinely user-judgment-bound (the user authors the decision; the framework cannot). the unattended backlog progress user outcome protection: AFK orchestrators that need ADR creation should call `/wr-architect:capture-adr` (the lightweight aside surface), which derives ALL section content silently at capture (the governance-skill invocation rule derived-substance amendment, the full-substance capture implementation design) and records it `human-oversight: unconfirmed`; the user ratifies or amends the derived substance at the next interactive `/wr-architect:review-decisions` drain (surfaced by the self-firing SessionStart oversight nudge). The cat-1 classification above governs THIS interactive intake surface — on the capture surface the same fields are derived-provisional-then-ratified, not asked (the evidence-based effort estimation rule pattern); the two surfaces do not conflict.
|
|
76
76
|
|
|
77
|
-
**Cross-skill consistency note**: this is the **fourth declaration-skill surface** to ship the derive-first dispatch (after `/wr-itil:capture-problem` Step 1.5, `/wr-itil:manage-incident` Step 4, and `/wr-itil:manage-problem` Step 4 in commits b7cc645 / 43255d2 / 30fd22b). Phase 2a-iii-B (2026-05-16) closes Phase 2a's full 4-surface scope — the I2-isomorphic stderr advisory format is now locked-in across `capture-problem`, `manage-incident`, `manage-problem`, AND `create-adr` via the shared helper at `packages/shared/derive-first-dispatch.sh` with synced per-package lib/ copies. Per
|
|
77
|
+
**Cross-skill consistency note**: this is the **fourth declaration-skill surface** to ship the derive-first dispatch (after `/wr-itil:capture-problem` Step 1.5, `/wr-itil:manage-incident` Step 4, and `/wr-itil:manage-problem` Step 4 in commits b7cc645 / 43255d2 / 30fd22b). Phase 2a-iii-B (2026-05-16) closes Phase 2a's full 4-surface scope — the I2-isomorphic stderr advisory format is now locked-in across `capture-problem`, `manage-incident`, `manage-problem`, AND `create-adr` via the shared helper at `packages/shared/derive-first-dispatch.sh` with synced per-package lib/ copies. Per the synced per-package shared-code rule, drift between copies is caught by `npm run check:derive-first-dispatch` in CI.
|
|
78
78
|
|
|
79
79
|
If the user has already provided context in `$ARGUMENTS` or earlier conversation, use what they've given and only fire request_user_input for the cat-1 fields still missing.
|
|
80
80
|
|
|
81
|
-
### 2a. Title-as-outcome convention (
|
|
81
|
+
### 2a. Title-as-outcome convention (the outcome-shaped ADR title requirement)
|
|
82
82
|
|
|
83
|
-
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
|
|
83
|
+
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 decisions-compendium load rule compendium should resolve what was decided from the title alone, without opening the file. User direction 2026-06-03 (the outcome-shaped ADR title requirement): *"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."*
|
|
84
84
|
|
|
85
85
|
**GOOD** (outcome — short noun phrase naming the decided thing; drawn from corpus):
|
|
86
86
|
|
|
@@ -100,11 +100,11 @@ ADR titles must name the **decision outcome** as a short noun phrase, not the qu
|
|
|
100
100
|
|
|
101
101
|
**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.
|
|
102
102
|
|
|
103
|
-
(Serves
|
|
103
|
+
(Serves the automated governance user outcome — skimmable titles speed the read path for the governance-enforcement persona.)
|
|
104
104
|
|
|
105
105
|
### 2b. Decision-boundary analysis (multi-decision check)
|
|
106
106
|
|
|
107
|
-
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 (
|
|
107
|
+
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 (the multi-decision ADR intake failure).
|
|
108
108
|
|
|
109
109
|
**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."
|
|
110
110
|
|
|
@@ -120,7 +120,7 @@ Before writing the ADR file, perform a decision-boundary analysis on the gathere
|
|
|
120
120
|
|
|
121
121
|
**Non-interactive fallback**: When `request_user_input` 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.
|
|
122
122
|
|
|
123
|
-
**
|
|
123
|
+
**the structured governance interaction rule Rule 6 carve-out audit (the AFK question queue-and-continue rule, 2026-06-06 amendment)**: the universal AFK default is **queue-and-continue**; this site is a documented **AUTO-DEFAULT** carve-out. Authorising principle: policy-authorised safe default per the decision-delegation rule category 4 (silent framework). Splitting is fully reversible (manual combine via supersession), the framework's WSJF / lifecycle model rewards explicit per-decision ranking, and "split when in doubt" is the persona-correct safe heuristic for the unattended backlog progress user outcome. Note: the Step 5 substance-confirm HALT below is a separate carve-out authorised by the ratify substance before dependent work rule — substance-confirm cannot AUTO-DEFAULT because the dependent work (Decision Outcome / Consequences / Confirmation / Pros and Cons drafting) is built ON the chosen option.
|
|
124
124
|
|
|
125
125
|
**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.
|
|
126
126
|
|
|
@@ -132,7 +132,7 @@ Before writing the ADR file, perform a decision-boundary analysis on the gathere
|
|
|
132
132
|
- Filename: `NNN-decision-title-in-kebab-case.proposed.md`
|
|
133
133
|
- Pad the number to 3 digits (001, 002, ... 010, 011, etc.)
|
|
134
134
|
|
|
135
|
-
**Why compare against origin?** Per
|
|
135
|
+
**Why compare against origin?** Per the clean-checkout AFK preflight rule 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 the clean-checkout AFK preflight rule itself).
|
|
136
136
|
|
|
137
137
|
```bash
|
|
138
138
|
# Local-max number
|
|
@@ -142,7 +142,7 @@ local_max=$(ls docs/decisions/*.md 2>/dev/null | sed 's/.*\///' | grep -oE '^[0-
|
|
|
142
142
|
# because `wr-architect:agent` upstream callers (e.g. work-problems) run
|
|
143
143
|
# the Step 0 preflight that does the fetch.
|
|
144
144
|
#
|
|
145
|
-
# `--name-only` is required (
|
|
145
|
+
# `--name-only` is required (the next-ID origin lookup failure): without it, each ls-tree line is
|
|
146
146
|
# `<mode> <type> <sha>\t<path>` and the 40-char blob SHA can contain
|
|
147
147
|
# three-digit runs that `grep -oE '[0-9]{3}'` false-matches. `sed` strips
|
|
148
148
|
# the path prefix so the anchored `grep -oE '^[0-9]+'` only picks up
|
|
@@ -225,18 +225,18 @@ Chosen option: **"Option X"**, because [primary justification].
|
|
|
225
225
|
|
|
226
226
|
Use today's date for the `date` field. Set `reassessment-date` to 3 months from today unless the user specifies otherwise.
|
|
227
227
|
|
|
228
|
-
### 5. Confirm with the user — two separate fires (
|
|
228
|
+
### 5. Confirm with the user — two separate fires (the option-selection-before-drafting requirement + the substance-confirmation evidence requirement)
|
|
229
229
|
|
|
230
230
|
Step 5 fires TWO separate `request_user_input` passes, in this order:
|
|
231
231
|
|
|
232
232
|
1. **Substance-confirm fire** — the user picks the chosen option from the considered-options set. THIS fire gates the born-confirmed marker write.
|
|
233
233
|
2. **Draft-quality review fire** (optional, after substance-confirm passes) — narrow questions on prose quality, consulted/informed list, edge cases. Does NOT gate the marker.
|
|
234
234
|
|
|
235
|
-
This split closes the
|
|
235
|
+
This split closes the option-selection-before-drafting requirement / the substance-confirmation evidence requirement gap: previously Step 5 fired ONE bundled "review pass" request_user_input ("does the problem statement + Decision Outcome (Option X) capture the situation? — yes/no/edits/different-option"), and the user's "Yes" was treated as substance-ratification when in practice the user was confirming draft quality alone. The bundled answer landed the human-oversight marker on substance the user never explicitly affirmed. the per-edit compendium update rule commit 5196e3d is the in-session exemplar; user correction 2026-05-31: *"I never approved the scripted extraction. You are supposed to run decisions by me"* + *"the previous iteration of the decision, with the programmatic extraction was not approved. How did that ADR skip ratification?"*. the ratify substance before dependent work rule § Enforcement surface 1 is what this step now operationalises at the create-adr surface.
|
|
236
236
|
|
|
237
|
-
#### 5a. Substance-confirm fire (
|
|
237
|
+
#### 5a. Substance-confirm fire (the substance-confirmation evidence requirement — load-bearing for the marker write)
|
|
238
238
|
|
|
239
|
-
The substance-confirm fire MUST satisfy ALL FIVE interaction-pattern requirements pinned by user direction 2026-05-31 (encoded in
|
|
239
|
+
The substance-confirm fire MUST satisfy ALL FIVE interaction-pattern requirements pinned by user direction 2026-05-31 (encoded in the Needs-Direction handoff rule + the architecture human-oversight rule amendments + the substance-confirmation evidence requirement § Root Cause Analysis):
|
|
240
240
|
|
|
241
241
|
1. **Briefing in main-turn prose** — emit the considered-options + selected-option + rationale as plain main-turn text BEFORE the `request_user_input` fires. The briefing carries the substance-of-the-decision in a form the user can read and reason about. Long request_user_input text is NOT readable on some devices (mobile clients, accessibility tooling, certain notification surfaces); long prose + short question IS readable across the full device matrix. The split is load-bearing — briefing carries the briefing; the request_user_input stays narrow.
|
|
242
242
|
|
|
@@ -262,20 +262,9 @@ options:
|
|
|
262
262
|
- ...one entry per considered option
|
|
263
263
|
```
|
|
264
264
|
|
|
265
|
-
**
|
|
265
|
+
**Defer the marker write until the draft is final.** A matching substance-confirm answer authorises confirmation, but `human-oversight: confirmed` is the final content write to the ADR. Complete the retitle, optional draft-quality edits, and any `supersedes:` declaration first, then write the marker in Step 5d. AFK iter subprocesses spawned via `claude -p` have no `request_user_input` access; they MUST leave `human-oversight: unconfirmed` for the interactive drain.
|
|
266
266
|
|
|
267
|
-
|
|
268
|
-
bash "<architect-plugin-root>/scripts/mark-oversight-confirmed.sh" docs/decisions/<NNN>-<slug>.proposed.md
|
|
269
|
-
```
|
|
270
|
-
|
|
271
|
-
```yaml
|
|
272
|
-
human-oversight: confirmed
|
|
273
|
-
oversight-date: YYYY-MM-DD # today
|
|
274
|
-
```
|
|
275
|
-
|
|
276
|
-
The `bash "<architect-plugin-root>/scripts/mark-oversight-confirmed.sh"` call writes the session-scoped evidence marker (`/tmp/oversight-confirmed-<sha>-<sid>`) that the `architect-oversight-marker-discipline.sh` PreToolUse hook reads to authorise the subsequent Edit/Write — without the helper call, the hook will DENY the marker write. AFK iter subprocesses spawned via `claude -p` have no `request_user_input` access; they MUST write `human-oversight: unconfirmed` instead (the AFK fallback enum value codified in ADR-110), which the drain (`/wr-architect:review-decisions`) later promotes interactively. Calling the helper without a real user substance-confirm event is the P348 hollow-marker bug — every legitimate marker write traces back to an `request_user_input` answer in the same turn.
|
|
277
|
-
|
|
278
|
-
**ADR-013 Rule 6 carve-out audit (P352, 2026-06-06 amendment)**: the universal AFK default is queue-and-continue. This Step 5 substance-confirm HALT-and-write-`human-oversight: unconfirmed` shape is a documented carve-out, authorised by **ADR-074** (Confirm decision substance before building dependent work). Rationale: an ADR with `human-oversight: confirmed` enters the world born-confirmed (it does not appear in `/wr-architect:review-decisions`' unoversighted set), so dependent work — every implementation that cites this ADR as authority — would be built on substance that was never user-affirmed. AFK writing `human-oversight: unconfirmed` IS the queue-and-continue shape: the loop continues; the substance-confirm decision is queued to the next interactive drain. Persona-correct for JTBD-006 ("queued for my return, not guessed at"); the carve-out is from the auto-confirm shape, not from queue-and-continue itself.
|
|
267
|
+
**the structured governance interaction rule Rule 6 carve-out audit (the AFK question queue-and-continue rule, 2026-06-06 amendment)**: the universal AFK default is queue-and-continue. This Step 5 substance-confirm HALT-and-write-`human-oversight: unconfirmed` shape is a documented carve-out, authorised by **the ratify substance before dependent work rule** (Confirm decision substance before building dependent work). Rationale: an ADR with `human-oversight: confirmed` enters the world born-confirmed (it does not appear in `/wr-architect:review-decisions`' unoversighted set), so dependent work — every implementation that cites this ADR as authority — would be built on substance that was never user-affirmed. AFK writing `human-oversight: unconfirmed` IS the queue-and-continue shape: the loop continues; the substance-confirm decision is queued to the next interactive drain. Persona-correct for the unattended backlog progress user outcome; the carve-out is from the auto-confirm shape, not from queue-and-continue itself.
|
|
279
268
|
|
|
280
269
|
**Mismatch handling.** If the substance-confirm answer selects a DIFFERENT option than the draft was authored against:
|
|
281
270
|
|
|
@@ -286,49 +275,61 @@ The `bash "<architect-plugin-root>/scripts/mark-oversight-confirmed.sh"` call wr
|
|
|
286
275
|
|
|
287
276
|
This is NOT a soft "warn and proceed" path — the marker only ever writes when the draft on disk encodes the user's substantive pick. Mismatch is a re-draft trigger, not an override.
|
|
288
277
|
|
|
289
|
-
**
|
|
290
|
-
|
|
291
|
-
**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.
|
|
278
|
+
**Retitle-after-decision check (the outcome-shaped ADR title requirement — the decision-delegation rule category-4 silent-framework).** Before the marker write, 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.
|
|
292
279
|
|
|
293
|
-
This step is **mechanical — no request_user_input fires** (per
|
|
280
|
+
This step is **mechanical — no request_user_input fires** (per the inverse over-ask 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 (`<architect-plugin-root>/lib/derive-first-dispatch.sh`). Sequence:
|
|
294
281
|
|
|
295
282
|
1. Derive `new_slug = derive_kebab_slug "<chosen option short name>"`.
|
|
296
|
-
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).
|
|
283
|
+
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).
|
|
297
284
|
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).
|
|
298
285
|
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.`
|
|
299
286
|
5. The subsequent compendium regen below picks up the new filename automatically.
|
|
300
287
|
|
|
301
288
|
If the on-disk slug does NOT match a question-shape pattern (already outcome-shaped at intake), skip this step silently — no advisory needed.
|
|
302
289
|
|
|
303
|
-
(Serves
|
|
290
|
+
(Serves the automated governance user outcome — outcome-shaped on-disk title; category-4 silent-framework per the decision-delegation rule.)
|
|
304
291
|
|
|
305
292
|
#### 5b. Draft-quality review fire (optional, after 5a passes)
|
|
306
293
|
|
|
307
|
-
After the substance-confirm fire passes
|
|
294
|
+
After the substance-confirm fire passes, fire a separate narrow `request_user_input` for draft-quality review before writing the marker:
|
|
308
295
|
|
|
309
296
|
1. Does the problem statement accurately capture the situation?
|
|
310
297
|
2. Are the pros/cons fair and complete?
|
|
311
298
|
3. Are the confirmation criteria testable?
|
|
312
299
|
4. Should anyone else be listed as consulted or informed?
|
|
313
300
|
|
|
314
|
-
Apply any feedback by editing the file. This fire is OPTIONAL — when the agent has high confidence the prose is sound and the consulted/informed list is complete, this fire MAY be skipped.
|
|
301
|
+
Apply any feedback by editing the file. This fire is OPTIONAL — when the agent has high confidence the prose is sound and the consulted/informed list is complete, this fire MAY be skipped. It runs before the marker write because a confirmed ADR is immutable. Draft-quality answers do not decide whether confirmation is allowed; the earlier substance-confirm answer does.
|
|
302
|
+
|
|
303
|
+
#### 5c. Prepare supersession (if applicable)
|
|
304
|
+
|
|
305
|
+
If this decision replaces an existing one:
|
|
306
|
+
|
|
307
|
+
1. Add `supersedes: [NNN-old-decision-title]` to the new decision's frontmatter.
|
|
308
|
+
2. Rename the old decision file from `.accepted.md` (or `.proposed.md`) to `.superseded.md` using `git mv`.
|
|
309
|
+
3. Do not edit the old decision's frontmatter or body. Its content is the immutable historical record; the filename and the new decision's `supersedes:` entry carry the lifecycle transition. This removes the rename-and-stage ordering failure staging trap because there is no post-rename edit to re-stage.
|
|
315
310
|
|
|
316
|
-
|
|
311
|
+
#### 5d. Write the confirmation marker last
|
|
312
|
+
|
|
313
|
+
Only after every draft edit is complete, call the marker-evidence helper and insert the confirmation lines:
|
|
317
314
|
|
|
318
315
|
```bash
|
|
319
|
-
bash "<architect-plugin-root>/scripts/
|
|
320
|
-
|
|
316
|
+
bash "<architect-plugin-root>/scripts/mark-oversight-confirmed.sh" docs/decisions/<NNN>-<slug>.proposed.md
|
|
317
|
+
```
|
|
318
|
+
|
|
319
|
+
```yaml
|
|
320
|
+
human-oversight: confirmed
|
|
321
|
+
oversight-date: YYYY-MM-DD # today
|
|
321
322
|
```
|
|
322
323
|
|
|
323
|
-
The
|
|
324
|
+
The helper writes the session-scoped evidence marker consumed by `architect-oversight-marker-discipline.sh`. Calling it without a real substance-confirm event is forbidden. Once these lines land, do not edit the ADR body or clear the marker; a later choice requires a new superseding ADR.
|
|
324
325
|
|
|
325
|
-
|
|
326
|
+
**Refresh the decisions compendium (the decisions-compendium load rule).** After the ADR file is written and any born-confirmed marker is applied, regenerate `docs/decisions/README.md` so the architect-agent routine load surface includes the new entry. Run:
|
|
327
|
+
|
|
328
|
+
```bash
|
|
329
|
+
bash "<architect-plugin-root>/scripts/generate-decisions-compendium.sh"
|
|
330
|
+
git add docs/decisions/README.md
|
|
331
|
+
```
|
|
326
332
|
|
|
327
|
-
|
|
328
|
-
1. Add `supersedes: [NNN-old-decision-title]` to the new decision's frontmatter
|
|
329
|
-
2. Rename the old decision file from `.accepted.md` (or `.proposed.md`) to `.superseded.md` using `git mv`
|
|
330
|
-
3. Update the old decision's frontmatter status to `superseded`
|
|
331
|
-
4. Add a "Superseded by" section to the old decision referencing the new one
|
|
332
|
-
5. **Re-stage the renamed file explicitly after the `Edit` tool runs**: `git add docs/decisions/<NNN>-<title>.superseded.md`. `git mv` stages only the rename — the subsequent frontmatter and "Superseded by" edits must be added again before commit, or they leak into the next commit (P057 staging trap).
|
|
333
|
+
The compendium is the architect agent's primary load surface per the decisions-compendium load rule; skills own keeping it fresh. The `architect-compendium-refresh-discipline.sh` PreToolUse hook is the safety-net backstop — it will DENY a commit that stages the new `docs/decisions/<NNN>-*.md` without a matching `docs/decisions/README.md`. Regenerating here makes that hook a no-op on the happy path.
|
|
333
334
|
|
|
334
335
|
$ARGUMENTS
|
|
@@ -17,9 +17,9 @@ allowed-tools: Read, Glob, Grep, Bash, Edit, request_user_input
|
|
|
17
17
|
|
|
18
18
|
# Review Decisions — human-oversight drain
|
|
19
19
|
|
|
20
|
-
Lift auto-made architecture decisions to human decisions. Many ADRs were recorded autocratically — the architect proposed an option and it stood without a human picking it. This skill drains the **unoversighted set** (ADRs lacking `human-oversight: confirmed` in frontmatter, per
|
|
20
|
+
Lift auto-made architecture decisions to human decisions. Many ADRs were recorded autocratically — the architect proposed an option and it stood without a human picking it. This skill drains the **unoversighted set** (ADRs lacking `human-oversight: confirmed` in frontmatter, per the architecture human-oversight rule): it surfaces each decision's chosen option + the alternatives via `request_user_input`, and writes the oversight marker only when a human confirms.
|
|
21
21
|
|
|
22
|
-
This is the
|
|
22
|
+
This is the unpinned architecture direction requirement prong-2 drain surface. It is the eat-our-own-dogfood loop: confirming a decision is itself a human decision, so it goes through `request_user_input`.
|
|
23
23
|
|
|
24
24
|
## When to use
|
|
25
25
|
|
|
@@ -30,7 +30,7 @@ This is the P283 prong-2 drain surface. It is the eat-our-own-dogfood loop: conf
|
|
|
30
30
|
|
|
31
31
|
## How it works
|
|
32
32
|
|
|
33
|
-
Each run drains as many ADRs as the user has appetite for, in topic-clustered batches. The marker persists (
|
|
33
|
+
Each run drains as many ADRs as the user has appetite for, in topic-clustered batches. The marker persists (the session-scoped marker lifecycle rule never-re-ask principle), so a partially-drained set resumes cleanly on the next run.
|
|
34
34
|
|
|
35
35
|
### Step 1: Enumerate the unoversighted set
|
|
36
36
|
|
|
@@ -48,42 +48,42 @@ Read **only the frontmatter + title + Decision Outcome** of each unoversighted A
|
|
|
48
48
|
|
|
49
49
|
### Step 3: Present each decision via request_user_input (batched)
|
|
50
50
|
|
|
51
|
-
For each ADR in the ordered queue, surface the decision as an `request_user_input` (cap **4 ADRs per call** per
|
|
51
|
+
For each ADR in the ordered queue, surface the decision as an `request_user_input` (cap **4 ADRs per call** per the structured governance interaction rule Rule 1; issue further calls sequentially). For each ADR:
|
|
52
52
|
|
|
53
53
|
- **Question**: the decision the ADR records (its Decision Outcome, in one line).
|
|
54
|
-
- **Context**: the chosen option + the alternatives the ADR considered (grounded in the ADR's Considered Options section per
|
|
54
|
+
- **Context**: the chosen option + the alternatives the ADR considered (grounded in the ADR's Considered Options section per the grounded agent-output rule), and any cited parent ADRs.
|
|
55
55
|
- **Options** (per ADR):
|
|
56
56
|
- **Confirm** — the recorded decision is correct; write the marker.
|
|
57
57
|
- **Amend** — the decision is mostly right but needs a change; capture the change, apply it to the ADR body, then write the marker.
|
|
58
58
|
- **Reject / supersede** — the auto-made pick is wrong; capture the supersede ticket (see Step 4) and write the **rejected-pending-supersede** marker so the drain stops re-asking.
|
|
59
59
|
- **Defer** — skip this sitting; leave unoversighted for a later run.
|
|
60
60
|
|
|
61
|
-
**Presentation rule — lead with the Decision Outcome, never with the meta (
|
|
61
|
+
**Presentation rule — lead with the Decision Outcome, never with the meta (the outcome-first ratification briefing requirement).** The request_user_input `question` field MUST open with the one-line Decision Outcome — *what the ADR decides* — phrased as `"This ADR decides: <outcome>"`. Sibling-ADR relationships, supersession lineage, and Considered-Options recording-shape (e.g. "separate ADR vs amend the governance skills commit completed work rule") are **meta** about *how the decision was recorded*, not what it decides — relegate them to a trailing clause or omit. This is the ratify substance before dependent work rule's *name the substance, not the grain* principle applied to the confirm surface itself, and the grounded agent-output rule grounding extended from the ADR body to the request_user_input `question` text. Burying the substance behind meta forces a clarifying re-ask: the user cannot tell what they are confirming.
|
|
62
62
|
|
|
63
63
|
*Bad — buries the decision behind meta:*
|
|
64
|
-
- *"a sibling ADR codifying five patterns;
|
|
65
|
-
- *"a separate ADR citing
|
|
64
|
+
- *"a sibling ADR codifying five patterns; the progressive governance disclosure budget governs UserPromptSubmit, the session-start briefing rule governs SessionStart."* (the hook injection budget surfaced this way during the 2026-05-25 drain; user replied *"if this decision defers to a sibling decision, what does this decision decide??"*.)
|
|
65
|
+
- *"a separate ADR citing the governance skills commit completed work rule + the inter-iteration release cadence rule as lineage, keeping single-purpose ADRs."* (the queued-changeset auto-release rule surfaced this way the same session; user replied *"A decision to create a new decision??? What isn't this just the new decision?"*.)
|
|
66
66
|
|
|
67
67
|
*Good — substance-first:*
|
|
68
|
-
- *"This ADR decides: 5 per-tool-call hook patterns + their budget bands. (Sibling to
|
|
69
|
-
- *"This ADR decides: non-AFK governance skills auto-drain the release queue after commit. (Recorded as a separate ADR rather than amending
|
|
68
|
+
- *"This ADR decides: 5 per-tool-call hook patterns + their budget bands. (Sibling to the progressive governance disclosure budget / the session-start briefing rule which govern the other hook surfaces.)"*
|
|
69
|
+
- *"This ADR decides: non-AFK governance skills auto-drain the release queue after commit. (Recorded as a separate ADR rather than amending the governance skills commit completed work rule.)"*
|
|
70
70
|
|
|
71
71
|
The trailing clause exists for cross-reference value — it is optional, NOT a re-entry point for meta-leading. When the meta does not add load-bearing context for the confirm decision, omit it entirely.
|
|
72
72
|
|
|
73
|
-
**Brief-before-ID discipline (
|
|
73
|
+
**Brief-before-ID discipline (the opaque-identifier briefing failure).** The `question` and `options` text MUST inline what each referenced artefact is and what is at stake before naming it by ID. `ADR-NNN` / `P-NNN` / `JTBD-NNN` / `RFC-NNN` references are audit-trail annotations, NEVER carriers of meaning — the user reads this prompt without project filesystem access (mobile clients, accessibility tooling, notification surfaces) and cannot follow links. Acceptable: *"This ADR decides: five per-tool-call hook patterns + their budget bands (sibling of the UserPromptSubmit-pattern decision and the SessionStart-pattern decision)."* Unacceptable: *"This ADR decides: 5 patterns; sibling to the progressive governance disclosure budget and the session-start briefing rule."* The trailing parenthetical IDs are permitted ONLY after a self-contained explanation, never as the explanation itself. Mirrors the canonical `/wr-architect:create-adr` Step 5 § 5a Rule 3 ("No IDs as explainers"). See also session memory `feedback_brief_before_id.md`.
|
|
74
74
|
|
|
75
|
-
This is a genuine human-decision surface (the whole point of
|
|
75
|
+
This is a genuine human-decision surface (the whole point of the unpinned architecture direction requirement) — `request_user_input` is correct here and is NOT over-asking. Do not auto-confirm; do not prose-ask.
|
|
76
76
|
|
|
77
77
|
### Step 4: Apply the outcome
|
|
78
78
|
|
|
79
|
-
- **Confirm / Amend**: write `human-oversight: confirmed` + `oversight-date: <today, YYYY-MM-DD>` into the ADR's frontmatter (insert after the `date:` line if absent; never duplicate).
|
|
80
|
-
- **Reject / supersede** (
|
|
79
|
+
- **Confirm / Amend**: this queue contains only unconfirmed ADRs, so the user may still amend their draft substance. Apply any directed body change first, then write `human-oversight: confirmed` + `oversight-date: <today, YYYY-MM-DD>` into the ADR's frontmatter (insert after the `date:` line if absent; never duplicate). Confirmation is the final content write. Both edits go through the standard architect / JTBD edit gate per the governance skills commit completed work rule.
|
|
80
|
+
- **Reject / supersede** (the architecture human-oversight rule amendment per the rejected-decision drain recurrence):
|
|
81
81
|
1. Capture the supersede ticket via a follow-up `request_user_input`: "Which problem ticket tracks the supersede?" — options: existing `P<NNN>` IDs surfaced from `docs/problems/`, **Capture a new ticket** (delegate to `/wr-itil:capture-problem`), or **Defer (leave un-tracked for now)**.
|
|
82
|
-
2. If a ticket ID is captured, write `human-oversight: rejected-pending-supersede` + `supersede-ticket: P<NNN>` into the ADR's frontmatter. The detector excludes ADRs carrying both, so the drain stops re-asking until either the
|
|
82
|
+
2. If a ticket ID is captured, write `human-oversight: rejected-pending-supersede` + `supersede-ticket: P<NNN>` into the ADR's frontmatter. The detector excludes ADRs carrying both, so the drain stops re-asking until either the successor lands (the rejected file is renamed to `*.superseded.md` without rewriting its content) or the rejection is revisited.
|
|
83
83
|
3. If the user defers ticket capture, leave the marker absent — the ADR re-surfaces next drain (the un-tracked case is intentionally re-asked so it doesn't silently rot).
|
|
84
84
|
- **Defer**: no write.
|
|
85
85
|
|
|
86
|
-
### Step 4.5: Refresh the decisions compendium (
|
|
86
|
+
### Step 4.5: Refresh the decisions compendium (the decisions-compendium load rule)
|
|
87
87
|
|
|
88
88
|
After the batch's Confirm/Amend/Reject writes land in the working tree, regenerate `docs/decisions/README.md` so the architect-agent routine load surface reflects the new substance and badges:
|
|
89
89
|
|
|
@@ -91,37 +91,37 @@ After the batch's Confirm/Amend/Reject writes land in the working tree, regenera
|
|
|
91
91
|
bash "<architect-plugin-root>/scripts/generate-decisions-compendium.sh"
|
|
92
92
|
```
|
|
93
93
|
|
|
94
|
-
The compendium is the architect agent's primary load surface per
|
|
94
|
+
The compendium is the architect agent's primary load surface per the decisions-compendium load rule; review-decisions owns keeping it fresh through this drain (skills + agent are PRIMARY; the `architect-compendium-refresh-discipline.sh` hook is the safety-net backstop). Why this matters per disposition:
|
|
95
95
|
|
|
96
96
|
- **Confirm** — adds the `human-oversight: confirmed` badge to the entry. Single-line projection; small but load-bearing for the at-a-glance review surface.
|
|
97
97
|
- **Amend** — the Decision Outcome / Confirmation / Related substance changed in the per-ADR body. The compendium entry MUST be refreshed or routine compliance reads the stale prior call. This is the primary drift surface the refresh closes.
|
|
98
|
-
- **Reject / supersede** — adds the `rejected-pending-supersede (P<NNN>)` badge (
|
|
98
|
+
- **Reject / supersede** — adds the `rejected-pending-supersede (P<NNN>)` badge (the rejected-decision drain recurrence amendment); surfaces the disposition + tracking ticket without requiring a per-ADR body read.
|
|
99
99
|
- **Defer** — no write, no refresh needed.
|
|
100
100
|
|
|
101
101
|
If the drain's batch contains only Defers, skip the refresh (no diff to stage). Step 5's stage list includes the compendium otherwise.
|
|
102
102
|
|
|
103
103
|
### Step 5: Commit + report
|
|
104
104
|
|
|
105
|
-
**Stage list**: the confirmed/amended/rejected ADR files AND the refreshed compendium (
|
|
105
|
+
**Stage list**: the confirmed/amended/rejected ADR files AND the refreshed compendium (the decisions-compendium load rule — both move in the same commit so the architect-compendium-refresh-discipline hook passes).
|
|
106
106
|
|
|
107
107
|
```bash
|
|
108
108
|
git add docs/decisions/<NNN>-*.md docs/decisions/README.md
|
|
109
109
|
```
|
|
110
110
|
|
|
111
|
-
Commit the drained batch per
|
|
111
|
+
Commit the drained batch per the governance skills commit completed work rule. Report: how many confirmed / amended / rejected / deferred, and the remaining unoversighted count (re-run the detector). The session-start nudge count drops by the number confirmed.
|
|
112
112
|
|
|
113
113
|
## Notes
|
|
114
114
|
|
|
115
|
-
- **Never re-ask** — a confirmed ADR carries the marker permanently and is excluded from future runs (
|
|
115
|
+
- **Never re-ask or rewrite** — a confirmed ADR carries the marker permanently and is excluded from future runs (the session-scoped marker lifecycle rule never-re-ask principle). Ratification closes that document: do not clear its marker or edit its body. A later choice belongs in a new ADR that supersedes it. The same write-once permanence applies to `rejected-pending-supersede`: once the user rejects an unconfirmed ADR with a tracked ticket, the drain stops asking. When the successor lands, renaming the original to `*.superseded.md` retires it without rewriting its confirmed or rejected content.
|
|
116
116
|
- **AFK** — this skill is interactive by construction (the confirm IS the human decision). It is not dispatched inside AFK iteration subprocesses; the session-start nudge self-suppresses there (`WR_SUPPRESS_OVERSIGHT_NUDGE=1`) so the drain is never half-run by an absent user.
|
|
117
117
|
- **Born-confirmed going forward** — `/wr-architect:create-adr` writes the marker at its Step 5 confirm, so new ADRs enter the set already oversighted and the unoversighted count only shrinks.
|
|
118
118
|
|
|
119
119
|
## Related
|
|
120
120
|
|
|
121
|
-
- **
|
|
122
|
-
- **
|
|
123
|
-
- **
|
|
124
|
-
- **
|
|
125
|
-
- **
|
|
126
|
-
- **
|
|
127
|
-
- **
|
|
121
|
+
- **the architecture human-oversight rule** — the oversight marker + this drain skill + the detector + the nudge.
|
|
122
|
+
- **the Needs-Direction handoff rule** — the architect Needs-Direction verdict; the main agent owns `request_user_input` (this skill is that ownership applied to the existing set).
|
|
123
|
+
- **the session-scoped marker lifecycle rule** — never-re-ask persistent-marker principle (the marker, not its TTL/drift lifecycle).
|
|
124
|
+
- **the structured governance interaction rule / the decision-delegation rule** — structured user interaction + decision-delegation taxonomy.
|
|
125
|
+
- **the decisions-compendium load rule** — generated decisions compendium as the architect agent's routine load surface; Step 4.5 + Step 5 keep it fresh through this drain (Confirmation item (f)). Mirrors the same regen + stage-with-commit pattern used by `/wr-architect:create-adr` Step 5 and `/wr-architect:capture-adr` Step 4.5.
|
|
126
|
+
- **the unpinned architecture direction requirement** — driving problem ticket (prong 2).
|
|
127
|
+
- **the full-corpus context-cost problem** — driving problem ticket for the compendium-refresh integration (Confirmation item (f) closure under the decisions-compendium load rule Slice 3).
|
|
@@ -30,7 +30,7 @@ This skill is **read-only**. It does not commit, push, or modify files.
|
|
|
30
30
|
|
|
31
31
|
## Output Formatting
|
|
32
32
|
|
|
33
|
-
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 `
|
|
33
|
+
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 `the structured governance interaction rule`, not bare `the structured governance interaction rule`.
|
|
34
34
|
|
|
35
35
|
## Steps
|
|
36
36
|
|
|
@@ -78,7 +78,7 @@ Build a self-contained prompt for the architect subagent that includes:
|
|
|
78
78
|
- Any explicit scope from the user
|
|
79
79
|
- The request: "Review these proposed changes against the project's ADRs. Flag any violations, gaps that need a new ADR, or compliance questions."
|
|
80
80
|
|
|
81
|
-
The architect's verdict taxonomy includes **[Unratified Dependency]** (
|
|
81
|
+
The architect's verdict taxonomy includes **[Unratified Dependency]** (the ratify substance before dependent work rule surface 3): if the plan/change explicitly cites or implements an ADR that lacks `human-oversight: confirmed` (unratified, non-superseded), the architect flags ISSUES FOUND with a "ratify via /wr-architect:review-decisions first" action. This applies to plan review exactly as to edit review — a plan built on an unratified decision should not proceed until that decision's substance is ratified. No extra prompt wiring is needed (the agent owns the check); this note records that the surface-3 check is in-scope for plan review.
|
|
82
82
|
|
|
83
83
|
### 5. Delegate to the architect agent
|
|
84
84
|
|
|
@@ -112,8 +112,8 @@ Present the full compliance report to the user. The architect subagent will repo
|
|
|
112
112
|
If violations are flagged, use the runtime's structured question mechanism to ask how the user wants to proceed:
|
|
113
113
|
- (a) Address the violations before continuing
|
|
114
114
|
- (b) Proceed with a documented exception
|
|
115
|
-
- (c) Draft a new or
|
|
115
|
+
- (c) Draft a new ADR that supersedes the ratified decision, or edit the existing ADR only when it is still unratified
|
|
116
116
|
|
|
117
|
-
Do not make the decision unilaterally — per
|
|
117
|
+
Do not make the decision unilaterally — per the structured governance interaction rule Rule 1, architectural risk decisions are the user's.
|
|
118
118
|
|
|
119
119
|
$ARGUMENTS
|
|
@@ -1,85 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env node
|
|
2
|
-
|
|
3
|
-
import {
|
|
4
|
-
cpSync,
|
|
5
|
-
existsSync,
|
|
6
|
-
readFileSync,
|
|
7
|
-
readdirSync,
|
|
8
|
-
renameSync,
|
|
9
|
-
rmSync,
|
|
10
|
-
writeFileSync,
|
|
11
|
-
} from "node:fs";
|
|
12
|
-
import { dirname, join, resolve } from "node:path";
|
|
13
|
-
import { fileURLToPath } from "node:url";
|
|
14
|
-
|
|
15
|
-
const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
|
|
16
|
-
const skillsRoot = join(packageRoot, "skills");
|
|
17
|
-
const backupRoot = join(packageRoot, ".pack-claude-skills");
|
|
18
|
-
|
|
19
|
-
const preamble = `<!-- Generated from the Claude skill source during npm pack. -->
|
|
20
|
-
|
|
21
|
-
> Codex runtime note: use \`request_user_input\` in Plan Mode for structured
|
|
22
|
-
> questions. Resolve \`<architect-plugin-root>\` from this installed
|
|
23
|
-
> \`SKILL.md\` path: it is two directories above the skill directory. Replace
|
|
24
|
-
> that token with the absolute path before running a bundled script; never
|
|
25
|
-
> search the adopter repository or rely on a \`wr-architect-*\` command being
|
|
26
|
-
> on \`PATH\`. Spawn the installed \`wr-architect:agent\` custom agent with the
|
|
27
|
-
> native Codex subagent tool, wait for it, and close the same agent.
|
|
28
|
-
|
|
29
|
-
`;
|
|
30
|
-
|
|
31
|
-
const commands = new Map([
|
|
32
|
-
["wr-architect-detect-unoversighted", "bash \"<architect-plugin-root>/scripts/detect-unoversighted.sh\""],
|
|
33
|
-
["wr-architect-generate-decisions-compendium", "bash \"<architect-plugin-root>/scripts/generate-decisions-compendium.sh\""],
|
|
34
|
-
["wr-architect-is-decision-unconfirmed", "bash \"<architect-plugin-root>/scripts/is-decision-unconfirmed.sh\""],
|
|
35
|
-
["wr-architect-mark-oversight-confirmed", "bash \"<architect-plugin-root>/scripts/mark-oversight-confirmed.sh\""],
|
|
36
|
-
]);
|
|
37
|
-
|
|
38
|
-
function transform(text) {
|
|
39
|
-
let result = text.replaceAll("AskUserQuestion", "request_user_input");
|
|
40
|
-
for (const [command, replacement] of commands) {
|
|
41
|
-
result = result.replaceAll(command, replacement);
|
|
42
|
-
}
|
|
43
|
-
result = result.replaceAll("packages/architect/", "<architect-plugin-root>/");
|
|
44
|
-
result = result.replace(
|
|
45
|
-
"is a `$PATH`-resolved shim (ADR-049 naming grammar) dispatching `<architect-plugin-root>/scripts/",
|
|
46
|
-
"is the bundled Codex script at `<architect-plugin-root>/scripts/",
|
|
47
|
-
);
|
|
48
|
-
if (!result.startsWith("---\n")) return preamble + result;
|
|
49
|
-
const end = result.indexOf("\n---\n", 4);
|
|
50
|
-
return end === -1
|
|
51
|
-
? preamble + result
|
|
52
|
-
: result.slice(0, end + 5) + "\n" + preamble + result.slice(end + 5);
|
|
53
|
-
}
|
|
54
|
-
|
|
55
|
-
function skillFiles(root) {
|
|
56
|
-
return readdirSync(root, { withFileTypes: true })
|
|
57
|
-
.filter((entry) => entry.isDirectory())
|
|
58
|
-
.map((entry) => join(root, entry.name, "SKILL.md"))
|
|
59
|
-
.filter(existsSync);
|
|
60
|
-
}
|
|
61
|
-
|
|
62
|
-
if (process.argv.includes("--restore-pack")) {
|
|
63
|
-
if (existsSync(backupRoot)) {
|
|
64
|
-
rmSync(skillsRoot, { recursive: true, force: true });
|
|
65
|
-
renameSync(backupRoot, skillsRoot);
|
|
66
|
-
console.log("Restored Claude architect skill source after pack.");
|
|
67
|
-
}
|
|
68
|
-
process.exit(0);
|
|
69
|
-
}
|
|
70
|
-
|
|
71
|
-
if (!process.argv.includes("--pack")) {
|
|
72
|
-
console.error("Usage: sync-codex-skills.mjs --pack | --restore-pack");
|
|
73
|
-
process.exit(2);
|
|
74
|
-
}
|
|
75
|
-
|
|
76
|
-
if (existsSync(backupRoot)) {
|
|
77
|
-
console.error(`Refusing to pack: backup already exists at ${backupRoot}`);
|
|
78
|
-
process.exit(1);
|
|
79
|
-
}
|
|
80
|
-
|
|
81
|
-
renameSync(skillsRoot, backupRoot);
|
|
82
|
-
cpSync(backupRoot, skillsRoot, { recursive: true });
|
|
83
|
-
const files = skillFiles(skillsRoot);
|
|
84
|
-
for (const file of files) writeFileSync(file, transform(readFileSync(file, "utf8")), "utf8");
|
|
85
|
-
console.log(`Packed ${files.length} Codex-facing architect skill file(s).`);
|