@sabaiway/agent-workflow-memory 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -4,6 +4,42 @@ 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 `1.3.0`).
 
+## 1.10.0 — Installer verb parity (the AD-034 cmp-keyed contract) + the recipe discovery step in the templates
+
+A **feature** release (installer messaging + template text; deployment-lineage head stays `1.3.0`
+— content-only, no migration):
+
+- **`bin/install.mjs`** — the install verb is now keyed on the OBSERVED version relation, never on
+  mere presence (closing the false `updated the substrate to vX` on an already-current machine):
+  fresh/legacy-unstamped → `installed`; older → `updated the substrate to`; same →
+  `refreshed the already-current substrate` + the fact-only repair-on-rerun note (never a cache
+  accusation; conditional `@latest` hint); newer → a loud **never-downgrade refusal** (nothing
+  written) unless `--allow-downgrade`, which then says `downgraded the substrate to` plainly. The
+  installed version is read from the target SKILL.md `metadata:`-scoped `version` (decoy-proof);
+  an existing-but-unreadable SKILL.md **fails closed**, never silently treated as legacy. Helpers
+  cloned INLINE (this package references no sibling — the knows-nobody DAG).
+- **`bin/install.test.mjs`** — the full engine-shape contract suite: no-op re-run wording,
+  downgrade refusal + `--allow-downgrade`, fail-closed unreadable SKILL.md, legacy no-stamp,
+  metadata-decoy version read.
+- **`references/templates/agent_rules.md` §1.1** — new step 2: read `docs/ai/orchestration.json`
+  (the CONFIGURED orchestration recipes) BEFORE picking a task; a silent recipe downgrade is a
+  forbidden substitution. **`references/templates/handover.md`** — a standing `**Active recipes:**`
+  slot line. Both regions byte-identical with the kit template copies, path-neutral (this substrate
+  names no sibling skill), guarded by the kit's `template-region-parity.test.mjs` (AD-038).
+
+## 1.9.0 — The agent_rules lens carries the checked-vs-unchecked plan boundary
+
+A **feature** release (template text only; scripts and installer unchanged; deployment-lineage
+head stays `1.3.0` — content-only, no migration). The §2.6 lens B5 bullet mirrors the engine's §9
+sharpening:
+
+- **`references/templates/agent_rules.md` (B5)** — a plan carries only **checked syntax** (a
+  Step's commands, run by its own Verification against an explicit expected outcome or gate) plus
+  literal fixture/schema fragments a named test copies or validates; **un-run, logic-bearing
+  syntax** (control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL) never lives
+  in plan prose — a fold or draft that wants one is the trigger to write the test instead. The
+  line stays byte-identical to the kit template (lens-mirror guarded).
+
 ## 1.8.0 — ADR-cascade rotation script + the seeded per-project gate declaration
 
 A **feature** release (deployment-lineage head stays `1.3.0`; the new surfaces reach existing

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

package/bin/install.mjs

@@ -53,6 +53,55 @@ const readVersion = async () => {
   }
 };
 
+// Never-downgrade gate helpers (D3 / AD-012, verb contract AD-034) — cloned INLINE from the
+// kit/engine installers (this package references no sibling — the knows-nobody DAG), so a bare
+// `npx … init` serving an OLDER cached build cannot overwrite a NEWER installed substrate.
+// Dependency-free semver: parse the leading x.y.z (prerelease/build ignored). compareSemver →
+// -1 | 0 | 1, or null when either side is unparseable (a legacy install predating any stamp → no gate).
+const parseSemver = (str) => {
+  const m = typeof str === 'string' ? str.trim().match(/^(\d+)\.(\d+)\.(\d+)/) : null;
+  return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+};
+
+const compareSemver = (a, b) => {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return null;
+  const firstDiff = [0, 1, 2].map((i) => (pa[i] === pb[i] ? 0 : pa[i] < pb[i] ? -1 : 1)).find((c) => c !== 0);
+  return firstDiff ?? 0;
+};
+
+// Extract the version that is a DIRECT child of the top-level `metadata:` key — never a top-level or
+// deeper-nested decoy `version:` (mirrors the manifest validator + the kit installer). Pure walk.
+const metadataVersion = (frontmatter) => {
+  const lines = frontmatter.split(/\r?\n/);
+  const metaIdx = lines.findIndex((l) => /^metadata:[ \t]*$/.test(l));
+  if (metaIdx === -1) return null;
+  const after = lines.slice(metaIdx + 1);
+  const dedent = after.findIndex((l) => /^[^ \t]/.test(l)); // a column-0 line closes the metadata block
+  const block = dedent === -1 ? after : after.slice(0, dedent);
+  const baseIndent = block.length ? (block[0].match(/^[ \t]*/)?.[0] ?? '') : '';
+  const verLine = block.find((l) => l.startsWith(`${baseIndent}version:`));
+  return verLine?.match(/version:[ \t]*['"]?(\d+\.\d+\.\d+)['"]?/)?.[1] ?? null;
+};
+
+// The installed version is read from the target's SKILL.md frontmatter metadata.version (the
+// substrate's detect.installed.file). Returns the semver string, or null when ABSENT / unstamped
+// (legacy → no gate). A SKILL.md that EXISTS but cannot be read is NOT swallowed as "legacy": fail
+// closed (throw) so the gate can never be silently bypassed (AGENTS.md: no silent failures).
+const readInstalledVersion = async (target) => {
+  const skill = resolve(target, 'SKILL.md');
+  if (!existsSync(skill)) return null; // absent → new/legacy install, nothing to compare
+  const text = await readFile(skill, 'utf8').catch((err) => {
+    throw new Error(
+      `[agent-workflow-memory] cannot read the installed SKILL.md (${tildify(skill)}): ${err.message}. ` +
+        `Refusing to install over an unreadable substrate — fix permissions/contents or remove it, then re-run.`,
+    );
+  });
+  const fm = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  return fm ? metadataVersion(fm[1]) : null;
+};
+
 // lstat without following symlinks; null when the path does not exist. Using lstat (not
 // existsSync, which FOLLOWS symlinks and so reports a *dangling* symlink as absent) is what
 // makes the guard below catch a dangling destination symlink too.
@@ -114,6 +163,7 @@ const parseArgs = (argv) => {
   return {
     help: argv.includes('--help') || argv.includes('-h'),
     version: argv.includes('--version') || argv.includes('-v'),
+    allowDowngrade: argv.includes('--allow-downgrade'),
     dir: dirFlag >= 0 ? argv[dirFlag + 1] : undefined,
   };
 };
@@ -128,13 +178,15 @@ const printHelp = (version) => {
   console.log(`agent-workflow-memory ${version}
 
 Usage:
-  npx @sabaiway/agent-workflow-memory@latest init [--dir <path>]
+  npx @sabaiway/agent-workflow-memory@latest init [--dir <path>] [--allow-downgrade]
   npx @sabaiway/agent-workflow-memory --version
   npx @sabaiway/agent-workflow-memory --help
 
 Installs/refreshes the memory substrate at ~/.claude/skills/agent-workflow-memory
   (override with --dir <path> or AGENT_WORKFLOW_MEMORY_DIR). init is additive —
-  it never deletes your settings and never writes through a symlink.
+  it never deletes your settings and never writes through a symlink. If the installed
+  substrate is newer than the version you ran, init refuses (no network — it compares
+  the version on disk) and points you at @latest; --allow-downgrade overrides that refusal.
 
 After install, invoke the skill in your agent, inside a project:
   first time in the project  ->  /agent-workflow-memory
@@ -169,13 +221,52 @@ const main = async () => {
     console.error(`[agent-workflow-memory] target dir is a symlink — refusing to write through it: ${tildify(target)}`);
     process.exit(1);
   }
+
+  // Stale-cache defenses (no network — version already on disk vs this runner). Read BEFORE any write
+  // so a refusal touches nothing. cmp is null on a legacy/unparseable install → no gate.
+  const installedVersion = wasPresent ? await readInstalledVersion(target) : null;
+  const cmp = installedVersion ? compareSemver(installedVersion, version) : null;
+
+  // Never-downgrade gate (D3 / AD-012): a bare `npx … init` can run an OLDER cached build, which
+  // would overwrite a NEWER installed substrate with old files. Refuse loudly (nonzero) unless
+  // --allow-downgrade — surfacing the cache trap instead of silently regressing (no silent failures).
+  if (cmp === 1 && !args.allowDowngrade) {
+    console.error(
+      `[agent-workflow-memory] refusing to downgrade: the installed substrate is v${installedVersion}, but ` +
+        `this runner is the OLDER v${version}.\n` +
+        `  This is the classic npx cache serving a stale build. To get the newest substrate, bypass the cache:\n` +
+        `    npx @sabaiway/agent-workflow-memory@latest init\n` +
+        `  (or pass --allow-downgrade to overwrite the newer install with v${version} anyway).`,
+    );
+    process.exit(1);
+  }
+
   await mkdir(target, { recursive: true });
   await Promise.all(
     PAYLOAD.map((entry) => copyRecursive(resolve(PKG_ROOT, entry), resolve(target, entry), target)),
   );
-  console.log(
-    `[agent-workflow-memory] ${wasPresent ? 'updated the substrate to' : 'installed'} v${version} -> ${tildify(target)}`,
-  );
+  // Verb keyed on the OBSERVED version relation (cmp), never on mere presence (AD-034): null (fresh
+  // install, or a legacy/unstamped one whose prior version is unknowable) → "installed"; -1 → a real
+  // update; 0 → already current (the copy still ran — see the note below); 1 is reachable only under
+  // --allow-downgrade (the gate above refused otherwise) and says so plainly.
+  const verb =
+    cmp === 0 ? 'refreshed the already-current substrate'
+    : cmp === 1 ? 'downgraded the substrate to'
+    : cmp === -1 ? 'updated the substrate to'
+    : 'installed';
+  console.log(`[agent-workflow-memory] ${verb} v${version} -> ${tildify(target)}`);
+
+  // Same-version re-run: state observable facts only. The copy DID run (repair-on-rerun is a feature —
+  // it restores locally modified/deleted files), and whether npx served a cached build is NOT
+  // observable here (no network), so the note never claims it; the @latest hint is conditional.
+  if (cmp === 0) {
+    console.log(
+      `[agent-workflow-memory] note: the substrate was already v${version} — the copy still ran, restoring ` +
+        `any locally modified or deleted skill file to this version's packaged contents. If you ` +
+        `expected a NEWER version, invoke the @latest tag explicitly:\n` +
+        `    npx @sabaiway/agent-workflow-memory@latest init`,
+    );
+  }
 
   console.log(`
 Next — open your agent inside a project and run the skill:

package/capability.json

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

package/package.json

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

@@ -18,8 +18,9 @@ Every AI agent working on this project **must** adhere to this protocol before w
 ### 1.1. Start of Session
 Read in order, then confirm before starting:
 1. `docs/ai/handover.md` — where we left off.
-2. `docs/ai/active_plan.md` — pick ONE task from "Immediate Priority".
-3. Confirm with the user: *"I'm taking task X. Confirm?"*
+2. `docs/ai/orchestration.json` — the CONFIGURED orchestration recipes (per activity/slot). Honor them: a silent recipe downgrade is a forbidden substitution.
+3. `docs/ai/active_plan.md` — pick ONE task from "Immediate Priority".
+4. Confirm with the user: *"I'm taking task X. Confirm?"*
 
 ### 1.2. During Work
 **Before any feature:** read the relevant page spec (`docs/ai/pages/<page>.md`). If behaviour changes, update the spec FIRST so docs and code never diverge.
@@ -74,7 +75,7 @@ Apply this as part of §2 before any user-facing summary:
 Apply these when authoring a plan, reviewing, folding a finding, or editing code — the layer read **before any code change**. (Full canon: the project's planning / workflow-methodology + orchestration canon.)
 - **Fold by code, not prose.** Before folding a code-touching finding into a plan or change, read the cited `file:line` and cite it — a prose fold drifts from the code and seeds the next bug.
 - **Right altitude.** Pin intent + invariants + acceptance criteria (named tests); leave fine code-mechanics to Execute, where prose cannot diverge from reality.
-- **No code-mechanics in the plan.** A Step still carries its exact paths + commands (the plan-structure / self-review canon); the ceiling is on *fold-bred* detail — a review fold must not push fine code-mechanics (`cd`, an env default, a flag) into prose. A fold that needs a mechanic is the trigger to write the test instead.
+- **No code-mechanics in the plan.** A Step still carries its exact paths + commands (the plan-structure / self-review canon) — checked syntax: the plan's own Verification runs them against an explicit expected outcome or gate; the only other syntax a plan may carry is a literal fixture/schema fragment a named test copies or validates. Un-run, logic-bearing syntax — control-flow, a regex, a glob, a grammar, an algorithm body, a mini-DSL — never lives in plan prose, however plausible or shell-verified it looks: a fold or draft that wants one is the trigger to write the test instead.
 - **Test-as-spec.** Fold a code-touching finding into a red→green TEST, not a prose paragraph — the gate is the only deterministic checker; a paragraph cannot self-check.
 - **Characterize-first.** Before editing UNCOVERED code, pin its current behavior in a green test, then edit — any unintended change goes red. Never edit what has no checker; first give it one. Keep edits atomic/reversible; prefer SUBTRACTIVE folds.
 - **Fold minimally — prose has no checker.** An ephemeral, gitignored plan is prose with no executable checker; fold **minimally, in ONE place** and run a **self-consistency** read across the plan before every re-review — a fold that drifts several prose spots is what turns a 2-round review into churn.

package/references/templates/handover.md

@@ -14,6 +14,7 @@ maxLines: 80
 
 **Last session:** {{DATE}}
 **Branch:** {{BRANCH}}
+**Active recipes:** not recorded yet — paste the configured-recipe line (composed from `docs/ai/orchestration.json`) and refresh it whenever the config changes.
 
 ## What was done last session