omp-conductor 0.2.0 → 0.2.1

package/README.md

@@ -212,6 +212,48 @@ turned on you can also invoke it directly:
 Nothing about the wizard changes: `/conductor setup` on its own remains a
 complete, supported path, and the brief it renders is safe unedited.
 
+### Keeping a brief current
+
+Upgrading the package does not upgrade a brief you are already running, and it is
+worth knowing exactly which half of that sentence is true.
+
+| What | Updates on `omp plugin install`? |
+| --- | --- |
+| `skills/conductor-onboarding/SKILL.md` | Yes. The session reads it from the installed package. |
+| `src/briefs/worker.md` | Yes. It is read per run, so the next worker gets the new text. |
+| `src/briefs/orchestrator.md` | Yes, but it is only a *template*: it is read when the wizard renders a brief. |
+| Your rendered `ORCHESTRATOR.md` | **No.** It was written once and is yours from then on. |
+
+That last row is the point. Once the wizard renders your brief, nothing in this
+package reads it back or rewrites it, so a later version that ships a new protocol
+above the `YOURS TO EDIT` banner is invisible to every fleet already running:
+
+```bash
+omp-conductor brief-upgrade              # report only
+omp-conductor brief-upgrade --apply      # replace the shipped half, keep yours
+```
+
+The banner is what makes this safe. Everything above it belongs to the package and
+everything below it belongs to you, so an upgrade replaces the first and copies the
+second across untouched, keeping the previous file as
+`ORCHESTRATOR.md.bak-<timestamp>`. Three cases where it will not write at all:
+
+- **Your brief has no banner** (hand-written, or predating the split). There is no
+  way to tell which lines are yours, so it lists the sections the template has and
+  yours does not, and leaves the file alone. Retitled sections count as present, so
+  `## Reporting (low noise)` is not reported as a missing `## Reporting`.
+- **No config resolved**, so the template still carries its `{{PLACEHOLDER}}`
+  coordinates. Merging it would write those literals into a live prompt.
+- **Nothing changed.** It says so and exits.
+
+`--file PATH` checks a brief that is not where the wizard would have put it, which
+is the normal case on a dedicated fleet host: the supervising session runs from its
+own directory, and that host may never have configured a dispatch daemon.
+
+A brief with the **Learning loop** section has a second route. The session running
+from it can propose the missing sections itself, as a diff, for you to approve with
+a yes over Telegram, which is the same protocol it uses for any other amendment.
+
 ## Quick start
 
 1. Write a config (see [Configuration](#configuration)) at
@@ -620,6 +662,7 @@ omp-conductor status [--project NAME]
 omp-conductor daemon [--once] [--port N] [--project NAME]
 omp-conductor pause
 omp-conductor resume
+omp-conductor brief-upgrade [--apply] [--file PATH] [--project NAME]
 omp-conductor help
 ```
 
@@ -635,6 +678,9 @@ omp-conductor help
 | `--project NAME` | Pick the project to service. One daemon process serves exactly one project; with several configured projects the name is required. |
 | `pause` | Stop claiming new work. The running daemon notices on its next tick; runs already in flight finish. |
 | `resume` | Allow claiming again. |
+| `brief-upgrade` | Compare a project's `ORCHESTRATOR.md` against the brief this version of the package ships. Reports by default; see [Keeping a brief current](#keeping-a-brief-current). |
+| `--apply` | Only for `brief-upgrade`. Replaces the half above the `YOURS TO EDIT` banner and keeps everything below it, backing the previous file up first. Ignored when the brief cannot be split or the template is unrendered. |
+| `--file PATH` | Only for `brief-upgrade`. Check a brief that is not where the wizard would have put it, on a host that may have no config at all. |
 | `help`, `--help`, `-h` | Print usage. An unknown or missing verb prints it too, and exits `2`. |
 
 Pause is a flag file under the state directory, so it applies to every project and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "license": "MIT",
   "description": "A 24/7 dispatcher that takes ready GitHub issues to green, mergeable PRs using omp coding sessions, with tiered escalation first to an orchestrator session and then to a human.",

package/src/brief-upgrade.ts

@@ -0,0 +1,242 @@
+/**
+ * Keeping a live `ORCHESTRATOR.md` current with the shipped template.
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+
+/**
+ * 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";
+
+/**
+ * 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.
+ */
+export interface BriefHalves {
+  shipped: string;
+  owned: string;
+}
+
+/**
+ * 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.
+ */
+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.
+  const lineEnd = text.indexOf("\n", at);
+  const cut = lineEnd < 0 ? text.length : lineEnd + 1;
+  return { shipped: text.slice(0, cut), owned: text.slice(cut) };
+}
+
+/** A `## Heading` in the shipped half, by its exact text. */
+function headings(text: string): string[] {
+  const out: string[] = [];
+  for (const line of text.split("\n")) {
+    if (line.startsWith("## ")) out.push(line.slice(3).trim());
+  }
+  return out;
+}
+
+/**
+ * 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 {
+  const cut = heading.search(/[—–:(-]/u);
+  return (cut < 0 ? heading : heading.slice(0, cut)).trim().toLowerCase();
+}
+
+/**
+ * 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.
+ */
+export function missingSections(live: string, rendered: string): string[] {
+  const present = new Set(headings(live).map(topicKey));
+  return headings(rendered).filter((h) => !present.has(topicKey(h)));
+}
+
+/** Section bodies from a rendered template, keyed by heading, for reporting. */
+export function sectionText(rendered: string, heading: string): string {
+  const lines = rendered.split("\n");
+  const start = lines.findIndex((l) => l.startsWith("## ") && l.slice(3).trim() === heading);
+  if (start < 0) return "";
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line !== undefined && line.startsWith("## ")) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join("\n").trimEnd();
+}
+
+/** An unfilled `{{KEY}}` coordinate in a template nobody rendered. */
+const PLACEHOLDER_PATTERN = /\{\{[A-Za-z0-9_]+\}\}/;
+
+/** What a check found, and what a caller may do about it. */
+export type BriefStatus =
+  | { kind: "current" }
+  /** Banner present and the shipped half differs: a merge is exact. */
+  | { kind: "mergeable"; merged: string; liveShipped: string; freshShipped: string }
+  /** 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[] };
+
+/**
+ * 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.
+ */
+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) {
+    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) };
+  }
+
+  if (liveHalves.shipped === freshHalves.shipped) return { kind: "current" };
+
+  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,
+  };
+}
+
+/**
+ * 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.
+ */
+export function shippedDiff(before: string, after: string): string {
+  const old = new Set(before.split("\n"));
+  const now = new Set(after.split("\n"));
+  const lines: string[] = [];
+  for (const line of before.split("\n")) {
+    if (!now.has(line) && line.trim() !== "") lines.push(`- ${line}`);
+  }
+  for (const line of after.split("\n")) {
+    if (!old.has(line) && line.trim() !== "") lines.push(`+ ${line}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * 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.
+ */
+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;
+}
+
+/** The check rendered for a terminal, including what to do next. */
+export function formatBriefStatus(path: string, status: BriefStatus): string {
+  if (status.kind === "current") {
+    return [`brief ${path}`, "", "up to date — its shipped half matches this version of the template."].join("\n");
+  }
+
+  if (status.kind === "mergeable") {
+    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.",
+      "",
+      shippedDiff(status.liveShipped, status.freshShipped),
+      "",
+      "Apply it with:  omp-conductor brief-upgrade --apply",
+      "The previous file is kept beside it as ORCHESTRATOR.md.bak-<timestamp>.",
+    ].join("\n");
+  }
+
+  const lines = [`brief ${path}`, ""];
+  lines.push(
+    ...(status.kind === "unrendered"
+      ? [
+          "The shipped template still carries its {{PLACEHOLDER}} coordinates, because no",
+          "project config resolved on this host. Merging it would write those literals",
+          "into a live standing prompt, so this can only be reported on. Run it with",
+          "--project on a host that has the config to apply an upgrade.",
+        ]
+      : [
+          "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.",
+        ]),
+  );
+  if (status.missing.length === 0) {
+    lines.push("", "It already has a heading for every section the template ships.");
+    return lines.join("\n");
+  }
+  lines.push(
+    "",
+    `Sections the shipped template has and this brief does not (${status.missing.length}):`,
+    ...status.missing.map((h) => `  - ${h}`),
+    "",
+    "Merge the ones you want by hand, or ask the session running from this brief to",
+    "propose them through its own amendment protocol.",
+  );
+  return lines.join("\n");
+}

package/src/briefs/orchestrator.md

@@ -54,6 +54,27 @@ For each one, pick exactly one of three outcomes:
 - **It is already done.** The PR is green and waiting on a human merge. Note it,
   with the link, and move on. You do not merge it.
 
+**Then check for orphans.** A worker is a process, and processes die: a daemon
+restart, a host reboot, a kill. The `agent:in-progress` label survives that death
+by design — it is the guard that stops the next tick double-dispatching — but
+nothing removes it, so a dead worker's issue sits "in progress" forever, occupying
+a slot that no longer exists. Compare the in-progress labels against the active
+runs `omp-conductor status` just showed you: **an in-progress issue with no
+matching active run is an orphan.**
+
+For an orphan, look at what the dead worker left — its branch, any commits, an
+open PR — then pick one:
+
+- **Real progress exists** (commits or an open PR). Note the issue, the branch and
+  what state it reached, and remove the in-progress label so the loop can re-claim
+  it. The next worker starts from the branch's actual state rather than from
+  nothing, and the attempt counter still protects against a loop of deaths.
+- **Nothing useful exists.** Remove the in-progress label and let the next tick
+  re-claim it clean.
+
+Never leave an orphan holding a slot "to be safe": a label nobody is working under
+is not safety, it is a deadlocked fleet that looks busy.
+
 ## Duty 2 — groom
 
 Keep the queue worth draining.

package/src/cli.ts

@@ -5,8 +5,13 @@
  * process lifecycle in ./lifecycle.ts, so the CLI and the `/conductor` plugin
  * cannot drift apart.
  */
+import { readFileSync } from "node:fs";
+import { checkBrief, formatBriefStatus, writeMergedBrief } from "./brief-upgrade.ts";
+import { findProject, loadConfig } from "./config.ts";
 import { formatStatus, runDaemon, setPaused, statusSnapshot } from "./daemon.ts";
 import { healthCheck, livingDaemon, startDaemon, stopDaemon } from "./lifecycle.ts";
+import { briefPathForProject, renderBriefForProject, shippedBriefTemplate } from "./setup.ts";
+import type { ProjectConfig } from "./types.ts";
 
 const USAGE = `omp-conductor — dispatch ready issues to omp coding sessions
 
@@ -18,6 +23,7 @@ usage:
   omp-conductor daemon [--once] [--port N] [--project NAME]
   omp-conductor pause
   omp-conductor resume
+  omp-conductor brief-upgrade [--apply] [--file PATH] [--project NAME]
   omp-conductor help
 
   start    run the dispatch loop in the background and wait until it answers
@@ -32,6 +38,14 @@ usage:
            and exits. This is what \`start\` launches.
   pause    stop claiming new work. The running daemon notices on its next tick.
   resume   allow claiming again.
+  brief-upgrade
+           compare a project's ORCHESTRATOR.md against the brief this version of
+           the package ships. Reports by default; --apply replaces the half above
+           the YOURS TO EDIT banner and keeps everything below it, backing the old
+           file up first. --file checks a brief that is not where the wizard would
+           have put it, on a host that may have no config at all. Nothing is
+           written for a brief with no banner, or when no config resolved and the
+           template still carries its {{PLACEHOLDER}} coordinates.
   help     print this text (also --help, -h).
 
 Pause is a flag file under the state directory, so it applies to every project
@@ -159,6 +173,60 @@ try {
       process.stdout.write("resumed — work will be claimed on the next tick\n");
       break;
 
+    case "brief-upgrade": {
+      // `--file` exists because a real fleet's brief is often not where the wizard
+      // would have put it: the supervising session runs from its own directory, and
+      // that host may never have configured a dispatch daemon at all. Without this
+      // the command cannot check the one file it was written for.
+      const override = flag(argv, "file");
+      let project: ProjectConfig | undefined;
+      let path: string;
+      if (override === undefined) {
+        project = findProject(loadConfig(), flag(argv, "project"));
+        path = briefPathForProject(project);
+      } else {
+        path = override;
+        try {
+          project = findProject(loadConfig(), flag(argv, "project"));
+        } catch {
+          // No config here, or several projects and no name given. With an explicit
+          // file we need neither, and refusing would make the command unusable on a
+          // fleet host that runs only the supervising session.
+          project = undefined;
+        }
+      }
+
+      let live: string;
+      try {
+        live = readFileSync(path, "utf8");
+      } catch {
+        process.stderr.write(
+          `omp-conductor: no brief at ${path}` +
+            `${override === undefined ? " — run /conductor setup and say yes to writing ORCHESTRATOR.md." : "."}\n`,
+        );
+        process.exit(1);
+      }
+
+      // With no config there are no coordinates to substitute, so the template is
+      // compared raw. Headings carry no placeholders, so the section-level report is
+      // unaffected; the note below keeps the printed text honest.
+      const status = checkBrief(live, project === undefined ? shippedBriefTemplate() : renderBriefForProject(project));
+      // Report first, always: --apply on a brief with no banner must not be the
+      // command that silently discards an operator's hand-written policy.
+      process.stdout.write(`${formatBriefStatus(path, status)}\n`);
+      if (project === undefined) {
+        process.stdout.write(
+          "\nnote: no conductor config resolved on this host, so the template's\n" +
+            "{{PLACEHOLDER}} coordinates are unsubstituted. Section names are unaffected.\n",
+        );
+      }
+      if (argv.includes("--apply") && status.kind === "mergeable") {
+        const backup = writeMergedBrief(path, status.merged);
+        process.stdout.write(`\napplied — previous brief kept at ${backup}\n`);
+      }
+      break;
+    }
+
     case "help":
     case "--help":
     case "-h":

package/src/plugin.ts

@@ -10,8 +10,9 @@
  * tested; this file turns answers into questions and back again. The invariant
  * worth protecting is on `setup()` below — nothing is written before the confirm.
  */
-import { existsSync } from "node:fs";
-import { configPath, loadConfig, saveConfig } from "./config.ts";
+import { existsSync, readFileSync } from "node:fs";
+import { checkBrief, formatBriefStatus, writeMergedBrief } from "./brief-upgrade.ts";
+import { configPath, findProject, loadConfig, saveConfig } from "./config.ts";
 import {
   armConductor,
   formatStatus,
@@ -25,12 +26,14 @@ import {
   ORCHESTRATOR_BRIEF_NAME,
   REPORT_SCOPE_CHOICES,
   SETUP_DEFAULTS,
+  briefPathForProject,
   buildConfig,
   checkTokenScopes,
   createMissingLabels,
   detectTelegram,
   orchestratorBriefPath,
   planLabels,
+  renderBriefForProject,
   summarisePlan,
   writeOrchestratorBrief,
   type SetupAnswers,
@@ -100,13 +103,19 @@ const SUBCOMMANDS: Completion[] = [
   { value: "status", label: "status", description: "pause state, caps, active runs, today's usage" },
   { value: "pause", label: "pause", description: "stop claiming new work" },
   { value: "resume", label: "resume", description: "allow claiming again" },
+  {
+    value: "brief-upgrade",
+    label: "brief-upgrade",
+    description: "check ORCHESTRATOR.md against the brief this version ships",
+  },
 ];
 
 const USAGE = [
-  "/conductor setup [project]   create or update a project, then arm after you confirm",
-  "/conductor status [project]  pause state, caps, active runs, today's usage",
-  "/conductor pause             stop claiming new work",
-  "/conductor resume            allow claiming again",
+  "/conductor setup [project]         create or update a project, then arm after you confirm",
+  "/conductor status [project]        pause state, caps, active runs, today's usage",
+  "/conductor pause                   stop claiming new work",
+  "/conductor resume                  allow claiming again",
+  "/conductor brief-upgrade [project] check ORCHESTRATOR.md against the shipped brief",
 ].join("\n");
 
 /**
@@ -588,6 +597,34 @@ export default function conductorPlugin(pi: PluginApi): void {
             ctx.ui.notify("Conductor resumed — work will be claimed on the next tick.", "info");
             break;
 
+          case "brief-upgrade": {
+            const p = findProject(loadConfig(), project);
+            const path = briefPathForProject(p);
+            if (!existsSync(path)) {
+              ctx.ui.notify(
+                `No brief at ${path} — run /conductor setup and say yes to writing ${ORCHESTRATOR_BRIEF_NAME}.`,
+                "warning",
+              );
+              break;
+            }
+            const status = checkBrief(readFileSync(path, "utf8"), renderBriefForProject(p));
+            ctx.ui.notify(formatBriefStatus(path, status), status.kind === "current" ? "info" : "warning");
+            // Confirmed here rather than applied on sight: this file is a standing
+            // prompt the operator may have spent an hour on, so the diff they just
+            // read is the thing they are agreeing to.
+            if (status.kind === "mergeable") {
+              const apply = await ctx.ui.confirm(
+                "Upgrade the brief?",
+                "Replace the half above the YOURS TO EDIT banner with the one this version ships? Everything below the banner is kept exactly as it is, and the current file is backed up first.",
+              );
+              if (apply) {
+                const backup = writeMergedBrief(path, status.merged);
+                ctx.ui.notify(`Brief upgraded. Previous version kept at ${backup}.`, "info");
+              }
+            }
+            break;
+          }
+
           default:
             ctx.ui.notify(
               `${sub ? `Unknown subcommand "${sub}".` : "Pick a subcommand."}\n\n${USAGE}` +

package/src/setup.ts

@@ -27,6 +27,7 @@ import { configPath, resolveCaps, stateDir } from "./config.ts";
 import {
   CONFIG_VERSION,
   DEFAULT_CAPS,
+  DEFAULT_REPORT_SCOPE,
   type Caps,
   type ConductorConfig,
   type ProjectConfig,
@@ -392,31 +393,55 @@ export function buildConfig(a: SetupAnswers, existing?: ConductorConfig): Conduc
 }
 
 /**
- * Where the operator's own brief lands: beside the worktrees, under the state
+ * Where a configured project's brief lives: beside its worktrees, under the state
  * directory, so it is on the same disk the fleet already owns and survives a
- * reinstall of the package. Derived from the answers rather than fixed, so a
+ * reinstall of the package. Derived from the project rather than fixed, so a
  * project that ever gains a chosen workspace root keeps its brief with it.
  */
-export function orchestratorBriefPath(a: SetupAnswers): string {
-  return join(buildProject(a).workspaceRoot, ORCHESTRATOR_BRIEF_NAME);
+export function briefPathForProject(p: ProjectConfig): string {
+  return join(p.workspaceRoot, ORCHESTRATOR_BRIEF_NAME);
 }
 
 /**
- * The shipped template with this project's real values in it.
+ * The brief template exactly as shipped, placeholders and all.
+ *
+ * Exported for the upgrade check, which has to be able to read the shipped text
+ * on a host that has no config to render it against.
+ */
+export function shippedBriefTemplate(): string {
+  return readFileSync(ORCHESTRATOR_TEMPLATE_PATH, "utf8");
+}
+
+/**
+ * The shipped template with a configured project's real values in it.
  *
  * Only the coordinates and the chosen scope are substituted: the policy text is
  * left exactly as shipped, because from here on the file is the operator's to
  * edit and nothing in this package reads it back.
+ *
+ * Takes a `ProjectConfig` rather than answers so that a *later* upgrade check can
+ * reproduce the same render from what is on disk, months after the wizard's
+ * answers are gone.
  */
-export function renderOrchestratorBrief(a: SetupAnswers): string {
+export function renderBriefForProject(p: ProjectConfig): string {
   return renderBrief(readFileSync(ORCHESTRATOR_TEMPLATE_PATH, "utf8"), {
-    PROJECT: a.projectName,
-    TRACKER_REPO: a.trackerRepo,
-    QUEUE_LABEL: a.queueLabel,
-    REPORT_SCOPE: a.reportScope,
+    PROJECT: p.name,
+    TRACKER_REPO: p.tracker.repo,
+    QUEUE_LABEL: p.queueLabel,
+    REPORT_SCOPE: p.reporting?.scope ?? DEFAULT_REPORT_SCOPE,
   });
 }
 
+/** Wizard-time path, via the project the answers describe. */
+export function orchestratorBriefPath(a: SetupAnswers): string {
+  return briefPathForProject(buildProject(a));
+}
+
+/** Wizard-time render, via the project the answers describe. */
+export function renderOrchestratorBrief(a: SetupAnswers): string {
+  return renderBriefForProject(buildProject(a));
+}
+
 /**
  * Writes the rendered brief and returns where it went.
  *