@sabaiway/agent-workflow-memory 8.1.5 → 8.2.1

package/CHANGELOG.md

@@ -4,6 +4,28 @@ 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.1 — the architecture template points to the layout rules instead of a fixed set of layers (AD-191)
+
+`references/templates/architecture.md`: the lead line drops "Layers", and the Layers and Module Boundaries sections
+give way to one section, **Layout rules**: modules nest by meaning, and in a kit deployment the rules live in
+`docs/ai/rules/effective/project-layout.md`. The File Tree and the rest of the template are unchanged; a deployed
+`docs/ai/architecture.md` is never rewritten. PATCH: template text only.
+
+## 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

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.5'
+  version: '8.2.1'
 ---
 
 # 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.5",
+  "version": "8.2.1",
   "provides": ["context"],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "8.1.5",
+  "version": "8.2.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/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/templates/architecture.md

@@ -9,28 +9,13 @@ maxLines: 350
 
 # Architecture
 
-> How the code is organized. Layers, boundaries, where new code goes.
+> How the code is organized: where each module lives and where new code goes.
 
-## Layers
+## Layout rules
 
-```
-UI Components       ← {{src/components/}}
-    ↓
-Hooks / Composition ← {{src/hooks/}}
-    ↓
-Services (pure)     ← {{src/services/}}
-    ↓
-State / Storage     ← {{src/store/ or src/data/}}
-    ↓
-Types / Schemas     ← {{src/types/}}
-```
-
-## Module Boundaries
-
-- **Components** — render only. No fetching, no business logic.
-- **Hooks** — orchestration; combine services + state.
-- **Services** — pure functions. Easy to test.
-- **State** — single source of truth per domain.
+The code is laid out by the project-layout rules: modules nest by meaning, and a name says where
+code, tests and specs live. In a kit deployment those rules live in
+`docs/ai/rules/effective/project-layout.md`, laid down by the kit's upgrade.
 
 ## File Tree (top level)