@windyroad/itil 2.2.1 → 2.3.0-preview.1211

package/.claude-plugin/plugin.json

@@ -497,5 +497,5 @@
     }
   },
   "name": "wr-itil",
-  "version": "2.2.1"
+  "version": "2.3.0"
 }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "wr-itil",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "ITIL problem-management workflows for AI coding agents",
   "author": {
     "name": "Windy Road Technology",

package/bin/wr-itil-migrate-story-map

@@ -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 (highest-version-wins-shim-wrapper-for-plugin-scaffold-template-shims-architecture-rule):
+#   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 highest-version-wins-shim-wrapper-for-plugin-scaffold-template-shims-architecture-rule (highest-version-wins shim wrapper plugin scaffold)
+# @adr plugin-bundled-scripts-invoked-from-skill-md-resolve-via-bin-on-path-architecture-rule (plugin-bundled scripts resolve via bin/ on $PATH — amended)
+# @problem install-updates-refreshes-the-global-plugin-cache-but-does-not-fix-path-ordering-stale-plugin-version-shims-stay-first-on-path-so-subsequent-shim-invocations-run-old-code-problem (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/migrate-story-map.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/migrate-story-map.sh" "$@"

package/lib/story-oversight.sh

@@ -57,7 +57,8 @@ oversight_excluded_keys() {
   printf '%s\n' human-oversight oversight-hash oversight-basis status
 }
 
-# The MAP-SUBSTANCE key set: the island keys a story map's ratification hangs on.
+# The MAP-SUBSTANCE key set: island keys plus the derived historical-row key a
+# story map's ratification hangs on.
 #
 # Editing this set — here or in the SUBSTANCE tuple below — changes story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule's
 # Decision Outcome as amended by a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule, not merely a mechanism. It IS the drift
@@ -66,10 +67,11 @@ oversight_excluded_keys() {
 # whenever both move together, which is the shape of exactly that edit. The
 # sibling notice on _oversight_filter says the same thing for the same reason.
 #
-# SCOPE: island keys only. Unlike oversight_excluded_keys, which strips keys from
-# every artefact in three encodings, this set is meaningless for anything with no
-# island — stories and pre-story-maps-render-from-json-through-a-canonical-template-architecture-rule maps fall through to whole-file bytes. The two
-# are not complements; `excluded ∪ substance` is not the key space.
+# SCOPE: data-island substance only. `historicalPreRfcRows` is derived from the
+# island's manifested historical release rows rather than authored as a key.
+# Unlike oversight_excluded_keys, this set is meaningless for anything with no
+# island — stories and pre-story-maps-render-from-json-through-a-canonical-template-architecture-rule maps fall through to whole-file bytes. The
+# two are not complements; `excluded ∪ substance` is not the key space.
 #
 # THIS IS THE ONLY ENUMERATION. Six documents used to restate it (story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule,
 # a-release-row-is-the-rfc-and-the-map-is-the-approval-surface-architecture-rule, the-grid-ships-in-the-file-a-map-is-readable-with-no-script-engine-architecture-rule, capture-story-map, and manage-story-map twice) and by
@@ -83,7 +85,7 @@ oversight_excluded_keys() {
 # derives its pattern from oversight_excluded_keys. A consumer that hardcodes the
 # list starts a seventh enumeration.
 oversight_map_substance_keys() {
-  printf '%s\n' storyMapId title persona secondaryPersona traces backbone caption
+  printf '%s\n' storyMapId title persona secondaryPersona traces backbone caption historicalPreRfcRows
 }
 
 # Emit the bytes a fingerprint should cover.
@@ -130,7 +132,11 @@ except Exception:
 # nothing documents would still have been ratification-bearing.
 SUBSTANCE = ("storyMapId", "title", "persona", "secondaryPersona",
              "traces", "backbone", "caption")
-print(json.dumps({k: d[k] for k in SUBSTANCE if k in d}, sort_keys=True, indent=2))
+basis = {k: d[k] for k in SUBSTANCE if k in d}
+historical = [r for r in d.get("releases", []) if "historicalProjection" in r]
+if historical:
+    basis["historicalPreRfcRows"] = historical
+print(json.dumps(basis, sort_keys=True, indent=2))
 '
   else
     cat "$f"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@windyroad/itil",
-  "version": "2.2.1",
+  "version": "2.3.0-preview.1211",
   "description": "ITIL-aligned IT service management for Claude Code and Codex",
   "bin": {
     "windyroad-itil": "./bin/install.mjs"

package/scripts/migrate-story-map.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { relative, resolve, sep } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { historicalProjectionHash, validateHistoricalContent, validateHistoricalMapping } from './story-map-history.mjs';
+
+const [targetArg, mappingArg] = process.argv.slice(2);
+if (!targetArg || !mappingArg) {
+  console.error('usage: migrate-story-map.mjs <legacy-map.html> <mapping.json>');
+  process.exit(2);
+}
+
+const unresolvedTarget = resolve(targetArg);
+if (!existsSync(unresolvedTarget)) process.exit(0);
+const target = realpathSync(unresolvedTarget);
+const source = readFileSync(target);
+if (source.includes(Buffer.from('<script id="story-map-data"'))) process.exit(0);
+
+const mapping = JSON.parse(readFileSync(resolve(mappingArg), 'utf8'));
+const allowed = new Set(['mapId', 'path', 'authorityAdr', 'sourceCommit', 'sourceSha256', 'map']);
+if (!mapping || typeof mapping !== 'object' || Object.keys(mapping).some((key) => !allowed.has(key)) ||
+    Object.keys(mapping).length !== allowed.size) {
+  throw new Error('mapping must contain exactly mapId, path, authorityAdr, sourceCommit, sourceSha256, and map');
+}
+const actualPath = relative(process.cwd(), target).split(sep).join('/');
+const sourceSha256 = createHash('sha256').update(source).digest('hex');
+if (mapping.path !== actualPath || mapping.mapId !== mapping.map?.storyMapId ||
+    mapping.sourceSha256 !== sourceSha256 || !mapping.sourceCommit) {
+  throw new Error('mapping identity, path, source commit, or source fingerprint does not match the selected map');
+}
+if (!validateHistoricalContent(mapping.map)) throw new Error('mapping contains no historical pre-RFC rows');
+
+const manifestPath = resolve('docs/story-maps/legacy-projection-manifest.json');
+const previousManifest = existsSync(manifestPath) ? readFileSync(manifestPath) : null;
+const manifest = previousManifest ? JSON.parse(previousManifest) : { schemaVersion: 1, maps: [] };
+if (manifest.schemaVersion !== 1 || !Array.isArray(manifest.maps) ||
+    manifest.maps.some((entry) => entry?.mapId === mapping.mapId || entry?.path === mapping.path)) {
+  throw new Error('legacy projection manifest is invalid or already contains the selected map');
+}
+const entry = {
+  mapId: mapping.mapId,
+  path: mapping.path,
+  authorityAdr: mapping.authorityAdr,
+  sourceCommit: mapping.sourceCommit,
+  sourceSha256,
+  historicalSha256: historicalProjectionHash(mapping.map),
+  canonicalSha256: '0'.repeat(64),
+};
+validateHistoricalMapping(mapping.map, target, entry);
+manifest.maps.push(entry);
+
+const render = () => {
+  const result = spawnSync(process.execPath, [resolve(import.meta.dirname, 'render-story-map.mjs'), target], { encoding: 'utf8' });
+  if (result.status !== 0) throw new Error(result.stderr || result.stdout || 'story-map render failed');
+};
+
+try {
+  const island = `<script id="story-map-data" type="application/json">\n${JSON.stringify(mapping.map, null, 2).replaceAll('<', '\\u003c')}\n</script>\n`;
+  writeFileSync(target, island);
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  render();
+  entry.canonicalSha256 = createHash('sha256').update(readFileSync(target)).digest('hex');
+  writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+  render();
+  const verified = createHash('sha256').update(readFileSync(target)).digest('hex');
+  if (verified !== entry.canonicalSha256) throw new Error('canonical story-map fingerprint changed during verification');
+} catch (error) {
+  writeFileSync(target, source);
+  if (previousManifest) writeFileSync(manifestPath, previousManifest);
+  else rmSync(manifestPath, { force: true });
+  throw error;
+}
+
+console.log(`migrated ${mapping.mapId} to the canonical story-map format`);

package/scripts/migrate-story-map.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -euo pipefail
+exec node "$(cd "$(dirname "$0")" && pwd)/migrate-story-map.mjs" "$@"

package/scripts/render-story-map.mjs

@@ -36,6 +36,7 @@
 import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
 import { dirname, join, resolve, relative, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { validateHistoricalRows } from './story-map-history.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const TEMPLATE = join(HERE, '..', 'templates', 'story-map.html');
@@ -397,6 +398,7 @@ function resolveHref(mapPath, id) {
  *  when card status was stored.
  */
 function rowStatus(row, tasks, statuses) {
+  if (row.historicalProjection) return 'historical';
   const mine = tasks.filter((t) => t.release === row.id);
   const terminal = (s) => s === 'done' || s === 'archived';
   const shipped = mine.length && mine.every((t) => terminal(statuses[t.storyId]));
@@ -511,7 +513,7 @@ function renderStatus(map, storiesDir, mapPath) {
  * alongside colour.
  * ------------------------------------------------------------------------- */
 
-const BADGE_GLYPH = { 'b-live': '\u2713', 'b-next': '\u2192', 'b-defect': '\u26a0' };
+const BADGE_GLYPH = { 'b-live': '\u2713', 'b-next': '\u2192', 'b-history': '\u25c7', 'b-defect': '\u26a0' };
 
 /** Status as a class. Derived, never an authored badge — a hand-written R1/R2
  *  ordinal duplicated the RFC identity and collided with it. */
@@ -519,6 +521,7 @@ function badgeClass(rel) {
   switch (String(rel.status || '').toLowerCase()) {
     case 'delivered': return 'b-live';
     case 'proposed':  return rel.rfc ? 'b-next' : 'b-defect';
+    case 'historical': return 'b-history';
     default:          return 'b-defect';
   }
 }
@@ -543,6 +546,10 @@ function badgeClass(rel) {
  */
 function rowLabel(rel) {
   const status = String(rel.status || '').toLowerCase();
+  if (status === 'historical') {
+    const projection = rel.historicalProjection;
+    return `Historical context: ${projection.sourceLabel} as of ${projection.reported}`;
+  }
   if (rel.rfc) {
     if (status === 'delivered') return `Delivered: ${rel.rfc}`;
     if (status === 'proposed') return `Proposed: ${rel.rfc}`;
@@ -647,6 +654,15 @@ function cardHtml(task, status, value, hrefs) {
   return out + '</div>';
 }
 
+function historicalCardHtml(card) {
+  let out = '<div class="task historical-card">';
+  out += '<div class="t-status ts-arch">Historical context</div>';
+  out += `<span class="t-title">${esc(card.title)}</span>`;
+  out += `<div class="t-value">${esc(card.text)}</div>`;
+  out += `<div class="t-ref">Recorded status: ${esc(card.statusLabel)}</div>`;
+  return out + '</div>';
+}
+
 /** The whole grid: caption, both header axes, and one row per release. */
 /** Read back the payload we just serialised, so the grid and the island share
  *  one resolution rather than computing it twice. */
@@ -724,23 +740,28 @@ function renderGrid(map, derived) {
     }
     out += '</th>';
 
-    const filled = backbone.map((act) =>
-      tasks.filter((t) => t.activity === act.id && t.release === rel.id));
+    const historicalCards = rel.historicalProjection?.cards ?? [];
+    const filled = backbone.map((act) => rel.historicalProjection
+      ? historicalCards.filter((card) => card.activity === act.id)
+      : tasks.filter((t) => t.activity === act.id && t.release === rel.id));
+    const noun = rel.historicalProjection ? 'historical cards' : 'stories';
 
     if (filled.every((h) => h.length === 0)) {
       // A wholly empty band is silent in a screen reader's browse mode while
       // being a loud full-width hatch visually. One spanning cell states it
       // once — per-cell text would bury a sparse map's few cards.
-      out += `<td class="cell empty" colspan="${backbone.length || 1}"><span class="vh">No stories in this release band.</span></td>`;
+      out += `<td class="cell empty" colspan="${backbone.length || 1}"><span class="vh">No ${noun} in this release band.</span></td>`;
     } else {
       for (const [i, here] of filled.entries()) {
         if (!here.length) {
-          out += `<td class="cell empty"><span class="vh">No stories for ${esc(backbone[i]?.title || 'this activity')} in ${esc(rel.name || rel.id || 'this release')}.</span></td>`;
+          out += `<td class="cell empty"><span class="vh">No ${noun} for ${esc(backbone[i]?.title || 'this activity')} in ${esc(rel.name || rel.id || 'this release')}.</span></td>`;
           continue;
         }
         out += '<td class="cell"><ul class="tasks" role="list">';
         for (const t of here) {
-          out += '<li>' + cardHtml(t, statuses[t.storyId], values[t.storyId], hrefs) + '</li>';
+          out += '<li>' + (rel.historicalProjection
+            ? historicalCardHtml(t)
+            : cardHtml(t, statuses[t.storyId], values[t.storyId], hrefs)) + '</li>';
         }
         out += '</ul></td>';
       }
@@ -966,6 +987,7 @@ function render(map, storiesDir, mapPath) {
     throw new Error('story map needs a non-empty "releases" array (the horizontal slices)');
   }
 
+  validateHistoricalRows(map, mapPath);
   assertEveryCardHasAStory(map, storiesDir);
   assertArchivedIsSeparated(map, storiesDir);
   assertOneReleasePerStory(map);

package/scripts/story-map-history.mjs

@@ -0,0 +1,132 @@
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { basename, dirname, join, relative, sep } from 'node:path';
+
+const SHA256 = /^[a-f0-9]{64}$/;
+const keysAre = (value, allowed) => Object.keys(value).every((key) => allowed.has(key));
+
+function stable(value) {
+  if (Array.isArray(value)) return value.map(stable);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stable(value[key])]));
+}
+
+function sha256(value) {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+export function historicalProjectionHash(map) {
+  const rows = (map.releases ?? [])
+    .filter((row) => row?.historicalProjection !== undefined)
+    .map(({ id, name, note, preRfc, historicalProjection }) =>
+      stable({ id, name, note, preRfc, historicalProjection }));
+  return sha256(JSON.stringify(rows));
+}
+
+function authorityProjectionHash(body, mapId) {
+  if (!/^human-oversight:\s*confirmed\s*$/m.test(body)) return null;
+  const lines = body.split('\n');
+  const start = lines.findIndex((line) => /^legacy-projections:\s*$/.test(line));
+  if (start === -1) return null;
+  const found = new Map();
+  for (const line of lines.slice(start + 1)) {
+    if (!line.trim()) continue;
+    if (!/^\s+/.test(line)) break;
+    const match = line.match(/^\s+(STORY-MAP-\d+):\s*([a-f0-9]{64})\s*$/);
+    if (!match || found.has(match[1])) return null;
+    found.set(match[1], match[2]);
+  }
+  return found.get(mapId) ?? null;
+}
+
+function decisionFile(docsRoot, authorityAdr) {
+  const match = String(authorityAdr ?? '').match(/^ADR-(\d+)$/);
+  if (!match) return null;
+  const prefix = `${String(Number(match[1])).padStart(3, '0')}-`;
+  const dir = join(docsRoot, 'decisions');
+  try {
+    const hits = readdirSync(dir).filter((name) => name.startsWith(prefix) && name.endsWith('.md'));
+    return hits.length === 1 ? join(dir, hits[0]) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function validateHistoricalContent(map) {
+  const historical = (map.releases ?? []).filter((row) => row?.historicalProjection !== undefined);
+  if (!historical.length) return false;
+
+  const activities = new Set((map.backbone ?? []).map((activity) => activity.id));
+  for (const row of historical) {
+    const projection = row.historicalProjection;
+    if (row.preRfc !== true || row.rfc || !projection || typeof projection !== 'object' ||
+        !keysAre(row, new Set(['id', 'name', 'note', 'preRfc', 'historicalProjection']))) {
+      throw new Error(`historical row ${row.id ?? '(missing id)'} must use preRfc: true, contain historicalProjection, and contain no rfc`);
+    }
+    if (!keysAre(projection, new Set(['reported', 'sourceBandId', 'sourceLabel', 'sourceNote', 'cards'])) ||
+        !projection.reported || !projection.sourceBandId || !projection.sourceLabel ||
+        typeof projection.sourceNote !== 'string' || !Array.isArray(projection.cards)) {
+      throw new Error(`historical row ${row.id ?? '(missing id)'} has an incomplete historicalProjection`);
+    }
+    if ((map.tasks ?? []).some((task) => task.release === row.id)) {
+      throw new Error(`historical row ${row.id} cannot contain ordinary tasks`);
+    }
+    for (const card of projection.cards) {
+      if (!card || !keysAre(card, new Set(['activity', 'title', 'text', 'statusLabel'])) ||
+          !activities.has(card.activity) || !card.title || !card.text || !card.statusLabel ||
+          card.storyId || card.release || card.rfc) {
+        throw new Error(`historical row ${row.id} has an invalid historical card`);
+      }
+    }
+  }
+
+  return true;
+}
+
+export function validateHistoricalMapping(map, mapPath, entry) {
+  if (!validateHistoricalContent(map)) return;
+  if (!mapPath) throw new Error('historical pre-RFC rows require a repository path');
+
+  let storyMapsRoot = dirname(mapPath);
+  if (basename(storyMapsRoot) !== 'story-maps') storyMapsRoot = dirname(storyMapsRoot);
+  if (basename(storyMapsRoot) !== 'story-maps') throw new Error('historical story map must live in docs/story-maps');
+  const docsRoot = dirname(storyMapsRoot);
+  const repoRoot = dirname(docsRoot);
+  const expectedPath = relative(repoRoot, mapPath).split(sep).join('/');
+  const hash = historicalProjectionHash(map);
+  if (entry.path !== expectedPath || entry.historicalSha256 !== hash ||
+      !SHA256.test(entry.sourceSha256 ?? '') || !SHA256.test(entry.canonicalSha256 ?? '') ||
+      !/^[a-f0-9]{7,64}$/.test(entry.sourceCommit ?? '')) {
+    throw new Error(`legacy projection manifest entry for ${map.storyMapId} does not match the map`);
+  }
+  const retained = spawnSync('git', ['-C', repoRoot, 'show', `${entry.sourceCommit}:${entry.path}`]);
+  if (retained.status !== 0 || sha256(retained.stdout) !== entry.sourceSha256) {
+    throw new Error(`legacy projection source fingerprint for ${map.storyMapId} does not match retained history`);
+  }
+  const authority = decisionFile(docsRoot, entry.authorityAdr);
+  if (!authority || !existsSync(authority)) {
+    throw new Error(`legacy projection authority ${entry.authorityAdr ?? '(missing)'} cannot be resolved`);
+  }
+  const authorisedHash = authorityProjectionHash(readFileSync(authority, 'utf8'), map.storyMapId);
+  if (authorisedHash !== hash) throw new Error(`legacy projection authority ${entry.authorityAdr} is unconfirmed or mismatched`);
+}
+
+export function validateHistoricalRows(map, mapPath) {
+  if (!validateHistoricalContent(map)) return;
+  let storyMapsRoot = dirname(mapPath);
+  if (basename(storyMapsRoot) !== 'story-maps') storyMapsRoot = dirname(storyMapsRoot);
+  const manifestPath = join(storyMapsRoot, 'legacy-projection-manifest.json');
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  } catch {
+    throw new Error('historical pre-RFC rows require a valid legacy-projection-manifest.json');
+  }
+  if (manifest.schemaVersion !== 1 || !Array.isArray(manifest.maps)) {
+    throw new Error('legacy projection manifest has an unsupported schema');
+  }
+  const matches = manifest.maps.filter((entry) => entry?.mapId === map.storyMapId);
+  if (matches.length !== 1) throw new Error(`legacy projection manifest must contain exactly one entry for ${map.storyMapId}`);
+  validateHistoricalMapping(map, mapPath, matches[0]);
+}

package/scripts/story-map-query.mjs

@@ -23,6 +23,7 @@
 // @adr story-maps-and-stories-carry-a-drift-invalidated-human-oversight-marker-architecture-rule (drift-invalidated human-oversight marker)
 
 import { readFileSync } from 'node:fs';
+import { validateHistoricalRows } from './story-map-history.mjs';
 
 const ISLAND_OPEN = '<script id="story-map-data" type="application/json">';
 
@@ -41,11 +42,14 @@ function island(path) {
   const from = start + ISLAND_OPEN.length;
   const end = html.indexOf('</script>', from);
   if (end === -1) return null;
+  let data;
   try {
-    return JSON.parse(html.slice(from, end).replace(/\\u003c/g, '<'));
+    data = JSON.parse(html.slice(from, end).replace(/\\u003c/g, '<'));
   } catch {
     return null;
   }
+  validateHistoricalRows(data, path);
+  return data;
 }
 
 /** Everything the renderer derived from outside the island — story statuses and

package/skills/capture-story-map/SKILL.md

@@ -188,7 +188,7 @@ appear here changes what that test asserts, and that binding is deliberate.
 - **A row IS an RFC (the "A release row is the RFC, and the map is the approval surface" architecture rule).** A row a problem has proposed carries its `rfc`; drawing the row is what allocates the identity. There is no separate "not yet allocated" state and no `badge` field — a row's status is derived from its stories, and its label is its RFC id.
 - **Every row carries an identity, and finishing one earns no exemption (the "A story map's RFC list is derived from its release rows" architecture rule).** A row with no `rfc` renders as a defect — a red "Untraced" badge — whether or not its stories are done. Delivery cannot excuse a missing identity, because every row is delivered eventually; that reading would let work nobody proposed become legitimate by being finished.
 
-  The only exception is a row holding work that shipped **before rows carried identities**, and such a row says so explicitly with `"preRfc": true`. That set is closed. Do not add the marker to a new row: it is a statement about history, not a way to skip allocating an RFC. It appears in no example above because a row that has an `rfc` does not need it, and the example shows the normal case.
+  The ordinary exception is a row holding work that shipped **before rows carried identities**, and such a row says so explicitly with `"preRfc": true`. That set is closed. Do not add the marker to a newly captured row: it is a statement about history, not a way to skip allocating an RFC. A separate manifest-bound historical subtype may be written only by `/wr-itil:migrate-story-map` from a retained legacy map under exact confirmed adopter authority; capture never authors it. It appears in no example above because the example shows the normal case.
 - **A map carries no `traces.rfcs` (the "A story map's RFC list is derived from its release rows" architecture rule).** The map's RFC list is the union of its row identities, so authoring it restates the rows and drifts from them the moment one changes.
 - `storyId` / `rfc` / `jtbd` are optional per task and emit the `data-*` reference layer that reverse-trace and the story-map queries consume. Omit them until stories exist; add them as stories are captured onto the map.
 - **Author nothing a story file already says (the "A story map card stores no value a story file already carries" architecture rule).** A story's lifecycle state, its value statement, and the problems it closes are all read from the story when the map renders — so a transition needs no map edit and does not re-open the map's ratification. There are no `storyStatus`, `value` or row-level `problems` fields, and no `--status` or `--value` flags. A row's problems are the union of its stories'; a map's are the union of its rows'.

package/skills/manage-story-map/SKILL.md

@@ -116,7 +116,7 @@ Per architect amend finding 2 on Slice 7: story-map HTML files do NOT carry an a
 
 ### 7.5. Ratification flow (`ratify`) — the "Story maps and stories carry a drift-invalidated human-oversight marker" architecture rule / the "A release row is the RFC, and the map is the approval surface" architecture rule / the ": Ratify the story map and its stories after any change" delivery story
 
-`ratify` is **orthogonal to the status lifecycle** — a map can be ratified at any status. It confirms human oversight of **the map**, and under the "A release row is the RFC, and the map is the approval surface" architecture rule that approves every story on it, including stories added later; stories are never ratified individually. Ratification is **drift-invalidated** (the "Gate Marker Lifecycle: TTL + Drift, Not Stop-Hook Reset" architecture rule lineage, NOT the ": Human-oversight marker + `/wr-architect:review-decisions` drain for recorded decisions" architecture rule write-once), but only a **substance** edit re-opens it: the map's own substance as the "Story maps and stories carry a drift-invalidated human-oversight marker" architecture rule defines it — its journey, its identity, and what it traces to. `oversight_map_substance_keys()` is the authoritative field list; this page deliberately does not restate it. Release rows, the cards in them, story-body edits and template restyling all sit outside the fingerprint basis and change nothing. This is the ": Ratify the story map and its stories after any change" delivery story surface.
+`ratify` is **orthogonal to the status lifecycle** — a map can be ratified at any status. It confirms human oversight of **the map**, and under the "A release row is the RFC, and the map is the approval surface" architecture rule that approves every ordinary story on it, including stories added later; stories are never ratified individually. Ratification is **drift-invalidated** (the "Gate Marker Lifecycle: TTL + Drift, Not Stop-Hook Reset" architecture rule lineage, NOT the ": Human-oversight marker + `/wr-architect:review-decisions` drain for recorded decisions" architecture rule write-once), but only a **substance** edit re-opens it: the map's own substance as the "Story maps and stories carry a drift-invalidated human-oversight marker" architecture rule defines it — its journey, its identity, what it traces to, and any manifest-bound historical projection. `oversight_map_substance_keys()` is the authoritative field list; this page deliberately does not restate it. Ordinary release rows and cards, story-body edits and template restyling sit outside the fingerprint basis and change nothing. Historical projections are the narrow exception and may be added only through `/wr-itil:migrate-story-map` under exact confirmed adopter authority. This is the ": Ratify the story map and its stories after any change" delivery story surface.
 
 **Born-confirmed discipline (the "iter subprocesses set `human-oversight: confirmed` marker on ADRs / personas / JTBDs without an actual user-confirmation event" problem).** Before any marker write, `export CLAUDE_SESSION_ID` from the transcript path — the marker shim silently no-ops on an empty SID. Every `confirmed` marker MUST be backed by a same-turn human confirm event; never write `confirmed` without the `AskUserQuestion` below (a hollow marker is the "iter subprocesses set `human-oversight: confirmed` marker on ADRs / personas / JTBDs without an actual user-confirmation event" problem bug).
 

package/skills/migrate-story-map/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: wr-itil:migrate-story-map
+description: "Replace one eligible legacy story map with a manifest-bound canonical map from a complete adopter-ratified mapping."
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Migrate Story Map
+
+Use this only for a retained legacy map whose exact historical projection is authorised by a confirmed adopter decision under the manifest-bound historical-row architecture rule.
+
+## Steps
+
+1. Read the complete legacy map and the supplied structured mapping. Confirm every historical card and placement comes from the retained source; do not infer or add content.
+2. Confirm the cited decision has `human-oversight: confirmed` and maps the selected story-map identifier to the mapping's historical SHA-256 fingerprint under `legacy-projections`.
+3. Run `wr-itil-migrate-story-map <legacy-map.html> <mapping.json>` from the adopter repository root. The command fails before writing on incomplete or mismatched input, and restores the source and manifest if rendering fails. It exits successfully without changes when the map is absent or already canonical.
+4. Run the repository's story-map query, renderer, accessibility, and governance checks.
+5. Run the repository's required risk review, then commit the replaced map and manifest as one auditable migration.
+
+Do not use this skill to create new history, approve an RFC, create stories, or interpret arbitrary legacy HTML automatically.
+
+$ARGUMENTS

package/skills-codex/capture-story-map/SKILL.md

@@ -199,7 +199,7 @@ appear here changes what that test asserts, and that binding is deliberate.
 - **A row IS an RFC (the "A release row is the RFC, and the map is the approval surface" architecture rule).** A row a problem has proposed carries its `rfc`; drawing the row is what allocates the identity. There is no separate "not yet allocated" state and no `badge` field — a row's status is derived from its stories, and its label is its RFC id.
 - **Every row carries an identity, and finishing one earns no exemption (the "A story map's RFC list is derived from its release rows" architecture rule).** A row with no `rfc` renders as a defect — a red "Untraced" badge — whether or not its stories are done. Delivery cannot excuse a missing identity, because every row is delivered eventually; that reading would let work nobody proposed become legitimate by being finished.
 
-  The only exception is a row holding work that shipped **before rows carried identities**, and such a row says so explicitly with `"preRfc": true`. That set is closed. Do not add the marker to a new row: it is a statement about history, not a way to skip allocating an RFC. It appears in no example above because a row that has an `rfc` does not need it, and the example shows the normal case.
+  The ordinary exception is a row holding work that shipped **before rows carried identities**, and such a row says so explicitly with `"preRfc": true`. That set is closed. Do not add the marker to a newly captured row: it is a statement about history, not a way to skip allocating an RFC. A separate manifest-bound historical subtype may be written only by `/wr-itil:migrate-story-map` from a retained legacy map under exact confirmed adopter authority; capture never authors it. It appears in no example above because the example shows the normal case.
 - **A map carries no `traces.rfcs` (the "A story map's RFC list is derived from its release rows" architecture rule).** The map's RFC list is the union of its row identities, so authoring it restates the rows and drifts from them the moment one changes.
 - `storyId` / `rfc` / `jtbd` are optional per task and emit the `data-*` reference layer that reverse-trace and the story-map queries consume. Omit them until stories exist; add them as stories are captured onto the map.
 - **Author nothing a story file already says (the "A story map card stores no value a story file already carries" architecture rule).** A story's lifecycle state, its value statement, and the problems it closes are all read from the story when the map renders — so a transition needs no map edit and does not re-open the map's ratification. There are no `storyStatus`, `value` or row-level `problems` fields, and no `--status` or `--value` flags. A row's problems are the union of its stories'; a map's are the union of its rows'.

package/skills-codex/manage-story-map/SKILL.md

@@ -127,7 +127,7 @@ Per architect amend finding 2 on Slice 7: story-map HTML files do NOT carry an a
 
 ### 7.5. Ratification flow (`ratify`) — the "Story maps and stories carry a drift-invalidated human-oversight marker" architecture rule / the "A release row is the RFC, and the map is the approval surface" architecture rule / the ": Ratify the story map and its stories after any change" delivery story
 
-`ratify` is **orthogonal to the status lifecycle** — a map can be ratified at any status. It confirms human oversight of **the map**, and under the "A release row is the RFC, and the map is the approval surface" architecture rule that approves every story on it, including stories added later; stories are never ratified individually. Ratification is **drift-invalidated** (the "Gate Marker Lifecycle: TTL + Drift, Not Stop-Hook Reset" architecture rule lineage, NOT the ": Human-oversight marker + `/wr-architect:review-decisions` drain for recorded decisions" architecture rule write-once), but only a **substance** edit re-opens it: the map's own substance as the "Story maps and stories carry a drift-invalidated human-oversight marker" architecture rule defines it — its journey, its identity, and what it traces to. `oversight_map_substance_keys()` is the authoritative field list; this page deliberately does not restate it. Release rows, the cards in them, story-body edits and template restyling all sit outside the fingerprint basis and change nothing. This is the ": Ratify the story map and its stories after any change" delivery story surface.
+`ratify` is **orthogonal to the status lifecycle** — a map can be ratified at any status. It confirms human oversight of **the map**, and under the "A release row is the RFC, and the map is the approval surface" architecture rule that approves every ordinary story on it, including stories added later; stories are never ratified individually. Ratification is **drift-invalidated** (the "Gate Marker Lifecycle: TTL + Drift, Not Stop-Hook Reset" architecture rule lineage, NOT the ": Human-oversight marker + `/wr-architect:review-decisions` drain for recorded decisions" architecture rule write-once), but only a **substance** edit re-opens it: the map's own substance as the "Story maps and stories carry a drift-invalidated human-oversight marker" architecture rule defines it — its journey, its identity, what it traces to, and any manifest-bound historical projection. `oversight_map_substance_keys()` is the authoritative field list; this page deliberately does not restate it. Ordinary release rows and cards, story-body edits and template restyling sit outside the fingerprint basis and change nothing. Historical projections are the narrow exception and may be added only through `/wr-itil:migrate-story-map` under exact confirmed adopter authority. This is the ": Ratify the story map and its stories after any change" delivery story surface.
 
 **Born-confirmed discipline (the "iter subprocesses set `human-oversight: confirmed` marker on ADRs / personas / JTBDs without an actual user-confirmation event" problem).** Before any marker write, `export CODEX_THREAD_ID` from the transcript path — the marker shim silently no-ops on an empty SID. Every `confirmed` marker MUST be backed by a same-turn human confirm event; never write `confirmed` without the `request_user_input` below (a hollow marker is the "iter subprocesses set `human-oversight: confirmed` marker on ADRs / personas / JTBDs without an actual user-confirmation event" problem bug).
 

package/skills-codex/migrate-story-map/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: migrate-story-map
+description: "Replace one eligible legacy story map with a manifest-bound canonical map from a complete adopter-ratified mapping."
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+<!-- Generated from the runtime-neutral skill source. Do not edit. -->
+
+> Codex runtime note: use `request_user_input` only where this contract
+> explicitly requires a human decision. Resolve `<itil-plugin-root>` from
+> this installed `SKILL.md`: it is two directories above the skill
+> directory. Run bundled commands from `<itil-plugin-root>/bin/`; do not
+> search the adopter repository or rely on those commands being on `PATH`.
+> Spawn `wr-itil:hang-off-check` with the native Codex subagent tool, wait
+> for it, and close that same agent.
+
+
+# Migrate Story Map
+
+Use this only for a retained legacy map whose exact historical projection is authorised by a confirmed adopter decision under the manifest-bound historical-row architecture rule.
+
+## Steps
+
+1. Read the complete legacy map and the supplied structured mapping. Confirm every historical card and placement comes from the retained source; do not infer or add content.
+2. Confirm the cited decision has `human-oversight: confirmed` and maps the selected story-map identifier to the mapping's historical SHA-256 fingerprint under `legacy-projections`.
+3. Run `<itil-plugin-root>/bin/wr-itil-migrate-story-map <legacy-map.html> <mapping.json>` from the adopter repository root. The command fails before writing on incomplete or mismatched input, and restores the source and manifest if rendering fails. It exits successfully without changes when the map is absent or already canonical.
+4. Run the repository's story-map query, renderer, accessibility, and governance checks.
+5. Run the repository's required risk review, then commit the replaced map and manifest as one auditable migration.
+
+Do not use this skill to create new history, approve an RFC, create stories, or interpret arbitrary legacy HTML automatically.
+
+$ARGUMENTS

package/templates/story-map.css

@@ -81,6 +81,7 @@ button:focus-visible,
    thing distinguishing the three states. */
 .b-live  { color: var(--live-fg);  background: var(--live-bg);  border-color: var(--live-line); }
 .b-next  { color: var(--next-fg);  background: var(--next-bg);  border-color: var(--next-line); }
+.b-history { color: var(--fg); background: var(--card); border-color: var(--line); }
 /* A row with no RFC identity, or whose stories close no problem. Deliberately
    red rather than amber: this is not "later", it is wrong, and it needs an edit
    before the map is ratified. There is no amber resting state — the `.b-later`