@sabaiway/agent-workflow-kit 1.5.2 → 1.6.0

package/CHANGELOG.md

@@ -4,6 +4,42 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 1.6.0 — Methodology slot reconciliation; engine becomes the canonical methodology home
+
+The workflow methodology now has a **single canonical home** in `agent-workflow-engine`
+(`available:false` — content only, not yet published or wired live), and the kit keeps
+**byte-identical mirror copies** so the existing injection + fallback keep working with **no new
+runtime dependency**. A drift-guard test (`tools/methodology-mirror.test.mjs`) pins the mirrors to
+the engine canon: `references/planning.md` and `tools/methodology-slot.md` must equal their engine
+counterparts byte-for-byte.
+
+The user-facing win is **stamp-independent slot reconciliation**. A single atomic, idempotent kit
+operation now **ensures the `workflow:methodology` slot exists and is filled** in a deployed
+`AGENTS.md`, on **bootstrap** and on **every upgrade**:
+
+- **`tools/inject-methodology.mjs`** gains `METHODOLOGY_ANCHOR`, `EMPTY_SLOT`, `ensureSlot`, and
+  `reconcileSlot` (reusing the existing `findSlot` / `injectMethodology` / `extractSlot` marker
+  parser — no second parser). `reconcileSlot` = **ensure the slot exists** (insert an empty marker
+  pair right after the Session-Protocols anchor when a legacy entry point lacks one) → **inject the
+  bounded fragment ONLY IF the slot is empty** (a filled / user-customized slot is preserved
+  verbatim) → **cap-check** (`AGENTS.md` ≤ 100 lines). On a malformed slot or a missing / duplicate
+  anchor it **STOPs with an error and never edits** — the file is left byte-for-byte unchanged.
+- A new CLI mode — `inject-methodology.mjs reconcile <AGENTS.md>` — runs that policy as **one
+  atomic write** (temp + rename); there is no partial state where markers exist but the fill failed.
+- The kit **fallback** entry-point template (`references/templates/AGENTS.md`) now ships the **empty
+  methodology slot** (matching memory's template) instead of an inline methodology line, so a fresh
+  fallback bootstrap gets a slot the kit fills. A new test (`test/fallback-template-cap.test.mjs`)
+  pins that template — empty and filled — under the 100-line cap.
+- **Bootstrap** and **upgrade** (`SKILL.md`) now run `reconcile`. On upgrade it runs
+  **before** the lineage short-circuit, so the slot is reconciled on every upgrade — reaching even
+  legacy **`1.3.0`** deployments — **without bumping the deployment-lineage head**.
+
+The deployment-lineage head **stays `1.3.0`** and `agent-workflow-memory` is **untouched** (no code,
+version, or migration change): reconciliation is stamp-independent, so it needs no head bump (which
+would have forced a memory republish, since the head is hard-coded in memory's stamp module).
+Additive — no user-facing break. The engine's npm packaging, `available:true`, and the live
+`kit → engine` read selector are deferred to the next plan.
+
 ## 1.5.2 — README uplift to front-door grade (docs)
 
 Docs-only patch. The npm-facing `README.md` is uplifted to match the GitHub family front door's

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '1.5.2'
+  version: '1.6.0'
 ---
 
 # agent-workflow-kit
@@ -49,21 +49,25 @@ made: a partial/broken memory install discovered mid-flow must not disable the w
 **Hand-off contract (explicit; tested independent of agent interpretation).**
 - **Delegated** (memory valid): the kit passes the **target project dir** + the **three setup
   answers** (visibility / language / attribution) to `agent-workflow-memory`, which writes
-  `docs/ai/` + `AGENTS.md` + **`.memory-version`**. The kit then **injects the bounded
-  methodology slot** (below) and writes the kit-fallback **`.workflow-version`**. → **both
-  stamps** present.
+  `docs/ai/` + `AGENTS.md` (with the empty slot) + **`.memory-version`**. The kit then
+  **reconciles the bounded methodology slot** (below) and writes the kit-fallback
+  **`.workflow-version`**. → **both stamps** present.
 - **Fallback** (memory absent/invalid): the kit runs the bootstrap procedure below from its own
-  bundled assets and writes **`.workflow-version`** only. Softly suggest installing
+  bundled assets — whose entry-point template now ships the **empty methodology slot** the kit
+  reconciles + fills — and writes **`.workflow-version`** only. Softly suggest installing
   `agent-workflow-memory` — never a prerequisite.
 
-**Methodology injection (the kit is the ONLY writer of memory's slot).** After `AGENTS.md`
-exists, inject the bounded methodology fragment into its `workflow:methodology` slot:
-`node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs <project>/AGENTS.md`. It injects a short
-summary + pointer (Phase-1 source: the kit's bundled `tools/methodology-slot.md`) — **not** the
-full `references/planning.md` — and keeps `AGENTS.md` under its ≤100-line cap. Marker contract:
-exactly one ordered `start → end` pair → replace only the bytes between them; markers absent →
-no-op; any malformed state (single, reversed, nested, duplicate) → no-op **with an error**,
-never edit.
+**Methodology slot reconciliation (the kit is the ONLY writer of memory's slot).** After
+`AGENTS.md` exists, reconcile its `workflow:methodology` slot:
+`node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs reconcile <project>/AGENTS.md`. Reconcile is
+**one atomic operation**: **ensure the slot exists** (insert an empty marker pair right after the
+Session-Protocols anchor when a legacy entry point lacks one) → **inject the bounded fragment ONLY
+IF the slot is empty** (a filled / user-customized slot is preserved verbatim) → **cap-check**
+(keeps `AGENTS.md` ≤100 lines). The fragment is a short summary + pointer (source: the kit's bundled
+`tools/methodology-slot.md`, a **byte-identical mirror of the `agent-workflow-engine` canon**) —
+**not** the full `references/planning.md`. Contract: exactly one ordered `start → end` pair; a
+malformed slot (single, reversed, nested, duplicate) or a missing / duplicate anchor → **STOP with
+an error**, never edit (the file is left byte-for-byte unchanged).
 
 **One composition-level commit gate.** The delegated memory mode performs **no** commit and
 raises **no** "ask to commit". There is exactly **one** gate, owned by the kit, **after**
@@ -103,7 +107,8 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
 9. **Wire / hide** per visibility (see contract). Install the pre-commit hook (Node projects): `node scripts/install-git-hooks.mjs`. If the installer reports a pre-existing non-marker hook, stop and ask the user to merge it manually rather than overwriting.
 10. **Stamp the deployment lineage.** Write the **deployment-lineage head** into
     `docs/ai/.workflow-version` (one semver line). The lineage head is **`1.3.0`** — the shared
-    `agent-workflow` deployment lineage, **NOT** this kit's package version (`1.4.0`). The two are
+    `agent-workflow` deployment lineage, **NOT** this kit's npm package version (see
+    `package.json` / `CHANGELOG.md`). The two are
     independent axes: a packaging-only release bumps the package but leaves the lineage head until a
     migration actually changes the deployed `docs/ai` structure. A stamp greater than the head →
     STOP (never downgrade).
@@ -122,11 +127,13 @@ Fill strategy:
 ### Mode: upgrade
 
 1. Read `docs/ai/.workflow-version` (the project's stamped lineage). If missing, treat as a pre-versioned deployment and offer to re-bootstrap conservatively.
-2. Compare to the **deployment-lineage head** (`1.3.0` — NOT this kit's package version). If equal → report "up to date" and stop. If the stamp is **greater than the head** or unparseable → **STOP and report** (never downgrade).
-3. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` diff (entries newer than the project's stamp).
-4. Apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those newer than the project's stamp. Migrations are **idempotent** — safe to re-run.
-5. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. If `AGENTS.md` has no *Communication language* block (pre-1.1.0 deployment), **ask the user their conversational language** and insert the block — see `migrations/1.1.0-communication-language.md`. If it has no *Attribution* block (pre-1.2.0 deployment), **ask whether the agent may attribute work to itself / AI** and insert the block (defaulting to `off`) — see `migrations/1.2.0-agent-attribution.md`.
-6. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version). Report changes; **ask before committing**.
+2. **Never-downgrade gate — FIRST, before any write.** Compare the stamp to the **deployment-lineage head** (`1.3.0` — NOT this kit's package version). If the stamp is **greater than the head** or unparseable → **STOP and report**; do not touch a newer / unknown deployment at all (not even the methodology slot).
+3. **Reconcile the methodology slot — stamp-independent, BEFORE the equal-head short-circuit.** Reached only when the stamp **≤ head**. Run `node ${CLAUDE_SKILL_DIR}/tools/inject-methodology.mjs reconcile <project>/AGENTS.md`. This ensures the `workflow:methodology` slot exists and is filled on **every** upgrade, idempotently (zero-diff when already present + filled) — so even a legacy / current **`1.3.0`** deployment gains the slot **without a lineage-head bump** (the head stays `1.3.0`; **no `agent-workflow-memory` change**). It inserts an empty slot at the Session-Protocols anchor if absent, preserves a customized slot verbatim, and STOPs (never edits) on a malformed slot or a missing / duplicate anchor. No-Node project: open `AGENTS.md`, and if there is no `<!-- workflow:methodology:start/end -->` pair, paste it right after the *Read it before any code change.* line and fill it from `tools/methodology-slot.md`.
+4. **Equal-head short-circuit.** If the stamp **equals** the head → the lineage is up to date: **stop here** (the slot was already reconciled in step 3).
+5. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` diff (entries newer than the project's stamp).
+6. Apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those newer than the project's stamp. Migrations are **idempotent** — safe to re-run.
+7. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. If `AGENTS.md` has no *Communication language* block (pre-1.1.0 deployment), **ask the user their conversational language** and insert the block — see `migrations/1.1.0-communication-language.md`. If it has no *Attribution* block (pre-1.2.0 deployment), **ask whether the agent may attribute work to itself / AI** and insert the block (defaulting to `off`) — see `migrations/1.2.0-agent-attribution.md`.
+8. Re-stamp `docs/ai/.workflow-version` to the **deployment-lineage head** (`1.3.0`, not the package version). Report changes; **ask before committing**.
 
 ### Mode: backends
 
@@ -207,6 +214,6 @@ Deploy these into `AGENTS.md`; remove rows that don't apply to the stack.
 - [`references/scripts/`](references/scripts/) — the Node enforcement scripts (caps + staleness + index-freshness gate, 3-tier archive, hook installer) and their unit tests.
 - [`migrations/`](migrations/) — per-version upgrade steps; see `migrations/README.md`.
 - [`launchers/`](launchers/) — run the bootstrapper from non-Claude agents (`SKILL.md` is a native Codex skill; a Devin Desktop workflow launcher + install script). See `launchers/README.md`.
-- [`tools/`](tools/) — the family-wide tooling the kit **owns and ships**: `manifest/{schema.md,validate.mjs}` (the `capability.json` schema + the validator the kit runs as the memory detector, and root CI invokes), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `methodology-slot.md` (the bounded slot injection), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`), and `release-scan.mjs` (the attribution-off release gate). See [`tools/manifest/schema.md`](tools/manifest/schema.md).
+- [`tools/`](tools/) — the family-wide tooling the kit **owns and ships**: `manifest/{schema.md,validate.mjs}` (the `capability.json` schema + the validator the kit runs as the memory detector, and root CI invokes), `delegation.mjs` (the executable delegate/fallback decision + hand-off plan), `inject-methodology.mjs` + `methodology-slot.md` (the bounded slot reconciliation — ensure-slot / inject-if-empty / cap; the fragment is a byte-identical mirror of the `agent-workflow-engine` canon, pinned by `methodology-mirror.test.mjs`), `detect-backends.mjs` (the read-only **backend detector** behind `/agent-workflow-kit backends`), and `release-scan.mjs` (the attribution-off release gate). See [`tools/manifest/schema.md`](tools/manifest/schema.md).
 - [`capability.json`](capability.json) — the kit's own `agent-workflow` family manifest (`kind: composition-root`).
 - [`CHANGELOG.md`](CHANGELOG.md) — version history of this kernel.

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "provides": [],
   "roles": {},
   "detect": {

package/migrations/README.md

@@ -11,7 +11,7 @@ releases add files/templates, which `upgrade` reconciles without a 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/.workflow-version` to the **deployment-lineage head** (`1.3.0` today — the
-   shared lineage, **not** this skill's package version `1.4.0`). A stamp greater than the head → STOP.
+   shared lineage, **not** this skill's npm package version). A stamp greater than the head → STOP.
 
 ## Authoring rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/templates/AGENTS.md

@@ -53,7 +53,8 @@ All project knowledge lives in `docs/ai/`. Layered, lazy-loaded context:
 
 Start-of-session, during-work, and task-completion procedures live in [`docs/ai/agent_rules.md`](./docs/ai/agent_rules.md) §1. **Read it before any code change.**
 
-Planning (plan files, vocabulary, lifecycle, mandatory Cleanup) → the project's planning skill / `docs/ai/agent_rules.md` §"Planning Workflow".
+<!-- workflow:methodology:start -->
+<!-- workflow:methodology:end -->
 
 ---
 

package/tools/delegation.mjs

@@ -83,10 +83,10 @@ export const handoffPlan = (delegate) =>
     : {
         mode: 'fallback',
         memoryWrites: [],
-        // Fallback ships the kit's OWN AGENTS.md, which carries the methodology INLINE (no slot
-        // markers) — so injection is a deliberate no-op here. Label it as inline, not a "slot"
-        // (the "slot" mechanism only exists in the delegate branch, on memory's AGENTS.md).
-        kitWrites: ['docs/ai/', 'AGENTS.md', 'AGENTS.md methodology (inline)', 'docs/ai/.workflow-version'],
+        // Fallback now ships the kit's OWN AGENTS.md carrying the EMPTY methodology slot (Plan 2);
+        // the kit reconciles it (ensure-slot + inject-because-empty) exactly like the delegate
+        // path — so both paths end with a FILLED slot, not inline methodology.
+        kitWrites: ['docs/ai/', 'AGENTS.md', 'AGENTS.md methodology slot', 'docs/ai/.workflow-version'],
         stampsPresent: ['.workflow-version'],
         memoryRaisesCommitGate: false,
         commitGate: 'kit-only-after-injection',

package/tools/delegation.test.mjs

@@ -106,10 +106,11 @@ describe('handoffPlan — stamp sets + single commit gate', () => {
     assert.deepEqual(p.memoryWrites, []);
     assert.equal(p.memoryRaisesCommitGate, false);
     assert.equal(p.commitGate, 'kit-only-after-injection');
-    // Fallback ships the kit's own AGENTS.md with methodology INLINE — never a "slot" (no markers).
+    // Fallback now ships the kit's own AGENTS.md with the EMPTY methodology slot, which the kit
+    // reconciles + fills — the same slot mechanism as the delegate path (Plan 2).
     assert.ok(
-      p.kitWrites.some((w) => w.includes('inline')) && !p.kitWrites.some((w) => w.includes('slot')),
-      'fallback kitWrites should describe inline methodology, not a slot',
+      p.kitWrites.some((w) => w.includes('slot')) && !p.kitWrites.some((w) => w.includes('inline')),
+      'fallback kitWrites should describe the methodology slot, not inline methodology',
     );
   });
 });

package/tools/inject-methodology.mjs

@@ -1,16 +1,20 @@
 #!/usr/bin/env node
-// Methodology slot injection — the composition root's only mutation of memory's AGENTS.md.
+// Methodology slot injection + reconciliation — the composition root's only mutation of a
+// deployed AGENTS.md.
 //
-// memory ships an EMPTY delimited slot in templates/AGENTS.md; the kit (which knows the whole
-// family) fills it. The engine only *provides* the methodology text — Plan 2 repoints the
-// source to it. Phase 1 source = the kit's bundled tools/methodology-slot.md (a BOUNDED summary
-// + pointer, NOT the full references/planning.md), so AGENTS.md stays under its line cap.
+// Both templates (memory's + the kit fallback) ship an EMPTY delimited slot; the kit (which knows
+// the whole family) fills it. The bounded fragment (tools/methodology-slot.md) is a BOUNDED summary
+// + pointer, NOT the full references/planning.md, so AGENTS.md stays under its line cap; it is a
+// byte-identical MIRROR of the canonical text in agent-workflow-engine (drift-guarded).
 //
-// Marker contract (shared with memory's upgrade extract-and-reinsert), strictly enforced:
-//   - exactly one ordered start→end pair  → replace only the bytes between them.
-//   - markers absent (legacy AGENTS.md)   → gracefully NO-OP (slot migration is Plan 2).
-//   - any malformed state (single, reversed, nested, duplicate) → NO-OP WITH AN ERROR; never edit.
-// Prefix/suffix bytes are preserved exactly. Re-running with the same fragment is idempotent.
+// Two layers over one marker parser:
+//   - injectMethodology — fill an EXISTING slot. Marker contract, strictly enforced:
+//       exactly one ordered start→end pair → replace only the bytes between them;
+//       markers absent → NO-OP; any malformed state (single, reversed, nested, duplicate) →
+//       NO-OP WITH AN ERROR, never edit. Prefix/suffix preserved exactly; re-run is idempotent.
+//   - ensureSlot / reconcileSlot — the bootstrap/upgrade policy (Plan 2): ensure the slot EXISTS
+//       (insert an empty pair at the Session-Protocols anchor when a legacy file lacks one) →
+//       inject ONLY IF empty (preserve a customized slot verbatim) → cap-check. Stamp-independent.
 //
 // Pure string functions (testable with byte-preservation fixtures); dependency-free, Node >= 18.
 
@@ -18,6 +22,10 @@ export const START_MARKER = '<!-- workflow:methodology:start -->';
 export const END_MARKER = '<!-- workflow:methodology:end -->';
 export const AGENTS_MD_CAP = 100; // the deployed AGENTS.md line budget (its own footer rule)
 
+// Count lines independent of a trailing newline (CRLF-safe: split on '\n' — a CRLF line still ends
+// in '\n', so the count is the same as for LF).
+const lineCount = (text) => text.split('\n').length - (text.endsWith('\n') ? 1 : 0);
+
 const countOccurrences = (haystack, needle) => {
   let count = 0;
   let from = 0;
@@ -58,14 +66,15 @@ export const injectMethodology = (text, fragment, { maxLines } = {}) => {
   const slot = findSlot(text);
   if (slot.state === 'absent') return { status: 'noop-absent', text };
   if (slot.state === 'malformed') return { status: 'error', text, error: slot.reason };
+  // Frame the fragment with the DOCUMENT's newline style (and convert the LF-canonical fragment to
+  // it) so injecting into a CRLF file does not leave lone LFs around the slot.
+  const nl = text.includes('\r\n') ? '\r\n' : '\n';
   const before = text.slice(0, slot.startIdx + START_MARKER.length);
   const after = text.slice(slot.endIdx);
-  const out = `${before}\n${fragment.trim()}\n${after}`;
-  if (maxLines != null) {
-    const lines = out.split('\n').length - (out.endsWith('\n') ? 1 : 0);
-    if (lines > maxLines) {
-      return { status: 'error', text, error: `injection would push AGENTS.md to ${lines} lines (cap ${maxLines}) — trim the fragment or the file` };
-    }
+  const body = fragment.trim().replace(/\r?\n/g, nl);
+  const out = `${before}${nl}${body}${nl}${after}`;
+  if (maxLines != null && lineCount(out) > maxLines) {
+    return { status: 'error', text, error: `injection would push AGENTS.md to ${lineCount(out)} lines (cap ${maxLines}) — trim the fragment or the file` };
   }
   return { status: 'injected', text: out };
 };
@@ -78,19 +87,120 @@ export const extractSlot = (text) => {
   return text.slice(slot.startIdx + START_MARKER.length, slot.endIdx);
 };
 
+// The Session-Protocols anchor line both deployed templates carry (the agent_rules.md §1 sentence).
+// ensureSlot inserts an empty slot right after this line when a legacy entry point has no markers.
+// Contract: EXACTLY ONE match required — 0 or >1 → error (never guess where the methodology lives).
+export const METHODOLOGY_ANCHOR = /^.*Read it before any code change\..*$/m;
+
+// The canonical empty slot (an ordered start→end pair, nothing between) — what a fresh template
+// ships and what ensureSlot inserts. LF form; ensureSlot rewrites the newline to match the document.
+export const EMPTY_SLOT = `${START_MARKER}\n${END_MARKER}`;
+
+const countMatches = (text, re) => (text.match(new RegExp(re.source, 'gm')) || []).length;
+
+// Ensure a single, well-formed methodology slot EXISTS — without filling it. Pure; no fs.
+//   { status: 'present',  text }   a well-formed slot already exists → bytes unchanged (idempotent).
+//   { status: 'inserted', text }   absent + exactly one anchor → an EMPTY slot inserted right after
+//                                   the anchor line, newline style + all other bytes preserved.
+//   { status: 'error', text, error }  malformed slot, OR (when absent) 0/>1 anchors → bytes unchanged.
+export const ensureSlot = (text) => {
+  const slot = findSlot(text);
+  if (slot.state === 'ok') return { status: 'present', text };
+  if (slot.state === 'malformed') return { status: 'error', text, error: slot.reason };
+  // absent → place an empty slot at the one anchor, or refuse rather than guess.
+  const anchors = countMatches(text, METHODOLOGY_ANCHOR);
+  if (anchors !== 1) {
+    return {
+      status: 'error',
+      text,
+      error: `expected exactly one methodology anchor (the "Read it before any code change." Session-Protocols line), found ${anchors} — refusing to guess where the slot belongs; add the slot markers manually`,
+    };
+  }
+  const nl = text.includes('\r\n') ? '\r\n' : '\n';
+  const match = text.match(METHODOLOGY_ANCHOR);
+  const eol = text.indexOf('\n', match.index);
+  const insertAt = eol === -1 ? text.length : eol + 1;
+  const block = `${nl}${EMPTY_SLOT.replace(/\n/g, nl)}${nl}`;
+  const out = `${text.slice(0, insertAt)}${block}${text.slice(insertAt)}`;
+  return { status: 'inserted', text: out };
+};
+
+// Bootstrap/upgrade reconciliation policy (pure): ensure the slot exists, then fill it ONLY IF it
+// is empty (a filled/customized slot is preserved verbatim), enforcing the line cap — all as one
+// step the CLI commits with a single atomic write. On ANY error the INPUT bytes are returned
+// unchanged (the intermediate slot-insert is discarded), so there is no partial on-disk state.
+//   reconciled-inserted — slot was absent, inserted at the anchor, then filled.
+//   reconciled-filled   — slot existed but was empty, now filled.
+//   present-filled      — slot already carried content → preserved verbatim.
+//   error               — malformed slot, 0/>1 anchors, or cap exceeded → input unchanged.
+export const reconcileSlot = (text, fragment, { maxLines } = {}) => {
+  const ensured = ensureSlot(text);
+  if (ensured.status === 'error') return { status: 'error', text, error: ensured.error };
+  const current = extractSlot(ensured.text);
+  const isEmpty = current == null || current.trim() === '';
+  if (!isEmpty) {
+    // Preserve a filled/customized slot verbatim — but still enforce the cap on the result, so an
+    // already-over-cap entry point is surfaced (input unchanged) rather than silently accepted.
+    if (maxLines != null && lineCount(ensured.text) > maxLines) {
+      return { status: 'error', text, error: `AGENTS.md is ${lineCount(ensured.text)} lines (cap ${maxLines}) — trim the file (a customized methodology slot must still fit the cap)` };
+    }
+    return { status: 'present-filled', text: ensured.text };
+  }
+  const injected = injectMethodology(ensured.text, fragment, { maxLines });
+  if (injected.status !== 'injected') return { status: 'error', text, error: injected.error };
+  const status = ensured.status === 'inserted' ? 'reconciled-inserted' : 'reconciled-filled';
+  return { status, text: injected.text };
+};
+
 const main = async (argv) => {
-  const { readFile, writeFile, rename } = await import('node:fs/promises');
+  const { readFile, writeFile, rename, rm } = await import('node:fs/promises');
   const { dirname, basename, join, resolve } = await import('node:path');
   const { fileURLToPath } = await import('node:url');
   const here = dirname(fileURLToPath(import.meta.url));
-  const agentsPath = argv[0];
+
+  // `reconcile <AGENTS.md> [fragment.md]` = ensure-slot + inject-if-empty + cap (bootstrap/upgrade);
+  // `<AGENTS.md> [fragment.md]` = the legacy inject-into-existing-slot mode.
+  const mode = argv[0] === 'reconcile' ? 'reconcile' : 'inject';
+  const rest = mode === 'reconcile' ? argv.slice(1) : argv;
+  const agentsPath = rest[0];
   if (!agentsPath) {
-    console.error('usage: inject-methodology.mjs <path/to/AGENTS.md> [fragment.md]');
+    console.error('usage: inject-methodology.mjs [reconcile] <path/to/AGENTS.md> [fragment.md]');
     process.exit(2);
   }
-  const fragmentPath = argv[1] ? resolve(argv[1]) : resolve(here, 'methodology-slot.md');
+  const fragmentPath = rest[1] ? resolve(rest[1]) : resolve(here, 'methodology-slot.md');
   const text = await readFile(resolve(agentsPath), 'utf8');
   const fragment = await readFile(fragmentPath, 'utf8');
+
+  const writeAtomic = async (out) => {
+    const tmp = join(dirname(resolve(agentsPath)), `.${basename(agentsPath)}.tmp-${process.pid}-${Date.now()}`);
+    try {
+      await writeFile(tmp, out, 'utf8');
+      await rename(tmp, resolve(agentsPath));
+    } catch (err) {
+      await rm(tmp, { force: true }).catch(() => {}); // never leave a temp file behind on failure
+      throw err;
+    }
+  };
+
+  if (mode === 'reconcile') {
+    const result = reconcileSlot(text, fragment, { maxLines: AGENTS_MD_CAP });
+    if (result.status === 'error') {
+      console.error(`[inject-methodology] reconcile refused — ${result.error}`);
+      process.exit(1);
+    }
+    if (result.status === 'present-filled') {
+      console.log('[inject-methodology] methodology slot already present and filled — nothing to do (zero-diff).');
+      return;
+    }
+    await writeAtomic(result.text);
+    const what =
+      result.status === 'reconciled-inserted'
+        ? 'inserted the methodology slot at the Session-Protocols anchor and filled it'
+        : 'filled the empty methodology slot';
+    console.log(`[inject-methodology] reconcile: ${what}.`);
+    return;
+  }
+
   const result = injectMethodology(text, fragment, { maxLines: AGENTS_MD_CAP });
   if (result.status === 'error') {
     console.error(`[inject-methodology] malformed slot — refusing to edit: ${result.error}`);
@@ -100,9 +210,7 @@ const main = async (argv) => {
     console.log('[inject-methodology] no methodology markers found — nothing to inject (legacy AGENTS.md).');
     return;
   }
-  const tmp = join(dirname(resolve(agentsPath)), `.${basename(agentsPath)}.tmp-${process.pid}-${Date.now()}`);
-  await writeFile(tmp, result.text, 'utf8');
-  await rename(tmp, resolve(agentsPath));
+  await writeAtomic(result.text);
   console.log('[inject-methodology] injected the bounded methodology fragment into the slot.');
 };
 

package/tools/inject-methodology.test.mjs

@@ -1,22 +1,56 @@
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
-import { readFileSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
 import {
   injectMethodology,
   findSlot,
   extractSlot,
+  ensureSlot,
+  reconcileSlot,
+  METHODOLOGY_ANCHOR,
+  EMPTY_SLOT,
+  AGENTS_MD_CAP,
   START_MARKER,
   END_MARKER,
 } from './inject-methodology.mjs';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
+const SCRIPT = join(HERE, 'inject-methodology.mjs');
 const FRAGMENT = readFileSync(join(HERE, 'methodology-slot.md'), 'utf8');
 
 const wrap = (inner) =>
   `# AGENTS.md\n\nprefix bytes\n\n## Session Protocols\n\nintro line.\n\n${START_MARKER}${inner}${END_MARKER}\n\n## Hard Constraints\n\nsuffix bytes\n`;
 
+// The exact Session-Protocols line both deployed templates carry — the slot anchor.
+const ANCHOR_LINE =
+  'Start-of-session, during-work, and task-completion procedures live in [`docs/ai/agent_rules.md`](./docs/ai/agent_rules.md) §1. **Read it before any code change.**';
+
+// A pre-slot (markerless) entry point that still carries the Session-Protocols anchor line —
+// the realistic shape of a legacy deployment the upgrade reconciliation must add a slot to.
+const legacyWithAnchor = (nl = '\n') =>
+  [
+    '# AGENTS.md',
+    '',
+    'prefix bytes',
+    '',
+    '## 🚀 Session Protocols',
+    '',
+    ANCHOR_LINE,
+    '',
+    '---',
+    '',
+    '## 🚫 Hard Constraints',
+    '',
+    'suffix bytes',
+    '',
+  ].join(nl);
+
+const countMatches = (text, re) => (text.match(new RegExp(re.source, 'gm')) || []).length;
+
 describe('findSlot — marker classification', () => {
   it('one ordered pair → ok', () => {
     assert.equal(findSlot(wrap('\n')).state, 'ok');
@@ -122,3 +156,200 @@ describe('post-injection cap — AGENTS.md stays under its line budget', () => {
     assert.ok(lines <= 100, `AGENTS.md would be ${lines} lines after injection (cap 100)`);
   });
 });
+
+describe('METHODOLOGY_ANCHOR — locating the Session-Protocols slot position', () => {
+  it('matches exactly one line in a deployed-style markerless entry point', () => {
+    assert.equal(countMatches(legacyWithAnchor(), METHODOLOGY_ANCHOR), 1);
+  });
+  it('matches exactly one line in BOTH shipped templates', () => {
+    const memTmpl = readFileSync(
+      join(HERE, '..', '..', 'agent-workflow-memory', 'references', 'templates', 'AGENTS.md'),
+      'utf8',
+    );
+    const kitTmpl = readFileSync(join(HERE, '..', 'references', 'templates', 'AGENTS.md'), 'utf8');
+    assert.equal(countMatches(memTmpl, METHODOLOGY_ANCHOR), 1, 'memory template has exactly one anchor');
+    assert.equal(countMatches(kitTmpl, METHODOLOGY_ANCHOR), 1, 'kit fallback template has exactly one anchor');
+  });
+  it('does not match an entry point that lacks the Session-Protocols line', () => {
+    assert.equal(countMatches('# AGENTS.md\nno session protocols here\n', METHODOLOGY_ANCHOR), 0);
+  });
+});
+
+describe('EMPTY_SLOT — the canonical empty marker pair', () => {
+  it('is exactly the start+end markers joined by a newline', () => {
+    assert.equal(EMPTY_SLOT, `${START_MARKER}\n${END_MARKER}`);
+    assert.equal(findSlot(EMPTY_SLOT).state, 'ok');
+    assert.equal(extractSlot(EMPTY_SLOT).trim(), '');
+  });
+});
+
+describe('ensureSlot — idempotent slot presence (insert at the anchor only when absent)', () => {
+  it('present (one ok pair) → status present, bytes unchanged', () => {
+    const input = wrap('\nfilled\n');
+    const out = ensureSlot(input);
+    assert.equal(out.status, 'present');
+    assert.equal(out.text, input);
+  });
+
+  it('malformed slot → status error, never edits', () => {
+    const input = `${START_MARKER}\n${END_MARKER}\n${START_MARKER}\n${END_MARKER}\n`;
+    const out = ensureSlot(input);
+    assert.equal(out.status, 'error');
+    assert.equal(out.text, input);
+  });
+
+  it('absent + exactly one anchor → inserts EMPTY_SLOT after the anchor line, preserving bytes', () => {
+    const input = legacyWithAnchor();
+    const out = ensureSlot(input);
+    assert.equal(out.status, 'inserted');
+    assert.equal(findSlot(out.text).state, 'ok', 'a well-formed slot now exists');
+    assert.equal(extractSlot(out.text).trim(), '', 'the inserted slot is empty');
+    // the slot lands right after the anchor line
+    assert.match(out.text, new RegExp(`Read it before any code change\\.\\*\\*\\n+${START_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`));
+    // every original line survives
+    for (const line of ['# AGENTS.md', 'prefix bytes', ANCHOR_LINE, '## 🚫 Hard Constraints', 'suffix bytes']) {
+      assert.ok(out.text.includes(line), `original line preserved: ${line}`);
+    }
+  });
+
+  it('absent + zero anchor → status error with an actionable message, never edits', () => {
+    const input = '# AGENTS.md\n\nno anchor at all\n';
+    const out = ensureSlot(input);
+    assert.equal(out.status, 'error');
+    assert.equal(out.text, input);
+    assert.match(out.error, /anchor/i);
+  });
+
+  it('absent + multiple anchors → status error (refuses to guess), never edits', () => {
+    const input = `${ANCHOR_LINE}\n\nsome text\n\n${ANCHOR_LINE}\n`;
+    const out = ensureSlot(input);
+    assert.equal(out.status, 'error');
+    assert.equal(out.text, input);
+  });
+
+  it('preserves CRLF newline style when inserting', () => {
+    const input = legacyWithAnchor('\r\n');
+    const out = ensureSlot(input);
+    assert.equal(out.status, 'inserted');
+    assert.equal(findSlot(out.text).state, 'ok');
+    assert.ok(out.text.includes(`${START_MARKER}\r\n${END_MARKER}`), 'markers use CRLF');
+    assert.ok(!/[^\r]\n/.test(out.text), 'no lone LF introduced into a CRLF document');
+  });
+
+  it('is idempotent — a second ensureSlot finds the slot present and changes nothing', () => {
+    const once = ensureSlot(legacyWithAnchor()).text;
+    const twice = ensureSlot(once);
+    assert.equal(twice.status, 'present');
+    assert.equal(twice.text, once);
+  });
+});
+
+describe('reconcileSlot — ensure + inject-if-empty + cap, as one atomic policy', () => {
+  it('markerless legacy (with anchor) → reconciled-inserted, slot filled, outside bytes preserved', () => {
+    const input = legacyWithAnchor();
+    const out = reconcileSlot(input, FRAGMENT, { maxLines: AGENTS_MD_CAP });
+    assert.equal(out.status, 'reconciled-inserted');
+    assert.equal(extractSlot(out.text).trim(), FRAGMENT.trim(), 'slot now carries the fragment');
+    assert.ok(out.text.includes(ANCHOR_LINE), 'anchor preserved');
+    assert.ok(out.text.includes('## 🚫 Hard Constraints'), 'suffix preserved');
+  });
+
+  it('present empty slot → reconciled-filled', () => {
+    const out = reconcileSlot(wrap('\n'), FRAGMENT, { maxLines: AGENTS_MD_CAP });
+    assert.equal(out.status, 'reconciled-filled');
+    assert.equal(extractSlot(out.text).trim(), FRAGMENT.trim());
+  });
+
+  it('present customized/filled slot → present-filled, preserved verbatim (byte-for-byte)', () => {
+    const custom = wrap('\nuser-authored methodology notes\nsecond line\n');
+    const out = reconcileSlot(custom, FRAGMENT, { maxLines: AGENTS_MD_CAP });
+    assert.equal(out.status, 'present-filled');
+    assert.equal(out.text, custom, 'a filled slot is never overwritten');
+  });
+
+  it('malformed slot → error, input returned byte-for-byte', () => {
+    const input = `${START_MARKER}\n${END_MARKER}\n${START_MARKER}\n${END_MARKER}\n`;
+    const out = reconcileSlot(input, FRAGMENT, { maxLines: AGENTS_MD_CAP });
+    assert.equal(out.status, 'error');
+    assert.equal(out.text, input);
+  });
+
+  it('markerless with no anchor → error, input unchanged (never guesses placement)', () => {
+    const input = '# AGENTS.md\n\nno slot, no anchor\n';
+    const out = reconcileSlot(input, FRAGMENT, { maxLines: AGENTS_MD_CAP });
+    assert.equal(out.status, 'error');
+    assert.equal(out.text, input);
+  });
+
+  it('over-cap result → error, input unchanged (atomic: discards the intermediate slot insert)', () => {
+    const input = legacyWithAnchor();
+    const out = reconcileSlot(input, FRAGMENT, { maxLines: 5 });
+    assert.equal(out.status, 'error');
+    assert.equal(out.text, input);
+  });
+
+  it('produces a clean CRLF document when inserting + filling (no lone LF)', () => {
+    // ensureSlot preserves the document newline style for the markers, and injectMethodology frames
+    // the LF-canonical fragment with the document's EOL — so a CRLF document stays uniformly CRLF.
+    const input = legacyWithAnchor('\r\n');
+    const out = reconcileSlot(input, FRAGMENT, { maxLines: AGENTS_MD_CAP });
+    assert.equal(out.status, 'reconciled-inserted');
+    assert.equal(extractSlot(out.text).trim(), FRAGMENT.trim());
+    assert.ok(out.text.includes(`${ANCHOR_LINE}\r\n`), 'anchor line keeps CRLF');
+    assert.ok(!/[^\r]\n/.test(out.text), 'no lone LF introduced into a CRLF document');
+  });
+
+  it('present filled slot over the line cap → error, input returned unchanged', () => {
+    const bigSlot = `\n${Array.from({ length: 30 }, (_, i) => `note ${i}`).join('\n')}\n`;
+    const filled = wrap(bigSlot);
+    const out = reconcileSlot(filled, FRAGMENT, { maxLines: 10 });
+    assert.equal(out.status, 'error');
+    assert.equal(out.text, filled, 'an over-cap entry point is surfaced, not silently accepted');
+    assert.match(out.error, /cap 10/);
+  });
+});
+
+describe('reconcile CLI — atomic ensure+inject-if-empty+cap on the real filesystem', () => {
+  const withTempAgents = (contents, run) => {
+    const dir = mkdtempSync(join(tmpdir(), 'reconcile-cli-'));
+    const agents = join(dir, 'AGENTS.md');
+    writeFileSync(agents, contents);
+    try {
+      return run(agents);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  };
+
+  it('markerless legacy (with anchor) → slot inserted and filled (exit 0)', () => {
+    withTempAgents(legacyWithAnchor(), (agents) => {
+      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe' });
+      const out = readFileSync(agents, 'utf8');
+      assert.equal(findSlot(out).state, 'ok');
+      assert.equal(extractSlot(out).trim(), FRAGMENT.trim());
+    });
+  });
+
+  it('present empty slot → slot filled (exit 0)', () => {
+    withTempAgents(wrap('\n'), (agents) => {
+      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe' });
+      assert.equal(extractSlot(readFileSync(agents, 'utf8')).trim(), FRAGMENT.trim());
+    });
+  });
+
+  it('filled/customized slot → file left byte-for-byte untouched', () => {
+    const custom = wrap('\nuser notes\n');
+    withTempAgents(custom, (agents) => {
+      execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe' });
+      assert.equal(readFileSync(agents, 'utf8'), custom);
+    });
+  });
+
+  it('malformed slot → STOP with non-zero exit, file byte-unchanged', () => {
+    const malformed = `${START_MARKER}\n${END_MARKER}\n${START_MARKER}\n${END_MARKER}\n`;
+    withTempAgents(malformed, (agents) => {
+      assert.throws(() => execFileSync(process.execPath, [SCRIPT, 'reconcile', agents], { stdio: 'pipe' }));
+      assert.equal(readFileSync(agents, 'utf8'), malformed);
+    });
+  });
+});