@windyroad/itil 1.2.0 → 2.0.0-preview.1111

package/scripts/plugin-maturity-populate.sh

@@ -1,17 +1,17 @@
 #!/usr/bin/env bash
 # packages/itil/scripts/plugin-maturity-populate.sh
 #
-# Phase 3a (P087) plugin-maturity population script.
+# Phase 3a (problem-087-no-maturity-battle-hardening-signal-on-plugins-skills-agents-or-hooks-readmes-don-t-tell-users-which-features-are-stable-vs-experimental-problem) plugin-maturity population script.
 #
 # Reads two Phase 2 NDJSON streams — `wr-itil-skill-invocations` output
 # (transcript-axis) + `wr-itil-plugin-exercise-index` output (git-axis) —
-# applies ADR-053 §promotion criteria + §Bootstrapping clause, and writes
+# applies windyroad-plugin-skill-agent-hook-maturity-taxonomy-architecture-rule §promotion criteria + §Bootstrapping clause, and writes
 # the `maturity:` field per surface and per plugin root into each
 # `packages/<plugin>/.claude-plugin/plugin.json`. Idempotent: re-running
 # with unchanged inputs and a pinned `--now=` produces byte-identical
 # plugin.json output.
 #
-# Plugin.json schema extension (ADR-063 §plugin.json field schema):
+# Plugin.json schema extension (windyroad-plugin-maturity-presentation-layer-plugin-json-schema-prose-woven-readme-badge-in-suite-wr-itil-plugin-maturity-list-display-shim-architecture-rule §plugin.json field schema):
 #   {
 #     "name": "wr-<plugin>",
 #     "version": "...",
@@ -56,7 +56,7 @@
 # (`packages/<bare-name>/`) and accepts bare-form NDJSON input — no
 # plugin.json `name`-matching required.
 #
-# Bootstrapping clause (ADR-053 §Bootstrapping clause):
+# Bootstrapping clause (windyroad-plugin-skill-agent-hook-maturity-taxonomy-architecture-rule §Bootstrapping clause):
 #   Active iff `max(days_shipped across plugins) < 60`. Sunset auto-
 #   derives from the data (architect §D — no hard-coded calendar date).
 #   Under bootstrapping: default = Experimental; provisional Alpha iff
@@ -64,7 +64,7 @@
 #   stay Experimental during bootstrapping — provisional-Alpha rule
 #   requires a numeric invocation count.
 #
-# Steady-state thresholds (ADR-053 §promotion criteria, post-sunset):
+# Steady-state thresholds (windyroad-plugin-skill-agent-hook-maturity-taxonomy-architecture-rule §promotion criteria, post-sunset):
 #   Experimental: days <14 OR invocations <10 OR tickets <3
 #   Alpha:        days 14–60 AND inv 10–100 AND tickets 3–10
 #   Beta:         days ≥60 AND inv ≥100 AND tickets ≥10 AND breaking ≥30
@@ -72,11 +72,11 @@
 #   Stable:       days ≥180 AND inv ≥1000 AND breaking ≥90 (or null)
 #   Deprecated:   author-declared; preserved across re-runs.
 #
-# ADR-044 silent-framework carve-out (scope-limited per ADR-063 §scope):
+# decision-delegation-contract-when-agents-act-on-the-framework-vs-ask-the-user-architecture-rule silent-framework carve-out (scope-limited per windyroad-plugin-maturity-presentation-layer-plugin-json-schema-prose-woven-readme-badge-in-suite-wr-itil-plugin-maturity-list-display-shim-architecture-rule §scope):
 #   Band recomputation is mechanical, policy-resolved. No `AskUserQuestion`
 #   per band recompute. The carve-out does NOT cover author-declared
 #   Deprecated assignment, `supersededBy:` authoring, or Phase 4+ gate
-#   threshold tuning — those remain AskUserQuestion-eligible per ADR-013
+#   threshold tuning — those remain AskUserQuestion-eligible per structured-user-interaction-for-governance-skill-decisions-architecture-rule
 #   Rule 1.
 #
 # Usage:
@@ -88,29 +88,29 @@
 #     [--dry-run]                   # print diff to stdout, do not write
 #
 # Exit codes:
-#   0 = always — ADR-013 Rule 6 fail-safe. Missing NDJSON inputs / no
+#   0 = always — structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 6 fail-safe. Missing NDJSON inputs / no
 #                packages/ / opt-out marker all hit the no-write stderr-
 #                comment path.
 #
-# Privacy (ADR-035 clauses adopted verbatim):
+# Privacy (centralised-review-reports-for-cross-project-skill-improvement-jsonl-at-claude-review-reports-architecture-rule clauses adopted verbatim):
 #   - Opt-out marker `.claude/.skill-metrics-opt-out` disables writes.
 #   - No network egress — the script body invokes no exfiltration
 #     primitives. Negative-grep enforcement lives in the bats fixture.
 #
-# @problem P237 (Phase 3a — population script)
-# @problem P087 (parent — no maturity signal on plugin features)
-# @adr ADR-063 (Plugin maturity presentation layer — Phase 3a contract)
-# @adr ADR-053 (Plugin maturity taxonomy — promotion criteria +
+# @problem phase-3a-wr-itil-plugin-maturity-populate-writes-plugin-json-maturity-field-from-phase-2-ndjson-problem (Phase 3a — population script)
+# @problem problem-087-no-maturity-battle-hardening-signal-on-plugins-skills-agents-or-hooks-readmes-don-t-tell-users-which-features-are-stable-vs-experimental-problem (parent — no maturity signal on plugin features)
+# @adr windyroad-plugin-maturity-presentation-layer-plugin-json-schema-prose-woven-readme-badge-in-suite-wr-itil-plugin-maturity-list-display-shim-architecture-rule (Plugin maturity presentation layer — Phase 3a contract)
+# @adr windyroad-plugin-skill-agent-hook-maturity-taxonomy-architecture-rule (Plugin maturity taxonomy — promotion criteria +
 #   Bootstrapping clause)
