@sabaiway/agent-workflow-memory 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog — @sabaiway/agent-workflow-memory
+
+All notable changes to the memory substrate. Versions are this **package's** npm versions;
+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.0.0
+
+Initial standalone release. The **memory substrate** extracted into its own package as Plan 1
+of the agent-workflow family refactor (deployment-lineage head `1.3.0`). Additive: the family
+composition root keeps its own bundled copy as a fallback, so nothing breaks for existing users.
+
+### Added
+- Standalone npm package + `bin/install.mjs` installer targeting
+  `~/.claude/skills/agent-workflow-memory` (`AGENT_WORKFLOW_MEMORY_DIR`), with a
+  symlink-traversal guard — the installer never writes *through* a destination symlink
+  (root / intermediate / leaf).
+- `capability.json` — the `agent-workflow` family manifest (`kind: memory-substrate`,
+  `provides: ["context"]`). The package ships **no** family-wide schema/validator tooling
+  (owned by the composition root) — it knows nobody.
+- An **empty** delimited methodology slot in `templates/AGENTS.md`
+  (`<!-- workflow:methodology:start -->` / `:end`); the substrate only ever ships it empty
+  and preserves any filled content on upgrade. The composition root injects the methodology.
+- `scripts/stamp-takeover.mjs` — a pure, unit-tested state machine for the legacy
+  `.workflow-version` → `.memory-version` lineage takeover, with **atomic** (write-temp +
+  rename) stamp writes, plus `migrations/legacy-stamp-takeover.md` (the no-Node manual
+  fallback).
+
+### Changed
+- The deployment stamp is `docs/ai/.memory-version` (the legacy `.workflow-version` is never
+  deleted; both track the shared lineage). Hidden-mode ignore lists now include
+  `.memory-version`.
+- `references/templates/agent_rules.md` no longer embeds the planning-methodology vocabulary —
+  it points at the methodology owner. `contracts.md` attribution wiring is de-attributed from
+  "the kit" to "the bootstrap".
+
+### Carried over from the original substrate (deployment-lineage 1.3.0)
+- `docs/ai/` templates, the Node enforcement scripts (caps + index freshness + 3-tier archive
+  + hook installer) and their tests, the three setup contracts, and migrations `1.1.0`
+  (conversational language) and `1.2.0` (agent attribution).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sabaiway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,61 @@
+# @sabaiway/agent-workflow-memory
+
+**Portable, cross-agent memory substrate for AI coding agents.** Deploys an `AGENTS.md`
+entry point (+ a `CLAUDE.md` symlink for Claude Code) and a structured `docs/ai/` context
+store with cap / archive / index-freshness enforcement into any repo. After it runs, any
+future agent — including a fresh session of yourself — can reconstruct project context in
+~60 seconds, find the current task, and avoid repeating past mistakes.
+
+This is the **memory layer** of the `agent-workflow` family.
+It owns the substrate only — `docs/ai/`, the entry point, caps / 3-tier archive / index gate,
+the Node enforcement scripts, the pre-commit hook, the templates, and the three setup
+contracts (visibility / conversational language / agent attribution). It deliberately **knows
+nobody else** in the `agent-workflow` family: the **workflow methodology** (plan → execute →
+review vocabulary, lifecycle, `queue.md`, mandatory Cleanup) lives elsewhere and is injected
+into a delimited slot in `AGENTS.md` by the family composition root, not by this package.
+
+## Install
+
+```bash
+npx @sabaiway/agent-workflow-memory init
+```
+
+Installs/refreshes the skill at `~/.claude/skills/agent-workflow-memory` (override with
+`--dir <path>` or `AGENT_WORKFLOW_MEMORY_DIR`). `init` is additive — it never deletes your
+settings and never writes through a symlink. Re-running updates the skill's own files; that is
+how you upgrade the *skill*. Migrating a *project's* deployment is a separate in-agent step
+(below).
+
+## Use
+
+Open your agent inside a project and run the skill:
+
+- **`/agent-workflow-memory`** — bootstrap a new or empty project. Asks the three setup
+  questions (visibility, conversational language, agent attribution), then writes `docs/ai/`,
+  `AGENTS.md`, the enforcement scripts + pre-commit hook, and stamps
+  `docs/ai/.memory-version`. The methodology slot in `AGENTS.md` is left **empty**.
+- **`/agent-workflow-memory upgrade`** — migrate an existing deployment to the skill's current
+  version. Reads `docs/ai/.memory-version`, runs only newer migrations in semver order, and
+  **preserves** anything already in the methodology slot (extract-and-reinsert — it never
+  regenerates `AGENTS.md` wholesale).
+
+## Stamps & lineage
+
+Two independent axes: this package's **npm version** vs the **deployment-lineage** stamp the
+substrate writes into a project. They are not the same number. `.memory-version` tracks the
+shared `agent-workflow` deployment lineage (head `1.3.0` today), **not** this package's
+version. A project bootstrapped by the kit's fallback carries a `.workflow-version`; when this
+substrate is later installed, `migrations/legacy-stamp-takeover.md` copies that value verbatim
+into `.memory-version` and never deletes the legacy stamp. See `migrations/README.md`.
+
+## What this package ships
+
+`SKILL.md` (procedure + ownership table), `references/` (templates + the deployable Node
+enforcement scripts + the setup contracts), `scripts/stamp-takeover.mjs` (the upgrade-time
+lineage state machine + tests), `migrations/`, `capability.json` (the family manifest), and
+this installer. It ships **no** family-wide tooling (the schema/validator are owned by the
+composition root) — preserving "knows nobody".
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/SKILL.md

