@sabaiway/agent-workflow-memory 7.1.2 → 7.2.0

package/CHANGELOG.md

@@ -4,6 +4,29 @@ 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 `3.0.0`).
 
+## 7.2.0 — the standalone bootstrap offers enforcement on every project (AD-131)
+
+`SKILL.md` steps 8–9 no longer decide by the stack recon ("Node projects" / "No Node runtime → skip
+this + the hook"): the enforcement scripts + pre-commit hook are OFFERED on every project,
+preview-first, with a one-line why — the dependency-free Node scripts are available because the
+agent host already runs the skill-home navigator; the only skip condition is that the agent host
+cannot run them; the residual is stated (a committer without `node` on PATH gets the hook's own loud
+failure). On a yes the scripts are copied and the hook installed; on a no the docs command slots of
+`env_commands.md` and `AGENTS.md` carry a note (the caps + index gate run from the agent's own skill
+copy, the archive rotations need the scripts deployed) and never the skill's absolute path. The
+Gotchas bullet points at step 8; the "non-Node stacks follow the policy manually" claim is gone.
+
+**A declined offer leaves no false claim.** `references/contracts.md`'s visible bullet wires the
+`package.json` scripts only when one exists and the enforcement offer was accepted (the
+`.gitignore` either way); the seeded `templates/changelog.md`, `decisions.md` and `agent_rules.md`
+say `installed on a yes` / `where installed` instead of asserting an install; the README's use line
+says the same. The seed `adr/log.md` stays the generator's byte-exact output.
+
+**Two characterization pins, no script change.** `references/scripts/install-git-hooks.test.mjs`
+pins the hook marker's directory-basename fallback beside no or a malformed `package.json` (a named
+`package.json` wins); `archiver-structure.test.mjs` pins the same fallback in the archivers' headings
+through the copied four-file import closure. Mirrored byte-identically into the kit.
+
 ## 7.1.2 — the seed orchestration note names the fold slot (AD-125)
 
 `references/templates/orchestration.json`: the `_README` note lists `plan-authoring`'s third slot,

package/README.md

@@ -32,7 +32,7 @@ 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
+  `AGENTS.md`, offers the enforcement scripts + pre-commit hook (installed on a yes), and stamps
   `docs/ai/.memory-version`. The three pointer slots in `AGENTS.md` (the **methodology**,
   **orchestration** and **autonomy** pointers, filled later by the family composition root) are
   left **empty**.

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: '7.1.2'
+  version: '7.2.0'
 ---
 
 # agent-workflow-memory
@@ -14,9 +14,9 @@ reconstruct project context in ~60 seconds, find the current task, and avoid rep
 mistakes.
 
 The substrate is **stack-agnostic memory** — `docs/ai/` structure, entry-point doc, session
-protocols, frontmatter caps, one-file-per-ADR archive, index-freshness gate. Enforcement ships as **Node
-`.mjs` scripts** (the reference implementation; non-Node stacks follow the same policy
-manually).
+protocols, frontmatter caps, one-file-per-ADR archive, index-freshness gate. Enforcement ships as
+dependency-free **Node `.mjs` scripts** with a pre-commit hook, offered on every project because
+the agent host runs them.
 
 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** (the plan shape,
@@ -124,11 +124,22 @@ bootstrapping over a live system, but the user makes the final call.
    before reporting the deploy, since the navigator the entry point declares does not exist yet). The
    generator runs from the **skill home**, so a **No-Node target** is covered too: the operator's own
    host runs it, and step 8's copy is not a precondition.
