@sabaiway/agent-workflow-memory 1.0.0

package/references/templates/handover.md

@@ -0,0 +1,37 @@
+---
+type: state
+lastUpdated: {{DATE}}
+scope: session
+staleAfter: 7d
+owner: handover
+maxLines: 80
+---
+
+# Handover — Session Context
+
+> **Read this FIRST every session.** What we did last, what's open, what's risky.
+> This is a **session delta**: REPLACE the last-session block each time — do not append. Older deltas live in `changelog.md` → `history/`.
+
+**Last session:** {{DATE}}
+**Branch:** {{BRANCH}}
+
+## What was done last session
+
+- Bootstrap — AI-agent memory system initialised.
+
+## What's open right now
+
+- TODO: fill domain-specific sections after the first real task.
+
+## Risks / gotchas for next session
+
+- None recorded yet.
+
+## Quality snapshot
+
+| Check | Status |
+|-------|--------|
+| lint | n/a |
+| type-check | n/a |
+| unit tests | n/a |
+| E2E tests | n/a |

package/references/templates/known_issues.md

@@ -0,0 +1,33 @@
+---
+type: reference
+lastUpdated: {{DATE}}
+scope: permanent
+staleAfter: 30d
+owner: none
+maxLines: 300
+---
+
+# Known Issues
+
+> Every bug we hit. Status, workaround, impact, plan. Avoids re-discovering pain.
+
+## 🔴 Open
+
+### Issue-001 — {{Title}}
+- **Discovered:** {{DATE}}
+- **Status:** Open
+- **Impact:** {{user-facing? dev-only? blocking?}}
+- **Workaround:** {{if any}}
+- **Plan:** {{next action}}
+- **Related files:** `{{src/...}}`
+
+## 🟢 Resolved
+
+### Issue-XXX — {{Title}}
+- **Resolved:** {{DATE}}
+- **Resolution:** {{what fixed it}}
+- **Commit:** {{SHA}}
+
+---
+
+> Resolved issues older than the window are rotated to `history/issues-resolved.md` by the issue-archive script.

package/references/templates/pages/PAGE_TEMPLATE.md

@@ -0,0 +1,53 @@
+---
+type: reference
+lastUpdated: {{DATE}}
+scope: permanent
+staleAfter: 90d
+owner: none
+maxLines: 200
+---
+
+# Page: {{PAGE_NAME}}
+
+**Route:** `{{/path}}`
+**Component:** `{{src/routes/<file>}}`
+
+> Template — copy to `docs/ai/pages/<page>.md` when a route appears. NOT deployed on bootstrap.
+
+## Purpose
+
+{{1–2 sentences.}}
+
+## Layout
+
+```
+{{ASCII or description of regions.}}
+```
+
+## States
+
+| State | Trigger | UI |
+|-------|---------|----|
+| Empty | No data | {{description}} |
+| Loading | Fetch in flight | {{description}} |
+| Ready | Data loaded | {{description}} |
+| Error | Fetch failed | {{description}} |
+
+## User Actions
+
+| Action | Trigger | Result | Validation |
+|--------|---------|--------|------------|
+| — | — | — | — |
+
+## Data Dependencies
+
+- Reads: {{data sources}}
+- Writes: {{mutations}}
+
+## Linked Components
+
+- `{{src/components/...}}`
+
+## Open Questions / TODO
+
+- [ ] —

package/references/templates/pages/index.md

@@ -0,0 +1,23 @@
+---
+type: reference
+lastUpdated: {{DATE}}
+scope: permanent
+staleAfter: 90d
+owner: none
+maxLines: 80
+---
+
+# Pages Index
+
+> Registry of every user-facing page/route. Source of truth for routing.
+
+| Route | Name | Spec | Status |
+|-------|------|------|--------|
+| `/` | Home | [home.md](./home.md) | TODO |
+| `{{/path}}` | {{Name}} | [{{name}}.md](./{{name}}.md) | TODO |
+
+## Shared
+
+- [shared-patterns.md](./shared-patterns.md) — loading, empty, error, modal, form, toast patterns.
+
+> Create one `pages/<page>.md` per route as it appears (use `PAGE_TEMPLATE.md` from the skill). Every page must ship an HTML-validity / a11y E2E test.

package/references/templates/pages/shared-patterns.md

@@ -0,0 +1,30 @@
+---
+type: reference
+lastUpdated: {{DATE}}
+scope: permanent
+staleAfter: 90d
+owner: none
+maxLines: 400
+---
+
+# Shared Page Patterns
+
+> Cross-cutting UI patterns. Copy these, don't reinvent them.
+
+## Loading State
+{{Pattern + example.}}
+
+## Empty State
+{{Pattern + example.}}
+
+## Error State
+{{Pattern + example.}}
+
+## Modal Lifecycle
+{{Pattern + example.}}
+
+## Form Validation Flow
+{{Pattern + example.}}
+
+## Toast / Notification
+{{Pattern + example.}}

