@sabaiway/agent-workflow-kit 14.4.3 → 14.6.0

package/tools/migration-blocks.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+import { lstatSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AGENTS_MD_CAP } from './inject-methodology.mjs';
+import { writeContainedFileAtomic } from './atomic-write.mjs';
+import { isDirectRun } from './direct-run.mjs';
+
+const LF = String.fromCharCode(10);
+const CRLF = String.fromCharCode(13) + LF;
+const ANCHOR = '## 🧭 Memory Map';
+const TEMPLATE_PATH = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'references', 'templates', 'AGENTS.md');
+const REINSTALL = 'npx @sabaiway/agent-workflow-kit@latest init';
+const BLOCKS = [
+  { name: 'communication', heading: '## 🗣️ Communication language', flag: 'language', placeholder: '{{COMM_LANGUAGE}}' },
+  { name: 'attribution', heading: '## ✍️ Attribution', flag: 'attribution', placeholder: '{{AGENT_ATTRIBUTION}}' },
+];
+const FLAGS = ['--cwd', '--language', '--attribution', '--apply'];
+const USAGE = 'usage: migration-blocks.mjs --cwd <project> [--language <text>] [--attribution on|off] [--apply]';
+const CONTROL_BYTES = /[\x00-\x1f\x7f\u2028\u2029]/u;
+
+const makeResult = (code, stdout = '', stderr = '') => ({ code, stdout, stderr });
+const renderDetail = (detail) => String(detail).replace(/[\r\n\u2028\u2029]+/gu, ' ');
+const refuse = (name, detail) => makeResult(1, '', detail ? `${name}: ${renderDetail(detail)}` : name);
+const countLines = (text) => text.split(LF).length - Number(text.endsWith(LF));
+const findHeadings = (lines, heading) => lines.flatMap((line, index) => line.trimEnd() === heading ? [index] : []);
+
+const parseArgs = (argv) => {
+  const parsed = argv.reduce((state, argument) => {
+    if (state.pending) {
+      if (argument.startsWith('--')) throw new Error(`${state.pending} needs a value`);
+      return { options: { ...state.options, [state.pending.slice(2)]: argument }, pending: null };
+    }
+    if (!FLAGS.includes(argument)) throw new Error(`unknown argument ${argument}`);
+    const key = argument.slice(2);
+    if (Object.hasOwn(state.options, key)) throw new Error(`${argument} repeated`);
+    if (argument === '--apply') return { options: { ...state.options, apply: true }, pending: null };
+    return { options: state.options, pending: argument };
+  }, { options: {}, pending: null });
+  if (parsed.pending) throw new Error(`${parsed.pending} needs a value`);
+  if (!parsed.options.cwd) throw new Error('--cwd is required');
+  return parsed.options;
+};
+
+const checkAnswers = ({ language, attribution }) => {
+  if (language !== undefined && (!language.trim() || CONTROL_BYTES.test(language))) {
+    return refuse('language', 'provide one nonempty line without control bytes');
+  }
+  if (attribution !== undefined && !['on', 'off'].includes(attribution)) {
+    return refuse('attribution', 'expected on or off');
+  }
+  return null;
+};
+
+const extractSpans = (template) => {
+  const lines = template.split(CRLF).join(LF).split(LF);
+  return BLOCKS.map((block) => {
+    const headings = findHeadings(lines, block.heading);
+    if (headings.length !== 1) throw new Error(`${block.name} heading must occur once`);
+    const start = headings[0];
+    const next = lines.findIndex((line, index) => index > start && line.startsWith('## '));
+    const span = next < 0 ? lines.slice(start).join(LF) : lines.slice(start, next).join(LF) + LF;
+    if (span.split(block.placeholder).length !== 2) {
+      throw new Error(`${block.name} placeholder must occur once in its span`);
+    }
+    return { ...block, span };
+  });
+};
+
+const readTemplate = (path, deps) => {
+  try {
+    const read = deps.readFileSync ?? readFileSync;
+    return { spans: extractSpans(read(path, 'utf8')) };
+  } catch (error) {
+    return { error: refuse('template', `${error.message}; run ${REINSTALL}`) };
+  }
+};
+
+const readDocument = (path, deps) => {
+  const probe = deps.lstatSync ?? lstatSync;
+  const read = deps.readFileSync ?? readFileSync;
+  const status = (() => {
+    try {
+      return { stat: probe(path) };
+    } catch (error) {
+      const name = error.code === 'ENOENT' ? 'file-absent' : 'file-unreadable';
+      return { error: refuse(name, error.message) };
+    }
+  })();
+  if (status.error) return status;
+  if (status.stat.isSymbolicLink()) return { error: refuse('file-symlink', path) };
+  if (!status.stat.isFile()) return { error: refuse('file-unreadable', `${path} is not a regular file`) };
+  try {
+    return { text: read(path, 'utf8') };
+  } catch (error) {
+    return { error: refuse('file-unreadable', error.message) };
+  }
+};
+
+const classifyBlock = (block, lines, answers, newline) => {
+  const headings = findHeadings(lines, block.heading);
+  const answer = answers[block.flag];
+  if (headings.length > 1) return { error: refuse('heading-twice', block.name) };
+  if (headings.length === 1) {
+    return { ...block, state: 'present', index: headings[0], ignored: answer !== undefined };
+  }
+  if (answer === undefined) return { ...block, state: 'needs' };
+  const body = block.span.split(block.placeholder).join(answer).split(LF).join(newline);
+  return { ...block, state: 'planned', body };
+};
+
+const renderBlock = (block, applied) => {
+  if (block.state === 'present') return `${block.name}: present${block.ignored ? '; answer ignored' : ''}`;
+  if (block.state === 'needs') return `${block.name}: needs --${block.flag}`;
+  return `${block.name}: ${applied ? 'inserted' : 'planned'}`;
+};
+
+const insertBlocks = (text, lines, blocks) => {
+  const planned = blocks.filter((block) => block.state === 'planned');
+  if (planned.length === 0) return { body: text };
+  const anchors = lines.flatMap((line, index) => line.replace(/\r$/u, '') === ANCHOR ? [index] : []);
+  if (anchors.length === 0) return { error: refuse('anchor-absent', ANCHOR) };
+  if (anchors.length !== 1) return { error: refuse('anchor-repeated', ANCHOR) };
+  const total = countLines(text) + planned.reduce((count, block) => count + countLines(block.body), 0);
+  if (total > AGENTS_MD_CAP) {
+    return { error: refuse('cap', `${total} lines exceed ${AGENTS_MD_CAP}; trim AGENTS.md and re-run`) };
+  }
+  const anchor = anchors[0];
+  const attribution = blocks.find((block) => block.name === 'attribution');
+  const insertions = planned.map((block) => ({
+    ...block,
+    index: block.name === 'communication' && attribution.state === 'present' && attribution.index < anchor
+      ? attribution.index : anchor,
+  }));
+  const body = lines.map((line, index) => {
+    const prefix = insertions.filter((block) => block.index === index).map((block) => block.body).join('');
+    return prefix + line;
+  }).join(LF);
+  return { body };
+};
+
+export const planBlocks = ({ text, spans, language, attribution, apply = false }) => {
+  const lines = text.split(LF);
+  const newline = text.includes(CRLF) ? CRLF : LF;
+  const blocks = spans.map((block) => classifyBlock(block, lines, { language, attribution }, newline));
+  const refused = blocks.find((block) => block.error);
+  if (refused) return { result: refused.error, write: false };
+  const insertion = insertBlocks(text, lines, blocks);
+  if (insertion.error) return { result: insertion.error, write: false };
+  const missing = blocks.some((block) => block.state === 'needs');
+  const write = apply && !missing && blocks.some((block) => block.state === 'planned');
+  const stdout = blocks.map((block) => renderBlock(block, write)).join(LF);
+  const result = apply && missing ? makeResult(1, stdout, 'answer-missing') : makeResult(0, stdout);
+  return { result, write, body: insertion.body };
+};
+
+const runBlocks = (options, deps) => {
+  const invalid = checkAnswers(options);
+  if (invalid) return invalid;
+  const template = readTemplate(deps.templatePath ?? TEMPLATE_PATH, deps);
+  if (template.error) return template.error;
+  const root = resolve(options.cwd);
+  const destination = resolve(root, 'AGENTS.md');
+  const document = readDocument(destination, deps);
+  if (document.error) return document.error;
+  const plan = planBlocks({ ...options, text: document.text, spans: template.spans });
+  if (plan.write) {
+    try {
+      writeContainedFileAtomic(root, destination, plan.body, {
+        writeFile: deps.writeFile,
+        rename: deps.rename,
+        rm: deps.rm,
+      });
+    } catch (error) {
+      return refuse('write-failed', error.message);
+    }
+  }
+  return plan.result;
+};
+
+export const main = (argv, deps = {}) => {
+  const parsed = (() => {
+    try {
+      return { options: parseArgs(argv) };
+    } catch (error) {
+      return { error: makeResult(2, '', `${USAGE}; ${renderDetail(error.message)}`) };
+    }
+  })();
+  return parsed.error ?? runBlocks(parsed.options, deps);
+};
+
+if (isDirectRun(import.meta.url)) {
+  const result = await main(process.argv.slice(2));
+  if (result.stdout) console.log(result.stdout);
+  if (result.stderr) console.error(result.stderr);
+  process.exit(result.code);
+}