-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
+8. **Offer enforcement on every project, preview-first.** Explain in one line that the
+   dependency-free Node scripts are available because the agent host already runs the skill-home
+   navigator; the only skip condition is that the agent host cannot run them. Preview the source
+   and destination list and ask; on a yes copy
+   `${CLAUDE_SKILL_DIR}/references/scripts/*.mjs` (+ `*.test.mjs`) into the project's `scripts/`.
+   On a no, skip the hook in step 9 and say so; the docs command slots then name no project-local
+   command — fill `env_commands.md` and the `Docs caps + index freshness` row of `AGENTS.md` with
+   the same note: the caps + index gate run from the agent's own skill copy (the step-7
+   `--root=<target>` form) and the archive rotations need the scripts deployed. Never write the
+   skill's absolute path into a deployed doc. They self-configure
+   (project name from `package.json` or, without one, the directory basename). The hook calls
+   `node scripts/<x>.mjs` directly, so a committer without `node` on PATH gets the hook's own loud
+   failure.
+9. **Wire / hide** per visibility (see contract). When the user accepts the enforcement offer,
+   install the pre-commit hook: `node scripts/install-git-hooks.mjs`. If it reports a pre-existing
+   non-marker hook, stop and
    ask the user to merge it manually. **Hidden** → add memory's own artifact paths (the canonical
    anchored list in the [Visibility contract](references/contracts.md#visibility-contract)) to the
    **project-local** `.git/info/exclude` (resolve via `git rev-parse --git-path info/exclude`),
@@ -162,7 +173,7 @@ Fill strategy:
 | `tech_reference.md` | Carry over real configs/patterns found in deps. |
 | `active_plan.md`, `handover.md` | TODO seed. |
 | `decisions.md` | The HOT ADR window — seed `AD-001` (adopting this memory system), newest at the bottom. |
-| `adr/log.md` | The seed navigator — deployed as-is (the generator over the seeded HOT); regenerated by `archive-decisions.mjs`, never hand-edited. |
+| `adr/log.md` | The seed navigator — deployed as-is (the generator over the seeded HOT); regenerated by `archive-decisions.mjs` where the enforcement scripts are deployed (installed on a yes), otherwise it stays the seed — never hand-edited either way. |
 | `known_issues.md`, `changelog.md`, `pages/shared-patterns.md` | Empty template / first bootstrap entry. |
 
 ### Mode: upgrade
@@ -333,7 +344,8 @@ memory substrate has none, so it relies on the STOP + the explicit ask — never
   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.
+- **Enforcement is offered on every project.** See step 8 for the preview, the agent-host
+  criterion, and the committer-node residual.
 - **Never auto-commit.** Report quality-gate results and wait for explicit approval — both modes.
 
 ---

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "7.1.2",
+  "version": "7.2.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",

package/references/contracts.md

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

package/references/scripts/archiver-structure.test.mjs

@@ -1,8 +1,9 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { readFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 // Structural pin (green by construction, a tripwire not a proof): all three archivers read
 // documents through the ONE shared tokenizer. A fourth archiver — or a future edit that reaches
@@ -12,6 +13,50 @@ import { fileURLToPath } from 'node:url';
 
 const DIR = dirname(fileURLToPath(import.meta.url));
 const ARCHIVERS = ['archive-changelog.mjs', 'archive-issues.mjs', 'archive-decisions.mjs'];
+const ARCHIVER_CLOSURE = ['archive-changelog.mjs', 'archive-issues.mjs', 'archive-caps.mjs', 'markdown-blocks.mjs'];
+const FIXED_DATE = '2026-09-02';
+const MALFORMED_PACKAGE_JSON = '{ not json';
+const NAMED_PACKAGE_JSON = '{"name":"named-fixture"}';
+const NAMED_FIXTURE = 'named-fixture';
+
+const buildArchiveHeadings = async (packageJson) => {
+  const root = mkdtempSync(join(tmpdir(), 'archiver-name-'));
+  const scripts = join(root, 'scripts');
+  mkdirSync(scripts);
+  for (const name of ARCHIVER_CLOSURE) cpSync(join(DIR, name), join(scripts, name));
+  if (packageJson !== null) writeFileSync(join(root, 'package.json'), packageJson);
+  const changelog = await import(pathToFileURL(join(scripts, 'archive-changelog.mjs')).href);
+  const issues = await import(pathToFileURL(join(scripts, 'archive-issues.mjs')).href);
+  const result = {
+    fallback: basename(root),
+    changelog: changelog.buildRecent([], FIXED_DATE),
+    issues: issues.buildResolvedFile(null, [], FIXED_DATE),
+  };
+  rmSync(root, { recursive: true, force: true });
+  return result;
+};
+
+const assertArchiveHeadings = (result, projectName) => {
+  assert.ok(result.changelog.includes(`# Changelog WARM Archive \u2014 ${projectName}`));
+  assert.ok(result.issues.includes(`# Resolved Issues \u2014 ${projectName}`));
+};
+
+describe('the archivers head their archives with the directory basename when no package.json, or a malformed one, names the project', () => {
+  it('no package.json names the directory basename', async () => {
+    const result = await buildArchiveHeadings(null);
+    assertArchiveHeadings(result, result.fallback);
+  });
+
+  it('a malformed package.json names the directory basename', async () => {
+    const result = await buildArchiveHeadings(MALFORMED_PACKAGE_JSON);
+    assertArchiveHeadings(result, result.fallback);
+  });
+
+  it('a named package.json wins', async () => {
+    const result = await buildArchiveHeadings(NAMED_PACKAGE_JSON);
+    assertArchiveHeadings(result, NAMED_FIXTURE);
+  });
+});
 
 describe('every archiver reads through the tokenizer — no raw scan survives', () => {
   for (const name of ARCHIVERS) {

package/references/scripts/install-git-hooks.test.mjs

@@ -8,12 +8,15 @@ import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync, cpSync, existsSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join, dirname, resolve } from 'node:path';
+import { basename, join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { spawnSync } from 'node:child_process';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const INSTALLER_SRC = join(HERE, 'install-git-hooks.mjs');
+const MALFORMED_PACKAGE_JSON = '{ not json';
+const NAMED_PACKAGE_JSON = '{"name":"named-fixture"}';
+const NAMED_FIXTURE = 'named-fixture';
 
 // The installer anchors ROOT at <its dir>/.. — deploy it into a fixture's scripts/ like a consumer.
 const mkProject = () => {
@@ -39,6 +42,33 @@ const hooksPathOf = (root) => {
   return resolve(root, r.stdout.trim());
 };
 
+const markerFor = (name) => `# ${name}:install-git-hooks.mjs`;
+const readHook = (root) => readFileSync(join(hooksPathOf(root), 'pre-commit'), 'utf8');
+
+describe('install-git-hooks \u2014 beside no package.json, or a malformed one, the marker names the directory basename', () => {
+  it('no package.json, then a MALFORMED one \u2014 the marker names the directory basename', () => {
+    const { root } = mkProject();
+    const expected = markerFor(basename(root));
+    const absent = runInstaller(root);
+    assert.equal(absent.status, 0, absent.stderr);
+    assert.ok(readHook(root).split('\n').includes(expected));
+    writeFileSync(join(root, 'package.json'), MALFORMED_PACKAGE_JSON);
+    const malformed = runInstaller(root);
+    assert.equal(malformed.status, 0, malformed.stderr);
+    assert.ok(readHook(root).split('\n').includes(expected));
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  it('a named package.json wins \u2014 the marker carries its name', () => {
+    const { root } = mkProject();
+    writeFileSync(join(root, 'package.json'), NAMED_PACKAGE_JSON);
+    const result = runInstaller(root);
+    assert.equal(result.status, 0, result.stderr);
+    assert.ok(readHook(root).split('\n').includes(markerFor(NAMED_FIXTURE)));
+    rmSync(root, { recursive: true, force: true });
+  });
+});
+
 describe('install-git-hooks — the hooks path comes from git plumbing (C7)', () => {
   it('a normal repo installs at the git-path hooks location', () => {
     const { root } = mkProject();

package/references/templates/agent_rules.md

@@ -39,7 +39,7 @@ Read in order, then confirm before starting:
 Before claiming "done":
 1. Run all quality gates (lint + type-check + tests) — all green.
 2. Update docs: `current_state.md` (feature ready), `changelog.md` (entry), `handover.md` (**REPLACE** the last-session block — session delta, never append; older deltas live in `changelog.md` → `history/`), `pages/<page>.md` (matches implementation), the governing spec (its revision lands with the code: `draft` -> `live` on the landing row). Only bump "Last Updated" when content actually changed.
-3. Run the docs cap-validator + index-freshness gate (pre-commit also enforces). On failure: trim the offending file, or run the changelog rotation if the offender is `changelog.md`.
+3. Run the docs cap-validator + index-freshness gate (the pre-commit hook also enforces it where installed). On failure: trim the offending file, or run the changelog rotation if the offender is `changelog.md`.
 4. If the work executed a plan file — complete it per the project's **planning skill / methodology** (the `workflow:methodology` slot in `AGENTS.md` points to it; see §5). Without completing that step the plan is not done. (The methodology, including any mandatory final cleanup, is defined there — not in this substrate.)
 5. **Ask before committing** (§4): report lint / type-check / test counts + docs status, then wait for explicit approval. DO NOT auto-commit.
 

package/references/templates/changelog.md

@@ -20,7 +20,7 @@ maxLines: 700
 **Changes:**
 - Created `AGENTS.md` (entry point) + `CLAUDE.md` symlink.
 - Created `docs/ai/` with the spec files + `pages/`.
-- Installed the docs cap-validator / index-freshness / archive scripts + pre-commit hook.
+- Offered the docs cap-validator / index-freshness / archive scripts + pre-commit hook (installed on a yes).
 - Recorded the real stack, scripts, and architecture into the relevant files.
 
 **Quality gates:** n/a (no code changes).

package/references/templates/decisions.md

@@ -13,7 +13,7 @@ maxLines: 500
 > consequences, newest at the bottom. Link related ADRs with `[[AD-XXX]]`; retrieval is by the
 > `AD-NNN` id (filename), grep over the flat store, or the `[[AD-NNN]]` supersession chain.
 
-> **Archive:** older ADRs are stored one immutable file per record under [`adr/`](./adr/) — see the active-set navigator [`adr/log.md`](./adr/log.md). `archive-decisions.mjs` explodes the oldest entries beyond this window automatically; no cap is ever raised and there is no monolithic ledger.
+> **Archive:** older ADRs are stored one immutable file per record under [`adr/`](./adr/) — see the active-set navigator [`adr/log.md`](./adr/log.md). `archive-decisions.mjs` explodes the oldest entries beyond this window automatically where the enforcement scripts are deployed (installed on a yes); no cap is ever raised and there is no monolithic ledger.
 
 ## AD-001 — Adopt AI-agent memory system (`docs/ai/`)
 
@@ -22,7 +22,7 @@ maxLines: 500
 
 **Context.** Multi-session AI work loses context between runs. Without a structured handover, each new session re-reads code, re-discovers decisions, and repeats past mistakes.
 
-**Decision.** Adopt a Memory Map in `AGENTS.md` (entry point — the cross-agent standard; tool aliases like `CLAUDE.md` symlink to it) + structured files under `docs/ai/`. Define three protocols (Start / During / Complete). Enforce frontmatter caps + index freshness + a one-file-per-ADR archive via a pre-commit hook. Deployed via the `agent-workflow-memory` substrate (standalone, or as part of the agent-workflow family).
+**Decision.** Adopt a Memory Map in `AGENTS.md` (entry point — the cross-agent standard; tool aliases like `CLAUDE.md` symlink to it) + structured files under `docs/ai/`. Define three protocols (Start / During / Complete). Enforce frontmatter caps + index freshness + a one-file-per-ADR archive via the deployed scripts + pre-commit hook (offered on every project, installed on a yes). Deployed via the `agent-workflow-memory` substrate (standalone, or as part of the agent-workflow family).
 
 **Rationale.** Single entry + structured spec files = constant boot-up cost regardless of project size. ADRs prevent litigating the same decision twice. `pages/<page>.md` keeps behaviour canonical (docs > assumptions). Caps + one-file-per-ADR archival keep every record scannable as the decision history grows without bound.