@sabaiway/agent-workflow-memory 1.0.0 → 1.1.1

package/CHANGELOG.md

@@ -4,6 +4,39 @@ All notable changes to the memory substrate. Versions are this **package's** npm
 they are distinct from the **deployment-lineage** stamp written into a project's
 `docs/ai/.memory-version` (which tracks the shared `agent-workflow` lineage, head `1.3.0`).
 
+## 1.1.1 — Installer hardening (Issue-004 parity)
+
+A patch release that applies the same two installer fixes shipped to the engine in 1.1.0, keeping the
+two identical family installers in lockstep.
+
+### Fixed
+- Containment check now accepts a legitimately-contained child literally named `..foo` (it wrongly
+  rejected anything starting with `..` before); `tildify` collapses only a **leading** `$HOME`, never
+  a mid-path occurrence (**Issue-004**).
+
+### Changed
+- The installer is importable without side effects (the `isDirectRun` guard) and exports its
+  path/format helpers for in-process tests. The installer's own + README bare `npx … init` strings now
+  use `@latest`.
+
+The deployment-lineage head stays **`1.3.0`** (no `docs/ai` structural change; no migration file).
+
+## 1.1.0 — Hidden mode writes project-local, not global, excludes
+
+Memory's **hidden** visibility now targets the **project-local** `.git/info/exclude` (its own footprint
+only — `/AGENTS.md`, `/CLAUDE.md`, `/docs/ai/`, the added `/scripts/*.mjs`, `/docs/plans/`, both
+`/.claude/settings*.json` — in canonical anchored form, idempotently), **never** the machine-global
+`core.excludesFile`. Hiding a deployment no longer affects every other repo on the host (visibility is
+a project setting). This is a **docs/prose** release (memory's hide was always prose-driven; no new
+executable code); the tested superset path is the family composition root's hide tool, which absorbs
+memory's project-local lines into one canonical managed block and adds the external footprint. The
+deployment-lineage head stays **`1.3.0`** (no `docs/ai` structural change; no migration file).
+
+### Changed
+- `references/contracts.md` Visibility contract + `SKILL.md` step 9 retarget the hide to project-local.
+- The upgrade flow moves an older machine-global hide to project-local — **after** the never-downgrade
+  gate and **before** the equal-head short-circuit, so even an at-head hidden deployment is migrated.
+
 ## 1.0.0
 
 Initial standalone release. The **memory substrate** extracted into its own package as Plan 1

package/README.md

@@ -17,7 +17,7 @@ into a delimited slot in `AGENTS.md` by the family composition root, not by this
 ## Install
 
 ```bash
-npx @sabaiway/agent-workflow-memory init
+npx @sabaiway/agent-workflow-memory@latest init
 ```
 
 Installs/refreshes the skill at `~/.claude/skills/agent-workflow-memory` (override with

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-memory
 description: Deploy or upgrade a portable AI-agent memory substrate in any project — an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) and a structured `docs/ai/` context store with cap/archive/index enforcement. Use when the user wants to bootstrap `docs/ai/`, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-memory` / `/agent-workflow-memory upgrade`. Triggers on "set up the memory system", "deploy the AI memory here", "bootstrap docs/ai", "upgrade the memory substrate". This is the substrate only — the workflow methodology (plan→execute→review, queue, Cleanup) is owned elsewhere and injected into AGENTS.md by the family composition root.
 disable-model-invocation: true
 metadata:
-  version: '1.0.0'
+  version: '1.1.1'
 ---
 
 # agent-workflow-memory
@@ -73,7 +73,8 @@ bootstrapping over a live system, but the user makes the final call.
    `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
+   recommended) or `hidden` (in-tree, git-ignored via the **project-local** `.git/info/exclude` —
+   never the machine-global excludes). 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
@@ -99,11 +100,15 @@ bootstrapping over a live system, but the user makes the final call.
    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.
