@sabaiway/agent-workflow-memory 1.0.0

package/migrations/1.1.0-communication-language.md

@@ -0,0 +1,51 @@
+# Migration 1.1.0-communication-language
+
+**From:** versions < 1.1.0   **To:** 1.1.0
+
+## Why
+
+1.1.0 adds a **conversational language** setting: the language the agent *talks to the
+user* in (questions, explanations, summaries, status). It is recorded in a *Communication
+language* block in the project's `AGENTS.md` so every agent that reads the entry point
+honours it instead of drifting between languages. Pre-1.1.0 deployments have no such block.
+
+Scope is **dialogue only** — code, identifiers, paths, commands, log output, and
+abbreviations stay in their source language, and the `docs/ai/` files + `AGENTS.md` are not
+translated either. This migration changes *one* doc block, nothing else.
+
+## Steps
+
+1. Open the project's entry point `AGENTS.md` (the real file; `CLAUDE.md` is a symlink to it).
+2. **Idempotency check** — if it already contains a `## 🗣️ Communication language` heading,
+   this migration is done; skip to Verification.
+3. **Ask the user** which language the agent should converse in (questions, explanations,
+   summaries, status). Offer the language they're already writing in as the default.
+4. Insert this block immediately **after the opening blockquote** (before `## 🧭 Memory Map`),
+   replacing `<their language>` with the answer from step 3:
+
+   ```markdown
+   ---
+
+   ## 🗣️ Communication language
+
+   > **Talk to the user in <their language>** — every question, explanation, summary, and status update.
+   > Keep code, identifiers, file paths, shell commands, log output, and abbreviations in their **source language** — translating them breaks copy-paste, search, and tooling.
+   > This sets the **dialogue** language only — it does not translate the files in `docs/ai/` or this entry point, which stay in their source language (for cross-agent / cross-team portability).
+   ```
+
+5. Keep `AGENTS.md` within its ≤100-line budget (the block is ~6 lines; it fits). Do **not**
+   touch any other section, and do **not** translate existing file contents.
+
+## Verification
+
+- `AGENTS.md` has exactly one `## 🗣️ Communication language` block, with a real language in
+  place of `<their language>` (no leftover `{{COMM_LANGUAGE}}` placeholder).
+- The docs cap-validator is still green (`node scripts/check-docs-size.mjs` for Node projects)
+  — the entry point did not bust its line budget.
+- From now on the agent's replies are in the chosen language; paths/commands/identifiers
+  remain in their source language.
+
+## Rollback
+
+Delete the inserted `## 🗣️ Communication language` block (and its trailing `---`) from
+`AGENTS.md`. No other files were changed.

package/migrations/1.2.0-agent-attribution.md

