@sabaiway/agent-workflow-memory 7.2.1 → 8.0.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ 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`).
 
+## 8.0.0 — the reader refuses an open-list clause: a guarantee is an invariant, never a list of cases (AD-133)
+
+**BREAKING — the 35th rule id, `open-list`.** `references/scripts/spec-schema.mjs` refuses a Contract clause that
+carries a check verb (`refuse` / `refusal`, case-sensitive substrings) AND an enumeration of two or more items
+(`a, b or c` / `a · b`) AND no closure token inside that same clause. The unit is the CLAUSE: a top-level bullet joined
+with its continuation lines (a blank line, the next top-level bullet — an empty `-` included — or any ATX heading,
+indented up to three spaces, ends it), split at `. ` and `; ` outside a backtick span — the span is opaque to the split
+and to nothing else. Every `## Contract` section of a `kind: spec`, every top-level bullet of a `kind: part`; never an
+index or prose outside bullets. Twelve closure tokens (`only if`, `only when`, `the only`, `everything else`,
+`anything else`, `nothing else`, `every other`, `any other`, `otherwise`, `exactly`, `one of`, `closed`) match
+case-insensitively at word boundaries; `ONLY` is the one case-sensitive emphatic word (a lowercase `only` alone closes
+nothing; `READ-ONLY` and `closed-key` glue). A single-case check is its own closure; a closure that is FALSE is out of
+scope — a form rule. The remedy for a spec valid under the old canon that now refuses: state the invariant in the
+clause ("accepted only if …; everything else is the named refusal …"), never a fourth case; the refusal names the
+clause's first six words. `SPEC_SCHEMA.openList` carries the frozen fragment (every list frozen); `rules` gains
+`open-list` after `fence`. The comment blocks became one-line pointers naming no sibling package; the module is 415
+lines, recorded. The test twin gains the "open-list clauses" describe (clause and bullet boundaries, the span mask, the
+matching rules, every Contract section, part scope, frozenness). Mirrored byte-identically into the kit and the root
+`scripts/`.
+
 ## 7.2.1 — the orchestration seed's note names four activities (AD-132)
 
 `references/templates/orchestration.json`: the `_README` is the kit's new canonical byte for byte —

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: '7.2.1'
+  version: '8.0.0'
 ---
 
 # agent-workflow-memory

package/capability.json

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

package/package.json

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

@@ -1,13 +1,5 @@
 #!/usr/bin/env node
-// spec-schema.mjs — the ONE reader that DEFINES a well-formed spec document under docs/ai/specs/.
-//
-// Pure text in, verdict out: readSpecDocument(text, rel) never touches the filesystem and imports
-// nothing, so it seeds layout-free into any deployment. The navigator's collapse (check-docs-size.mjs)
-// and the future spec-check read through THIS module — "malformed" has one definition, never two.
-// `rel` is the path INSIDE docs/ai/specs/ (the store root navigator is `index.md`).
-//
-// SPEC_SCHEMA carries the frozen values; the engine canon (references/specs.md) is pinned against it.
-// A refusal names exactly one rule id per defect, so a fixture corpus can be read rule by rule.
+// Canon: the methodology engine's references/specs.md (frozen schema, refusals table).
 
 export const SPEC_SCHEMA = Object.freeze({
   storePrefix: 'docs/ai/specs/',
@@ -34,17 +26,25 @@ export const SPEC_SCHEMA = Object.freeze({
   rootOwnedKeys: Object.freeze(['status', 'revision']),
   rootOwnedSections: Object.freeze(['## Scenarios', '## Out of scope', '## Module', '## Parts']),
   scenarioGrammar: '- S<N> <name> :: <repo-relative test path> :: spec:<slug>/S<N>  |  - S<N> <name> :: unbound',
+  openList: Object.freeze({
+    checkVerbs: Object.freeze(['refuse', 'refusal', 'REFUSE', 'REFUSAL']),
+    enumerationForms: Object.freeze([Object.freeze([',', ' or ']), Object.freeze([' · '])]),
+    closureTokens: Object.freeze([
+      'only if', 'only when', 'the only', 'everything else', 'anything else', 'nothing else',
+      'every other', 'any other', 'otherwise', 'exactly', 'one of', 'closed',
+    ]),
+    emphaticToken: 'ONLY',
+  }),
   rules: 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',
+    'section-forbidden', 'fence', 'open-list', 'children-link', 'children-duplicate', 'fan-out', 'scenario-line',
     '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',
   ]),
 });
 
