@windyroad/itil 0.59.2 → 0.60.0-preview.1031

package/.claude-plugin/plugin.json

@@ -497,5 +497,5 @@
     }
   },
   "name": "wr-itil",
-  "version": "0.59.2"
+  "version": "0.60.0"
 }

package/README.md

@@ -93,7 +93,7 @@ See [ADR-011](../../docs/decisions/011-manage-incident-skill.proposed.md) for th
 | `/wr-itil:capture-story` | Lightweight story-capture skill — mandatory problem-trace AND JTBD-trace per ADR-060 I6 + I9 invariants; optional `--rfc` / `--story-map` flags (I7 + I8 enforce at `accepted` transition); drafts an INVEST-shaped sub-workstream entity under a parent RFC (Phase 2 of the Problem-RFC-Story framework, P170 / ADR-060) | Experimental |
 | `/wr-itil:list-stories` | Read-only display of stories grouped by lifecycle state, with optional `--rfc RFC-<NNN>` filter rendering the RFC's ordered story list per ADR-060 line 259 (Phase 2 / P170) | Experimental |
 | `/wr-itil:reconcile-stories` | Detect and correct drift between `docs/stories/README.md` and on-disk story inventory + reverse-trace `## Stories` sections on driving problems / RFCs / JTBDs (Phase 2 / P170) | Experimental |
-| `/wr-itil:manage-story` | Heavyweight story lifecycle management — draft → accepted → in-progress → done → archived; I7+I8+I10 hard-block at accepted transition; INVEST 4-axis check; auto-transitions on `Refs: STORY-NNN` commit trailer + linked RFC closure (Phase 2 / P170) | Experimental |
+| `/wr-itil:manage-story` | Heavyweight story lifecycle management — draft → accepted → in-progress → done → archived; I7+I8+I10+I12 hard-block at accepted transition; INVEST 4-axis check; auto-transitions on `Refs: STORY-NNN` commit trailer + linked RFC closure (Phase 2 / P170). **I12 (ADR-101)**: `accepted` requires a recorded ratification basis, and an implementing commit against an unratified story is blocked. The basis is a human ratification event by default; an `oversight-basis: pure-decomposition` marker is written instead only where the project has opted in AND the story decomposes nothing but already-confirmed substance — see the config key below | Experimental |
 | `/wr-itil:capture-story-map` | Lightweight story-map-capture skill — mandatory problem-trace AND JTBD-trace per ADR-060 I3 + I4 invariants; HTML skeleton at `docs/story-maps/draft/STORY-MAP-NNN-<slug>.html` per ADR-060 § Phase 2 encoding amendment 2026-05-12 (Phase 2 / P170) | Experimental |
 | `/wr-itil:manage-story-map` | Heavyweight story-map lifecycle management — draft → accepted → in-progress → completed → archived; backbone/ribs/slices authoring guidance; reverse-trace `## Story Maps` refresh on driving problems + JTBDs (Phase 2 / P170) | Experimental |
 | `/wr-itil:reconcile-story-maps` | Detect and correct drift between `docs/story-maps/README.md` and on-disk story-map HTML inventory (Phase 2 / P170) | Experimental |
@@ -103,6 +103,22 @@ See [ADR-011](../../docs/decisions/011-manage-incident-skill.proposed.md) for th
 | `/wr-itil:mitigate-incident` / `/wr-itil:restore-incident` / `/wr-itil:close-incident` / `/wr-itil:link-incident` | Incident lifecycle transitions (ADR-011) | Experimental |
 | `/wr-itil:scaffold-intake` | Scaffold OSS intake surfaces (`.github/ISSUE_TEMPLATE/`, `SECURITY.md`, `SUPPORT.md`, `CONTRIBUTING.md`) for downstream adopters (ADR-036) | Experimental |
 
+## Configuration
+
+Optional. Create `.claude/itil.config.json` in your project (or `~/.claude/itil.config.json` for all your projects); a project key wins over a machine key, and both are optional.
+
+| Key | Default | What it does |
+|---|---|---|
+| `afk_accept_pure_decomposition` | `false` | Lets an unattended run accept and implement a story **without** asking you first — but only when that story adds no new thinking. Every decision, job and map it draws on must already be one you confirmed, and each of its acceptance criteria must name the confirmed clause it breaks down. Anything that introduces a new design choice, persona or decision is still held for you. Off unless you turn it on. |
+
+```json
+{ "afk_accept_pure_decomposition": true }
+```
+
+Only the literal `true` turns it on. Stories accepted this way are marked `oversight-basis: pure-decomposition`, listed by `wr-itil-detect-unratified-stories-maps --with-afk-accepted`, and shown distinctly by `/wr-itil:list-stories`, so you can review them afterwards. Nothing ever writes this file for you. Background: ADR-101.
+
+Independently of this setting, an implementing commit against a story you have not ratified is blocked for everyone.
+
 ## Updating and Uninstalling
 
 ```bash

package/bin/wr-itil-check-afk-accept-eligible

@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Generated by scripts/sync-shim-wrappers.sh from
+# packages/shared/lib/shim-wrapper-template.sh. DO NOT EDIT individual
+# shim files in packages/*/bin/wr-* directly; edit the template + run
+# `npm run sync:shim-wrappers` to regenerate.
+#
+# Resolution (ADR-080):
+#   1. If the wrapper's parent dir is semver-shaped, treat as installed-
+#      cache execution and resolve to the highest-version sibling's
+#      scripts/ entry below.
+#   2. Otherwise (parent dir is e.g. `architect`), treat as source-
+#      monorepo execution and dispatch to own scripts/. The source-repo-
+#      guard `exec` is the anchor parsed by
+#      packages/retrospective/scripts/check-tarball-shipped-shims.sh.
+#   3. If the cache parent contains zero semver-shaped siblings, exit
+#      127 with a stderr message naming the cache parent (per SQ-080-2).
+#
+# @adr ADR-080 (highest-version-wins shim wrapper plugin scaffold)
+# @adr ADR-049 (plugin-bundled scripts resolve via bin/ on $PATH — amended)
+# @problem P343 (mid-session staleness window)
+
+set -euo pipefail
+
+SHIM_DIR="$(cd "$(dirname "$0")" && pwd)"
+OWN_VERSION_DIR="$(dirname "$SHIM_DIR")"
+OWN_VERSION_NAME="$(basename "$OWN_VERSION_DIR")"
+CACHE_PARENT="$(dirname "$OWN_VERSION_DIR")"
+
+SEMVER_RE='^[0-9]+\.[0-9]+\.[0-9]+([-+][0-9A-Za-z.-]+)?$'
+
+# Source-repo guard: own parent dir is NOT semver → dispatch to own scripts/.
+if ! [[ "$OWN_VERSION_NAME" =~ $SEMVER_RE ]]; then
+  exec "$SHIM_DIR/../scripts/check-afk-accept-eligible.sh" "$@"
+fi
+
+# Cache execution: pick the highest-semver sibling under CACHE_PARENT.
+HIGHEST=""
+while IFS= read -r dir; do
+  name="$(basename "$dir")"
+  [[ "$name" =~ $SEMVER_RE ]] || continue
+  if [[ -z "$HIGHEST" ]] || [[ "$(printf '%s\n%s\n' "$HIGHEST" "$name" | sort -V | tail -1)" == "$name" ]]; then
+    HIGHEST="$name"
+  fi
+done < <(find "$CACHE_PARENT" -mindepth 1 -maxdepth 1 -type d 2>/dev/null)
+
+if [[ -z "$HIGHEST" ]]; then
+  printf 'wr-shim: no cached versions in %s\n' "$CACHE_PARENT" >&2
+  exit 127
+fi
+
+exec "$CACHE_PARENT/$HIGHEST/scripts/check-afk-accept-eligible.sh" "$@"

package/hooks/itil-no-implement-draft-gate.sh

@@ -10,14 +10,31 @@
 # the exact P404 bypass — a direct implementing commit against a draft story,
 # whether from the orchestrator or by hand.
 #
+# It ALSO enforces the ADR-090 ratification ADR-096 names but never implemented
+# (P465): a commit against an `accepted`/`in-progress` story is blocked unless
+# that story is ratified. This half is UNCONDITIONAL — a pure tightening, no
+# config, no opt-in — because putting an ADR-090-mandated check behind a flag
+# would be the decision conflict. Where the marker was machine-written under the
+# ADR-101 pure-decomposition carve-out, the gate additionally re-asserts the
+# story-LOCAL structure of that carve-out. It never re-evaluates the carve-out's
+# shared-artefact conditions: those are accept-time only, because unrelated churn
+# on a shared story map must not block an unrelated story (that is P456's shape).
+#
 # Bypass: BYPASS_NO_IMPLEMENT_DRAFT=1.
 #
 # @adr ADR-096 (no-implement-while-draft) ADR-060 (lifecycle) ADR-013 (Rule 6)
 #      ADR-095 (sibling capture-time gates) ADR-052 (bats)
-# @problem P404
+#      ADR-090 (drift-invalidated ratification) ADR-101 (AFK carve-out)
+# @problem P404 P465 P456
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 # shellcheck source=lib/command-detect.sh
 source "$SCRIPT_DIR/lib/command-detect.sh" 2>/dev/null || exit 0
+# Fail-open per ADR-013 Rule 6. A missing story-oversight lib degrades to the
+# draft-only gate; a missing command-detect lib (sourced above with the same
+# guard) exits before the draft check too, so that path degrades to no gate at
+# all. Both fail in the safe direction — never blocking every commit.
+# shellcheck source=../lib/story-oversight.sh
+source "$SCRIPT_DIR/../lib/story-oversight.sh" 2>/dev/null || exit 0
 
 INPUT=$(cat)
 TOOL_NAME=$(printf '%s' "$INPUT" | python3 -c "import sys,json
@@ -64,6 +81,34 @@ while IFS= read -r id; do
   if [ ${#draftfiles[@]} -gt 0 ]; then
     deny "BLOCKED (ADR-096 / P404): this commit references ${id} via a Refs: trailer, but ${id} is still in draft. A draft story cannot be implemented — accept it first via /wr-itil:manage-story ${id} accepted (it runs the INVEST + RFC-trace gates + ratification), then re-commit. Bypass: BYPASS_NO_IMPLEMENT_DRAFT=1."
   fi
+
+  # ADR-090 ratification at the implementation locus (P465). ADR-096's Decision
+  # Outcome claims no unratified story can ever be implemented; nothing enforced
+  # it until here. Scoped to accepted/in-progress — done/archived stories are
+  # past implementation and are not gated.
+  shopt -s nullglob
+  livefiles=(./docs/stories/accepted/${id}-*.md ./docs/stories/in-progress/${id}-*.md)
+  shopt -u nullglob
+  [ ${#livefiles[@]} -gt 0 ] || continue
+  story="${livefiles[0]}"
+
+  if ! is_story_map_ratified "$story"; then
+    deny "BLOCKED (ADR-090 / ADR-096 / P465): this commit references ${id}, but ${id} is not ratified — it carries no confirmed human-oversight marker, or its content has drifted since it was ratified. ADR-096 requires ratification before any implementation. Ratify it via /wr-itil:manage-story ${id} ratify, then re-commit. Bypass: BYPASS_NO_IMPLEMENT_DRAFT=1."
+  fi
+
+  # ADR-101 belt-and-braces. The load-bearing catch for a post-accept edit is
+  # the hash above (both `afk-accept:` and `## Decomposition basis` sit inside
+  # it). This adds a specific, actionable deny reason instead of a generic drift
+  # deny, on a story-local structure no shared-artefact churn can invalidate.
+  if oversight_is_pure_decomposition "$story"; then
+    oversight_declares_pure_decomposition "$story" || deny \
+      "BLOCKED (ADR-101): ${id} carries a machine-written pure-decomposition marker but no longer declares \`afk-accept: pure-decomposition\`. Re-accept it, or ratify it as a human via /wr-itil:manage-story ${id} ratify."
+    crit=$(awk '/^##[[:space:]]+Acceptance criteria/{i=1;next} i&&/^##[[:space:]]/{exit} i' "$story" | grep -cE '^- \[[ xX]\]')
+    basis=$(awk '/^##[[:space:]]+Decomposition basis/{i=1;next} i&&/^##[[:space:]]/{exit} i' "$story" | grep -cE '^- ')
+    if [ "$crit" -eq 0 ] || [ "$basis" -ne "$crit" ]; then
+      deny "BLOCKED (ADR-101): ${id} was AFK-accepted as pure decomposition, but its \`## Decomposition basis\` (${basis} entries) no longer matches its acceptance criteria (${crit}). Every criterion must name the already-confirmed clause it decomposes. Re-run /wr-itil:manage-story ${id} accepted, or ratify it as a human."
+    fi
+  fi
 done <<< "$STORIES"
 
 exit 0

