@sabaiway/agent-workflow-memory 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,43 @@ 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.3.0 — Agent-writable config note; §2.5 Communication (memory)
+
+A **feature** release. The seeded `docs/ai/orchestration.json` note now frames the config as
+agent-writable (via the `set-recipe` writer) **and** still hand-editable — the old "never written for
+you" wording is gone. The `agent_rules.md` substrate gains a **§2.5 Communication** self-review item
+(deliver the artifact inline; lead with the result; large-artifact carve-out). The deployment-lineage
+head stays **`1.3.0`** (no `docs/ai` structural change, no migration file); the npm package version is a
+separate axis.
+
+- **Seed-or-preserve only (unchanged contract).** This substrate still only **seeds** the config from its
+  template when missing and **preserves** an existing one byte-for-byte — a NEW deployment gets the updated
+  note from the seed. Refreshing the note *in place* on an already-deployed file is the **composition
+  root's** job (memory stays standalone and owns no cross-package refresh helper).
+- **Template parity preserved** — the seeded `orchestration.json` stays byte-identical to the composition
+  root's fallback copy; the new note is identical across both.
+- **Knows-nobody invariant intact** — the note + SKILL.md refer to the writer generically, never naming a
+  specific sibling skill.
+
+## 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

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.1'
+  version: '1.3.0'
 ---
 
 # agent-workflow-memory
@@ -47,7 +47,7 @@ What this substrate owns vs what it only points at. The methodology + orchestrat
 | Deployment-lineage stamp | **memory** | `docs/ai/.memory-version` |
 | Plan→Phase→Step vocabulary, lifecycle, `queue.md`, mandatory Cleanup | **methodology** (not this skill) | the empty `workflow:methodology` slot — filled by the composition root |
 | Orchestration recipes (Solo / Reviewed / Council / Delegated) | **methodology engine** (not this skill) | the empty `workflow:orchestration` slot — filled by the composition root |
-| Per-project recipe **CONFIG** (which recipe each activity/slot uses) | **memory** seeds an *editable default* | `docs/ai/orchestration.json` (hand-edited; the recipe **canon** + the slot **vocabulary** live in the engine / composition root, never here) |
+| Per-project recipe **CONFIG** (which recipe each activity/slot uses) | **memory** seeds an *editable default* | `docs/ai/orchestration.json` (agent-writable via the composition root's `set-recipe` writer, or hand-edited; the recipe **canon** + the slot **vocabulary** live in the engine / composition root, never here) |
 
 ---
 
@@ -113,7 +113,8 @@ bootstrapping over a live system, but the user makes the final call.
 10. **Stamp the deployment lineage.** Write the **deployment-lineage head** into
     `docs/ai/.memory-version` (one semver line). The lineage head is **`1.3.0`** (the
     `LINEAGE_HEAD` constant in `scripts/stamp-takeover.mjs`) — the shared `agent-workflow`
-    lineage, **not** this package's npm version (`1.2.0`). Use the atomic writer in
+    lineage, a **separate axis** from this package's npm version (the two may even coincide by
+    accident; see *Stamp = lineage head, not package version*). Use the atomic writer in
     `scripts/stamp-takeover.mjs` (write-temp + rename).
 11. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on filled-vs-TODO, then **ask before
     committing** — never auto-commit. **Exception — delegated mode (below): skip this gate.**
@@ -163,11 +164,14 @@ Fill strategy:
    **behind** the never-downgrade STOP above. **Also stamp-independent (same gate, before the equal-head
    short-circuit): ensure `docs/ai/orchestration.json`** — **create it from
    `${CLAUDE_SKILL_DIR}/references/templates/orchestration.json` if missing**, **preserve it byte-for-byte
