@windyroad/itil 0.61.2 → 1.0.0

package/scripts/render-story-map.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Thin bash entry point for the story-map renderer, so the ADR-049/ADR-080
+# shim machinery (which resolves `scripts/<NAME>.sh`) reaches the Node
+# implementation without the generator needing to learn about .mjs.
+#
+# Usage: wr-itil-render-story-map <map.html>
+#
+# One mode: renders a map in place from its own data island. To create a map,
+# write a file containing just the island and render it.
+#
+# @adr ADR-102 (story maps render from JSON through a canonical template)
+# @adr ADR-049 (plugin scripts resolve via bin/ on $PATH)
+
+set -euo pipefail
+exec node "$(cd "$(dirname "$0")" && pwd)/render-story-map.mjs" "$@"

package/scripts/story-map-edit.mjs

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+// Card-level editing for a story map, so nobody hand-edits the data island.
+//
+// A map's data lives in a JSON island inside a several-hundred-line HTML file,
+// with `<` escaped as <. Editing that with an exact-match string tool is
+// error-prone enough that it does not get done: during ADR-102's own authoring
+// every island change went through a throwaway load-mutate-save script rather
+// than the editing tool an agent normally reaches for. This command is that
+// script, made a first-class surface — state the operation, never open the JSON.
+//
+// Every operation validates against the map's own backbone and bands before
+// writing, and re-renders afterwards, so the grid and the data cannot disagree.
+// A rejected operation leaves the file untouched.
+//
+// Usage:
+//   story-map-edit.mjs <map.html> add-card     --story ID --activity ID --release ID
+//                                              --title T [--ref R] [--rfc ID] [--jtbd ID]
+//   story-map-edit.mjs <map.html> move-card    --story ID [--activity ID] [--release ID]
+//   story-map-edit.mjs <map.html> remove-card  --story ID
+//   story-map-edit.mjs <map.html> add-band     --id ID --name N [--rfc RFC-NNN] [--note N]
+//   story-map-edit.mjs <map.html> add-activity --id ID --title T [--note N]
+//
+// Nothing the story file already says is settable here — status, the value
+// statement, and the problems a story closes are all read from the story at
+// render time (ADR-104). A card carries what identifies it and where it sits;
+// a row carries its RFC identity and its name. There are no --status, --value
+// or --badge flags, and a row's status and problems are derived from the
+// stories in it.
+//
+// @adr ADR-102 (story maps render from JSON through a canonical template)
+// @adr ADR-095 (story-map membership enforced at capture — drives add-card)
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const RENDERER = join(HERE, 'render-story-map.mjs');
+const ISLAND_OPEN = '<script id="story-map-data" type="application/json">';
+
+function parseFlags(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (!a.startsWith('--')) continue;
+    const key = a.slice(2);
+    const next = argv[i + 1];
+    out[key] = next && !next.startsWith('--') ? next : true;
+    if (out[key] !== true) i += 1;
+  }
+  return out;
+}
+
+function readIsland(path) {
+  const html = readFileSync(path, 'utf8');
+  const start = html.indexOf(ISLAND_OPEN);
+  if (start === -1) {
+    throw new Error(
+      `${path} carries no <script id="story-map-data"> block — not a story map.`
+    );
+  }
+  const from = start + ISLAND_OPEN.length;
+  const end = html.indexOf('</script>', from);
+  if (end === -1) throw new Error(`${path}: data block is not closed.`);
+  return { html, from, end, data: JSON.parse(html.slice(from, end).replace(/\\u003c/g, '<')) };
+}
+
+function writeIsland(path, { html, from, end }, data) {
+  const island = JSON.stringify(data, null, 2).replace(/</g, '\\u003c');
+  writeFileSync(path, html.slice(0, from) + '\n' + island + '\n  ' + html.slice(end));
+}
+
+function need(flags, name, op) {
+  const v = flags[name];
+  if (!v || v === true) throw new Error(`${op} needs --${name}`);
+  return String(v);
+}
+
+/** Reject an id that is not on the map, naming what IS available — a bare
+ *  "invalid activity" sends the caller back to open the island, which is the
+ *  thing this command exists to avoid. */
+function requireId(list, id, what) {
+  const ids = list.map((x) => x.id);
+  if (!ids.includes(id)) {
+    throw new Error(`no ${what} "${id}" on this map. Available: ${ids.join(', ')}`);
+  }
+}
+
+const OPS = {
+  'add-card'(data, flags) {
+    const story = need(flags, 'story', 'add-card');
+    const activity = need(flags, 'activity', 'add-card');
+    const release = need(flags, 'release', 'add-card');
+    const title = need(flags, 'title', 'add-card');
+    requireId(data.backbone ?? [], activity, 'activity');
+    requireId(data.releases ?? [], release, 'release band');
+    data.tasks = data.tasks ?? [];
+    if (data.tasks.some((t) => t.storyId === story)) {
+      throw new Error(`${story} is already on this map — use move-card to relocate it.`);
+    }
+    const card = { activity, release, title };
+    if (flags.rfc && flags.rfc !== true) card.rfc = String(flags.rfc);
+    if (flags.jtbd && flags.jtbd !== true) card.jtbd = String(flags.jtbd);
+    card.storyId = story;
+    if (flags.ref && flags.ref !== true) card.ref = String(flags.ref);
+    data.tasks.push(card);
+    return `added ${story} at ${activity} × ${release}`;
+  },
+
+  'move-card'(data, flags) {
+    const story = need(flags, 'story', 'move-card');
+    const card = (data.tasks ?? []).find((t) => t.storyId === story);
+    if (!card) throw new Error(`${story} is not on this map.`);
+    if (flags.activity && flags.activity !== true) {
+      requireId(data.backbone ?? [], String(flags.activity), 'activity');
+      card.activity = String(flags.activity);
+    }
+    if (flags.release && flags.release !== true) {
+      requireId(data.releases ?? [], String(flags.release), 'release band');
+      card.release = String(flags.release);
+    }
+    return `moved ${story} to ${card.activity} × ${card.release}`;
+  },
+
+  'remove-card'(data, flags) {
+    const story = need(flags, 'story', 'remove-card');
+    const before = (data.tasks ?? []).length;
+    data.tasks = (data.tasks ?? []).filter((t) => t.storyId !== story);
+    if (data.tasks.length === before) throw new Error(`${story} is not on this map.`);
+    return `removed ${story}`;
+  },
+
+  'add-band'(data, flags) {
+    const id = need(flags, 'id', 'add-band');
+    const name = need(flags, 'name', 'add-band');
+    data.releases = data.releases ?? [];
+    if (data.releases.some((r) => r.id === id)) {
+      throw new Error(`release band "${id}" already exists on this map.`);
+    }
+    const band = { id, name };
+    // A row IS an RFC (ADR-103). Where a problem has proposed the row it carries
+    // that identity; where nothing has, it renders as speculative and says so.
+    if (flags.rfc && flags.rfc !== true) band.rfc = String(flags.rfc);
+    if (flags.note && flags.note !== true) band.note = String(flags.note);
+    data.releases.push(band);
+    return `added release band ${id}`;
+  },
+
+  'add-activity'(data, flags) {
+    const id = need(flags, 'id', 'add-activity');
+    const title = need(flags, 'title', 'add-activity');
+    data.backbone = data.backbone ?? [];
+    if (data.backbone.some((a) => a.id === id)) {
+      throw new Error(`activity "${id}" already exists on this map.`);
+    }
+    const act = { id, title };
+    if (flags.note && flags.note !== true) act.note = String(flags.note);
+    data.backbone.push(act);
+    return `added activity ${id}`;
+  },
+};
+
+function usage() {
+  console.error('usage: story-map-edit.mjs <map.html> <operation> [flags]');
+  console.error('');
+  console.error('  add-card     --story ID --activity ID --release ID --title T');
+  console.error('               [--ref R] [--rfc ID] [--jtbd ID]');
+  console.error('  move-card    --story ID [--activity ID] [--release ID]');
+  console.error('  remove-card  --story ID');
+  console.error('  add-band     --id ID --name N [--rfc RFC-NNN] [--note N]');
+  console.error('  add-activity --id ID --title T [--note N]');
+  console.error('');
+  console.error('Or pass the operation as JSON on stdin, which needs no shell escaping:');
+  console.error('  echo \'{"op":"add-card","story":"STORY-1","activity":"a","release":"r1","title":"He said \\"go\\" — then left"}\' \\');
+  console.error('    | story-map-edit.mjs <map.html> --json -');
+  console.error('');
+  console.error('Status, value and problems are derived from the story files at');
+  console.error('render time and are not settable here (ADR-104).');
+}
+
+/** Read an operation as a JSON object on stdin.
+ *
+ *  The escaping problem this closes: a card title or value carrying quotes, an
+ *  em-dash or a newline is painful to pass through a shell command line and
+ *  trivial to pass as JSON. Validation is the same code path as the flag form —
+ *  the object is simply converted to the flag map the operations already take.
+ *
+ *  NOTE: the sibling story-map-query uses stdin for the opposite purpose — it
+ *  consumes facts fed in by its own wrapper. Do not assume symmetry. */
+function flagsFromStdin() {
+  let raw;
+  try {
+    raw = readFileSync(0, 'utf8');
+  } catch {
+    throw new Error('--json - expects the operation as a JSON object on stdin');
+  }
+  let obj;
+  try {
+    obj = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`stdin is not valid JSON — ${err.message}`);
+  }
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+    throw new Error('stdin must be a JSON object, e.g. {"op":"add-card","story":"STORY-1",...}');
+  }
+  const { op, ...flags } = obj;
+  if (!op) throw new Error('the JSON object needs an "op", e.g. "add-card"');
+  return { op: String(op), flags };
+}
+
+function main(argv) {
+  let [target, op, ...rest] = argv;
+
+  // `--json -` replaces the operation and flags with a JSON object on stdin.
+  if (argv.includes('--json')) {
+    const path = argv[0];
+    let parsed;
+    try {
+      parsed = flagsFromStdin();
+    } catch (err) {
+      console.error(`story-map-edit: ${err.message}`);
+      return 1;
+    }
+    return run(path, parsed.op, parsed.flags);
+  }
+
+  if (!target || !op) {
+    usage();
+    return 2;
+  }
+  return run(target, op, parseFlags(rest));
+}
+
+/** The single execution path. Both the flag form and the stdin form land here
+ *  with an operation name and a flag map, so validation cannot diverge between
+ *  them — an equivalence asserted in prose drifts the first time a branch is
+ *  added to one form only. */
+function run(target, op, flags) {
+  if (!OPS[op]) {
+    console.error(`story-map-edit: unknown operation "${op}"`);
+    usage();
+    return 2;
+  }
+  const path = resolve(target);
+  if (!existsSync(path)) {
+    console.error(`story-map-edit: not found: ${target}`);
+    return 1;
+  }
+
+  let island;
+  try {
+    island = readIsland(path);
+  } catch (err) {
+    console.error(`story-map-edit: ${err.message}`);
+    return 1;
+  }
+
+  // Mutate a copy, so a rejected operation cannot leave the file half-edited.
+  const draft = JSON.parse(JSON.stringify(island.data));
+  let summary;
+  try {
+    summary = OPS[op](draft, flags);
+  } catch (err) {
+    console.error(`story-map-edit: ${err.message}`);
+    return 1;
+  }
+
+  writeIsland(path, island, draft);
+  try {
+    execFileSync(process.execPath, [RENDERER, path], { stdio: 'pipe' });
+  } catch (err) {
+    console.error(`story-map-edit: wrote the data but re-render failed — ${err.message}`);
+    return 1;
+  }
+  console.error(`story-map-edit: ${summary}`);
+  return 0;
+}
+
+process.exit(main(process.argv.slice(2)));