package/hooks/test/itil-no-implement-draft-gate.bats

@@ -6,9 +6,17 @@
 
 setup() {
   HOOK="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)/itil-no-implement-draft-gate.sh"
+  MARK="$(cd "$(dirname "$BATS_TEST_FILENAME")/../../scripts" && pwd)/mark-story-oversight-confirmed.sh"
   TMP="$(mktemp -d)"; cd "$TMP"; git init -q .
-  mkdir -p docs/stories/draft docs/stories/accepted
+  mkdir -p docs/stories/draft docs/stories/accepted docs/stories/in-progress
 }
+
+# Seed a minimally well-formed story. Since ADR-101 the gate is ratification-
+# aware, so a bare `touch` no longer produces a story it will pass.
+seed_story() { printf -- '---\nstatus: accepted\n---\n\n# %s\n' "$1" > "$2"; }
+# Ratify via the real write path, never a hand-written marker — the hash has one
+# definition and a hand-rolled fixture would drift from it.
+ratify() { bash "$MARK" "$@" >/dev/null 2>&1; }
 teardown() { cd /; rm -rf "$TMP"; }
 
 # write env.json carrying the given command string
@@ -25,8 +33,128 @@ Refs: STORY-042"'
   echo "$output" | grep -q 'STORY-042'
 }
 