package/references/templates/tech_reference.md

@@ -0,0 +1,34 @@
+---
+type: reference
+lastUpdated: {{DATE}}
+scope: permanent
+staleAfter: 90d
+owner: none
+maxLines: 300
+---
+
+# Technical Reference — Patterns & Examples
+
+> Copy-paste-ready snippets for libraries and patterns used in this project. (Mature projects may fold this into a project patterns skill.)
+
+## No Silent Failures
+
+Every internal validation/guard that rejects an action MUST log via the structured logger with context (component, action, ids, inputs). User-facing failures also surface in the UI.
+
+```{{lang}}
+{{Show the project's logger usage. Replace with a real example after first use.}}
+```
+
+## {{Library Name}} — {{Pattern}}
+
+```{{lang}}
+{{Example after first use.}}
+```
+
+---
+
+## Add a section when
+
+- You discover a non-trivial library configuration.
+- You establish a reusable pattern across 2+ files.
+- You hit a gotcha future agents should not re-discover.

package/references/templates/technical_specification.md

@@ -0,0 +1,37 @@
+---
+type: reference
+lastUpdated: {{DATE}}
+scope: permanent
+staleAfter: 90d
+owner: none
+maxLines: 280
+---
+
+# Technical Specification
+
+> Application-level overview: what it does, who uses it, key data models.
+
+## Purpose
+
+{{One-paragraph mission.}}
+
+## Users / Personas
+
+- {{Persona}} — {{what they do}}
+
+## Core Domain Model
+
+```
+{{Entities and relationships, e.g.}}
+User ──owns──> Project ──contains──> Item
+```
+
+## Data Flow
+
+{{Numbered flow: client → API → storage → render.}}
+
+## External Integrations
+
+| Service | Purpose | Auth |
+|---------|---------|------|
+| — | — | — |

package/scripts/package-content.test.mjs

