ma-agents 3.5.5 → 3.6.0

package/lib/installer.js

@@ -8,6 +8,205 @@ const MANIFEST_FILE = '.ma-agents.json';
 const MANIFEST_VERSION = '1.2.0';
 const MA_AGENTS_SOURCE = 'ma-agents';
 const TEMPLATE_PATH = path.join(__dirname, 'templates', 'project-context.template.md');
+const UNIVERSAL_INSTRUCTION_TEMPLATE_PATH = path.join(__dirname, 'templates', 'instruction-block-universal.template.md');
+const ONPREM_INSTRUCTION_TEMPLATE_PATH = path.join(__dirname, 'templates', 'instruction-block-onprem.template.md');
+const CLINERULES_TEMPLATE_PATH = path.join(__dirname, 'templates', 'clinerules.template.md');
+const EXTRA_TEMPLATE_DIR = path.join(__dirname, 'templates');
+
+/**
+ * Story 21.5 AC #6 — Dual-file drift detection error.
+ *
+ * Thrown by the installer when the in-marker contents of `.cline/clinerules.md`
+ * and `.clinerules` diverge (non-whitespace diff). `--yes` does NOT bypass this
+ * check — reconciliation between the two Cline rule files is user work, and
+ * silently picking a "winner" could discard intentional edits.
+ *
+ * Follows the error-class naming pattern introduced by Story 21.3/21.10's
+ * RoomodesSlugDivergenceError.
+ */
+class ClinerulesDualFileDriftError extends Error {
+  constructor({ fileA, fileB, diff }) {
+    const header = `Cline dual-file drift detected between ${fileA} and ${fileB}.`;
+    const guidance = 'Reconcile the two files manually (copy the correct marker-block content into both) before re-running install. `--yes` does NOT bypass this check.';
+    super(`${header}\n${guidance}\n\n--- diff (${fileA} vs. ${fileB}) ---\n${diff}`);
+    this.name = 'ClinerulesDualFileDriftError';
+    this.fileA = fileA;
+    this.fileB = fileB;
+    this.diff = diff;
+  }
+}
+
+/**
+ * Extract the content between MA-AGENTS markers in a file, without the marker
+ * lines themselves. Returns null when the file does not exist OR has no marker
+ * pair. Whitespace-only leading/trailing runs inside the block are preserved —
+ * caller decides whether to normalize before comparing.
+ */
+function _extractMarkerBlockInner(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const m = content.match(/<!-- MA-AGENTS-START -->([\s\S]*?)<!-- MA-AGENTS-END -->/);
+  if (!m) return null;
+  return m[1];
+}
+
+/**
+ * Story 21.5 AC #6 — Compare in-marker content of `.cline/clinerules.md` and
+ * `.clinerules` (when both exist). Non-whitespace divergence throws
+ * ClinerulesDualFileDriftError. If only one file exists, drift detection is
+ * skipped (AC #6, Task 3.4 "render once, write twice" invariant).
+ *
+ * Exposed for tests via module.exports; called internally by
+ * updateAgentInstructions on the Cline agent path.
+ */
+function checkClinerulesDualFileDrift(projectRoot) {
+  const pathA = path.join(projectRoot, '.cline', 'clinerules.md');
+  const pathB = path.join(projectRoot, '.clinerules');
+  const innerA = _extractMarkerBlockInner(pathA);
+  const innerB = _extractMarkerBlockInner(pathB);
+  if (innerA == null || innerB == null) return; // one (or both) absent — skip
+  const normalize = (s) => s.replace(/\s+/g, ' ').trim();
+  if (normalize(innerA) === normalize(innerB)) return;
+  // Build a minimal unified diff (line-level) for the message.
+  const linesA = innerA.split('\n');
+  const linesB = innerB.split('\n');
+  const diffLines = [];
+  const maxLen = Math.max(linesA.length, linesB.length);
+  for (let i = 0; i < maxLen; i++) {
+    const a = linesA[i];
+    const b = linesB[i];
+    if (a === b) continue;
+    if (a !== undefined) diffLines.push(`- ${a}`);
+    if (b !== undefined) diffLines.push(`+ ${b}`);
+  }
+  throw new ClinerulesDualFileDriftError({
+    fileA: path.relative(projectRoot, pathA).replace(/\\/g, '/'),
+    fileB: path.relative(projectRoot, pathB).replace(/\\/g, '/'),
+    diff: diffLines.join('\n')
+  });
+}
+
+// Story 21.4 — memoize resolved BMAD-output dirs per projectRoot so the
+// install loop resolves once (AC #10c) and logs once.
+const _bmadOutputDirsCache = new Map();
+const _bmadOutputDirsLogged = new Set();
+
+/**
+ * Story 21.2 — Universal per-tool instruction block composer.
+ *
+ * Reads lib/templates/instruction-block-universal.template.md (always).
+ * If profile === 'on-prem', appends lib/templates/instruction-block-onprem.template.md
+ * separated by a single blank line. If the on-prem template is missing when required,
+ * THROWS — there is no silent fallback (Decision A, AC #3).
+ *
+ * Templates contain NO substitution of {{...}} placeholders inside this function; any
+ * substitution (e.g., {{MANIFEST_PATH}}) is the caller's responsibility, applied AFTER
+ * composition. This keeps the composer a single-owner entry point that downstream
+ * stories 21.3/21.4/21.5/21.6 consume without duplication.
+ *
+ * @param {{profile: string|undefined, projectRoot: string}} args
+ * @returns {string} composed template content (with placeholders intact)
+ */
+function composeInstructionBlock({ profile, projectRoot } = {}) {
+  // projectRoot is accepted for API-stability with downstream stories even though
+  // the current implementation does not read from it (templates ship with the
+  // package). Keeping the parameter documented avoids signature churn in 21.6.
+  void projectRoot;
+
+  let universal;
+  try {
+    universal = fs.readFileSync(UNIVERSAL_INSTRUCTION_TEMPLATE_PATH, 'utf-8');
+  } catch (err) {
+    throw new Error(
+      `universal instruction template not found at ${UNIVERSAL_INSTRUCTION_TEMPLATE_PATH} — ma-agents installation may be corrupted: ${err.message}`
+    );
+  }
+
+  if (!universal.includes('{{MANIFEST_PATH}}')) {
+    throw new Error(
+      `universal instruction template at ${UNIVERSAL_INSTRUCTION_TEMPLATE_PATH} is missing the required {{MANIFEST_PATH}} placeholder`
+    );
+  }
+
+  if (profile === 'on-prem') {
+    if (!fs.existsSync(ONPREM_INSTRUCTION_TEMPLATE_PATH)) {
+      throw new Error('on-prem profile selected but instruction-block-onprem.template.md is missing');
+    }
+    const onprem = fs.readFileSync(ONPREM_INSTRUCTION_TEMPLATE_PATH, 'utf-8');
+    // Normalize both pieces so the concatenation has exactly one blank line between them
+    // and no trailing whitespace — feeds NFR46 byte-identity.
+    return universal.replace(/\s+$/, '') + '\n\n' + onprem.replace(/\s+$/, '') + '\n';
+  }
+
+  // Normalize trailing whitespace so first-insert and in-place-replace both
+  // produce byte-identical content inside the markers (NFR46, AC #6).
+  return universal.replace(/\s+$/, '') + '\n';
+}
+
+/**
+ * Story 21.4 AC #10 — resolve BMAD output directories once per install.
+ *
+ * Precedence:
+ *   a) If `_bmad/bmm/config.yaml` exists AND has explicit `planning_artifacts`,
+ *      `architecture_artifacts`, and `implementation_artifacts`, use those.
+ *   b) Otherwise, fall back to the documented defaults:
+ *        planning:       _bmad-output/planning-artifacts
+ *        architecture:   _bmad-output/planning-artifacts (co-located default)
+ *        stories:        _bmad-output/implementation-artifacts
+ *
+ * YAML parsing is intentionally minimal — we only need a handful of
+ * top-level scalar keys. Adding a full YAML dependency just for this is
+ * overkill and would widen the supply chain for one helper.
+ *
+ * @param {string} projectRoot
+ * @returns {{planning: string, architecture: string, stories: string}}
+ */
+function resolveBmadOutputDirs(projectRoot) {
+  if (_bmadOutputDirsCache.has(projectRoot)) {
+    return _bmadOutputDirsCache.get(projectRoot);
+  }
+
+  const defaults = {
+    planning: '_bmad-output/planning-artifacts',
+    architecture: '_bmad-output/planning-artifacts',
+    stories: '_bmad-output/implementation-artifacts'
+  };
+
+  const configPath = path.join(projectRoot, '_bmad', 'bmm', 'config.yaml');
+  const dirs = { ...defaults };
+
+  if (fs.existsSync(configPath)) {
+    try {
+      const yamlText = fs.readFileSync(configPath, 'utf-8');
+      const scanScalar = (key) => {
+        // Match `key: "value"` or `key: value` at line start (indent tolerated),
+        // ignoring commented lines. Value is the quoted string or the bare token.
+        const re = new RegExp(`^[\\t ]*${key}\\s*:\\s*(?:"([^"]*)"|'([^']*)'|([^#\\n\\r]+?))\\s*(?:#.*)?$`, 'm');
+        const m = yamlText.match(re);
+        if (!m) return null;
+        const raw = m[1] || m[2] || m[3] || '';
+        return raw.trim().replace(/\\/g, '/');
+      };
+      const planning = scanScalar('planning_artifacts');
+      const architecture = scanScalar('architecture_artifacts');
+      const stories = scanScalar('implementation_artifacts');
+      if (planning) dirs.planning = planning;
+      if (architecture) dirs.architecture = architecture;
+      if (stories) dirs.stories = stories;
+    } catch {
+      // Malformed or unreadable config — fall back silently to defaults.
+    }
+  }
+
+  _bmadOutputDirsCache.set(projectRoot, dirs);
+  if (!_bmadOutputDirsLogged.has(projectRoot)) {
+    _bmadOutputDirsLogged.add(projectRoot);
+    console.log(
+      `Resolved BMAD output dirs: planning=${dirs.planning}, architecture=${dirs.architecture}, stories=${dirs.stories}`
+    );
+  }
+  return dirs;
+}
 
 // Claude Code hook configuration for MANIFEST verification
 const CLAUDE_CODE_HOOK_ID = 'ma-agents-verify-manifest';