-@test "allows a commit referencing an ACCEPTED story" {
-  touch docs/stories/accepted/STORY-042-foo.md
+# This case previously seeded an EMPTY, unratified accepted story and asserted
+# allow — the P465 hole encoded as a test rather than behaviour anyone chose.
+# ADR-096 always claimed no unratified story could be implemented; nothing
+# enforced it. Split into both directions, flipped in the slice that ships the
+# behaviour (the ADR-089 precedent).
+
+@test "allows a commit referencing an ACCEPTED and RATIFIED story" {
+  seed_story STORY-042 docs/stories/accepted/STORY-042-foo.md
+  ratify docs/stories/accepted/STORY-042-foo.md
+  env_cmd 'git commit -m "fix: thing
+
+Refs: STORY-042"'
+  run bash -c "bash '$HOOK' < env.json"
+  [ "$status" -eq 0 ]
+  ! echo "$output" | grep -q 'deny'
+}
+
+@test "blocks a commit referencing an ACCEPTED but UNRATIFIED story (P465)" {
+  seed_story STORY-042 docs/stories/accepted/STORY-042-foo.md
+  env_cmd 'git commit -m "fix: thing
+
+Refs: STORY-042"'
+  run bash -c "bash '$HOOK' < env.json"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -q '"permissionDecision": "deny"'
+  echo "$output" | grep -q 'not ratified'
+}
+
+@test "blocks a commit referencing an IN-PROGRESS story whose content has drifted since ratification" {
+  seed_story STORY-042 docs/stories/in-progress/STORY-042-foo.md
+  ratify docs/stories/in-progress/STORY-042-foo.md
+  printf -- '\nA substance edit made after ratification.\n' >> docs/stories/in-progress/STORY-042-foo.md
+  env_cmd 'git commit -m "fix: thing
+
+Refs: STORY-042"'
+  run bash -c "bash '$HOOK' < env.json"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -q '"permissionDecision": "deny"'
+}
+
+@test "ticking an acceptance criterion is progress, not drift — commit still allowed" {
+  cat > docs/stories/in-progress/STORY-042-foo.md <<'EOF'
+---
+status: in-progress
+---
+
+# STORY-042
+
+## Acceptance criteria (accepted-gate, INVEST Testable)
+
+- [ ] The step happens.
+EOF
+  ratify docs/stories/in-progress/STORY-042-foo.md
+  sed -i.bak 's/- \[ \] The step happens./- [x] The step happens./' docs/stories/in-progress/STORY-042-foo.md
+  rm -f docs/stories/in-progress/*.bak
+  env_cmd 'git commit -m "fix: thing
+
+Refs: STORY-042"'
+  run bash -c "bash '$HOOK' < env.json"
+  [ "$status" -eq 0 ]
+  ! echo "$output" | grep -q 'deny'
+}
+
+@test "ADR-101: a pure-decomposition story whose basis no longer matches its criteria is blocked" {
+  cat > docs/stories/accepted/STORY-042-foo.md <<'EOF'
+---
+status: accepted
+afk-accept: pure-decomposition
+---
+
+# STORY-042
+
+## Acceptance criteria (accepted-gate, INVEST Testable)
+
+- [ ] One.
+- [ ] Two.
+
+## Decomposition basis
+
+- One decomposes ADR-900.
+EOF
+  bash "$MARK" --pure-decomposition docs/stories/accepted/STORY-042-foo.md >/dev/null 2>&1
+  env_cmd 'git commit -m "fix: thing
+
+Refs: STORY-042"'
+  run bash -c "bash '$HOOK' < env.json"
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -q '"permissionDecision": "deny"'
+  echo "$output" | grep -q 'Decomposition basis'
+}
+
+@test "ADR-101: a well-formed pure-decomposition story is allowed" {
+  cat > docs/stories/accepted/STORY-042-foo.md <<'EOF'
+---
+status: accepted
+afk-accept: pure-decomposition
+---
+
+# STORY-042
+
+## Acceptance criteria (accepted-gate, INVEST Testable)
+
+- [ ] One.
+- [ ] Two.
+
+## Decomposition basis
+
+- One decomposes ADR-900.
+- Two decomposes ADR-900.
+EOF
+  bash "$MARK" --pure-decomposition docs/stories/accepted/STORY-042-foo.md >/dev/null 2>&1
+  env_cmd 'git commit -m "fix: thing
+
+Refs: STORY-042"'
+  run bash -c "bash '$HOOK' < env.json"
+  [ "$status" -eq 0 ]
+  ! echo "$output" | grep -q 'deny'
+}
+
+@test "a DONE story is past implementation and is not ratification-gated" {
+  mkdir -p docs/stories/done
+  touch docs/stories/done/STORY-042-foo.md
   env_cmd 'git commit -m "fix: thing
 
 Refs: STORY-042"'

package/lib/story-oversight.sh

@@ -25,11 +25,64 @@ oversight_content_hash() {
   # ONLY a SUBSTANCE change re-opens ratification. Ticking a criterion or advancing
   # status/slice-progress is progress, not a change to what the user ratified; the
   # value statement, criterion TEXT, and structure still drift the hash.
-  grep -vE '^(human-oversight|oversight-hash|status):|<meta[^>]*name="(human-oversight|oversight-hash|status)"' "$1" \
+  grep -vE '^(human-oversight|oversight-hash|oversight-basis|status):|<meta[^>]*name="(human-oversight|oversight-hash|oversight-basis|status)"' "$1" \
     | sed -E 's/- \[[ xX]\]/- [ ]/g; s/data-status="[^"]*"/data-status=""/g' \
     | shasum -a 256 | awk '{print $1}'
 }
 
+# Hash a story MAP's content while EXCLUDING the single-line card elements whose
+# data-story-id is in the caller-supplied set (ADR-101 condition (a), map leg).
+#
+# ADR-095 requires story-map membership at capture, so authoring a story ALWAYS
+# adds a card to its map — which, under ADR-090 drift-invalidation, re-opens the
+# map's ratification by construction. Requiring a hash-matching map would make
+# the AFK-accept carve-out unsatisfiable: capturing the story would break the
+# very condition the story must satisfy.
+#
+# This COARSENS the drift trigger to a coherent edit-set — the remedy ADR-090's
+# own Reassessment Criteria authorises — rather than dropping to write-once,
+# which ADR-090 explicitly forbids. Any map edit OTHER than adding the named
+# cards still drifts the hash, so the condition stays load-bearing.
+oversight_content_hash_excluding_stories() {
+  local f="$1"; shift
+  local filtered id
+  filtered="$(cat "$f")"
+  for id in "$@"; do
+    [ -n "$id" ] || continue
+    # Anchored on the closing quote so STORY-05 cannot strip STORY-054's card.
+    filtered="$(printf '%s\n' "$filtered" | grep -vF "data-story-id=\"${id}\"" || true)"
+  done
+  printf '%s\n' "$filtered" \
+    | grep -vE '^(human-oversight|oversight-hash|oversight-basis|status):|<meta[^>]*name="(human-oversight|oversight-hash|oversight-basis|status)"' \
+    | sed -E 's/- \[[ xX]\]/- [ ]/g; s/data-status="[^"]*"/data-status=""/g' \
+    | shasum -a 256 | awk '{print $1}'
+}
+
+# True (0) if this artefact's `confirmed` marker was written by the ADR-101 AFK
+# pure-decomposition carve-out rather than by a human ratification event.
+# BSD grep has no \s — use [[:space:]] (the P334 portability class).
+oversight_is_pure_decomposition() {
+  grep -qE '^oversight-basis:[[:space:]]*pure-decomposition([[:space:]]|$)' "$1" 2>/dev/null
+}
+
+# True (0) if the story DECLARES itself eligible for the ADR-101 carve-out.
+# Unlike `oversight-basis:` (marker-adjacent, excluded from the hash), this is an
+# AUTHORED claim and stays INSIDE the hash — editing it re-opens ratification,
+# and it cannot be stripped to hide the story from the post-hoc drain.
+oversight_declares_pure_decomposition() {
+  grep -qE '^afk-accept:[[:space:]]*pure-decomposition([[:space:]]|$)' "$1" 2>/dev/null
+}
+
+# ADR-101 map leg. Satisfied when the map is fully ratified (card already present
+# at ratification time), OR when it is `confirmed` and its stored hash matches the
+# content hash with THIS story's card excluded (card added after ratification).
+oversight_map_leg_ok() {
+  local map="$1" story_id="$2"
+  is_story_map_ratified "$map" && return 0
+  oversight_is_confirmed "$map" || return 1
+  [ "$(oversight_stored_hash "$map")" = "$(oversight_content_hash_excluding_stories "$map" "$story_id")" ]
+}
+
 # Echo the stored oversight-hash (md frontmatter OR HTML meta), empty if none.
 oversight_stored_hash() {
   local h

package/package.json

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

package/scripts/check-afk-accept-eligible.sh

@@ -0,0 +1,230 @@
+#!/usr/bin/env bash
+# check-afk-accept-eligible.sh — ADR-101 AFK pure-decomposition carve-out.
+#
+# Decides whether an AFK loop may transition a story `draft -> accepted` with a
+# machine-written `human-oversight: confirmed` marker, and implement it, WITHOUT
+# a fresh human ratification. Opt-in and fail-closed: absent the project opt-in
+# or the story's own declaration, the answer is always "not eligible".
+#
+# Eligible IFF the project has opted in AND the story declares
+# `afk-accept: pure-decomposition` AND both conditions hold:
+#
+#   (a) PARENT SUBSTANCE CONFIRMED — every `adrs:` / `jtbd:` entry resolves and
+#       carries `human-oversight: confirmed` (persona too); every `rfcs:` entry
+#       resolves and every ADR in THAT RFC's `adrs:` is confirmed; every
+#       `problems:` entry resolves; every `story-maps:` entry satisfies the
+#       ADR-101 map leg (fully ratified, OR confirmed with this story's own card
+#       excluded from the hash — ADR-095 compels that card, so it cannot be the
+#       thing that disqualifies the story). Map LIFECYCLE status is out of scope.
+#       The RFC tier holds no independent decisions per ADR-070 and so has no
+#       oversight marker of its own; condition (a) proxies through its `adrs:`.
+#
+#   (b) NO NEW SUBSTANCE, ESTABLISHED POSITIVELY — a whitelist, not a novelty
+#       blacklist, because "introduces no new design choice" is a negative
+#       existential an agent cannot discharge. `## Decomposition basis` must
+#       carry exactly one entry per acceptance criterion, each naming the
+#       artefact whose already-confirmed clause that criterion decomposes, and
+#       every cited ID must be a member of the set (a) PROVED ratified —
+#       frontmatter membership is not ratification. Zero criteria is FAIL-CLOSED.
+#       A secondary blacklist rejects open-decision markers outside fenced or
+#       backticked spans.
+#
+# The failure direction is deliberate: conservatively hold a genuine
+# decomposition rather than silently accept an embedded decision.
+#
+# Usage: check-afk-accept-eligible.sh <story-file> [maps-root] [rfcs-root]
+#                                     [jtbd-root] [problems-root] [decisions-root]
+# Exit:  0 = eligible; 1 = not eligible (reasons on stderr); 2 = usage / file error.
+#
+# @adr ADR-101 (AFK pure-decomposition carve-out) ADR-090 (drift-invalidated
+#      oversight) ADR-095 ADR-096 ADR-060 ADR-070 ADR-098 (config shape)
+#      ADR-013 (Rule 6) ADR-052 (behavioural bats)
+# @problem P456 (AFK iter cannot land a fix) P465 (accepted gate unenforced)
+# @jtbd JTBD-006 (Progress the Backlog While I'm Away)
+# @jtbd JTBD-003 (Compose Only the Guardrails I Need)
+set -uo pipefail
+
+# Adopter-safe: source the shared lazy-fingerprint lib RELATIVE TO THIS SCRIPT
+# (P317), never repo-relative.
+LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" 2>/dev/null && pwd)" || {
+  echo "check-afk-accept-eligible: cannot locate lib dir" >&2; exit 2; }
+# shellcheck source=/dev/null
+source "$LIB/story-oversight.sh"
+
+story="${1:-}"
+maps_root="${2:-docs/story-maps}"
+rfcs_root="${3:-docs/rfcs}"
+jtbd_root="${4:-docs/jtbd}"
+problems_root="${5:-docs/problems}"
+decisions_root="${6:-docs/decisions}"
+
+if [ -z "$story" ]; then
+  echo "check-afk-accept-eligible: usage: check-afk-accept-eligible.sh <story-file> [maps-root] [rfcs-root] [jtbd-root] [problems-root] [decisions-root]" >&2
+  exit 2
+fi
+[ -f "$story" ] || { echo "check-afk-accept-eligible: file not found: $story" >&2; exit 2; }
+
+fail() { echo "check-afk-accept-eligible: NOT ELIGIBLE — $1" >&2; exit 1; }
+
+# --- Project opt-in (ADR-101 split; config shape mirrors ADR-098) ------------
+# Resolution FAILS OPEN to the built-in default (this never errors); because the
+# built-in default is `false`, the POLICY outcome of every degraded path — no
+# jq, no file, unreadable, unparseable, non-boolean — is not-eligible.
+# Env trumps both files: a loosening override for bats and one-off use, NOT a
+# project-configuration surface.
+afk_accept_enabled() {
+  local v
+  case "${WR_ITIL_AFK_ACCEPT:-}" in
+    1|true) return 0 ;;
+    0|false) return 1 ;;
+  esac
+  command -v jq >/dev/null 2>&1 || return 1
+  for cfg in ".claude/itil.config.json" "$HOME/.claude/itil.config.json"; do
+    [ -r "$cfg" ] || continue
+    # Per-KEY fallback per ADR-098: a project file that simply omits the key
+    # must not strand the machine layer. Only a file that actually sets it
+    # decides the answer.
+    jq -e 'has("afk_accept_pure_decomposition")' "$cfg" >/dev/null 2>&1 || continue
+    # Strict: only the literal JSON `true` enables. The string form, 1, yes and
+    # null do not — a typo must never open a permission-loosening carve-out.
+    v="$(jq -r 'if .afk_accept_pure_decomposition == true then "true" else "false" end' "$cfg" 2>/dev/null || echo false)"
+    [ "$v" = "true" ] && return 0
+    return 1
+  done
+  return 1
+}
+
+afk_accept_enabled || fail "the project has not opted in to the ADR-101 carve-out (set \"afk_accept_pure_decomposition\": true in .claude/itil.config.json)"
+
+# --- Declaration ------------------------------------------------------------
+oversight_declares_pure_decomposition "$story" \
+  || fail "$story does not declare \`afk-accept: pure-decomposition\` — the carve-out is opt-in per story, never a default"
+
+story_id="$(basename "$story" | grep -oE 'STORY-[0-9]+' | head -1)"
+[ -n "$story_id" ] || fail "cannot resolve a STORY-NNN id from $story"
+
+# Read one frontmatter list field (inline `[A, B]` or block `- A` form).
+trace_ids() {
+  local field="$1" line ids
+  line="$(awk -v f="^${field}:" '$0 ~ f {print; exit}' "$story")"
+  ids="$(printf '%s' "$line" | grep -oE '(ADR|JTBD|RFC|STORY-MAP|P)-?[0-9]+' || true)"
+  if [ -z "$ids" ]; then
+    ids="$(awk -v f="^${field}:" '$0 ~ f {g=1;next} g&&/^[[:space:]]*-/{print} g&&/^[^[:space:]-]/{exit}' "$story" \
+      | grep -oE '(ADR|JTBD|RFC|STORY-MAP|P)-?[0-9]+' || true)"
+  fi
+  printf '%s' "$ids"
+}
+
+# The set condition (a) PROVES ratified. Condition (b) intersects against this,
+# so a basis entry can never cite an artefact (a) never verified (B4).
+RATIFIED_SET=""
+add_ratified() { RATIFIED_SET="$RATIFIED_SET $1"; }
+
+# (a) ADR parents — write-once oversight per ADR-066.
+for id in $(trace_ids adrs); do
+  n="${id#ADR-}"
+  f="$(ls "$decisions_root"/"$n"-*.md 2>/dev/null | head -1)"
+  [ -n "$f" ] || fail "$id does not resolve under $decisions_root — a new decision is new substance"
+  oversight_is_confirmed "$f" || fail "$id is not \`human-oversight: confirmed\` — condition (a) requires every parent decision be human-confirmed"
+  add_ratified "$id"
+done
+
+# (a) JTBD parents + their personas — ADR-068 oversight sibling.
+for id in $(trace_ids jtbd); do
+  n="${id#JTBD-}"
+  f="$(ls "$jtbd_root"/*/"JTBD-$n"-*.md 2>/dev/null | head -1)"
+  [ -n "$f" ] || fail "$id does not resolve under $jtbd_root — a new job is new substance"
+  oversight_is_confirmed "$f" || fail "$id is not \`human-oversight: confirmed\`"
+  p="$(dirname "$f")/persona.md"
+  if [ -f "$p" ]; then
+    oversight_is_confirmed "$p" || fail "the persona for $id ($p) is not \`human-oversight: confirmed\` — a new or unconfirmed persona is new substance"
+  fi
+  add_ratified "$id"
+done
+
+# (a) RFC parents — no oversight tier of their own (ADR-070); proxy via `adrs:`.
+for id in $(trace_ids rfcs); do
+  n="${id#RFC-}"
+  f="$(ls "$rfcs_root"/"RFC-$n"-*.md 2>/dev/null | head -1)"
+  [ -n "$f" ] || fail "$id does not resolve under $rfcs_root"
+  rfc_adrs="$(awk '/^adrs:/{print; exit}' "$f" | grep -oE 'ADR-[0-9]+' || true)"
+  for a in $rfc_adrs; do
+    af="$(ls "$decisions_root"/"${a#ADR-}"-*.md 2>/dev/null | head -1)"
+    [ -n "$af" ] || fail "$id depends on $a which does not resolve under $decisions_root"
+    oversight_is_confirmed "$af" || fail "$id depends on $a which is not \`human-oversight: confirmed\`"
+    add_ratified "$a"
+  done
+  add_ratified "$id"
+done
+
+# (a) Problem parents — resolve only; problems carry no oversight tier.
+for id in $(trace_ids problems); do
+  n="${id#P}"
+  f="$(ls "$problems_root"/"$n"-*.md "$problems_root"/*/"$n"-*.md 2>/dev/null | head -1)"
+  [ -n "$f" ] || fail "$id does not resolve under $problems_root"
+  add_ratified "$id"
+done
+
+# (a) Story-map parents — the ADR-101 map leg.
+for id in $(trace_ids story-maps); do
+  n="${id#STORY-MAP-}"
+  f="$(ls "$maps_root"/*/"STORY-MAP-$n"-*.html 2>/dev/null | head -1)"
+  [ -n "$f" ] || fail "$id does not resolve under $maps_root"
+  oversight_map_leg_ok "$f" "$story_id" \
+    || fail "$id fails the ADR-101 map leg — it is not human-confirmed, or it has drifted for a reason other than adding ${story_id}'s own card. Ratify the map."
+  add_ratified "$id"
+done
+
+# --- (b) NO NEW SUBSTANCE, established positively ---------------------------
+# Acceptance criteria: prefix-anchored section (headings carry trailing
+# qualifiers like `(accepted-gate, INVEST Testable)`), terminated by the next
+# `##`. Tick-insensitive so implementation progress never flips the check, and
+# the criterion literal is aligned with oversight_content_hash's normaliser so
+# every counted line is a normalised line.
+section_of() {
+  awk -v h="$1" '
+    $0 ~ h {inside=1; next}
+    inside && /^##[[:space:]]/ {exit}
+    inside {print}
+  ' "$story"
+}
+
+# NO `\b` IN THESE ANCHORS, and do not re-add it. Two independent reasons:
+# (1) awk escape-processes a `-v` assignment value, so `\b` arrives as a literal
+#     BACKSPACE (0x08) — the pattern then never matches a real heading, which
+#     silently makes this whole check inert. It fails CLOSED, so there is no
+#     permission hole, but the carve-out can never return eligible for anyone.
+# (2) POSIX ERE has no `\b` at all, so it is equally wrong in the commit-locus
+#     copy of this count in itil-no-implement-draft-gate.sh, where the failure
+#     would be silent in a different way. Those two loci MUST stay aligned.
+# Prefix matching is the documented intent anyway (ADR-101): corpus headings
+# carry trailing qualifiers like `(accepted-gate, INVEST Testable)`.
+criteria_count="$(section_of '^##[[:space:]]+Acceptance criteria' | grep -cE '^- \[[ xX]\]' || true)"
+[ "${criteria_count:-0}" -gt 0 ] \
+  || fail "no top-level \`- [ ]\` criterion lines found in the acceptance-criteria section — condition (b) is fail-closed on zero, since an absent section is indistinguishable from absent criteria"
+
+basis="$(section_of '^##[[:space:]]+Decomposition basis')"
+[ -n "$(printf '%s' "$basis" | tr -d '[:space:]')" ] \
+  || fail "\`## Decomposition basis\` is missing or empty — condition (b) requires each criterion to name the already-confirmed clause it decomposes"
+
+basis_count="$(printf '%s\n' "$basis" | grep -cE '^- ' || true)"
+[ "${basis_count:-0}" -eq "$criteria_count" ] \
+  || fail "\`## Decomposition basis\` has $basis_count entries but there are $criteria_count acceptance criteria — every criterion must name the confirmed clause it decomposes"
+
+# Every cited ID must be in the set condition (a) proved ratified (B4).
+for cited in $(printf '%s' "$basis" | grep -oE '(ADR|JTBD|RFC|STORY-MAP)-[0-9]+' | sort -u); do
+  case " $RATIFIED_SET " in
+    *" $cited "*) ;;
+    *) fail "\`## Decomposition basis\` cites $cited, which condition (a) never verified as ratified — cite only traced, confirmed parents" ;;
+  esac
+done
+
+# Secondary blacklist. Fenced and backticked spans are stripped first so a story
+# may DESCRIBE the blocked vocabulary (this one does) without tripping on it.
+prose="$(awk '/^```/{f=!f;next} !f' "$story" | sed -E 's/`[^`]*`//g')"
+if printf '%s' "$prose" | grep -qiE '\[Unratified Dependency\]|\bTBD\b|to be decided|open question|decision needed'; then
+  fail "an open-decision marker appears outside a fenced or backticked span — the story is not pure decomposition"
+fi
+
+echo "check-afk-accept-eligible: ELIGIBLE — $story_id is pure decomposition of confirmed substance ($criteria_count criteria, all basis citations ratified)" >&2
+exit 0

