omp-conductor 0.3.11 → 0.3.13

package/src/brief-upgrade.ts

@@ -1,55 +1,177 @@
 /**
- * Keeping a live `ORCHESTRATOR.md` current with the shipped template.
+ * Package floor + fleet POLICY.md overlay.
  *
- * The wizard renders the template once and then never touches the file again,
- * because from that moment it is the operator's. That is the right ownership
- * rule and it has one consequence nobody notices until months later: every
- * later improvement to the *shipped* half of the brief — a new duty, a protocol
- * like the amendment loop — is invisible to every fleet already running. The
- * package updates; the standing prompt does not.
+ * The shipped orchestrator floor lives in the package and is re-rendered into a
+ * composed `ORCHESTRATOR.md` on every tick. Fleet-specific policy lives in
+ * `POLICY.md` and is the only file Learning-loop / operator edits should touch.
  *
- * This module is the missing half of that story. It never guesses: the brief has
- * an explicit banner separating the package's text from the operator's, so when
- * that banner is present the split is exact and the merge is mechanical. When it
- * is absent — a hand-written brief, or one predating the split — there is no
- * honest way to know which lines are the operator's, so nothing is rewritten and
- * the missing sections are reported instead.
+ * Legacy single-file briefs with a `YOURS TO EDIT` banner still split exactly;
+ * `migrate` lifts the owned half into `POLICY.md`. Hand-written briefs without a
+ * banner can `retrofit` one at a classified cut before migrating.
  */
 
