@sabaiway/agent-workflow-kit 1.2.0 → 1.4.0

package/references/contracts.md

@@ -0,0 +1,62 @@
+# Setup contracts
+
+The three choices the bootstrap makes with the user — **visibility**, **conversational
+language**, and **agent attribution** — each have a contract below. `SKILL.md` links here so the
+main procedure stays lean; load this file when you need the full rule for a contract (e.g. while
+filling the matching `AGENTS.md` block, or when an `upgrade` migration touches it).
+
+Ask each as a **structured multiple-choice prompt where your agent supports it** (`AskUserQuestion`
+in Claude Code), otherwise in prose — and always wait for the answer before writing.
+
+---
+
+## Visibility contract
+
+The user chooses at bootstrap whether the AI artifacts are visible in the repo or hidden — an
+**explicit up-front question** (bootstrap step 2), never an assumed default. The two modes then
+diverge:
+
+- **visible** — artifacts are committed. Wire the project's `package.json` scripts (`docs:check` / `docs:index` / `docs:index:check` / `docs:archive` / `docs:archive:check` / `docs:archive:issues` / `docs:archive:issues:check` / `prepare: node scripts/install-git-hooks.mjs`) and add a minimal `.gitignore` (`docs/plans/`, `.claude/settings.local.json`). This is the canonical model.
+- **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/.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.
+
+Not in this version: a fully-external hidden mode (artifacts relocated outside the repo tree).
+Deferred to a later release + migration.
+
+---
+
+## Communication contract
+
+The user chooses at bootstrap (step 3) which language the agent **talks to them** in. The choice is
+recorded in the *Communication language* block of the project's `AGENTS.md`, so every agent that
+reads the entry point honours it — and stops drifting between languages mid-session.
+
+Scope — **dialogue only**:
+
+- **In the chosen language** — everything the agent produces *for the user to read*: questions, explanations, plan summaries, status updates, commit-message prose if asked, review notes.
+- **Always in their source language** — code, identifiers, file paths, shell commands, log/console output, error strings, config keys, and abbreviations/acronyms. Translating these breaks copy-paste, search, and tooling.
+- **Files aren't translated** — the deployed `docs/ai/` files, `AGENTS.md`, and this kernel stay in their source language regardless of the chosen language (cross-agent / cross-team portability). The conversational language is about the *chat*, not the *artifacts*.
+
+Default to the language the user is already writing in; confirm rather than assume. On `upgrade`, a
+pre-1.1.0 deployment with no block gets one (the agent asks).
+
+---
+
+## Attribution contract
+
+The user chooses at bootstrap (step 4) whether the agent may **attribute work to itself or to AI**.
+The choice is recorded in the *Attribution* block of the project's `AGENTS.md`, so every agent that
+reads the entry point honours it. **Default is `off`** — people are routinely surprised to find an
+AI listed as a repo contributor (a `Co-Authored-By` trailer is enough to do it), so opt-in, never
+opt-out.
+
+When attribution is **`off`**, no mention of the agent, AI, or the model appears **anywhere**:
+
+- **No `Co-Authored-By` trailers** and **no "Generated with …" footers** on commits or PRs.
+- **No AI/agent/model references** in code, comments, commit messages, PR titles/bodies, branch names, or `docs/` prose. The work reads as the human author's.
+- **Two enforcement layers** — the *Attribution* block binds everything an agent writes **by hand**; the automatic `Co-Authored-By` trailer is added by the **harness**, not the prose, so for **Claude Code** the kit also sets `"includeCoAuthoredBy": false` in the project's `.claude/settings.json`. Other tools: disable their equivalent co-author/footer setting if present.
+
+When **`on`**, the agent may add its standard trailer / footer per the user's tooling defaults. This
+block is about *attribution*, not authorship of the actual changes — quality, tests, and the "ask
+before commit" rule are unchanged either way.
+
+On `upgrade`, a pre-1.2.0 deployment with no block gets one (the agent asks, defaulting to `off`).

package/references/scripts/archive-changelog.mjs