package/scripts/detect-unratified-stories-maps.sh

@@ -11,7 +11,15 @@
 #   - drift-reopened   (marker says confirmed, but content changed → hash mismatch)
 #   - legacy confirmed  (confirmed but no fingerprint yet — needs one re-ratify)
 #
-# Usage: detect-unratified-stories-maps.sh [STORIES_DIR=docs/stories] [MAPS_DIR=docs/story-maps]
+# With `--with-afk-accepted` (ADR-101) it ALSO lists, on stderr, stories whose
+# `confirmed` marker was machine-written by the AFK pure-decomposition carve-out
+# rather than by a human — they are awaiting post-hoc human ratification. The
+# listing keys on the UNION of `afk-accept:` and `oversight-basis:`, because the
+# latter is excluded from the content hash and could otherwise be stripped to
+# hide a machine-accepted story from this drain; `afk-accept:` stays in the hash.
+# stdout is untouched by the flag, so the Step 2.4 drain consumer is unaffected.
+#
+# Usage: detect-unratified-stories-maps.sh [--with-afk-accepted] [STORIES_DIR=docs/stories] [MAPS_DIR=docs/story-maps]
 # Output: one unratified artefact path per line, sorted. Empty = all ratified.
 # Always exits 0 (detector, not a gate). Consumed by the work-problems Step 2.4
 # oversight-unconfirmed drain.