@@ -355,9 +554,279 @@ function findInsertionPoint(content, skipPatterns) {
   return idx;
 }
 
-async function updateAgentInstructions(agent, projectRoot) {
+/**
+ * Story 21.2 AC #10 — canonical backup filename format.
+ * Format: <target>.backup-<ISO-8601-timestamp> with colons replaced by hyphens
+ * for Windows filename safety (e.g., .claude/CLAUDE.md.backup-2026-04-15T12-30-00Z).
+ * Story 21.2 OWNS this format; stories 21.10 (reconfigure) and 21.11 (uninstall)
+ * consume it. The date source is injectable to keep tests deterministic.
+ */
+function formatBackupTimestamp(date = new Date()) {
+  // ISO 8601 with hyphens instead of colons and no milliseconds:
+  // 2026-04-15T12-30-00Z
+  return date.toISOString().replace(/\.\d{3}Z$/, 'Z').replace(/:/g, '-');
+}
+
+function buildBackupFilename(targetPath, date = new Date()) {
+  const base = `${targetPath}.backup-${formatBackupTimestamp(date)}`;
+  // Guard against sub-second re-runs clobbering a prior backup. If the canonical
+  // name already exists on disk, append a ".N" suffix until we find a free slot.
+  if (!fs.existsSync(base)) return base;
+  let i = 1;
+  while (fs.existsSync(`${base}.${i}`)) i++;
+  return `${base}.${i}`;
+}
+
+/**
+ * Story 21.2 AC #10 — marker-block drift handler.
+ *
+ * Called when the existing in-marker content differs from what
+ * composeInstructionBlock would produce for the current profile. In interactive
+ * mode (no --yes), prompts the user for confirmation. With --yes or when stdin
+ * is not a TTY, emits the pinned WARNING line and proceeds. In all drift cases
+ * where we proceed with the overwrite, a backup sibling file is written
+ * containing ONLY the marker-block region (markers included).
+ *
+ * Throws if the user declines the interactive prompt, short-circuiting the
+ * write in the caller.
+ */
+async function handleMarkerBlockDrift({ filePath, existingBlock, expectedBlock, yesMode }) {
+  const backupPath = buildBackupFilename(filePath);
+
+  // In non-interactive mode (yes mode or non-TTY), emit pinned warning and proceed.
+  // In interactive mode, show diff preview and prompt for confirmation.
+  const interactive = !yesMode && process.stdin.isTTY;
+
+  if (interactive) {
+    // Show a compact diff-style preview. We intentionally do not require a diff
+    // library — the on-screen diff is informational only.
+    console.log(chalk.yellow(`\nma-agents marker-block in ${filePath} was modified since last install.`));
+    console.log(chalk.gray('--- current on-disk (inside markers) ---'));
+    console.log(existingBlock);
+    console.log(chalk.gray('--- expected (ma-agents) ---'));
+    console.log(expectedBlock);
+    const { proceed } = await prompts({
+      type: 'confirm',
+      name: 'proceed',
+      message: `Overwrite and back up previous content to ${backupPath}?`,
+      initial: false
+    });
+    if (!proceed) {
+      throw new Error(`User declined to overwrite ma-agents marker block in ${filePath}`);
+    }
+  } else {
+    // AC #10 pinned WARNING line (verbatim).
+    console.log(
+      `WARNING: ma-agents marker-block content modified since last install — overwriting. Previous content backed up to ${backupPath}`
+    );
+  }
+
+  // Backup contains only the marker-block region (markers included).
+  await fs.outputFile(backupPath, existingBlock, 'utf-8');
+}
+
+/**
+ * Story 21.4 — markdown-markers merger for extraInstructionTemplates.
+ *
+ * Writes a marker-wrapped instruction block into a markdown target file. This
+ * is the same marker-wrap contract used by updateAgentInstructions for
+ * single-instructionFile agents (AC #5), lifted into a reusable helper so the
+ * extraInstructionTemplates processor can dispatch on merger = 'markdown-markers'.
+ *
+ * Behavior (AC #5):
+ *   - If target file does not exist: create it by writing the full template
+ *     contents (including the leading "Generated by ma-agents" comment and
+ *     the markers), with `composedBlock` placed between the MA-AGENTS markers.
+ *   - If target exists with markers: replace in-marker content only; content
+ *     outside markers is preserved byte-for-byte. Hand-edit drift detection
+ *     (AC #11) uses the same handleMarkerBlockDrift helper as Story 21.2.
+ *   - If target exists WITHOUT markers: append the marker block at EOF
+ *     separated by one blank line. Existing content preserved.
+ *
+ * @param {string} targetPath - absolute path to the target file
+ * @param {string} templateBody - static template text (from lib/templates/)
+ * @param {string} composedBlock - the output of composeInstructionBlock(...)
+ * @param {{ yesMode?: boolean }} opts
+ * @returns {Promise<'created'|'updated'|'appended'|'skipped'>}
+ */
+async function markdownMarkersMerger(targetPath, templateBody, composedBlock, opts = {}) {
+  const markerStart = '<!-- MA-AGENTS-START -->';
+  const markerEnd = '<!-- MA-AGENTS-END -->';
+  const yesMode = !!(opts.yesMode || process.env.MA_AGENTS_YES === '1');
+
+  // Normalize composedBlock trailing whitespace once so first-insert and
+  // in-place-replace both produce byte-identical in-marker content (NFR46).
+  const normalized = composedBlock.replace(/\s+$/, '') + '\n';
+  const wrappedBlock = `${markerStart}\n${normalized}${markerEnd}`;
+
+  if (!fs.existsSync(targetPath)) {
+    // AC #5 first bullet: fresh create — write leading comment + template, with
+    // markers replaced to carry the composed content.
+    const leadingComment = '<!-- Generated by ma-agents. Edit outside the MA-AGENTS-START/END markers to preserve your changes. -->\n';
+    // The template already contains placeholder empty markers ("<!-- MA-AGENTS-START -->\n<!-- MA-AGENTS-END -->").
+    // Replace the first such pair with the wrapped block. If the template has no markers,
+    // the block is appended at EOF separated by one blank line (defensive — template ships with markers).
+    const emptyMarkerPair = new RegExp(`${markerStart}\\s*\\n\\s*${markerEnd}`);
+    let body;
+    if (emptyMarkerPair.test(templateBody)) {
+      body = templateBody.replace(emptyMarkerPair, wrappedBlock);
+    } else {
+      const trimmed = templateBody.replace(/\s+$/, '');
+      body = trimmed + '\n\n' + wrappedBlock + '\n';
+    }
+    // Ensure single trailing newline.
+    const finalBody = body.replace(/\s+$/, '') + '\n';
+    await fs.outputFile(targetPath, leadingComment + finalBody, 'utf-8');
+    console.log(chalk.cyan(`    + Created ${path.relative(path.dirname(targetPath), targetPath) === path.basename(targetPath) ? path.basename(targetPath) : targetPath}`));
+    return 'created';
+  }
+
+  const content = await fs.readFile(targetPath, 'utf-8');
+  const regex = new RegExp(`${markerStart}[\\s\\S]*?${markerEnd}`);
+  const existingMatch = content.match(regex);
+
+  if (existingMatch) {
+    // AC #5 second bullet + AC #11 drift detection.
+    const existingBlock = existingMatch[0];
+    if (existingBlock === wrappedBlock) {
+      // Byte-identical — idempotent no-op write to preserve mtime semantics would be
+      // wasteful; just return. Outside-markers content is unchanged.
+      return 'skipped';
+    }
+    // Drift: previous content differs from expected.
+    try {
+      await handleMarkerBlockDrift({
+        filePath: targetPath,
+        existingBlock,
+        expectedBlock: wrappedBlock,
+        yesMode
+      });
+    } catch (declineErr) {
+      console.log(chalk.gray(`    Skipped ${path.basename(targetPath)} (user declined marker-block overwrite)`));
+      return 'skipped';
+    }
+    const replaced = content.replace(regex, wrappedBlock);
+    await fs.writeFile(targetPath, replaced, 'utf-8');
+    console.log(chalk.cyan(`    + Updated ${path.basename(targetPath)}`));
+    return 'updated';
+  }
+
+  // AC #5 third bullet: existing file, no markers — append marker block at EOF
+  // separated by one blank line.
+  const base = content.replace(/\s+$/, '');
+  const appended = (base.length ? base + '\n\n' : '') + wrappedBlock + '\n';
+  await fs.writeFile(targetPath, appended, 'utf-8');
+  console.log(chalk.cyan(`    + Appended marker block to ${path.basename(targetPath)}`));
+  return 'appended';
+}
+
+/**
+ * Story 21.4 — process extraInstructionTemplates entries on an agent.
+ *
+ * For each { template, target, merger } entry:
+ *   1. Resolve the source template file under lib/templates/.
+ *   2. Call composeInstructionBlock({ profile, projectRoot }) exactly once per
+ *      entry (canonical composer contract — Story 21.2, decision A).
+ *   3. Dispatch on `merger`:
+ *        - 'markdown-markers' → markdownMarkersMerger (this story)
+ *        - 'yaml-customModes' → reserved for Story 21.3 (.roomodes)
+ *   4. Per-entry MANIFEST_PATH substitution is applied to the composed string
+ *      BEFORE the merger receives it (caller-owned per Story 21.2 AC #3).
+ *
+ * @param {object} agent - lib/agents.js entry
+ * @param {string} projectRoot
+ * @param {{ yesMode?: boolean }} opts
+ */
+async function stampExtraInstructionTemplates(agent, projectRoot, opts = {}) {
+  if (!Array.isArray(agent.extraInstructionTemplates) || agent.extraInstructionTemplates.length === 0) {
+    return;
+  }
+
+  // Resolve BMAD output dirs once per projectRoot (memoized + logged once).
+  resolveBmadOutputDirs(projectRoot);
+
+  const { getProfile } = require('./profile');
+  const resolvedProfile = getProfile(projectRoot) || 'standard';
+  const agentProjectPath = agent.getProjectPath();
+  const relManifestPath = path.relative(projectRoot, path.join(agentProjectPath, 'MANIFEST.yaml')).replace(/\\/g, '/');
+
+  for (const entry of agent.extraInstructionTemplates) {
+    if (!entry || !entry.template || !entry.target || !entry.merger) {
+      console.log(chalk.yellow(`    Warning: malformed extraInstructionTemplates entry on ${agent.id}, skipping`));
+      continue;
+    }
+    const templatePath = path.join(EXTRA_TEMPLATE_DIR, entry.template);
+    if (!fs.existsSync(templatePath)) {
+      console.log(chalk.yellow(`    Warning: template not found at ${templatePath}, skipping`));
+      continue;
+    }
+    const templateBody = fs.readFileSync(templatePath, 'utf-8');
+
+    // Canonical composer contract: called exactly once per artifact.
+    let composed = composeInstructionBlock({ profile: resolvedProfile, projectRoot });
+    // Post-composition substitution is caller-owned (Story 21.2 AC #3).
+    composed = composed.replace(/\{\{MANIFEST_PATH\}\}/g, relManifestPath);
+
+    const targetPath = path.join(projectRoot, entry.target);
+
+    if (entry.merger === 'markdown-markers') {
+      await markdownMarkersMerger(targetPath, templateBody, composed, { yesMode: opts.yesMode });
+    } else if (entry.merger === 'yaml-customModes') {
+      // Story 21.3 — .roomodes YAML splice. The template contains
+      // {{UNIVERSAL_BLOCK}} sentinels that must be expanded with the
+      // composed block BEFORE the merger (caller-owned substitution, AC #2/#4).
+      // Indent-preserving expansion keeps each line of the multi-line block
+      // aligned with the YAML block-scalar indent of the sentinel.
+      const composedTemplate = templateBody.replace(
+        /^([ \t]*)\{\{UNIVERSAL_BLOCK\}\}/gm,
+        (_m, indent) => composed
+          .replace(/\s+$/, '')
+          .split('\n')
+          .map(line => indent + line)
+          .join('\n')
+      );
+      const { mergeRoomodes } = require('./merge/roomodes');
+      const existingYaml = fs.existsSync(targetPath)
+        ? fs.readFileSync(targetPath, 'utf-8')
+        : '';
+      const mergedContent = mergeRoomodes(existingYaml, composedTemplate);
+
+      // Backup if the target exists and content differs (Story 21.2 canonical format).
+      if (fs.existsSync(targetPath)) {
+        const existing = fs.readFileSync(targetPath, 'utf-8');
+        if (existing !== mergedContent) {
+          const backupPath = buildBackupFilename(targetPath);
+          await fs.outputFile(backupPath, existing, 'utf-8');
+        }
+      }
+
+      const tmpPath = targetPath + '.tmp';
+      await fs.outputFile(tmpPath, mergedContent, 'utf-8');
+      await fs.rename(tmpPath, targetPath);
+      console.log(chalk.cyan(`    + Updated ${entry.target}`));
+    } else {
+      console.log(chalk.yellow(`    Warning: unknown merger '${entry.merger}' for ${agent.id}, skipping ${entry.target}`));
+    }
+  }
+}
+
+async function updateAgentInstructions(agent, projectRoot, opts = {}) {
   if (!agent.instructionFiles || agent.instructionFiles.length === 0) return;
 
+  // Story 21.2 — yesMode resolution (AC #10): explicit opts.yesMode wins,
+  // fall back to MA_AGENTS_YES env var (used by tests and subprocess flows).
+  // The CLI passes yesMode via opts when --yes is set so non-interactive
+  // installs do not hang on the drift-confirmation prompt.
+  const yesMode = !!(opts.yesMode || process.env.MA_AGENTS_YES === '1');
+
+  // Story 21.2 — resolve profile once per stamped artifact; compose the universal
+  // (+ on-prem when applicable) block once; mergers consume the already-composed string.
+  // Lazy require avoids potential circular-import pitfalls at module load (profile.js
+  // already lazy-requires installer for the ensureManifest bootstrap path).
+  const { getProfile } = require('./profile');
+  const resolvedProfile = getProfile(projectRoot) || 'standard';
+  const composedTemplate = composeInstructionBlock({ profile: resolvedProfile, projectRoot });
+
   // JSON merge strategy (e.g., OpenCode)
   // OpenCode expects instructions to be plain strings, not objects.
   // We identify our entries by a marker prefix in the string content,
@@ -367,63 +836,103 @@ async function updateAgentInstructions(agent, projectRoot) {
     const filePath = path.join(projectRoot, agent.instructionFiles[0]);
     const agentProjectPath = agent.getProjectPath();
     const relManifestPath = path.relative(projectRoot, path.join(agentProjectPath, 'MANIFEST.yaml')).replace(/\\/g, '/');
-    const instructionText = `[${MA_AGENTS_SOURCE}] # AI Agent Skills - Planning Instruction\n\nYou have access to a library of skills in your skills directory. Before starting any task:\n\n1. Read the skill manifest at ${relManifestPath}\n2. Based on the task description, select which skills are relevant\n3. Read only the selected skill files\n4. Then proceed with the task\n\nAlways load skills marked with always_load: true.\nDo not load skills that are not relevant to the current task.`;
+    // Story 21.2 — substitute {{MANIFEST_PATH}} AFTER composition (caller-owned, per AC #3).
+    // Prefix with [ma-agents] tag so the isMaEntry filter identifies the entry on re-install.
+    const instructionBody = composedTemplate.replace(/\{\{MANIFEST_PATH\}\}/g, relManifestPath);
+    const instructionText = `[${MA_AGENTS_SOURCE}] ${instructionBody}`.replace(/\s+$/, '');
 
     const isMaEntry = (entry) =>
       (typeof entry === 'string' && entry.startsWith(`[${MA_AGENTS_SOURCE}]`)) ||
       (typeof entry === 'object' && entry != null && entry._source === MA_AGENTS_SOURCE);
 
+    // Story 21.4 AC #6, #7 — collect any extra path-string entries that must be
+    // appended to the JSON array (e.g., literal "AGENTS.md" for OpenCode). These
+    // entries are USER-OWNED after first install (no [ma-agents] prefix → the
+    // isMaEntry filter does NOT match them → never re-appended, never removed
+    // by subsequent installs). Dedup uses strict string equality per AC #6.
+    const extraJsonEntries = [];
+    if (Array.isArray(agent.extraInstructionTemplates)) {
+      for (const tpl of agent.extraInstructionTemplates) {
+        if (tpl && tpl.merger === 'markdown-markers' && typeof tpl.target === 'string') {
+          extraJsonEntries.push(tpl.target);
+        }
+      }
+    }
+
     if (!fs.existsSync(filePath)) {
       // File absent: create fresh (atomic write)
-      const data = { [targetKey]: [instructionText] };
+      const data = { [targetKey]: [instructionText, ...extraJsonEntries] };
       const tmpPath = filePath + '.tmp';
       await fs.outputFile(tmpPath, JSON.stringify(data, null, 2), 'utf-8');
       await fs.rename(tmpPath, filePath);
       console.log(chalk.cyan(`    + Created ${agent.instructionFiles[0]}`));
-      return;
-    }
-    // File present: read and merge
-    try {
-      const content = await fs.readFile(filePath, 'utf-8');
-      const data = JSON.parse(content);
-      if (!Array.isArray(data[targetKey])) {
-        data[targetKey] = [];
+      // Continue to stamp extra templates below (e.g., AGENTS.md).
+    } else {
+      // File present: read and merge
+      try {
+        const content = await fs.readFile(filePath, 'utf-8');
+        const data = JSON.parse(content);
+        if (!Array.isArray(data[targetKey])) {
+          data[targetKey] = [];
+        }
+        // Filter out stale ma-agents entries (string or legacy object format), keep user entries
+        const userEntries = data[targetKey].filter(entry => entry != null && !isMaEntry(entry));
+        // Story 21.4 AC #6 — append extraJsonEntries (e.g., "AGENTS.md") using strict
+        // string-equality dedup against userEntries so pre-existing user additions
+        // are not duplicated. AC #7: entries lack the [ma-agents] prefix and are
+        // therefore user-owned after first install.
+        const missingExtras = extraJsonEntries.filter(e => !userEntries.includes(e));
+        data[targetKey] = [...userEntries, instructionText, ...missingExtras];
+        // Atomic write: temp file then rename
+        const tmpPath = filePath + '.tmp';
+        await fs.outputFile(tmpPath, JSON.stringify(data, null, 2), 'utf-8');
+        await fs.rename(tmpPath, filePath);
+        console.log(chalk.cyan(`    + Updated ${agent.instructionFiles[0]}`));
+      } catch (err) {
+        console.error(`[${MA_AGENTS_SOURCE}] ERROR: Could not parse ${filePath} — ${err.message}. File not modified.`);
+        return; // non-fatal: do NOT re-throw
       }
-      // Filter out stale ma-agents entries (string or legacy object format), keep user entries
-      const userEntries = data[targetKey].filter(entry => entry != null && !isMaEntry(entry));
-      data[targetKey] = [...userEntries, instructionText];
-      // Atomic write: temp file then rename
-      const tmpPath = filePath + '.tmp';
-      await fs.outputFile(tmpPath, JSON.stringify(data, null, 2), 'utf-8');
-      await fs.rename(tmpPath, filePath);
-      console.log(chalk.cyan(`    + Updated ${agent.instructionFiles[0]}`));
-    } catch (err) {
-      console.error(`[${MA_AGENTS_SOURCE}] ERROR: Could not parse ${filePath} — ${err.message}. File not modified.`);
-      return; // non-fatal: do NOT re-throw
     }
+
+    // Story 21.4 — stamp any extraInstructionTemplates (e.g., AGENTS.md) after
+    // the JSON-merge branch. This path does not fall through to the markdown
+    // marker-wrap below because `instructionFiles: ['opencode.json']` is JSON.
+    await stampExtraInstructionTemplates(agent, projectRoot, { yesMode });
     return;
   }
 
   const agentProjectPath = agent.getProjectPath();
   const relManifestPath = path.relative(projectRoot, path.join(agentProjectPath, 'MANIFEST.yaml')).replace(/\\/g, '/');
 
-  const planningInstruction = `
-# AI Agent Skills - Planning Instruction
-
-You have access to a library of skills in your skills directory. Before starting any task:
-
-1. Read the skill manifest at ${relManifestPath}
-2. Based on the task description, select which skills are relevant
-3. Read only the selected skill files
-4. Then proceed with the task
-
-Always load skills marked with always_load: true.
-Do not load skills that are not relevant to the current task.
-`;
+  // Story 21.2 — replace the previously-hardcoded planningInstruction with the
+  // composed block. {{MANIFEST_PATH}} substitution happens AFTER composition
+  // (caller-owned per AC #3). The leading "\n" preserves the historical shape
+  // of the wrapped instruction so existing markers keep the same layout.
+  const planningInstruction = '\n' + composedTemplate.replace(/\{\{MANIFEST_PATH\}\}/g, relManifestPath);
 
   const markerStart = '<!-- MA-AGENTS-START -->';
   const markerEnd = '<!-- MA-AGENTS-END -->';
-  const wrappedInstruction = `${markerStart}${planningInstruction}${markerEnd}\n`;
+  // NFR46: normalize once so first-insert and in-place-replace produce
+  // byte-identical marker-block content. Both paths now use `.trim()` + '\n'.
+  const wrappedInstruction = `${markerStart}${planningInstruction}${markerEnd}`;
+  const wrappedInstructionWithTrailingNewline = wrappedInstruction + '\n';
+
+  // Story 21.5 AC #6 — Cline dual-file drift detection.
+  // Runs BEFORE the file loop so we abort cleanly without partial writes.
+  // `--yes` does NOT bypass (explicit documented exception, AC #6).
+  if (agent.id === 'cline') {
+    checkClinerulesDualFileDrift(projectRoot);
+  }
+
+  // Story 21.5 AC #1, #2 — optional framing template for fresh Cline file creation.
+  // The composer produces the universal body once; the framing supplies the
+  // Cline-flavored header paragraph + Architect-mode guidance line. Framing is
+  // only used when creating a NEW file — existing files go through the normal
+  // marker-replace path so user content outside markers is preserved (AC #4).
+  let frameworkTemplate = null;
+  if (agent.id === 'cline' && fs.existsSync(CLINERULES_TEMPLATE_PATH)) {
+    frameworkTemplate = fs.readFileSync(CLINERULES_TEMPLATE_PATH, 'utf-8');
+  }
 
   for (const fileName of agent.instructionFiles) {
     const filePath = path.join(projectRoot, fileName);
@@ -433,14 +942,33 @@ Do not load skills that are not relevant to the current task.
       content = await fs.readFile(filePath, 'utf-8');
 
       const regex = new RegExp(`${markerStart}[\\s\\S]*?${markerEnd}`, 'g');
-      if (regex.test(content)) {
+      const existingMatch = content.match(regex);
+      if (existingMatch) {
+        // AC #10 — upgrade-safety: detect hand-edits to the marker block and back up.
+        const existingBlock = existingMatch[0];
+        if (existingBlock !== wrappedInstruction) {
+          let proceedWithOverwrite = true;
+          try {
+            await handleMarkerBlockDrift({
+              filePath,
+              existingBlock,
+              expectedBlock: wrappedInstruction,
+              yesMode
+            });
+          } catch (declineErr) {
+            // User declined in interactive mode — leave file unchanged for this agent file.
+            proceedWithOverwrite = false;
+            console.log(chalk.gray(`    Skipped ${fileName} (user declined marker-block overwrite)`));
+          }
+          if (!proceedWithOverwrite) continue;
+        }
         // Replace existing block in-place (AC #2)
-        content = content.replace(regex, wrappedInstruction.trim());
+        content = content.replace(regex, wrappedInstruction);
       } else {
         // Top-insert: place after skipped headers (AC #1, #3)
         const strategy = agent.injectionStrategy || { position: 'top', skipPatterns: [] };
         const insertIdx = findInsertionPoint(content, strategy.skipPatterns);
-        content = content.slice(0, insertIdx) + wrappedInstruction + '\n' + content.slice(insertIdx);
+        content = content.slice(0, insertIdx) + wrappedInstructionWithTrailingNewline + '\n' + content.slice(insertIdx);
       }
     } else if (agent.category === 'bmad') {
       // BMAD agent instruction files ARE the agent definitions (persona, menu, activation).
@@ -449,16 +977,41 @@ Do not load skills that are not relevant to the current task.
       // wiping the entire agent definition.
       console.log(chalk.gray(`    Skipped ${fileName} (BMAD agent file not yet deployed)`));
       continue;
+    } else if (frameworkTemplate) {
+      // Story 21.5 AC #1/#2 — fresh Cline file: wrap the composed block in
+      // the Cline-flavored framing template (header paragraph + Architect-mode
+      // guidance line). The framing contains empty MA-AGENTS markers that we
+      // replace with the wrapped block. Cross-file byte-identity by construction
+      // is preserved because both `.cline/clinerules.md` and `.clinerules`
+      // receive the SAME rendered string in this single loop pass.
+      const emptyMarkerPair = new RegExp(`${markerStart}\\s*\\n\\s*${markerEnd}`);
+      let framed;
+      if (emptyMarkerPair.test(frameworkTemplate)) {
+        framed = frameworkTemplate.replace(emptyMarkerPair, wrappedInstruction);
+      } else {
+        // Defensive: framing shipped without markers — append block at EOF.
+        const trimmed = frameworkTemplate.replace(/\s+$/, '');
+        framed = trimmed + '\n\n' + wrappedInstruction + '\n';
+      }
+      content = framed.replace(/\s+$/, '') + '\n';
     } else {
       // New non-BMAD file: block is sole content (AC #1, #3)
-      content = wrappedInstruction;
+      content = wrappedInstructionWithTrailingNewline;
     }
 
     await fs.outputFile(filePath, content, 'utf-8');
     console.log(chalk.cyan(`    + Updated ${fileName}`));
   }
+
+  // Story 21.4 — stamp any extraInstructionTemplates on non-JSON-merge agents
+  // (forward-compat for Story 21.3 .roomodes and Story 21.5 .clinerules).
+  await stampExtraInstructionTemplates(agent, projectRoot, { yesMode });
 }
 
+// Story 21.3's parallel applyExtraInstructionTemplates was consolidated during
+// rebase onto Story 21.4's canonical stampExtraInstructionTemplates dispatcher
+// (see above) — the yaml-customModes merger branch lives there now.
+
 /**
  * Compare two semver strings. Returns -1, 0, or 1.
  */
@@ -729,7 +1282,7 @@ async function installSkill(skillId, agentIds, customPath = '', scope = 'project
           await generateSkillsManifest(installPath);
           if (scope === 'project') {
             for (const entry of agentEntries) {
-              await updateAgentInstructions(entry.agent, process.cwd());
+              await updateAgentInstructions(entry.agent, process.cwd(), { yesMode: yes });
             }
           }
           continue;
@@ -775,7 +1328,12 @@ async function installSkill(skillId, agentIds, customPath = '', scope = 'project
         await generateSkillsManifest(installPath);
         if (scope === 'project') {
           for (const entry of agentEntries) {
-            await updateAgentInstructions(entry.agent, process.cwd());
+            await updateAgentInstructions(entry.agent, process.cwd(), { yesMode: yes });
+            // Story 21.4 — updateAgentInstructions now internally invokes
+            // stampExtraInstructionTemplates, which handles per-agent extra
+            // templates (e.g., Roo Code .roomodes via merger 'yaml-customModes',
+            // OpenCode AGENTS.md via merger 'markdown-markers'). No sibling
+            // call needed here.
           }
           // Deploy Claude Code hook when skills are installed for claude-code
           if (includesClaudeCode(agentEntries)) {
@@ -1067,5 +1625,21 @@ module.exports = {
   updateProjectContextRepoLayout,
   _updateProjectContextManifestPaths: updateProjectContextManifestPaths,
   _testUpdateAgentInstructions: updateAgentInstructions,
-  _MA_AGENTS_SOURCE: MA_AGENTS_SOURCE
+  _MA_AGENTS_SOURCE: MA_AGENTS_SOURCE,
+  // Story 21.2 — universal instruction-block composer and helpers.
+  composeInstructionBlock,
+  buildBackupFilename,
+  formatBackupTimestamp,
+  UNIVERSAL_INSTRUCTION_TEMPLATE_PATH,
+  ONPREM_INSTRUCTION_TEMPLATE_PATH,
+  // Story 21.4 — AGENTS.md template, markdown-markers merger, extraInstructionTemplates processor.
+  // Story 21.3 (rebased) — yaml-customModes merger dispatch is integrated into stampExtraInstructionTemplates.
+  resolveBmadOutputDirs,
+  markdownMarkersMerger,
+  stampExtraInstructionTemplates,
+  EXTRA_TEMPLATE_DIR,
+  // Story 21.5 — Cline dual-file drift detection + framing template path.
+  CLINERULES_TEMPLATE_PATH,
+  ClinerulesDualFileDriftError,
+  checkClinerulesDualFileDrift
 };