@sabaiway/agent-workflow-memory 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -4,6 +4,35 @@ 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.2.2 — Strip the package's own tests from the npm tarball (memory)
+
+Packaging only — no API/behaviour change; removed the package's own colocated tests from the
+published tarball, deploy payload tests retained. The deployment-lineage head stays **`1.3.0`** (no
+`docs/ai` structural change, no migration file). The npm package version is a separate axis.
+
+- **`files[]` scoped negation.** Appended `!bin/*.test.mjs` and `!scripts/*.test.mjs` to the
+  package allowlist (npm ignores a root `.npmignore` when `files[]` is present, so negation entries
+  in `files[]` are the mechanism). Tarball **41 → 37 files**: 4 of the package's own colocated tests
+  no longer ship.
+- **Deploy payload tests retained.** `references/scripts/*.test.mjs` are deployed into a consumer
+  repo's `scripts/`, so they still ship — `!scripts/*.test.mjs` does not cross `/` and never touches
+  `references/scripts/`. **Never broaden it to `!references/**`** — those tests are deploy payload.
+- **Tarball guard.** `scripts/package-content.test.mjs` (dev-only) gains an `npm pack --dry-run
+  --json` invariant: no own-test leak, payload tests + runtime files present, exact file count
+  `=== 37`.
+- Test files stay on disk; the gate + publish CI run them from the checkout, unchanged. This is a
+  tarball-only exclusion.
+
+## 1.2.1 — Hidden-mode maintenance invariant (memory)
+
+Patch: documentation only. The deployment-lineage head stays **`1.3.0`** (no `docs/ai` structural
+change, no migration file). The npm package version is a separate axis.
+
+- **`agent_rules.md` template (§1.3) + the Visibility contract** now state that the task-completion
+  doc updates are **visibility-independent**: hidden mode git-ignores `docs/ai` but never makes
+  maintaining it optional — the updates simply live on disk and never enter a commit. Future
+  deployments carry the clarified protocol; the durable wording lives in `agent_rules.md` §1.3.
+
 ## 1.2.0 — Seeds the per-project orchestration config
 
 The substrate now seeds a new **per-project, user-editable recipe config** —

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

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "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",
@@ -42,7 +42,9 @@
     "capability.json",
     "references/",
     "scripts/",