package/scripts/story-map-edit.sh

@@ -0,0 +1,10 @@
+#!/usr/bin/env bash
+# Bash entry point for the story-map card editor, so the ADR-049/ADR-080 shim
+# machinery (which resolves `scripts/<NAME>.sh`) reaches the Node implementation.
+#
+# Usage: wr-itil-story-map-edit <map.html> <operation> [flags]
+#
+# @adr ADR-102 (story maps render from JSON through a canonical template)
+# @adr ADR-049 (plugin scripts resolve via bin/ on $PATH)
+set -euo pipefail
+exec node "$(cd "$(dirname "$0")" && pwd)/story-map-edit.mjs" "$@"

package/scripts/story-map-query.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+// Read-only JSON query over the story-map corpus. Presentation and island
+// parsing only — oversight facts arrive pre-computed on stdin from
+// story-map-query.sh, which owns the single hash definition. Nothing here
+// hashes anything; see that wrapper's header for why.
+//
+// Reads the data island, never the rendered grid. Under ADR-102 the grid is a
+// projection regenerated from the island, so a map edited but not yet
+// re-rendered would answer with stale content if this scraped the markup — and
+// would disagree with the oversight hash, which is island-scoped.
+//
+// Operations:
+//   list                     every map: id, title, status, jobs, problems,
+//                            RFC row identities, ratification
+//   get <MAP-ID>             one map: backbone, releases, tasks
+//   find-story <STORY-ID>    which maps hold a story, and in which cell
+//   find-rfc <RFC-ID>        which release rows carry an RFC and their stories
+//   unratified               only the maps needing ratification, with a reason
+//
+// @adr ADR-102 (story maps render from JSON through a canonical template)
+// @adr ADR-090 (drift-invalidated human-oversight marker)
+
+import { readFileSync } from 'node:fs';
+
+const ISLAND_OPEN = '<script id="story-map-data" type="application/json">';
+
+/** Read the authored data. Falls through to null for a pre-ADR-102 map, which
+ *  has no island — mirroring _oversight_hashable's own fallthrough rather than
+ *  inventing a second rule about what counts as a map. */
+function island(path) {
+  let html;
+  try {
+    html = readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+  const start = html.indexOf(ISLAND_OPEN);
+  if (start === -1) return null;
+  const from = start + ISLAND_OPEN.length;
+  const end = html.indexOf('</script>', from);
+  if (end === -1) return null;
+  try {
+    return JSON.parse(html.slice(from, end).replace(/\\u003c/g, '<'));
+  } catch {
+    return null;
+  }
+}
+
+/** Everything the renderer derived from outside the island — story statuses and
+ *  values, row statuses, and resolved hrefs. Emitted alongside the data island
+ *  when the renderer runs in a repository; outside one it is absent. */
+function derivedIsland(mapPath) {
+  let html;
+  try {
+    html = readFileSync(mapPath, 'utf8');
+  } catch {
+    return {};
+  }
+  const OPEN = '<script id="story-map-status" type="application/json">';
+  const start = html.indexOf(OPEN);
+  if (start === -1) return {};
+  const from = start + OPEN.length;
+  const end = html.indexOf('</script>', from);
+  if (end === -1) return {};
+  try {
+    const d = JSON.parse(html.slice(from, end).replace(/\\u003c/g, '<'));
+    // The derived island grew from a flat {storyId: status} map into
+    // {rows, status, values, hrefs}. Normalise the older shape so a map
+    // rendered by a previous version is still readable — this reader is not the
+    // place to force a re-render.
+    if (!d || typeof d !== 'object') return {};
+    return d.status || d.rows || d.values || d.hrefs ? d : { status: d };
+  } catch {
+    return {};
+  }
+}
+
+/** Oversight facts from the bash wrapper: path, ratified, reason. */
+function readFacts() {
+  let raw = '';
+  try {
+    raw = readFileSync(0, 'utf8');
+  } catch {
+    return [];
+  }
+  return raw
+    .split('\n')
+    .filter(Boolean)
+    .map((line) => {
+      const [path, ratified, reason] = line.split('\t');
+      return { path, ratified: ratified === 'true', reason };
+    });
+}
+
+/** Row status is DERIVED, and this reads the value the renderer emitted rather
+ *  than recomputing it. There was a second copy of the derivation here; two
+ *  definitions of one fact is the drift class this map format has already
+ *  removed four times over. The renderer owns it because it is the only layer
+ *  that can read story files.
+ *
+ *  A map edited but not re-rendered answers `stale` for every row — a value the
+ *  renderer never emits, so it reads as "no derived answer" rather than
+ *  impersonating a verdict. It is the same staleness the story statuses and card
+ *  values already carry, and `story-map-edit` re-renders after every operation
+ *  so it does not arise in practice.
+ */
+function rowStatus(row, derived) {
+  return (derived.rows ?? {})[row.id] ?? 'stale';
+}
+
+function corpus() {
+  return readFacts()
+    .map((f) => ({ ...f, data: island(f.path), derived: derivedIsland(f.path) }))
+    .filter((m) => m.data)
+    .sort((a, b) => String(a.data.storyMapId).localeCompare(String(b.data.storyMapId)));
+}
+
+function summary(m) {
+  return {
+    storyMapId: m.data.storyMapId,
+    title: m.data.title ?? null,
+    status: m.data.status ?? null,
+    persona: m.data.persona ?? null,
+    // `traces` holds ONE authored key — the jobs the map is drawn for. Spelled
+    // out rather than passed through, so a stale island carrying the removed
+    // `adrs`/`rfcs` cannot leak them back into the query's answer.
+    traces: { jtbd: m.data.traces?.jtbd ?? [] },
+    // Derived, and read from what the renderer emitted rather than recomputed —
+    // the renderer is the definition, and two definitions of one fact is the
+    // drift class this format has removed repeatedly. Row RFC identities are
+    // AUTHORED, so they come from the island; only problems are derived.
+    problems: m.derived?.mapProblems ?? [],
+    rfcs: [...new Set((m.data.releases ?? []).map((r) => r.rfc).filter(Boolean))],
+    ratified: m.ratified,
+    reason: m.reason,
+    activities: (m.data.backbone ?? []).length,
+    releases: (m.data.releases ?? []).length,
+    cards: (m.data.tasks ?? []).length,
+    path: m.path,
+  };
+}
+
+const OPS = {
+  list: (maps) => maps.map(summary),
+
+  get(maps, [id]) {
+    if (!id) throw new Error('get needs a story-map id, e.g. STORY-MAP-002');
+    const m = maps.find((x) => x.data.storyMapId === id);
+    if (!m) throw new Error(`no story map ${id} in this corpus`);
+    return {
+      ...summary(m),
+      backbone: m.data.backbone ?? [],
+      releasesDetail: (m.data.releases ?? []).map((r) => ({
+        ...r,
+        status: rowStatus(r, m.derived ?? {}),
+      })),
+      tasks: m.data.tasks ?? [],
+    };
+  },
+
+  'find-story': (maps, [storyId]) => {
+    if (!storyId) throw new Error('find-story needs a story id, e.g. STORY-047');
+    const hits = [];
+    for (const m of maps) {
+      for (const t of m.data.tasks ?? []) {
+        if (t.storyId !== storyId) continue;
+        hits.push({
+          storyMapId: m.data.storyMapId,
+          activity: t.activity,
+          release: t.release,
+          title: t.title ?? null,
+          ratified: m.ratified,
+          path: m.path,
+        });
+      }
+    }
+    return hits;
+  },
+
+  'find-rfc': (maps, [rfcId]) => {
+    if (!rfcId) throw new Error('find-rfc needs an RFC id, e.g. RFC-062');
+    const hits = [];
+    for (const m of maps) {
+      for (const row of m.data.releases ?? []) {
+        if (row.rfc !== rfcId) continue;
+        hits.push({
+          storyMapId: m.data.storyMapId,
+          rowId: row.id,
+          status: rowStatus(row, m.derived ?? {}),
+          stories: [...new Set((m.data.tasks ?? [])
+            .filter((task) => task.release === row.id)
+            .map((task) => task.storyId)
+            .filter(Boolean))],
+          path: m.path,
+        });
+      }
+    }
+    return hits;
+  },
+
+  unratified: (maps) => maps.filter((m) => !m.ratified).map(summary),
+};
+
+function main(argv) {
+  const [op, ...rest] = argv;
+  if (!op || !OPS[op]) {
+    console.error('usage: story-map-query <list|get|find-story|find-rfc|unratified> [args] [--maps-dir DIR]');
+    console.error('');
+    console.error('  list                   every map: status, jobs, problems, RFC rows, ratification');
+    console.error('  get <MAP-ID>           one map: backbone, release bands, cards');
+    console.error('  find-story <STORY-ID>  which maps hold a story, and in which cell');
+    console.error('  find-rfc <RFC-ID>       which release rows carry an RFC and their stories');
+    console.error('  unratified             maps needing ratification, each with a reason');
+    return 2;
+  }
+  let out;
+  try {
+    out = OPS[op](corpus(), rest);
+  } catch (err) {
+    console.error(`story-map-query: ${err.message}`);
+    return 1;
+  }
+  process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+  return 0;
+}
+
+process.exit(main(process.argv.slice(2)));

package/scripts/story-map-query.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Read-only JSON query over the story-map corpus.
+#
+# Usage: wr-itil-story-map-query <list|get|find-story|find-rfc|unratified> [args] [--maps-dir DIR]
+#
+# WHY THIS IS A BASH ENTRY POINT AND NOT JUST A .mjs. Ratification state is
+# drift-invalidated and must come from ONE hash definition — the one in
+# lib/story-oversight.sh that detect-unratified-stories-maps.sh,
+# check-rfc-stories-ratified.sh and mark-story-oversight-confirmed.sh all share.
+# A JavaScript re-implementation would be a fourth definition, and the pair
+# would disagree the first time either drifted. So this wrapper sources the lib,
+# computes the oversight facts per map in bash, and pipes them to the Node half,
+# which does presentation and island parsing only. No hashing in JavaScript.
+#
+# NOTE ON STDIN: this tool consumes stdin for facts fed in by this wrapper, so
+# stdin is not available as a user input channel here. Its sibling
+# story-map-edit reads an operation FROM stdin under `--json -`. The asymmetry
+# is deliberate; do not assume symmetry between the two.
+#
+# @adr ADR-102 (story maps render from JSON through a canonical template)
+# @adr ADR-090 (drift-invalidated human-oversight marker)
+# @adr ADR-049 (plugin scripts resolve via bin/ on $PATH)
+
+set -uo pipefail
+
+HERE="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=/dev/null
+. "$HERE/../lib/story-oversight.sh"
+
+MAPS_DIR="docs/story-maps"
+ARGS=()
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --maps-dir) MAPS_DIR="${2:-}"; shift 2 ;;
+    *) ARGS+=("$1"); shift ;;
+  esac
+done
+
+# Same two globs as detect-unratified-stories-maps.sh, and the same default.
+# A different corpus would make the two surfaces disagree about which maps
+# exist while agreeing perfectly on every per-map verdict — the more confusing
+# failure, and one this repo has already hit once via a subdirectory-glob miss.
+shopt -s nullglob
+MAPS=("$MAPS_DIR"/*.html "$MAPS_DIR"/*/*.html)
+shopt -u nullglob
+
+# One facts line per map. `reason` is decided HERE, not in JS: separating
+# drift-reopened from never-ratified needs a hash comparison, and doing that on
+# the JS side is exactly how a fourth hash definition appears.
+facts() {
+  local f confirmed stored fresh ratified reason
+  for f in "${MAPS[@]}"; do
+    [ -f "$f" ] || continue
+    confirmed=false; stored=""; ratified=false; reason="never-ratified"
+    if oversight_is_confirmed "$f" 2>/dev/null; then confirmed=true; fi
+    stored="$(oversight_stored_hash "$f" 2>/dev/null || true)"
+    if [ "$confirmed" = true ] && [ -z "$stored" ]; then
+      reason="legacy-confirmed-without-fingerprint"
+    elif [ "$confirmed" = true ]; then
+      fresh="$(oversight_content_hash "$f" 2>/dev/null || true)"
+      if [ "$stored" = "$fresh" ]; then ratified=true; reason="ratified"
+      else reason="drift-reopened"; fi
+    fi
+    printf '%s\t%s\t%s\n' "$f" "$ratified" "$reason"
+  done
+}
+
+facts | exec node "$HERE/story-map-query.mjs" "${ARGS[@]+"${ARGS[@]}"}"