@@ -0,0 +1,57 @@
+# Migration 1.2.0-agent-attribution
+
+**From:** versions < 1.2.0   **To:** 1.2.0
+
+## Why
+
+1.2.0 makes **agent attribution opt-in**. The agent may attribute work to itself / AI —
+`Co-Authored-By` trailers, "Generated with …" footers, AI/agent/model mentions in code,
+comments, commit messages, PR titles/bodies, branch names, or docs — **only if the user
+allows it**. Default is `off`. The choice is recorded in an *Attribution* block in the
+project's `AGENTS.md`; pre-1.2.0 deployments have no such block.
+
+A single `Co-Authored-By` trailer is enough to list an AI as a repo contributor, and GitHub
+keeps it permanently via PR refs — so the safe default is "no mention anywhere".
+
+## Steps
+
+1. Open the project's entry point `AGENTS.md` (the real file; `CLAUDE.md` is a symlink to it).
+2. **Idempotency check** — if it already contains a `## ✍️ Attribution` heading, skip to Verification.
+3. **Ask the user**: may the agent attribute work to itself / AI anywhere (commits, PRs, code,
+   comments, docs)? **Default to `off`** unless they opt in.
+4. Insert this block immediately **after the *Communication language* block** (or, if that is
+   absent, after the opening blockquote — before `## 🧭 Memory Map`), replacing `<off|on>` with
+   the answer from step 3:
+
+   ```markdown
+   ---
+
+   ## ✍️ Attribution
+
+   > **Agent attribution: <off|on>** (chosen at setup).
+   > **off** → never attribute work to the agent, AI, or the model: no `Co-Authored-By` trailers, no "Generated with …" footers, no AI/agent/model mentions in code, comments, commit messages, PR titles/bodies, branch names, or docs. Author everything as the human.
+   > **on** → the agent may add its standard `Co-Authored-By` trailer / footer per your tooling defaults.
+   > Claude Code also honours `includeCoAuthoredBy` in `.claude/settings.json`; this block binds every agent for everything written by hand.
+   ```
+
+5. **If the answer is `off` and the project uses Claude Code**, also set the harness flag so the
+   automatic trailer stops (a doc directive cannot stop a harness-added trailer):
+   - Ensure `.claude/settings.json` exists in the project root; create it as `{}` if absent.
+   - Set `"includeCoAuthoredBy": false` (merge into the existing JSON; do not clobber other keys).
+   - For other tools, disable their equivalent co-author / footer setting if present.
+6. Keep `AGENTS.md` within its ≤100-line budget (the block is ~7 lines; it fits). Do **not**
+   retroactively rewrite existing git history here — that is a separate, deliberate operation.
+
+## Verification
+
+- `AGENTS.md` has exactly one `## ✍️ Attribution` block, with `off` or `on` (no leftover
+  `{{AGENT_ATTRIBUTION}}` placeholder).
+- If `off` + Claude Code: `.claude/settings.json` contains `"includeCoAuthoredBy": false`, and
+  the file is valid JSON (`node -e "JSON.parse(require('fs').readFileSync('.claude/settings.json'))"`).
+- The docs cap-validator is still green (`node scripts/check-docs-size.mjs` for Node projects).
+
+## Rollback
+
+Delete the inserted `## ✍️ Attribution` block (and its trailing `---`) from `AGENTS.md`, and
+remove the `includeCoAuthoredBy` key from `.claude/settings.json` if you added it. No other
+files were changed.

package/migrations/README.md

@@ -0,0 +1,46 @@
+# Migrations
+
+Each upgrade step is one file: `migrations/<version>-<slug>.md`, where `<version>` is the
+skill release that introduced the change (matches a `CHANGELOG.md` heading) and `<slug>`
+is a short kebab-case name. Empty until the first change that needs migrating — most
+releases add files/templates, which `upgrade` reconciles without a migration.
+
+## How `upgrade` applies them
+
+1. Read the project's stamped version from `docs/ai/.memory-version` (the deployment-lineage
+   stamp owned by this substrate). On a deployment that has only the legacy `docs/ai/.workflow-version`
+   (a kit fallback bootstrap), `legacy-stamp-takeover.md` runs first and copies that value into
+   `.memory-version` verbatim — see that migration.
+2. Select every migration whose `<version>` is **strictly newer** than the stamp.
+3. Apply them in **ascending semver order**.
+4. Re-stamp `docs/ai/.memory-version` to the deployment-lineage head (`1.3.0` today — the shared
+   lineage sequence, **not** this package's npm version). The legacy `.workflow-version`, if present,
+   is never deleted.
+
+## Authoring rules
+
+- **Idempotent** — safe to re-run; check before mutating (e.g. "if the file already has X, skip").
+- **Non-destructive** — never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs). Add/rename/restructure only what the kernel owns.
+- **Self-contained** — exact paths + commands, readable cold, like a mini-plan.
+- **Mention rollback** — note how to undo if the step is risky.
+
+## Template
+
+```markdown
+# Migration <version>-<slug>
+
+**From:** versions < <version>   **To:** <version>
+
+## Why
+<what changed in the kernel and why a project needs to follow>
+
+## Steps
+1. <exact, idempotent action with paths/commands>
+2. ...
+
+## Verification
+<how to confirm the project is now consistent — e.g. docs cap-validator green>
+
+## Rollback
+<how to undo, or "n/a — additive only">
+```

