@sabaiway/agent-workflow-memory 1.12.0 → 2.0.0

package/references/scripts/check-docs-size.mjs

@@ -270,6 +270,31 @@ const formatIndexRow = (row) => {
   return `| ${link} | ${fm.type ?? '—'} | ${row.lineCount}/${fm.maxLines ?? '—'} | ${fm.lastUpdated ?? '—'} | ${fm.staleAfter ?? '—'} |`;
 };
 
+// The one-file-per-ADR store (docs/ai/adr/) grows O(n) forever, so its rows would blow the index's
+// own 80-line cap. It COLLAPSES to a single aggregate row (link → the navigator adr/log.md, record
+// count + numeric id range) — while walkMarkdownFiles still finds + cap-checks every individual body
+// (a body over its own cap still fails in the main flow; only the index RENDERING is collapsed).
+const ADR_DIR_PREFIX = 'docs/ai/adr/';
+const ADR_RECORD_RE = /\/AD-(\d{3,})-[^/]*\.md$/;
+const ADR_NAV_PATH = 'docs/ai/adr/log.md';
+
+// Only genuine records + the navigator collapse into the aggregate row; an UNEXPECTED file under
+// adr/ (a stray README.md, AD-foo.md) renders as its OWN visible index row — never silently hidden
+// by the collapse (it also fails archive-decisions' own store-integrity check).
+const isCollapsibleAdr = (path) => path.startsWith(ADR_DIR_PREFIX) && (ADR_RECORD_RE.test(path) || path === ADR_NAV_PATH);
+
+const formatAdrCollapseRow = (adrRows) => {
+  const recs = adrRows
+    .map((r) => {
+      const m = r.path.match(ADR_RECORD_RE);
+      return m ? { idStr: m[1], idNum: Number(m[1]) } : null;
+    })
+    .filter(Boolean)
+    .sort((a, b) => a.idNum - b.idNum); // NUMERIC id ordering (AD-200 before AD-1000), never lexical
+  const range = recs.length > 0 ? `AD-${recs[0].idStr} … AD-${recs[recs.length - 1].idStr}` : '—';
+  return `| [\`adr/\`](./adr/log.md) | adr | ${recs.length} records | ${range} | — |`;
+};
+
 // Pure index renderer — given inspected rows + the date to stamp in the header,
 // returns the exact bytes `docs/ai/index.md` should contain. Shared by
 // `--write-index` (writes it) and `--check-index` (diffs against on-disk).