package/scripts/update-story-references-section.sh

@@ -51,7 +51,12 @@ extract_from_html_data_story_id() {
   local file="$1"
   # Story maps reference stories via <a data-story-id="STORY-NNN"> per ADR-060
   # amendment schema; grep on the literal attribute match.
-  grep -qE "data-story-id=\"${story_id}\"" "$file"
+  # Two spellings carry the same fact, and a rendered map carries BOTH: the
+  # card as data-story-id="X", and the authored island entry as "storyId": "X".
+  # Pre-ADR-102 maps have only the first; a map edited but not yet re-rendered
+  # has only the second. Matching both covers every state. The alternation is
+  # boolean per file, so a map carrying both spellings is not double-listed.
+  grep -qE "data-story-id=\"${story_id}\"|\"storyId\"[[:space:]]*:[[:space:]]*\"${story_id}\"" "$file"
 }
 
 extract_id_from_filename() { basename "$1" | grep -oE "$id_pattern" | head -1; }

package/skills/capture-rfc/SKILL.md

@@ -295,7 +295,7 @@ After the commit, report:
 
 The trailing pointer is **not optional** — on the user-aside path it is the user-visible signal that the RFC is intentionally skeleton-only and how to advance it; on the `--fix-time` path it signals the RFC is already authored and points at the ratification drain.
 