@@ -23,6 +31,12 @@ LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" 2>/dev/null && pwd)" || {
 # shellcheck source=/dev/null
 source "$LIB/story-oversight.sh"
 
+WITH_AFK=0
+if [ "${1:-}" = "--with-afk-accepted" ]; then
+  WITH_AFK=1
+  shift
+fi
+
 STORIES_DIR="${1:-docs/stories}"
 MAPS_DIR="${2:-docs/story-maps}"
 
@@ -42,4 +56,14 @@ shopt -s nullglob
   fi
 } | sort
 
+# ADR-101 post-hoc drain — stderr only, so the stdout path contract is preserved.
+if [ "$WITH_AFK" = "1" ] && [ -d "$STORIES_DIR" ]; then
+  for f in "$STORIES_DIR"/*.md "$STORIES_DIR"/*/*.md; do
+    [ "$(basename "$f")" = "README.md" ] && continue
+    if oversight_declares_pure_decomposition "$f" || oversight_is_pure_decomposition "$f"; then
+      echo "AFK-ACCEPTED (awaiting post-hoc human ratification): $f" >&2
+    fi
+  done
+fi
+
 exit 0

package/scripts/mark-story-oversight-confirmed.sh

@@ -8,10 +8,19 @@
 # stored fingerprint no longer matches → the artefact reads as drifted /
 # unratified until re-ratified (ADR-090 drift-invalidation).
 #
-# Usage: mark-story-oversight-confirmed.sh <story-or-map-file>
+# With `--pure-decomposition` (ADR-101) it additionally records
+# `oversight-basis: pure-decomposition` — the marker was written by an AFK loop
+# under the carve-out, not by a human ratification event. That field is
+# markdown-story-only (a map is always human-ratified and never carries a
+# decomposition basis) and is EXCLUDED from the content hash, exactly like
+# `oversight-hash`; the authored `afk-accept:` declaration stays INSIDE the hash.
+# Without the flag the basis line is dropped, so re-ratifying by hand clears a
+# stale basis rather than leaving a human-ratified story labelled AFK-accepted.
+#
+# Usage: mark-story-oversight-confirmed.sh [--pure-decomposition] <story-or-map-file>
 # Exit:  0 = ratified; 2 = usage / file error.
 #
-# Authority: ADR-090. Driver: P404 Phase 2. Test: mark-story-oversight-confirmed.bats.
+# Authority: ADR-090, ADR-101. Driver: P404 Phase 2, P456. Test: mark-story-oversight-confirmed.bats.
 set -euo pipefail
 
 # Adopter-safe: source the shared hash lib RELATIVE TO THIS SCRIPT (P317), never
@@ -21,9 +30,15 @@ LIB="$(cd "$(dirname "${BASH_SOURCE[0]}")/../lib" 2>/dev/null && pwd)" || {
 # shellcheck source=/dev/null
 source "$LIB/story-oversight.sh"
 
+basis=""
+if [ "${1:-}" = "--pure-decomposition" ]; then
+  basis="pure-decomposition"
+  shift
+fi
+
 f="${1:-}"
 if [ -z "$f" ]; then
-  echo "mark-story-oversight-confirmed: usage: mark-story-oversight-confirmed.sh <file>" >&2
+  echo "mark-story-oversight-confirmed: usage: mark-story-oversight-confirmed.sh [--pure-decomposition] <file>" >&2
   exit 2
 fi
 [ -f "$f" ] || { echo "mark-story-oversight-confirmed: file not found: $f" >&2; exit 2; }
@@ -54,12 +69,13 @@ case "$f" in
   *)
     # Markdown: rewrite frontmatter — drop existing markers, insert both before
     # the closing `---`.
-    awk -v H="$h" '
+    awk -v H="$h" -v B="$basis" '
       NR==1 && $0=="---" { infm=1; print; next }
-      infm && /^(human-oversight|oversight-hash):/ { next }
+      infm && /^(human-oversight|oversight-hash|oversight-basis):/ { next }
       infm && /^---[[:space:]]*$/ && !done {
         print "human-oversight: confirmed"
         print "oversight-hash: " H
+        if (B != "") print "oversight-basis: " B
         print; done=1; infm=0; next
       }
       { print }

package/scripts/test/check-afk-accept-eligible.bats

