@sabaiway/agent-workflow-memory 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -4,6 +4,35 @@ 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.2 — Entry-point template headroom for the orchestration pointer
+
+A **docs/prose** release (no new executable, the `1.1.1`/`1.9.1` precedent). The bundled entry-point
+template (`references/templates/AGENTS.md`) ships a second empty marker pair — `workflow:orchestration`,
+right under the methodology pair — which the family **composition root** fills live from the methodology
+engine on deploy. To keep the deployed `AGENTS.md` inside its ≤100-line budget with **both** pointers
+filled, the template trimmed non-essential slack (the Hard-Constraints intro blockquote + one
+illustrative row a deploying agent adapts anyway). No behaviour change; the composition root remains the
+only writer of the slots.
+
+The deployment-lineage head stays **`1.3.0`** (no `docs/ai` structural change; no migration file).
+
+## 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

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
@@ -33,10 +33,11 @@ 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**.
+  `docs/ai/.memory-version`. The two pointer slots in `AGENTS.md` (the **methodology** and
+  **orchestration** pointers, filled later by the family composition root) are 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
+  **preserves** anything already in either pointer slot (extract-and-reinsert — it never
   regenerates `AGENTS.md` wholesale).
 
 ## Stamps & lineage

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.1.0'
+  version: '1.1.2'
 ---
 
 # agent-workflow-memory
@@ -20,11 +20,12 @@ 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.
+review vocabulary, lifecycle, `docs/plans/queue.md`, mandatory Cleanup, plan-then-execute) **or the
+orchestration recipes** — those are injected into **two delimited pointer slots** in `AGENTS.md`
+(`workflow:methodology` + `workflow:orchestration`) 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 **both** slots **empty** and **preserves** whatever is already
+in them 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
@@ -35,8 +36,8 @@ 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.
+What this substrate owns vs what it only points at. The methodology + orchestration pointers are the
+**two empty slots** the composition root fills — never author that text here.
 
 | Concern | Owner | In the deployed `AGENTS.md` |
 |---|---|---|
@@ -45,6 +46,7 @@ the composition root fills — never author methodology text here.
 | 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 |
+| Orchestration recipes (Solo / Reviewed / Council / Delegated) | **methodology engine** (not this skill) | the empty `workflow:orchestration` slot — filled by the composition root |
 
 ---
 
@@ -90,8 +92,8 @@ bootstrapping over a live system, but the user makes the final call.
 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.
+   (`ln -s AGENTS.md CLAUDE.md`). **Leave BOTH pointer slots (`workflow:methodology` +
+   `workflow:orchestration`) exactly as shipped — empty.** Filling them 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.
@@ -117,7 +119,7 @@ bootstrapping over a live system, but the user makes the final call.
 > 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.
+> composition root owns the **single** commit gate, raised after it injects the two pointer slots.
 > 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).
@@ -164,12 +166,12 @@ Fill strategy:
    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.
+6. **Preserve BOTH pointer slots.** If `AGENTS.md` has the `workflow:methodology` and/or
+   `workflow:orchestration` markers, **never regenerate the file wholesale** — extract any bytes
+   between each pair and reinsert them unchanged. If a pair is absent (a legacy `AGENTS.md`),
+   gracefully **no-op** on that slot (adding a slot to already-deployed files is the composition
+   root's reconcile, not this substrate's job). 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.
@@ -182,8 +184,9 @@ Fill strategy:
   **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.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.
+- **Both pointer slots ship empty and stay the user's.** Never author methodology or orchestration
+  text into them; on upgrade, preserve their content byte-for-byte. The composition root is their 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 is project-local, never machine-global.** Memory's hide writes to the repo's
@@ -209,8 +212,8 @@ The three setup choices each have a full contract in
 ## 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/templates/`](references/templates/) — stack-agnostic `AGENTS.md` (with the two empty
+  pointer slots — methodology + orchestration), `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

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.1.0",
+  "version": "1.1.2",
   "provides": ["context"],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "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/templates/AGENTS.md

@@ -55,19 +55,18 @@ Start-of-session, during-work, and task-completion procedures live in [`docs/ai/
 
 <!-- workflow:methodology:start -->
 <!-- workflow:methodology:end -->