-**Oversight marker discipline (ADR-066 + ADR-068 amendments 2026-06-02 / P348).** The skeleton frontmatter MUST include `human-oversight: unconfirmed`. capture-rfc is the AFK-friendly aside surface; there is no substance-confirm `AskUserQuestion` pass in this flow (deferred to `/wr-itil:manage-rfc accepted`), so `confirmed` would be a hollow marker (the P348 bug class). The architect-side hook (`architect-oversight-marker-discipline.sh`) does NOT gate `docs/rfcs/`, but downstream paths that promote a captured RFC to `confirmed` MUST do so via a proper substance-confirm AskUserQuestion (e.g. `/wr-itil:manage-rfc accepted` for genuine ratification) — agents authoring RFCs at capture-time MUST NOT write `confirmed`. The drain pattern mirrors the ADR drain: an RFC's `unconfirmed` state surfaces interactively during the `accepted` transition.
+**Oversight marker discipline (ADR-110 / P348).** The skeleton frontmatter MUST include `human-oversight: unconfirmed`. capture-rfc is the AFK-friendly aside surface; there is no substance-confirm `AskUserQuestion` pass in this flow (deferred to `/wr-itil:manage-rfc accepted`), so `confirmed` would be a hollow marker (the P348 bug class). The architect-side hook (`architect-oversight-marker-discipline.sh`) does NOT gate `docs/rfcs/`, but downstream paths that promote a captured RFC to `confirmed` MUST do so via a proper substance-confirm AskUserQuestion (e.g. `/wr-itil:manage-rfc accepted` for genuine ratification) — agents authoring RFCs at capture-time MUST NOT write `confirmed`. The drain pattern mirrors the ADR drain: an RFC's `unconfirmed` state surfaces interactively during the `accepted` transition.
 
 ## Composition with manage-rfc