@sabaiway/agent-workflow-memory 4.6.0 → 4.7.0

package/CHANGELOG.md

@@ -4,6 +4,52 @@ 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`).
 
+## 4.7.0 — the reader's verdict gains the additive `structure` extraction (AD-114)
+
+The slice-2 checker (`spec-check`, next release) must read a document's structure through the SAME
+module that defines "malformed" — a second parser of the frozen grammar would fork that definition.
+`readSpecDocument` therefore now returns, beside the untouched errors and warnings, an additive
+`structure` field in a shape frozen at plan time:
+
+- **`{scenarios: [{ordinal, binding: {file, marker} | null}], children: [{name, target}], parts:
+  [{name, target}], module: {form: 'root' | 'fileSet', paths: [...]} | null}`** — every target
+  VERBATIM as written (`./x.md` and `./x/index.md` stay distinct strings).
+- **Null ONLY on the early refusals** (missing frontmatter, a frontmatter-key defect, an unknown
+  kind); for a known kind with errors it is the DETERMINISTIC extraction of what parsed: a
+  grammar-malformed scenario/child/part line is simply absent (valid lines before and after it
+  extract), while a line that parses but breaks a rule still extracts verbatim beside its error.
+- **The module is a conjunction** — ONE `dir/` root or an all-file list; prose, a refused path, a
+  dir/file mix or `*(empty)*` extracts `module: null`. `## Links` stays free prose, never
+  extracted.
+- The 33 rule ids, every refusal and every existing verdict field stay behaviour-identical (the
+  engine corpus suite is green untouched; engine stays 3.3.0). The deep-equal suite pins the shape
+  per kind, both module forms, every early-refusal branch and the partial extractions; the new
+  tests were red-proofed against the pre-change reader.
+
+MINOR: a shipped script gains a capability. One prose alignment rides along: the upgrade's
+refresh-lane sentence now names a file of EITHER deployed pair (reader or checker) on a shipped
+body as refreshed by the composition root's upgrade — this substrate still carries no catalog and
+never overwrites a deployed script itself.
+
+## 4.6.1 — the standalone upgrade delivers the spec layer behind a checker it can prove (AD-113)
+
+4.6.0 shipped the feature-spec layer for FRESH bootstraps; an EXISTING deployment at lineage head
+`3.0.0` had no lane to it. The standalone (skill-only) upgrade now closes that gap in prose, with no
+digest catalog and no change to the shipped payload:
+
+- **SKILL.md upgrade step 2 gains the spec-layer twin.** The reader pair (`scripts/spec-schema.mjs`
+  + its test) seeds create-only if missing. The store root `docs/ai/specs/index.md` seeds ONLY when
+  BOTH deployed pairs — reader and checker — are regular files byte-equal to the bundled copies
+  (checked via lstat; a dangling symlink anywhere means nothing is written), with the template's
+  date placeholder rendered. Every other state — a custom or partial pair, reader or checker — is
+  reported as is, with the composition root's upgrade named as the refresh lane and NO store root
+  written.
+- **`standalone-bootstrap.test.mjs` models the equal-head upgrade both ways:** both pairs
+  bundle-equal -> store seeded and the installed pre-commit hook exits 0 over a seeded spec; a
+  custom or partial pair -> reported, no store.
+
+PATCH: prose + the E2E model only.
+
 ## 4.6.0 — the feature-spec layer: a store under `docs/ai/specs/`, one text-only reader, a counted navigator row (AD-112)
 
 A deployed project gains a middle altitude of durable knowledge between the whole-project

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: '4.6.0'
+  version: '4.7.0'
 ---
 
 # agent-workflow-memory
@@ -225,6 +225,20 @@ Fill strategy:
    hook gains its `archive-decisions.mjs --check` line only when the hook is next refreshed via
    `node scripts/install-git-hooks.mjs`; an old hook without the line stays consistent-safe (the
    decisions gate is simply not enforced yet — never a broken hook). **Same gate, also
+   stamp-independent — ensure the SPEC LAYER (Node projects; skip on a No-Node project like the
+   pair above):** copy `spec-schema.mjs` + `spec-schema.test.mjs` from
+   `${CLAUDE_SKILL_DIR}/references/scripts/` into the project's `scripts/` **if missing** (preserve
+   an existing file byte-for-byte). Then seed `docs/ai/specs/index.md` **if missing** from
+   `${CLAUDE_SKILL_DIR}/references/templates/specs/` (date filled; an existing root is preserved
+   byte-for-byte) **ONLY if BOTH pairs** — that reader pair AND `check-docs-size.mjs` +
+   `check-docs-size.test.mjs` — are regular files (probe with `ls -l`, never a follow-the-link
+   test: a symlink, dangling or not, or a directory at any of the five paths means NOTHING is
+   written) **byte-equal** to this skill's bundled copies (compare with `cmp`): the deployed checker
+   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
+   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
    `node ${CLAUDE_SKILL_DIR}/references/scripts/check-docs-size.mjs --ensure-index --root=<target>`

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "4.6.0",
+  "version": "4.7.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/spec-schema.mjs