@@ -0,0 +1,310 @@
+#!/usr/bin/env bats
+# Behavioural tests for check-afk-accept-eligible.sh (ADR-101 / P456 / P465).
+# Each case maps onto an ADR-101 Confirmation item. Behavioural, not structural:
+# every test runs the real script against a real fixture tree and asserts on its
+# exit status and stderr, never on its source text (ADR-052 / P081).
+#
+# The POSITIVE case is the load-bearing one. An earlier revision shipped an
+# `awk -v` escape bug that made the checker permanently inert — it fails closed,
+# so no negative test could ever have caught it. Only asserting that a
+# well-formed story IS eligible surfaces that class of bug.
+#
+# @adr ADR-101 ADR-090 ADR-095 ADR-096 ADR-098 ADR-052  @problem P456 P465
+
+setup() {
+  SCRIPTS="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)"
+  CHECK="$SCRIPTS/check-afk-accept-eligible.sh"
+  MARK="$SCRIPTS/mark-story-oversight-confirmed.sh"
+  TMP="$(mktemp -d)"; cd "$TMP"
+  mkdir -p docs/stories/draft docs/story-maps/draft docs/rfcs docs/jtbd/dev docs/problems/open docs/decisions
+  export HOME="$TMP/home"; mkdir -p "$HOME/.claude"
+
+  # --- confirmed parents -----------------------------------------------------
+  printf -- '---\nhuman-oversight: confirmed\n---\n\n# ADR-900\n' > docs/decisions/900-a-confirmed-decision.proposed.md
+  printf -- '---\nhuman-oversight: confirmed\n---\n\n# JTBD-900\n' > docs/jtbd/dev/JTBD-900-a-job.proposed.md
+  printf -- '---\nhuman-oversight: confirmed\n---\n\n# persona\n' > docs/jtbd/dev/persona.md
+  printf -- '---\nadrs: [ADR-900]\n---\n\n# RFC-900\n' > docs/rfcs/RFC-900-a-vehicle.proposed.md
+  printf -- '# P900\n' > docs/problems/open/900-a-problem.md
+
+  # A map that was ratified BEFORE the story's card was added — the common case,
+  # since ADR-095 compels the card at capture.
+  MAP=docs/story-maps/draft/STORY-MAP-900-a-map.html
+  printf '<html><head>\n<a class="slice" data-story-id="STORY-800">old</a>\n</head></html>\n' > "$MAP"
+  bash "$MARK" "$MAP" 2>/dev/null
+  # Now add STORY-901's card, drifting the map exactly as capture would.
+  python3 - "$MAP" <<'PY'
+import sys
+p=sys.argv[1]; s=open(p).read()
+open(p,"w").write(s.replace('</head>','  <a class="slice" data-story-id="STORY-901">new</a>\n</head>'))
+PY
+
+  export WR_ITIL_AFK_ACCEPT=1
+}
+teardown() { cd /; rm -rf "$TMP"; }
+
+# A well-formed pure-decomposition story: 2 criteria, 2 basis entries, all
+# citations traced and confirmed.
+seed_story() {
+  cat > docs/stories/draft/STORY-901-a-story.md <<'EOF'
+---
+status: draft
+problems: [P900]
+jtbd: [JTBD-900]
+rfcs: [RFC-900]
+story-maps: [STORY-MAP-900]
+adrs: [ADR-900]
+afk-accept: pure-decomposition
+---
+
+# STORY-901: A story
+
+## User value
+
+In order to land confirmed work, as a developer, I want the loop to proceed.
+
+## Acceptance criteria (accepted-gate, INVEST Testable)
+
+- [ ] The first step happens.
+- [ ] The second step happens.
+
+## Decomposition basis
+
+- Criterion 1 decomposes ADR-900's rule about the first step.
+- Criterion 2 decomposes ADR-900's rule about the second step.
+EOF
+}
+run_check() { run bash "$CHECK" docs/stories/draft/STORY-901-a-story.md \
+  docs/story-maps docs/rfcs docs/jtbd docs/problems docs/decisions; }
+
+# --- ADR-101 Confirmation: eligibility ---------------------------------------
+
+@test "ELIGIBLE: pure-decomposition story whose parents are all confirmed" {
+  seed_story; run_check
+  [ "$status" -eq 0 ]
+  echo "$output" | grep -q 'ELIGIBLE'
+}
+
+@test "NOT eligible: a traced ADR parent is unconfirmed" {
+  seed_story
+  printf -- '---\nhuman-oversight: unconfirmed\n---\n\n# ADR-900\n' > docs/decisions/900-a-confirmed-decision.proposed.md
+  run_check
+  [ "$status" -eq 1 ]
+  echo "$output" | grep -q 'ADR-900'
+}
+
+@test "NOT eligible: a traced JTBD's persona is unconfirmed" {
+  seed_story
+  printf -- '---\nhuman-oversight: unconfirmed\n---\n\n# persona\n' > docs/jtbd/dev/persona.md
+  run_check
+  [ "$status" -eq 1 ]
+  echo "$output" | grep -qi 'persona'
+}
+
+@test "NOT eligible: a traced artefact does not resolve (new substance)" {
+  seed_story
+  rm docs/decisions/900-a-confirmed-decision.proposed.md
+  run_check
+  [ "$status" -eq 1 ]
+}
+
+@test "NOT eligible: basis entries do not match the criteria count" {
+  seed_story
+  printf -- '- [ ] A third step nobody accounted for.\n' >> docs/stories/draft/STORY-901-a-story.md
+  run_check
+  [ "$status" -eq 1 ]
+  echo "$output" | grep -q 'Decomposition basis'
+}
+
+@test "NOT eligible: basis cites an artefact condition (a) never verified" {
+  seed_story
+  sed -i.bak 's/ADR-900.s rule about the first step/ADR-999 rule about the first step/' docs/stories/draft/STORY-901-a-story.md
+  run_check
+  [ "$status" -eq 1 ]
+  echo "$output" | grep -q 'ADR-999'
+}
+
+@test "NOT eligible: the story does not declare the carve-out" {
+  seed_story
+  sed -i.bak '/^afk-accept:/d' docs/stories/draft/STORY-901-a-story.md
+  run_check
+  [ "$status" -eq 1 ]
+  echo "$output" | grep -q 'afk-accept'
+}
+
+@test "NOT eligible: no acceptance criteria at all (fail-closed on zero)" {
+  seed_story
+  sed -i.bak 's/^- \[ \] The first step happens.//; s/^- \[ \] The second step happens.//' docs/stories/draft/STORY-901-a-story.md
+  run_check
+  [ "$status" -eq 1 ]
+}
+
+# --- ADR-101 Confirmation: the secondary blacklist ---------------------------
+
+@test "NOT eligible: an open-decision marker in ordinary prose" {
+  seed_story
+  printf -- '\nThe storage locus is still to be decided.\n' >> docs/stories/draft/STORY-901-a-story.md
+  run_check
+  [ "$status" -eq 1 ]
+}
+
+@test "ELIGIBLE: the same vocabulary inside a fenced or backticked span" {
+  seed_story
+  printf -- '\nThe checker rejects the phrase `to be decided` when it appears in prose:\n\n```\nopen question / TBD / decision needed\n```\n' \
+    >> docs/stories/draft/STORY-901-a-story.md
+  run_check
+  [ "$status" -eq 0 ]
+}
+
+# --- ADR-101 Confirmation: the map leg disjunction ---------------------------
+
+@test "ELIGIBLE: map re-ratified WITH the story's card already present" {
+  seed_story
+  bash "$MARK" "$MAP" 2>/dev/null   # re-ratify now that STORY-901's card exists
+  run_check
+  [ "$status" -eq 0 ]
+}
+
+@test "NOT eligible: map drifted for a reason OTHER than the story's own card" {
+  seed_story
+  printf '<p>an unrelated edit</p>\n' >> "$MAP"
+  run_check
+  [ "$status" -eq 1 ]
+  echo "$output" | grep -q 'STORY-MAP-900'
+}
+
+@test "NOT eligible: map carries no human-oversight marker at all" {
+  seed_story
+  grep -v 'oversight' "$MAP" > "$MAP.tmp" && mv "$MAP.tmp" "$MAP"
+  run_check
+  [ "$status" -eq 1 ]
+}
+
+# --- ADR-101 Confirmation: the opt-in split ----------------------------------
+
+@test "NOT eligible without opt-in, even when (a) and (b) both hold" {
+  seed_story
+  unset WR_ITIL_AFK_ACCEPT
+  run_check
+  [ "$status" -eq 1 ]
+  echo "$output" | grep -q 'opted in'
+}
+
+@test "project config opts in" {
+  seed_story
+  unset WR_ITIL_AFK_ACCEPT
+  mkdir -p .claude
+  printf '{ "afk_accept_pure_decomposition": true }\n' > .claude/itil.config.json
+  run_check
+  [ "$status" -eq 0 ]
+}
+
+@test "a non-boolean config value does NOT opt in" {
+  seed_story
+  unset WR_ITIL_AFK_ACCEPT
+  mkdir -p .claude
+  printf '{ "afk_accept_pure_decomposition": "true" }\n' > .claude/itil.config.json
+  run_check
+  [ "$status" -eq 1 ]
+}
+
+@test "an unparseable config does NOT opt in" {
+  seed_story
+  unset WR_ITIL_AFK_ACCEPT
+  mkdir -p .claude
+  printf 'not json at all\n' > .claude/itil.config.json
+  run_check
+  [ "$status" -eq 1 ]
+}
+
+@test "ADR-098 per-key fallback: a project file omitting the key falls through to machine" {
+  seed_story
+  unset WR_ITIL_AFK_ACCEPT
+  mkdir -p .claude
+  printf '{ "some_other_key": 1 }\n' > .claude/itil.config.json
+  printf '{ "afk_accept_pure_decomposition": true }\n' > "$HOME/.claude/itil.config.json"
+  run_check
+  [ "$status" -eq 0 ]
+}
+
+@test "a project file setting the key FALSE wins over a machine TRUE" {
+  seed_story
+  unset WR_ITIL_AFK_ACCEPT
+  mkdir -p .claude
+  printf '{ "afk_accept_pure_decomposition": false }\n' > .claude/itil.config.json
+  printf '{ "afk_accept_pure_decomposition": true }\n' > "$HOME/.claude/itil.config.json"
+  run_check
+  [ "$status" -eq 1 ]
+}
+
+@test "jq absent resolves to the built-in default: NOT eligible" {
+  seed_story
+  unset WR_ITIL_AFK_ACCEPT
+  mkdir -p .claude bin
+  printf '{ "afk_accept_pure_decomposition": true }\n' > .claude/itil.config.json
+  run env PATH="/usr/bin:/bin" bash "$CHECK" docs/stories/draft/STORY-901-a-story.md \
+    docs/story-maps docs/rfcs docs/jtbd docs/problems docs/decisions
+  # Only meaningful where jq is genuinely off PATH; skip otherwise.
+  if PATH="/usr/bin:/bin" command -v jq >/dev/null 2>&1; then skip "jq is on the minimal PATH here"; fi
+  [ "$status" -eq 1 ]
+}
+
+# --- ADR-101 Confirmation: no automated path writes a `true` opt-in ----------
+
+@test "no shipped installer or scaffold writes an opt-in value" {
+  # The guard that keeps opt-in from becoming opt-out-by-stealth. Any shipped
+  # code that WRITES this key would defeat the split; reading it is fine.
+  cd "$(dirname "$CHECK")/.."
+  # Guard the search roots. Pointed at a directory that does not exist, grep
+  # matches nothing and the assertion below passes for the wrong reason — and
+  # whether it passes at all then depends on which grep merges its warning into
+  # bats' $output.
+  [ -d bin ] && [ -d hooks ]
+  run grep -rIlE 'afk_accept_pure_decomposition' --include='*.mjs' --include='*.js' bin/ hooks/
+  [ -z "$output" ]
+}
+
+# --- ADR-101 Confirmation: detector stdout contract --------------------------
+
+@test "detect-unratified-stories-maps stdout is byte-identical with and without the flag" {
+  seed_story
+  a="$(bash "$SCRIPTS/detect-unratified-stories-maps.sh" docs/stories docs/story-maps 2>/dev/null)"
+  b="$(bash "$SCRIPTS/detect-unratified-stories-maps.sh" --with-afk-accepted docs/stories docs/story-maps 2>/dev/null)"
+  [ "$a" = "$b" ]
+}
+
+@test "--with-afk-accepted surfaces the machine-accepted story on stderr" {
+  seed_story
+  run bash -c "bash '$SCRIPTS/detect-unratified-stories-maps.sh' --with-afk-accepted docs/stories docs/story-maps 2>&1 >/dev/null"
+  echo "$output" | grep -q 'STORY-901'
+  echo "$output" | grep -q 'AFK-ACCEPTED'
+}
+
+@test "the post-hoc drain still finds the story when oversight-basis is stripped" {
+  # The union key. `oversight-basis` is excluded from the content hash, so
+  # stripping it would otherwise hide a machine-accepted story from the drain;
+  # the authored `afk-accept:` declaration is inside the hash and closes that.
+  seed_story
+  bash "$MARK" --pure-decomposition docs/stories/draft/STORY-901-a-story.md 2>/dev/null
+  sed -i.bak '/^oversight-basis:/d' docs/stories/draft/STORY-901-a-story.md
+  run bash -c "bash '$SCRIPTS/detect-unratified-stories-maps.sh' --with-afk-accepted docs/stories docs/story-maps 2>&1 >/dev/null"
+  echo "$output" | grep -q 'STORY-901'
+}
+
+# --- the marker write path ---------------------------------------------------
+
+@test "--pure-decomposition records the basis AND leaves the story ratified" {
+  seed_story
+  bash "$MARK" --pure-decomposition docs/stories/draft/STORY-901-a-story.md 2>/dev/null
+  grep -q '^oversight-basis: pure-decomposition' docs/stories/draft/STORY-901-a-story.md
+  # The basis line is excluded from the hash, so the story must NOT read as
+  # drifted the instant it is marked.
+  run bash -c "source '$SCRIPTS/../lib/story-oversight.sh'; is_story_map_ratified docs/stories/draft/STORY-901-a-story.md"
+  [ "$status" -eq 0 ]
+}
+
+@test "a plain re-ratify CLEARS a stale pure-decomposition basis" {
+  seed_story
+  bash "$MARK" --pure-decomposition docs/stories/draft/STORY-901-a-story.md 2>/dev/null
+  bash "$MARK" docs/stories/draft/STORY-901-a-story.md 2>/dev/null
+  ! grep -q '^oversight-basis:' docs/stories/draft/STORY-901-a-story.md
+}

