@windyroad/itil 0.35.10 → 0.35.11-preview.403

package/.claude-plugin/plugin.json

@@ -484,5 +484,5 @@
     }
   },
   "name": "wr-itil",
-  "version": "0.35.10"
+  "version": "0.35.11"
 }

package/hooks/lib/readme-refresh-detect.sh

@@ -43,15 +43,18 @@
 #     launching `claude` — inline-prefix syntax (`VAR=1 git commit ...`)
 #     does NOT propagate from a Bash subshell to PreToolUse hooks (P173).
 #   - Registered `RISK_BYPASS: <token>` commit-message trailer (P265) →
-#     return 0 (allow). Narrow allow-list (currently only
-#     `adr-031-migration`, the standalone ADR-031 layout-migration
-#     commit, which is a rename-only change that legitimately stages no
-#     README refresh). The trailer is read from the live `git commit`
-#     command string at PreToolUse time (the commit message is not yet
-#     written), matching the sibling `risk-score-commit-gate.sh`
-#     recognition (P170 T11) so one logical migration commit clears both
-#     gates. Registry of record: ADR-014 commit-message bypass-token
-#     table.
+#     return 0 (allow). Narrow allow-list: `adr-031-migration` (the
+#     standalone ADR-031 layout-migration commit — a rename-only change
+#     that legitimately stages no README refresh; also clears
+#     risk-score-commit-gate.sh) and `capture-deferred-readme` (the
+#     /wr-itil:capture-problem Step 6 commit, whose README refresh is
+#     deferred to /wr-itil:review-problems per ADR-032 — P262; this
+#     token clears THIS gate only, not the risk-score gate). The trailer
+#     is read from the live `git commit` command string at PreToolUse
+#     time (the commit message is not yet written), matching the sibling
+#     `risk-score-commit-gate.sh` recognition (P170 T11) for the shared
+#     `adr-031-migration` token. Registry of record: ADR-014
+#     commit-message bypass-token table.
 #
 # Narrative-only short-circuit (P230):
 #   - When all staged ticket edits are purely narrative — no
@@ -129,7 +132,21 @@
 #     risk-score-commit-gate.sh (P170 T11); both gates recognise it via
 #     the identical grep below so one logical migration commit clears
 #     both. Registry of record: ADR-014 commit-message bypass-token table.
-_README_REFRESH_BYPASS_TRAILERS=("adr-031-migration")
+#   capture-deferred-readme — the lightweight /wr-itil:capture-problem
+#     Step 6 commit (subject `docs(problems): capture P<NNN> ...`). Per
+#     ADR-032 the capture variant DEFERS the README refresh to the next
+#     /wr-itil:review-problems (capture-time speed is the load-bearing
+#     distinction from manage-problem's full-intake path), so the capture
+#     commit legitimately stages only the new ticket file. Without this
+#     token the P165 gate's new-ticket-is-ranking-bearing rule denied
+#     every capture commit (P262 — observed 4×/session). UNLIKE
+#     adr-031-migration this token clears the P165 README-refresh gate
+#     ONLY — it is intentionally NOT registered in
+#     risk-score-commit-gate.sh (a capture commit is real work and must
+#     be risk-scored normally; risk-score-commit-gate.sh hard-greps only
+#     `adr-031-migration`). Registry of record: ADR-014 commit-message
+#     bypass-token table (which documents the README-gate-only asymmetry).
+_README_REFRESH_BYPASS_TRAILERS=("adr-031-migration" "capture-deferred-readme")
 
 # Returns 0 if the given `git commit` command string carries a
 # registered RISK_BYPASS trailer from the allow-list above. The grep

package/hooks/test/itil-readme-refresh-discipline.bats

@@ -581,3 +581,62 @@ EOF
   [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
   [ "${#output}" -eq 0 ]
 }