@@ -130,9 +130,6 @@ export const parseChangelogText = (text) => {
 
 const TRAILING_FOOTER_PATTERNS = [
   /^\*\*Last Updated:/i,
-  // Legacy in-tree footer line from the deleted changelog-archive.md — match left in place
-  // so a re-migration cannot leak the old marker into a freshly-rotated entry.
-  /^> Записи старше/i,
 ];
 
 export const stripTrailingSeparator = (block) => {
@@ -149,7 +146,7 @@ export const stripTrailingSeparator = (block) => {
 export const stripBlockquoteHistoryNotice = (preamble) => {
   const filtered = preamble
     .split('\n')
-    .filter((line) => !/changelog-archive\.md/i.test(line) && !/Записи старше/i.test(line));
+    .filter((line) => !/changelog-archive\.md/i.test(line));
 
   // Strip any previously-inserted "## History" section so re-running the rotator is idempotent.
   // A History section starts at `## History` and ends at the next `---` separator or end-of-file.

package/references/templates/AGENTS.md

@@ -9,8 +9,8 @@
 ## 🗣️ Communication language
 
 > **Talk to the user in {{COMM_LANGUAGE}}** — every question, explanation, summary, and status update.
-> Keep code, identifiers, file paths, shell commands, log output, and abbreviations in their **source language** (usually English) — translating them breaks copy-paste, search, and tooling.
-> This sets the **dialogue** language only. The files in `docs/ai/` and this entry point stay in English (kernel is English-only, for cross-agent / cross-team portability).
+> Keep code, identifiers, file paths, shell commands, log output, and abbreviations in their **source language** — translating them breaks copy-paste, search, and tooling.
+> This sets the **dialogue** language only — it does not translate the files in `docs/ai/` or this entry point, which stay in their source language (for cross-agent / cross-team portability).
 
 ---
 

package/tools/delegation.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// Delegation decision + hand-off plan — the kit-owned, executable form of the composition
+// contract, so the "delegate vs fall back" choice and the stamp/commit responsibilities are
+// pinned down by code + tests, not left to agent interpretation (Plan §1.7).
+//
+//   detectMemory(dir) → { delegate, reason, ... }   runs the kit's OWN validator + asset check
+//   handoffPlan(delegate) → who writes what, which stamps end up present, who owns the commit gate
+//
+// Pure (dependency-injectable validator + fs), dependency-free, Node >= 18.
+
+import { statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { validateManifest, VALID } from './manifest/validate.mjs';
+
+// The exact skill name a delegable memory candidate must declare (guards against a wrong-name
+// manifest that happens to be a valid memory-substrate with the right assets).
+export const EXPECTED_MEMORY_NAME = 'agent-workflow-memory';
+
+// The assets a memory candidate must carry, AND their required type. A partial install (manifest +
+// SKILL.md only) is missing these → invalid → fallback. Checking the type (not just existence)
+// rejects a wrong-shaped install (e.g. a file where a dir is expected) BEFORE any project write.
+export const REQUIRED_MEMORY_ASSETS = [
+  { path: 'references/templates', type: 'dir' },
+  { path: 'references/contracts.md', type: 'file' },
+  { path: 'references/scripts', type: 'dir' },
+  { path: 'scripts/stamp-takeover.mjs', type: 'file' },
+  { path: 'migrations', type: 'dir' },
+  { path: 'capability.json', type: 'file' },
+];
+
+const defaultStatType = (path) => {
+  try {
+    const s = statSync(path);
+    return s.isDirectory() ? 'dir' : s.isFile() ? 'file' : 'other';
+  } catch {
+    return null;
+  }
+};
+
+// Decide whether to delegate substrate deployment to a memory candidate. The kit runs its OWN
+// validator (never one shipped by the candidate). Delegate only on valid + kind memory-substrate +
+// right name + available + all required assets present AT THE RIGHT TYPE; otherwise fall back.
+export const detectMemory = (memorySkillDir, deps = {}) => {
+  const validate = deps.validate ?? validateManifest;
+  const statType = deps.statType ?? defaultStatType;
+  const report = validate(memorySkillDir);
+  const missingAssets = REQUIRED_MEMORY_ASSETS.filter(
+    (asset) => statType(join(memorySkillDir, asset.path)) !== asset.type,
+  ).map((asset) => asset.path);
+  const delegate =
+    report.result === VALID &&
+    report.kind === 'memory-substrate' &&
+    report.name === EXPECTED_MEMORY_NAME &&
+    report.available !== false &&
+    missingAssets.length === 0;
+  const reason = delegate
+    ? 'memory manifest valid (kind: memory-substrate) and all required assets present'
+    : report.result !== VALID
+      ? `memory manifest ${report.result} — using bundled fallback`
+      : report.kind !== 'memory-substrate'
+        ? `memory manifest kind "${report.kind}" is not memory-substrate — using bundled fallback`
+        : report.name !== EXPECTED_MEMORY_NAME
+          ? `memory manifest name "${report.name}" is not "${EXPECTED_MEMORY_NAME}" — using bundled fallback`
+          : report.available === false
+            ? 'memory manifest is a declared stub (available:false) — using bundled fallback'
+            : `memory install incomplete (missing: ${missingAssets.join(', ')}) — using bundled fallback`;
+  return { delegate, reason, validatorResult: report.result, kind: report.kind, name: report.name, available: report.available, missingAssets };
+};
+
+// The hand-off matrix. Memory NEVER raises its own commit gate; the kit owns exactly ONE
+// composition-level gate, after injection. Delegated → both stamps; fallback → .workflow-version only.
+export const handoffPlan = (delegate) =>
+  delegate
+    ? {
+        mode: 'delegate',
+        memoryWrites: ['docs/ai/', 'AGENTS.md', 'docs/ai/.memory-version'],
+        kitWrites: ['AGENTS.md methodology slot', 'docs/ai/.workflow-version'],
+        stampsPresent: ['.memory-version', '.workflow-version'],
+        memoryRaisesCommitGate: false,
+        commitGate: 'kit-only-after-injection',
+      }
+    : {
+        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'],
+        stampsPresent: ['.workflow-version'],
+        memoryRaisesCommitGate: false,
+        commitGate: 'kit-only-after-injection',
+      };
+
+const main = (argv) => {
+  const dir = argv[0];
+  if (!dir) {
+    console.error('usage: delegation.mjs <memory-skill-dir>   (prints the delegate/fallback decision + hand-off plan)');
+    process.exit(2);
+  }
+  const decision = detectMemory(resolve(dir));
+  const plan = handoffPlan(decision.delegate);
+  console.log(`[delegation] ${plan.mode}: ${decision.reason}`);
+  console.log(`[delegation] stamps present after deploy: ${plan.stampsPresent.join(', ')}`);
+  console.log(`[delegation] commit gate: ${plan.commitGate} (memory raises its own gate: ${plan.memoryRaisesCommitGate})`);
+};
+
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) main(process.argv.slice(2));

package/tools/delegation.test.mjs

@@ -0,0 +1,115 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { detectMemory, handoffPlan, REQUIRED_MEMORY_ASSETS } from './delegation.mjs';
+
+// Inject a fake validator + fs so the decision matrix is tested independent of real files/agents.
+const fakeValidate = (over = {}) => () => ({
+  result: 'valid',
+  kind: 'memory-substrate',
+  name: 'agent-workflow-memory',
+  available: true,
+  errors: [],
+  ...over,
+});
+const ASSET_TYPE = {
+  'references/templates': 'dir',
+  'references/contracts.md': 'file',
+  'references/scripts': 'dir',
+  'scripts/stamp-takeover.mjs': 'file',
+  migrations: 'dir',
+  'capability.json': 'file',
+};
+const typeFor = (p) => {
+  for (const [k, t] of Object.entries(ASSET_TYPE)) if (p.endsWith(k)) return t;
+  return 'file';
+};
+const allPresent = (p) => typeFor(p);
+const missing = (absent) => (p) => (absent.some((a) => p.endsWith(a)) ? null : typeFor(p));
+const wrongType = (paths) => (p) => {
+  for (const [k, t] of Object.entries(ASSET_TYPE)) {
+    if (p.endsWith(k)) return paths.includes(k) ? (t === 'dir' ? 'file' : 'dir') : t;
+  }
+  return 'file';
+};
+
+describe('detectMemory — decision matrix', () => {
+  it('valid + memory-substrate + right name + available + all assets → delegate', () => {
+    const d = detectMemory('/m', { validate: fakeValidate(), statType: allPresent });
+    assert.equal(d.delegate, true);
+  });
+
+  it('invalid manifest → fallback', () => {
+    const d = detectMemory('/m', { validate: fakeValidate({ result: 'invalid' }), statType: allPresent });
+    assert.equal(d.delegate, false);
+    assert.match(d.reason, /invalid/);
+  });
+
+  it('unsupported schema → fallback (treated like invalid)', () => {
+    const d = detectMemory('/m', { validate: fakeValidate({ result: 'unsupported' }), statType: allPresent });
+    assert.equal(d.delegate, false);
+  });
+
+  it('wrong kind → fallback', () => {
+    const d = detectMemory('/m', { validate: fakeValidate({ kind: 'composition-root' }), statType: allPresent });
+    assert.equal(d.delegate, false);
+    assert.match(d.reason, /not memory-substrate/);
+  });
+
+  it('wrong name → fallback (even if kind + assets are right)', () => {
+    const d = detectMemory('/m', { validate: fakeValidate({ name: 'evil-substrate' }), statType: allPresent });
+    assert.equal(d.delegate, false);
+    assert.match(d.reason, /name/);
+  });
+
+  it('available:false stub → fallback', () => {
+    const d = detectMemory('/m', { validate: fakeValidate({ available: false }), statType: allPresent });
+    assert.equal(d.delegate, false);
+    assert.match(d.reason, /stub/);
+  });
+
+  it('partial install (missing stamp-takeover) → fallback', () => {
+    const d = detectMemory('/m', {
+      validate: fakeValidate(),
+      statType: missing(['scripts/stamp-takeover.mjs']),
+    });
+    assert.equal(d.delegate, false);
+    assert.match(d.reason, /stamp-takeover/);
+  });
+
+  it('wrong-type asset (templates is a file, not a dir) → fallback', () => {
+    const d = detectMemory('/m', { validate: fakeValidate(), statType: wrongType(['references/templates']) });
+    assert.equal(d.delegate, false);
+    assert.match(d.reason, /references\/templates/);
+  });
+
+  it('required assets use real (references/) paths', () => {
+    const paths = REQUIRED_MEMORY_ASSETS.map((a) => a.path);
+    assert.ok(paths.includes('references/templates'));
+    assert.ok(paths.includes('references/contracts.md'));
+  });
+});
+
+describe('handoffPlan — stamp sets + single commit gate', () => {
+  it('delegate → both stamps present; memory never raises its own commit gate', () => {
+    const p = handoffPlan(true);
+    assert.deepEqual(p.stampsPresent, ['.memory-version', '.workflow-version']);
+    assert.equal(p.memoryRaisesCommitGate, false);
+    assert.equal(p.commitGate, 'kit-only-after-injection');
+    assert.ok(p.memoryWrites.includes('docs/ai/.memory-version'));
+    // Delegate is the ONLY branch with a real slot (memory ships it empty; the kit injects).
+    assert.ok(p.kitWrites.some((w) => w.includes('slot')), 'delegate kitWrites should name the methodology slot');
+  });
+
+  it('fallback → only .workflow-version; kit writes everything; one kit gate', () => {
+    const p = handoffPlan(false);
+    assert.deepEqual(p.stampsPresent, ['.workflow-version']);
+    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).
+    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',
+    );
+  });
+});

package/tools/inject-methodology.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// Methodology slot injection — the composition root's only mutation of memory's 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.
+//
+// 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.
+//
+// Pure string functions (testable with byte-preservation fixtures); dependency-free, Node >= 18.
+
+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)
+
+const countOccurrences = (haystack, needle) => {
+  let count = 0;
+  let from = 0;
+  for (;;) {
+    const idx = haystack.indexOf(needle, from);
+    if (idx === -1) return count;
+    count += 1;
+    from = idx + needle.length;
+  }
+};
+
+// Classify the marker state of an AGENTS.md text. Pure; no fs.
+//   { state: 'ok',      startIdx, endIdx }   exactly one ordered pair
+//   { state: 'absent' }                      no markers at all → caller no-ops
+//   { state: 'malformed', reason }           anything else → caller no-ops WITH error
+export const findSlot = (text) => {
+  const starts = countOccurrences(text, START_MARKER);
+  const ends = countOccurrences(text, END_MARKER);
+  if (starts === 0 && ends === 0) return { state: 'absent' };
+  if (starts !== 1 || ends !== 1) {
+    return { state: 'malformed', reason: `expected exactly one start/end marker pair, found ${starts} start / ${ends} end` };
+  }
+  const startIdx = text.indexOf(START_MARKER);
+  const endIdx = text.indexOf(END_MARKER);
+  if (endIdx < startIdx) return { state: 'malformed', reason: 'end marker precedes start marker' };
+  return { state: 'ok', startIdx, endIdx };
+};
+
+// Inject `fragment` between the markers, replacing only the bytes between them.
+// Returns { status: 'injected' | 'noop-absent' | 'error', text, error? }. On absent/error the
+// returned text is the INPUT, byte-for-byte (never edit on a malformed slot). Pass
+// `{ maxLines }` to enforce the AGENTS.md line cap as a postcondition (refuse, don't bust it).
+export const injectMethodology = (text, fragment, { maxLines } = {}) => {
+  // A fragment that itself contains a marker would create a duplicate/nested slot — refuse.
+  if (fragment.includes(START_MARKER) || fragment.includes(END_MARKER)) {
+    return { status: 'error', text, error: 'fragment contains a methodology marker — refusing to inject (would create a duplicate/nested slot)' };
+  }
+  const slot = findSlot(text);
+  if (slot.state === 'absent') return { status: 'noop-absent', text };
+  if (slot.state === 'malformed') return { status: 'error', text, error: slot.reason };
+  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` };
+    }
+  }
+  return { status: 'injected', text: out };
+};
+
+// Inverse used by memory's upgrade: extract the current slot content (preserve-on-upgrade).
+// Returns the bytes strictly between the markers, or null on absent/malformed.
+export const extractSlot = (text) => {
+  const slot = findSlot(text);
+  if (slot.state !== 'ok') return null;
+  return text.slice(slot.startIdx + START_MARKER.length, slot.endIdx);
+};
+
+const main = async (argv) => {
+  const { readFile, writeFile, rename } = 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];
+  if (!agentsPath) {
+    console.error('usage: inject-methodology.mjs <path/to/AGENTS.md> [fragment.md]');
+    process.exit(2);
+  }
+  const fragmentPath = argv[1] ? resolve(argv[1]) : resolve(here, 'methodology-slot.md');
+  const text = await readFile(resolve(agentsPath), 'utf8');
+  const fragment = await readFile(fragmentPath, 'utf8');
+  const result = injectMethodology(text, fragment, { maxLines: AGENTS_MD_CAP });
+  if (result.status === 'error') {
+    console.error(`[inject-methodology] malformed slot — refusing to edit: ${result.error}`);
+    process.exit(1);
+  }
+  if (result.status === 'noop-absent') {
+    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));
+  console.log('[inject-methodology] injected the bounded methodology fragment into the slot.');
+};
+
+const { pathToFileURL } = await import('node:url');
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) await main(process.argv.slice(2));

package/tools/inject-methodology.test.mjs

@@ -0,0 +1,124 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  injectMethodology,
+  findSlot,
+  extractSlot,
+  START_MARKER,
+  END_MARKER,
+} from './inject-methodology.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+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`;
+
+describe('findSlot — marker classification', () => {
+  it('one ordered pair → ok', () => {
+    assert.equal(findSlot(wrap('\n')).state, 'ok');
+  });
+  it('no markers → absent', () => {
+    assert.equal(findSlot('# AGENTS.md\nno markers here\n').state, 'absent');
+  });
+  it('duplicate pair → malformed', () => {
+    const text = `${START_MARKER}\n${END_MARKER}\n${START_MARKER}\n${END_MARKER}\n`;
+    assert.equal(findSlot(text).state, 'malformed');
+  });
+  it('single start only → malformed', () => {
+    assert.equal(findSlot(`x\n${START_MARKER}\ny\n`).state, 'malformed');
+  });
+  it('single end only → malformed', () => {
+    assert.equal(findSlot(`x\n${END_MARKER}\ny\n`).state, 'malformed');
+  });
+  it('reversed (end before start) → malformed', () => {
+    assert.equal(findSlot(`${END_MARKER}\nmiddle\n${START_MARKER}\n`).state, 'malformed');
+  });
+});
+
+describe('injectMethodology — byte preservation', () => {
+  it('injects into an empty slot, preserving prefix/suffix exactly', () => {
+    const input = wrap('\n');
+    const out = injectMethodology(input, FRAGMENT);
+    assert.equal(out.status, 'injected');
+    assert.ok(out.text.startsWith('# AGENTS.md\n\nprefix bytes\n\n## Session Protocols\n\nintro line.\n\n'));
+    assert.ok(out.text.endsWith('\n\n## Hard Constraints\n\nsuffix bytes\n'));
+    assert.ok(out.text.includes(FRAGMENT.trim()));
+    // markers themselves are preserved
+    assert.equal((out.text.match(new RegExp(START_MARKER.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g')) || []).length, 1);
+  });
+
+  it('is idempotent — re-injecting the same fragment is stable', () => {
+    const once = injectMethodology(wrap('\n'), FRAGMENT).text;
+    const twice = injectMethodology(once, FRAGMENT).text;
+    assert.equal(twice, once);
+  });
+
+  it('overwrites a previously-filled slot (bootstrap composition), preserving outside bytes', () => {
+    const filled = wrap('\nstale content\n');
+    const out = injectMethodology(filled, FRAGMENT);
+    assert.equal(out.status, 'injected');
+    assert.ok(!out.text.includes('stale content'));
+    assert.ok(out.text.endsWith('\n\n## Hard Constraints\n\nsuffix bytes\n'));
+  });
+
+  it('rejects a fragment that itself contains a marker (would nest/duplicate the slot)', () => {
+    const out = injectMethodology(wrap('\n'), `bad ${START_MARKER} fragment`);
+    assert.equal(out.status, 'error');
+    assert.equal(out.text, wrap('\n'));
+  });
+
+  it('refuses to bust the line cap (maxLines) instead of silently overflowing it', () => {
+    const huge = Array.from({ length: 40 }, (_, i) => `methodology line ${i}`).join('\n');
+    const out = injectMethodology(wrap('\n'), huge, { maxLines: 20 });
+    assert.equal(out.status, 'error');
+    assert.match(out.error, /cap 20/);
+    assert.equal(out.text, wrap('\n')); // unchanged
+  });
+
+  it('absent markers → no-op, returns input byte-for-byte', () => {
+    const input = '# AGENTS.md\nlegacy file, no slot\n';
+    const out = injectMethodology(input, FRAGMENT);
+    assert.equal(out.status, 'noop-absent');
+    assert.equal(out.text, input);
+  });
+
+  for (const [label, input] of [
+    ['duplicate pair', `${START_MARKER}\n${END_MARKER}\n${START_MARKER}\n${END_MARKER}\n`],
+    ['single start', `head\n${START_MARKER}\ntail\n`],
+    ['single end', `head\n${END_MARKER}\ntail\n`],
+    ['reversed', `${END_MARKER}\nx\n${START_MARKER}\n`],
+  ]) {
+    it(`malformed (${label}) → error, returns input byte-for-byte`, () => {
+      const out = injectMethodology(input, FRAGMENT);
+      assert.equal(out.status, 'error');
+      assert.equal(out.text, input); // never edits a malformed slot
+    });
+  }
+});
+
+describe('extractSlot — preserve-on-upgrade inverse', () => {
+  it('returns the bytes strictly between the markers', () => {
+    assert.equal(extractSlot(wrap('\nkeep me\n')), '\nkeep me\n');
+  });
+  it('null on absent/malformed', () => {
+    assert.equal(extractSlot('no markers'), null);
+    assert.equal(extractSlot(`${START_MARKER}\n${START_MARKER}\n${END_MARKER}\n`), null);
+  });
+});
+
+describe('post-injection cap — AGENTS.md stays under its line budget', () => {
+  it('injecting the bounded fragment into the real memory template keeps AGENTS.md ≤ 100 lines', () => {
+    const template = readFileSync(
+      join(HERE, '..', '..', 'agent-workflow-memory', 'references', 'templates', 'AGENTS.md'),
+      'utf8',
+    );
+    const out = injectMethodology(template, FRAGMENT);
+    assert.equal(out.status, 'injected');
+    const lines = out.text.split('\n').length - (out.text.endsWith('\n') ? 1 : 0);
+    assert.ok(lines <= 100, `AGENTS.md would be ${lines} lines after injection (cap 100)`);
+  });
+});

package/tools/manifest/fixtures/bad-available/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: bad-available
+metadata:
+  version: '1.0.0'
+---
+
+# bad-available fixture — `available` is a string, not a boolean → invalid.

package/tools/manifest/fixtures/bad-available/capability.json

@@ -0,0 +1,10 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "bad-available",
+  "kind": "memory-substrate",
+  "version": "1.0.0",
+  "available": "yes",
+  "provides": [],
+  "roles": {}
+}

package/tools/manifest/fixtures/detect-array/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: detect-array
+metadata:
+  version: '1.0.0'
+---
+
+# detect-array fixture — `detect.installed` is an array, not an object.

package/tools/manifest/fixtures/detect-array/capability.json

@@ -0,0 +1,10 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "detect-array",
+  "kind": "memory-substrate",
+  "version": "1.0.0",
+  "provides": [],
+  "roles": {},
+  "detect": { "installed": [] }
+}

package/tools/manifest/fixtures/malformed-json/capability.json

@@ -0,0 +1 @@
+{ "family": "agent-workflow", "schema": 1, "name": "broken",

package/tools/manifest/fixtures/metadata-version/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: metadata-version
+version: '9.9.9'
+description: A decoy top-level `version:` that must NOT be read as the authoritative version.
+metadata:
+  version: '1.0.0'
+---
+
+# metadata-version fixture — authoritative version is `metadata.version` (1.0.0), not the
+# stray top-level `version: 9.9.9`. capability.json declares 1.0.0, so this is VALID.

package/tools/manifest/fixtures/metadata-version/capability.json

@@ -0,0 +1,9 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "name": "metadata-version",
+  "kind": "memory-substrate",
+  "version": "1.0.0",
+  "provides": [],
+  "roles": {}
+}

package/tools/manifest/fixtures/missing-key/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: missing-key
+metadata:
+  version: '1.0.0'
+---
+
+# missing-key fixture — capability.json omits the required `name` key.

package/tools/manifest/fixtures/missing-key/capability.json

@@ -0,0 +1,8 @@
+{
+  "family": "agent-workflow",
+  "schema": 1,
+  "kind": "memory-substrate",
+  "version": "1.0.0",
+  "provides": [],
+  "roles": {}
+}

package/tools/manifest/fixtures/missing-source/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: missing-source
+metadata:
+  version: '1.0.0'
+---
+
+# missing-source fixture — `roles.review.source` points to a file that does not exist.