@sabaiway/agent-workflow-kit 4.5.0 → 5.0.0

package/references/scripts/archiver-structure.test.mjs

@@ -0,0 +1,39 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Structural pin (green by construction, a tripwire not a proof): all three archivers read
+// documents through the ONE shared tokenizer. A fourth archiver — or a future edit that reaches
+// for a quick raw-line regex — reds here instead of quietly reintroducing the class the tokenizer
+// retired: private frontmatter regexes, per-raw-line heading scans, fence blindness. Modeled on
+// the release-scan / doc-parity precedent of asserting over the sources themselves.
+
+const DIR = dirname(fileURLToPath(import.meta.url));
+const ARCHIVERS = ['archive-changelog.mjs', 'archive-issues.mjs', 'archive-decisions.mjs'];
+
+describe('every archiver reads through the tokenizer — no raw scan survives', () => {
+  for (const name of ARCHIVERS) {
+    const source = readFileSync(resolve(DIR, name), 'utf8');
+
+    it(`${name} imports and calls tokenizeMarkdown`, () => {
+      assert.match(source, /import \{[^}]*tokenizeMarkdown[^}]*\} from '\.\/markdown-blocks\.mjs'/);
+      assert.match(source, /tokenizeMarkdown\(/);
+    });
+
+    it(`${name} carries no private frontmatter regex`, () => {
+      // The CRLF-fragile `/^(---\n[\s\S]*?\n---\n)/` was triplicated beside each archiver; the
+      // tokenizer is now its only home.
+      assert.doesNotMatch(source, /---\\n\[\\s\\S\]/);
+    });
+
+    it(`${name} never scans raw split lines for headings`, () => {
+      // The historical form: iterate `text.split('\n')` and regex-test each raw line. Both loop
+      // shapes that carried it are banned; heading recognition belongs to the tokenizer, unit
+      // grammars apply to `heading.text` tokens only.
+      assert.doesNotMatch(source, /\.forEach\(\(line/);
+      assert.doesNotMatch(source, /for \(const line of lines\)/);
+    });
+  }
+});

package/references/scripts/markdown-blocks.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+// The ONE block model the archivers read through.
+//
+// Every archiver used to scan `text.split('\n')` itself and test regexes against raw lines. That is
+// one defect with many faces: a heading inside a fenced sample counts as real content, an unclosed
+// fence hides the rest of the file, CRLF and trailing spaces break strict matches, and each archiver
+// is wrong in its own way because each was fixed against only the inputs its author imagined. This
+// module makes that one place instead of three.
+//
+// It is deliberately SMALL. It models exactly what the archivers must not get wrong:
+//   - frontmatter as the leading block, CRLF-safe
+//   - fenced regions (``` / ~~~), with an unclosed fence at EOF a LOUD error
+//   - ATX headings, emitted only OUTSIDE fences, matched on a trailing-whitespace-free view
+//   - which lines are fenced, so a caller can find a paragraph break without bisecting a fence
+//
+// It deliberately does NOT model: inline syntax, setext headings, indented code blocks, lists,
+// blockquotes, HTML, tables, or nesting. Anything ambiguous REFUSES rather than guesses — fail-closed
+// is the product, so "refuse" is a correct answer everywhere "parse" is hard.
+//
+// Line content is returned BYTE-EXACT. Normalisation applies only to the view used for matching, so
+// re-emitting a block reproduces the file. Dependency-free, Node >= 22. No side effects on import.
+
+export const fail = (exitCode, message) => Object.assign(new Error(message), { exitCode });
+
+const FRONTMATTER_RE = /^(---\r?\n[\s\S]*?\r?\n---\r?\n)/;
+// Up to three leading spaces, then a run of at least three backticks or tildes (CommonMark).
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
+// Indented 1-3 spaces is STILL a heading in CommonMark. Emitting it matters: a consumer's unit
+// grammar is anchored at column 0, so the token exists, fails that grammar, and is refused — where
+// dropping it here would silently glue it into the block above. The separator is spaces OR tabs
+// (CommonMark): a tab-separated heading must become a token for the same reason.
+const ATX_HEADING_RE = /^ {0,3}(#{1,6})[ \t]+(.*)$/;
+const BACKTICK = '`';
+
+// The matching view of a line: trailing whitespace and any CR are invisible in rendered markdown, so
+// they must not decide whether something is a heading. A file written on Windows parses identically.
+const toMatchable = (line) => line.replace(/\s+$/, '');
+
+// A fence closes only on a bare run of the SAME marker, at least as long as the opener. An info
+// string ("```markdown") opens; a trailing info string never closes.
+const closesFence = (matchable, open) => {
+  const match = FENCE_RE.exec(matchable);
+  if (!match) return false;
+  const [, marker, info] = match;
+  return marker[0] === open.char && marker.length >= open.length && info.trim() === '';
+};
+
+// A BACKTICK fence may not carry a backtick in its info string — otherwise a line of inline code
+// (```a``` used inline) would open a fence and swallow every heading after it. Tilde fences have no
+// such restriction, which is exactly why CommonMark distinguishes them.
+const opensFence = (matchable) => {
+  const match = FENCE_RE.exec(matchable);
+  if (!match) return null;
+  const [, marker, info] = match;
+  if (marker[0] === BACKTICK && info.includes(BACKTICK)) return null;
+  return { char: marker[0], length: marker.length };
+};
+
+// Split a document into { frontmatter, lines, headings, fencedLines }.
+//
+//   frontmatter   the leading `---` block, byte-exact and possibly ''
+//   frontLines    how many lines it occupies (so a caller can report 1-based file lines)
+//   lines         the body, byte-exact, exactly as `split('\n')` would give
+//   headings      [{ index, level, text, raw }] for every ATX heading OUTSIDE a fence
+//   fencedLines   Set of body-line indexes inside a fence, fence markers included
+//
+// `label` names the source in refusals; pass the repo-relative path.
+export const tokenizeMarkdown = (text, label = 'document') => {
+  const frontMatch = FRONTMATTER_RE.exec(text);
+  // A leading `---` is ambiguous: real frontmatter, or a thematic break whose next `---` is an entry
+  // separator — in which case everything between them would be swallowed and its headings hidden.
+  // REFUSE rather than pick, because both guesses are silently wrong in opposite directions: demoting
+  // real frontmatter (a YAML comment starts with `#`) leaves it in the body to be re-emitted twice,
+  // and promoting a thematic break hides content. The caller fixes it by making the file unambiguous.
+  if (frontMatch) {
+    const suspectAt = frontMatch[1]
+      .split('\n')
+      .findIndex((line) => ATX_HEADING_RE.test(toMatchable(line)) || FENCE_RE.test(toMatchable(line)));
+    if (suspectAt !== -1) {
+      throw fail(
+        1,
+        `${label}:${suspectAt + 1}: the leading \`---\` block contains "${frontMatch[1].split('\n')[suspectAt]}", ` +
+          'so it is either frontmatter holding a heading or fence, or a thematic break whose closing `---` ' +
+          'belongs to the body — and the two are indistinguishable here. Separate them: keep frontmatter ' +
+          'free of `#` and fence lines, or put a blank line and prose before the first `---`.',
+      );
+    }
+  }
+  const frontmatter = frontMatch ? frontMatch[1] : '';
+  const frontLines = frontmatter === '' ? 0 : frontmatter.split('\n').length - 1;
+  const lines = text.slice(frontmatter.length).split('\n');
+
+  const headings = [];
+  const fencedLines = new Set();
+  let open = null;
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const matchable = toMatchable(lines[index]);
+
+    if (open) {
+      fencedLines.add(index);
+      if (closesFence(matchable, open)) open = null;
+      continue;
+    }
+
+    const fence = opensFence(matchable);
+    if (fence) {
+      open = { ...fence, index };
+      fencedLines.add(index);
+      continue;
+    }
+
+    const heading = ATX_HEADING_RE.exec(matchable);
+    if (heading) {
+      headings.push({ index, level: heading[1].length, text: matchable, raw: lines[index] });
+    }
+  }
+
+  if (open) {
+    // Left open, the remainder of the file silently stops being scanned: every later heading
+    // disappears and its text ends up inside whichever block precedes it, where a compressor that
+    // keeps only an opening paragraph will drop it — a loss that lands long after a green check.
+    throw fail(
+      1,
+      `${label}:${frontLines + open.index + 1}: "${lines[open.index]}" opens a code fence that is ` +
+        'never closed, so every heading after it is invisible and its text is silently absorbed. ' +
+        `Close it with a bare \`${open.char.repeat(open.length)}\`, then re-run.`,
+    );
+  }
+
+  return { frontmatter, frontLines, lines, headings, fencedLines };
+};
+
+// The index of the first blank line at or after `from` that is NOT inside a fence, or -1. Callers
+// that split a block into "opening paragraph" and "rest" must use this rather than a bare blank-line
+// scan: a fenced sample contains blank lines, and cutting there writes a half-fence into an archive
+// that the next run cannot read.
+export const findParagraphBreak = (lines, fencedLines, from = 0) => {
+  for (let index = from; index < lines.length; index += 1) {
+    if (lines[index].trim() === '' && !fencedLines.has(index)) return index;
+  }
+  return -1;
+};

package/references/scripts/markdown-blocks.test.mjs

@@ -0,0 +1,310 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { tokenizeMarkdown, findParagraphBreak } from './markdown-blocks.mjs';
+
+const FM = '---\ntype: history\nlastUpdated: 2026-07-28\nmaxLines: 700\n---\n';
+const B = '```';
+const T = '~~~';
+
+describe('frontmatter', () => {
+  it('splits the leading block and counts its lines, leaving the body byte-exact', () => {
+    const { frontmatter, frontLines, lines } = tokenizeMarkdown(`${FM}\n# Doc\n\n## 2026-07-20 — a\n`);
+    assert.equal(frontmatter, FM);
+    assert.equal(frontLines, 5);
+    assert.equal(lines[1], '# Doc');
+  });
+
+  it('recognises CRLF frontmatter', () => {
+    const { frontmatter, frontLines } = tokenizeMarkdown(`${FM}\n# Doc\n`.replace(/\n/g, '\r\n'));
+    assert.match(frontmatter, /^---\r\n/);
+    assert.equal(frontLines, 5);
+  });
+
+  it('tolerates a document with no frontmatter at all', () => {
+    const { frontmatter, frontLines, headings } = tokenizeMarkdown('# Doc\n\n## 2026-07-20 — a\n');
+    assert.equal(frontmatter, '');
+    assert.equal(frontLines, 0);
+    assert.equal(headings.length, 2);
+  });
+
+  it('REFUSES a leading `---` block that is indistinguishable from a thematic break', () => {
+    assert.throws(
+      () => tokenizeMarkdown('---\n\n# Doc\n\n## 2026-07-20 — a\n\n---\n\n## 2026-07-19 — b\n', 'docs/ai/changelog.md'),
+      (err) => {
+        assert.equal(err.exitCode, 1);
+        assert.match(err.message, /docs\/ai\/changelog\.md:3:/);
+        return true;
+      },
+    );
+  });
+
+  it('REFUSES rather than silently demoting frontmatter that holds a YAML comment', () => {
+    // Demoting it would leave the real frontmatter in the body, so a rebuild writes a fresh one and
+    // the original is duplicated. Guessing the other way hides content. Both are silent; refuse.
+    assert.throws(
+      () => tokenizeMarkdown('---\n# pinned by AD-084\ntype: history\n---\n\n## 2026-07-20 — a\n', 'f.md'),
+      /f\.md:2:/,
+    );
+  });
+});
+
+describe('headings', () => {
+  it('reports level, index and a trailing-whitespace-free text, keeping raw byte-exact', () => {
+    const { headings } = tokenizeMarkdown(`${FM}\n## 2026-07-20 — a  \n\n### deeper\n`);
+    assert.deepEqual(headings.map((h) => h.level), [2, 3]);
+    assert.equal(headings[0].text, '## 2026-07-20 — a');
+    assert.equal(headings[0].raw, '## 2026-07-20 — a  ');
+  });
+
+  it('sees a heading that carries a CR, so a Windows file parses identically', () => {
+    const { headings } = tokenizeMarkdown(`${FM}\n## 2026-07-20\n`.replace(/\n/g, '\r\n'));
+    assert.equal(headings.length, 1);
+    assert.equal(headings[0].text, '## 2026-07-20');
+  });
+
+  it('emits an indented heading as a TOKEN so a column-0 grammar can refuse it loudly', () => {
+    const { headings } = tokenizeMarkdown(`${FM}\n## 2026-07-20 — a\n\n  ## 2026-07-19 — indented\n`);
+    assert.deepEqual(headings.map((h) => h.text), ['## 2026-07-20 — a', '  ## 2026-07-19 — indented']);
+  });
+
+  it('does not treat a bare hash run without a space as a heading', () => {
+    const { headings } = tokenizeMarkdown(`${FM}\n##notaheading\n`);
+    assert.equal(headings.length, 0);
+  });
+
+  it('a tab after the hashes still makes a heading token (CommonMark allows spaces or tabs)', () => {
+    const { headings } = tokenizeMarkdown(`${FM}\n##\t2026-07-18 — tab separated\n`);
+    assert.deepEqual(headings.map((h) => h.level), [2]);
+    assert.equal(headings[0].text, '##\t2026-07-18 — tab separated');
+  });
+});
+
+describe('fences', () => {
+  it('hides headings inside a backtick fence', () => {
+    const { headings, fencedLines } = tokenizeMarkdown(
+      `${FM}\n## 2026-07-20 — real\n\n${B}markdown\n## 2026-07-19 — a sample\n${B}\n\nend.\n`,
+    );
+    assert.deepEqual(headings.map((h) => h.text), ['## 2026-07-20 — real']);
+    assert.equal(fencedLines.has(3), true);
+    assert.equal(fencedLines.has(5), true);
+  });
+
+  it('a backtick run whose info string contains a backtick is inline code, not a fence', () => {
+    const { headings } = tokenizeMarkdown(
+      `${FM}\n${B}a${B} used inline\n\n## 2026-07-20 — a real entry\n\nbody.\n\n${B}\nsample\n${B}\n`,
+    );
+    assert.deepEqual(headings.map((h) => h.text), ['## 2026-07-20 — a real entry']);
+  });
+
+  it('a tilde fence MAY carry backticks in its info string', () => {
+    const { headings } = tokenizeMarkdown(`${FM}\n${T}a${B}\n## 2026-07-19 — fenced\n${T}\n\n## 2026-07-20 — real\n`);
+    assert.deepEqual(headings.map((h) => h.text), ['## 2026-07-20 — real']);
+  });
+
+  it('closes only on the same marker, so a backtick run inside a tilde fence stays content', () => {
+    const { headings } = tokenizeMarkdown(
+      `${FM}\n## 2026-07-20 — real\n\n${T}markdown\n${B}\n## 2026-07-19 — nested sample\n${B}\n${T}\n\nend.\n`,
+    );
+    assert.deepEqual(headings.map((h) => h.text), ['## 2026-07-20 — real']);
+  });
+
+  it('needs a closer at least as long as the opener', () => {
+    const { headings } = tokenizeMarkdown(
+      `${FM}\n## 2026-07-20 — real\n\n\`\`\`\`\n${B}\n## 2026-07-19 — still fenced\n\`\`\`\`\n\nend.\n`,
+    );
+    assert.deepEqual(headings.map((h) => h.text), ['## 2026-07-20 — real']);
+  });
+
+  it('does not let an info string close a fence', () => {
+    const { headings } = tokenizeMarkdown(
+      `${FM}\n## 2026-07-20 — real\n\n${B}markdown\n${B}js\n## 2026-07-19 — still fenced\n${B}\n\nend.\n`,
+    );
+    assert.deepEqual(headings.map((h) => h.text), ['## 2026-07-20 — real']);
+  });
+
+  it('REFUSES an unclosed fence, naming the 1-based file line that opened it', () => {
+    let caught;
+    try {
+      tokenizeMarkdown(`${FM}\n## 2026-07-20 — real\n\n${B}markdown\n## 2026-07-19 — hidden\n`, 'docs/ai/changelog.md');
+    } catch (err) {
+      caught = err;
+    }
+    assert.ok(caught, 'expected a refusal');
+    assert.equal(caught.exitCode, 1);
+    assert.match(caught.message, /docs\/ai\/changelog\.md:9:/);
+    assert.match(caught.message, /never closed/);
+  });
+});
+
+describe('findParagraphBreak', () => {
+  it('skips blank lines that live inside a fence', () => {
+    const { lines, fencedLines } = tokenizeMarkdown(`${FM}\n## 2026-07-20 — a\n${B}\nx\n\ny\n${B}\n\nafter.\n`);
+    assert.equal(fencedLines.has(4), true);
+    assert.equal(findParagraphBreak(lines, fencedLines, 1), 7);
+  });
+
+  it('returns -1 when no unfenced blank line follows', () => {
+    const { lines, fencedLines } = tokenizeMarkdown(`${FM}\n## 2026-07-20 — a\nbody.\n`);
+    assert.equal(findParagraphBreak(lines, fencedLines, 4), -1);
+  });
+});
+
+// ── properties over generated documents ───────────────────────────────────────────────
+//
+// The generator builds each document AND its ground truth in the SAME pass, by construction: when
+// it emits a fenced region it records those line indexes directly, never by re-deriving them with a
+// regex. So the oracle is independent of the tokenizer's logic, and a disagreement is a real
+// failure rather than two copies of the same mistake agreeing.
+//
+// It deliberately emits the shapes that shipped as bugs: unclosed fences mid-document, closers that
+// are too short, closers carrying an info string, the other marker inside a fence, backtick inline
+// code at column 0, indented headings, trailing whitespace, and both line endings. Seeded, so a
+// failure replays from its seed alone.
+
+const buildDocument = (seed) => {
+  let state = seed;
+  // Drawn from the HIGH bits: this LCG's low bit strictly alternates, so `state % 2` is fixed by
+  // call parity and every other two-apart draw correlates. With the low bits, a backtick fence
+  // carrying an info string was unreachable in every seed — a generator blind spot that looks like
+  // coverage.
+  const rand = (n) => {
+    state = (state * 1103515245 + 12345) % 2147483648;
+    return Math.floor(state / 65536) % n;
+  };
+
+  const eol = rand(2) === 0 ? '\n' : '\r\n';
+  const rows = [];
+  const fenced = new Set();
+  const headings = [];
+  let unclosedAt = null;
+
+  const pushHeading = () => {
+    const indent = ' '.repeat(rand(4));
+    const hashes = '#'.repeat(2 + rand(2));
+    const body = rand(2) === 0 ? `2026-07-2${rand(9)} — entry` : `2026-7-${rand(9)} — malformed`;
+    const text = `${indent}${hashes} ${body}`;
+    headings.push({ index: rows.length, text });
+    rows.push(text + ' '.repeat(rand(3)));
+  };
+
+  const pushFence = (allowUnclosed) => {
+    const char = rand(2) === 0 ? '`' : '~';
+    const length = 3 + rand(3);
+    const marker = char.repeat(length);
+    const info = rand(2) === 0 ? '' : 'markdown';
+    const openIndex = rows.length;
+    fenced.add(openIndex);
+    rows.push(`${marker}${info}` + ' '.repeat(rand(3)));
+
+    const inner = [
+      `## 2026-07-1${rand(9)} — fenced sample`,
+      '',
+      char.repeat(length - 1), // too short to close
+      `${marker}js`, // info string never closes
+      (char === '`' ? '~' : '`').repeat(length + 1), // the other marker never closes
+      'plain fenced text',
+    ];
+    const innerCount = 1 + rand(inner.length);
+    for (let i = 0; i < innerCount; i += 1) {
+      fenced.add(rows.length);
+      rows.push(inner[(i + rand(inner.length)) % inner.length]);
+    }
+
+    if (allowUnclosed && rand(4) === 0) {
+      unclosedAt = openIndex;
+      return;
+    }
+    fenced.add(rows.length);
+    rows.push(char.repeat(length + rand(2)) + ' '.repeat(rand(3)));
+  };
+
+  const frontmatter = rand(2) === 0 ? FM.replace(/\n/g, eol) : '';
+  const segmentCount = 3 + rand(5);
+  // An unclosed fence may open ANYWHERE, not only last: the generator keeps emitting after it and
+  // marks the remainder fenced, so the refusal is exercised with real content behind it rather than
+  // at a convenient end-of-file.
+  for (let i = 0; i < segmentCount; i += 1) {
+    if (unclosedAt !== null) {
+      fenced.add(rows.length);
+      rows.push(rand(2) === 0 ? `## 2026-07-0${i} — hidden behind the open fence` : `trailing text ${i}`);
+      continue;
+    }
+    const kind = rand(5);
+    if (kind === 0) pushHeading();
+    else if (kind === 1) rows.push('');
+    else if (kind === 2) rows.push(`${B}inline${B} used in prose`);
+    else if (kind === 3) pushFence(true);
+    else rows.push(`body text ${i}`);
+  }
+
+  return { text: frontmatter + rows.join(eol) + eol, frontmatter, fenced, headings, unclosedAt };
+};
+
+describe('properties over generated documents', () => {
+  const SEEDS = 400;
+
+  it('the fenced-line set equals the oracle the generator recorded', () => {
+    for (let seed = 1; seed <= SEEDS; seed += 1) {
+      const doc = buildDocument(seed);
+      if (doc.unclosedAt !== null) continue;
+      const { fencedLines } = tokenizeMarkdown(doc.text, `seed-${seed}`);
+      assert.deepEqual([...fencedLines].sort((a, b) => a - b), [...doc.fenced].sort((a, b) => a - b), `seed ${seed}`);
+    }
+  });
+
+  it('the heading tokens equal the oracle — index and text', () => {
+    for (let seed = 1; seed <= SEEDS; seed += 1) {
+      const doc = buildDocument(seed);
+      if (doc.unclosedAt !== null) continue;
+      const { headings } = tokenizeMarkdown(doc.text, `seed-${seed}`);
+      assert.deepEqual(
+        headings.map((h) => ({ index: h.index, text: h.text })),
+        doc.headings,
+        `seed ${seed}`,
+      );
+    }
+  });
+
+  it('an unclosed fence always refuses, naming the line the generator opened it on', () => {
+    let covered = 0;
+    for (let seed = 1; seed <= SEEDS; seed += 1) {
+      const doc = buildDocument(seed);
+      if (doc.unclosedAt === null) continue;
+      covered += 1;
+      const frontLines = doc.frontmatter === '' ? 0 : doc.frontmatter.split('\n').length - 1;
+      assert.throws(
+        () => tokenizeMarkdown(doc.text, `seed-${seed}`),
+        (err) => {
+          assert.equal(err.exitCode, 1, `seed ${seed}`);
+          assert.ok(
+            err.message.startsWith(`seed-${seed}:${frontLines + doc.unclosedAt + 1}:`),
+            `seed ${seed}: refusal names the wrong line — ${err.message.slice(0, 60)}`,
+          );
+          return true;
+        },
+      );
+    }
+    assert.ok(covered >= 10, `the generator must actually produce unclosed fences (got ${covered})`);
+  });
+
+  it('line endings never change the block structure', () => {
+    for (let seed = 1; seed <= SEEDS; seed += 1) {
+      const doc = buildDocument(seed);
+      if (doc.unclosedAt !== null) continue;
+      const lf = doc.text.replace(/\r\n/g, '\n');
+      const a = tokenizeMarkdown(lf, `seed-${seed}`);
+      const b = tokenizeMarkdown(lf.replace(/\n/g, '\r\n'), `seed-${seed}`);
+      assert.deepEqual(a.headings.map((h) => h.text), b.headings.map((h) => h.text), `seed ${seed}`);
+      assert.deepEqual([...a.fencedLines], [...b.fencedLines], `seed ${seed}`);
+    }
+  });
+
+  it('the body is returned byte-exact — rejoining reproduces the input', () => {
+    for (let seed = 1; seed <= SEEDS; seed += 1) {
+      const doc = buildDocument(seed);
+      if (doc.unclosedAt !== null) continue;
+      const { frontmatter, lines } = tokenizeMarkdown(doc.text, `seed-${seed}`);
+      assert.equal(frontmatter + lines.join('\n'), doc.text, `seed ${seed}`);
+    }
+  });
+});

package/references/templates/changelog.md

@@ -10,7 +10,9 @@ maxLines: 700
 # AI Session Changelog
 
 > One entry per session. Newest at the top. Entries roll off to `history/recent.md` (WARM) then `history/YYYY-MM.md` (COLD) via the archive script.
-> Heading format is load-bearing for rotation: `## YYYY.MM.DD — <title>`.
+> Heading format is load-bearing for rotation: `## YYYY-MM-DD — <title>`. The rotator also still
+> reads the legacy dotted form `## YYYY.MM.DD`, so existing archives keep working — but write ISO,
+> the form every other date in this substrate uses, including `lastUpdated:` above.
 
 ## {{DATE}} — Bootstrap
 

package/references/templates/known_issues.md

@@ -11,6 +11,19 @@ maxLines: 300
 
 > Every bug we hit. Status, workaround, impact, plan. Avoids re-discovering pain.
 
+When an issue is resolved, move its section under `## 🟢 Resolved` and REPLACE its
+`- **Status:**` line with a line-leading ISO-dated `**Resolved:**` field — that one dated line is
+what the archive script reads (the legacy `**Status:** ✅ FIXED (YYYY-MM-DD)` form is still read;
+~~strikethrough~~ on the heading is optional decoration). Keeping an open `Status:` line next to a
+dated `Resolved:` line refuses loudly. Write it like this:
+
+```markdown
+### ~~Issue-042 — Example resolved issue~~
+- **Resolved:** 2026-01-15 — what fixed it ([[AD-NNN]])
+- **Resolution:** the fix, one line
+- **Commit:** abc1234
+```
+
 ## 🔴 Open
 
 ### Issue-001 — {{Title}}
@@ -23,11 +36,6 @@ maxLines: 300
 
 ## 🟢 Resolved
 
-### Issue-XXX — {{Title}}
-- **Resolved:** {{DATE}}
-- **Resolution:** {{what fixed it}}
-- **Commit:** {{SHA}}
-
 ---
 
 > Resolved issues older than the window are rotated to `history/issues-resolved.md` by the issue-archive script.

package/tools/known-footprint.mjs

@@ -29,7 +29,7 @@ export const stop = (message, fields = {}) =>
 // ── registries ────────────────────────────────────────────────────────────────
 
 // The kit's OWN footprint — canonical anchored patterns. `/docs/ai/` subsumes the deployment stamp
-// (`.workflow-version`); the 8 enforcement scripts are enumerated (no bare `/scripts/` — a host repo
+// (`.workflow-version`); the enforcement scripts are enumerated (no bare `/scripts/` — a host repo
 // may have unrelated scripts). `/.claude/settings.json` is carried HIDDEN-ONLY: in hidden mode the
 // kit's own attribution file is a footprint; in visible mode the kit commits it and never runs this
 // tool. It passes the same tracked→ASK classifier, so a project that already commits it gets an ASK,
@@ -43,13 +43,17 @@ export const KIT_OWN_PATHS = [
   '/scripts/_expect-shim.mjs',
   '/scripts/archive-changelog.mjs',
   '/scripts/archive-changelog.test.mjs',
+  '/scripts/archive-conservation.test.mjs',
   '/scripts/archive-decisions.mjs',
   '/scripts/archive-decisions.test.mjs',
   '/scripts/archive-issues.mjs',
   '/scripts/archive-issues.test.mjs',
+  '/scripts/archiver-structure.test.mjs',
   '/scripts/check-docs-size.mjs',
   '/scripts/check-docs-size.test.mjs',
   '/scripts/install-git-hooks.mjs',
+  '/scripts/markdown-blocks.mjs',
+  '/scripts/markdown-blocks.test.mjs',
   '/docs/plans/',
   '/.claude/settings.local.json',
   '/.claude/settings.json',

package/tools/migrate-adr-store.mjs

@@ -119,6 +119,26 @@ export const planScriptRefresh = (cwd, deps = {}) => {
   return out;
 };
 
+// COMPANION seeds: modules the refreshed archivers IMPORT. The refresh above is deliberately
+// directional (never ADDS a basename the consumer lacks), but refreshing an OLD deployment's
+// archivers to this kit's canon without their runtime dependency would leave every refreshed
+// script crashing on a missing `./markdown-blocks.mjs` import until a separate upgrade run — so
+// the dependency rides the SAME apply, atomically, written before its importers.
+const COMPANION_SEEDS = ['markdown-blocks.mjs', 'markdown-blocks.test.mjs'];
+export const planCompanionSeeds = (cwd, refresh, deps = {}) => {
+  if (refresh.length === 0) return [];
+  const exists = deps.exists ?? existsSync;
+  const kitScripts = deps.kitScripts ?? KIT_SCRIPTS;
+  const consumerScripts = join(cwd, CONSUMER_SCRIPTS_REL);
+  const out = [];
+  for (const name of COMPANION_SEEDS) {
+    const canon = join(kitScripts, name);
+    const dst = join(consumerScripts, name);
+    if (exists(canon) && !exists(dst)) out.push({ name, canon, dst });
+  }
+  return out;
+};
+
 const gitDirOf = (cwd, spawn) => {
   const r = spawn('git', ['rev-parse', '--absolute-git-dir'], { cwd, encoding: 'utf8' });
   return r && r.status === 0 && r.stdout ? r.stdout.trim() : null;
@@ -206,10 +226,15 @@ const applyScriptRefresh = (cwd, refresh, deps = {}) => {
   const read = deps.read ?? readFileSync;
   const chmod = deps.chmod ?? chmodSync;
   const stat = deps.stat ?? statSync;
-  for (const { canon, dst, name } of refreshOrder(refresh)) {
+  // Companion modules FIRST (a dependency must land before its importers), refresh order after —
+  // the discriminator still last, so an interrupted apply always re-plans in full. Returns the
+  // seeded names (computed pre-write; recomputing after would see them present and report none).
+  const seeds = planCompanionSeeds(cwd, refresh, deps);
+  for (const { canon, dst, name } of [...seeds, ...refreshOrder(refresh)]) {
     writeContainedFileAtomic(cwd, dst, read(canon, 'utf8'), deps, { stop, label: `${CONSUMER_SCRIPTS_REL}/${name}` });
     chmod(dst, stat(canon).mode & 0o777); // the exec bit is the git-tracked axis the mirror guard pins
   }
+  return seeds.map((s) => s.name);
 };
 
 // ── the no-monolith crossing ─────────────────────────────────────────────────────
@@ -307,6 +332,7 @@ const crossWithoutMonolith = (cwd, args, stamp, { log, error, runMigrate, deps }
     log(`  ${ADR_DIR_REL}/: ${hasStore ? 'present, but the crossing has not been completed' : 'absent'}`);
     log(`  snapshot → ${preview.dir ? `${preview.dir} (${preview.viaGitDir ? 'git dir' : 'out-of-tree fallback'})` : 'NONE — no out-of-tree location; run inside a git repo (apply would refuse otherwise)'}`);
     log(`  refresh ${refresh.length} enforcement script(s) to this kit's version${drifted.length ? ` (${drifted.length} locally differ: ${drifted.map((r) => r.name).join(', ')})` : ''}`);
+    for (const s of planCompanionSeeds(cwd, refresh, deps)) log(`  seed companion module ${CONSUMER_SCRIPTS_REL}/${s.name} (imported by the refreshed archivers; absent at the consumer)`);
     log(`  then seed the store: create ${ADR_DIR_REL}/, write ${NAV_REL} and regenerate docs/ai/index.md`);
     const code = preflight((m) => error(`    ${m}`));
     if (code !== EXIT_OK) {
@@ -328,7 +354,7 @@ const crossWithoutMonolith = (cwd, args, stamp, { log, error, runMigrate, deps }
   const snapshot = writeSnapshot(cwd, refresh, stamp, deps);
   // The FULL refresh is re-planned and re-applied on every entry, so an interrupted one always
   // completes; the discriminator script is written last (see refreshOrder).
-  applyScriptRefresh(cwd, refresh, deps);
+  const seededNames = applyScriptRefresh(cwd, refresh, deps);
 
   // Capture the index-regeneration verdict instead of matching log prose: the rotator logs a failed
   // regeneration and still returns 0, so "the gates are green" would not mean the index is fresh.
@@ -359,7 +385,7 @@ const crossWithoutMonolith = (cwd, args, stamp, { log, error, runMigrate, deps }
   // interrupted crossing whose scripts were already current, which no "old-scheme" claim covers.
   log('[migrate-adr-store] crossing complete — the one-file-per-ADR store is in place (no legacy monolith was present):');
   log(`  snapshot: ${snapshot.dir} (${snapshot.viaGitDir ? 'git dir' : 'out-of-tree fallback'}, ${snapshot.fileCount} file(s))`);
-  log(`  refreshed ${refresh.length} enforcement script(s) to this kit's version`);
+  log(`  refreshed ${refresh.length} enforcement script(s) to this kit's version${seededNames.length ? ` + seeded ${seededNames.join(', ')}` : ''}`);
   log(`  seeded ${ADR_DIR_REL}/ with ${NAV_REL} and regenerated docs/ai/index.md`);
   log('  next: run the normal upgrade (it re-stamps the deployment lineage to the current head),');
   log('  then review the migrated docs/ai/ tree and the re-stamp together and commit them yourself — this command never commits.');
@@ -394,6 +420,7 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
       log(`  old layout: ${monoliths.join(', ')} (will be exploded into ${ADR_DIR_REL}/ then retired)`);
       log(`  snapshot → ${preview.dir ? `${preview.dir} (${preview.viaGitDir ? 'git dir' : 'out-of-tree fallback'})` : 'NONE — no out-of-tree location; run inside a git repo (apply would refuse otherwise)'}`);
       log(`  refresh ${refresh.length} enforcement script(s) to this kit's version${drifted.length ? ` (${drifted.length} locally differ: ${drifted.map((r) => r.name).join(', ')})` : ''}`);
+    for (const s of planCompanionSeeds(cwd, refresh, deps)) log(`  seed companion module ${CONSUMER_SCRIPTS_REL}/${s.name} (imported by the refreshed archivers; absent at the consumer)`);
       log('  then the conservation-checked rotation:');
       // Surface the rotation's own exit code: a failed dry-run must NOT print the
       // "run with --apply" go-ahead nor exit 0 — it would send the user to --apply on an unsafe tree.
@@ -419,14 +446,14 @@ export const main = (argv = process.argv.slice(2), deps = {}) => {
     }
 
     const snapshot = writeSnapshot(cwd, refresh, stamp, deps);
-    applyScriptRefresh(cwd, refresh, deps);
+    const seededNames = applyScriptRefresh(cwd, refresh, deps);
     const code = runMigrate(['--migrate', '--apply'], { root: cwd, log, logError: error });
     if (code !== EXIT_OK) {
       throw stop(`the rotation failed (exit ${code}) — the pre-migration snapshot is at ${snapshot.dir}; resolve the reported problem and re-run (the migration is idempotent).`);
     }
     log('[migrate-adr-store] migrated the 3-tier ADR cascade → one-file-per-ADR store:');
     log(`  snapshot: ${snapshot.dir} (${snapshot.viaGitDir ? 'git dir' : 'out-of-tree fallback'}, ${snapshot.fileCount} file(s))`);
-    log(`  refreshed ${refresh.length} enforcement script(s) to this kit's version`);
+    log(`  refreshed ${refresh.length} enforcement script(s) to this kit's version${seededNames.length ? ` + seeded ${seededNames.join(', ')}` : ''}`);
     log('  next: run the normal upgrade (it re-stamps the deployment lineage to the current head),');
     log('  then review the migrated docs/ai/ tree and the re-stamp together and commit them yourself — this command never commits.');
     return EXIT_OK;