@sabaiway/agent-workflow-memory 1.1.2 → 1.2.0

package/CHANGELOG.md

@@ -4,6 +4,27 @@ 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.2.0 — Seeds the per-project orchestration config
+
+The substrate now seeds a new **per-project, user-editable recipe config** —
+`references/templates/orchestration.json` — deployed into `docs/ai/orchestration.json` by the bootstrap
+template loop. It declares the orchestration **recipe** each named activity/slot uses (the composition
+root's read-only `procedures` advisor reads it); the recipe **canon** and the slot **vocabulary** still
+live in the engine / composition root, never here (the substrate keeps knowing nobody — the seed's
+self-documentation uses generic "composition root" phrasing, naming no sibling). The shipped default is
+conservative: **`solo` everywhere**, with an onboarding `_README` explaining how to raise a slot.
+
+### Added
+- **`references/templates/orchestration.json`** — strict JSON (no comments), byte-identical to the kit's
+  fallback copy (kit↔memory template parity guard). Seeded on bootstrap; on upgrade it is **ensured
+  stamp-independently** (create-if-missing / **preserve-if-edited** — a user's edits are never clobbered),
+  so even an equal-head (`1.3.0`) deployment gains it **without a lineage-head bump or a migration file**.
+- An **ownership-table** row distinguishing the seeded, editable recipe **CONFIG** (memory) from the
+  recipe **CANON** + slot vocabulary (engine / composition root).
+
+The deployment-lineage head stays **`1.3.0`** (no `docs/ai` structural change; no migration file). The
+npm package version is a separate axis.
+
 ## 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

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.2'
+  version: '1.2.0'
 ---
 
 # agent-workflow-memory
@@ -47,6 +47,7 @@ What this substrate owns vs what it only points at. The methodology + orchestrat
 | 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 |
+| Per-project recipe **CONFIG** (which recipe each activity/slot uses) | **memory** seeds an *editable default* | `docs/ai/orchestration.json` (hand-edited; the recipe **canon** + the slot **vocabulary** live in the engine / composition root, never here) |
 
 ---
 
@@ -95,7 +96,9 @@ bootstrapping over a live system, but the user makes the final call.
    (`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.
+   `${CLAUDE_SKILL_DIR}/references/templates/` (every non-`AGENTS.md` template, including the seeded,
+   **user-editable** `docs/ai/orchestration.json` config — strict JSON, the per-project recipe defaults
+   the composition root's `procedures` advisor reads). 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;
@@ -110,7 +113,7 @@ bootstrapping over a live system, but the user makes the final call.
 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.1.0`). Use the atomic writer in
+    lineage, **not** this package's npm version (`1.2.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.**
@@ -118,7 +121,8 @@ bootstrapping over a live system, but the user makes the final call.
 > **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
+> `.memory-version`, **including seeding / stamp-independently ensuring `docs/ai/orchestration.json`**)
+> 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 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
@@ -156,8 +160,14 @@ Fill strategy:
    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.
+   **behind** the never-downgrade STOP above. **Also stamp-independent (same gate, before the equal-head
+   short-circuit): ensure `docs/ai/orchestration.json`** — **create it from
+   `${CLAUDE_SKILL_DIR}/references/templates/orchestration.json` if missing**, **preserve it byte-for-byte
+   if it already exists** (a user may have edited it; never clobber it). This is why an equal-head (`1.3.0`)
+   deployment still gains the config seed **without a lineage-head bump or a migration file** (the
+   stamp-independent-reconcile precedent — like the pointer slots + the hidden-mode footprint). **Then**,
+   if the stamp **equals** the head → report "up to date" (plus any footprint move / config seed 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**.
@@ -183,7 +193,7 @@ 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.1.0`. They are independent axes.
+  `agent-workflow` lineage), not the npm `1.2.0`. They are independent axes.
 - **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.
@@ -213,7 +223,8 @@ The three setup choices each have a full contract in
 
 - [`references/contracts.md`](references/contracts.md) — the three setup contracts in full.
 - [`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.
+  pointer slots — methodology + orchestration), `agent_rules.md`, the seeded user-editable
+  `orchestration.json` config, 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.test.mjs

@@ -33,6 +33,7 @@ describe('memory installer — payload + symlink-traversal hardening', () => {
       'scripts/stamp-takeover.mjs',
       'references/contracts.md',
       'references/templates/AGENTS.md',
+      'references/templates/orchestration.json',
       'migrations/legacy-stamp-takeover.md',
     ]) {
       assert.ok(existsSync(join(target, f)), `missing installed entry: ${f}`);

package/capability.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-memory",
-  "version": "1.1.2",
+  "version": "1.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/scripts/check-docs-size.mjs

@@ -139,7 +139,10 @@ export const parseStaleAfter = (value) => {
   return Number(m[1]);
 };
 
-const walkMarkdownFiles = async (dir) => {
+// Discover the docs to validate: ONLY `*.md` files (recursively). Non-`.md` files — e.g. a hand-edited
+// `docs/ai/orchestration.json` config — are inherently skipped, so they are never subject to the
+// frontmatter / maxLines caps. Exported so that skip is pinned by a regression test.
+export const walkMarkdownFiles = async (dir) => {
   const entries = await readdir(dir, { withFileTypes: true });
   const files = [];
   for (const entry of entries) {

package/references/scripts/check-docs-size.test.mjs

@@ -10,6 +10,7 @@ import {
   inspectFile,
   buildIndex,
   checkIndexFreshness,
+  walkMarkdownFiles,
 } from './check-docs-size.mjs';
 
 describe('parseFrontmatter', () => {
@@ -126,6 +127,29 @@ describe('inspectFile', () => {
   });
 });
 
+// The cap-validator discovers ONLY `*.md` files, so a non-`.md` doc — e.g. a hand-edited
+// `docs/ai/orchestration.json` config — is inherently skipped: never validated for frontmatter / caps.
+// This belt-and-suspenders regression pins that skip so adding a config `.json` under docs/ai can never
+// start failing the docs gate.
+describe('walkMarkdownFiles — only *.md is discovered (a config .json is skipped)', () => {
+  let dir;
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'walk-md-test-'));
+  });
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true });
+  });
+
+  it('returns the .md file and NOT a sibling orchestration.json', async () => {
+    await writeFile(join(dir, 'doc.md'), '---\ntype: reference\nmaxLines: 100\n---\n\nbody.\n');
+    await writeFile(join(dir, 'orchestration.json'), '{ "plan-authoring": { "review": "reviewed" } }\n');
+    const found = await walkMarkdownFiles(dir);
+    expect(found.some((f) => f.endsWith('doc.md'))).toBe(true);
+    expect(found.some((f) => f.endsWith('.json'))).toBe(false);
+    expect(found.some((f) => f.endsWith('orchestration.json'))).toBe(false);
+  });
+});
+
 // Synthetic row matching the shape produced by `inspectFile` + `formatRow`.
 const makeRow = (path, overrides = {}) => ({
   path,

package/references/templates/orchestration.json

@@ -0,0 +1,5 @@
+{
+  "_README": "Per-project orchestration config: the recipe used at each step (slot) of each named activity. Hand-edit this file — it is never written for you. Each activity is configured independently (e.g. plan-authoring, plan-execution), and so is each slot within it. A slot's value is a recipe: a 'review' slot accepts solo | reviewed | council (you self-review / one backend reviews / both review and you synthesize); an 'execute' slot accepts solo | delegated (you implement / a backend runs a bounded sub-task). The default below is 'solo' everywhere — no execution backend required. Raise a slot to reviewed or council for a second opinion, or to delegated to hand off execution; those need an execution backend set up first. Remove a slot's line to fall back to the computed default (reviewed when a review backend is ready, otherwise solo). Run the read-only procedures advisor to see an activity's steps plus the recipe resolved for your environment, and pass a per-run override to change one slot just once. Strict JSON — no comments.",
+  "plan-authoring": { "review": "solo" },
+  "plan-execution": { "execute": "solo", "review": "solo" }
+}

package/scripts/standalone-bootstrap.test.mjs

@@ -18,6 +18,7 @@ import {
   cpSync,
   readdirSync,
   readFileSync,
+  writeFileSync,
   existsSync,
   symlinkSync,
 } from 'node:fs';
@@ -122,6 +123,45 @@ describe('standalone substrate bootstrap (end-to-end, real temp project)', () =>
     assert.equal(orch.trim(), '', 'the orchestration slot is empty as shipped');
   });
 
+  it('seeds docs/ai/orchestration.json from the template (the bootstrap loop deploys it)', () => {
+    const project = makeProject();
+    const docsAi = bootstrap(project);
+    const seeded = join(docsAi, 'orchestration.json');
+    assert.ok(existsSync(seeded), 'the orchestration.json config is seeded into docs/ai');
+    assert.equal(
+      readFileSync(seeded, 'utf8'),
+      readFileSync(join(TEMPLATES, 'orchestration.json'), 'utf8'),
+      'the seeded config is byte-identical to the template',
+    );
+    // strict JSON valid + the conservative all-solo default the maintainer chose.
+    const config = JSON.parse(readFileSync(seeded, 'utf8'));
+    assert.equal(typeof config._README, 'string', 'an onboarding _README is present');
+    assert.equal(config['plan-authoring'].review, 'solo', 'default review recipe is solo');
+  });
+
+  // The stamp-independent upgrade "ensure" (SKILL.md upgrade step 2): create-if-missing /
+  // preserve-if-edited. Modeled here the way the documented prose performs it — so an equal-head
+  // re-run never clobbers a user's edited config, and a deleted one is re-seeded.
+  it('the upgrade ensure preserves an edited config and re-creates a deleted one', () => {
+    const project = makeProject();
+    const docsAi = bootstrap(project);
+    const dest = join(docsAi, 'orchestration.json');
+    const ensureConfig = () => {
+      if (!existsSync(dest)) cpSync(join(TEMPLATES, 'orchestration.json'), dest);
+    };
+
+    // A user edits the deployed config.
+    writeFileSync(dest, '{ "plan-authoring": { "review": "council" } }\n');
+    ensureConfig(); // an equal-head upgrade re-runs the ensure
+    assert.match(readFileSync(dest, 'utf8'), /council/, 'an edited config is preserved (never clobbered)');
+
+    // A missing config is re-seeded.
+    rmSync(dest);
+    ensureConfig();
+    assert.ok(existsSync(dest), 'a missing config is re-created from the template');
+    assert.equal(readFileSync(dest, 'utf8'), readFileSync(join(TEMPLATES, 'orchestration.json'), 'utf8'));
+  });
+
   it('stays ≤ the cap when the composition root fills BOTH pointer slots (D-CAP headroom)', () => {
     const project = makeProject();
     bootstrap(project);