@@ -310,13 +310,45 @@ const checkParts = (parsed, at, errors) => {
   if (duplicate !== undefined) errors.push({ rule: 'parts', message: `part "${duplicate}" is listed twice` });
 };
 
-// The verdict: { kind, status, revision, errors: [{ rule, message }], warnings: [{ rule, message }] }.
-// Errors are collected past the first defect wherever later checks stay meaningful; a missing or
-// defective frontmatter and an unknown kind each end the read, because no shape can be judged without them.
+// The structure verdict (additive, slice 2a): the DETERMINISTIC extraction of what parsed, per
+// section, targets VERBATIM as written (`./x.md` and `./x/index.md` stay distinct strings). The
+// grammar is per line for scenarios/children/parts — a malformed line is simply absent — while the
+// module is a conjunction (ONE `dir/` root or an all-file list): prose, a refused path, a mix or
+// `*(empty)*` extracts null. `## Links` is free prose and is never extracted.
+const scenarioEntry = (line) => {
+  const scenario = parseScenario(line);
+  if (scenario === null) return null;
+  return { ordinal: scenario.n, binding: scenario.bound ? { file: scenario.path, marker: scenario.marker } : null };
+};
+const linkEntry = (re) => (line) => {
+  const m = line.match(re);
+  return m && SLUG_RE.test(m[2]) ? { name: m[1], target: `./${m[2]}${m[3] ?? ''}.md` } : null;
+};
+const entriesOf = (parsed, heading, entryOf) =>
+  contentOf(sectionLines(parsed, heading) ?? []).map(entryOf).filter((entry) => entry !== null);
+const extractModule = (parsed) => {
+  const content = contentOf(sectionLines(parsed, '## Module') ?? []);
+  const paths = bulletsOf(content);
+  if (paths.length === 0 || content.some((line) => !isBullet(line))) return null;
+  const kinds = paths.map(classifyPath);
+  if (paths.length === 1 && kinds[0] === 'dir') return { form: 'root', paths };
+  return kinds.every((kind) => kind === 'file') ? { form: 'fileSet', paths } : null;
+};
+const extractStructure = (parsed) => ({
+  scenarios: entriesOf(parsed, '## Scenarios', scenarioEntry),
+  children: entriesOf(parsed, '## Children', linkEntry(CHILD_LINK_RE)),
+  parts: entriesOf(parsed, '## Parts', linkEntry(PART_LINK_RE)),
+  module: extractModule(parsed),
+});
+
+// The verdict: { kind, status, revision, structure, errors: [{ rule, message }], warnings: [{ rule,
+// message }] }. Errors are collected past the first defect wherever later checks stay meaningful; a
+// missing or defective frontmatter and an unknown kind each end the read (structure stays null),
+// because no shape can be judged without them.
 export const readSpecDocument = (text, rel) => {
   const errors = [];
   const warnings = [];
-  const verdict = (kind, status, revision) => ({ kind, status, revision, errors, warnings });
+  const verdict = (kind, status, revision, structure = null) => ({ kind, status, revision, structure, errors, warnings });
   const front = parseFrontmatter(text.replace(/\r\n/g, '\n'));
   if (front === null) {
     errors.push({ rule: 'frontmatter', message: 'missing YAML frontmatter' });
@@ -351,5 +383,5 @@ export const readSpecDocument = (text, rel) => {
   }
   const status = kind === 'spec' ? fields.status ?? null : null;
   const revision = kind === 'spec' && REVISION_RE.test(fields.revision ?? '') ? Number(fields.revision) : null;
-  return verdict(kind, status, revision);
+  return verdict(kind, status, revision, extractStructure(parsed));
 };

package/references/scripts/spec-schema.test.mjs

@@ -194,6 +194,73 @@ describe('readSpecDocument — refuse, exactly one rule per defect', () => {
   });
 });
 