@@ -0,0 +1,201 @@
+---
+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.0.0'
+---
+
+# agent-workflow-memory
+
+Deploys a **portable AI-agent memory substrate** into a project, and upgrades it as the
+substrate evolves. After it runs, any future agent (including a fresh session of yourself) can
+reconstruct project context in ~60 seconds, find the current task, and avoid repeating past
+mistakes.
+
+The substrate is **stack-agnostic memory** — `docs/ai/` structure, entry-point doc, session
+protocols, frontmatter caps, 3-tier archive, index-freshness gate. Enforcement ships as **Node
+`.mjs` scripts** (the reference implementation; non-Node stacks follow the same policy
+manually).
+
+This skill is the **memory layer** of the `agent-workflow` family. It **knows nobody else** in
+the family. In particular it does **not** own the **workflow methodology** (plan → execute →
+review vocabulary, lifecycle, `docs/plans/queue.md`, mandatory Cleanup, plan-then-execute) —
+that is injected into a delimited slot in `AGENTS.md` by the family **composition root**, never by
+this skill. (This substrate does not name or depend on any specific sibling — it only honours the
+slot contract.) This skill only ever ships the slot **empty** and **preserves** whatever is already
+in it on upgrade.
+
+The substrate **artifacts** (this skill, the templates, the deployed `docs/ai/` files) stay in
+their **source language** — for cross-agent and cross-team portability. That is separate from the
+**conversational language** chosen at bootstrap (which governs dialogue only, never file
+contents).
+
+---
+
+## Ownership table
+
+What this substrate owns vs what it only points at. The methodology pointer is the empty slot
+the composition root fills — never author methodology text here.
+
+| Concern | Owner | In the deployed `AGENTS.md` |
+|---|---|---|
+| Entry point, Memory Map, session protocols (Start / During / Complete) | **memory** (this skill) | authored from templates |
+| `docs/ai/` files, frontmatter caps, 3-tier archive, index-freshness gate | **memory** | `docs/ai/*` + scripts + hook |
+| Visibility / conversational-language / agent-attribution contracts | **memory** | the three `AGENTS.md` blocks |
+| 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 |
+
+---
+
+## Two modes
+
+Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to guard against
+bootstrapping over a live system, but the user makes the final call.
+
+- **`/agent-workflow-memory`** (default) — bootstrap a new or empty project. If `docs/ai/`
+  already exists, stop and ask whether they meant `upgrade`.
+- **`/agent-workflow-memory upgrade`** — upgrade an existing deployment.
+
+### Mode: bootstrap
+
+> Bundled sources below (templates, scripts) live in **this skill's own directory** —
+> `${CLAUDE_SKILL_DIR}/` in Claude Code, or the folder containing this `SKILL.md` elsewhere.
+> Use that as the copy/read source; the working directory is the **target project**.
+
+> The three setup questions (steps 2–4) are decisions only the user can make and are hard to
+> reverse after a commit. Ask each as a **structured multiple-choice prompt where supported**
+> (`AskUserQuestion` in Claude Code, recommended option first), otherwise in prose — and
+> **wait for the answer before writing anything**.
+
+1. **Recon (read-only).** Before writing anything: `package.json` / `pyproject.toml` / `go.mod`
+   / `Cargo.toml` → stack, package manager, scripts; `ls -la` root → README, existing
+   `AGENTS.md`/`CLAUDE.md`, CI / linter configs; `git log --oneline -30` + `git status`; `src/`
+   2–3 levels deep; tests + linter rules. Record stack, package manager, daily commands, layers.
+2. **Choose visibility — ASK explicitly and wait.** `visible` (committed — canonical,
+   recommended) or `hidden` (in-tree, hidden via `~/.gitignore_global`). See
+   [Visibility contract](references/contracts.md#visibility-contract).
+3. **Choose conversational language — ASK explicitly and wait.** Which language the agent
+   *talks to them* in. Offer the language they're already writing in as the default. Carry it
+   into the `{{COMM_LANGUAGE}}` slot of the *Communication language* block (step 5). See
+   [Communication contract](references/contracts.md#communication-contract). Dialogue only —
+   never the files.
+4. **Choose agent attribution — ASK explicitly and wait.** May the agent attribute work to
+   itself / AI — `Co-Authored-By` trailers, "Generated with …" footers, AI/agent/model mentions?
+   **Default `off`.** Carry it into `{{AGENT_ATTRIBUTION}}` (step 5). **If `off` and the project
+   uses Claude Code**, also set `"includeCoAuthoredBy": false` in the project's
+   `.claude/settings.json` (create it if absent). See
+   [Attribution contract](references/contracts.md#attribution-contract).
+5. **Entry-point doc.** If `AGENTS.md` / `CLAUDE.md` already exist (recon), do **not**
+   overwrite — show the user and ask whether to merge or replace. Otherwise create `AGENTS.md`
+   from `${CLAUDE_SKILL_DIR}/references/templates/AGENTS.md` and symlink `CLAUDE.md -> AGENTS.md`
+   (`ln -s AGENTS.md CLAUDE.md`). **Leave the `workflow:methodology` slot exactly as shipped —
+   empty.** Filling it is the composition root's job.
+6. **Deploy `docs/ai/`.** Create the files + `pages/` from
+   `${CLAUDE_SKILL_DIR}/references/templates/`. Keep each file's frontmatter.
+7. **Fill templates** per the table below.
+8. **Install enforcement (Node projects).** Copy `${CLAUDE_SKILL_DIR}/references/scripts/*.mjs`
+   (+ `*.test.mjs`) into the project's `scripts/`. **No Node runtime** → skip this + the hook;
+   follow the cap/archive/index policy manually.
+9. **Wire / hide** per visibility (see contract). Install the pre-commit hook (Node projects):
+   `node scripts/install-git-hooks.mjs`. If it reports a pre-existing non-marker hook, stop and
+   ask the user to merge it manually.
+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.0.0`). 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.**
+
+> **Delegated mode (invoked by the composition root) — applies to BOTH bootstrap and upgrade.**
+> When the family composition root drives this substrate as part of a family bootstrap **or
+> upgrade**, do the write steps (bootstrap 1–10 / upgrade 1–7: write `docs/ai/` + `AGENTS.md` +
+> `.memory-version`) but **do NOT** run **any** commit gate and **do NOT** ask to commit — the
+> composition root owns the **single** commit gate, raised after it injects the methodology slot.
+> The three setup answers and the target dir are passed in by the composition root; you perform no
+> commit and no slot injection. **Standalone** invocation keeps its own commit gate (bootstrap step
+> 11 / upgrade step 7).
+
+Fill strategy:
+
+| File | Strategy |
+|------|----------|
+| `current_state.md`, `architecture.md`, `env_commands.md`, `technical_specification.md`, `pages/index.md` | Fill with **real** recon data. |
+| `tech_reference.md` | Carry over real configs/patterns found in deps. |
+| `active_plan.md`, `handover.md` | TODO seed. |
+| `decisions.md` | Seed `AD-001` (adopting this memory system). |
+| `known_issues.md`, `changelog.md`, `pages/shared-patterns.md` | Empty template / first bootstrap entry. |
+
+### Mode: upgrade
+
+1. **Resolve the stamp.** Read `docs/ai/.memory-version`. If it is absent but a legacy
+   `docs/ai/.workflow-version` exists (a kit fallback bootstrap), run
+   `migrations/legacy-stamp-takeover.md` **first** — it copies that value verbatim into
+   `.memory-version` (and never deletes the legacy stamp). The pure state machine in
+   `scripts/stamp-takeover.mjs` decides the action per state; the Markdown migration is the
+   no-Node manual fallback. If **no** stamp exists at all, offer a conservative re-bootstrap.
+2. **Compare** the stamp to the **deployment-lineage head** (`LINEAGE_HEAD`, `1.3.0`). Equal →
+   report "up to date" and stop. **Greater than the head, or unparseable → STOP and report**
+   (never downgrade or guess).
+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**.
+5. Reconcile drift: add any substrate files/scripts the project is missing; **never clobber
+   project-authored content** (their `decisions.md`, `known_issues.md`, page specs stay). For a
+   pre-1.1.0 deployment with no *Communication language* block, ask + insert
+   (`migrations/1.1.0-communication-language.md`); pre-1.2.0 with no *Attribution* block, ask +
+   insert defaulting to `off` (`migrations/1.2.0-agent-attribution.md`).
+6. **Preserve the methodology slot.** If `AGENTS.md` has the `workflow:methodology` markers,
+   **never regenerate the file wholesale** — extract any bytes between the markers and reinsert
+   them unchanged. If the markers are absent (a legacy `AGENTS.md`), gracefully **no-op** on the
+   slot (adding the slot to already-deployed files is a separate methodology migration). On any
+   malformed marker state (single, reversed, nested, or duplicate pair), **no-op with an error**
+   — never edit.
+7. **Re-stamp** `docs/ai/.memory-version` to the lineage head (atomic write). Report changes;
+   **ask before committing** — **except in delegated mode** (see the *Delegated mode* note above),
+   where the composition root owns the single gate and this step raises none.
+
+---
+
+## Gotchas
+
+- **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.0.0`. They are independent axes.
+- **The methodology slot ships empty and stays the user's.** Never author methodology text into
+  it; on upgrade, preserve its content byte-for-byte. The composition root is its only writer.
+- **The `Co-Authored-By` trailer is added by the harness, not by prose.** When attribution is
+  `off` + Claude Code, also set `"includeCoAuthoredBy": false` in `.claude/settings.json`.
+- **Hidden mode must never touch `package.json`.** It also ignores `docs/ai/.memory-version`
+  (and any kit-fallback `.workflow-version`). After hiding, verify `git status` shows the
+  artifacts as ignored.
+- **`CLAUDE.md` is a symlink, not a copy.** `ln -s AGENTS.md CLAUDE.md`.
+- **Never overwrite an existing entry point or hook.** Stop and ask to merge vs replace.
+- **No Node runtime → skip enforcement** (scripts + hook); follow the policy manually.
+- **Never auto-commit.** Report quality-gate results and wait for explicit approval — both modes.
+
+---
+
+## Setup contracts
+
+The three setup choices each have a full contract in
+[`references/contracts.md`](references/contracts.md). Defaults: visibility = `visible`; language
+= whatever the user is already writing in; attribution = `off`.
+
+---
+
+## References
+
+- [`references/contracts.md`](references/contracts.md) — the three setup contracts in full.
+- [`references/templates/`](references/templates/) — stack-agnostic `AGENTS.md` (with the empty
+  methodology slot), `agent_rules.md`, and all `docs/ai/` files to deploy.
+- [`references/scripts/`](references/scripts/) — the Node enforcement scripts (caps + staleness +
+  index-freshness gate, 3-tier archive, hook installer) and their unit tests.
+- [`scripts/stamp-takeover.mjs`](scripts/stamp-takeover.mjs) — the upgrade-time lineage state
+  machine (`LINEAGE_HEAD`, atomic stamp writes) + tests.
+- [`migrations/`](migrations/) — per-version upgrade steps, incl. `legacy-stamp-takeover.md`;
+  see `migrations/README.md`.
+- [`capability.json`](capability.json) — the `agent-workflow` family manifest.
+- [`CHANGELOG.md`](CHANGELOG.md) — version history of this substrate.

package/bin/install.mjs

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+// One-shot installer for @sabaiway/agent-workflow-memory.
+//
+//   npx @sabaiway/agent-workflow-memory init
+//
+// Copies the memory substrate into the canonical skill home
+// (~/.claude/skills/agent-workflow-memory, override with --dir or
+// AGENT_WORKFLOW_MEMORY_DIR). Re-running refreshes the skill to this package's
+// version — that is how you upgrade the *skill files* themselves:
+//
+//   npx @sabaiway/agent-workflow-memory@latest init
+//
+// That is distinct from `/agent-workflow-memory upgrade`, which migrates a
+// *project's* docs/ai deployment — see README "Use".
+//
+// No telemetry, no phone-home. Dependency-free, Node >= 18.
+
+import { readFile, mkdir, readdir, copyFile, lstat, readlink, symlink } from 'node:fs/promises';
+import { existsSync, lstatSync } from 'node:fs';
+import { dirname, join, resolve, relative, sep, isAbsolute } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, '..');
+
+// The deployable skill = everything except the npm wrapper (package.json, bin/).
+// Enumerated explicitly (mirrors package.json "files") so a missing payload entry
+// is a loud failure, not a silent partial install.
+const PAYLOAD = [
+  'SKILL.md',
+  'README.md',
+  'CHANGELOG.md',
+  'LICENSE',
+  'capability.json',
+  'references',
+  'scripts',
+  'migrations',
+];
+
+const tildify = (path) => path.replace(homedir(), '~');
+
+const readVersion = async () => {
+  try {
+    const pkg = JSON.parse(await readFile(resolve(PKG_ROOT, 'package.json'), 'utf8'));
+    return pkg.version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+};
+
+// lstat without following symlinks; null when the path does not exist. Using lstat (not
+// existsSync, which FOLLOWS symlinks and so reports a *dangling* symlink as absent) is what
+// makes the guard below catch a dangling destination symlink too.
+const lstatNoFollow = (path) => {
+  try {
+    return lstatSync(path);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err; // EACCES/EIO etc. must NOT fail open (be read as "not a symlink")
+  }
+};
+
+// Symlink-traversal guard: refuse to write *through* any symlink at or above `dest`
+// within `root`. Walks `root` plus each existing path component down to `dest`; if the
+// root, an intermediate dir, or the leaf is a symlink (including a dangling one), a copy
+// could escape the target — STOP rather than follow it. Also refuses a dest outside `root`.
+const assertContainedRealPath = (root, dest) => {
+  const rel = relative(root, dest);
+  if (rel.startsWith('..') || isAbsolute(rel)) {
+    throw new Error(`[agent-workflow-memory] refusing to write outside the target dir: ${dest}`);
+  }
+  if (lstatNoFollow(root)?.isSymbolicLink()) {
+    throw new Error(`[agent-workflow-memory] refusing to install into a symlinked target dir: ${root}`);
+  }
+  const walk = (acc, part) => {
+    const cur = join(acc, part);
+    if (lstatNoFollow(cur)?.isSymbolicLink()) {
+      throw new Error(
+        `[agent-workflow-memory] refusing to write through a symlink at ${cur} (would escape ${root}).`,
+      );
+    }
+    return cur;
+  };
+  rel.split(sep).filter(Boolean).reduce(walk, root);
+};
+
+const copyRecursive = async (src, dest, root) => {
+  assertContainedRealPath(root, dest); // never write through a dest symlink (root/intermediate/leaf)
+  const stat = await lstat(src);
+  if (stat.isSymbolicLink()) {
+    if (existsSync(dest)) return; // additive: never delete/replace an existing entry
+    const linkTarget = await readlink(src);
+    await symlink(linkTarget, dest);
+  } else if (stat.isDirectory()) {
+    await mkdir(dest, { recursive: true });
+    const entries = await readdir(src);
+    await Promise.all(entries.map((entry) => copyRecursive(join(src, entry), join(dest, entry), root)));
+  } else {
+    await mkdir(dirname(dest), { recursive: true });
+    await copyFile(src, dest);
+  }
+};
+
+const parseArgs = (argv) => {
+  const dirFlag = argv.indexOf('--dir');
+  return {
+    help: argv.includes('--help') || argv.includes('-h'),
+    version: argv.includes('--version') || argv.includes('-v'),
+    dir: dirFlag >= 0 ? argv[dirFlag + 1] : undefined,
+  };
+};
+
+const resolveTarget = (dirArg) => {
+  if (dirArg) return resolve(dirArg);
+  if (process.env.AGENT_WORKFLOW_MEMORY_DIR) return resolve(process.env.AGENT_WORKFLOW_MEMORY_DIR);
+  return resolve(homedir(), '.claude/skills/agent-workflow-memory');
+};
+
+const printHelp = (version) => {
+  console.log(`agent-workflow-memory ${version}
+
+Usage:
+  npx @sabaiway/agent-workflow-memory init [--dir <path>]
+  npx @sabaiway/agent-workflow-memory --version
+  npx @sabaiway/agent-workflow-memory --help
+
+Installs/refreshes the memory substrate at ~/.claude/skills/agent-workflow-memory
+  (override with --dir <path> or AGENT_WORKFLOW_MEMORY_DIR). init is additive —
+  it never deletes your settings and never writes through a symlink.
+
+After install, invoke the skill in your agent, inside a project:
+  first time in the project  ->  /agent-workflow-memory
+  project already has it     ->  /agent-workflow-memory upgrade
+
+Re-running this npx command updates the skill's own files; /agent-workflow-memory
+upgrade then migrates a project's deployment to that version.`);
+};
+
+const main = async () => {
+  const version = await readVersion();
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) return printHelp(version);
+  if (args.version) return console.log(version);
+
+  const missing = PAYLOAD.filter((entry) => !existsSync(resolve(PKG_ROOT, entry)));
+  if (missing.includes('SKILL.md')) {
+    console.error('[agent-workflow-memory] package payload missing (no SKILL.md) — corrupt install?');
+    process.exit(1);
+  }
+  if (missing.length > 0) {
+    console.error(`[agent-workflow-memory] package payload incomplete — missing: ${missing.join(', ')}`);
+    process.exit(1);
+  }
+
+  const target = resolveTarget(args.dir);
+  const wasPresent = existsSync(resolve(target, 'SKILL.md'));
+  // If the target dir itself is a symlink (incl. dangling), refuse before writing through it.
+  // (copyRecursive re-checks per entry; this fails fast with a clear message.)
+  if (lstatNoFollow(target)?.isSymbolicLink()) {
+    console.error(`[agent-workflow-memory] target dir is a symlink — refusing to write through it: ${tildify(target)}`);
+    process.exit(1);
+  }
+  await mkdir(target, { recursive: true });
+  await Promise.all(
+    PAYLOAD.map((entry) => copyRecursive(resolve(PKG_ROOT, entry), resolve(target, entry), target)),
+  );
+  console.log(
+    `[agent-workflow-memory] ${wasPresent ? 'updated the substrate to' : 'installed'} v${version} -> ${tildify(target)}`,
+  );
+
+  console.log(`
+Next — open your agent inside a project and run the skill:
+  • first time in this project  ->  /agent-workflow-memory
+  • project already has it       ->  /agent-workflow-memory upgrade
+
+This command only installs/updates the skill itself (in ${tildify(target)}).
+To update it later, re-run:  npx @sabaiway/agent-workflow-memory@latest init`);
+};
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/bin/install.test.mjs

@@ -0,0 +1,76 @@
+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 } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+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',
+      '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');
+  });
+});

package/capability.json

@@ -0,0 +1,27 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "agent-workflow-memory",
+  "kind": "memory-substrate",
+  "version": "1.0.0",
+  "provides": ["context"],
+  "roles": {},
+  "detect": {
+    "installed": {
+      "env": "AGENT_WORKFLOW_MEMORY_DIR",
+      "default": "~/.claude/skills/agent-workflow-memory",
+      "file": "SKILL.md"
+    },
+    "deployed": {
+      "file": "docs/ai/.memory-version"
+    }
+  },
+  "install": { "npm": "@sabaiway/agent-workflow-memory" },
+  "uninstall": {
+    "removeResolved": "detect.installed",
+    "note": "init copies into the skill dir; uninstall removes the resolved detect.installed dir — not an npm dependency"
+  },
+  "cost": "none",
+  "quota": null,
+  "provenance": { "author": "sabaiway", "source": "github:sabaiway/agent-workflow" }
+}