@@ -0,0 +1,78 @@
+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.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+// Legacy-stamp takeover — the lineage-coherent state machine for the
+// `.workflow-version` (kit-fallback) → `.memory-version` (memory) transition.
+//
+// Two independent axes: npm *package* versions vs the *deployment-lineage* stamp.
+// The deployment lineage is a SINGLE shared sequence; its current head is LINEAGE_HEAD.
+// Both `.memory-version` and the kit-fallback `.workflow-version` track THAT sequence —
+// never their package versions. So this substrate's package may be 1.0.0 while the stamp
+// it writes is the lineage head (1.3.0 today).
+//
+// `decideTakeover` is a PURE function (stamp state in → action out) so the state machine is
+// unit-testable per row. `applyTakeover` is the thin fs wrapper; stamp writes are ATOMIC
+// (write temp + rename) so an interrupted write can never corrupt the prior stamp.
+//
+// The Markdown twin `migrations/legacy-stamp-takeover.md` documents the same table as the
+// no-Node manual fallback. Dependency-free, Node >= 18.
+
+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';
+
+// 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.
+export const LINEAGE_HEAD = '1.3.0';
+
+const SEMVER_RE = /^v?(\d+)\.(\d+)\.(\d+)$/;
+
+export const parseSemver = (value) => {
+  if (value == null) return null;
+  const match = String(value).trim().match(SEMVER_RE);
+  if (!match) return null;
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+};
+
+// Returns -1 | 0 | 1 for a<b | a==b | a>b, or null if either side is unparseable.
+export const compareSemver = (a, b) => {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < 3; i += 1) {
+    if (pa[i] !== pb[i]) return pa[i] < pb[i] ? -1 : 1;
+  }
+  return 0;
+};
+
+// null ONLY for a truly absent value (ENOENT). A PRESENT but empty/whitespace stamp normalizes to
+// '' (not null), so decideTakeover treats it as unparseable → STOP rather than absent → rebootstrap.
+const normalize = (value) => (value == null ? null : String(value).trim());
+
+// PURE: given the two stamp values (string contents or null) and the lineage head, decide the
+// takeover action. Mirrors the §1.5 state table. Output:
+//   status            'ok' | 'stop' | 'rebootstrap'
+//   writeMemoryVersion the value to atomically write to .memory-version now, or null
+//   migrateFrom        the version memory migrations run from (exclusive), or null
+//   note              human-readable reason (for the report)
+export const decideTakeover = (state, head = LINEAGE_HEAD) => {
+  const memory = normalize(state?.memoryVersion);
+  const workflow = normalize(state?.workflowVersion);
+
+  // Validate every PRESENT stamp before any state branch: unparseable or future → STOP.
+  for (const [name, value] of [['.memory-version', memory], ['.workflow-version', workflow]]) {
+    if (value == null) continue;
+    if (!parseSemver(value)) {
+      return {
+        status: 'stop',
+        writeMemoryVersion: null,
+        migrateFrom: null,
+        note: `unparseable ${name} stamp "${value}" — STOP and report (needs manual review).`,
+      };
+    }
+    if (compareSemver(value, head) > 0) {
+      return {
+        status: 'stop',
+        writeMemoryVersion: null,
+        migrateFrom: null,
+        note: `${name} stamp "${value}" is newer than the lineage head ${head} — STOP and report (do not downgrade).`,
+      };
+    }
+  }
+
+  if (memory != null) {
+    // .memory-version present (valid, not future): takeover is a no-op; migrate from it.
+    return {
+      status: 'ok',
+      writeMemoryVersion: null,
+      migrateFrom: memory,
+      note:
+        workflow != null
+          ? 'both stamps present — no takeover; each tool migrates from its own stamp (.memory-version here).'
+          : 'migrate from the existing .memory-version.',
+    };
+  }
+
+  if (workflow != null) {
+    // Legacy only: copy verbatim → .memory-version; leave .workflow-version; migrate from it.
+    return {
+      status: 'ok',
+      writeMemoryVersion: workflow,
+      migrateFrom: workflow,
+      note: `legacy takeover — copy .workflow-version "${workflow}" verbatim into .memory-version; the legacy stamp is left in place.`,
+    };
+  }
+
+  // No stamp at all → conservative re-bootstrap offer (existing behaviour).
+  return {
+    status: 'rebootstrap',
+    writeMemoryVersion: null,
+    migrateFrom: null,
+    note: 'no stamp found — offer a conservative re-bootstrap.',
+  };
+};
+
+// Select migration versions strictly newer than `migrateFrom` and ≤ head, ascending.
+// `available` is the list of migration `<version>` strings present in migrations/.
+export const selectMigrations = (migrateFrom, available, head = LINEAGE_HEAD) =>
+  [...available]
+    .filter((v) => parseSemver(v))
+    .filter((v) => (migrateFrom == null || compareSemver(v, migrateFrom) > 0) && compareSemver(v, head) <= 0)
+    .sort((a, b) => compareSemver(a, b));
+
+// Absent ONLY for ENOENT. A permission/EISDIR/IO error must NOT masquerade as "no stamp" — that
+// would silently route a real failure into re-bootstrap or a wrong takeover; surface it so the
+// caller STOPs.
+export const readStamp = async (filePath) => {
+  try {
+    return normalize(await readFile(filePath, 'utf8'));
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+};
+
+// Atomic single-line stamp write: an EXCLUSIVE (`wx` = O_EXCL|O_CREAT) randomized temp file in the
+// same dir, then rename over the target. `wx` never follows or overwrites a pre-existing path
+// (so a planted temp-name symlink can't redirect the write); a randomized name avoids collisions;
+// a crash before the rename leaves the prior stamp byte-for-byte intact; the temp is cleaned on
+// any failure so no residue is left behind.
+export const writeStampAtomic = async (filePath, value) => {
+  const tmp = join(dirname(filePath), `.${basename(filePath)}.tmp-${randomBytes(8).toString('hex')}`);
+  try {
+    await writeFile(tmp, `${String(value).trim()}\n`, { encoding: 'utf8', flag: 'wx' });
+    await rename(tmp, filePath);
+  } catch (err) {
+    await unlink(tmp).catch(() => {});
+    throw err;
+  }
+};
+
+// Thin fs wrapper: read both stamps from a docs/ai dir, decide, and (only when the decision
+// says so) atomically write .memory-version. Idempotent: a second run sees .memory-version
+// and writes nothing. Returns the decision for the caller to report.
+export const applyTakeover = async (docsAiDir, { head = LINEAGE_HEAD } = {}) => {
+  const memoryPath = join(docsAiDir, '.memory-version');
+  const workflowPath = join(docsAiDir, '.workflow-version');
+  const decision = decideTakeover(
+    { memoryVersion: await readStamp(memoryPath), workflowVersion: await readStamp(workflowPath) },
+    head,
+  );
+  if (decision.status === 'ok' && decision.writeMemoryVersion != null) {
+    await writeStampAtomic(memoryPath, decision.writeMemoryVersion);
+  }
+  return decision;
+};
+
+// Direct-run CLI: `node stamp-takeover.mjs <docs/ai-dir>` reads the two stamps, applies the
+// lineage takeover (atomic, idempotent), and prints the decision. Exits non-zero on a STOP state.
+const main = async (argv) => {
+  const dir = argv[0];
+  if (!dir) {
+    console.error('usage: stamp-takeover.mjs <docs/ai-dir>  (applies the .workflow-version → .memory-version lineage takeover)');
+    process.exit(2);
+  }
+  const decision = await applyTakeover(resolve(dir));
+  console.log(`[stamp-takeover] ${decision.status}: ${decision.note}`);
+  if (decision.migrateFrom) console.log(`[stamp-takeover] migrate memory migrations from: ${decision.migrateFrom} (head ${LINEAGE_HEAD})`);
+  if (decision.status === 'stop') process.exit(1);
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) await main(process.argv.slice(2));

package/scripts/stamp-takeover.test.mjs

@@ -0,0 +1,166 @@
+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);
+  });
+});