-    "migrations/"
+    "migrations/",
+    "!bin/*.test.mjs",
+    "!scripts/*.test.mjs"
   ],
   "engines": {
     "node": ">=18"

package/references/contracts.md

@@ -19,6 +19,8 @@ diverge:
 - **visible** — artifacts are committed. Wire the project's `package.json` scripts (`docs:check` / `docs:index` / `docs:index:check` / `docs:archive` / `docs:archive:check` / `docs:archive:issues` / `docs:archive:issues:check` / `prepare: node scripts/install-git-hooks.mjs`) and add a minimal `.gitignore` (`docs/plans/`, `.claude/settings.local.json`). This is the canonical model.
 - **hidden** (in-tree) — same files on disk, but the repo "looks normal": add memory's OWN artifact paths to **one project-local ignore list, the repo's `.git/info/exclude`** — resolve it with `git rev-parse --git-path info/exclude` (worktree-safe) and **never** the machine-global `core.excludesFile`, which would silently affect every repo on the host (visibility is a *project* setting). Write each path **once**, in the **canonical anchored form** — `/AGENTS.md`, `/CLAUDE.md`, `/docs/ai/` (this subsumes `docs/ai/.memory-version` and any kit-fallback `docs/ai/.workflow-version` — do **not** list the stamps separately), the `/scripts/*.mjs` you added, `/docs/plans/`, `/.claude/settings.local.json`, and `/.claude/settings.json` (step-4 attribution can create it; a standalone hidden memory hides it too). Append only — never duplicate a line that is already present. **Verify `git status` shows the artifacts as ignored** afterwards. **Do not edit `package.json`** — that is a tracked change and would leak; the pre-commit hook (always untracked in `.git/hooks/`) calls the scripts via `node scripts/<x>.mjs` directly. *(In a family deploy the composition root then runs its hide tool, which absorbs these project-local lines into one canonical managed block and adds the external AI/agent footprint; memory writes no machine-global excludes at any step.)*
 
+**Visibility changes only what git sees, never how the agent works.** Both modes carry the same working memory and run the same session protocol — `docs/ai` is read at session start and maintained on task completion **identically** in hidden mode; "git-ignored / `git status` clean" is **not** "optional to update", the updates just live on disk and never enter a commit (the durable wording lives in `agent_rules.md` §1.3).
+
 Not in this version: a fully-external hidden mode (artifacts relocated outside the repo tree).
 Deferred to a later release + migration.
 

package/references/templates/agent_rules.md

@@ -33,6 +33,8 @@ Read in order, then confirm before starting:
 6. Run quality checks: lint, type-check, tests.
 
 ### 1.3. Task Completion
+> **Visibility-independent.** Every step below is mandatory in **both** visibility modes. Hidden mode (the AI footprint git-ignored via `.git/info/exclude`) changes only what **git** tracks — never whether you maintain `docs/ai`. "Git-ignored / `git status` clean" is **not** "optional to update": the doc/state updates still happen, they just live on disk and never enter a commit.
+
 Before claiming "done":
 1. Run all quality gates (lint + type-check + tests) — all green.
 2. Update docs: `current_state.md` (feature ready), `changelog.md` (entry), `handover.md` (**REPLACE** the last-session block — session delta, never append; older deltas live in `changelog.md` → `history/`), `pages/<page>.md` (matches implementation). Only bump "Last Updated" when content actually changed.

package/bin/install.test.mjs

@@ -1,110 +0,0 @@
-import { describe, it, beforeEach, afterEach } from 'node:test';
-import assert from 'node:assert/strict';
-import { spawnSync } from 'node:child_process';
-import { mkdtemp, rm, mkdir, symlink, readdir } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { tmpdir, homedir } from 'node:os';
-import { dirname, join, sep } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { assertContainedRealPath, tildify } from './install.mjs';
-
-const INSTALLER = join(dirname(fileURLToPath(import.meta.url)), 'install.mjs');
-const runInstaller = (target) => spawnSync(process.execPath, [INSTALLER, '--dir', target], { encoding: 'utf8' });
-
-describe('memory installer — payload + symlink-traversal hardening', () => {
-  let dir;
-  beforeEach(async () => {
-    dir = await mkdtemp(join(tmpdir(), 'aw-memory-install-'));
-  });
-  afterEach(async () => {
-    await rm(dir, { recursive: true, force: true });
-  });
-
-  it('installs the full enumerated payload (capability.json, LICENSE, stamp-takeover.mjs) and not the npm wrapper', () => {
-    const target = join(dir, 'agent-workflow-memory');
-    const res = runInstaller(target);
-    assert.equal(res.status, 0, res.stderr);
-    for (const f of [
-      'SKILL.md',
-      'capability.json',
-      'LICENSE',
-      'README.md',
-      'CHANGELOG.md',
-      'scripts/stamp-takeover.mjs',
-      'references/contracts.md',
-      'references/templates/AGENTS.md',
-      'references/templates/orchestration.json',
-      'migrations/legacy-stamp-takeover.md',
-    ]) {
-      assert.ok(existsSync(join(target, f)), `missing installed entry: ${f}`);
-    }
-    assert.equal(existsSync(join(target, 'bin/install.mjs')), false, 'the npm wrapper must not be copied into the skill dir');
-  });
-
-  it('refuses to write through a symlinked INTERMEDIATE dest component (no leak)', async () => {
-    const target = join(dir, 'target');
-    const evil = join(dir, 'evil');
-    await mkdir(target, { recursive: true });
-    await mkdir(evil, { recursive: true });
-    await symlink(evil, join(target, 'references'));
-    const res = runInstaller(target);
-    assert.notEqual(res.status, 0);
-    assert.match(res.stderr, /symlink/i);
-    assert.deepEqual(await readdir(evil), [], 'nothing should be written through the symlink');
-  });
-
-  it('refuses a DANGLING destination symlink (existsSync would have followed it to absent)', async () => {
-    const target = join(dir, 'target');
-    await mkdir(target, { recursive: true });
-    // references -> a path that does not exist (dangling). copyFile through it would create
-    // the file at the dangling target, outside `target`.
-    await symlink(join(dir, 'nowhere'), join(target, 'references'));
-    const res = runInstaller(target);
-    assert.notEqual(res.status, 0);
-    assert.match(res.stderr, /symlink/i);
-    assert.equal(existsSync(join(dir, 'nowhere')), false, 'dangling target must not be materialised');
-  });
-
-  it('refuses a symlinked TARGET root (no leak)', async () => {
-    const real = join(dir, 'real');
-    const root = join(dir, 'root');
-    await mkdir(real, { recursive: true });
-    await symlink(real, root);
-    const res = runInstaller(root);
-    assert.notEqual(res.status, 0);
-    assert.match(res.stderr, /symlink/i);
-    assert.deepEqual(await readdir(real), [], 'nothing should be written through the symlinked target');
-  });
-});
-
-describe('memory installer — Issue-004 regressions (exported helpers, in-process)', () => {
-  it('assertContainedRealPath accepts a contained child literally named "..foo"', () => {
-    const root = join(tmpdir(), 'aw-mem-contain-root');
-    assert.doesNotThrow(() => assertContainedRealPath(root, join(root, '..foo')));
-  });
-
-  it('assertContainedRealPath rejects a true `../` escape', () => {
-    const root = join(tmpdir(), 'aw-mem-contain-root');
-    assert.throws(() => assertContainedRealPath(root, join(root, '..', 'escape')), /outside the target dir/);
-  });
-
-  it('tildify collapses only a LEADING homedir, never a mid-path occurrence', () => {
-    assert.equal(tildify(`${homedir()}${sep}skills${sep}x`), `~${sep}skills${sep}x`, 'leading home → ~');
-    const midPath = `${sep}tmp${homedir()}${sep}x`;
-    assert.equal(tildify(midPath), midPath, 'a mid-path home occurrence is left untouched');
-  });
-});
-
-describe('memory installer — module hygiene', () => {
-  it('importing install.mjs runs nothing (main() is guarded by isDirectRun)', () => {
-    const url = JSON.stringify(pathToFileURL(INSTALLER).href);
-    const res = spawnSync(
-      process.execPath,
-      ['--input-type=module', '-e', `import(${url}).then(() => console.log('IMPORT_OK'));`],
-      { encoding: 'utf8' },
-    );
-    assert.equal(res.status, 0, res.stderr);
-    assert.match(res.stdout, /IMPORT_OK/);
-    assert.doesNotMatch(res.stdout, /installed v|updated the substrate/);
-  });
-});

package/scripts/package-content.test.mjs

@@ -1,78 +0,0 @@
-import { describe, it } from 'node:test';
-import assert from 'node:assert/strict';
-import { readFileSync, readdirSync, statSync } from 'node:fs';
-import { dirname, join, basename } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-// The memory substrate must "know nobody": it ships ONLY its own capability.json and NO
-// family-wide tooling (schema/validator/injection/scanner — those are owned by the composition
-// root). This guards the DAG at the package-content level.
-const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
-
-const FORBIDDEN_FILES = new Set([
-  'validate.mjs',
-  'schema.md',
-  'inject-methodology.mjs',
-  'methodology-slot.md',
-  'release-scan.mjs',
-]);
-const FORBIDDEN_DIRS = new Set(['tools', 'manifest']);
-
-const walk = (dir, acc = []) => {
-  for (const entry of readdirSync(dir)) {
-    if (entry === 'node_modules' || entry === '.git') continue;
-    const full = join(dir, entry);
-    if (statSync(full).isDirectory()) {
-      acc.push({ kind: 'dir', name: entry, full });
-      walk(full, acc);
-    } else {
-      acc.push({ kind: 'file', name: entry, full });
-    }
-  }
-  return acc;
-};
-
-describe('memory package content — DAG guard (knows nobody)', () => {
-  const entries = walk(ROOT);
-
-  it('ships no family-wide tooling files', () => {
-    const leaks = entries.filter((e) => e.kind === 'file' && FORBIDDEN_FILES.has(e.name));
-    assert.deepEqual(leaks.map((e) => e.full), [], 'family tooling must not ship in the memory package');
-  });
-
-  it('has no tools/ or manifest/ directory', () => {
-    const leaks = entries.filter((e) => e.kind === 'dir' && FORBIDDEN_DIRS.has(e.name));
-    assert.deepEqual(leaks.map((e) => e.full), []);
-  });
-
-  it('package.json files[] does not enumerate any family tooling', () => {
-    const pkg = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf8'));
-    const offending = (pkg.files ?? []).filter((f) => /tools|manifest|validate|schema\.md|inject-methodology|release-scan/.test(f));
-    assert.deepEqual(offending, []);
-  });
-
-  it('does ship its own capability.json (the only manifest it owns)', () => {
-    assert.ok(entries.some((e) => e.kind === 'file' && e.name === 'capability.json' && basename(dirname(e.full)) === basename(ROOT)));
-  });
-
-  it('no source file names a specific sibling skill (knows nobody — generic "composition root" only)', () => {
-    // Built from fragments so the literal sibling names never appear in THIS test's own source
-    // (otherwise the walk below would flag this file).
-    const d = '-';
-    const SIBLINGS = [
-      ['agent', 'workflow', 'kit'].join(d),
-      ['codex', 'cli', 'bridge'].join(d),
-      ['antigravity', 'cli', 'bridge'].join(d),
-      ['agent', 'workflow', 'engine'].join(d),
-    ];
-    const offenders = [];
-    for (const e of entries) {
-      if (e.kind !== 'file' || !/\.(md|mjs|json|sh|ya?ml)$/.test(e.name)) continue;
-      const text = readFileSync(e.full, 'utf8');
-      for (const sibling of SIBLINGS) {
-        if (text.includes(sibling)) offenders.push(`${e.full} → "${sibling}"`);
-      }
-    }
-    assert.deepEqual(offenders, [], 'memory must reference only the generic composition root, never a named sibling');
-  });
-});

package/scripts/stamp-takeover.test.mjs

@@ -1,166 +0,0 @@
-import { describe, it, beforeEach, afterEach } from 'node:test';
-import assert from 'node:assert/strict';
-import { mkdtemp, rm, writeFile, readFile, readdir } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import {
-  LINEAGE_HEAD,
-  parseSemver,
-  compareSemver,
-  decideTakeover,
-  selectMigrations,
-  writeStampAtomic,
-  applyTakeover,
-  readStamp,
-} from './stamp-takeover.mjs';
-
-describe('LINEAGE_HEAD', () => {
-  it('is the shared deployment-lineage head (not this package version)', () => {
-    assert.equal(LINEAGE_HEAD, '1.3.0');
-  });
-});
-
-describe('parseSemver / compareSemver', () => {
-  it('parses plain and v-prefixed semver, rejects junk', () => {
-    assert.deepEqual(parseSemver('1.3.0'), [1, 3, 0]);
-    assert.deepEqual(parseSemver(' v2.0.1 '), [2, 0, 1]);
-    assert.equal(parseSemver('1.3'), null);
-    assert.equal(parseSemver('next'), null);
-    assert.equal(parseSemver(null), null);
-  });
-  it('orders versions and returns null on unparseable input', () => {
-    assert.equal(compareSemver('1.2.0', '1.3.0'), -1);
-    assert.equal(compareSemver('1.3.0', '1.3.0'), 0);
-    assert.equal(compareSemver('1.4.0', '1.3.0'), 1);
-    assert.equal(compareSemver('x', '1.0.0'), null);
-  });
-});
-
-describe('decideTakeover — §1.5 state table (pure, per row)', () => {
-  it('only .workflow-version=V → copy V verbatim → .memory-version; migrate from V', () => {
-    const d = decideTakeover({ memoryVersion: null, workflowVersion: '1.2.0' });
-    assert.equal(d.status, 'ok');
-    assert.equal(d.writeMemoryVersion, '1.2.0'); // exact stamp value asserted
-    assert.equal(d.migrateFrom, '1.2.0');
-  });
-
-  it('both stamps → no takeover write; migrate from .memory-version', () => {
-    const d = decideTakeover({ memoryVersion: '1.3.0', workflowVersion: '1.1.0' });
-    assert.equal(d.status, 'ok');
-    assert.equal(d.writeMemoryVersion, null);
-    assert.equal(d.migrateFrom, '1.3.0');
-  });
-
-  it('only .memory-version → migrate from it, no write', () => {
-    const d = decideTakeover({ memoryVersion: '1.1.0', workflowVersion: null });
-    assert.equal(d.status, 'ok');
-    assert.equal(d.writeMemoryVersion, null);
-    assert.equal(d.migrateFrom, '1.1.0');
-  });
-
-  it('no stamp → conservative re-bootstrap', () => {
-    const d = decideTakeover({ memoryVersion: null, workflowVersion: null });
-    assert.equal(d.status, 'rebootstrap');
-    assert.equal(d.writeMemoryVersion, null);
-    assert.equal(d.migrateFrom, null);
-  });
-
-  it('unparseable .memory-version → STOP', () => {
-    const d = decideTakeover({ memoryVersion: 'garbage', workflowVersion: '1.2.0' });
-    assert.equal(d.status, 'stop');
-    assert.equal(d.writeMemoryVersion, null);
-  });
-
-  it('PRESENT but empty/whitespace stamp → STOP (not absent → rebootstrap)', () => {
-    assert.equal(decideTakeover({ memoryVersion: null, workflowVersion: '' }).status, 'stop');
-    assert.equal(decideTakeover({ memoryVersion: '   ', workflowVersion: null }).status, 'stop');
-  });
-
-  it('unparseable .workflow-version → STOP', () => {
-    const d = decideTakeover({ memoryVersion: null, workflowVersion: 'not-a-version' });
-    assert.equal(d.status, 'stop');
-  });
-
-  it('future .memory-version (> head) → STOP', () => {
-    const d = decideTakeover({ memoryVersion: '2.0.0', workflowVersion: null });
-    assert.equal(d.status, 'stop');
-    assert.match(d.note, /newer than the lineage head/);
-  });
-
-  it('future .workflow-version (> head) → STOP', () => {
-    const d = decideTakeover({ memoryVersion: null, workflowVersion: '9.9.9' });
-    assert.equal(d.status, 'stop');
-  });
-
-  it('workflow exactly at head → takeover writes the head', () => {
-    const d = decideTakeover({ memoryVersion: null, workflowVersion: '1.3.0' });
-    assert.equal(d.status, 'ok');
-    assert.equal(d.writeMemoryVersion, '1.3.0');
-  });
-});
-
-describe('selectMigrations', () => {
-  const available = ['1.1.0', '1.2.0', '1.3.0'];
-  it('selects strictly-newer migrations up to the head, ascending', () => {
-    assert.deepEqual(selectMigrations('1.0.0', available), ['1.1.0', '1.2.0', '1.3.0']);
-    assert.deepEqual(selectMigrations('1.2.0', available), ['1.3.0']);
-    assert.deepEqual(selectMigrations('1.3.0', available), []);
-  });
-  it('null migrateFrom selects all ≤ head; excludes future migrations', () => {
-    assert.deepEqual(selectMigrations(null, [...available, '1.4.0']), ['1.1.0', '1.2.0', '1.3.0']);
-  });
-});
-
-describe('applyTakeover — atomic, idempotent, integration (temp fs)', () => {
-  let dir;
-  beforeEach(async () => {
-    dir = await mkdtemp(join(tmpdir(), 'stamp-takeover-'));
-  });
-  afterEach(async () => {
-    await rm(dir, { recursive: true, force: true });
-  });
-
-  it('legacy-only: writes .memory-version verbatim and preserves .workflow-version', async () => {
-    await writeFile(join(dir, '.workflow-version'), '1.2.0\n', 'utf8');
-    const d = await applyTakeover(dir);
-    assert.equal(d.writeMemoryVersion, '1.2.0');
-    assert.equal(await readStamp(join(dir, '.memory-version')), '1.2.0');
-    assert.equal(await readStamp(join(dir, '.workflow-version')), '1.2.0'); // never deleted
-    // single trailing newline, no leftover temp files
-    assert.equal(await readFile(join(dir, '.memory-version'), 'utf8'), '1.2.0\n');
-    assert.equal((await readdir(dir)).filter((f) => f.includes('.tmp-')).length, 0);
-  });
-
-  it('is idempotent — a second run does not rewrite the stamp', async () => {
-    await writeFile(join(dir, '.workflow-version'), '1.2.0\n', 'utf8');
-    await applyTakeover(dir);
-    const second = await applyTakeover(dir);
-    assert.equal(second.writeMemoryVersion, null); // memory now present → no write
-    assert.equal(second.migrateFrom, '1.2.0');
-    assert.equal(await readStamp(join(dir, '.memory-version')), '1.2.0');
-  });
-
-  it('both stamps present: leaves .memory-version untouched', async () => {
-    await writeFile(join(dir, '.memory-version'), '1.3.0\n', 'utf8');
-    await writeFile(join(dir, '.workflow-version'), '1.1.0\n', 'utf8');
-    const d = await applyTakeover(dir);
-    assert.equal(d.writeMemoryVersion, null);
-    assert.equal(await readStamp(join(dir, '.memory-version')), '1.3.0');
-  });
-
-  it('STOP state performs no write (future stamp leaves prior state intact)', async () => {
-    await writeFile(join(dir, '.workflow-version'), '5.0.0\n', 'utf8');
-    const d = await applyTakeover(dir);
-    assert.equal(d.status, 'stop');
-    assert.equal(existsSync(join(dir, '.memory-version')), false); // nothing written
-  });
-
-  it('writeStampAtomic overwrites cleanly with a single trailing newline', async () => {
-    const target = join(dir, '.memory-version');
-    await writeStampAtomic(target, '1.1.0');
-    await writeStampAtomic(target, '1.3.0');
-    assert.equal(await readFile(target, 'utf8'), '1.3.0\n');
-    assert.equal((await readdir(dir)).filter((f) => f.includes('.tmp-')).length, 0);
-  });
-});

package/scripts/standalone-bootstrap.test.mjs

@@ -1,180 +0,0 @@
-// End-to-end acceptance: a standalone substrate bootstrap into a fresh project.
-//
-// The unit suites cover each module in isolation (the stamp state machine, the atomic
-// writer, the hook installer). This drives the documented bootstrap WRITE steps end to end
-// over a real temp project + a real git checkout, then asserts the deployed artifact set:
-// docs/ai + entry point exist, the pre-commit hook is installed, the deployment-lineage
-// stamp is .memory-version (the lineage head) ONLY, and the methodology slot ships empty.
-//
-// Standalone here means substrate-only: nothing fills the slot, so it stays empty and no
-// second (composition-root) stamp appears. The composition path is covered separately.
-
-import { describe, it, afterEach } from 'node:test';
-import assert from 'node:assert/strict';
-import {
-  mkdtempSync,
-  mkdirSync,
-  rmSync,
-  cpSync,
-  readdirSync,
-  readFileSync,
-  writeFileSync,
-  existsSync,
-  symlinkSync,
-} from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join, resolve, dirname } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { execFileSync } from 'node:child_process';
-import { writeStampAtomic, LINEAGE_HEAD } from './stamp-takeover.mjs';
-
-const SKILL_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
-const TEMPLATES = join(SKILL_ROOT, 'references', 'templates');
-const ENFORCEMENT = join(SKILL_ROOT, 'references', 'scripts');
-
-// The empty delimited slot the substrate ships in its entry point. Hard-coded (not imported
-// from the composition root) so this substrate test stays self-contained and dependency-free.
-const SLOT_START = '<!-- workflow:methodology:start -->';
-const SLOT_END = '<!-- workflow:methodology:end -->';
-const ORCH_START = '<!-- workflow:orchestration:start -->';
-const ORCH_END = '<!-- workflow:orchestration:end -->';
-// The deployed AGENTS.md line budget the composition root fills BOTH pointers inside (D-CAP). A
-// representative single-line fragment per slot models what the composition root injects.
-const AGENTS_MD_CAP = 100;
-const lineCount = (text) => text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
-const extractPair = (text, start, end) => {
-  const a = text.indexOf(start);
-  const b = text.indexOf(end);
-  return a !== -1 && b !== -1 && b > a ? text.slice(a + start.length, b) : null;
-};
-
-const tempDirs = [];
-const makeProject = () => {
-  const dir = mkdtempSync(join(tmpdir(), 'substrate-bootstrap-'));
-  tempDirs.push(dir);
-  return dir;
-};
-afterEach(() => {
-  while (tempDirs.length) rmSync(tempDirs.pop(), { recursive: true, force: true });
-});
-
-// Mirrors the bootstrap WRITE steps: entry point at the root (+ tool alias symlink), every
-// other template under docs/ai, enforcement scripts copied in, the hook installed against a
-// real checkout, and the lineage head stamped atomically. Returns the docs/ai dir.
-const bootstrap = (project) => {
-  cpSync(join(TEMPLATES, 'AGENTS.md'), join(project, 'AGENTS.md'));
-  symlinkSync('AGENTS.md', join(project, 'CLAUDE.md'));
-
-  const docsAi = join(project, 'docs', 'ai');
-  mkdirSync(docsAi, { recursive: true });
-  for (const entry of readdirSync(TEMPLATES)) {
-    if (entry === 'AGENTS.md') continue;
-    cpSync(join(TEMPLATES, entry), join(docsAi, entry), { recursive: true });
-  }
-
-  const projectScripts = join(project, 'scripts');
-  mkdirSync(projectScripts, { recursive: true });
-  cpSync(ENFORCEMENT, projectScripts, { recursive: true });
-
-  // The hook installer resolves its target from its OWN location, so run the copied-in copy
-  // (project/scripts/...) to install into project/.git/hooks — exactly as the procedure does.
-  execFileSync('git', ['init', '-q'], { cwd: project });
-  execFileSync(process.execPath, [join(projectScripts, 'install-git-hooks.mjs')], {
-    cwd: project,
-    stdio: 'pipe',
-  });
-
-  return docsAi;
-};
-
-describe('standalone substrate bootstrap (end-to-end, real temp project)', () => {
-  it('deploys docs/ai + entry point and installs the pre-commit hook', () => {
-    const project = makeProject();
-    const docsAi = bootstrap(project);
-
-    assert.ok(existsSync(join(project, 'AGENTS.md')), 'entry point exists');
-    assert.ok(existsSync(docsAi), 'docs/ai exists');
-    assert.ok(existsSync(join(docsAi, 'agent_rules.md')), 'a representative docs/ai file landed');
-
-    const hook = join(project, '.git', 'hooks', 'pre-commit');
-    assert.ok(existsSync(hook), 'pre-commit hook installed');
-    assert.match(readFileSync(hook, 'utf8'), /install-git-hooks\.mjs/, 'hook carries the installer marker');
-  });
-
-  it('stamps .memory-version (lineage head) ONLY — no second stamp', async () => {
-    const project = makeProject();
-    const docsAi = bootstrap(project);
-    await writeStampAtomic(join(docsAi, '.memory-version'), LINEAGE_HEAD);
-
-    assert.equal(readFileSync(join(docsAi, '.memory-version'), 'utf8').trim(), LINEAGE_HEAD);
-    assert.ok(!existsSync(join(docsAi, '.workflow-version')), 'no composition-root stamp in a standalone bootstrap');
-  });
-
-  it('ships BOTH pointer slots present-but-empty (methodology + orchestration)', () => {
-    const project = makeProject();
-    bootstrap(project);
-
-    const entry = readFileSync(join(project, 'AGENTS.md'), 'utf8');
-    const meth = extractPair(entry, SLOT_START, SLOT_END);
-    const orch = extractPair(entry, ORCH_START, ORCH_END);
-    assert.notEqual(meth, null, 'an ordered methodology marker pair is present');
-    assert.equal(meth.trim(), '', 'the methodology slot is empty as shipped');
-    assert.notEqual(orch, null, 'an ordered orchestration marker pair is present');
-    assert.equal(orch.trim(), '', 'the orchestration slot is empty as shipped');
-  });
-
-  it('seeds docs/ai/orchestration.json from the template (the bootstrap loop deploys it)', () => {
-    const project = makeProject();
-    const docsAi = bootstrap(project);
-    const seeded = join(docsAi, 'orchestration.json');
-    assert.ok(existsSync(seeded), 'the orchestration.json config is seeded into docs/ai');
-    assert.equal(
-      readFileSync(seeded, 'utf8'),
-      readFileSync(join(TEMPLATES, 'orchestration.json'), 'utf8'),
-      'the seeded config is byte-identical to the template',
-    );
-    // strict JSON valid + the conservative all-solo default the maintainer chose.
-    const config = JSON.parse(readFileSync(seeded, 'utf8'));
-    assert.equal(typeof config._README, 'string', 'an onboarding _README is present');
-    assert.equal(config['plan-authoring'].review, 'solo', 'default review recipe is solo');
-  });
-
-  // The stamp-independent upgrade "ensure" (SKILL.md upgrade step 2): create-if-missing /
-  // preserve-if-edited. Modeled here the way the documented prose performs it — so an equal-head
-  // re-run never clobbers a user's edited config, and a deleted one is re-seeded.
-  it('the upgrade ensure preserves an edited config and re-creates a deleted one', () => {
-    const project = makeProject();
-    const docsAi = bootstrap(project);
-    const dest = join(docsAi, 'orchestration.json');
-    const ensureConfig = () => {
-      if (!existsSync(dest)) cpSync(join(TEMPLATES, 'orchestration.json'), dest);
-    };
-
-    // A user edits the deployed config.
-    writeFileSync(dest, '{ "plan-authoring": { "review": "council" } }\n');
-    ensureConfig(); // an equal-head upgrade re-runs the ensure
-    assert.match(readFileSync(dest, 'utf8'), /council/, 'an edited config is preserved (never clobbered)');
-
-    // A missing config is re-seeded.
-    rmSync(dest);
-    ensureConfig();
-    assert.ok(existsSync(dest), 'a missing config is re-created from the template');
-    assert.equal(readFileSync(dest, 'utf8'), readFileSync(join(TEMPLATES, 'orchestration.json'), 'utf8'));
-  });
-
-  it('stays ≤ the cap when the composition root fills BOTH pointer slots (D-CAP headroom)', () => {
-    const project = makeProject();
-    bootstrap(project);
-    const entry = readFileSync(join(project, 'AGENTS.md'), 'utf8');
-    assert.ok(lineCount(entry) <= AGENTS_MD_CAP, `shipped (empty) AGENTS.md is ${lineCount(entry)} lines (cap ${AGENTS_MD_CAP})`);
-    // Fill each one-line pointer the way the composition root does (replace the empty body), then re-count.
-    const fill = (text, start, end, body) => {
-      const a = text.indexOf(start);
-      const b = text.indexOf(end);
-      return `${text.slice(0, a + start.length)}\n${body}\n${text.slice(b)}`;
-    };
-    let filled = fill(entry, SLOT_START, SLOT_END, '> methodology pointer (one line)');
-    filled = fill(filled, ORCH_START, ORCH_END, '> orchestration recipes pointer (one line)');
-    assert.ok(lineCount(filled) <= AGENTS_MD_CAP, `dual-filled AGENTS.md is ${lineCount(filled)} lines (cap ${AGENTS_MD_CAP})`);
-  });
-});