-# @adr ADR-058 (Phase 2 NDJSON measurement — input shape)
-# @adr ADR-049 (Shim grammar — `wr-itil-plugin-maturity-populate` on $PATH)
-# @adr ADR-035 (Privacy posture — opt-out marker, no network primitive)
-# @adr ADR-044 (Decision delegation — silent-framework carve-out)
-# @adr ADR-052 (Behavioural tests default)
-# @adr ADR-013 Rule 6 (non-interactive fail-safe — exit 0 always)
-# @jtbd JTBD-201 (Restore Service Fast — rich-record evidence block IS the
+# @adr windyroad-plugin-maturity-measurement-mechanism-session-transcript-invocation-counts-plus-commit-history-composite-read-only-ndjson-architecture-rule (Phase 2 NDJSON measurement — input shape)
+# @adr plugin-bundled-scripts-invoked-from-skill-md-resolve-via-bin-on-path-architecture-rule (Shim grammar — `wr-itil-plugin-maturity-populate` on $PATH)
+# @adr centralised-review-reports-for-cross-project-skill-improvement-jsonl-at-claude-review-reports-architecture-rule (Privacy posture — opt-out marker, no network primitive)
+# @adr decision-delegation-contract-when-agents-act-on-the-framework-vs-ask-the-user-architecture-rule (Decision delegation — silent-framework carve-out)
+# @adr behavioural-tests-default-for-skill-testing-architecture-rule (Behavioural tests default)
+# @adr structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 6 (non-interactive fail-safe — exit 0 always)
+# @jtbd restore-service-fast-with-an-audit-trail-user-outcome (Restore Service Fast — rich-record evidence block IS the
 #   durable audit-trail surface at the canonical record)
-# @jtbd JTBD-101 (Extend the Suite — band-derivation persists Phase 2
+# @jtbd extend-the-suite-with-new-plugins-user-outcome (Extend the Suite — band-derivation persists Phase 2
 #   transient NDJSON signal as durable plugin.json field)
 
 set -uo pipefail
@@ -140,7 +140,7 @@ for arg in "$@"; do
   esac
 done
 
-# ── Opt-out marker check (ADR-035 / ADR-058 §Privacy posture) ───────────────
+# ── Opt-out marker check (centralised-review-reports-for-cross-project-skill-improvement-jsonl-at-claude-review-reports-architecture-rule / windyroad-plugin-maturity-measurement-mechanism-session-transcript-invocation-counts-plus-commit-history-composite-read-only-ndjson-architecture-rule §Privacy posture) ───────────────
 
 OPT_OUT_MARKER="${PROJECT_ROOT}/.claude/.skill-metrics-opt-out"
 if [ -e "$OPT_OUT_MARKER" ]; then
@@ -148,7 +148,7 @@ if [ -e "$OPT_OUT_MARKER" ]; then
   exit 0
 fi
 
-# ── packages/ discovery check (ADR-013 Rule 6 fail-safe) ────────────────────
+# ── packages/ discovery check (structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 6 fail-safe) ────────────────────
 
 if [ ! -d "${PROJECT_ROOT}/packages" ]; then
   echo "# wr-itil-plugin-maturity-populate: no packages/ directory at ${PROJECT_ROOT}" >&2
@@ -287,16 +287,16 @@ def discover_surfaces(pkg_dir):
         out["command"] = sorted(f.stem for f in commands_dir.glob("*.md") if f.is_file())
     return out
 
-# ── Band-mapping (ADR-053 §promotion criteria + §Bootstrapping clause) ─────
+# ── Band-mapping (windyroad-plugin-skill-agent-hook-maturity-taxonomy-architecture-rule §promotion criteria + §Bootstrapping clause) ─────
 
-# Band ordering, worst-first. "Deprecated" is an overlay axis (ADR-053
+# Band ordering, worst-first. "Deprecated" is an overlay axis (windyroad-plugin-skill-agent-hook-maturity-taxonomy-architecture-rule
 # §granularity contract line 109) — elided from the rollup computation but
 # retained on individual surface entries. Worst-case rollup compares only
 # {Experimental, Alpha, Beta, Stable}.
 BAND_ORDER = ["Experimental", "Alpha", "Beta", "Stable"]
 
 def compute_band(evidence):
-    """Map a per-surface evidence record -> band per ADR-053.
+    """Map a per-surface evidence record -> band per windyroad-plugin-skill-agent-hook-maturity-taxonomy-architecture-rule.
 
     - During bootstrapping (suite-oldest < 60d): default Experimental;
       provisional Alpha iff invocations_30d >= 100 AND days_shipped >= 14.
@@ -310,7 +310,7 @@ def compute_band(evidence):
     breaking = evidence.get("breaking_change_age_days")  # None or int
 
     if bootstrapping_active:
-        # Provisional Alpha rule (ADR-053 §Bootstrapping clause line 86).
+        # Provisional Alpha rule (windyroad-plugin-skill-agent-hook-maturity-taxonomy-architecture-rule §Bootstrapping clause line 86).
         if isinstance(inv, int) and inv >= 100 and days >= 14:
             return "Alpha"
         return "Experimental"
@@ -359,12 +359,12 @@ def lookup_invocations(plugin_bare, kind, name):
 
 def build_surface_record(existing, kind, plugin_bare, name, evidence):
     """Construct the new maturity record for a surface, respecting the
-    Deprecated-overlay invariant (architect §I + ADR-053 #6 / #102):
+    Deprecated-overlay invariant (architect §I + windyroad-plugin-skill-agent-hook-maturity-taxonomy-architecture-rule #6 / #102):
     if existing band is Deprecated, return existing record VERBATIM —
     do NOT recompute, do NOT update computed_at, do NOT overwrite
     supersededBy. All other records get a fresh recompute.
 
-    Under ADR-063 Amendment 2026-05-18 (P0 hotfix), `existing` IS the
+    Under windyroad-plugin-maturity-presentation-layer-plugin-json-schema-prose-woven-readme-badge-in-suite-wr-itil-plugin-maturity-list-display-shim-architecture-rule Amendment 2026-05-18 (P0 hotfix), `existing` IS the
     maturity record directly (no inner `.maturity` envelope) when read
     from the new nested location `plugin_doc["maturity"][<kind>][<name>]`.
     """