+<!-- workflow:orchestration:start -->
+<!-- workflow:orchestration:end -->
 
 ---
 
 ## 🚫 Hard Constraints
 
-> Adapt to this stack — remove rows that don't apply. Style rules should be linter-enforced, not prose.
-
 | Rule | Enforcement |
 |------|-------------|
 | No `export default` (named exports only) | Linter |
 | No `any` / no unsafe casts | Linter / type-checker |
 | Functional style (no mutation in app code) | Linter |
-| No single-letter variables | Code review |
 | Interactive elements semantic (button/link, not div+onClick) | Linter / a11y |
 | No hardcoded colors — design tokens only | Code review |
 | No business logic in components → hooks/services | Architecture review |

package/scripts/standalone-bootstrap.test.mjs

@@ -35,6 +35,17 @@ const ENFORCEMENT = join(SKILL_ROOT, 'references', 'scripts');
 // from the composition root) so this substrate test stays self-contained and dependency-free.
 const SLOT_START = '<!-- workflow:methodology:start -->';
 const SLOT_END = '<!-- workflow:methodology:end -->';
+const ORCH_START = '<!-- workflow:orchestration:start -->';
+const ORCH_END = '<!-- workflow:orchestration:end -->';
+// The deployed AGENTS.md line budget the composition root fills BOTH pointers inside (D-CAP). A
+// representative single-line fragment per slot models what the composition root injects.
+const AGENTS_MD_CAP = 100;
+const lineCount = (text) => text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+const extractPair = (text, start, end) => {
+  const a = text.indexOf(start);
+  const b = text.indexOf(end);
+  return a !== -1 && b !== -1 && b > a ? text.slice(a + start.length, b) : null;
+};
 
 const tempDirs = [];
 const makeProject = () => {
@@ -98,14 +109,32 @@ describe('standalone substrate bootstrap (end-to-end, real temp project)', () =>
     assert.ok(!existsSync(join(docsAi, '.workflow-version')), 'no composition-root stamp in a standalone bootstrap');
   });
 
-  it('ships the methodology slot present-but-empty', () => {
+  it('ships BOTH pointer slots present-but-empty (methodology + orchestration)', () => {
     const project = makeProject();
     bootstrap(project);
 
     const entry = readFileSync(join(project, 'AGENTS.md'), 'utf8');
-    const start = entry.indexOf(SLOT_START);
-    const end = entry.indexOf(SLOT_END);
-    assert.ok(start !== -1 && end !== -1 && end > start, 'an ordered slot marker pair is present');
-    assert.equal(entry.slice(start + SLOT_START.length, end).trim(), '', 'the slot is empty as shipped');
+    const meth = extractPair(entry, SLOT_START, SLOT_END);
+    const orch = extractPair(entry, ORCH_START, ORCH_END);
+    assert.notEqual(meth, null, 'an ordered methodology marker pair is present');
+    assert.equal(meth.trim(), '', 'the methodology slot is empty as shipped');
+    assert.notEqual(orch, null, 'an ordered orchestration marker pair is present');
+    assert.equal(orch.trim(), '', 'the orchestration slot is empty as shipped');
+  });
+
+  it('stays ≤ the cap when the composition root fills BOTH pointer slots (D-CAP headroom)', () => {
+    const project = makeProject();
+    bootstrap(project);
+    const entry = readFileSync(join(project, 'AGENTS.md'), 'utf8');
+    assert.ok(lineCount(entry) <= AGENTS_MD_CAP, `shipped (empty) AGENTS.md is ${lineCount(entry)} lines (cap ${AGENTS_MD_CAP})`);
+    // Fill each one-line pointer the way the composition root does (replace the empty body), then re-count.
+    const fill = (text, start, end, body) => {
+      const a = text.indexOf(start);
+      const b = text.indexOf(end);
+      return `${text.slice(0, a + start.length)}\n${body}\n${text.slice(b)}`;
+    };
+    let filled = fill(entry, SLOT_START, SLOT_END, '> methodology pointer (one line)');
+    filled = fill(filled, ORCH_START, ORCH_END, '> orchestration recipes pointer (one line)');
+    assert.ok(lineCount(filled) <= AGENTS_MD_CAP, `dual-filled AGENTS.md is ${lineCount(filled)} lines (cap ${AGENTS_MD_CAP})`);
   });
 });