-import { readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 
 /**
  * The line that divides the two halves. Matched on this substring rather than
  * the whole comment banner so a reflowed or re-decorated banner still splits.
  */
-const EDIT_BANNER = "YOURS TO EDIT";
+export const EDIT_BANNER = "YOURS TO EDIT";
+
+/** Fleet-owned overlay beside the composed orchestrator brief. */
+export const POLICY_BRIEF_NAME = "POLICY.md";
+
+/** Composed view the session / AGENTS.md symlink historically pointed at. */
+export const ORCHESTRATOR_BRIEF_NAME = "ORCHESTRATOR.md";
+
+/** Topic keys that belong in POLICY.md (matched like {@link topicKey}). */
+export const OWNED_TOPIC_KEYS = ["releases", "project context", "reporting", "amendments"] as const;
+
+/** Banner written into composed ORCHESTRATOR.md between floor and policy. */
+export const COMPOSE_BANNER = [
+  "<!-- ==================================================================== -->",
+  "<!-- YOURS TO EDIT — live copy of POLICY.md. Edit POLICY.md, not here.   -->",
+  "<!-- This composed ORCHESTRATOR.md is regenerated from package floor +   -->",
+  "<!-- POLICY.md; hand-edits above or below the banner will not last.      -->",
+  "<!-- ==================================================================== -->",
+].join("\n");
 
 /**
  * A brief split into the package's half and the operator's half.
  *
- * `shipped` runs to the end of the banner line; `owned` is everything after it.
- * Concatenating them reproduces the input byte for byte, which is what makes a
- * merge safe to write back.
+ * `shipped` runs through the full contiguous HTML-comment banner that contains
+ * {@link EDIT_BANNER}; `owned` is everything after that block. Concatenating
+ * them reproduces the input byte for byte, which is what makes a merge safe to
+ * write back.
  */
 export interface BriefHalves {
   shipped: string;
   owned: string;
 }
 
+/** True when a line is a single HTML comment (the banner's only vocabulary). */
+export function isHtmlCommentLine(line: string): boolean {
+  const trimmed = line.trim();
+  return trimmed.startsWith("<!--") && trimmed.endsWith("-->");
+}
+
+/**
+ * Substrings that identify **package** banner chrome phrases, never operator
+ * notes and never a bare decorative separator.
+ *
+ * Matched case-insensitively inside an HTML comment. Keep this list tight: a
+ * false positive would delete fleet-owned POLICY prose.
+ */
+const BANNER_CHROME_MARKERS = [
+  EDIT_BANNER,
+  "never reads this file back",
+  "live copy of POLICY.md",
+  "regenerated from package floor",
+  "hand-edits above or below",
+] as const;
+
+/** `<!-- ====...==== -->` / dash separators that *frame* the banner. */
+const BANNER_SEPARATOR = /^<!--\s*[=-]{3,}\s*-->$/;
+
+/** True when a line is a decorative `<!-- === -->` / `<!-- --- -->` separator. */
+export function isBannerSeparatorLine(line: string): boolean {
+  return BANNER_SEPARATOR.test(line.trim());
+}
+
+/**
+ * True when a line is a package banner **phrase** comment (YOURS TO EDIT /
+ * never-reads footer / compose-banner wording) — not a bare separator.
+ */
+export function isPhraseChromeLine(line: string): boolean {
+  const trimmed = line.trim();
+  if (!isHtmlCommentLine(trimmed)) return false;
+  if (isBannerSeparatorLine(trimmed)) return false;
+  const lower = trimmed.toLowerCase();
+  return BANNER_CHROME_MARKERS.some((marker) => lower.includes(marker.toLowerCase()));
+}
+
+/**
+ * @deprecated Prefer {@link isPhraseChromeLine}. Separators alone are not chrome.
+ */
+export function isKnownBannerChromeLine(line: string): boolean {
+  return isPhraseChromeLine(line);
+}
+
+/**
+ * Drop a leading **known package footer fragment** from an owned half / POLICY.md.
+ *
+ * Only strips when the leading blank+comment prefix contains at least one
+ * package phrase marker (e.g. "never reads this file back"). Separators like
+ * `<!-- ==== -->` strip only as companions to that phrase — a POLICY that
+ * legitimately starts with a decorative separator alone is left untouched.
+ * Stops at the first non-blank line that is neither a phrase nor a separator,
+ * so `<!-- operator notes -->` survive.
+ */
+export function stripLeadingBannerCrumbs(text: string): string {
+  const lines = text.split("\n");
+
+  // Peek: does the leading blank/comment prefix carry a package phrase?
+  let j = 0;
+  let phraseInPrefix = false;
+  while (j < lines.length) {
+    const line = lines[j];
+    if (line === undefined) break;
+    const trimmed = line.trim();
+    if (trimmed === "") {
+      j += 1;
+      continue;
+    }
+    if (!isHtmlCommentLine(line)) break;
+    if (isPhraseChromeLine(line)) phraseInPrefix = true;
+    j += 1;
+  }
+  // Separator-only (or operator-comment-only) prefixes are fleet-owned — keep.
+  if (!phraseInPrefix) return text;
+
+  // Strip blanks, phrase chrome, and separators that framed that phrase.
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line === undefined) break;
+    const trimmed = line.trim();
+    if (trimmed === "" || isPhraseChromeLine(line) || isBannerSeparatorLine(line)) {
+      i += 1;
+      continue;
+    }
+    break;
+  }
+  return lines.slice(i).join("\n");
+}
+
+/** @deprecated Use {@link stripLeadingBannerCrumbs}. Kept for call-site stability. */
+export const stripLeadingHtmlComments = stripLeadingBannerCrumbs;
+
 /**
  * Splits on the banner, or returns `undefined` when there is none.
  *
  * `undefined` is a real answer, not a failure: it means this brief cannot be
  * merged mechanically, and every caller is expected to degrade to reporting
  * rather than to assume a boundary.
+ *
+ * The cut is the end of the **whole contiguous HTML-comment block** that
+ * contains `YOURS TO EDIT`, not merely the line with that substring. Legacy and
+ * compose banners both trail the marker with more `<!-- … -->` lines; leaving
+ * those in `owned` would write package chrome into POLICY.md.
  */
 export function splitBrief(text: string): BriefHalves | undefined {
   const at = text.indexOf(EDIT_BANNER);
   if (at < 0) return undefined;
-  // Keep the whole banner line on the shipped side: the operator's half starts
-  // at the first line they own, so a merge never has to reconstruct the banner.
+  // End of the line that carries YOURS TO EDIT…
   const lineEnd = text.indexOf("\n", at);
-  const cut = lineEnd < 0 ? text.length : lineEnd + 1;
+  let cut = lineEnd < 0 ? text.length : lineEnd + 1;
+  // …then every contiguous HTML-comment line after it (footer / closer).
+  while (cut < text.length) {
+    const nextNl = text.indexOf("\n", cut);
+    const nextLine = nextNl < 0 ? text.slice(cut) : text.slice(cut, nextNl);
+    if (!isHtmlCommentLine(nextLine)) break;
+    cut = nextNl < 0 ? text.length : nextNl + 1;
+  }
   return { shipped: text.slice(0, cut), owned: text.slice(cut) };
 }
 
