@sabaiway/agent-workflow-memory 3.2.0 → 4.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.