@sabaiway/agent-workflow-memory 8.3.0 → 8.4.0

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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 `4.0.0`).
 
+## 8.4.0 — the commit hook runs your own scripts/pre-commit.local first (AD-195)
+
+**Your own commit checks now have a place of their own: `scripts/pre-commit.local`.** Every hook that
+`references/scripts/install-git-hooks.mjs` writes carries, right after `set -e`, a comment line naming that file and
+`if [ -f scripts/pre-commit.local ]; then bash scripts/pre-commit.local; fi`, so the file runs with bash before the
+docs and scripts lines.
+
+- A non-zero exit of the file stops the commit; with no such file the hook runs as before.
+- The installer never writes, reads or ships the file, and no flag turns the line off.
+- A hook this installer wrote gains the line the next time the installer runs (`prepare`, or by hand); a hook it
+  did not write is refused as before.
+- `install-git-hooks-repo-exec.test.mjs` proves it through real commits: the file runs before the docs check, an exit
+  1 stops the commit, and an absent file lets it through.
+
+MINOR: two new lines in every written hook.
+
 ## 8.3.0 — the hook installer arms the project-rules check and the layout check (AD-193)
 
 **`references/scripts/install-git-hooks.mjs` gains `--rules-check <path>` and `--layout-check <path>`.** Each writes

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

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "8.3.0",
+  "version": "8.4.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/install-git-hooks-repo-exec.test.mjs

@@ -4,12 +4,13 @@
 // deploy-copy suite (install-git-hooks.test.mjs) keeps the consumer-shaped behavior pins. Every
 // branch of the installer runs from here: fresh install, the guard arm/carry/disable/conflict
 // lanes, the rules-check and layout-check arm/carry/duplicate/refusal lanes (win32 included), the
-// unmanaged refusal, the up-to-date short-circuit, and the not-a-git-checkout skip. Every child
+// unmanaged refusal, the up-to-date short-circuit, the not-a-git-checkout skip, and the S71
+// real-commit lane (real `git commit` through the written hook over stand-in scripts). Every child
 // runs with each inherited GIT_* variable stripped, so a hook's environment never leaks in.
 
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync, realpathSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, existsSync, realpathSync, chmodSync, statSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -130,3 +131,55 @@ describe('install-git-hooks — the in-place installer under a GIT_DIR-pinned fi
     rmSync(nowhere, { recursive: true, force: true });
   });
 });
+
+// The commit lane also drops NODE_TEST_CONTEXT: an inherited one makes the hook's nested `node --test` skip every file.
+const IDENTITY = { GIT_AUTHOR_NAME: 'p', GIT_AUTHOR_EMAIL: 'p@e', GIT_COMMITTER_NAME: 'p', GIT_COMMITTER_EMAIL: 'p@e' };
+const bareAt = (home, extra = {}) => { const { NODE_TEST_CONTEXT: _, ...env } = envAt(home, { ...IDENTITY, ...extra }); return env; };
+const passes = (r) => (assert.equal(r.status, 0, r.stderr), r);
+
+// Passing stand-ins for every script the hook runs; check-docs-size.mjs, run right after the local line, records
+// whether the marker existed. The marker and the record live in a sibling dir, outside the work tree.
+const commitRepo = (root, side) => {
+  const [marker, record, local] = [join(side, 'marker'), join(side, 'record'), join(root, 'scripts', 'pre-commit.local')];
+  const git = (...args) => spawnChecked('git', args, { cwd: root, env: bareAt(root) });
+  mkdirSync(join(root, 'scripts'));
+  writeFileSync(join(root, 'scripts', 'check-docs-size.mjs'), `import { existsSync, writeFileSync } from 'node:fs';
+if (!process.argv.includes('--check-index')) writeFileSync(${JSON.stringify(record)}, String(existsSync(${JSON.stringify(marker)})));\n`);
+  for (const name of ['archive-changelog', 'archive-issues', 'archive-decisions']) writeFileSync(join(root, 'scripts', `${name}.mjs`), 'process.exit(0);\n');
+  writeFileSync(join(root, 'scripts', 'stand-in.test.mjs'), "import { test } from 'node:test';\ntest('a passing stand-in', () => {});\n");
+  for (const args of [['init', '-q'], ['add', '-A'], ['commit', '-qm', 'base']]) passes(git(...args));
+  passes(spawnChecked(process.execPath, [INSTALLER], { env: bareAt(root, { GIT_DIR: join(root, '.git') }) }));
+  const head = () => git('rev-parse', 'HEAD').stdout.trim();
+  const commit = (body) => {
+    if (body !== undefined) { writeFileSync(local, body); chmodSync(local, 0o644); assert.equal(statSync(local).mode & 0o111, 0, 'the local file is not executable'); }
+    writeFileSync(join(root, 'change.txt'), 'change\n');
+    passes(git('add', 'change.txt'));
+    return git('commit', '-qm', 'change');
+  };
+  return { marker, record, head, commit };
+};
+const inCommitRepo = (cell) => () => {
+  const dirs = ['hooks-commit-', 'hooks-commit-side-'].map((prefix) => realpathSync(mkdtempSync(join(tmpdir(), prefix))));
+  try { cell(commitRepo(...dirs)); } finally { for (const dir of dirs) rmSync(dir, { recursive: true, force: true }); }
+};
+
+describe('spec:init-project/S71 the local hook file through real commits over stand-ins', () => {
+  it('a local file that writes a marker runs before the docs check, and the commit exits 0', { timeout: 120_000 }, inCommitRepo((fx) => {
+    passes(fx.commit(`printf made > "${fx.marker}"\n`));
+    assert.ok(existsSync(fx.marker), 'the local file ran: its marker appeared');
+    assert.equal(readFileSync(fx.record, 'utf8'), 'true', 'the marker existed when check-docs-size.mjs ran');
+  }));
+
+  it('a local file that exits 1 stops the commit: non-zero, no new commit', { timeout: 120_000 }, inCommitRepo((fx) => {
+    const before = fx.head();
+    assert.notEqual(fx.commit('exit 1\n').status, 0, 'a local file exiting 1 stops the commit');
+    assert.equal(fx.head(), before, 'no new commit');
+  }));
+
+  it('with no local file the commit exits 0', { timeout: 120_000 }, inCommitRepo((fx) => {
+    const before = fx.head();
+    passes(fx.commit());
+    assert.notEqual(fx.head(), before, 'the commit landed');
+    assert.equal(readFileSync(fx.record, 'utf8'), 'false', 'the hook ran its stand-ins, with no marker');
+  }));
+});

