@sabaiway/agent-workflow-memory 4.4.0 → 4.5.1

package/CHANGELOG.md

@@ -4,6 +4,54 @@ 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.5.1 — the deployed scripts decide direct-run by real path, so a symlinked entry point stops silently doing nothing (AD-102; ships with kit 5.11.1)
+
+**A script invoked through a symlink ran nothing and exited 0.** The guard that decides "was I run
+directly, or imported?" compared `import.meta.url` against `process.argv[1]` — a comparison that is
+false whenever the entry point reached the script through a symlink. The script then took the
+imported-as-a-module path, did no work, and reported success. The fix has been sitting in-repo,
+unpublished, since the delegation series' own measurement came back FAIL and the fix was correctly
+held back from a release it should not have justified (AD-101). It ships here as the plain bug fix it
+is.
+
+- **The six standalone scripts this package deploys inline a fail-closed realpath guard.** A deployed
+  script cannot reach the kit's shared direct-run leaf, so one lexical line becomes an 11-line IIFE
+  that resolves both sides through `realpath` and refuses to guess when it cannot: `references/scripts/`
+  `archive-changelog.mjs` · `archive-decisions.mjs` · `archive-issues.mjs` · `check-docs-size.mjs` ·
+  `migrate-gates.mjs`, plus `scripts/stamp-takeover.mjs`.
+- **No behaviour changes for a script invoked by its real path** — which is why this is a PATCH. What
+  changes is that invoking one through a symlink now does what you asked instead of nothing.
+
+Recorded size effect (reason: a standalone deployed script cannot reach the kit's shared direct-run
+leaf, so it inlines the realpath guard — one lexical line becomes an 11-line fail-closed IIFE):
+
+```text
+  agent-workflow-memory/references/scripts/archive-changelog.mjs: lines 546 -> 557 (raise)
+  agent-workflow-memory/references/scripts/archive-decisions.mjs: lines 1199 -> 1210 (raise)
+  agent-workflow-memory/references/scripts/archive-issues.mjs: lines 415 -> 426 (raise)
+  agent-workflow-memory/references/scripts/check-docs-size.mjs: lines 580 -> 591 (raise)
+  agent-workflow-memory/references/scripts/migrate-gates.mjs: lines 722 -> 733 (raise)
+  agent-workflow-memory: aggregate lines 10907 -> 10962 -> 10974 (raise)
+```
+
+## 4.5.0 — the closing state block gets a canon rule, and its slot labels are declared English (AD-098; ships with kit 5.10.0)
+
+**Three slots that answer three different questions, or one restatement written three times.** The
+deployed rules template already asked for a closing state block; what it never said was what belongs
+in each slot — so *now* drifted into a report of finished work, and the block collapsed into a
+summary the reader had already read.
+
+- **`agent_rules.md` gains the rule, in §2.5.** *Now* is the state at this instant — what is running
+  or what the work is stopped on, never a report of what was completed (that belongs in the message
+  body, above the block). *From you* is the real unblocker, named; a turn that is ending always has
+  one. *Next* is what follows.
+- **The slot LABELS stay English; the values take the dialogue language.** An English label is what
+  lets a state-block checker find the block and its slots at all; everything written into a slot is
+  in the project's own language, and the checker's English phrase sets do not judge those values.
+  This is the substrate half of the same decision the kit's guard ships.
+- **One test point renamed to describe the check it actually runs** — the `--write-index` refusal is
+  a pre-write symlink refusal on the index path, which is what the body has pinned since 4.4.0.
+
 ## 4.4.0 — the deploy finishes by writing the navigator its entry point declares (AD-096; ships with kit 5.9.0)
 
 **The substrate deployed an `AGENTS.md` that calls `docs/ai/index.md` always-loaded, and no step

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.4.0'
+  version: '4.5.1'
 ---
 
 # agent-workflow-memory

package/capability.json

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

package/package.json

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