package/tools/migration-notes.mjs

@@ -0,0 +1,218 @@
+import { lstatSync, readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { EXPECTED_WORKFLOW_VERSION } from './cheap-agents-read.mjs';
+import { isDirectRun } from './direct-run.mjs';
+
+const NOTES_DIR = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'migrations');
+const STAMP_PATH = 'docs/ai/.workflow-version';
+const VERSION_PATTERN = /^[0-9]+[.][0-9]+[.][0-9]+$/u;
+const SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const CONTROL_PATTERN = /[\p{Cc}\p{Zl}\p{Zp}]/gu;
+const NOTE_SUFFIX = '.md';
+const README_NAME = 'README.md';
+const HEADLINE_PREFIX = '# ';
+const LF = String.fromCharCode(10);
+const CR = String.fromCharCode(13);
+const EXIT_ACCEPTED = 0;
+const EXIT_REFUSED = 1;
+const EXIT_USAGE = 2;
+
+const formatDetail = (value) => String(value).replace(CONTROL_PATTERN, ' ');
+const makeRefusal = (name, detail) => ({
+  code: EXIT_REFUSED,
+  stdout: '',
+  stderr: `${name}: ${formatDetail(detail)}`,
+});
+const matchesEntire = (text, pattern) => text.match(pattern)?.[0] === text;
+const parseVersion = (version) => version.split('.').map((field) => BigInt(field));
+const compareVersions = (left, right) => {
+  const rightFields = parseVersion(right);
+  for (const [index, field] of parseVersion(left).entries()) {
+    if (field < rightFields[index]) {
+      return -1;
+    }
+    if (field > rightFields[index]) {
+      return 1;
+    }
+  }
+  return 0;
+};
+
+const judgeStamp = (stamp, head) => {
+  if (!matchesEntire(stamp, VERSION_PATTERN)) {
+    return makeRefusal('stamp-unparseable', 'expected one major.minor.patch version');
+  }
+  if (compareVersions(stamp, head) > 0) {
+    return makeRefusal('stamp-above-head', `${stamp} is newer than ${head}; never downgrade`);
+  }
+  return null;
+};
+
+const shouldIgnore = (name) => name.startsWith('.') || !name.endsWith(NOTE_SUFFIX);
+const parseNote = (entry) => {
+  const stem = entry.name.slice(0, -NOTE_SUFFIX.length);
+  const separator = stem.indexOf('-');
+  const version = stem.slice(0, separator);
+  const slug = stem.slice(separator + 1);
+  const valid = separator > 0 && matchesEntire(version, VERSION_PATTERN) && matchesEntire(slug, SLUG_PATTERN);
+  return { ...entry, version, valid };
+};
+
+const readHeadline = (text) => {
+  const line = text.split(LF).find((candidate) => candidate.startsWith(HEADLINE_PREFIX));
+  if (line === undefined) {
+    return null;
+  }
+  const content = (line.endsWith(CR) ? line.slice(0, -CR.length) : line).slice(HEADLINE_PREFIX.length);
+  return content.search(CONTROL_PATTERN) < 0 && content.trim() !== '' ? content.trim() : null;
+};
+
+const findDuplicate = (notes) => {
+  const versions = new Set();
+  for (const note of notes) {
+    const key = parseVersion(note.version).join('.');
+    if (versions.has(key)) {
+      return note;
+    }
+    versions.add(key);
+  }
+  return null;
+};
+
+// The caller has trimmed and judged the stamp; main judges every stamp cell before reading the notes directory.
+export const selectNotes = (stamp, entries, head) => {
+  const candidates = entries.filter(({ name }) => !shouldIgnore(name));
+  const unreadable = candidates.find(({ kind }) => kind === 'unreadable');
+  if (unreadable) {
+    return makeRefusal('notes-unreadable', `${unreadable.name}: ${unreadable.detail}`);
+  }
+  const parsed = candidates.map(parseNote);
+  const invalid = parsed.find(({ kind, name, valid }) => kind !== 'file' || (name !== README_NAME && !valid));
+  if (invalid) {
+    return makeRefusal('notes-entry', invalid.name);
+  }
+  const notes = parsed.filter(({ name }) => name !== README_NAME);
+  const aboveHead = notes.find(({ version }) => compareVersions(version, head) > 0);
+  if (aboveHead) {
+    return makeRefusal('note-above-head', `${aboveHead.name} is newer than ${head}`);
+  }
+  const duplicate = findDuplicate(notes);
+  if (duplicate) {
+    return makeRefusal('note-version-twice', duplicate.version);
+  }
+  const titled = notes.map((note) => ({ ...note, headline: readHeadline(note.text) }));
+  const untitled = titled.find(({ headline }) => headline === null);
+  if (untitled) {
+    return makeRefusal('note-headline', untitled.name);
+  }
+  const selected = titled
+    .filter(({ version }) => compareVersions(version, stamp) > 0 && compareVersions(version, head) <= 0)
+    .sort((left, right) => compareVersions(left.version, right.version));
+  const none = compareVersions(stamp, head) === 0
+    ? `none: stamp ${stamp} equals head ${head}; no note applies`
+    : `none: no notes newer than stamp ${stamp} through head ${head}`;
+  const lines = selected.map(({ version, path, headline }) => `note ${version} ${path} :: ${headline}`);
+  const ignored = entries.filter(({ name }) => shouldIgnore(name)).map(({ name }) => `ignored: ${formatDetail(name)}`);
+  return {
+    code: EXIT_ACCEPTED,
+    stdout: lines.length > 0 ? lines.join(LF) : none,
+    stderr: ignored.join(LF),
+  };
+};
+
+const probePath = (path, fs) => {
+  try {
+    const stat = fs.lstatSync(path);
+    if (stat.isSymbolicLink()) {
+      return { kind: 'symlink' };
+    }
+    if (stat.isFile()) {
+      return { kind: 'file' };
+    }
+    return { kind: stat.isDirectory() ? 'directory' : 'other' };
+  } catch (error) {
+    return { kind: error.code === 'ENOENT' ? 'absent' : 'unreadable', detail: error.message };
+  }
+};
+
+const readStamp = (path, fs) => {
+  const probe = probePath(path, fs);
+  if (probe.kind === 'absent') {
+    return { refusal: makeRefusal('stamp-absent', `${path}; use step 1 conservative re-bootstrap`) };
+  }
+  if (probe.kind !== 'file') {
+    return { refusal: makeRefusal('stamp-unreadable', `${path}: ${probe.detail ?? probe.kind}`) };
+  }
+  try {
+    return { text: fs.readFileSync(path, 'utf8') };
+  } catch (error) {
+    return { refusal: makeRefusal('stamp-unreadable', `${path}: ${error.message}`) };
+  }
+};
+
+const readEntry = (notesDir, name, fs) => {
+  const path = join(notesDir, name);
+  if (shouldIgnore(name)) {
+    return { name, path };
+  }
+  const probe = probePath(path, fs);
+  if (probe.kind !== 'file' || name === README_NAME) {
+    return { name, path, ...probe };
+  }
+  try {
+    return { name, path, kind: 'file', text: fs.readFileSync(path, 'utf8') };
+  } catch (error) {
+    return { name, path, kind: 'unreadable', detail: error.message };
+  }
+};
+
+const readNotes = (notesDir, fs) => {
+  const probe = probePath(notesDir, fs);
+  if (probe.kind === 'absent') {
+    return { refusal: makeRefusal('notes-absent', notesDir) };
+  }
+  if (probe.kind !== 'directory') {
+    return { refusal: makeRefusal('notes-unreadable', `${notesDir}: ${probe.detail ?? probe.kind}`) };
+  }
+  try {
+    return { entries: fs.readdirSync(notesDir).map((name) => readEntry(notesDir, name, fs)) };
+  } catch (error) {
+    return { refusal: makeRefusal('notes-unreadable', `${notesDir}: ${error.message}`) };
+  }
+};
+
+export const main = (argv, deps = {}) => {
+  const validUsage = argv.length === 2 && argv[0] === '--cwd'
+    && typeof argv[1] === 'string' && argv[1].trim() !== '' && !argv[1].startsWith('--');
+  if (!validUsage) {
+    return { code: EXIT_USAGE, stdout: '', stderr: 'usage: migration-notes.mjs --cwd <project>' };
+  }
+  const fs = {
+    lstatSync: deps.lstatSync ?? lstatSync,
+    readFileSync: deps.readFileSync ?? readFileSync,
+    readdirSync: deps.readdirSync ?? readdirSync,
+  };
+  const stamp = readStamp(resolve(argv[1], STAMP_PATH), fs);
+  if (stamp.refusal) {
+    return stamp.refusal;
+  }
+  const stampText = stamp.text.trim();
+  const stampRefusal = judgeStamp(stampText, EXPECTED_WORKFLOW_VERSION);
+  if (stampRefusal) {
+    return stampRefusal;
+  }
+  const notes = readNotes(resolve(deps.notesDir ?? NOTES_DIR), fs);
+  return notes.refusal ?? selectNotes(stampText, notes.entries, EXPECTED_WORKFLOW_VERSION);
+};
+
+if (isDirectRun(import.meta.url)) {
+  const result = await main(process.argv.slice(2));
+  if (result.stdout) {
+    console.log(result.stdout);
+  }
+  if (result.stderr) {
+    console.error(result.stderr);
+  }
+  process.exit(result.code);
+}

