@sabaiway/agent-workflow-memory 3.0.0 → 3.0.1

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to the memory substrate. Versions are this **package's** npm
 they are distinct from the **deployment-lineage** stamp written into a project's
 `docs/ai/.memory-version` (which tracks the shared `agent-workflow` lineage, head `3.0.0`).
 
+## 3.0.1 — bundled reference scripts refreshed (no behavior change)
+
+PATCH rider on the kit 3.1.0 release — the publish workflow's changed-but-unbumped tooth caught
+that two bundled reference scripts had moved since 3.0.0 without a version bump. No CLI surface,
+output, or exit-code change:
+
+- `references/scripts/check-docs-size.mjs` — reworked to an in-process CLI shape (pure argv
+  parser, injectable log, exported `runCli`) so suites drive it without a spawn; same flags, same
+  behavior; a colocated CLI test pins it.
+- `references/scripts/archive-decisions.mjs` — comment-only cleanup (reviewer-round identity
+  references removed as part of the family-wide neutral-review-ID sweep).
+
 ## 3.0.0 — strip-the-kit: the substrate follows the hardened computed core (AD-059)
 
 > ### ⚠ BREAKING — retired loop surfaces + Node >= 22

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-memory
 description: Deploy or upgrade a portable AI-agent memory substrate in any project — an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) and a structured `docs/ai/` context store with cap/archive/index enforcement. Use when the user wants to bootstrap `docs/ai/`, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-memory` / `/agent-workflow-memory upgrade`. Triggers on "set up the memory system", "deploy the AI memory here", "bootstrap docs/ai", "upgrade the memory substrate". This is the substrate only — the workflow methodology (plan→execute→review, queue, Cleanup) is owned elsewhere and injected into AGENTS.md by the family composition root.
 disable-model-invocation: true
 metadata:
-  version: '3.0.0'
+  version: '3.0.1'
 ---
 
 # agent-workflow-memory

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-memory",
   "kind": "memory-substrate",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "provides": ["context"],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Portable, cross-agent memory substrate for AI coding agents — an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement, deployable standalone or as part of the agent-workflow family. The memory layer of the agent-workflow family.",
   "keywords": [
     "ai-agents",

package/references/scripts/archive-decisions.mjs

@@ -649,7 +649,7 @@ const runMigrate = (root, flags, today, deps, log, logError) => {
   verifyConservation(oldItems, newItems);
   // Integrity over the FULL final store — existing records ∪ freshly-exploded — not just the new
   // writes: a pre-existing adr/ record whose id also stays RETAINED in HOT would otherwise leave the
-  // ADR in two places (codex R4). Same full-store pattern as runRotate.
+  // ADR in two places. Same full-store pattern as runRotate.
   const finalStoreById = new Map(existingStore.map((e) => [e.id, { id: e.id, idNum: e.idNum, fileName: e.fileName }]));
   for (const r of records) finalStoreById.set(r.id, { id: r.id, idNum: r.idNum, fileName: r.fileName });
   assertStoreIntegrity(retained, [...finalStoreById.values()]);
@@ -783,7 +783,7 @@ const runRotate = (root, flags, today, deps, log, logError) => {
   }
 
   const records = explode(toExplode, today);
-  // Crash-resume (fold-induced, codex R2): a record from a prior crashed rotate may already be on
+  // Crash-resume (fold-induced): a record from a prior crashed rotate may already be on
   // disk. A byte-identical one is done (deduped, not a duplicate-id error); a divergent-body one is
   // corrupt → FAIL. The FINAL store = existing ∪ freshly-exploded, deduped by id.
   const existingById = new Map(existingStore.map((e) => [e.id, e]));

package/references/scripts/archive-decisions.test.mjs

@@ -341,7 +341,7 @@ describe('1.3 --migrate --apply — records + snapshot + retire monoliths + HOT
     assert.equal(run(['--check', '--today=2026-07-09'], root).code, 0, 'the resumed tree passes --check');
   });
 
-  it('refuses when a pre-existing adr/ record duplicates an ADR that stays in HOT (never two places — codex R4)', () => {
+  it('refuses when a pre-existing adr/ record duplicates an ADR that stays in HOT (never two places — review-adr-archive-r04-major-01)', () => {
     const root = makeRoot();
     seedLegacy(root, { hot: ['005', '006'], warm: ['003'], cold: ['001'] });
     mkdirSync(join(root, ADR_DIR_REL), { recursive: true });
@@ -452,7 +452,7 @@ describe('1.4 --check', () => {
     assert.match(errText, /duplicate ADR id AD-002/);
   });
 
-  it('a decisions.md with NO maxLines cap fails loud (never operates against an unknown budget — codex R4)', () => {
+  it('a decisions.md with NO maxLines cap fails loud (never operates against an unknown budget — review-adr-archive-r04-major-02)', () => {
     const root = makeRoot();
     mkdirSync(join(root, 'docs', 'ai'), { recursive: true });
     const noCapFm = '---\ntype: reference\nlastUpdated: 2026-01-01\nscope: permanent\nstaleAfter: never\nowner: none\n---\n';
@@ -514,7 +514,7 @@ describe('1.4 --check', () => {
     assert.match(errText, /two records for AD-001/);
   });
 
-  it('a NESTED subdirectory in adr/ fails loud (the store is a flat directory — codex R2)', () => {
+  it('a NESTED subdirectory in adr/ fails loud (the store is a flat directory — review-adr-archive-r02-major-01)', () => {
     const root = makeRoot();
     seedMigrated(root, { hotIds: ['005'], storeIds: ['001'] });
     mkdirSync(join(root, ADR_DIR_REL, 'nested'), { recursive: true });
@@ -561,7 +561,7 @@ describe('1.4 default rotate — explode the oldest beyond cap + regenerate the
     assert.equal(regenCalls.length, 0, 'a no-op never regenerates the index');
   });
 
-  it('is crash-resumable: a byte-identical record from a crashed prior rotate is deduped, not a fatal duplicate (codex R2)', () => {
+  it('is crash-resumable: a byte-identical record from a crashed prior rotate is deduped, not a fatal duplicate (review-adr-archive-r02-major-02)', () => {
     const root = makeRoot();
     mkdirSync(join(root, ADR_DIR_REL), { recursive: true });
     const blocks = ['005', '006', '007', '008'].map((id) => adrBlock(id));
@@ -579,7 +579,7 @@ describe('1.4 default rotate — explode the oldest beyond cap + regenerate the
     assert.equal(run(['--check', '--today=2026-07-09'], root).code, 0);
   });
 
-  it('a no-op rotate still REFUSES a corrupt store (partition) — never a silent green no-op (codex R2)', () => {
+  it('a no-op rotate still REFUSES a corrupt store (partition) — never a silent green no-op (review-adr-archive-r02-major-03)', () => {
     const root = makeRoot();
     seedMigrated(root, { hotIds: ['005'], storeIds: ['001'] }); // under cap
     const rec = explode(parseDecisionsText(tierText(999, '# T', [adrBlock('010')]), 'x').entries, '2026-07-09')[0];

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

@@ -0,0 +1,41 @@
+// check-docs-size-cli.test.mjs — runCli branch pins the subprocess smokes cannot reach
+// in-process (Phase-5 coverage fill; the main spec file is parity-frozen, so these ride a
+// colocated file): the unknown-argument refusal and the written-empty-index guard.
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { runCli } from './check-docs-size.mjs';
+
+const cli = async (argv) => {
+  const { code, stdout, stderr } = await runCli(argv);
+  return { code, stdout, stderr };
+};
+
+describe('check-docs-size runCli — refusal branches', () => {
+  it('an unknown argument exits 2 naming it', async () => {
+    const { code, stderr } = await cli(['--bogus']);
+    assert.equal(code, 2);
+    assert.match(stderr, /Unknown argument: --bogus/);
+  });
+
+  it('--write-index landing on a sink path (index stat size 0) is the loud written-empty refusal', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'cds-cli-'));
+    try {
+      mkdirSync(join(root, 'docs', 'ai'), { recursive: true });
+      writeFileSync(
+        join(root, 'docs', 'ai', 'a.md'),
+        '---\ntype: state\nlastUpdated: 2026-07-18\nscope: session\nstaleAfter: never\nowner: none\nmaxLines: 10\n---\n\n# a\n',
+      );
+      // The index path is a symlink into /dev/null: the write lands, the stat reads size 0 —
+      // the guard must refuse loudly instead of reporting a written index.
+      symlinkSync('/dev/null', join(root, 'docs', 'ai', 'index.md'));
+      const { code, stderr } = await cli(['--write-index', `--root=${root}`]);
+      assert.equal(code, 2);
+      assert.match(stderr, /index\.md was written empty/);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

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

@@ -103,25 +103,19 @@ export const discoverMeta = async (root = ROOT) => {
   return { projectName, hierarchicalLinks, onDemandLinks };
 };
 
+// Pure argv parser (no I/O, no exit): `help` / `error` ride out as data for runCli to render.
 const parseArgs = (argv) => {
   const flags = { report: false, writeIndex: false, checkIndex: false, quiet: false };
   const opts = { today: null, root: null };
-  for (const arg of argv.slice(2)) {
+  for (const arg of argv) {
     if (arg === '--report') flags.report = true;
     else if (arg === '--write-index') flags.writeIndex = true;
     else if (arg === '--check-index') flags.checkIndex = true;
     else if (arg === '--quiet') flags.quiet = true;
     else if (arg.startsWith('--today=')) opts.today = arg.slice('--today='.length);
     else if (arg.startsWith('--root=')) opts.root = arg.slice('--root='.length);
-    else if (arg === '--help' || arg === '-h') {
-      console.log(
-        'Usage: check-docs-size.mjs [--report|--write-index|--check-index] [--today=YYYY-MM-DD] [--root=<dir>] [--quiet]',
-      );
-      process.exit(0);
-    } else {
-      console.error(`Unknown argument: ${arg}`);
-      process.exit(2);
-    }
+    else if (arg === '--help' || arg === '-h') return { flags, opts, help: true };
+    else return { flags, opts, error: `Unknown argument: ${arg}` };
   }
   return { flags, opts };
 };
@@ -218,7 +212,7 @@ const formatRow = (row) => {
   return { status, sizeCell, ...row };
 };
 
-const printReport = (rows, quiet) => {
+const printReport = (rows, quiet, log = console.log) => {
   const widths = {
     status: 2,
     path: Math.max(4, ...rows.map((r) => r.path.length)),
@@ -228,15 +222,15 @@ const printReport = (rows, quiet) => {
   };
   const printable = quiet ? rows.filter((r) => r.errors.length || r.warnings.length) : rows;
   if (printable.length > 0) {
-    console.log(
+    log(
       `${'S'.padEnd(widths.status)}  ${'PATH'.padEnd(widths.path)}  ${'SIZE/MAX'.padEnd(widths.size)}  ${'TYPE'.padEnd(widths.type)}  ${'UPDATED'.padEnd(widths.updated)}`,
     );
     for (const row of printable) {
-      console.log(
+      log(
         `${row.status.padEnd(widths.status)}  ${row.path.padEnd(widths.path)}  ${row.sizeCell.padEnd(widths.size)}  ${(row.frontmatter?.type ?? '').padEnd(widths.type)}  ${(row.frontmatter?.lastUpdated ?? '').padEnd(widths.updated)}`,
       );
-      for (const err of row.errors) console.log(`     - ERROR  ${err}`);
-      for (const warn of row.warnings) console.log(`     - WARN   ${warn}`);
+      for (const err of row.errors) log(`     - ERROR  ${err}`);
+      for (const warn of row.warnings) log(`     - WARN   ${warn}`);
     }
   }
 };
@@ -361,9 +355,29 @@ export const regenerateIndex = async (root, todayStr = null) => {
   return { indexPath, files: rows.length };
 };
 
-const main = async () => {
-  const { flags, opts } = parseArgs(process.argv);
-  const { root, docsDir, indexPath } = pathsFor(opts.root ? resolve(opts.root) : ROOT);
+// The return-code entry point (no process.argv / process.exit / console inside): argv[] →
+// { code, stdout, stderr }. The thin shell at the bottom is the only process-coupled code.
+export const runCli = async (argv, deps = {}) => {
+  const stdoutLines = [];
+  const stderrLines = [];
+  const log = (line) => stdoutLines.push(line);
+  const logError = (line) => stderrLines.push(line);
+  const result = (code) => ({
+    code,
+    stdout: stdoutLines.length > 0 ? `${stdoutLines.join('\n')}\n` : '',
+    stderr: stderrLines.length > 0 ? `${stderrLines.join('\n')}\n` : '',
+  });
+
+  const { flags, opts, help, error } = parseArgs(argv);
+  if (help) {
+    log('Usage: check-docs-size.mjs [--report|--write-index|--check-index] [--today=YYYY-MM-DD] [--root=<dir>] [--quiet]');
+    return result(0);
+  }
+  if (error) {
+    logError(error);
+    return result(2);
+  }
+  const { root, docsDir, indexPath } = pathsFor(opts.root ? resolve(opts.root) : (deps.root ?? ROOT));
   const today = computeToday(opts.today);
   const files = (await walkMarkdownFiles(docsDir)).sort();
   const inspected = await Promise.all(files.map((f) => inspectFile(f, today, root)));
@@ -373,11 +387,11 @@ const main = async () => {
 
   if (flags.writeIndex) {
     await writeIndex(rows, today, meta, indexPath);
-    console.log(`Wrote ${relative(root, indexPath)}`);
+    log(`Wrote ${relative(root, indexPath)}`);
     const after = await stat(indexPath);
     if (after.size === 0) {
-      console.error('index.md was written empty');
-      process.exit(2);
+      logError('index.md was written empty');
+      return result(2);
     }
   }
 
@@ -385,28 +399,31 @@ const main = async () => {
     const onDisk = existsSync(indexPath) ? await readFile(indexPath, 'utf8') : null;
     const { fresh } = checkIndexFreshness(rows, onDisk, meta);
     if (!fresh) {
-      console.error(
+      logError(
         `[check-docs-size] FAIL: ${relative(root, indexPath)} is stale (out of sync with source frontmatter). Regenerate the index (--write-index) and commit the regenerated file.`,
       );
-      process.exit(1);
+      return result(1);
     }
-    console.log(
+    log(
       `[check-docs-size] OK — ${relative(root, indexPath)} is in sync with source frontmatter.`,
     );
-    return;
+    return result(0);
   }
 
-  printReport(rows, flags.quiet);
+  printReport(rows, flags.quiet, log);
   const errorCount = rows.reduce((n, r) => n + r.errors.length, 0);
   const warnCount = rows.reduce((n, r) => n + r.warnings.length, 0);
-  console.log(
+  log(
     `\n${rows.length} files inspected  —  ${errorCount} error(s), ${warnCount} warning(s)`,
   );
 
-  if (errorCount > 0 && !flags.report) process.exit(1);
+  return result(errorCount > 0 && !flags.report ? 1 : 0);
 };
 
 const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
 if (isDirectRun) {
-  await main();
+  const { code, stdout, stderr } = await runCli(process.argv.slice(2));
+  if (stdout) process.stdout.write(stdout);
+  if (stderr) process.stderr.write(stderr);
+  process.exitCode = code;
 }