+   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`),
+   append-only (never duplicate an existing line), then **verify `git status` shows them ignored**.
+   Never the machine-global excludes; never edit `package.json`.
 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
+    lineage, **not** this package's npm version (`1.1.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.**
@@ -135,9 +140,22 @@ Fill strategy:
    `.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).
+2. **Never-downgrade gate FIRST, then the stamp-independent hidden-mode reconcile (D14).** Compare the
+   stamp to the **deployment-lineage head** (`LINEAGE_HEAD`, `1.3.0`). **Greater than the head, or
+   unparseable → STOP and report immediately, before ANY write** (never downgrade or guess, and never
+   touch `.git/info/exclude`). Otherwise (stamp **≤ head**) reconcile the hidden-mode footprint — but
+   first **infer this deployment's OWN visibility from its git state** (NOT from whether the machine-global
+   excludes list these paths — another repo on the host may have added them): if `AGENTS.md` (or
+   `docs/ai/`) is **tracked / committed** → **VISIBLE** → do nothing (never write `.git/info/exclude`);
+   if it is **untracked AND currently git-ignored** → **HIDDEN** → move memory's own footprint to the
+   **project-local** `.git/info/exclude` (the canonical anchored list from the Visibility contract,
+   append-only and idempotent — a clean re-run changes nothing), leaving the machine-global lines for the
+   user to remove (in a family upgrade the composition root's hide tool detects + reports that residual
+   block and removes it only after the user's explicit consent — never by default); if it is
+   **untracked AND not ignored** → **AMBIGUOUS** → **ASK** the user before writing. This visibility check
+   runs on **every** in-range upgrade, even at head — it is not gated by the stamp delta, but it is gated
+   **behind** the never-downgrade STOP above. **Then**, if the stamp **equals** the head → report "up to
+   date" (plus any footprint move just made) and stop.
 3. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` context (entries newer than the stamp).
 4. Apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those
    newer than the stamp. Migrations are **idempotent**.
@@ -163,13 +181,15 @@ Fill strategy:
 - **Source vs target directory.** Templates/scripts are read from the skill's own dir; the
   **working directory is the target project** — never write substrate files back into the skill.
 - **Stamp = lineage head, not package version.** `.memory-version` carries `1.3.0` (the shared
-  `agent-workflow` lineage), not the npm `1.0.0`. They are independent axes.
+  `agent-workflow` lineage), not the npm `1.1.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
+- **Hidden mode is project-local, never machine-global.** Memory's hide writes to the repo's
+  `.git/info/exclude` (one per-project ignore list), never `core.excludesFile`. `/docs/ai/`
+  subsumes `docs/ai/.memory-version` (and any kit-fallback `.workflow-version`) — list neither
+  separately. **Never touch `package.json`.** 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.

package/bin/install.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // One-shot installer for @sabaiway/agent-workflow-memory.
 //
-//   npx @sabaiway/agent-workflow-memory init
+//   npx @sabaiway/agent-workflow-memory@latest init
 //
 // Copies the memory substrate into the canonical skill home
 // (~/.claude/skills/agent-workflow-memory, override with --dir or
@@ -16,7 +16,7 @@
 // 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 { existsSync, lstatSync, realpathSync } from 'node:fs';
 import { dirname, join, resolve, relative, sep, isAbsolute } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
@@ -38,7 +38,11 @@ const PAYLOAD = [
   'migrations',
 ];
 
-const tildify = (path) => path.replace(homedir(), '~');
+// Collapse only a LEADING homedir() to "~" — anchored at the string start (boundary-checked with
+// `sep`), never a mid-path occurrence. A naive `path.replace(homedir(), '~')` would rewrite the
+// first match anywhere in the path (Issue-004). Exported so the regression can pin it in-process.
+export const tildify = (path) =>
+  path === homedir() ? '~' : path.startsWith(homedir() + sep) ? `~${path.slice(homedir().length)}` : path;
 
 const readVersion = async () => {
   try {
@@ -65,9 +69,12 @@ const lstatNoFollow = (path) => {
 // 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) => {
+export const assertContainedRealPath = (root, dest) => {
   const rel = relative(root, dest);
-  if (rel.startsWith('..') || isAbsolute(rel)) {
+  // A true escape is `..` exactly or a `..`-prefixed PATH SEGMENT (`../x`) — NOT any string starting
+  // with the two chars "..": a legitimately-contained child literally named `..foo` has rel `..foo`,
+  // which the old `rel.startsWith('..')` wrongly rejected (Issue-004).
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
     throw new Error(`[agent-workflow-memory] refusing to write outside the target dir: ${dest}`);
   }
   if (lstatNoFollow(root)?.isSymbolicLink()) {
@@ -121,7 +128,7 @@ const printHelp = (version) => {
   console.log(`agent-workflow-memory ${version}
 
 Usage:
