@sabaiway/agent-workflow-memory 3.0.1 → 3.2.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ 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`).
 
+## 3.2.0 — the ADR rotation can be asked whether a seed is safe, without seeding (AD-083)
+
+`archive-decisions.mjs --write-navigator` now honours `--dry-run`. It runs exactly the checks the
+real write runs — the heading parse, the half-migrated guard, and the store-integrity check — and
+then stops before touching anything, reporting how many decisions it validated.
+
+Why it exists: a guarded caller (the kit's ADR-store migration) had no way to find out whether
+seeding the store would succeed except by seeding it. A tree with a malformed decisions file could
+therefore be told «go ahead», and only discover the problem after files had been written. The same
+code now answers that question first. Nothing about the normal `--write-navigator` behaviour changes.
+
+## 3.1.0 — plain-language communication bar in §2.5 of the agent_rules template (AD-061)
+
+The `agent_rules.md` template's **§2.5 Communication** section gains a plain-language bar: every
+user-facing message is short, clear, and written in plain words of the dialogue language; when the
+dialogue language is not English, transliterated English jargon is banned — an English term
+survives only as the NAME of a thing (a flag / command / file / test), glossed in plain words when
+helpful; plain English stays plain for English-dialogue users.
+
+The bar is byte-identical to the kit's fallback copy of the same template (a hand-kept pair), so
+both deploy paths carry it. Existing deployments are reconciled into the bar by the kit's upgrade
+lane (not only new bootstraps); a standalone memory upgrade does not touch the §2.5 region. This is
+a COMMUNICATION contract (§2.5 of the deployed template), not a §2.x process invariant — the
+methodology engine is untouched.
+
 ## 3.0.1 — bundled reference scripts refreshed (no behavior change)
 
 PATCH rider on the kit 3.1.0 release — the publish workflow's changed-but-unbumped tooth caught

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

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "3.0.1",
+  "version": "3.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/archive-decisions.mjs

@@ -29,7 +29,10 @@
 //                      HOT preamble, and only THEN removes the monoliths — gated on conservation AND
 //                      the snapshot. Re-run skips byte-identical records (crash-resumable).
 //   --write-navigator  regenerate docs/ai/adr/log.md AND re-trigger the index regen (the authoring /
-//                      supersession write-side; the --write-index analog).
+//                      supersession write-side; the --write-index analog). With --dry-run it runs
+//                      EXACTLY the same validation (parse, half-migrated guard, store integrity) and
+//                      stops before every write — the read-only preflight a guarded caller needs to
+//                      earn a go-ahead without risking a partial write.
 //   --dry-run          print the planned rotation move-set, change nothing.
 //   --today=YYYY-MM-DD pin the lastUpdated stamp (tests / reproducible runs).
 //
@@ -693,7 +696,7 @@ const runMigrate = (root, flags, today, deps, log, logError) => {
   return 0;
 };
 
-const runWriteNavigator = (root, today, deps, log, logError) => {
+const runWriteNavigator = (root, flags, today, deps, log, logError) => {
   if (!existsSync(resolve(root, HOT_REL)) && !existsSync(resolve(root, ADR_DIR_REL))) {
     log(`[archive-decisions] SKIP — no ADR substrate (neither ${HOT_REL} nor ${ADR_DIR_REL}); nothing to write.`);
     return 0;
@@ -704,6 +707,14 @@ const runWriteNavigator = (root, today, deps, log, logError) => {
   const adrEntries = loadAdrStore(root);
   assertStoreIntegrity(hotEntries, adrEntries); // never emit a duplicate-row / corrupt navigator
   const corpus = [...hotEntries, ...adrEntries];
+  // --dry-run runs EXACTLY the validation above and stops before every write: the parse, the
+  // half-migrated guard and the store-integrity check are the same code the write path uses, so a
+  // caller (the guarded ADR-store crossing) can earn a go-ahead without a partial write. A separate
+  // re-implementation of these checks would be an approximation that can disagree with the writer.
+  if (flags.dryRun) {
+    log(`[archive-decisions] --write-navigator DRY-RUN — no files will be changed; ${corpus.length} ADR(s) validated.`);
+    return 0;
+  }
   writeNavigatorFile(root, corpus, today);
   const regen = (deps.regenerateIndex ?? defaultRegenerateIndex)(root, today);
   log(`[archive-decisions] wrote ${NAV_REL} (${corpus.length} ADRs in the corpus).`);
@@ -828,7 +839,7 @@ export const runCli = (argv, deps = {}) => {
     const today = todayOpt ?? new Date().toISOString().slice(0, 10);
 
     if (flags.migrate) return runMigrate(root, flags, today, deps, log, logError);
-    if (flags.writeNavigator) return runWriteNavigator(root, today, deps, log, logError);
+    if (flags.writeNavigator) return runWriteNavigator(root, flags, today, deps, log, logError);
     if (flags.check) return runCheck(root, today, log, logError);
 
     if (!existsSync(resolve(root, HOT_REL))) {

package/references/scripts/archive-decisions.test.mjs

@@ -643,6 +643,33 @@ describe('1.5 navigator — governing heads (computed), superseded drop out but
     assert.doesNotMatch(gov, /\| AD-002 \|/, 'the Proposed ADR is NOT a governing head (accepted & not-superseded only)');
   });
 
+  // The read-only preflight a guarded caller needs: the SAME parse / half-migrated guard / store
+  // integrity the writer runs, stopping before every write. Without it a caller can only learn that
+  // seeding is safe by seeding.
+  it('--write-navigator --dry-run validates and writes NOTHING', () => {
+    const root = makeRoot();
+    seedMigrated(root, { hotIds: ['005', '006'], storeIds: ['001'] });
+    const navBefore = readFileSync(join(root, NAV_REL), 'utf8');
+    rmSync(join(root, NAV_REL));
+    const r = run(['--write-navigator', '--dry-run', '--today=2026-07-09'], root);
+    assert.equal(r.code, 0);
+    assert.match(r.out.join('\n'), /DRY-RUN/, 'the run states it changed nothing');
+    assert.equal(existsSync(join(root, NAV_REL)), false, 'the navigator was NOT written by the dry-run');
+    // and the real run still produces exactly what the dry-run validated
+    assert.equal(run(['--write-navigator', '--today=2026-07-09'], root).code, 0);
+    assert.equal(readFileSync(join(root, NAV_REL), 'utf8'), navBefore);
+  });
+
+  it('--write-navigator --dry-run REFUSES a corrupt store instead of green-lighting it', () => {
+    const root = makeRoot();
+    seedMigrated(root, { hotIds: ['005', '006'], storeIds: ['001'] });
+    // a record whose id also lives in the HOT window — the store would hold the ADR twice
+    writeFileSync(join(root, ADR_DIR_REL, 'AD-005-dup.md'), '---\n---\n\n## AD-005 — Dup\n\nBody.\n');
+    const r = run(['--write-navigator', '--dry-run', '--today=2026-07-09'], root);
+    assert.notEqual(r.code, 0, 'a corrupt store fails the preflight');
+    assert.doesNotMatch(r.out.join('\n'), /DRY-RUN/, 'no go-ahead is printed for a tree that cannot converge');
+  });
+
   it('authoring a new HOT ADR then --write-navigator keeps --check green; a stale nav with NO write → exit 1, then --write-navigator fixes it', () => {
     const root = makeRoot();
     seedMigrated(root, { hotIds: ['005', '006'], storeIds: ['001'] });

package/references/templates/agent_rules.md

@@ -67,6 +67,7 @@ Before proposing changes or committing, review against:
 
 ### 2.5. Communication (user-facing messages)
 Apply this as part of §2 before any user-facing summary:
+- **Plain language.** User-facing narration is short, clear, plain words of the dialogue language; when the dialogue language is not English, transliterated English jargon is banned — an English term survives only as the NAME of a thing (a flag / command / file / test), glossed in plain words when helpful; plain English stays plain for English-dialogue users.
 - **Deliver the artifact IN the message** — paste the prompt / diff / version / command inline; never "see §X / open the file / run it and you'll see" as a *substitute* for showing what was asked.
 - **Lead with the result**, then the details; show exactly what was asked — no deflection, no "almost done" when the ask was the finished thing.
 - **No condescension, no filler.** Own a miss plainly and fix it in the same message.