package/skills/list-stories/SKILL.md

@@ -85,8 +85,8 @@ For each `STORY-<NNN>` in the ordered list, resolve to a file under `docs/storie
 
 ## Accepted
 
-| ID | Title | Problems | JTBD | RFCs | Story Maps | Effort |
-|----|-------|----------|------|------|------------|--------|
+| ID | Title | Problems | JTBD | RFCs | Story Maps | Effort | Accepted by |
+|----|-------|----------|------|------|------------|--------|-------------|
 ...
 
 ## In Progress
@@ -102,6 +102,8 @@ For each `STORY-<NNN>` in the ordered list, resolve to a file under `docs/storie
 
 Omit empty sections rather than rendering empty headers. The Estimated Effort column is omitted from the Draft section because effort is deferred at capture and only required at accepted per I10 INVEST Estimable.
 
+**The `Accepted by` column (ADR-101, Accepted + In Progress sections only).** `accepted` carries one of two ratification bases and they must not read alike — a report that counts them together overstates how much a human has seen, which is exactly what JTBD-202's auditable-handover outcome depends on. Render `human` when the story's marker is a human ratification event, and `pure-decomposition` when it carries `oversight-basis: pure-decomposition` (machine-accepted by an opted-in project's AFK loop; awaiting post-hoc human ratification). Derive it by reading the story's `oversight-basis:` frontmatter line — its absence means `human`. Never collapse the two into a single "accepted" tick.
+
 **Filtered mode** (`--rfc RFC-<NNN>`) — render a single ordered table:
 
 ```markdown

package/skills/manage-story/SKILL.md

@@ -14,8 +14,8 @@ Per ADR-060 Phase 2 amendment 2026-05-10 lines 200-253:
 
 | Status | Filename pattern | Meaning | Entry criteria |
 |--------|-----------------|---------|----------------|
-| **draft** | `docs/stories/draft/STORY-<NNN>-<slug>.md` | Captured (problem + JTBD traces present); skeleton body | I6 + I9 satisfied at capture |
-| **accepted** | `docs/stories/accepted/STORY-<NNN>-<slug>.md` | INVEST shape verified; ready for implementation | I7 + I8 + I10 hard-block satisfied |
+| **draft** | `docs/stories/draft/STORY-<NNN>-<slug>.md` | Content-complete (map membership + real user value + ≥1 real acceptance criterion per ADR-095) but not yet accepted — `estimated-effort`/Small unset, I7 RFC trace absent, ratification pending | I6 + I8 + I9 + content floor satisfied at capture |
+| **accepted** | `docs/stories/accepted/STORY-<NNN>-<slug>.md` | INVEST shape verified; ratified; ready for implementation | I7 + I8 + I10 + I12 hard-block satisfied |
 | **in-progress** | `docs/stories/in-progress/STORY-<NNN>-<slug>.md` | Implementation underway | Auto-transitioned on first non-capture commit carrying `Refs: STORY-<NNN>` |
 | **done** | `docs/stories/done/STORY-<NNN>-<slug>.md` | All acceptance criteria ticked + linked RFC closed | Auto-transitioned (triggered by RFC close-fire or by manual `manage-story <NNN> done`) |
 | **archived** | `docs/stories/archived/STORY-<NNN>-<slug>.md` | Closed without completion (scope shifted; superseded) | Manual transition only |
@@ -30,6 +30,7 @@ Per ADR-060 Phase 2 amendment 2026-05-10 lines 200-253:
 | **I9** trace-to-JTBD | Every story traces to ≥ 1 JTBD | Hard-block at `/wr-itil:capture-story` (also verified at every transition) |
 | **I10** INVEST shape | At acceptance, INVEST behaviourally: ≥1 acceptance criterion (Testable); user-value statement (Valuable); no Blocked-by-unaccepted refs (Independent); `estimated-effort` field set (Estimable); S/M effort SHOULD; L/XL flagged decomposition-candidate (Small) | Hard-block at `manage-story <NNN> accepted` |
 | **I11** no-WSJF-leak | Phase 2: stories MUST NOT carry a WSJF field | Behavioural test at this skill (no WSJF field added/read) |
+| **I12** ratification | Every story carries a recorded ratification basis before it is implementable — a human ratification event, OR the ADR-101 pure-decomposition carve-out | Hard-block at `manage-story <NNN> accepted`; re-asserted at the commit locus by `itil-no-implement-draft-gate` |
 
 **Bootstrap-exemption marker** (per ADR-060 line 339 + ADR-053 Bootstrapping precedent): the I7/I8/I9/I10 retrofit on bootstrap-migration stories rides a one-time exemption marker `<!-- bootstrap-exempt: STORY-MAP-001 migration per ADR-060 amendment 2026-05-10 -->` inline with the frontmatter. Non-bootstrap captures with the marker fail per the behavioural test.
 
@@ -53,6 +54,7 @@ Per ADR-060 Phase 2 amendment 2026-05-10 lines 200-253:
 | Lifecycle transition validation | Mechanical: state machine — draft → accepted → in-progress → done; allow draft → archived; disallow backwards | silent-mechanical |
 | I7 + I8 hard-block at accepted | Mechanical: frontmatter `rfcs:` and `story-maps:` arrays MUST be non-empty AND each ID must resolve to a file in `docs/rfcs/` and `docs/story-maps/` | silent-mechanical |
 | I10 INVEST shape check | Mechanical: `## User value` section non-empty; `## Acceptance criteria` has ≥ 1 `- [ ]` line; `estimated-effort` field set to S/M/L/XL; L/XL flagged as decomposition-candidate (advisory, not blocking per ADR-060 line 252 architect-amendment-2026-05-10 nitpick N3) | silent-mechanical |
+| I12 ratification basis at accepted | Mechanical: the story is ratified (`human-oversight: confirmed` + a matching `oversight-hash`), OR `wr-itil-check-afk-accept-eligible` exits 0. Never an `AskUserQuestion` — the eligibility predicate is fully framework-resolved per ADR-101, and a story that fails it is HELD for the ratification drain, not asked about | silent-mechanical |
 | INVEST shape violation | Halt-with-stderr-directive listing the missing INVEST attributes; user re-invokes after editing the story body | n/a (halt) |
 | README refresh on every transition | Mechanical: regenerate `docs/stories/README.md` Story Rankings + Done tables from FS truth; stage in same commit | silent-mechanical |
 | Reverse-trace refresh on driving artefacts | Mechanical: every transition refreshes `## Stories` section on each driving problem + JTBD + RFC + story-map via the Slice 2a/2b helpers | silent-mechanical |
@@ -99,7 +101,14 @@ Use `AskUserQuestion` for direction-setting fields (e.g. `## User value` rewrite
 For any transition `<from> → <to>`:
 
 1. **Verify pre-transition invariants** for `<to>`:
-   - `accepted`: I7 + I8 + I10 hard-block (see § I-invariant table).
+   - `accepted`: I7 + I8 + I10 + **I12** hard-block (see § I-invariant table).
+
+     **I12 — the ratification gate (ADR-090 / ADR-096, enforced per ADR-101; the hole P465 named).** A story reaches `accepted` only with a recorded ratification basis. Resolve it in this order:
+
+     1. Already ratified (`human-oversight: confirmed` with a matching `oversight-hash`)? I12 satisfied; proceed.
+     2. Otherwise run `wr-itil-check-afk-accept-eligible "$story_file"`. **Exit 0** — the story is pure decomposition of confirmed substance in an opted-in project; proceed and mark it with `--pure-decomposition` at step 5 below.
+     3. **Exit 1** — HALT. Do not accept. Interactively, route to the ratify flow (§ 7.5). Under AFK, leave the story in `draft` and queue the ratification to `outstanding_questions`; do NOT ask about it, and never hand-write the marker.
+
    - `in-progress`: linked RFC status is `accepted` or `in-progress` (you can't progress a story under a proposed/closed RFC).
    - `done`: ALL `- [ ]` checkboxes in `## Acceptance criteria` are ticked (i.e. zero unticked); linked RFC status is `closed` OR the RFC's other stories have closed (transitive closure check deferred to a per-RFC `manage-rfc done-gate` check in a future slice).
    - `archived`: no invariants (manual close-without-completion).
@@ -113,6 +122,16 @@ For any transition `<from> → <to>`:
 
 4. **P057 staging-trap** — after the Edit, re-stage: `git add "docs/stories/${to_state}/STORY-${nnn}-${slug}.md"`.
 
+5. **Ratify LAST, then re-stage (ADR-101 — write ordering is load-bearing).** Only when I12 resolved via the eligibility path at step 1. Every step above writes substance — the `estimated-effort` field, the `## User value` and `## Acceptance criteria` fills — and every substance write drifts the content hash. So the ratify write MUST be the LAST write of the transition, and the file MUST be re-staged after it:
+
+   ```bash
+   export CLAUDE_SESSION_ID="${CLAUDE_SESSION_ID:?marker shims silently no-op on an empty SID (P368)}"
+   wr-itil-mark-story-oversight-confirmed --pure-decomposition "docs/stories/accepted/STORY-${nnn}-${slug}.md"
+   git add "docs/stories/accepted/STORY-${nnn}-${slug}.md"
+   ```
+
+   Get the order wrong and the marker records a hash of a file that no longer exists — the commit-locus gate then denies the very next commit, inside an AFK loop, where the recovery is itself gated. Skip the re-stage and the committed blob carries the story WITHOUT the marker while the worktree has it; the hook reads the worktree, so nothing catches it.
+
 #### Auto-transition triggers (ADR-060 line 292)
 
 The auto-transition logic fires in two contexts:
@@ -176,11 +195,13 @@ The helpers are idempotent + lazy-empty per the Slice 2a/2b/Slice 11 contract.
 
 ### 7.5. Ratification flow (`ratify`) — ADR-090 / STORY-022
 
-`ratify` confirms human oversight of a single story — **orthogonal to the `status:` lifecycle** and drift-invalidated (any later content edit re-opens it via the `oversight-hash` fingerprint). The primary ratification surface is `/wr-itil:manage-story-map <NNN> ratify` (map first, then its stories); this per-story form is for ratifying a story on its own.
+`ratify` confirms human oversight of a single story. Ratification is **not itself a lifecycle state, but it IS a precondition of `accepted`** (I12) — and it is drift-invalidated, so any later content edit re-opens it via the `oversight-hash` fingerprint. The primary ratification surface is `/wr-itil:manage-story-map <NNN> ratify` (map first, then its stories); this per-story form is for ratifying a story on its own.
+
+> This sentence previously read "orthogonal to the `status:` lifecycle", which was ambiguous between "ratification is not itself a status" (what it meant) and "ratification is not a precondition of any status" (what it read like). An agent acting on the second reading accepted and implemented an unratified story believing it compliant — the P465 failure, 2026-07-26.
 
 1. **Born-confirmed discipline (P348):** `export CLAUDE_SESSION_ID` first (the marker shim no-ops on an empty SID). Never write `confirmed` without the same-turn confirm below.
 2. **Brief + confirm:** present the story's `## User value` + `## Acceptance criteria` — substance BEFORE the ID (P350) — then `AskUserQuestion` with two options: **Ratify** / **(type something)**. On **Ratify**: run `wr-itil-mark-story-oversight-confirmed <story-file>` (writes `confirmed` + fingerprint). On free-text: apply the correction as a story edit and re-present (the edit re-opens ratification).
-3. **AFK (ADR-013 Rule 6):** if `AskUserQuestion` is unavailable, do NOT auto-ratify (hollow marker, P348) — leave it unratified for the `/wr-itil:work-problems` Step 2.4 drain.
+3. **AFK (ADR-013 Rule 6):** if `AskUserQuestion` is unavailable, do NOT auto-ratify (hollow marker, P348) — leave it unratified for the `/wr-itil:work-problems` Step 2.4 drain. **One carve-out, and only one (ADR-101):** where `wr-itil-check-afk-accept-eligible` exits 0, the loop marks the story with `--pure-decomposition` at the accept transition (§ 7 mechanic 5). That is not a hollow marker — it records a machine-established basis rather than asserting a human confirmed something they never saw, it is opt-in per project and per story, and the story still surfaces for post-hoc human ratification via `wr-itil-detect-unratified-stories-maps --with-afk-accepted`. Everything else stays held.
 4. **Single commit** per ADR-014.
 
 ### 8. List flow (`list`)