package/tools/payload-prune.mjs

@@ -0,0 +1,173 @@
+import { lstatSync, readdirSync, readFileSync, unlinkSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
+import { assertContainedRealPath } from './fs-safe.mjs';
+import { lstatNoFollowRead } from './fs-read-nofollow.mjs';
+
+const PREFIX = '[agent-workflow-kit]';
+const NON_CONVERGENCE = `${PREFIX} the kit home did not converge to the package (see the lines above) `
+  + '— fix them, then re-run npx @sabaiway/agent-workflow-kit@latest init';
+
+export const readHomeOwner = (home) => {
+  try {
+    const stat = lstatSync(home, { throwIfNoEntry: false });
+    if (stat === undefined) {
+      return 'absent';
+    }
+    if (!stat.isDirectory()) {
+      return 'other';
+    }
+    if (readdirSync(home).length === 0) {
+      return 'empty';
+    }
+    const skill = resolve(home, 'SKILL.md');
+    if (!lstatSync(skill).isFile()) {
+      return 'other';
+    }
+    const lines = readFileSync(skill, 'utf8').split('\n').map((line) => line.replace(/\r$/, ''));
+    if (lines[0] !== '---') {
+      return 'other';
+    }
+    const end = lines.findIndex((line, index) => index > 0 && line === '---');
+    if (end < 0) {
+      return 'other';
+    }
+    return lines.slice(1, end).some((line) => line.trimEnd() === 'name: agent-workflow-kit') ? 'kit' : 'other';
+  } catch {
+    return 'other';
+  }
+};
+
+export const assertInstallableHome = (home) => {
+  const owner = readHomeOwner(home);
+  if (owner === 'other') {
+    throw new Error(
+      `${PREFIX} refusing to install into ${home}: it is not empty and holds no agent-workflow-kit SKILL.md; `
+      + 'choose a new or empty folder, or an existing kit home',
+    );
+  }
+  return owner;
+};
+
+const describeKind = (stat) => {
+  if (stat.isSymbolicLink()) {
+    return 'symlink';
+  }
+  if (stat.isDirectory()) {
+    return 'directory';
+  }
+  return stat.isFile() ? 'file' : 'non-regular object';
+};
+
+const reportFailure = (path, error) => ({
+  ok: false,
+  line: `${PREFIX} failed ${path}: ${error.message}`,
+});
+
+const finishReport = (reports) => {
+  const ok = reports.every((report) => report.ok);
+  return {
+    ok,
+    lines: reports.map((report) => report.line),
+    nonConvergence: ok ? null : NON_CONVERGENCE,
+  };
+};
+
+const readTree = (root, entry, reports, directoryOnly = false) => {
+  const entries = new Map();
+  const visitEntry = (path, first = false) => {
+    try {
+      const absolute = resolve(root, path);
+      const stat = lstatSync(absolute, { throwIfNoEntry: !first });
+      if (!stat || (first && directoryOnly && !stat.isDirectory())) {
+        return;
+      }
+      const kind = describeKind(stat);
+      entries.set(path, kind);
+      if (kind === 'directory') {
+        for (const name of readdirSync(absolute).sort()) {
+          visitEntry(`${path}/${name}`);
+        }
+      }
+    } catch (error) {
+      reports.push(reportFailure(path, error));
+    }
+  };
+  try {
+    const stat = lstatSync(root, { throwIfNoEntry: false });
+    if (!stat) {
+      return entries;
+    }
+    if (!stat.isDirectory()) {
+      throw new Error(`the root is a ${describeKind(stat)}, not a real directory`);
+    }
+    visitEntry(entry, true);
+  } catch (error) {
+    reports.push(reportFailure(entry, error));
+  }
+  return entries;
+};
+
+const planSubtree = (carried, installed, orphans, reports) => {
+  for (const [path, kind] of installed) {
+    if (carried.has(path)) {
+      const packageKind = carried.get(path);
+      if (kind !== packageKind) {
+        reports.push({
+          ok: false,
+          line: `${PREFIX} kind-mismatch ${path}: the home holds a ${kind}, the package a ${packageKind}`,
+        });
+      }
+    } else if (kind === 'file') {
+      orphans.push(path);
+    } else {
+      reports.push({
+        ok: true,
+        line: `${PREFIX} kept ${path} (a ${kind} the package does not carry — yours to remove by hand)`,
+      });
+    }
+  }
+};
+
+const removeOrphan = (home, path, remove) => {
+  const absolute = resolve(home, path);
+  try {
+    remove.assertContainedRealPath(home, absolute);
+    const stat = remove.lstatNoFollowRead(absolute);
+    if (stat === null) {
+      return [];
+    }
+    if (!stat.isFile()) {
+      throw new Error('the leaf is no longer a regular file');
+    }
+    remove.unlinkSync(absolute);
+    return [{ ok: true, line: `${PREFIX} removed ${path} (not in the package)` }];
+  } catch (error) {
+    return [reportFailure(path, error)];
+  }
+};
+
+export const prunePayload = ({ packageRoot, home, payload }, deps = {}) => {
+  const reports = [];
+  const orphans = [];
+  for (const entry of new Set(payload)) {
+    const path = entry.split(sep).join('/');
+    const carried = readTree(packageRoot, path, reports, true);
+    if (![...carried.values()].includes('file')) {
+      continue;
+    }
+    const installed = readTree(home, path, reports);
+    planSubtree(carried, installed, orphans, reports);
+  }
+  if (reports.some((report) => !report.ok)) {
+    return finishReport(reports);
+  }
+  const remove = {
+    assertContainedRealPath: deps.assertContainedRealPath ?? assertContainedRealPath,
+    lstatNoFollowRead: deps.lstatNoFollowRead ?? lstatNoFollowRead,
+    unlinkSync: deps.unlinkSync ?? unlinkSync,
+  };
+  for (const path of orphans) {
+    reports.push(...removeOrphan(home, path, remove));
+  }
+  return finishReport(reports);
+};

package/tools/profile-gaps.mjs

@@ -0,0 +1,90 @@
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  RULES_REGIONS,
+  extractRegionBy,
+  readTemplateSpan,
+  planInsert,
+  frontmatterMaxLines,
+  decodeUtf8Strict,
+} from './rules-regions.mjs';
+
+const GAP_ID = 'story-sessions-section';
+const STORY_ID = 'story-sessions';
+const TEMPLATE_CANON = 'template';
+const ENCODING = 'utf8';
+const MISSING_FILE_CODE = 'ENOENT';
+const SINGLE_HEADING = 1;
+const TARGET_PATH = 'docs/ai/agent_rules.md';
+const TEMPLATE_PATH = fileURLToPath(new URL('../references/templates/agent_rules.md', import.meta.url));
+const INSERT_PATH = fileURLToPath(new URL('./rules-insert.mjs', import.meta.url));
+const COMMAND_PREFIX = 'node ';
+const CWD_FLAG = ' --cwd ';
+const VERDICTS = Object.freeze({
+  present: 'present',
+  absent: 'absent',
+  undecidable: 'undecidable',
+});
+const REASONS = Object.freeze({
+  template: 'template',
+  fileAbsent: 'file-absent',
+  fileSymlink: 'file-symlink',
+  fileUnreadable: 'file-unreadable',
+});
+const TEMPLATE_REGIONS = RULES_REGIONS.filter(({ canon }) => canon === TEMPLATE_CANON);
+const STORY_REGION = RULES_REGIONS.find(({ id }) => id === STORY_ID);
+
+const reportUndecidable = (reason) => ({ verdict: VERDICTS.undecidable, reason });
+
+const readSpans = (deps) => {
+  try {
+    const template = deps.readFileSync(TEMPLATE_PATH, ENCODING);
+    const entries = TEMPLATE_REGIONS.map(({ id, headingRe }) => [
+      id, readTemplateSpan(template, headingRe),
+    ]);
+    const spans = Object.fromEntries(entries);
+    if (Object.values(spans).some(({ defect }) => defect)) {
+      return reportUndecidable(REASONS.template);
+    }
+    return { spans };
+  } catch {
+    return reportUndecidable(REASONS.template);
+  }
+};
+
+const readTarget = (root, deps) => {
+  const target = resolve(root, TARGET_PATH);
+  try {
+    const stat = deps.lstatSync(target);
+    if (stat.isSymbolicLink()) return reportUndecidable(REASONS.fileSymlink);
+    if (!stat.isFile()) return reportUndecidable(REASONS.fileUnreadable);
+  } catch (error) {
+    const reason = error?.code === MISSING_FILE_CODE ? REASONS.fileAbsent : REASONS.fileUnreadable;
+    return reportUndecidable(reason);
+  }
+  try {
+    return { text: decodeUtf8Strict(deps.readFileSync(target)) };
+  } catch {
+    return reportUndecidable(REASONS.fileUnreadable);
+  }
+};
+
+const detectStorySessions = ({ root, deps }) => {
+  const template = readSpans(deps);
+  if (template.verdict) return template;
+  const target = readTarget(root, deps);
+  if (target.verdict) return target;
+  const { text } = target;
+  if (extractRegionBy(text, STORY_REGION.headingRe).count === SINGLE_HEADING) {
+    return { verdict: VERDICTS.present };
+  }
+  const result = planInsert({ text, spans: template.spans, cap: frontmatterMaxLines(text) });
+  if (result.refusal) return reportUndecidable(result.refusal);
+  return { verdict: VERDICTS.absent };
+};
+
+const buildInsertPreview = (root) => COMMAND_PREFIX + INSERT_PATH + CWD_FLAG + root;
+
+export const PROFILE_GAPS = Object.freeze([
+  Object.freeze({ id: GAP_ID, detect: detectStorySessions, apply: buildInsertPreview }),
+]);