-  npx @sabaiway/agent-workflow-memory init [--dir <path>]
+  npx @sabaiway/agent-workflow-memory@latest init [--dir <path>]
   npx @sabaiway/agent-workflow-memory --version
   npx @sabaiway/agent-workflow-memory --help
 
@@ -179,7 +186,23 @@ 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);
-});
+// Run main() only when executed directly (npx / node bin/install.mjs), never on import — so tests can
+// import this module to unit-test its exported helpers with no side effects. Compare by REAL path:
+// npx invokes the bin through a node_modules/.bin symlink, so process.argv[1] is that symlink while
+// import.meta.url is the resolved real file — a raw string compare reads them as different and main()
+// never runs. realpathSync collapses the symlink so both sides match. (Same idiom as the kit.)
+const isDirectRun = (() => {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  try {
+    return realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+if (isDirectRun) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/bin/install.test.mjs

@@ -3,9 +3,10 @@ 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';
+import { tmpdir, homedir } from 'node:os';
+import { dirname, join, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { assertContainedRealPath, tildify } from './install.mjs';
 
 const INSTALLER = join(dirname(fileURLToPath(import.meta.url)), 'install.mjs');
 const runInstaller = (target) => spawnSync(process.execPath, [INSTALLER, '--dir', target], { encoding: 'utf8' });
@@ -74,3 +75,35 @@ describe('memory installer — payload + symlink-traversal hardening', () => {
     assert.deepEqual(await readdir(real), [], 'nothing should be written through the symlinked target');
   });
 });
+
+describe('memory installer — Issue-004 regressions (exported helpers, in-process)', () => {
+  it('assertContainedRealPath accepts a contained child literally named "..foo"', () => {
+    const root = join(tmpdir(), 'aw-mem-contain-root');
+    assert.doesNotThrow(() => assertContainedRealPath(root, join(root, '..foo')));
+  });
+
+  it('assertContainedRealPath rejects a true `../` escape', () => {
+    const root = join(tmpdir(), 'aw-mem-contain-root');
+    assert.throws(() => assertContainedRealPath(root, join(root, '..', 'escape')), /outside the target dir/);
+  });
+
+  it('tildify collapses only a LEADING homedir, never a mid-path occurrence', () => {
+    assert.equal(tildify(`${homedir()}${sep}skills${sep}x`), `~${sep}skills${sep}x`, 'leading home → ~');
+    const midPath = `${sep}tmp${homedir()}${sep}x`;
+    assert.equal(tildify(midPath), midPath, 'a mid-path home occurrence is left untouched');
+  });
+});
+
+describe('memory installer — module hygiene', () => {
+  it('importing install.mjs runs nothing (main() is guarded by isDirectRun)', () => {
+    const url = JSON.stringify(pathToFileURL(INSTALLER).href);
+    const res = spawnSync(
+      process.execPath,
+      ['--input-type=module', '-e', `import(${url}).then(() => console.log('IMPORT_OK'));`],
+      { encoding: 'utf8' },
+    );
+    assert.equal(res.status, 0, res.stderr);
+    assert.match(res.stdout, /IMPORT_OK/);
+    assert.doesNotMatch(res.stdout, /installed v|updated the substrate/);
+  });
+});

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "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
 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.
+- **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.)*
 
 Not in this version: a fully-external hidden mode (artifacts relocated outside the repo tree).
 Deferred to a later release + migration.