+describe('readSpecDocument — the structure verdict (additive, slice 2a)', () => {
+  const structureOf = (text, rel) => readSpecDocument(text, rel).structure;
+  const BOTH_SCENARIOS = [
+    { ordinal: 1, binding: { file: 'test/login.test.mjs', marker: 'spec:login/S1' } },
+    { ordinal: 2, binding: null },
+  ];
+
+  it('a flat spec extracts scenarios (bound + unbound) and its one dir/ module root', () => {
+    expect(structureOf(specDoc(), 'login.md')).toEqual({
+      scenarios: BOTH_SCENARIOS,
+      children: [],
+      parts: [],
+      module: { form: 'root', paths: ['src/login/'] },
+    });
+  });
+
+  it('a promoted root extracts parts and a fileSet module; ## Links stays free prose, never extracted', () => {
+    const text = specDoc({ module: '- src/a.mjs\n- src/b.mjs', extra: '\n## Parts\n\n- [sessions](./sessions.md)\n\n## Links\n\n- [[AD-112]]\n' });
+    expect(structureOf(text, 'auth/login/index.md')).toEqual({
+      scenarios: BOTH_SCENARIOS,
+      children: [],
+      parts: [{ name: 'sessions', target: './sessions.md' }],
+      module: { form: 'fileSet', paths: ['src/a.mjs', 'src/b.mjs'] },
+    });
+  });
+
+  it('an index extracts children with VERBATIM targets — ./x.md and ./x/index.md stay distinct strings', () => {
+    expect(structureOf(indexDoc(), 'auth/index.md')).toEqual({
+      scenarios: [],
+      children: [{ name: 'login', target: './login.md' }, { name: 'billing', target: './billing/index.md' }],
+      parts: [],
+      module: null,
+    });
+  });
+
+  it('a part extracts the empty structure; a retired *(empty)* module extracts null on a CLEAN document', () => {
+    expect(structureOf(partDoc(), 'auth/login/sessions.md')).toEqual({ scenarios: [], children: [], parts: [], module: null });
+    const retired = specDoc({ fields: { status: 'retired' }, module: '*(empty)*', scenarios: ['- S1 gone :: unbound'] });
+    expect(structureOf(retired, 'login.md').module).toBeNull();
+  });
+
+  it('EVERY early refusal reads structure null: missing frontmatter, a frontmatter defect, an unknown or absent kind', () => {
+    expect(structureOf('# Spec: Login\n', 'login.md')).toBeNull();
+    expect(structureOf(specDoc({ fields: { priority: 'high' } }), 'login.md')).toBeNull();
+    expect(structureOf(specDoc({ fields: { kind: 'feature' } }), 'login.md')).toBeNull();
+    expect(structureOf(specDoc({ drop: ['kind'] }), 'login.md')).toBeNull();
+  });
+
+  it('a grammar-malformed scenario/child/part line is simply ABSENT — valid lines before and after it extract', () => {
+    const s = structureOf(specDoc({ scenarios: ['- S1 a :: unbound', '- S2 broken', '- S3 c :: unbound'] }), 'login.md');
+    expect(s.scenarios).toEqual([{ ordinal: 1, binding: null }, { ordinal: 3, binding: null }]);
+    const c = structureOf(indexDoc({ children: ['- [a](./a.md)', '- broken', '- [b](./b/index.md)'] }), 'auth/index.md');
+    expect(c.children).toEqual([{ name: 'a', target: './a.md' }, { name: 'b', target: './b/index.md' }]);
+    const p = structureOf(specDoc({ extra: '\n## Parts\n\n- [a](./a.md)\n- broken\n- [b](./b.md)\n' }), 'auth/login/index.md');
+    expect(p.parts).toEqual([{ name: 'a', target: './a.md' }, { name: 'b', target: './b.md' }]);
+  });
+
+  it('the module is a CONJUNCTION — prose, a refused path, a dir/file mix each extract null; a rule-refused scenario line still extracts verbatim', () => {
+    for (const module of ['the root is\n- src/login/', '- ../src/', '- src/login/\n- src/login/a.mjs']) {
+      expect(structureOf(specDoc({ module }), 'login.md').module).toBeNull();
+    }
+    const v = readSpecDocument(specDoc({ scenarios: ['- S1 a :: test/a.mjs :: spec:login/S2'] }), 'login.md');
+    expect(v.errors.map((e) => e.rule)).toEqual(['scenario-marker']);
+    expect(v.structure.scenarios).toEqual([{ ordinal: 1, binding: { file: 'test/a.mjs', marker: 'spec:login/S2' } }]);
+  });
+});
+
 describe('classifyPath + the frozen constants', () => {
   it('classifies the lexical path forms', () => {
     expect(['src/', 'src/a.mjs', '../x', '/x', 'C:/x', 'a\\b', 'src/*.mjs'].map(classifyPath)).toEqual([