@@ -413,12 +413,12 @@ for pkg_dir in plugin_dirs:
     # (NOT top-level — Claude Code's plugin manifest validator rejects
     # top-level `hooks:` / `skills:` / `agents:` / `commands:` keys with
     # `Validation errors: hooks: Invalid input, skills: Invalid input` when
-    # they carry maturity-only records). Per ADR-063 Amendment 2026-05-18
+    # they carry maturity-only records). Per windyroad-plugin-maturity-presentation-layer-plugin-json-schema-prose-woven-readme-badge-in-suite-wr-itil-plugin-maturity-list-display-shim-architecture-rule Amendment 2026-05-18
     # (P0 hotfix). Schema version bumps to "2.0" because the path move is
-    # NOT additive per ADR-058 §Confirmation #8.
+    # NOT additive per windyroad-plugin-maturity-measurement-mechanism-session-transcript-invocation-counts-plus-commit-history-composite-read-only-ndjson-architecture-rule §Confirmation #8.
     kind_to_key = {"skill": "skills", "agent": "agents", "hook": "hooks", "command": "commands"}
     surface_bands_for_rollup = []
-    # P269: collect per-surface invocations_30d across the populate pass so
+    # amend-plugin-maturity-populate-sh-to-write-rollup-invocations-30d-on-plugin-root-rollup-for-compound-rendering-problem: collect per-surface invocations_30d across the populate pass so
     # the rollup can carry the sum. Non-null integers participate in the sum;
     # nulls (hook sentinel — architect §C) are excluded. All-null surface
     # set yields a null rollup_invocations_30d to preserve the "not
@@ -461,21 +461,21 @@ for pkg_dir in plugin_dirs:
         new_maturity_kinds[key] = new_map
         wrote_records += len(new_map)
 
-    # Plugin root rollup. ADR-063 Amendment 2026-05-18: per-kind surface
+    # Plugin root rollup. windyroad-plugin-maturity-presentation-layer-plugin-json-schema-prose-woven-readme-badge-in-suite-wr-itil-plugin-maturity-list-display-shim-architecture-rule Amendment 2026-05-18: per-kind surface
     # maps nest UNDER `maturity:` alongside `schema_version` + `band`, not
     # at top level. Write-ordering fix (architect issue 2 line 441): build
     # the entire `maturity:` dict in a single assignment so the rollup
     # write does not clobber the per-kind nested maps.
     #
-    # ADR-063 Amendment 2026-05-18 (P269 — rollup compound-evidence write):
+    # windyroad-plugin-maturity-presentation-layer-plugin-json-schema-prose-woven-readme-badge-in-suite-wr-itil-plugin-maturity-list-display-shim-architecture-rule Amendment 2026-05-18 (amend-plugin-maturity-populate-sh-to-write-rollup-invocations-30d-on-plugin-root-rollup-for-compound-rendering-problem — rollup compound-evidence write):
     # rollup additionally carries `rollup_invocations_30d` + `bootstrapping`
     # so the Phase 3b renderer's AND-gated compound predicate
     # (plugin-maturity-render.sh:146) can fire the
     # `*Maturity: <Band> (suite-bootstrap window; <N> invocations / 30d).*`
     # form during the bootstrapping window. Without these two fields the
-    # renderer falls through to bare-band, violating ADR-053 §Bootstrapping
+    # renderer falls through to bare-band, violating windyroad-plugin-skill-agent-hook-maturity-taxonomy-architecture-rule §Bootstrapping
     # clause Phase 3 rendering requirement (line 88). Additive-within-2.0
-    # per ADR-058 §Confirmation #8 — old consumers reading
+    # per windyroad-plugin-maturity-measurement-mechanism-session-transcript-invocation-counts-plus-commit-history-composite-read-only-ndjson-architecture-rule §Confirmation #8 — old consumers reading
     # `{schema_version, band}` continue to work; new consumers get the
     # additional fields where present.
     rollup = rollup_band(surface_bands_for_rollup)
@@ -495,7 +495,7 @@ for pkg_dir in plugin_dirs:
         plugin_doc["maturity"] = maturity_doc
     else:
         # Plugin with no shipped surfaces -> no plugin-level maturity field
-        # (ADR-053 §granularity contract line 110).
+        # (windyroad-plugin-skill-agent-hook-maturity-taxonomy-architecture-rule §granularity contract line 110).
         plugin_doc.pop("maturity", None)
 
     # Defensive cleanup: strip any legacy top-level keys left over from the
@@ -527,7 +527,7 @@ for pkg_dir in plugin_dirs:
     else:
         plugin_json_path.write_text(new_text, encoding="utf-8")
 