@@ -65,25 +187,22 @@ function headings(text: string): string[] {
 /**
  * The comparable part of a heading: everything before the first dash, colon or
  * bracket, lowercased.
- *
- * Operators retitle sections freely — `## Reporting` becomes `## Reporting (low
- * noise, evidence-backed)`, `## Duty 1 — drain` becomes `## Duty 1 — the dispatch
- * loop (run this on every tick)` — and an exact match would report all of those as
- * absent. Ten reported sections when four are genuinely missing is a list nobody
- * reads, which is the same as reporting nothing.
  */
-function topicKey(heading: string): string {
+export function topicKey(heading: string): string {
   const cut = heading.search(/[—–:(-]/u);
   return (cut < 0 ? heading : heading.slice(0, cut)).trim().toLowerCase();
 }
 
+/** True when a heading's topic is one of the owned POLICY sections. */
+export function isOwnedTopic(heading: string): boolean {
+  const key = topicKey(heading);
+  return (OWNED_TOPIC_KEYS as readonly string[]).includes(key);
+}
+
 /**
  * Shipped sections the live brief has no heading for.
  *
- * Matched on {@link topicKey}, so a retitled section counts as present. The
- * remaining bias is deliberate: this decides what to *offer* for a hand-merge, and
- * a section reported that the operator already covers costs them one read, while a
- * new protocol silently counted as present costs them the protocol.
+ * Matched on {@link topicKey}, so a retitled section counts as present.
  */
 export function missingSections(live: string, rendered: string): string[] {
   const present = new Set(headings(live).map(topicKey));
@@ -108,6 +227,19 @@ export function sectionText(rendered: string, heading: string): string {
 
 /** An unfilled `{{KEY}}` coordinate in a template nobody rendered. */
 const PLACEHOLDER_PATTERN = /\{\{[A-Za-z0-9_]+\}\}/;
+const PLACEHOLDER_REPLACE = /\{\{([A-Za-z0-9_]+)\}\}/g;
+
+/**
+ * Tiny template renderer kept here so the tick path never imports `worker.ts`
+ * (and through it the session SDK).
+ */
+export function renderBriefTemplate(template: string, vars: Record<string, string>): string {
+  return template.replace(PLACEHOLDER_REPLACE, (placeholder, key: string) => {
+    if (!Object.hasOwn(vars, key)) return placeholder;
+    const value = vars[key];
+    return value === undefined ? placeholder : value;
+  });
+}
 
 /** What a check found, and what a caller may do about it. */
 export type BriefStatus =
@@ -117,29 +249,31 @@ export type BriefStatus =
   /** No banner, so the boundary is unknown and only reporting is honest. */
   | { kind: "unsplittable"; missing: string[] }
   /** Template never rendered, so merging it would write `{{PROJECT}}` into a brief. */
-  | { kind: "unrendered"; missing: string[] };
+  | { kind: "unrendered"; missing: string[] }
+  /** Overlay already active: floor refreshes from package; policy is POLICY.md. */
+  | { kind: "overlay"; policyPath: string; orchestratorPath: string };
 
 /**
  * Compares a live brief against the freshly rendered template.
  *
- * `rendered` should come from `renderBriefForProject`, so the coordinates already
- * match and a diff reflects policy changes rather than substitution noise. A raw
- * template is accepted — a host that runs only the supervising session has no
- * config to render from — but it can only ever produce a report.
+ * Prefer {@link inspectBriefLayout} once a fleet has `POLICY.md`. This path
+ * remains for pre-overlay single-file briefs.
  */
 export function checkBrief(live: string, rendered: string): BriefStatus {
   const liveHalves = splitBrief(live);
   const freshHalves = splitBrief(rendered);
 
-  // A template without the banner is a packaging error, not an operator problem,
-  // so treat it the same as an unmergeable live brief rather than inventing a cut.
-  if (liveHalves === undefined || freshHalves === undefined) {
+  // A template without the banner is expected in the overlay world (floor-only).
+  // When the *live* brief still has a banner, compare using composed rendered text
+  // that includes the compose banner so migrate remains available.
+  if (liveHalves === undefined) {
+    return { kind: "unsplittable", missing: missingSections(live, rendered) };
+  }
+  if (freshHalves === undefined) {
+    // Floor-only rendered template: live bannered brief wants migrate, not merge.
     return { kind: "unsplittable", missing: missingSections(live, rendered) };
   }
 
-  // Enforced here rather than at each caller: merging an unrendered template would
-  // write `{{PROJECT}}` into a live standing prompt, and a session reading its own
-  // coordinates as a literal placeholder is worse than an out-of-date brief.
   if (PLACEHOLDER_PATTERN.test(freshHalves.shipped)) {
     return { kind: "unrendered", missing: missingSections(live, rendered) };
   }
@@ -148,20 +282,65 @@ export function checkBrief(live: string, rendered: string): BriefStatus {
 
   return {
     kind: "mergeable",
-    // The operator's half is carried across untouched. This is the whole safety
-    // property: an upgrade that reformats one of their sections is an upgrade
-    // nobody runs twice.
     merged: freshHalves.shipped + liveHalves.owned,
     liveShipped: liveHalves.shipped,
     freshShipped: freshHalves.shipped,
   };
 }
 
+/** Layout of brief files under a workspace root. */
+export type BriefLayout =
+  | { kind: "overlay"; policyPath: string; orchestratorPath: string }
+  | { kind: "legacy-bannered"; orchestratorPath: string; owned: string }
+  | { kind: "legacy-handwritten"; orchestratorPath: string; missing: string[] }
+  | { kind: "missing" };
+
+export function policyPathForRoot(workspaceRoot: string): string {
+  return join(workspaceRoot, POLICY_BRIEF_NAME);
+}
+
+export function orchestratorPathForRoot(workspaceRoot: string): string {
+  return join(workspaceRoot, ORCHESTRATOR_BRIEF_NAME);
+}
+
+/**
+ * Classifies what sits in the workspace: overlay, migratable legacy, or absent.
+ *
+ * `floorHeadings` is the rendered floor (or composed) heading list used only to
+ * report missing sections for handwritten briefs.
+ */
+export function inspectBriefLayout(
+  workspaceRoot: string,
+  floorOrComposedForReport: string,
+): BriefLayout {
+  const policyPath = policyPathForRoot(workspaceRoot);
+  const orchestratorPath = orchestratorPathForRoot(workspaceRoot);
+  if (existsSync(policyPath)) {
+    return { kind: "overlay", policyPath, orchestratorPath };
+  }
+  if (!existsSync(orchestratorPath)) return { kind: "missing" };
+  const live = readFileSync(orchestratorPath, "utf8");
+  const halves = splitBrief(live);
+  if (halves !== undefined) {
+    return { kind: "legacy-bannered", orchestratorPath, owned: halves.owned };
+  }
+  return {
+    kind: "legacy-handwritten",
+    orchestratorPath,
+    missing: missingSections(live, floorOrComposedForReport),
+  };
+}
+
+/** Join rendered floor + live policy into the composed session brief. */
+export function composeOrchestrator(floor: string, policy: string): string {
+  const f = floor.replace(/\s+$/, "\n");
+  const p = policy.replace(/^\s+/, "").replace(/\s+$/, "\n");
+  return `${f}\n${COMPOSE_BANNER}\n\n${p}`;
+}
+
 /**
  * Line-level diff of the two shipped halves, for a human to read before saying
- * yes. Deliberately not a real diff algorithm: the shipped half changes by whole
- * sections between versions, so listing removed and added lines in order is both
- * enough to review and impossible to misread as a merge preview.
+ * yes.
  */
 export function shippedDiff(before: string, after: string): string {
   const old = new Set(before.split("\n"));
@@ -176,22 +355,229 @@ export function shippedDiff(before: string, after: string): string {
   return lines.join("\n");
 }
 
+/**
+ * Writes content, leaving the previous file beside it when one existed.
+ */
+export function writeWithBackup(path: string, content: string): string | undefined {
+  mkdirSync(dirname(path), { recursive: true });
+  let backup: string | undefined;
+  if (existsSync(path)) {
+    backup = `${path}.bak-${new Date().toISOString().replace(/[:.]/g, "-")}`;
+    writeFileSync(backup, readFileSync(path));
+  }
+  writeFileSync(path, content);
+  return backup;
+}
+
 /**
  * Writes the merged brief, leaving the previous one beside it.
  *
- * The backup is not optional and not configurable: this file is a standing
- * prompt an operator may have spent an hour on, and the one thing an upgrade
- * must never do is be the reason it is gone.
+ * @deprecated Prefer {@link migrateToPolicy} / overlay refresh. Kept for
+ * pre-overlay `--apply` on bannered single-file briefs.
  */
 export function writeMergedBrief(path: string, merged: string): string {
-  const backup = `${path}.bak-${new Date().toISOString().replace(/[:.]/g, "-")}`;
-  writeFileSync(backup, readFileSync(path));
-  writeFileSync(path, merged);
-  return backup;
+  const backup = writeWithBackup(path, merged);
+  return backup ?? `${path}.bak-missing`;
+}
+
+/** Result of migrating a bannered ORCHESTRATOR.md into POLICY.md. */
+export interface MigrateResult {
+  policyPath: string;
+  orchestratorPath: string;
+  policyBackup?: string;
+  orchestratorBackup?: string;
+  ownedBytes: number;
+}
+
+/**
+ * Lifts the owned half of a bannered orchestrator brief into `POLICY.md`, then
+ * writes a composed orchestrator from `floor` + that policy.
+ */
+export function migrateToPolicy(opts: {
+  orchestratorPath: string;
+  policyPath: string;
+  floor: string;
+  /** When set, use this owned text instead of splitting the live file. */
+  owned?: string;
+}): MigrateResult {
+  const live = readFileSync(opts.orchestratorPath, "utf8");
+  const owned = opts.owned ?? splitBrief(live)?.owned;
+  if (owned === undefined) {
+    throw new Error(`cannot migrate ${opts.orchestratorPath}: no ${EDIT_BANNER} banner`);
+  }
+  // Strip banner footers that an older split may have left in owned — never let
+  // package chrome become fleet policy.
+  const policyBody = stripLeadingBannerCrumbs(owned).replace(/^\s+/, "");
+  const policyBackup = writeWithBackup(opts.policyPath, policyBody.endsWith("\n") ? policyBody : `${policyBody}\n`);
+  const composed = composeOrchestrator(opts.floor, readFileSync(opts.policyPath, "utf8"));
+  const orchestratorBackup = writeWithBackup(opts.orchestratorPath, composed);
+  return {
+    policyPath: opts.policyPath,
+    orchestratorPath: opts.orchestratorPath,
+    policyBackup,
+    orchestratorBackup,
+    ownedBytes: policyBody.length,
+  };
+}
+
+/**
+ * Strip leading banner-comment crumbs from an existing POLICY.md and recompose.
+ *
+ * For fleets that already migrated under the line-only split: `--migrate --apply`
+ * on an active overlay repairs POLICY.md in place rather than no-opping.
+ */
+export function repairPolicyBannerCrumbs(opts: {
+  orchestratorPath: string;
+  policyPath: string;
+  floor: string;
+}): MigrateResult | undefined {
+  if (!existsSync(opts.policyPath)) return undefined;
+  const before = readFileSync(opts.policyPath, "utf8");
+  const cleaned = stripLeadingBannerCrumbs(before);
+  if (cleaned === before) {
+    // Still recompose so the floor matches this package even when POLICY was clean.
+    writeFileSync(opts.orchestratorPath, composeOrchestrator(opts.floor, before));
+    return undefined;
+  }
+  const policyBackup = writeWithBackup(opts.policyPath, cleaned.endsWith("\n") ? cleaned : `${cleaned}\n`);
+  const composed = composeOrchestrator(opts.floor, readFileSync(opts.policyPath, "utf8"));
+  const orchestratorBackup = writeWithBackup(opts.orchestratorPath, composed);
+  return {
+    policyPath: opts.policyPath,
+    orchestratorPath: opts.orchestratorPath,
+    policyBackup,
+    orchestratorBackup,
+    ownedBytes: cleaned.length,
+  };
+}
+
+/**
+ * Refresh composed ORCHESTRATOR.md from rendered floor + existing POLICY.md.
+ * Creates nothing when POLICY.md is absent (caller should migrate first).
+ */
+export function refreshComposedBrief(opts: {
+  orchestratorPath: string;
+  policyPath: string;
+  floor: string;
+}): boolean {
+  if (!existsSync(opts.policyPath)) return false;
+  const policy = readFileSync(opts.policyPath, "utf8");
+  writeFileSync(opts.orchestratorPath, composeOrchestrator(opts.floor, policy));
+  return true;
+}
+
+/** A proposed banner insertion for a hand-written brief (#20). */
+export interface RetrofitProposal {
+  /** Byte offset in the live text where the banner block should be inserted. */
+  cut: number;
+  /** Heading that starts the owned half. */
+  atHeading: string;
+  /** Owned-topic headings (Releases / Project context / Reporting / Amendments). */
+  ownedHeadings: string[];
+  /** Non-owned headings that appear *before* the cut — stay on the floor side. */
+  floorAbove: string[];
+  /** Live text with the compose banner inserted at `cut`. */
+  retrofitted: string;
+}
+
+/**
+ * Why a retrofit cannot be applied automatically.
+ *
+ * `interleaved` means a floor-like heading (Duty, Learning loop, Hard boundaries,
+ * …) appears *below* the first owned-topic cut. Applying the banner there would
+ * push that floor section into POLICY.md on migrate — silent ownership theft.
+ */
+export type RetrofitRefusal = {
+  kind: "interleaved";
+  atHeading: string;
+  ownedHeadings: string[];
+  floorAbove: string[];
+  floorBelow: string[];
+};
+
+export type RetrofitResult =
+  | { kind: "ok"; proposal: RetrofitProposal }
+  | { kind: "no-cut" }
+  | RetrofitRefusal;
+
+/**
+ * Propose inserting the YOURS TO EDIT banner before the first owned-topic
+ * heading.
+ *
+ * Headings are classified by **position relative to that cut**, not globally:
+ * floor-like headings above the cut stay above; any floor-like heading below
+ * the cut is a refuse — the operator must reorder or hand-classify before apply.
+ */
+export function proposeRetrofit(live: string): RetrofitResult {
+  const lines = live.split("\n");
+  const ownedHeadings: string[] = [];
+  const floorAbove: string[] = [];
+  const floorBelow: string[] = [];
+  let cutLine = -1;
+  let atHeading: string | undefined;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === undefined || !line.startsWith("## ")) continue;
+    const heading = line.slice(3).trim();
+    if (isOwnedTopic(heading)) {
+      ownedHeadings.push(heading);
+      if (cutLine < 0) {
+        cutLine = i;
+        atHeading = heading;
+      }
+      continue;
+    }
+    // Position relative to the (eventual) cut — headings before any owned topic
+    // are tentatively "above"; once the cut is known, later floor headings are
+    // "below" and block apply.
+    if (cutLine < 0) floorAbove.push(heading);
+    else floorBelow.push(heading);
+  }
+  if (cutLine < 0 || atHeading === undefined) return { kind: "no-cut" };
+
+  if (floorBelow.length > 0) {
+    return {
+      kind: "interleaved",
+      atHeading,
+      ownedHeadings,
+      floorAbove,
+      floorBelow,
+    };
+  }
+
+  // Byte offset: sum of prior lines + newlines.
+  let cut = 0;
+  for (let i = 0; i < cutLine; i++) {
+    const line = lines[i];
+    cut += (line?.length ?? 0) + 1;
+  }
+  const retrofitted = `${live.slice(0, cut)}${COMPOSE_BANNER}\n\n${live.slice(cut)}`;
+  return {
+    kind: "ok",
+    proposal: { cut, atHeading, ownedHeadings, floorAbove, retrofitted },
+  };
+}
+
+/** Insert the banner into a hand-written brief (with backup). */
+export function applyRetrofit(path: string, proposal: RetrofitProposal): string {
+  const backup = writeWithBackup(path, proposal.retrofitted);
+  return backup ?? `${path}.bak-missing`;
 }
 
 /** The check rendered for a terminal, including what to do next. */
 export function formatBriefStatus(path: string, status: BriefStatus): string {
+  if (status.kind === "overlay") {
+    return [
+      `brief overlay active`,
+      "",
+      `  floor        package template → recomposed into ${status.orchestratorPath} each tick`,
+      `  policy       ${status.policyPath} (Learning loop / operator edits)`,
+      "",
+      "Protocol updates: npm install omp-conductor@… and restart — no brief-upgrade --apply.",
+      "Legacy migrate:   omp-conductor brief-upgrade --migrate",
+    ].join("\n");
+  }
+
   if (status.kind === "current") {
     return [`brief ${path}`, "", "up to date — its shipped half matches this version of the template."].join("\n");
   }
@@ -200,13 +586,13 @@ export function formatBriefStatus(path: string, status: BriefStatus): string {
     return [
       `brief ${path}`,
       "",
-      "This version of the package ships a different brief above the YOURS TO EDIT",
-      "banner. Everything below the banner is yours and would be carried across",
-      "unchanged.",
+      "Legacy single-file brief: this version ships a different half above the YOURS TO EDIT",
+      "banner. Prefer migrating to the POLICY.md overlay:",
       "",
       shippedDiff(status.liveShipped, status.freshShipped),
       "",
-      "Apply it with:  omp-conductor brief-upgrade --apply",
+      "Migrate:  omp-conductor brief-upgrade --migrate",
+      "Or apply the old single-file merge:  omp-conductor brief-upgrade --apply",
       "The previous file is kept beside it as ORCHESTRATOR.md.bak-<timestamp>.",
     ].join("\n");
   }
@@ -224,6 +610,11 @@ export function formatBriefStatus(path: string, status: BriefStatus): string {
           "This brief has no YOURS TO EDIT banner, so it was written by hand or predates",
           "the template split. There is no way to tell which lines are yours, so nothing",
           "will be rewritten automatically.",
+          "",
+          "Retrofit a banner at the first Releases/Project context/Reporting/Amendments",
+          "heading, then migrate:",
+          "  omp-conductor brief-upgrade --retrofit",
+          "  omp-conductor brief-upgrade --migrate",
         ]),
   );
   if (status.missing.length === 0) {
@@ -240,3 +631,57 @@ export function formatBriefStatus(path: string, status: BriefStatus): string {
   );
   return lines.join("\n");
 }
+
+export function formatRetrofitProposal(path: string, proposal: RetrofitProposal): string {
+  return [
+    `retrofit ${path}`,
+    "",
+    `Insert the YOURS TO EDIT banner before ## ${proposal.atHeading}.`,
+    "",
+    `Owned-topic headings (${proposal.ownedHeadings.length}):`,
+    ...proposal.ownedHeadings.map((h) => `  - ${h}`),
+    `Floor-like headings above the banner (${proposal.floorAbove.length}):`,
+    ...(proposal.floorAbove.length === 0
+      ? ["  (none)"]
+      : proposal.floorAbove.map((h) => `  - ${h}`)),
+    "",
+    "Apply:  omp-conductor brief-upgrade --retrofit --apply",
+    "Then:   omp-conductor brief-upgrade --migrate",
+  ].join("\n");
+}
+
+export function formatRetrofitRefusal(path: string, refusal: RetrofitRefusal): string {
+  return [
+    `retrofit ${path}`,
+    "",
+    `Refused: floor-like heading(s) appear below the proposed cut at ## ${refusal.atHeading}.`,
+    "Applying the banner here would put those sections into POLICY.md on migrate.",
+    "",
+    `Owned-topic headings (${refusal.ownedHeadings.length}):`,
+    ...refusal.ownedHeadings.map((h) => `  - ${h}`),
+    `Floor-like headings above the cut (${refusal.floorAbove.length}):`,
+    ...(refusal.floorAbove.length === 0
+      ? ["  (none)"]
+      : refusal.floorAbove.map((h) => `  - ${h}`)),
+    `Floor-like headings BELOW the cut — must move or reclassify (${refusal.floorBelow.length}):`,
+    ...refusal.floorBelow.map((h) => `  - ${h}`),
+    "",
+    "Reorder so all Duties / Hard boundaries / Learning loop sit above Releases,",
+    "or hand-insert the YOURS TO EDIT banner at the line you intend, then migrate.",
+    "Nothing was written.",
+  ].join("\n");
+}
+
+export function formatMigrateResult(result: MigrateResult): string {
+  return [
+    "migrated to POLICY.md overlay",
+    "",
+    `  policy       ${result.policyPath} (${result.ownedBytes} bytes)`,
+    ...(result.policyBackup ? [`  policy bak   ${result.policyBackup}`] : []),
+    `  composed     ${result.orchestratorPath}`,
+    ...(result.orchestratorBackup ? [`  brief bak    ${result.orchestratorBackup}`] : []),
+    "",
+    "Next ticks recompose ORCHESTRATOR.md from the package floor + POLICY.md.",
+    "Edit only POLICY.md going forward.",
+  ].join("\n");
+}