@sabaiway/agent-workflow-memory 8.1.4 → 8.2.0

package/CHANGELOG.md

@@ -4,6 +4,29 @@ 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 `4.0.0`).
 
+## 8.2.0 — the docs navigator stamps a cap it honours past 80 lines (AD-182)
+
+**`references/scripts/check-docs-size.mjs` now writes a `docs/ai/index.md` that its own default run and `--check-index`
+accept, however many docs the project has.** Before, the navigator always stamped `maxLines: 80` while it renders one
+row per document outside the collapsed ADR and spec stores, so a project with enough docs (measured: 67 docs, an 87-line navigator) got a navigator its own
+pre-commit hook refused.
+
+- The stamp is `maxLines: 80` while the rendered navigator has 80 lines or fewer, and its own line count past that,
+  counted as the gate counts (a trailing newline closes the last line and opens none). A navigator that fits is
+  byte-identical to before. There is no ceiling, as for the ADR navigator (AD-167).
+- A hand-edited cap line still reads as stale under `--check-index`, as before.
+- `SKILL.md`: a deployed spec-layer script with an edited body is named by the composition root's upgrade and replaced
+  only on the user's yes; this substrate still never overwrites a deployed script.
+- MINOR: the navigator's stamped cap changes past 80 lines. The deployed `check-docs-size.test.mjs` body is unchanged.
+
+## 8.1.5 — the gate migration names the `lcovProducer` marker (AD-175)
+
+`references/scripts/migrate-gates.mjs`: the four hints that print the paste-ready suite cmd (the
+customized `unit-tests` recovery, the INERT row of a vendored checker, and the withheld-checker and inert-checker
+warnings) also name the other producer form: `add "lcovProducer": true to that gate in docs/ai/gates.json`, for a suite cmd
+that already writes the lcov in a form the migration cannot recognise. The guarded `coverage-producer canon` and
+`checker-claim canon` regions are unchanged and stay byte-identical to the kit's. PATCH: no migration result changes.
+
 ## 8.1.4 — the templates carry the four-session story flow (AD-170)
 
 `references/templates/agent_rules.md`: §2.6 is the engine 5.12.0 lens render (the Finding scope, Spec-first, Fold

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: '8.1.4'
+  version: '8.2.0'
 ---
 
 # agent-workflow-memory
@@ -251,7 +251,8 @@ Fill strategy:
    is what the pre-commit hook runs, and an older or edited one renders the store row by row and
    reds its own index check. Otherwise seed NO store root and report which file differs: a
    file of either pair still on a body a release shipped is refreshed by the composition root's own upgrade
-   (it carries the catalog of shipped bodies), an edited one is the user's to refresh by hand — this
+   (it carries the catalog of shipped bodies), and an edited one is named by that upgrade and replaced
+   only on the user's yes — this
    substrate carries no such catalog and never overwrites a deployed script. **Same gate, also
    stamp-independent — ensure the NAVIGATOR:** `docs/ai/index.md` is a GENERATED artifact the entry
    point declares always-loaded, so a deployment that never had one must gain it even at head — run

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "8.1.4",
+  "version": "8.2.0",
   "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/check-docs-size-cli.test.mjs

@@ -58,6 +58,51 @@ maxLines: 80
 | [\`a.md\`](./a.md) | state | 10/10 | 2026-07-18 | never |
 `;
 
+describe('spec:docs-navigator/S1 the navigator stamps a cap it honours', () => {
+  const createNames = (count) => Array.from({ length: count }, (_, index) => `n${String(index + 1).padStart(2, '0')}`);
+  const buildDocs = (names) => ({ docs }) => {
+    for (const name of names) writeFileSync(join(docs, `${name}.md`), DOC(name));
+  };
+  const countLines = (text) => text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+
+  it("a tree whose navigator renders exactly 80 lines stamps maxLines 80, byte-identical to today's render", async () => {
+    const names = createNames(57);
+    await withRoot(buildDocs(names), async ({ root }) => {
+      assert.equal((await cli(['--write-index', `--root=${root}`, '--today=2026-07-18'])).code, 0);
+      const index = indexOf(root);
+      const rows = names.map((name) => `| [\`${name}.md\`](./${name}.md) | state | 10/10 | 2026-07-18 | never |\n`);
+      assert.equal(countLines(index), 80);
+      assert.equal(index, EXPECTED_INDEX + rows.join(''));
+    });
+  });
+
+  it('a tree of 81 lines stamps maxLines 81 and both checker runs exit 0', async () => {
+    await withRoot(buildDocs(createNames(58)), async ({ root }) => {
+      assert.equal((await cli(['--write-index', `--root=${root}`, '--today=2026-07-18'])).code, 0);
+      const index = indexOf(root);
+      const checked = await runCli([`--root=${root}`]);
+      const fresh = await runCli(['--check-index', `--root=${root}`]);
+      assert.equal(countLines(index), 81);
+      assert.equal(index.match(/^maxLines: \d+$/m)?.[0], 'maxLines: 81', `default: ${checked.code}, --check-index: ${fresh.code}`);
+      assert.equal(checked.code, 0, checked.stdout + checked.stderr);
+      assert.equal(fresh.code, 0, fresh.stdout + fresh.stderr);
+    });
+  });
+
+  it('a hand-edited cap line is stale under --check-index', async () => {
+    await withRoot(buildDocs(createNames(58)), async ({ root, docs }) => {
+      assert.equal((await cli(['--write-index', `--root=${root}`, '--today=2026-07-18'])).code, 0);
+      const index = indexOf(root);
+      const edited = index.replace(/^maxLines: \d+$/m, 'maxLines: 90');
+      assert.notEqual(edited, index);
+      writeFileSync(join(docs, 'index.md'), edited);
+      const { code, stdout, stderr } = await runCli(['--check-index', `--root=${root}`]);
+      assert.equal(code, 1);
+      assert.match(stdout + stderr, /is stale/);
+    });
+  });
+});
+
 describe('check-docs-size runCli — refusal branches', () => {
   it('an unknown argument exits 2 naming it', async () => {
     const { code, stderr } = await cli(['--bogus']);

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

@@ -11,6 +11,9 @@ import { runCli } from './check-docs-size.mjs';
 const DOC = (title) =>
   `---\ntype: state\nlastUpdated: 2026-08-15\nscope: session\nstaleAfter: never\nowner: none\nmaxLines: 10\n---\n\n# ${title}\n`;
 
+const NAVIGATOR_LINE_FLOOR = 80;
+const EXTRA_DOC_COUNT = 85;
+
 const makeTree = (prefix) => {
   const dir = mkdtempSync(join(tmpdir(), prefix));
   mkdirSync(join(dir, 'docs', 'ai'), { recursive: true });
@@ -330,3 +333,28 @@ describe('check-docs-size --ensure-index', () => {
     }
   });
 });
+
+describe('spec:docs-navigator/S2 --ensure-index past the 80-line floor', () => {
+  it('writes a navigator past 80 lines that the default run and --check-index accept', async () => {
+    const root = makeTree('cds-ensure-past-floor-');
+    try {
+      for (const number of Array.from({ length: EXTRA_DOC_COUNT }, (_, index) => index)) {
+        writeFileSync(join(root, 'docs', 'ai', `z-extra-${number}.md`), DOC(`extra ${number}`));
+      }
+      const { code, stdout } = await runCli(['--ensure-index', `--root=${root}`]);
+      assert.equal(code, 0);
+      assert.match(stdout, /ensure-index: regenerated/);
+      const navigator = readFileSync(join(root, 'docs', 'ai', 'index.md'), 'utf8');
+      const lineCount = navigator.split('\n').length - (navigator.endsWith('\n') ? 1 : 0);
+      const maxLines = Number(navigator.match(/^maxLines: (\d+)$/m)?.[1]);
+      assert.ok(lineCount > NAVIGATOR_LINE_FLOOR);
+      const defaultRun = await runCli([`--root=${root}`]);
+      const indexCheck = await runCli(['--check-index', `--root=${root}`]);
+      assert.equal(defaultRun.code, 0, defaultRun.stdout);
+      assert.equal(maxLines, lineCount);
+      assert.equal(indexCheck.code, 0, indexCheck.stdout);
+    } finally {
+      drop(root);
+    }
+  });
+});

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

@@ -45,6 +45,8 @@ const pathsFor = (root) => {
 };
 
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
+const NAVIGATOR_CAP_FLOOR = 80;
+const countLines = (text) => text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
 
 // The one token every `--ensure-index` outcome line opens with — deploy/upgrade prose relays it
 // verbatim and the kit's ensure op reads it, so it is a contract, not a message.
@@ -263,7 +265,7 @@ export const inspectFile = async (found, today, root = ROOT) => {
     return { path: rel, lineCount: 0, frontmatter: null, spec: null, refused: true, errors: [refusal], warnings: [] };
   }
   const text = await readFile(filePath, 'utf8');
-  const lineCount = text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+  const lineCount = countLines(text);
   const fm = parseFrontmatter(text);
   const spec = readSpecVerdict(rel, text);
 
@@ -332,7 +334,7 @@ lastUpdated: __TODAY__
 scope: permanent
 staleAfter: 30d
 owner: none
-maxLines: 80
+maxLines: __CAP__
 ---
 
 # Memory Map — __PROJECT__ \`docs/ai/\`
@@ -398,7 +400,6 @@ export const buildIndex = (rows, todayStr, meta = {}) => {
   const projectName = meta.projectName ?? DEFAULT_PROJECT_NAME;
   const onDemandLinks = meta.onDemandLinks ?? [];
   const hierarchicalLinks = meta.hierarchicalLinks ?? [];
-  const header = INDEX_HEADER.replace('__TODAY__', todayStr).replace('__PROJECT__', projectName);
   const tableHeader = `| File | Type | Lines/Max | Updated | Stale after |\n|------|------|-----------|---------|-------------|`;
   const singles = [];
   const grouped = COLLAPSE_GROUPS.map(() => []);
@@ -421,7 +422,8 @@ export const buildIndex = (rows, todayStr, meta = {}) => {
     hierarchicalLinks.length > 0
       ? `\n\n## Subdirectory \`AGENTS.md\` (hierarchical)\n\n${hierarchicalLinks.map((link) => `- ${link}`).join('\n')}`
       : '';
-  return `${header}${tableHeader}\n${tableRows}${onDemandSection}${hierarchicalSection}\n`;
+  const render = (cap) => `${INDEX_HEADER.replace('__CAP__', cap).replace('__TODAY__', todayStr).replace('__PROJECT__', projectName)}${tableHeader}\n${tableRows}${onDemandSection}${hierarchicalSection}\n`;
+  return render(Math.max(NAVIGATOR_CAP_FLOOR, countLines(render(NAVIGATOR_CAP_FLOOR))));
 };
 
 // Freshness regenerates the index with the on-disk header's OWN `lastUpdated`, so a mere day-rollover

package/references/scripts/migrate-gates.mjs

@@ -461,12 +461,14 @@ export const resultingGates = (plan) => {
   return [...kept, ...moved, ...added]; // move/add go LAST — the checker ends up the last declared gate
 };
 
+const MARKER_LANE = 'or, if your suite cmd already writes that lcov in a form this check cannot recognise, add "lcovProducer": true to that gate in docs/ai/gates.json';
+
 // The per-entry customized recovery: a unit-tests-class entry gets the FULL canonical flag set
 // (the intent is known — the cmd shape just cannot be verified); anything else gets the
 // dead-tool recovery.
 const customizedRecovery = (gate) =>
   gate.id === 'unit-tests'
-    ? `declare the canonical suite gate by hand so the coverage contract is verifiable: node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths>`
+    ? `declare the canonical suite gate by hand so the coverage contract is verifiable: node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths> — ${MARKER_LANE}`
     : 'remove the entry, or repoint it at a living check — the review-ledger / fold-completeness tools no longer exist.';
 
 const warningLines = ({ customized, finalCapable, hasReviewState = finalCapable, hasProducer = false, checkerWithheld = false, canonicalCheckerInert = false, duplicateCheckers = 0, externalCoreChecks = [], reviewStateCandidate }) => {
@@ -495,7 +497,7 @@ const warningLines = ({ customized, finalCapable, hasReviewState = finalCapable,
     } else if (inert && hasProducer) {
       lines.push('    it is also INERT as declared: a gate DOES produce the lcov, but it runs AFTER this entry, so this checker reads nothing (or stale bytes) and passes while verifying nothing — a checker belongs LAST, after its producer.');
     } else if (inert) {
-      lines.push(`    it is also INERT as declared: no declared gate PRODUCES the lcov it reads, so it passes while verifying nothing — declare the suite gate: node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths>`);
+      lines.push(`    it is also INERT as declared: no declared gate PRODUCES the lcov it reads, so it passes while verifying nothing — declare the suite gate: node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths> — ${MARKER_LANE}`);
     }
   }
   if (externalCoreChecks.length) {
@@ -506,12 +508,14 @@ const warningLines = ({ customized, finalCapable, hasReviewState = finalCapable,
   if (checkerWithheld) {
     lines.push('  WARNING: the canonical coverage-check gate was NOT added — no declared gate would PRODUCE the lcov it reads, and a checker with no producer passes while verifying nothing. Declare the suite gate first, then re-run this migration:');
     lines.push(`    node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths>`);
+    lines.push(`    ${MARKER_LANE}, then re-run this migration`);
   }
   // The CANONICAL checker's inertness only. An external row's is said on the row itself above, with
   // the edit that fits that row — this block would otherwise add a second, contradictory one.
   if (canonicalCheckerInert) {
     lines.push('  WARNING: the DECLARED coverage-check gate is INERT — no declared gate PRODUCES the lcov it reads, so it passes while verifying nothing. Nothing is removed for you; declare the suite gate:');
     lines.push(`    node --test ${UNIT_TESTS_COVERAGE_FLAGS} <your test paths>`);
+    lines.push(`    ${MARKER_LANE}`);
   }
   if (duplicateCheckers > 1) {
     lines.push(`  WARNING: ${duplicateCheckers} declared gates are the canonical coverage checker — run-gates --final accepts EXACTLY ONE, so the result is NOT final-run-capable. Nothing is removed for you; keep a single checker and delete the rest by hand.`);

package/references/scripts/migrate-gates.test.mjs

@@ -122,6 +122,7 @@ describe('migrate-gates — the pure migration plan', () => {
     const preview = formatPreview(analysis, 'APPLY');
     assert.match(preview, /CUSTOMIZED \(untouched\): unit-tests/);
     assert.match(preview, /declare the canonical suite gate by hand/, 'the paste-ready recovery rides along');
+    assert.match(preview, /recovery \(apply by hand[^\n]*"lcovProducer": true/, 'the recovery names the marker as the other lane');
   });
 
   it('adds the coverage-check gate LAST with the RESOLVED quoted path; never a second one', () => {
@@ -143,6 +144,7 @@ describe('migrate-gates — the pure migration plan', () => {
     const preview = formatPreview(analysis, 'APPLY');
     assert.match(preview, /coverage-check/, 'the withheld checker is named');
     assert.match(preview, /produce/i, 'the preview says WHY — no gate produces the lcov it would read');
+    assert.match(preview, /WARNING: the canonical coverage-check gate was NOT added[^\n]*\n[^\n]*\n[^\n]*"lcovProducer": true/, 'the withheld block names the marker as the other lane');
   });
 
   it('an ALREADY-declared checker over no producer is reported INERT, is never removed, and is not final-run-capable', () => {
@@ -154,6 +156,7 @@ describe('migrate-gates — the pure migration plan', () => {
     const preview = formatPreview(analysis, 'APPLY');
     assert.match(preview, /INERT/, 'the inert pair is named');
     assert.match(preview, /--experimental-test-coverage/, 'the paste-ready suite cmd is carried');
+    assert.match(preview, /WARNING: the DECLARED coverage-check gate is INERT[^\n]*\n[^\n]*\n[^\n]*"lcovProducer": true/, 'the inert block names the marker as the other lane');
     assert.doesNotMatch(preview, /already final-run-capable/);
   });
 
@@ -352,6 +355,7 @@ describe('migrate-gates — a VENDORED core check is the tool, from a copy --kit
     const absent = formatPreview(buildMigrationPlan([INSTALLED_REVIEW_STATE, vendored], KIT_TOOLS, PROJECT), 'APPLY');
     assert.match(absent, /no declared gate PRODUCES the lcov/, 'with nothing producing, the old sentence still holds');
     assert.match(absent, /declare the suite gate/);
+    assert.match(absent, /no declared gate PRODUCES the lcov[^\n]*"lcovProducer": true/, 'the INERT row names the marker as the other lane');
   });
 
   it('a mixed declaration renders ONE edit, never a removal and a reorder at once', () => {