@@ -32,9 +32,9 @@
 //   --warm-days=N (default 30)
 //   --today=YYYY-MM-DD (default today UTC) — useful for tests / reproducible runs
 
-import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync, realpathSync } from 'node:fs';
 import { dirname, resolve, basename } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { tokenizeMarkdown, findParagraphBreak, fail } from './markdown-blocks.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -542,5 +542,16 @@ export const runCli = (argv, deps = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+// Run main() only when executed directly, never on import. Compare by REAL path: an entry point
+// reached through a symlink resolves to its target, so a raw string compare reads the two as
+// different and the CLI never runs. realpathSync collapses the link so both sides match.
+const isDirectRun = (() => {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
 if (isDirectRun) process.exitCode = runCli(process.argv.slice(2));

package/references/scripts/archive-decisions.mjs

@@ -75,9 +75,9 @@
 //
 // Dependency-free, Node >= 22. Deployed into a consumer's scripts/ like its siblings.
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, rmSync, statSync, realpathSync } from 'node:fs';
 import { dirname, resolve, join, posix } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 import { createHash } from 'node:crypto';
 import { tmpdir } from 'node:os';
@@ -1195,5 +1195,16 @@ export const runCli = (argv, deps = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+// Run main() only when executed directly, never on import. Compare by REAL path: an entry point
+// reached through a symlink resolves to its target, so a raw string compare reads the two as
+// different and the CLI never runs. realpathSync collapses the link so both sides match.
+const isDirectRun = (() => {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
 if (isDirectRun) process.exitCode = runCli(process.argv.slice(2));

package/references/scripts/archive-issues.mjs

@@ -31,9 +31,9 @@
 //   --cutoff-days=N (default 14)
 //   --today=YYYY-MM-DD (default UTC today)
 
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from 'node:fs';
 import { dirname, resolve, basename } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { tokenizeMarkdown, fail } from './markdown-blocks.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -411,5 +411,16 @@ export const runCli = (argv, deps = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+// Run main() only when executed directly, never on import. Compare by REAL path: an entry point
+// reached through a symlink resolves to its target, so a raw string compare reads the two as
+// different and the CLI never runs. realpathSync collapses the link so both sides match.
+const isDirectRun = (() => {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
 if (isDirectRun) process.exitCode = runCli(process.argv.slice(2));

package/references/scripts/check-docs-size-cli.test.mjs

@@ -1,6 +1,6 @@
 // check-docs-size-cli.test.mjs — runCli branch pins the subprocess smokes cannot reach
 // in-process (Phase-5 coverage fill; the main spec file is parity-frozen, so these ride a
-// colocated file): the unknown-argument refusal and the written-empty-index guard.
+// colocated file): the unknown-argument refusal and the pre-write symlink refusal on the index path.
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtempSync, mkdirSync, writeFileSync, symlinkSync, rmSync } from 'node:fs';
@@ -20,7 +20,7 @@ describe('check-docs-size runCli — refusal branches', () => {
     assert.match(stderr, /Unknown argument: --bogus/);
   });
 
-  it('--write-index landing on a sink path (index stat size 0) is the loud written-empty refusal', async () => {
+  it('--write-index refuses a symlinked index path BEFORE writing, naming the path', async () => {
     const root = mkdtempSync(join(tmpdir(), 'cds-cli-'));
     try {
       mkdirSync(join(root, 'docs', 'ai'), { recursive: true });

package/references/scripts/check-docs-size.mjs

@@ -25,9 +25,9 @@
 //   --quiet            print only failures (and final summary)
 
 import { readFile, writeFile, readdir, stat, rename, rm } from 'node:fs/promises';
-import { existsSync, lstatSync } from 'node:fs';
+import { existsSync, lstatSync, realpathSync } from 'node:fs';
 import { dirname, resolve, relative, join, basename, sep } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { randomBytes } from 'node:crypto';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -571,7 +571,18 @@ export const runCli = async (argv, deps = {}) => {
   return result(errorCount > 0 && !flags.report ? 1 : 0);
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+// Run main() only when executed directly, never on import. Compare by REAL path: an entry point
+// reached through a symlink resolves to its target, so a raw string compare reads the two as
+// different and the CLI never runs. realpathSync collapses the link so both sides match.
+const isDirectRun = (() => {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
 if (isDirectRun) {
   const { code, stdout, stderr } = await runCli(process.argv.slice(2));
   if (stdout) process.stdout.write(stdout);

package/references/scripts/migrate-gates.mjs

@@ -28,7 +28,7 @@
 
 import { existsSync, lstatSync, readFileSync, writeFileSync, renameSync, unlinkSync, realpathSync } from 'node:fs';
 import { join, resolve, isAbsolute } from 'node:path';
-import { pathToFileURL, fileURLToPath } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { randomBytes } from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 
@@ -718,5 +718,16 @@ export const main = (argv = process.argv.slice(2), io = {}) => {
   }
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+// Run main() only when executed directly, never on import. Compare by REAL path: an entry point
+// reached through a symlink resolves to its target, so a raw string compare reads the two as
+// different and the CLI never runs. realpathSync collapses the link so both sides match.
+const isDirectRun = (() => {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
 if (isDirectRun) process.exitCode = main();

package/references/templates/agent_rules.md

@@ -73,6 +73,7 @@ Apply this as part of §2 before any user-facing summary:
 - **No condescension, no filler.** Own a miss plainly and fix it in the same message.
 - **Large artifact (≈>100 lines):** deliver a real summary or the key excerpt inline **and** link the file — never flood the reader with a 2000-line paste, never hide the answer behind a bare pointer.
 - **Live host/session facts are tool-composed only.** Any claim about the current host or session state (prompts fired, sandbox scope, whether a bypass was needed, network reachability, approval counts) must trace to **live tool output** from **this session**; a memory/handover snapshot is **context, never report facts**, and a claim with no live signal is **omitted or explicitly marked unverified** — never asserted from recollection.
+- **The closing state block answers three DIFFERENT questions.** Close a user-facing message with three labelled slots — *now* · *what I need from you* · *what's next*. The slot LABELS stay ENGLISH — an English label is what lets a state-block checker FIND the block and its slots at all; everything written INTO a slot is in the project's dialogue language; when that language is not English, the checker's English phrase sets do not judge those values. **Now** = the state at this instant: what is RUNNING, or what the work is stopped on. It is **never a report of finished work** — what you completed goes in the message BODY, above the block. **From you** = the real unblocker, named; a turn that is ENDING always has one. **Next** = what follows. A *now* slot that opens with what was completed buries the one fact the reader opened the message for, and the three slots collapse into one restatement.
 
 ### 2.6. Planning, review & process-fidelity invariants
 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. This section is rendered from that canon and refreshed on upgrade; a custom edit is preserved verbatim, but flagged.)

package/scripts/stamp-takeover.mjs

@@ -15,10 +15,11 @@
 // The Markdown twin `migrations/legacy-stamp-takeover.md` documents the same table as the
 // no-Node manual fallback. Dependency-free, Node >= 22.
 
+import { realpathSync } from 'node:fs';
 import { readFile, writeFile, rename, unlink } from 'node:fs/promises';
 import { dirname, basename, join, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 
 // The shared agent-workflow deployment-lineage head. Bumped only when a project-migration
 // changes the deployed docs/ai structure — NOT on a packaging-only release.
@@ -177,5 +178,16 @@ const main = async (argv) => {
   if (decision.status === 'stop') process.exit(1);
 };
 
-const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+// Run main() only when executed directly, never on import. Compare by REAL path: an entry point
+// reached through a symlink resolves to its target, so a raw string compare reads the two as
+// different and the CLI never runs. realpathSync collapses the link so both sides match.
+const isDirectRun = (() => {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
 if (isDirectRun) await main(process.argv.slice(2));