package/references/scripts/install-git-hooks.mjs

@@ -6,6 +6,7 @@
 // suite, so docs files cannot drift over their declared `maxLines`, the auto-generated
 // `index.md` navigator cannot silently fall out of sync, stale archive entries never
 // reach a commit, and regressions to the scripts themselves are caught at commit time.
+// First after `set -e` it runs the project's own `scripts/pre-commit.local` with bash when present.
 //
 // The hooks location comes from git's OWN answer (`git rev-parse --git-path hooks`) — a linked
 // worktree resolves ITS OWN hooks path (its `.git` is a FILE; a hardcoded `.git/hooks` would
@@ -161,6 +162,8 @@ ${MAGIC_MARKER}
 # declared maxLines, the auto-generated index.md cannot silently go stale, stale
 # archive entries never reach a commit, and regressions to the scripts are caught.
 set -e
+# Your own commit checks go in scripts/pre-commit.local; it runs first, with bash, when present.
+if [ -f scripts/pre-commit.local ]; then bash scripts/pre-commit.local; fi
 node scripts/check-docs-size.mjs
 node scripts/check-docs-size.mjs --check-index
 node scripts/archive-changelog.mjs --check

package/references/scripts/install-git-hooks.test.mjs

@@ -59,7 +59,7 @@ const markerFor = (name) => `# ${name}:install-git-hooks.mjs`;
 const readHook = (root) => readFileSync(join(hooksPathOf(root), 'pre-commit'), 'utf8');
 const stub = (root, rel) => (mkdirSync(dirname(join(root, rel)), { recursive: true }), writeFileSync(join(root, rel), '// a stand-in tool\n'), join(root, rel));
 
-// The hook the 4.0.0-8.2.1 installer body writes with no guard: the six docs and scripts lines.
+// The hook the 8.3.0 installer body writes with no guard: the six docs and scripts lines.
 const plainHook = (root) => `#!/usr/bin/env bash
 ${markerFor(basename(root))}
 # Auto-installed by scripts/install-git-hooks.mjs (run it from "prepare" or by hand).
@@ -75,6 +75,16 @@ node scripts/archive-issues.mjs --check
 node scripts/archive-decisions.mjs --check
 node --test scripts/*.test.mjs
 `;