-// The descriptor check-docs-size.mjs joins to its ADR group: rows under `prefix` whose reader verdict
-// is clean collapse into ONE navigator row linking `navPath`; a row with reader errors stays visible.
+// Consumer contract: scripts/check-docs-size.mjs.
 export const SPECS_COLLAPSE = Object.freeze({
   prefix: SPEC_SCHEMA.storePrefix,
   navPath: `${SPEC_SCHEMA.storePrefix}${SPEC_SCHEMA.navigatorFile}`,
@@ -72,8 +72,6 @@ const FORBIDDEN_SECTIONS = Object.freeze({
 
 const KNOWN_KEYS = Object.freeze([...SPEC_SCHEMA.substrateKeys, 'kind', ...SPEC_SCHEMA.rootOwnedKeys]);
 
-// The frontmatter is a closed key set: an unknown key, a repeated key or a line that is not
-// `key: value` is a defect (`frontmatter-key`), never silently dropped or last-one-wins.
 const parseFrontmatter = (text) => {
   const match = text.match(FRONTMATTER_RE);
   if (!match) return null;
@@ -91,10 +89,6 @@ const parseFrontmatter = (text) => {
 
 const FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
 
-// The body as { title, sections: [{ heading, lines }], preamble, fenced } — the title is the FIRST
-// `# ` line, every `## ` line opens a section, the lines before the first section are the preamble.
-// The reader parses NO markdown code: a fence line is recorded (the `fence` refusal) rather than
-// modelled, so a spec carries no code sample and no line is ever ambiguous between code and structure.
 const parseBody = (body) => {
   const sections = [];
   const preamble = [];
@@ -116,8 +110,6 @@ const parseBody = (body) => {
   return { title: state.title, sections, preamble, fenced, sectionBeforeTitle: state.sectionBeforeTitle };
 };
 
-// Lexical classification of a repo-relative path field — the same vocabulary for module roots and
-// scenario bindings. Realpath/symlink containment needs the filesystem and is the checker's duty.
 export const classifyPath = (path) => {
   if (path.trim() === '') return 'empty';
   if (path.includes('\\')) return 'backslash';
@@ -139,8 +131,47 @@ const MODULE_PATH_RULES = Object.freeze({
 const isBullet = (line) => line === '-' || line.startsWith('- ');
 const bulletsOf = (lines) => lines.filter(isBullet).map((line) => line.slice(2));
 const contentOf = (lines) => lines.filter((line) => line.trim() !== '');
+const isAtxHeading = (line) => /^ {0,3}#{1,6}(?:[ \t]|$)/.test(line);
+const topLevelBulletsOf = (lines) => lines.reduce((state, raw) => {
+  const line = raw.replace(/\s+$/, '');
+  if (isBullet(line)) {
+    state.current = [line === '-' ? '' : line.slice(2)];
+    state.bullets.push(state.current);
+  } else if (line.trim() === '' || isAtxHeading(line)) state.current = null;
+  else if (state.current !== null) state.current.push(line.trim());
+  return state;
+}, { bullets: [], current: null }).bullets.map((parts) => parts.join(' ').replace(/\s+/g, ' ').trim());
+
+const CLAUSE_BREAK = String.fromCharCode(0);
+const MASKED_DOT = String.fromCharCode(1);
+const MASKED_SEMICOLON = String.fromCharCode(2);
+const maskClauseSpans = (text) => [...text].reduce((state, character) => {
+  if (character === '`') state.inSpan = !state.inSpan;
+  state.output.push(state.inSpan && character === '.' ? MASKED_DOT : state.inSpan && character === ';' ? MASKED_SEMICOLON : character);
+  return state;
+}, { inSpan: false, output: [] }).output.join('');
+const clausesOf = (bullet) => maskClauseSpans(bullet).replace(/([.;][*`\)\]]*) /g, `$1${CLAUSE_BREAK}`).split(CLAUSE_BREAK)
+  .map((clause) => clause.split(MASKED_DOT).join('.').split(MASKED_SEMICOLON).join(';').trim()).filter(Boolean);
+const containsInOrder = (text, tokens) => tokens.reduce((position, token) => {
+  const found = position === -1 ? -1 : text.indexOf(token, position);
+  return found === -1 ? -1 : found + token.length;
+}, 0) !== -1;
+const hasBoundedToken = (clause, token, flags) => new RegExp(`(^|[^A-Za-z0-9_-])${token}([^A-Za-z0-9_-]|$)`, flags).test(clause);
+const checkOpenLists = (parsed, kind, errors) => {
+  const groups = kind === 'spec' ? parsed.sections.filter((section) => section.heading === '## Contract').map((section) => section.lines)
+    : kind === 'part' ? [parsed.preamble, ...parsed.sections.map((section) => section.lines)] : [];
+  for (const clause of groups.flatMap(topLevelBulletsOf).flatMap(clausesOf)) {
+    const hasVerb = SPEC_SCHEMA.openList.checkVerbs.some((verb) => clause.includes(verb));
+    const hasEnumeration = SPEC_SCHEMA.openList.enumerationForms.some((form) => containsInOrder(clause, form));
+    const hasClosure = SPEC_SCHEMA.openList.closureTokens.some((token) => hasBoundedToken(clause, token, 'i'))
+      || hasBoundedToken(clause, SPEC_SCHEMA.openList.emphaticToken, '');
+    if (hasVerb && hasEnumeration && !hasClosure) {
+      const prefix = clause.split(/\s+/).slice(0, 6).join(' ');
+      errors.push({ rule: 'open-list', message: `the clause "${prefix}…" is an open list — add a closing form to it such as "only if …; everything else …"` });
+    }
+  }
+};
 
-// The slug a document owns: the file stem for a flat file, the folder name for an index.md.
 const describeRel = (rel) => {
   const segments = rel.split('/');
   const file = segments[segments.length - 1];
@@ -314,11 +345,7 @@ const checkParts = (parsed, at, errors) => {
   if (duplicate !== undefined) errors.push({ rule: 'parts', message: `part "${duplicate}" is listed twice` });
 };
 
-// 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.
+// Structure verdict: the same canon, "The frozen schema".
 const scenarioEntry = (line) => {
   const scenario = parseScenario(line);
   if (scenario === null) return null;
@@ -345,10 +372,6 @@ const extractStructure = (parsed) => ({
   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 = [];
@@ -372,6 +395,7 @@ export const readSpecDocument = (text, rel) => {
   const at = checkPath(rel, kind, errors);
   const parsed = parseBody(body);
   if (parsed.fenced.length > 0) errors.push({ rule: 'fence', message: `"${parsed.fenced[0]}" — a spec document carries no code fence` });
+  checkOpenLists(parsed, kind, errors);
   checkSections(parsed, kind, errors);
   if (kind === 'index') {
     checkChildren(parsed, errors);

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

@@ -32,6 +32,8 @@ const refuses = (text, rel, rule) => {
   const verdict = readSpecDocument(text, rel);
   expect(rulesOf(verdict)).toEqual([rule]);
 };
+const withContract = (contract) => specDoc().replace('Accepts a credential pair.', contract);
+const openListErrors = (contract, rel = 'login.md') => readSpecDocument(withContract(contract), rel).errors;
 
 describe('readSpecDocument — accept', () => {
   it('a flat draft spec reads clean with kind/status/revision', () => {
@@ -269,6 +271,69 @@ describe('readSpecDocument — the structure verdict (additive, slice 2a)', () =
   });
 });
 
+describe('readSpecDocument — open-list clauses', () => {
+  const refusal = 'the clause "an anchor path reported modified, untracked…" is an open list — add a closing form to it such as "only if …; everything else …"';
+  const open = '- an anchor path reported modified, untracked or ignored is the named refusal `anchor-dirty`';
+  const closed = '- an anchor path is accepted only if `ls-files -v` lists it with tag `H` and `status` is silent — everything else, a path reported modified, untracked or ignored, is the named refusal `anchor-dirty`';
+
+  it('refuses the measured clause with the exact message; verb alone, form alone and an in-clause closure pass', () => {
+    expect(openListErrors(open)).toEqual([{ rule: 'open-list', message: refusal }]);
+    for (const text of [closed, '- refuse one case', '- alpha, beta or gamma']) expect(openListErrors(text)).toEqual([]);
+  });
+
+  it('joins continuation lines, collapses whitespace and keeps an indented bullet in its top-level bullet', () => {
+    for (const text of ['- refuse alpha,\n   beta   or ignored', '- refuse alpha,\n  - beta or ignored']) expect(rulesOf(readSpecDocument(withContract(text), 'login.md'))).toEqual(['open-list']);
+  });
+
+  it('ends a bullet at a blank, the next top-level bullet or every ATX heading; Contract prose is ignored', () => {
+    for (const tail of ['\n\nEverything else closes', '\n- Everything else closes', ...Array.from({ length: 6 }, (_, i) => `\n${'#'.repeat(i + 1)} Everything else closes`)]) {
+      expect(rulesOf(readSpecDocument(withContract('- refuse alpha, beta or gamma' + tail), 'login.md'))).toEqual(['open-list']);
+    }
+    expect(openListErrors('refuse alpha, beta or gamma')).toEqual([]);
+  });
+
+  it('ends a bullet at indented and tab-separated ATX headings', () => {
+    for (const tail of ['\n   ## Everything else closes', '\n#\tEverything else closes']) expect(rulesOf(readSpecDocument(withContract('- refuse alpha, beta or gamma' + tail), 'login.md'))).toEqual(['open-list']);
+  });
+
+  it('starts a new empty top-level bullet before following prose', () => {
+    for (const tail of ['\n- \nEverything else closes', '\n-\nonly if closes']) expect(rulesOf(readSpecDocument(withContract('- refuse alpha, beta or gamma' + tail), 'login.md'))).toEqual(['open-list']);
+  });
+
+  it('judges an open list in every Contract section', () => {
+    const duplicate = specDoc().replace('## Scenarios', '## Contract\n\n- refuse alpha, beta or gamma\n\n## Scenarios');
+    expect(rulesOf(readSpecDocument(duplicate, 'login.md')).includes('open-list')).toBe(true);
+  });
+
+  it('splits clauses at punctuation plus markdown tails, but not inside backtick spans', () => {
+    for (const tail of ['.** ', '.` ', '.) ', '.] ', '; ']) expect(rulesOf(readSpecDocument(withContract(`- refuse alpha, beta or gamma${tail}Everything else closes`), 'login.md'))).toEqual(['open-list']);
+    for (const text of ['- refuse `alpha. beta`, gamma or delta', '- refuse `alpha; beta`, gamma or delta', '- refuse `alpha. beta, gamma or delta']) expect(rulesOf(readSpecDocument(withContract(text), 'login.md'))).toEqual(['open-list']);
+    expect(openListErrors('- refuse alpha``. beta, gamma or delta')).toEqual([]);
+  });
+
+  it('keeps span content in judgement, and a closure in a neighbouring clause cannot lift a refusal', () => {
+    expect(rulesOf(readSpecDocument(withContract('- `refuse` alpha, beta or gamma'), 'login.md'))).toEqual(['open-list']);
+    expect(openListErrors('- refuse alpha, beta or gamma with `everything else`')).toEqual([]);
+    expect(rulesOf(readSpecDocument(withContract('- refuse alpha, beta or gamma. Everything else closes'), 'login.md'))).toEqual(['open-list']);
+  });
+
+  it('matches verbs, forms and closure tokens with the frozen case and boundary rules', () => {
+    for (const verb of ['refuse', 'refuses', 'refused', 'refusal', 'refusals', 'REFUSE', 'REFUSAL']) expect(rulesOf(readSpecDocument(withContract(`- ${verb} alpha, beta or gamma`), 'login.md'))).toEqual(['open-list']);
+    for (const text of ['- Refuse alpha, beta or gamma', '- refuse alpha, beta and gamma']) expect(openListErrors(text)).toEqual([]);
+    expect(rulesOf(readSpecDocument(withContract('- refuse alpha · beta'), 'login.md'))).toEqual(['open-list']);
+    for (const token of SPEC_SCHEMA.openList.closureTokens) expect(openListErrors(`- ${token.toUpperCase()}: refuse alpha, beta or gamma`)).toEqual([]);
+    for (const text of ['- refuse alpha, beta or gamma — none of these', '- refuse alpha, beta or gamma — closed-key', '- refuse alpha, beta or gamma — READ-ONLY', '- refuse alpha, beta or gamma — if only this', '- refuse alpha, beta or gamma — not only this']) expect(rulesOf(readSpecDocument(withContract(text), 'login.md'))).toEqual(['open-list']);
+    expect(openListErrors('- refuse alpha, beta or gamma — ONLY this')).toEqual([]);
+  });
+
+  it('judges every part bullet, never an index, and freezes every schema list and inner pair', () => {
+    expect(rulesOf(readSpecDocument(partDoc({ extra: `\n${open}\n` }), 'auth/login/sessions.md'))).toEqual(['open-list']);
+    expect(readSpecDocument(indexDoc({ children: [], preamble: `\n${open}\n` }), 'auth/index.md').errors).toEqual([]);
+    expect(SPEC_SCHEMA.openList).toEqual({ checkVerbs: ['refuse', 'refusal', 'REFUSE', 'REFUSAL'], enumerationForms: [[',', ' or '], [' · ']], closureTokens: ['only if', 'only when', 'the only', 'everything else', 'anything else', 'nothing else', 'every other', 'any other', 'otherwise', 'exactly', 'one of', 'closed'], emphaticToken: 'ONLY' });
+    expect([SPEC_SCHEMA.openList, SPEC_SCHEMA.openList.checkVerbs, SPEC_SCHEMA.openList.enumerationForms, ...SPEC_SCHEMA.openList.enumerationForms, SPEC_SCHEMA.openList.closureTokens].every(Object.isFrozen)).toBe(true);
+  });
+});
+
 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([