-   if it already exists** (a user may have edited it; never clobber it). This is why an equal-head (`1.3.0`)
-   deployment still gains the config seed **without a lineage-head bump or a migration file** (the
-   stamp-independent-reconcile precedent — like the pointer slots + the hidden-mode footprint). **Then**,
-   if the stamp **equals** the head → report "up to date" (plus any footprint move / config seed just
-   made) and stop.
+   if it already exists** (a user may have edited it; never clobber it). The shipped template's `_README`
+   already frames the config as agent-writable (set it with the `set-recipe` writer) and still
+   hand-editable. (Refreshing that note in place on an existing file is the **composition root's** job on
+   its own reconcile — this substrate is standalone and only seeds-or-preserves; it owns no cross-package
+   refresh helper.) This is why an equal-head (`1.3.0`) deployment still gains the config seed **without a
+   lineage-head bump or a migration file** (the stamp-independent-reconcile precedent — like the pointer
+   slots + the hidden-mode footprint). **Then**, if the stamp **equals** the head → report "up to date"
+   (plus any footprint move / config seed just made) and stop.
 3. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` context (entries newer than the stamp).
 4. Apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those
    newer than the stamp. Migrations are **idempotent**.
@@ -192,8 +196,9 @@ Fill strategy:
 
 - **Source vs target directory.** Templates/scripts are read from the skill's own dir; the
   **working directory is the target project** — never write substrate files back into the skill.
-- **Stamp = lineage head, not package version.** `.memory-version` carries `1.3.0` (the shared
-  `agent-workflow` lineage), not the npm `1.2.0`. They are independent axes.
+- **Stamp = lineage head, not package version.** `.memory-version` carries the **deployment-lineage
+  head** (`1.3.0`, the shared `agent-workflow` lineage) — a **separate axis** from this package's npm
+  version (the two may even coincide by accident). They move independently.
 - **Both pointer slots ship empty and stay the user's.** Never author methodology or orchestration
   text into them; on upgrade, preserve their content byte-for-byte. The composition root is their only
   writer.

package/capability.json

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

package/package.json

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

package/references/templates/agent_rules.md

@@ -63,6 +63,13 @@ Before proposing changes or committing, review against:
 ### 2.4. Quality Gates
 - Always run type-checker, linter, and all tests before committing.
 
+### 2.5. Communication (user-facing messages)
+Apply this as part of §2 before any user-facing summary:
+- **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.
+- **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.
+
 ---
 
 ## 3. Token & Session Optimization

package/references/templates/orchestration.json

@@ -1,5 +1,10 @@
 {
-  "_README": "Per-project orchestration config: the recipe used at each step (slot) of each named activity. Hand-edit this file — it is never written for you. Each activity is configured independently (e.g. plan-authoring, plan-execution), and so is each slot within it. A slot's value is a recipe: a 'review' slot accepts solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize); an 'execute' slot accepts solo | delegated (you implement / a backend runs a bounded sub-task). The default below is 'solo' everywhere — no execution backend required. Raise a slot to reviewed or council for a second opinion, or to delegated to hand off execution; those need an execution backend set up first. Remove a slot's line to fall back to the computed default (reviewed when a review backend is ready, otherwise solo). Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for your environment, and pass a per-run override to change one slot just once. Strict JSON — no comments.",
-  "plan-authoring": { "review": "solo" },
-  "plan-execution": { "execute": "solo", "review": "solo" }
+  "_README": "Per-project orchestration config: the recipe used at each step (slot) of each named activity. Easiest: tell the agent in plain language and run the `set-recipe` writer — it interprets your intent, previews the change, and writes valid JSON for you. You can still hand-edit this file directly whenever you prefer; that option never goes away. Each activity is configured independently (e.g. plan-authoring, plan-execution), and so is each slot within it. A slot's value is a recipe: a 'review' slot accepts solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize); an 'execute' slot accepts solo | delegated (you implement / a backend runs a bounded sub-task). The default below is 'solo' everywhere — no execution backend required. Raise a slot to reviewed or council for a second opinion, or to delegated to hand off execution; those need an execution backend set up first. Remove a slot's line (or run `set-recipe --unset <activity>.<slot>`) to fall back to the computed default (reviewed when a review backend is ready, otherwise solo). Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for your environment. Strict JSON — no comments.",
+  "plan-authoring": {
+    "review": "solo"
+  },
+  "plan-execution": {
+    "execute": "solo",
+    "review": "solo"
+  }
 }

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})`);
-  });
-});