-# ── Operator-facing freshness summary on stderr (JTBD-007 currency aid) ────
+# ── Operator-facing freshness summary on stderr (keep-plugins-current-across-projects-user-outcome currency aid) ────
 # Non-load-bearing; cheap operator-comfort signal per JTBD review §4.
 
 print(

package/scripts/plugin-maturity-render.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 # packages/itil/scripts/plugin-maturity-render.sh
 #
-# Phase 3b (P087 / P238) plugin-maturity README renderer.
+# Phase 3b (problem-087-no-maturity-battle-hardening-signal-on-plugins-skills-agents-or-hooks-readmes-don-t-tell-users-which-features-are-stable-vs-experimental-problem / phase-3b-readme-badge-renderer-wr-itil-plugin-maturity-render-advisory-drift-detector-check-plugin-maturity-drift-sh-problem) plugin-maturity README renderer.
 #
 # Reads each `packages/<plugin>/.claude-plugin/plugin.json` `maturity:`
 # field (populated by Phase 3a `wr-itil-plugin-maturity-populate`) and
@@ -12,19 +12,19 @@
 #        Post-bootstrap: `*Maturity: <Band>.*`
 #        Bootstrapping window: `*Maturity: <Band> (suite-bootstrap window;
 #                              <N> invocations / 30d).*`
-#      Markdown text only — no shields.io URL, no inline SVG (ADR-063
+#      Markdown text only — no shields.io URL, no inline SVG (windyroad-plugin-maturity-presentation-layer-plugin-json-schema-prose-woven-readme-badge-in-suite-wr-itil-plugin-maturity-list-display-shim-architecture-rule
 #      §README badge rendering format).
 #
 #   2. Per-skill `Maturity` column populated in the existing `## Skills`
 #      table. Cell value is band name only (no compound — compound stays
-#      at the rollup per ADR-063). Adds the column header on first run;
+#      at the rollup per windyroad-plugin-maturity-presentation-layer-plugin-json-schema-prose-woven-readme-badge-in-suite-wr-itil-plugin-maturity-list-display-shim-architecture-rule). Adds the column header on first run;
 #      replaces cell values on subsequent runs.
 #
 # Idempotent: re-running with unchanged plugin.json + README produces
 # byte-identical README output. Replaces existing `*Maturity: ...*` span
 # rather than appending.
 #
-# Anti-patterns enforced (ADR-063 §Decision Outcome §"README badge
+# Anti-patterns enforced (windyroad-plugin-maturity-presentation-layer-plugin-json-schema-prose-woven-readme-badge-in-suite-wr-itil-plugin-maturity-list-display-shim-architecture-rule §Decision Outcome §"README badge
 # rendering format" + §"Bootstrapping clause rendering"):
 #   - NEVER emit a standalone `## Maturity` section
 #   - NEVER emit a header block immediately after H1 before any prose
@@ -32,8 +32,8 @@
 #   - Compound rendering stays at rollup only — per-skill cell carries
 #     band name only
 #
-# ADR-044 silent-framework carve-out: band has already been computed by
-# Phase 3a per ADR-053 §promotion criteria; the renderer is mechanical
+# decision-delegation-contract-when-agents-act-on-the-framework-vs-ask-the-user-architecture-rule silent-framework carve-out: band has already been computed by
+# Phase 3a per windyroad-plugin-skill-agent-hook-maturity-taxonomy-architecture-rule §promotion criteria; the renderer is mechanical
 # and never invokes AskUserQuestion.
 #
 # Usage:
@@ -42,28 +42,28 @@
 #     [--dry-run]             # print diff to stdout, do not write
 #
 # Exit codes:
-#   0 = always — ADR-013 Rule 6 fail-safe. Missing packages/ / opt-out
+#   0 = always — structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 6 fail-safe. Missing packages/ / opt-out
 #                marker / missing plugin.json / missing README / missing
 #                maturity field all hit no-write stderr-comment paths.
 #
-# Privacy (ADR-035 clauses adopted verbatim):
+# Privacy (centralised-review-reports-for-cross-project-skill-improvement-jsonl-at-claude-review-reports-architecture-rule clauses adopted verbatim):
 #   - Opt-out marker `.claude/.skill-metrics-opt-out` disables writes.
 #   - No network egress — script body invokes no exfiltration primitive.
 #
-# @problem P238 (Phase 3b — README badge renderer + advisory drift detector)
-# @problem P087 (parent — no maturity signal on plugin features)
-# @adr ADR-063 (Plugin maturity presentation layer — Phase 3b contract)
-# @adr ADR-053 (Plugin maturity taxonomy — Bootstrapping clause rendering)
-# @adr ADR-051 (JTBD-anchored README — prose-weaving precedent)
-# @adr ADR-049 (Shim grammar — `wr-itil-plugin-maturity-render` on $PATH)
-# @adr ADR-044 (Decision delegation — silent-framework carve-out)
-# @adr ADR-035 (Privacy posture — opt-out marker, no network primitive)
-# @adr ADR-052 (Behavioural tests default)
-# @adr ADR-013 Rule 6 (non-interactive fail-safe — exit 0 always)
-# @jtbd JTBD-302 (Trust That the README Describes the Plugin I Just
+# @problem phase-3b-readme-badge-renderer-wr-itil-plugin-maturity-render-advisory-drift-detector-check-plugin-maturity-drift-sh-problem (Phase 3b — README badge renderer + advisory drift detector)
+# @problem problem-087-no-maturity-battle-hardening-signal-on-plugins-skills-agents-or-hooks-readmes-don-t-tell-users-which-features-are-stable-vs-experimental-problem (parent — no maturity signal on plugin features)
+# @adr windyroad-plugin-maturity-presentation-layer-plugin-json-schema-prose-woven-readme-badge-in-suite-wr-itil-plugin-maturity-list-display-shim-architecture-rule (Plugin maturity presentation layer — Phase 3b contract)
+# @adr windyroad-plugin-skill-agent-hook-maturity-taxonomy-architecture-rule (Plugin maturity taxonomy — Bootstrapping clause rendering)
+# @adr windyroad-plugin-readmes-anchor-on-jtbd-job-ids-with-load-bearing-commit-hook-prose-woven-framing-architecture-rule (JTBD-anchored README — prose-weaving precedent)
+# @adr plugin-bundled-scripts-invoked-from-skill-md-resolve-via-bin-on-path-architecture-rule (Shim grammar — `wr-itil-plugin-maturity-render` on $PATH)
+# @adr decision-delegation-contract-when-agents-act-on-the-framework-vs-ask-the-user-architecture-rule (Decision delegation — silent-framework carve-out)
+# @adr centralised-review-reports-for-cross-project-skill-improvement-jsonl-at-claude-review-reports-architecture-rule (Privacy posture — opt-out marker, no network primitive)
+# @adr behavioural-tests-default-for-skill-testing-architecture-rule (Behavioural tests default)
+# @adr structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 6 (non-interactive fail-safe — exit 0 always)
+# @jtbd trust-that-the-readme-describes-the-plugin-i-just-installed-user-outcome (Trust That the README Describes the Plugin I Just
 #   Installed — README is the contract surface)
-# @jtbd JTBD-101 (Extend the Suite — clear patterns include stability)
-# @jtbd JTBD-003 (Compose Only the Guardrails I Need — at-a-glance
+# @jtbd extend-the-suite-with-new-plugins-user-outcome (Extend the Suite — clear patterns include stability)
+# @jtbd compose-only-the-guardrails-i-need-user-outcome (Compose Only the Guardrails I Need — at-a-glance
 #   stability for composition decisions)
 
 set -uo pipefail
@@ -87,7 +87,7 @@ for arg in "$@"; do
   esac
 done
 
-# ── Opt-out marker check (ADR-035) ──────────────────────────────────────────
+# ── Opt-out marker check (centralised-review-reports-for-cross-project-skill-improvement-jsonl-at-claude-review-reports-architecture-rule) ──────────────────────────────────────────
 
 OPT_OUT_MARKER="${PROJECT_ROOT}/.claude/.skill-metrics-opt-out"
 if [ -e "$OPT_OUT_MARKER" ]; then
@@ -95,7 +95,7 @@ if [ -e "$OPT_OUT_MARKER" ]; then
   exit 0
 fi
 
-# ── packages/ discovery check (ADR-013 Rule 6 fail-safe) ────────────────────
+# ── packages/ discovery check (structured-user-interaction-for-governance-skill-decisions-architecture-rule Rule 6 fail-safe) ────────────────────
 
 if [ ! -d "${PROJECT_ROOT}/packages" ]; then
   echo "# wr-itil-plugin-maturity-render: no packages/ directory at ${PROJECT_ROOT}" >&2
@@ -134,10 +134,10 @@ ANTI_SECTION_RE = re.compile(r"(?m)^##\s+Maturity\s*$")
 
 
 def format_rollup_badge(maturity_record):
-    """Render the prose-woven rollup badge per ADR-063.
+    """Render the prose-woven rollup badge per windyroad-plugin-maturity-presentation-layer-plugin-json-schema-prose-woven-readme-badge-in-suite-wr-itil-plugin-maturity-list-display-shim-architecture-rule.
 
     During the suite-bootstrap window the rollup carries the compound
-    form per ADR-053 §Bootstrapping clause rendering; post-sunset it
+    form per windyroad-plugin-skill-agent-hook-maturity-taxonomy-architecture-rule §Bootstrapping clause rendering; post-sunset it
     renders the band name only.
     """
     band = maturity_record.get("band", "Experimental")
@@ -345,7 +345,7 @@ def render_plugin(pkg_dir):
     new_text = weave_rollup_into_lead_prose(readme_text, badge)
 
     # Build per-skill band map from the plugin.json `maturity.skills.<name>`
-    # nested location. Per ADR-063 Amendment 2026-05-18 (P0 hotfix), per-skill
+    # nested location. Per windyroad-plugin-maturity-presentation-layer-plugin-json-schema-prose-woven-readme-badge-in-suite-wr-itil-plugin-maturity-list-display-shim-architecture-rule Amendment 2026-05-18 (P0 hotfix), per-skill
     # maturity records nest UNDER the top-level `maturity:` key as `band` /
     # `schema_version` / `computed_at` / `evidence` (no outer `.maturity`
     # envelope — the nested record IS the maturity record).

package/scripts/plugin-validate-ci-gate.sh

@@ -1,19 +1,19 @@
 #!/usr/bin/env bash
 # packages/itil/scripts/plugin-validate-ci-gate.sh
 #
-# P263 / ADR-063 §Confirmation #11 — CI pre-publish manifest-validity
+# ci-gate-claude-plugin-install-dry-run-per-plugin-pre-publish-confirmation-11-implementation-problem / windyroad-plugin-maturity-presentation-layer-plugin-json-schema-prose-woven-readme-badge-in-suite-wr-itil-plugin-maturity-list-display-shim-architecture-rule §Confirmation #11 — CI pre-publish manifest-validity
 # gate. Loops every `packages/*/.claude-plugin/plugin.json` in CWD,
 # runs `claude plugin validate <plugin_dir>` (NON-strict — see RCA
 # note below), accumulates failures, and exits non-zero if ANY plugin
 # manifest fails validation.
 #
-# WHY NON-STRICT (P263 / P258 refined RCA, 2026-05-30):
-#   - The historical P258 incident's failure class was a RECOGNISED
+# WHY NON-STRICT (ci-gate-claude-plugin-install-dry-run-per-plugin-pre-publish-confirmation-11-implementation-problem / plugin-json-top-level-hooks-skills-agents-keys-are-reserved-by-claude-code-s-manifest-validator-adding-arbitrary-content-breaks-claude-plugin-install-problem refined RCA, 2026-05-30):
+#   - The historical plugin-json-top-level-hooks-skills-agents-keys-are-reserved-by-claude-code-s-manifest-validator-adding-arbitrary-content-breaks-claude-plugin-install-problem incident's failure class was a RECOGNISED
 #     top-level key (`hooks` / `skills` / `agents` / `commands`)
 #     carrying wrong-typed content — caught by `claude plugin validate`
 #     non-strict as a hard ERROR (`Validation errors: hooks: Invalid
 #     input`).
-#   - ADR-063 Amendment 2026-05-18's chosen safe-extension pattern
+#   - windyroad-plugin-maturity-presentation-layer-plugin-json-schema-prose-woven-readme-badge-in-suite-wr-itil-plugin-maturity-list-display-shim-architecture-rule Amendment 2026-05-18's chosen safe-extension pattern
 #     places maturity records at top-level `maturity:` — an
 #     UNRECOGNISED top-level key — because unrecognised keys are
 #     warning-only and the plugin still loads. This is the durable
@@ -22,7 +22,7 @@
 #   - Non-strict therefore catches the historical incident's
 #     mechanism without rejecting the safe-extension pattern. The
 #     prose Confirmation #11 originally named `claude plugin install
-#     --dry-run`; P258 investigation refined to `claude plugin
+#     --dry-run`; plugin-json-top-level-hooks-skills-agents-keys-are-reserved-by-claude-code-s-manifest-validator-adding-arbitrary-content-breaks-claude-plugin-install-problem investigation refined to `claude plugin
 #     validate --strict`; this script's RCA refined further to
 #     non-strict.
 #
@@ -30,7 +30,7 @@
 #   CI installs `@anthropic-ai/claude-code@2.1.150` before invoking
 #   this script. The exact pin protects against Anthropic-side CLI
 #   behaviour change silently breaking the gate. 2.1.150 is the
-#   version P263 iter 6 empirically tested against. Bump the pin
+#   version ci-gate-claude-plugin-install-dry-run-per-plugin-pre-publish-confirmation-11-implementation-problem iter 6 empirically tested against. Bump the pin
 #   only after re-running the iter-6 probe against the new version.
 #
 # LOOP CONTRACT:
@@ -38,19 +38,19 @@
 #   - Does NOT short-circuit on first failure — every plugin is
 #     exercised so CI surfaces every defect at once.
 #   - `nullglob` makes a zero-plugin tree a no-op exit 0 (adopter-
-#     tree portability per ADR-049).
+#     tree portability per plugin-bundled-scripts-invoked-from-skill-md-resolve-via-bin-on-path-architecture-rule).
 #
 # References:
-#   ADR-063  — Amendment 2026-05-18 + §Confirmation #11
-#   ADR-049  — PATH-on-shim grammar (`wr-itil-plugin-validate-ci-gate`)
-#   ADR-052  — behavioural tests default (bats at
+#   windyroad-plugin-maturity-presentation-layer-plugin-json-schema-prose-woven-readme-badge-in-suite-wr-itil-plugin-maturity-list-display-shim-architecture-rule  — Amendment 2026-05-18 + §Confirmation #11
+#   plugin-bundled-scripts-invoked-from-skill-md-resolve-via-bin-on-path-architecture-rule  — PATH-on-shim grammar (`wr-itil-plugin-validate-ci-gate`)
+#   behavioural-tests-default-for-skill-testing-architecture-rule  — behavioural tests default (bats at
 #              `scripts/test/plugin-validate-ci-gate.bats`)
-#   ADR-014  — single-commit grain (script + shim + bats + CI + ADR
+#   governance-skills-commit-their-own-completed-work-architecture-rule  — single-commit grain (script + shim + bats + CI + ADR
 #              amendment + changeset land together)
-#   P258     — root-cause driver (recognised vs unrecognised key
+#   plugin-json-top-level-hooks-skills-agents-keys-are-reserved-by-claude-code-s-manifest-validator-adding-arbitrary-content-breaks-claude-plugin-install-problem     — root-cause driver (recognised vs unrecognised key
 #              distinction)
-#   P246     — sibling-class "gate-the-actual-load-bearing-surface"
-#   P263     — this implementation's ticket
+#   agent-waits-on-calendar-trigger-for-held-cohort-graduation-violates-symmetric-balance-principle-problem     — sibling-class "gate-the-actual-load-bearing-surface"
+#   ci-gate-claude-plugin-install-dry-run-per-plugin-pre-publish-confirmation-11-implementation-problem     — this implementation's ticket
 
 set -e
 shopt -s nullglob

package/scripts/reconcile-readme.sh

@@ -4,7 +4,7 @@
 # Diagnose-only drift detector for docs/problems/README.md vs filesystem
 # truth. Reads ticket files from BOTH the flat layout
 # `<problems-dir>/<NNN>-*.<status>.md` AND the per-state subdir layout
-# `<problems-dir>/<status>/<NNN>-*.md` (RFC-002 dual-tolerant migration
+# `<problems-dir>/<status>/<NNN>-*.md` (docs-problems-flat-layout-migration-per-state-subdirs-adopter-auto-migration-release-design dual-tolerant migration
 # window), parses the README's WSJF Rankings + Verification Queue +
 # Closed tables, and reports each disagreement.
 #
@@ -15,7 +15,7 @@
 #
 # Dual-layout precedence: when the same ID appears in both layout-halves
 # (transient mid-migration race between `git mv` and README refresh),
-# the per-state subdir wins — ADR-031 §"Authoritative state signal"
+# the per-state subdir wins — problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule §"Authoritative state signal"
 # treats subdirectory as the post-migration ground truth.
 #
 # Exit codes:
@@ -24,7 +24,7 @@
 #   2 = parse error (README missing or malformed)
 #
 # Output format on drift (one line per drift entry, ≤ 150 bytes per
-# ADR-038 progressive-disclosure budget):
+# progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule progressive-disclosure budget):
 #   DRIFT    <ID> wsjf-rankings: claims=<status> actual=<status>
 #   MISSING  <ID> wsjf-rankings: actual=<status> file=<basename>
 #   STALE    <ID> verification-queue: actual=<status>
@@ -34,18 +34,18 @@
 # skill applies edits with narrative-aware preservation; this script's
 # only job is to report ground truth.
 #
-# @problem P118
-# @problem P170 (RFC-002 — dual-tolerant migration window)
-# @problem P252 (Inbound Upstream Reports rows mis-attributed to VQ)
-# @adr ADR-014 (Reconciliation as preflight robustness layer)
-# @adr ADR-022 (Verification Pending lifecycle excludes from WSJF Rankings)
-# @adr ADR-031 (Per-state subdir is post-migration authoritative state signal)
-# @adr ADR-038 (Progressive disclosure — per-row byte budget)
-# @adr ADR-062 (Inbound upstream-report discovery + assessment pipeline)
-# @rfc RFC-004 (P079 inbound-upstream-report discovery)
-# @jtbd JTBD-006 (Progress the Backlog While I'm Away)
-# @jtbd JTBD-001 (Enforce Governance Without Slowing Down)
-# @jtbd JTBD-302 (Trust That the README Describes the Plugin I Just Installed)
+# @problem docs-problems-readme-md-drifts-from-filesystem-truth-across-sessions-despite-refresh-on-create-and-refresh-on-transition-both-closed-problem
+# @problem problem-tickets-strain-as-fixes-decompose-into-multiple-coordinated-changes-need-an-rfc-framework-that-ties-all-changes-back-to-problems-and-unifies-technical-with-user-business-problems-problem (docs-problems-flat-layout-migration-per-state-subdirs-adopter-auto-migration-release-design — dual-tolerant migration window)
+# @problem reconcile-readme-false-positive-parses-inbound-upstream-reports-matched-local-ticket-column-as-verification-queue-problem (Inbound Upstream Reports rows mis-attributed to VQ)
+# @adr governance-skills-commit-their-own-completed-work-architecture-rule (Reconciliation as preflight robustness layer)
+# @adr problem-lifecycle-add-a-verification-pending-status-between-known-error-and-closed-architecture-rule (Verification Pending lifecycle excludes from WSJF Rankings)
+# @adr problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule (Per-state subdir is post-migration authoritative state signal)
+# @adr progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule (Progressive disclosure — per-row byte budget)
+# @adr inbound-upstream-report-discovery-assessment-pipeline-peer-of-architecture-rule (Inbound upstream-report discovery + assessment pipeline)
+# @rfc inbound-upstream-report-discovery-assessment-pipeline-implementation-rollout-release-design (problem-079-no-inbound-sync-of-upstream-reported-problems-reports-filed-via-the-intake-templates-never-surface-in-the-local-backlog-problem inbound-upstream-report discovery)
+# @jtbd progress-the-backlog-while-i-m-away-user-outcome (Progress the Backlog While I'm Away)
+# @jtbd enforce-governance-without-slowing-down-user-outcome (Enforce Governance Without Slowing Down)
+# @jtbd trust-that-the-readme-describes-the-plugin-i-just-installed-user-outcome (Trust That the README Describes the Plugin I Just Installed)
 
 set -uo pipefail
 
@@ -66,9 +66,9 @@ fi
 
 # ── Build filesystem truth: ID → status ─────────────────────────────────────
 #
-# RFC-002 dual-tolerant enumeration: walk BOTH the flat layout and the
+# docs-problems-flat-layout-migration-per-state-subdirs-adopter-auto-migration-release-design dual-tolerant enumeration: walk BOTH the flat layout and the
 # per-state subdir layout. Per-state subdir wins on collision (mid-
-# migration race; per-state is the migration target per ADR-031).
+# migration race; per-state is the migration target per problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule).
 
 declare -A FS_STATUS
 shopt -s nullglob
@@ -83,7 +83,7 @@ for f in "$PROBLEMS_DIR"/[0-9][0-9][0-9]-*.open.md \
   num="${base%%-*}"
   id="P${num}"
   # `ticket_status` (not bash `status`) — zsh has `$status` as a read-only
-  # built-in mapping to `$?`. Defensive rename per P133 even though this
+  # built-in mapping to `$?`. Defensive rename per zsh-portability-gap-in-shell-snippet-examples-across-skill-md-files-bash-style-word-splitting-bash-builtin-variable-names-fail-silently-or-noisily-on-zsh-problem even though this
   # script's `#!/usr/bin/env bash` shebang means it never runs under zsh.
   case "$base" in
     *.open.md)         ticket_status="open" ;;
@@ -98,7 +98,7 @@ done
 # Per-state subdir layout: docs/problems/<state>/<NNN>-<title>.md
 # Status derived from parent directory name (the subdirectory IS the
 # state signal post-migration). Writes after the flat loop so per-state
-# wins on cross-layout ID collision (ADR-031 authoritative state).
+# wins on cross-layout ID collision (problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule authoritative state).
 for ticket_status in open known-error verifying closed parked; do
   for f in "$PROBLEMS_DIR"/"$ticket_status"/[0-9][0-9][0-9]-*.md; do
     base="$(basename "$f")"
@@ -114,11 +114,11 @@ shopt -u nullglob
 
 WSJF_START=$(grep -n '^## WSJF Rankings' "$README" | head -1 | cut -d: -f1)
 VQ_START=$(grep -n '^## Verification Queue' "$README" | head -1 | cut -d: -f1)
-# Inbound Upstream Reports (ADR-062 / RFC-004) sits between Verification
+# Inbound Upstream Reports (inbound-upstream-report-discovery-assessment-pipeline-peer-of-architecture-rule / inbound-upstream-report-discovery-assessment-pipeline-implementation-rollout-release-design) sits between Verification
 # Queue and Closed when populated. Its `Matched local ticket` column
 # carries `| P<NNN> |` cross-refs that look like VQ rows but live in a
 # distinct section. The VQ slice MUST terminate at this header when
-# present, otherwise its rows get miscounted as VQ entries (P252).
+# present, otherwise its rows get miscounted as VQ entries (reconcile-readme-false-positive-parses-inbound-upstream-reports-matched-local-ticket-column-as-verification-queue-problem).
 INBOUND_START=$(grep -n '^## Inbound Upstream Reports' "$README" | head -1 | cut -d: -f1)
 CLOSED_START=$(grep -n '^## Closed' "$README" | head -1 | cut -d: -f1)
 PARKED_START=$(grep -n '^## Parked' "$README" | head -1 | cut -d: -f1)
@@ -126,7 +126,7 @@ END_LINE=$(wc -l < "$README")
 
 # Sentinel each end with the next section start (or EOF). The VQ_END
 # cascade prefers INBOUND_START when present so Inbound rows are
-# excluded from VQ extraction (P252).
+# excluded from VQ extraction (reconcile-readme-false-positive-parses-inbound-upstream-reports-matched-local-ticket-column-as-verification-queue-problem).
 WSJF_END=${VQ_START:-${INBOUND_START:-${CLOSED_START:-${PARKED_START:-$END_LINE}}}}
 VQ_END=${INBOUND_START:-${CLOSED_START:-${PARKED_START:-$END_LINE}}}
 CLOSED_END=${PARKED_START:-$END_LINE}
@@ -172,7 +172,7 @@ while read -r id; do
 done <<< "$README_WSJF_IDS"
 
 # (2) Each ID listed in Verification Queue must be .verifying.md on disk.
-#     .closed.md → STALE (drift class P062 closure didn't refresh);
+#     .closed.md → STALE (drift class problem-062-manage-problem-does-not-refresh-docs-problems-readme-md-on-single-ticket-transitions-fast-path-cache-goes-stale-silently-problem closure didn't refresh);
 #     .open.md / .known-error.md → STALE; missing → STALE.
 while read -r id; do
   [ -z "$id" ] && continue

package/scripts/reconcile-rfcs.sh

@@ -19,13 +19,13 @@
 #   2 = parse error (README missing or malformed)
 #
 # Output format on drift (one line per drift entry, ≤ 150 bytes per
-# ADR-038 progressive-disclosure budget):
+# progressive-disclosure-once-per-session-budget-for-userpromptsubmit-governance-prose-architecture-rule progressive-disclosure budget):
 #   DRIFT    RFC-<NNN> wsjf-rankings: claims=<status> actual=<status>
 #   MISSING  RFC-<NNN> wsjf-rankings: actual=<status>
 #   STALE    RFC-<NNN> verification-queue: actual=<status>
 #   MISMATCH RFC-<NNN> closed: actual=<status>
 #
-# Reverse-trace pass (B5.T8 — closes ADR-060 Confirmation criterion 3):
+# Reverse-trace pass (B5.T8 — closes problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule Confirmation criterion 3):
 # When <problems-dir> is provided AND on disk, the reconciler also
 # checks the auto-maintained `## RFCs` section on each problem ticket
 # against the RFC frontmatter `problems:` claims. Three drift kinds:
@@ -43,22 +43,22 @@
 # applies edits with narrative-aware preservation; this script's only
 # job is to report ground truth.
 #
-# Sibling to packages/itil/scripts/reconcile-readme.sh (P118 / ADR-014):
+# Sibling to packages/itil/scripts/reconcile-readme.sh (docs-problems-readme-md-drifts-from-filesystem-truth-across-sessions-despite-refresh-on-create-and-refresh-on-transition-both-closed-problem / governance-skills-commit-their-own-completed-work-architecture-rule):
 # same parse + diff structure, applied at the RFC tier instead of the
 # problems tier. Differences:
 #   - Filename pattern: RFC-NNN-*.<status>.md (5 statuses: proposed,
 #     accepted, in-progress, verifying, closed)
 #   - ID format: RFC-<NNN> (vs P<NNN>)
 #   - WSJF Rankings covers proposed/accepted/in-progress (RFC dev-work
-#     queue per ADR-060 § Decisions Resolved — RFC-level WSJF, Phase 1)
+#     queue per problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule § Decisions Resolved — RFC-level WSJF, Phase 1)
 #   - Verification Queue covers verifying (matches problem tier)
 #   - Closed covers closed
-#   - No Parked tier (RFCs don't have a Parked status per ADR-060;
+#   - No Parked tier (RFCs don't have a Parked status per problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule;
 #     only Problems do)
 #
-# @problem P170
-# @adr ADR-060 (Problem-RFC-Story framework — Phase 1 item 5)
-# @adr ADR-049 (Plugin script resolution via bin/ on PATH — paired bin shim)
+# @problem problem-tickets-strain-as-fixes-decompose-into-multiple-coordinated-changes-need-an-rfc-framework-that-ties-all-changes-back-to-problems-and-unifies-technical-with-user-business-problems-problem
+# @adr problem-rfc-story-framework-with-mandatory-problem-trace-and-unified-problem-ontology-architecture-rule (Problem-RFC-Story framework — Phase 1 item 5)
+# @adr plugin-bundled-scripts-invoked-from-skill-md-resolve-via-bin-on-path-architecture-rule (Plugin script resolution via bin/ on PATH — paired bin shim)
 
 set -uo pipefail
 
@@ -221,7 +221,7 @@ done
 # frontmatter `problems:` claims (and vice-versa).
 
 if [ -d "$PROBLEMS_DIR" ]; then
-  # rfc_problems_claim["RFC-NNN"] = "P168 P169 ..."
+  # rfc_problems_claim["RFC-NNN"] = "risk-scorer-doesn-t-consume-docs-risks-catalog-or-bootstrap-from-risk-reports-problem build-recogniser-shape-catalogue-into-windyroad-risk-scorer-plugin-automatic-bootstrap-ongoing-maintenance-problem ..."
   declare -A rfc_problems_claim
   shopt -s nullglob
   for f in "$RFCS_DIR"/RFC-[0-9][0-9][0-9]-*.md; do
@@ -229,7 +229,7 @@ if [ -d "$PROBLEMS_DIR" ]; then
     num="${base#RFC-}"
     num="${num%%-*}"
     rfc_id="RFC-${num}"
-    # Parse YAML frontmatter `problems: [P168, P169]` (single line).
+    # Parse YAML frontmatter `problems: [risk-scorer-doesn-t-consume-docs-risks-catalog-or-bootstrap-from-risk-reports-problem, build-recogniser-shape-catalogue-into-windyroad-risk-scorer-plugin-automatic-bootstrap-ongoing-maintenance-problem]` (single line).
     raw=$(awk '/^problems:/ { print; exit }' "$f")
     # Strip everything except inside-brackets bare comma-separated content.
     inner=$(echo "$raw" | sed -E 's/^[[:space:]]*problems:[[:space:]]*\[//; s/\][[:space:]]*$//')
@@ -247,11 +247,11 @@ if [ -d "$PROBLEMS_DIR" ]; then
   done
   shopt -u nullglob
 
-  # problem_rfc_rows["P168 RFC-001"] = "<claimed-status>"
-  # problem_rfc_ids["P168"] = "RFC-001 RFC-002 ..."
+  # problem_rfc_rows["risk-scorer-doesn-t-consume-docs-risks-catalog-or-bootstrap-from-risk-reports-problem pipeline-consume-catalog-and-bootstrap-from-reports-multi-commit-retrofit-release-design"] = "<claimed-status>"
+  # problem_rfc_ids["risk-scorer-doesn-t-consume-docs-risks-catalog-or-bootstrap-from-risk-reports-problem"] = "pipeline-consume-catalog-and-bootstrap-from-reports-multi-commit-retrofit-release-design docs-problems-flat-layout-migration-per-state-subdirs-adopter-auto-migration-release-design ..."
   declare -A problem_rfc_rows
   declare -A problem_rfc_ids
-  # P312 / ADR-031: scan both flat docs/problems/<NNN>-*.md AND per-state
+  # reconcile-rfcs-reports-spurious-missing-reverse-trace-doesn-t-traverse-docs-problems-per-state-subdirs-class-glob-gap-problem / problem-ticket-directory-layout-per-state-subdirectories-under-docs-problems-architecture-rule: scan both flat docs/problems/<NNN>-*.md AND per-state
   # subdir docs/problems/<state>/<NNN>-*.md layouts so the reverse-trace
   # remains valid post-migration. Mirrors reconcile-readme.sh lines 74-110.
   shopt -s nullglob