@@ -277,13 +302,18 @@ export const buildIndex = (rows, todayStr, meta = {}) => {
   const projectName = meta.projectName ?? DEFAULT_PROJECT_NAME;
   const onDemandLinks = meta.onDemandLinks ?? [];
   const hierarchicalLinks = meta.hierarchicalLinks ?? [];
-  const sorted = [...rows].sort((a, b) => a.path.localeCompare(b.path));
   const header = INDEX_HEADER.replace('__TODAY__', todayStr).replace('__PROJECT__', projectName);
   const tableHeader = `| File | Type | Lines/Max | Updated | Stale after |\n|------|------|-----------|---------|-------------|`;
-  const tableRows = sorted
-    .filter((r) => r.path !== 'docs/ai/index.md')
-    .map(formatIndexRow)
-    .join('\n');
+  const nonAdr = [];
+  const adrRows = [];
+  for (const r of rows) {
+    if (r.path === 'docs/ai/index.md') continue;
+    (isCollapsibleAdr(r.path) ? adrRows : nonAdr).push(r);
+  }
+  const tableEntries = nonAdr.map((r) => ({ sortPath: r.path, md: formatIndexRow(r) }));
+  if (adrRows.length > 0) tableEntries.push({ sortPath: ADR_DIR_PREFIX, md: formatAdrCollapseRow(adrRows) });
+  tableEntries.sort((a, b) => a.sortPath.localeCompare(b.sortPath));
+  const tableRows = tableEntries.map((e) => e.md).join('\n');
   const onDemandSection =
     onDemandLinks.length > 0
       ? `\n\n## Skills (on-demand)\n\n${onDemandLinks.map((link) => `- ${link}`).join('\n')}`

package/references/scripts/check-docs-size.test.mjs

@@ -164,6 +164,61 @@ const makeRow = (path, overrides = {}) => ({
   ...overrides,
 });
 
+// The one-file-per-ADR store collapses to a SINGLE aggregate index row so the index stays under its
+// own 80-line cap no matter how many records accumulate — while every body is still cap-checked.
+describe('buildIndex — docs/ai/adr/ directory collapse (Decision 11)', () => {
+  it('200 synthetic AD-*.md records collapse to ONE aggregate row; the index stays ≤ 80 lines', () => {
+    const adr = Array.from({ length: 200 }, (_, i) => makeRow(`docs/ai/adr/AD-${String(i + 1).padStart(3, '0')}-record-${i}.md`, { frontmatter: { type: 'adr', maxLines: '400', lastUpdated: '2026-07-09', staleAfter: 'never' } }));
+    const rows = [makeRow('docs/ai/handover.md'), makeRow('docs/ai/adr/log.md', { frontmatter: { type: 'reference', maxLines: '200' } }), ...adr];
+    const out = buildIndex(rows, '2026-07-09');
+    const adrRowLines = out.split('\n').filter((l) => l.includes('](./adr/log.md)'));
+    expect(adrRowLines.length).toBe(1); // exactly one row references the whole adr/ tree
+    expect(out).not.toMatch(/AD-001-record-0\.md/); // individual records are NOT listed
+    expect(out.split('\n').length <= 80).toBe(true);
+  });
+
+  it('a stray adr/ markdown file renders as its OWN visible row (never collapsed/hidden)', () => {
+    const rows = [
+      makeRow('docs/ai/adr/AD-001-a.md', { frontmatter: { type: 'adr', maxLines: '400' } }),
+      makeRow('docs/ai/adr/log.md', { frontmatter: { type: 'reference', maxLines: '200' } }),
+      makeRow('docs/ai/adr/notes.md', { frontmatter: { type: 'reference', maxLines: '100' } }),
+    ];
+    const out = buildIndex(rows, '2026-07-09');
+    expect(out).toMatch(/adr\/notes\.md/); // the stray is a visible row, not swallowed by the collapse
+    const aggregateRows = out.split('\n').filter((l) => l.includes('](./adr/log.md)'));
+    expect(aggregateRows.length).toBe(1); // exactly one aggregate row for the real record(s)
+  });
+
+  it('the aggregate row shows the record count and a NUMERIC id range (AD-200 … AD-1000)', () => {
+    const rows = [
+      makeRow('docs/ai/adr/AD-200-a.md', { frontmatter: { type: 'adr', maxLines: '400' } }),
+      makeRow('docs/ai/adr/AD-1000-b.md', { frontmatter: { type: 'adr', maxLines: '400' } }),
+      makeRow('docs/ai/adr/log.md', { frontmatter: { type: 'reference', maxLines: '200' } }),
+    ];
+    const out = buildIndex(rows, '2026-07-09');
+    expect(out).toMatch(/\[`adr\/`\]\(\.\/adr\/log\.md\) \| adr \| 2 records \| AD-200 … AD-1000/);
+  });
+
+  it('adding a record drifts the collapse row → checkIndexFreshness flags it stale', () => {
+    const base = [makeRow('docs/ai/adr/AD-001-a.md', { frontmatter: { type: 'adr', maxLines: '400' } }), makeRow('docs/ai/adr/log.md', { frontmatter: { type: 'reference', maxLines: '200' } })];
+    const onDisk = buildIndex(base, '2026-07-09');
+    const grown = [...base, makeRow('docs/ai/adr/AD-002-b.md', { frontmatter: { type: 'adr', maxLines: '400' } })];
+    expect(checkIndexFreshness(grown, onDisk).fresh).toBe(false);
+  });
+
+  it('a single adr record OVER its own cap still fails inspectFile (the collapse never hides a fat body)', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'adr-cap-'));
+    try {
+      const path = join(dir, 'AD-001-huge.md');
+      await writeFile(path, `---\ntype: adr\nlastUpdated: 2026-07-09\nscope: permanent\nstaleAfter: never\nowner: none\nmaxLines: 5\n---\n\n## AD-001 — Huge\n${'x\n'.repeat(20)}`);
+      const result = await inspectFile(path, computeToday('2026-07-09'));
+      expect(result.errors.some((e) => /lines > maxLines/.test(e))).toBe(true);
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  });
+});
+
 describe('buildIndex', () => {
   it('is deterministic, sorts rows by path, and excludes index.md itself', () => {
     const rows = [

package/references/templates/adr/log.md

@@ -0,0 +1,25 @@
+---
+type: reference
+lastUpdated: {{DATE}}
+scope: permanent
+staleAfter: never
+owner: none
+maxLines: 200
+---
+
+# ADR Navigator — active set (AD-001 … AD-001)
+
+> **Auto-generated** (`archive-decisions.mjs --write-navigator`). The governing heads only —
+> an ADR superseded/amended by another drops OUT (still reachable by filename, grep, or the
+> `[[AD-NNN]]` chain). The HOT window lives in [`../decisions.md`](../decisions.md); every
+> archived record is one file in this directory. This is a navigator, never a full ledger.
+
+## Governing (1) — accepted & not superseded
+
+| ADR | Title | Record |
+|-----|-------|--------|
+| AD-001 | Adopt AI-agent memory system (`docs/ai/`) | [`../decisions.md`](../decisions.md) |
+
+## Recent (1)
+
+- **AD-001** — governing — `decisions.md (HOT)`

package/references/templates/adr-record.md

@@ -0,0 +1,72 @@
+# ADR record format — authoring & lifecycle reference
+
+> How an Architecture Decision Record is authored, archived, and retrieved in this project's
+> **one-file-per-ADR** store. Read this when you author a new ADR or change an existing one's
+> lifecycle. This file is a reference — it is **not** deployed into `docs/ai/` (it never becomes a
+> record itself).
+
+## Where ADRs live
+
+- **HOT window — `docs/ai/decisions.md`.** The active ADR window. You **author here**, newest at the
+  bottom. It is self-bounding under its frontmatter `maxLines`.
+- **Store — `docs/ai/adr/AD-NNN-slug.md`.** One immutable record per archived ADR (full frontmatter +
+  the verbatim `## AD-NNN — title` block). You **never hand-write** these — `archive-decisions.mjs`
+  produces them by exploding the oldest HOT entries beyond the cap.
+- **Navigator — `docs/ai/adr/log.md`.** The one generated map: the currently-governing heads
+  (accepted ∧ not superseded) + a recent window. Superseded ADRs drop OUT (still reachable by
+  filename, grep, or the `[[AD-NNN]]` chain). It is a navigator, never a full ledger.
+
+## Authoring a new ADR (in the HOT window)
+
+Append a block at the **bottom** of `docs/ai/decisions.md`:
+
+```
+## AD-NNN — <concise title>
+
+**Date:** YYYY-MM-DD
+**Status:** Accepted
+
+**Context.** Why this decision is needed; the forces at play.
+**Decision.** What was chosen (imperative, unambiguous).
+**Consequences.** ➕ benefits · ➖ costs. Note any ADR this supersedes.
+```
+
+- **ID grammar: `AD-\d{3,}`.** Three digits minimum; `AD-1000+` is valid. Allocate the next integer
+  after the highest id across HOT ∪ `adr/`. Ordering is always **numeric**, never lexical.
+- **The `## AD-NNN — <title>` heading is strict.** Use the em dash ` — `. A non-canonical `## ` heading
+  is a loud parse failure — the store never silently glues an entry to the previous body.
+- **`slug` is cosmetic and frozen at creation** (`slugify(title)`); the `AD-NNN` prefix is the key. A
+  retitle never renames the file.
+- The block is preserved **verbatim** when it is archived, so write it as you want it to persist.
+
+## Lifecycle (the only mutable part after acceptance)
+
+The **body is immutable** once accepted — only lifecycle changes. Express supersession in the body of
+the **new** ADR; governance is then computed automatically (no predecessor-file edit is required):
+
+| Body form (in the newer ADR)     | Effect                                                            |
+|----------------------------------|------------------------------------------------------------------|
+| `Supersedes [[AD-NNN]]`          | retires AD-NNN (when the citing ADR is `accepted`)               |
+| `Superseded by [[AD-NNN]]`       | marks this ADR retired by AD-NNN                                  |
+| `Amended by [[AD-NNN]]`          | marks this ADR amended (also drops it from the governing heads)  |
+
+- **`status`** is the leading word of `**Status:**`, lowercased (`accepted` / `superseded` /
+  `amended` / `deprecated`). A **missing** `**Status:**` line defaults to `accepted` (the in-force
+  default). Only `accepted` ADRs govern.
+- When an ADR is archived, its record frontmatter backfills `status`, `date`, `supersedes`, and
+  `supersededBy` from these body forms — you do not maintain the frontmatter by hand.
+
+## Retrieval (never through an O(n) artifact)
+
+- **by id** → the deterministic filename `docs/ai/adr/AD-NNN-*.md` (glob).
+- **by topic** → `grep` the flat `docs/ai/adr/` tree.
+- **by lifecycle** → the two-way `supersedes` / `supersededBy` frontmatter + the `[[AD-NNN]]` chain;
+  `ls docs/ai/adr/` IS the log.
+
+## Commands
+
+- `node scripts/archive-decisions.mjs` — rotate: explode the oldest HOT entries beyond the cap into
+  `adr/` records, then regenerate the navigator + `docs/ai/index.md`.
+- `node scripts/archive-decisions.mjs --write-navigator` — regenerate `docs/ai/adr/log.md` (and the
+  index) after authoring an ADR or editing a supersession, so `--check` stays green.
+- `node scripts/archive-decisions.mjs --check` — verify HOT cap + store integrity + navigator freshness.

package/references/templates/decisions.md

@@ -9,7 +9,11 @@ maxLines: 500
 
 # Architecture Decision Records (ADRs)
 
-> Every significant choice that has long-term consequences. Newest at the bottom. Link related ADRs with `[[AD-XXX]]`.
+> The **HOT window** of Architecture Decision Records — every significant choice with long-term
+> consequences, newest at the bottom. Link related ADRs with `[[AD-XXX]]`; retrieval is by the
+> `AD-NNN` id (filename), grep over the flat store, or the `[[AD-NNN]]` supersession chain.
+
+> **Archive:** older ADRs are stored one immutable file per record under [`adr/`](./adr/) — see the active-set navigator [`adr/log.md`](./adr/log.md). `archive-decisions.mjs` explodes the oldest entries beyond this window automatically; no cap is ever raised and there is no monolithic ledger.
 
 ## AD-001 — Adopt AI-agent memory system (`docs/ai/`)
 
@@ -18,27 +22,12 @@ maxLines: 500
 
 **Context.** Multi-session AI work loses context between runs. Without a structured handover, each new session re-reads code, re-discovers decisions, and repeats past mistakes.
 
-**Decision.** Adopt a Memory Map in `AGENTS.md` (entry point — the cross-agent standard; tool aliases like `CLAUDE.md` symlink to it) + structured files under `docs/ai/`. Define three protocols (Start / During / Complete). Enforce frontmatter caps + index freshness + 3-tier archive via a pre-commit hook. Deployed via the `agent-workflow-memory` substrate (standalone, or as part of the agent-workflow family).
+**Decision.** Adopt a Memory Map in `AGENTS.md` (entry point — the cross-agent standard; tool aliases like `CLAUDE.md` symlink to it) + structured files under `docs/ai/`. Define three protocols (Start / During / Complete). Enforce frontmatter caps + index freshness + a one-file-per-ADR archive via a pre-commit hook. Deployed via the `agent-workflow-memory` substrate (standalone, or as part of the agent-workflow family).
 
-**Rationale.** Single entry + structured spec files = constant boot-up cost regardless of project size. ADRs prevent litigating the same decision twice. `pages/<page>.md` keeps behaviour canonical (docs > assumptions). Caps + archive keep files scannable as history grows.
+**Rationale.** Single entry + structured spec files = constant boot-up cost regardless of project size. ADRs prevent litigating the same decision twice. `pages/<page>.md` keeps behaviour canonical (docs > assumptions). Caps + one-file-per-ADR archival keep every record scannable as the decision history grows without bound.
 
 **Consequences.**
 - ➕ Faster session start, less drift between agents.
 - ➕ ADRs as institutional memory; honest `known_issues.md`.
 - ➖ Discipline cost: docs updated alongside code.
 - ➖ A set of markdown files + scripts to maintain.
-
----
-
-## AD-002 — {{Next decision}}
-
-**Date:** {{DATE}}
-**Status:** Proposed / Accepted / Superseded
-
-**Context.** {{...}}
-**Decision.** {{...}}
-**Consequences.** {{...}}
-
----
-
-> When this file nears ~90% of its cap, move the oldest Accepted/Superseded ADRs to `decisions-archive.md` (keep the IDs + a one-line pointer here) and record the split. Bumping the cap instead of splitting is a conscious exception, justified in an ADR.

package/scripts/stamp-takeover.mjs

@@ -6,7 +6,7 @@
 // The deployment lineage is a SINGLE shared sequence; its current head is LINEAGE_HEAD.
 // Both `.memory-version` and the kit-fallback `.workflow-version` track THAT sequence —
 // never their package versions. So this substrate's package may be 1.0.0 while the stamp
-// it writes is the lineage head (1.3.0 today).
+// it writes is the lineage head (2.0.0 today).
 //
 // `decideTakeover` is a PURE function (stamp state in → action out) so the state machine is
 // unit-testable per row. `applyTakeover` is the thin fs wrapper; stamp writes are ATOMIC
@@ -22,7 +22,7 @@ import { pathToFileURL } from 'node:url';
 
 // The shared agent-workflow deployment-lineage head. Bumped only when a project-migration
 // changes the deployed docs/ai structure — NOT on a packaging-only release.
-export const LINEAGE_HEAD = '1.3.0';
+export const LINEAGE_HEAD = '2.0.0';
 
 const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)$/;