@sabaiway/agent-workflow-memory 4.6.1 → 5.0.0

package/CHANGELOG.md

@@ -4,6 +4,60 @@ 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`).
 
+## 5.0.0 — the scenario floor: a contract can no longer pin NOTHING (AD-117)
+
+The reader enforced a minimum on `## Out of scope` and none on `## Scenarios`. A `kind: spec`
+document could therefore carry an EMPTY scenario section and pass everything — the reader, both
+`spec-check` lanes, the gate row. Measured cost, from writing the layer's first real specs: three
+stub specs would have satisfied every mechanical check of that slice and delivered nothing.
+
+> ### ⚠ BREAKING — the reader refuses a document it used to accept
+>
+> `SPEC_SCHEMA.rules` gains ONE frozen rule, **`scenarios-empty`**, in table position between
+> `scenario-path` and `out-of-scope`: a `## Scenarios` section carrying no scenario line is now an
+> error. The rule list is a frozen ordered contract, so a consumer that deep-equals it sees a 34th
+> id, and a deployment's spec gate can turn red with no edit of its own. The remedy is one line per
+> scenario — `- S<N> <name> :: unbound` while no test pins it.
+
+- **`*(empty)*` is deliberately NOT an escape here.** Written under `## Scenarios` it still refuses,
+  as `scenario-line`, and a fixture now pins that. The asymmetry with `## Out of scope` (where the
+  marker IS the decision) is the point: an empty exclusion list is a claim, an empty scenario list is
+  an absence, and the grammar already carries the honest form for the absence.
+- **`unbound` accepts on every status** — `draft`, `live` and `retired` alike — so the floor costs a
+  spec nothing but the statement that a scenario exists.
+- Measured before shipping: no document in the fixture corpus, the live store or the shipped
+  templates carries an empty section, so the floor refuses nothing that already exists.
+- The other 33 rule ids, every existing refusal and the whole `structure` extraction stay
+  behaviour-identical. The new arm was red-proofed against the pre-change reader.
+
+
+## 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

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.1'
+  version: '5.0.0'
 ---
 
 # agent-workflow-memory
@@ -236,7 +236,7 @@ Fill strategy:
    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
-   checker still on a body a release shipped is refreshed by the composition root's own upgrade
+   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

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "4.6.1",
+  "version": "5.0.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

@@ -38,7 +38,7 @@ export const SPEC_SCHEMA = Object.freeze({
     'frontmatter', 'frontmatter-key', 'substrate-key', 'type', 'kind', 'maxlines', 'status', 'revision',
     'root-owns', 'slug', 'kind-path', 'root-uplink', 'title', 'section-missing', 'section-order',
     'section-forbidden', 'fence', 'children-link', 'children-duplicate', 'fan-out', 'scenario-line',
-    'scenario-number', 'scenario-marker', 'scenario-path', 'out-of-scope', 'module-line', 'module-empty',
+    'scenario-number', 'scenario-marker', 'scenario-path', 'scenarios-empty', 'out-of-scope', 'module-line', 'module-empty',
     'module-traversal', 'module-absolute', 'module-backslash', 'module-glob', 'module-mix', 'parts',
   ]),
 });
@@ -238,6 +238,10 @@ const checkScenarios = (parsed, slug, status, errors, warnings) => {
     }
     scenarios.push(scenario);
   }
+  if (scenarios.length === 0) {
+    errors.push({ rule: 'scenarios-empty', message: `at least one scenario line (\`${SPEC_SCHEMA.unboundMarker}\` while no test pins it)` });
+    return;
+  }
   const gap = scenarios.findIndex((scenario, i) => scenario.n !== i + 1);
   if (gap !== -1) errors.push({ rule: 'scenario-number', message: `scenario ${gap + 1} is numbered S${scenarios[gap].n} — N runs contiguously from 1` });
   for (const scenario of scenarios) {
@@ -310,13 +314,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 +387,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

@@ -131,6 +131,14 @@ describe('readSpecDocument — refuse, exactly one rule per defect', () => {
     refuses(specDoc({ scenarios: ['- S1 a :: /abs/login.test.mjs :: spec:login/S1'] }), 'login.md', 'scenario-path');
   });
 
+  it('scenarios-empty / no empty-marker escape', () => {
+    refuses(specDoc({ scenarios: [] }), 'login.md', 'scenarios-empty');
+    refuses(specDoc({ scenarios: ['*(empty)*'] }), 'login.md', 'scenario-line');
+    for (const status of SPEC_SCHEMA.statuses) {
+      expect(readSpecDocument(specDoc({ scenarios: ['- S1 x :: unbound'], fields: { status } }), 'login.md').errors).toEqual([]);
+    }
+  });
+
   it('out-of-scope / module-empty / module-* path refusals / module-mix / parts', () => {
     refuses(specDoc({ outOfScope: '' }), 'login.md', 'out-of-scope');
     refuses(specDoc({ outOfScope: 'nothing excluded' }), 'login.md', 'out-of-scope');
@@ -194,6 +202,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([