+const LOCAL_LINE = 'if [ -f scripts/pre-commit.local ]; then bash scripts/pre-commit.local; fi';
+// The plain hook every write carries: the 8.3.0 hook with, right after set -e, one `# ` comment naming
+// scripts/pre-commit.local (its wording is free, so it is read from the written hook) and the exact local line.
+const localHook = (root) => {
+  const lines = readHook(root).split('\n');
+  const comment = lines[lines.indexOf('set -e') + 1];
+  assert.ok(comment?.startsWith('# ') && comment.includes('scripts/pre-commit.local'), `right after set -e a # comment names scripts/pre-commit.local, got ${JSON.stringify(comment)}`);
+  assert.deepEqual(lines.filter((l) => l.includes('scripts/pre-commit.local')), [comment, LOCAL_LINE], 'the comment and the local line are the only lines naming scripts/pre-commit.local');
+  return plainHook(root).replace('set -e\n', `set -e\n${comment}\n${LOCAL_LINE}\n`);
+};
 const line = (path, role) => `node "${role ? shown(path) : path}" --check${role ? ` # ${role}` : ''}\n`;
 
 describe('install-git-hooks — beside no package.json, or a malformed one, the marker names the directory basename', () => {
@@ -148,8 +158,9 @@ describe('spec:init-project/S58 install-git-hooks — the rules-check and layout
     const [rules, layout, guard, guard2] = ['tools/rules-cli.mjs', 'tools/source-size-check.mjs', 'guard.mjs', 'g2/guard.mjs'].map((rel) => stub(root, rel));
     installs(root, ['--commit-guard', 'guard.mjs']);
     installs(root, ['--layout-check', 'tools/source-size-check.mjs']);
+    assert.equal(readHook(root), localHook(root) + line(layout, 'layout-check') + line(guard), 'the --layout-check run carried the guard line');
     installs(root, ['--rules-check', rules]);
-    const armed = plainHook(root) + line(rules, 'rules-check') + line(layout, 'layout-check');
+    const armed = localHook(root) + line(rules, 'rules-check') + line(layout, 'layout-check');
     assert.equal(readHook(root), armed + line(guard), 'each arming run carried the other armed lines');
     assert.match(installs(root).stdout, /already up to date/, 'a flagless re-run keeps all three');
     assert.equal(readHook(root), armed + line(guard));
@@ -163,7 +174,7 @@ describe('spec:init-project/S58 install-git-hooks — the rules-check and layout
     const [legacy, rules] = ['legacy/rules-cli.mjs', 'tools/rules-cli.mjs'].map((rel) => stub(root, rel));
     installs(root, ['--commit-guard', legacy]);
     installs(root, ['--rules-check', rules]);
-    const expected = plainHook(root) + line(rules, 'rules-check') + line(legacy);
+    const expected = localHook(root) + line(rules, 'rules-check') + line(legacy);
     assert.equal(readHook(root), expected);
     installs(root);
     assert.equal(readHook(root), expected, 'the flagless re-run keeps the legacy line as the guard');
@@ -183,11 +194,11 @@ describe('spec:init-project/S58 install-git-hooks — the rules-check and layout
     }
   }));
 
-  it('over a hook with no rules or layout line, a flagless and a --commit-guard run write the 4.0.0-8.2.1 bytes', inProject(({ root }) => {
+  it('over a hook with no rules or layout line, a flagless and a --commit-guard run write the plain hook with the comment line and the local line right after set -e', inProject(({ root }) => {
     installs(root);
-    assert.equal(readHook(root), plainHook(root));
+    assert.equal(readHook(root), localHook(root));
     installs(root, ['--commit-guard', 'guard.mjs']);
-    assert.equal(readHook(root), plainHook(root) + line(join(root, 'guard.mjs')));
+    assert.equal(readHook(root), localHook(root) + line(join(root, 'guard.mjs')));
   }));
 
   it('a wrong file name, a shell-active path or a missing value exits 2, a missing file exits 1, each writing nothing', inProject(({ root }) => {
@@ -220,11 +231,11 @@ describe('spec:init-project/S58 install-git-hooks — the rules-check and layout
     const armedAt = stub(root, 'a/b/rules-cli.mjs');
     if (process.platform !== 'win32') { // there the backslash is refused, writing nothing
       const posix = runInstaller(root, ['--rules-check', given]);
-      assert.deepEqual([posix.status, /a backslash, CR or LF/.test(posix.stderr), readHook(root)], [2, true, plainHook(root)], posix.stderr);
+      assert.deepEqual([posix.status, /a backslash, CR or LF/.test(posix.stderr), readHook(root)], [2, true, localHook(root)], posix.stderr);
     }
     installs(root, ['--rules-check', given], WIN32);
-    assert.equal(readHook(root), plainHook(root) + line(armedAt, 'rules-check'));
+    assert.equal(readHook(root), localHook(root) + line(armedAt, 'rules-check'));
     assert.match(installs(root).stdout, /already up to date/, 'the flagless re-run recognises the win32-armed line');
-    assert.equal(readHook(root), plainHook(root) + line(armedAt, 'rules-check'));
+    assert.equal(readHook(root), localHook(root) + line(armedAt, 'rules-check'));
   }));
 });