+
+# --- P262: capture-deferred-readme RISK_BYPASS trailer allow-list bypass ---
+#
+# /wr-itil:capture-problem SKILL.md Step 6 deliberately stages ONLY the new
+# ticket file and NOT docs/problems/README.md — the deferred-README-refresh
+# contract is the load-bearing capture-time-speed distinction from
+# /wr-itil:manage-problem (ADR-032). The P165 gate treats any new ticket
+# file (status A) as ranking-bearing, so a bare capture commit was denied
+# 4×/session. Architect verdict (P262): register a reason-named token
+# `capture-deferred-readme` into the same P265 allow-list mechanism; the
+# capture commit carries `RISK_BYPASS: capture-deferred-readme` in its
+# message body. The carve-out is scoped to the TOKEN, not the commit
+# subject — a `docs(problems): capture` subject WITHOUT the trailer still
+# denies (proves the bypass cannot be self-claimed by message prose, and
+# manage-problem's full-intake `docs(problems): open` path still enforces
+# the refresh).
+
+@test "P262 allow: capture commit with RISK_BYPASS: capture-deferred-readme trailer → allow silently" {
+  echo "# Problem 999" > docs/problems/open/999-capture.md
+  git add docs/problems/open/999-capture.md
+  run run_bash_hook "git commit -m 'docs(problems): capture P999 some-thing' -m 'RISK_BYPASS: capture-deferred-readme'"
+  [ "$status" -eq 0 ]
+  [[ "$output" != *"\"permissionDecision\": \"deny\""* ]]
+  # Bypass is an allow path — silent per ADR-045 Pattern 1.
+  [ "${#output}" -eq 0 ]
+}
+
+@test "P262 deny: capture-subject commit WITHOUT the trailer still denies (token-scoped, not subject-scoped)" {
+  echo "# Problem 999" > docs/problems/open/999-capture.md
+  git add docs/problems/open/999-capture.md
+  run run_bash_hook "git commit -m 'docs(problems): capture P999 some-thing'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+  [[ "$output" == *"P165"* ]]
+}
+
+@test "P262 deny: subject merely contains the word capture but no registered trailer still denies" {
+  echo "# Problem 999" > docs/problems/open/999-x.md
+  git add docs/problems/open/999-x.md
+  run run_bash_hook "git commit -m 'fix(itil): handle the capture edge case'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "P262 deny: docs(problems): open (manage-problem full intake) without README still denies" {
+  echo "# Problem 999" > docs/problems/open/999-x.md
+  git add docs/problems/open/999-x.md
+  run run_bash_hook "git commit -m 'docs(problems): open P999 some-thing'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}
+
+@test "P262 deny: unregistered capture-ish token does NOT bypass (allow-list scope)" {
+  echo "# Problem 999" > docs/problems/open/999-x.md
+  git add docs/problems/open/999-x.md
+  run run_bash_hook "git commit -m 'docs(problems): capture P999 x' -m 'RISK_BYPASS: capture-something-else'"
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"\"permissionDecision\": \"deny\""* ]]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "0.35.10",
+  "version": "0.35.11-preview.403",
   "description": "ITIL-aligned IT service management for Claude Code (problem, and future incident/change skills)",
   "bin": {
     "windyroad-itil": "./bin/install.mjs"

package/skills/capture-problem/SKILL.md

@@ -257,14 +257,24 @@ Satisfy the commit gate per ADR-014 — same two-path pattern as manage-problem
 - **Primary**: delegate to subagent type `wr-risk-scorer:pipeline` via the Agent tool.
 - **Fallback**: invoke `/wr-risk-scorer:assess-release` via the Skill tool when the subagent type is unavailable in the current tool surface.
 
-Commit message:
+Commit message — the body MUST carry the `RISK_BYPASS: capture-deferred-readme` trailer:
 
 ```
 docs(problems): capture P<NNN> <title>
+
+RISK_BYPASS: capture-deferred-readme
 ```
 
 The `capture` verb in the message is the audit signal that this ticket landed via the lightweight aside path (vs. `open` for manage-problem's full intake).
 
+**Why the trailer (P262)**: the P165 README-refresh-discipline hook (`packages/itil/hooks/itil-readme-refresh-discipline.sh`) treats any newly-staged ticket file as ranking-bearing and DENIES a `git commit` that does not also stage `docs/problems/README.md`. That enforcement is correct for `/wr-itil:manage-problem`'s full-intake path (P094 refresh-on-create) but conflicts with this skill's deliberate deferred-README-refresh contract. The `RISK_BYPASS: capture-deferred-readme` trailer is a registered allow-list token (P265 mechanism; registry of record is the ADR-014 commit-message bypass-token table) that clears the **README-refresh gate ONLY** — the commit is still risk-scored normally (`risk-score-commit-gate.sh` does not recognise this token). Emit the trailer via a second `-m` paragraph so the literal token appears in the `git commit` command string the PreToolUse hook inspects:
+
+```bash
+git commit -m "docs(problems): capture P<NNN> <title>" -m "RISK_BYPASS: capture-deferred-readme"
+```
+
+Do NOT drop the trailer and stage the README instead — that would silently abandon the deferred-README-refresh contract (the capture-time-speed distinction this skill exists to provide per ADR-032). The README is reconciled at the next `/wr-itil:review-problems` per Step 7's trailing pointer.
+
 ### 7. Report
 
 After the commit, report:
@@ -297,6 +307,8 @@ The two skills share the `/tmp/manage-problem-grep-${SESSION_ID}` create-gate ma
 - **P014** (`docs/problems/014-aside-invocation-for-governance-skills.open.md`) — parent / master tracker.
 - **P078** — capture-on-correction OFFER pattern; depends on capture-problem shipping.
 - **P119** — manage-problem create-gate hook; capture-problem composes with the same marker.
+- **P262** — the P165 README-refresh-discipline hook conflicted with this skill's deferred-README-refresh contract (Step 6 "do NOT stage README" was denied by the hook on every capture commit). Resolved by the `RISK_BYPASS: capture-deferred-readme` allow-list token (Step 6 trailer above); clears the README-refresh gate only, not the risk-score gate.
+- **P265** — the RISK_BYPASS-trailer allow-list mechanism in `readme-refresh-detect.sh` that P262's `capture-deferred-readme` token registers into.
 - **P170** (`docs/problems/170-...open.md`) — RFC framework driver; Slice 4 B7.T3 / item 8c authored the type-classification prompt at Step 1.5.
 - **P176** — agent-side I2 (no type-branching) coverage gap on the SKILL.md surface (this file's surface); descendant of P012 master harness ticket. The Step 1.5 I2 invariant guard is enforced by audit-trailed prose here per ADR-052 § Surface 2 escape-hatch contract; behavioural enforcement awaits the master harness.
 - **ADR-032** (`docs/decisions/032-governance-skill-invocation-patterns.proposed.md`) — foreground-lightweight-capture variant amendment.