package/migrations/legacy-stamp-takeover.md

@@ -0,0 +1,72 @@
+# Migration legacy-stamp-takeover
+
+**From:** a deployment stamped only with the legacy `docs/ai/.workflow-version` (a kit-fallback
+bootstrap, or a pre-extraction kit deployment)   **To:** the memory substrate's
+`docs/ai/.memory-version`
+
+This is the **no-Node manual fallback** for `scripts/stamp-takeover.mjs`. The script is the
+source of truth (pure state machine + atomic writes, unit-tested per row); this file documents
+the same table so a non-Node project can do it by hand. Run it **first** in `upgrade`, before
+any other migration.
+
+## Why
+
+The deployment stamp moved from `.workflow-version` (owned by the kit) to `.memory-version`
+(owned by this substrate). They track the **same** shared deployment-lineage sequence — never
+their package versions. The current lineage head is **`1.3.0`** (`LINEAGE_HEAD`). This migration
+adopts an existing legacy stamp into the new file **without** changing the lineage value and
+**without** deleting the legacy stamp (both may coexist; each tool migrates from its own stamp).
+
+## State table (idempotent)
+
+Look at `docs/ai/` and act by row. `V` is the legacy stamp's value; `head` = `1.3.0`.
+
+| `docs/ai/` state | Action |
+|---|---|
+| only `.workflow-version=V` | copy `V` **verbatim** → `.memory-version`; **leave** `.workflow-version`; then apply only memory migrations `> V` |
+| both `.memory-version` and `.workflow-version` | **no-op** for takeover; migrate from `.memory-version` |
+| only `.memory-version` | no takeover; migrate from it |
+| no stamp | conservative re-bootstrap offer (existing behaviour) |
+| any present stamp unparseable, or `> head` (future) | **STOP and report** — never downgrade or guess |
+
+## Steps (manual)
+
+1. **Inspect** the two files. Distinguish *absent* (the file does not exist) from a *read failure*
+   (it exists but `cat` fails — permission/I/O): only absence is "no stamp"; a read failure must
+   **STOP** (don't treat it as absent):
+   ```bash
+   for f in docs/ai/.memory-version docs/ai/.workflow-version; do
+     if [ ! -e "$f" ]; then echo "$f: (absent)";
+     elif v=$(cat "$f"); then echo "$f: $v";
+     else echo "$f: READ FAILED — STOP and report"; exit 1; fi
+   done
+   ```
+2. **Validate** each value that exists: it must be `MAJOR.MINOR.PATCH`, non-empty, and **not** greater
+   than `1.3.0`. If any present stamp is empty, unparseable, or in the future → **STOP and report**;
+   do nothing else.
+3. **Apply** the matching row above. For the "only `.workflow-version=V`" row, copy verbatim and
+   write **atomically** — create an exclusive randomized temp in `docs/ai/` (so a planted temp-name
+   symlink can't be followed), then `mv` it over the target:
+   ```bash
+   v=$(cat docs/ai/.workflow-version)
+   tmp=$(mktemp docs/ai/.memory-version.XXXXXX) && printf '%s\n' "$v" > "$tmp" && mv "$tmp" docs/ai/.memory-version
+   ```
+4. Continue the normal `upgrade` flow: apply memory migrations strictly newer than the resolved
+   stamp, then re-stamp `.memory-version` to the lineage head.
+
+Node projects do all of this in one call — pass the project's `docs/ai` directory:
+```bash
+node "${CLAUDE_SKILL_DIR}/scripts/stamp-takeover.mjs" docs/ai   # runs applyTakeover() on docs/ai
+```
+
+## Verification
+
+- `docs/ai/.memory-version` exists and equals the resolved lineage value (a single semver line,
+  trailing newline). `docs/ai/.workflow-version`, if it existed, is **unchanged**.
+- Re-running this migration changes nothing (idempotent).
+- No `.memory-version.tmp-*` files remain in `docs/ai/`.
+
+## Rollback
+
+Delete `docs/ai/.memory-version` (the legacy `.workflow-version` was never modified). No other
+files were changed.

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@sabaiway/agent-workflow-memory",
+  "version": "1.0.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",
+    "ai-coding",
+    "coding-agent",
+    "llm",
+    "ai-tools",
+    "claude-code",
+    "codex",
+    "cursor",
+    "agents-md",
+    "agent-memory",
+    "context-engineering",
+    "cross-agent",
+    "memory",
+    "developer-tools"
+  ],
+  "homepage": "https://github.com/sabaiway/agent-workflow#readme",
+  "bugs": {
+    "url": "https://github.com/sabaiway/agent-workflow/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sabaiway/agent-workflow.git",
+    "directory": "agent-workflow-memory"
+  },
+  "license": "MIT",
+  "author": "sabaiway",
+  "type": "module",
+  "bin": {
+    "agent-workflow-memory": "bin/install.mjs"
+  },
+  "files": [
+    "bin/",
+    "SKILL.md",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "capability.json",
+    "references/",
+    "scripts/",
+    "migrations/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/references/contracts.md

@@ -0,0 +1,62 @@
+# Setup contracts
+
+The three choices the bootstrap makes with the user — **visibility**, **conversational
+language**, and **agent attribution** — each have a contract below. `SKILL.md` links here so the
+main procedure stays lean; load this file when you need the full rule for a contract (e.g. while
+filling the matching `AGENTS.md` block, or when an `upgrade` migration touches it).
+
+Ask each as a **structured multiple-choice prompt where your agent supports it** (`AskUserQuestion`
+in Claude Code), otherwise in prose — and always wait for the answer before writing.
+
+---
+
+## Visibility contract
+
+The user chooses at bootstrap whether the AI artifacts are visible in the repo or hidden — an
+**explicit up-front question** (bootstrap step 2), never an assumed default. The two modes then
+diverge:
+
+- **visible** — artifacts are committed. Wire the project's `package.json` scripts (`docs:check` / `docs:index` / `docs:index:check` / `docs:archive` / `docs:archive:check` / `docs:archive:issues` / `docs:archive:issues:check` / `prepare: node scripts/install-git-hooks.mjs`) and add a minimal `.gitignore` (`docs/plans/`, `.claude/settings.local.json`). This is the canonical model.
+- **hidden** (in-tree) — same files on disk, but the repo "looks normal": append the artifact paths (`AGENTS.md`, `CLAUDE.md`, `docs/ai/`, `docs/plans/`, `scripts/*.mjs` you added, `docs/ai/.memory-version`, and — if a kit fallback bootstrap stamped one — `docs/ai/.workflow-version`) to the global excludes file git **already uses** (`git config --get core.excludesFile`); if none is set, point it at `~/.gitignore_global` (`git config --global core.excludesFile ~/.gitignore_global`) and append there. **Verify `git status` shows the artifacts as ignored** afterwards. **Do not edit `package.json`** — that is a tracked change and would leak; the pre-commit hook (always untracked in `.git/hooks/`) calls the scripts via `node scripts/<x>.mjs` directly.
+
+Not in this version: a fully-external hidden mode (artifacts relocated outside the repo tree).
+Deferred to a later release + migration.
+
+---
+
+## Communication contract
+
+The user chooses at bootstrap (step 3) which language the agent **talks to them** in. The choice is
+recorded in the *Communication language* block of the project's `AGENTS.md`, so every agent that
+reads the entry point honours it — and stops drifting between languages mid-session.
+
+Scope — **dialogue only**:
+
+- **In the chosen language** — everything the agent produces *for the user to read*: questions, explanations, plan summaries, status updates, commit-message prose if asked, review notes.
+- **Always in their source language** — code, identifiers, file paths, shell commands, log/console output, error strings, config keys, and abbreviations/acronyms. Translating these breaks copy-paste, search, and tooling.
+- **Files aren't translated** — the deployed `docs/ai/` files, `AGENTS.md`, and this kernel stay in their source language regardless of the chosen language (cross-agent / cross-team portability). The conversational language is about the *chat*, not the *artifacts*.
+
+Default to the language the user is already writing in; confirm rather than assume. On `upgrade`, a
+pre-1.1.0 deployment with no block gets one (the agent asks).
+
+---
+
+## Attribution contract
+
+The user chooses at bootstrap (step 4) whether the agent may **attribute work to itself or to AI**.
+The choice is recorded in the *Attribution* block of the project's `AGENTS.md`, so every agent that
+reads the entry point honours it. **Default is `off`** — people are routinely surprised to find an
+AI listed as a repo contributor (a `Co-Authored-By` trailer is enough to do it), so opt-in, never
+opt-out.
+
+When attribution is **`off`**, no mention of the agent, AI, or the model appears **anywhere**:
+
+- **No `Co-Authored-By` trailers** and **no "Generated with …" footers** on commits or PRs.
+- **No AI/agent/model references** in code, comments, commit messages, PR titles/bodies, branch names, or `docs/` prose. The work reads as the human author's.
+- **Two enforcement layers** — the *Attribution* block binds everything an agent writes **by hand**; the automatic `Co-Authored-By` trailer is added by the **harness**, not the prose, so for **Claude Code** the bootstrap also sets `"includeCoAuthoredBy": false` in the project's `.claude/settings.json`. Other tools: disable their equivalent co-author/footer setting if present.
+
+When **`on`**, the agent may add its standard trailer / footer per the user's tooling defaults. This
+block is about *attribution*, not authorship of the actual changes — quality, tests, and the "ask
+before commit" rule are unchanged either way.
+
+On `upgrade`, a pre-1.2.0 deployment with no block gets one (the agent asks, defaulting to `off`).

package/references/scripts/_expect-shim.mjs

@@ -0,0 +1,41 @@
+// Minimal dependency-free `expect` shim mapping the Vitest matchers used by the
+// kernel's *.test.mjs onto node:assert, so the suite runs under `node --test` with
+// zero dependencies. Supports only the matchers these tests use.
+import assert from 'node:assert/strict';
+
+const has = (actual, expected) => {
+  if (typeof actual === 'string') return actual.includes(expected);
+  if (Array.isArray(actual)) return actual.includes(expected);
+  return false;
+};
+
+const matchers = (actual, negate) => ({
+  toBe: (expected) =>
+    negate ? assert.notStrictEqual(actual, expected) : assert.strictEqual(actual, expected),
+  toEqual: (expected) =>
+    negate ? assert.notDeepStrictEqual(actual, expected) : assert.deepStrictEqual(actual, expected),
+  toContain: (expected) =>
+    assert.ok(
+      negate ? !has(actual, expected) : has(actual, expected),
+      `expected ${JSON.stringify(actual)} ${negate ? 'not ' : ''}to contain ${JSON.stringify(expected)}`,
+    ),
+  toMatch: (re) => (negate ? assert.doesNotMatch(actual, re) : assert.match(actual, re)),
+  toHaveLength: (n) =>
+    negate ? assert.notStrictEqual(actual.length, n) : assert.strictEqual(actual.length, n),
+  toBeNull: () => (negate ? assert.notStrictEqual(actual, null) : assert.strictEqual(actual, null)),
+  toBeInstanceOf: (Ctor) =>
+    assert.ok(
+      negate ? !(actual instanceof Ctor) : actual instanceof Ctor,
+      `expected value ${negate ? 'not ' : ''}to be instance of ${Ctor.name}`,
+    ),
+  toBeGreaterThan: (n) =>
+    assert.ok(negate ? !(actual > n) : actual > n, `expected ${actual} ${negate ? 'not ' : ''}> ${n}`),
+  toBeLessThan: (n) =>
+    assert.ok(negate ? !(actual < n) : actual < n, `expected ${actual} ${negate ? 'not ' : ''}< ${n}`),
+});
+
+export const expect = (actual) => {
+  const api = matchers(actual, false);
+  api.not = matchers(actual, true);
+  return api;
+};