omp-conductor 0.3.11 → 0.3.13

package/src/plugin.ts

@@ -11,8 +11,16 @@
  * worth protecting is on `setup()` below — nothing is written before the confirm.
  */
 import { existsSync, readFileSync } from "node:fs";
-import { isAbsolute } from "node:path";
-import { checkBrief, formatBriefStatus, writeMergedBrief } from "./brief-upgrade.ts";
+import { dirname, isAbsolute } from "node:path";
+import {
+  checkBrief,
+  formatBriefStatus,
+  formatMigrateResult,
+  inspectBriefLayout,
+  migrateToPolicy,
+  repairPolicyBannerCrumbs,
+  writeMergedBrief,
+} from "./brief-upgrade.ts";
 import { configPath, expandHome, findProject, loadConfig, saveConfig } from "./config.ts";
 import {
   armConductor,
@@ -27,11 +35,14 @@ import { defaultGraphRoot } from "./graph.ts";
 import {
   AMEND_AREAS,
   ORCHESTRATOR_BRIEF_NAME,
+  POLICY_BRIEF_NAME,
   REPORT_SCOPE_CHOICES,
   SETUP_DEFAULTS,
   amendChoices,
   answersFromProject,
   briefPathForProject,
+  policyPathForProject,
+  renderFloorForProject,
   buildConfig,
   checkTokenScopes,
   createMissingLabels,
@@ -374,17 +385,17 @@ async function askGraphRoot(
 async function askOrchestratorBrief(ctx: CommandContext, a: SetupAnswers): Promise<boolean> {
   const path = orchestratorBriefPath(a);
   const wanted = await ctx.ui.confirm(
-    `Write an orchestrator brief template to ${path}?`,
-    `It is the standing prompt for your supervising session: duties, tiers, and boundaries, ` +
-      `plus a release policy and a reporting section that are yours to edit. ` +
-      `The conductor never reads it back — it stops at green PRs either way.`,
+    `Write ${ORCHESTRATOR_BRIEF_NAME} + ${POLICY_BRIEF_NAME} under ${dirname(path)}?`,
+    `Writes composed ${ORCHESTRATOR_BRIEF_NAME} (package floor, refreshed each tick) and ${POLICY_BRIEF_NAME} ` +
+      `(Releases, Project context, Reporting, Amendments — yours to edit via the Learning loop). ` +
+      `The conductor stops at green PRs either way.`,
   );
   if (!wanted) return false;
   if (!existsSync(path)) return true;
 
   return await ctx.ui.confirm(
-    `Overwrite the existing ${ORCHESTRATOR_BRIEF_NAME}?`,
-    `${path} already exists. Overwriting replaces it with the shipped template — any policy you wrote there is lost.`,
+    `Overwrite existing ${ORCHESTRATOR_BRIEF_NAME} / ${POLICY_BRIEF_NAME}?`,
+    `${path} already exists. Overwriting replaces the composed brief and POLICY.md scaffold — any policy you wrote is lost.`,
   );
 }
 
@@ -885,7 +896,7 @@ async function setup(ctx: CommandContext, projectArg: string | undefined): Promi
       `Wrote ${path} and armed the conductor.`,
       briefPath === undefined
         ? "No orchestrator brief written — the conductor stops at green PRs; merges and releases stay human."
-        : `Wrote ${briefPath} — edit its "Releases" and "Reporting" sections; nothing here reads them back.`,
+        : `Wrote ${briefPath} + POLICY.md — edit POLICY.md (Releases/Reporting); floor refreshes each tick.`,
       "",
       "Dry run against the config just written:",
       ...(await tryPreview(answers.projectName)),
@@ -929,18 +940,68 @@ export default function conductorPlugin(pi: PluginApi): void {
           case "brief-upgrade": {
             const p = findProject(loadConfig(), project);
             const path = briefPathForProject(p);
-            if (!existsSync(path)) {
+            const rendered = renderBriefForProject(p);
+            const layout = inspectBriefLayout(p.workspaceRoot, rendered);
+            if (layout.kind === "missing") {
+              ctx.ui.notify(
+                `No brief at ${path} — run /conductor setup and say yes to writing ${ORCHESTRATOR_BRIEF_NAME} + ${POLICY_BRIEF_NAME}.`,
+                "warning",
+              );
+              break;
+            }
+            if (layout.kind === "overlay") {
+              ctx.ui.notify(
+                formatBriefStatus(path, {
+                  kind: "overlay",
+                  policyPath: layout.policyPath,
+                  orchestratorPath: layout.orchestratorPath,
+                }),
+                "info",
+              );
+              const repair = await ctx.ui.confirm(
+                "Repair POLICY.md banner crumbs and recompose?",
+                "Strips any leading HTML-comment leftovers from a pre-fix migrate, then recomposes ORCHESTRATOR.md from the package floor + POLICY.md.",
+              );
+              if (repair) {
+                const repaired = repairPolicyBannerCrumbs({
+                  orchestratorPath: layout.orchestratorPath,
+                  policyPath: layout.policyPath,
+                  floor: renderFloorForProject(p),
+                });
+                ctx.ui.notify(
+                  repaired === undefined
+                    ? "Recomposed ORCHESTRATOR.md — POLICY.md needed no crumb strip."
+                    : formatMigrateResult(repaired),
+                  "info",
+                );
+              }
+              break;
+            }
+            if (layout.kind === "legacy-bannered") {
               ctx.ui.notify(
-                `No brief at ${path} — run /conductor setup and say yes to writing ${ORCHESTRATOR_BRIEF_NAME}.`,
+                [
+                  `Legacy bannered brief at ${layout.orchestratorPath}.`,
+                  "Migrate the owned half into POLICY.md so the package floor refreshes each tick.",
+                ].join("\n"),
                 "warning",
               );
+              const migrate = await ctx.ui.confirm(
+                "Migrate to POLICY.md overlay?",
+                "Writes POLICY.md from everything below YOURS TO EDIT, recomposes ORCHESTRATOR.md from the package floor + that policy, and keeps backups.",
+              );
+              if (migrate) {
+                const result = migrateToPolicy({
+                  orchestratorPath: layout.orchestratorPath,
+                  policyPath: policyPathForProject(p),
+                  floor: renderFloorForProject(p),
+                  owned: layout.owned,
+                });
+                ctx.ui.notify(formatMigrateResult(result), "info");
+              }
               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.
+            const status = checkBrief(readFileSync(path, "utf8"), rendered);
+            ctx.ui.notify(formatBriefStatus(path, status), "warning");
             if (status.kind === "mergeable") {
               const apply = await ctx.ui.confirm(
                 "Upgrade the brief?",

package/src/setup.ts

@@ -23,6 +23,15 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import {
+  COMPOSE_BANNER,
+  ORCHESTRATOR_BRIEF_NAME,
+  POLICY_BRIEF_NAME,
+  composeOrchestrator,
+  policyPathForRoot,
+  renderBriefTemplate,
+  writeWithBackup,
+} from "./brief-upgrade.ts";
 import { configPath, resolveCaps, stateDir } from "./config.ts";
 import { graphProjectPath, graphRepos } from "./graph.ts";
 import {
@@ -37,7 +46,6 @@ import {
   type ReportScope,
   type RepoTarget,
 } from "./types.ts";
-import { renderBrief } from "./worker.ts";
 
 /**
  * Every decision the wizard needs, in one plain object. Collected by the UI,
@@ -197,12 +205,14 @@ export const MERGE_DUTY: { readonly [K in ProjectConfig["authority"]["merge"]]:
     "  one is a hard boundary, not a preference.",
 };
 
-/** The operator's own brief, rendered into the project's workspace root. */
-export const ORCHESTRATOR_BRIEF_NAME = "ORCHESTRATOR.md";
+export { ORCHESTRATOR_BRIEF_NAME, POLICY_BRIEF_NAME };
 
-/** Shipped in `files[]`, so this resolves in an installed package too. */
+/** Shipped floor template — duties, tiers, hard boundaries, Learning loop. */
 const ORCHESTRATOR_TEMPLATE_PATH = join(import.meta.dir, "briefs", "orchestrator.md");
 
+/** Shipped POLICY.md scaffold — Releases, Project context, Reporting, Amendments. */
+const POLICY_TEMPLATE_PATH = join(import.meta.dir, "briefs", "policy.md");
+
 /**
  * `repo` writes labels and closes issues; `project` moves cards on the board.
  * Both are load-bearing for an unattended loop, so a missing one is reported
@@ -572,46 +582,69 @@ export function answersFromProject(p: ProjectConfig): SetupAnswers {
 }
 
 /**
- * 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 project rather than fixed, so a
- * project that ever gains a chosen workspace root keeps its brief with it.
+ * Where a configured project's composed 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 project rather than
+ * fixed, so a project that ever gains a chosen workspace root keeps its brief
+ * with it.
  */
 export function briefPathForProject(p: ProjectConfig): string {
   return join(p.workspaceRoot, ORCHESTRATOR_BRIEF_NAME);
 }
 
-/**
- * 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");
+/** Where the fleet-owned POLICY.md overlay lives for a project. */
+export function policyPathForProject(p: ProjectConfig): string {
+  return policyPathForRoot(p.workspaceRoot);
 }
 
-/**
- * The shipped template with a configured project's real values in it.
- *
- * Only the coordinates, the chosen scope and the authority paragraph are
- * substituted: the rest of 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 renderBriefForProject(p: ProjectConfig): string {
-  return renderBrief(readFileSync(ORCHESTRATOR_TEMPLATE_PATH, "utf8"), {
+function briefVarsForProject(p: ProjectConfig): Record<string, string> {
+  return {
     PROJECT: p.name,
     TRACKER_REPO: p.tracker.repo,
     QUEUE_LABEL: p.queueLabel,
     RELEASES_DEFAULT: RELEASES_DEFAULTS[`${p.authority.merge}/${p.authority.release}`],
     MERGE_DUTY: MERGE_DUTY[p.authority.merge],
     REPORT_SCOPE: p.reporting?.scope ?? DEFAULT_REPORT_SCOPE,
-  });
+  };
+}
+
+/** Package floor template, placeholders and all. */
+export function shippedFloorTemplate(): string {
+  return readFileSync(ORCHESTRATOR_TEMPLATE_PATH, "utf8");
+}
+
+/** POLICY.md scaffold template, placeholders and all. */
+export function shippedPolicyTemplate(): string {
+  return readFileSync(POLICY_TEMPLATE_PATH, "utf8");
+}
+
+/**
+ * Floor + policy templates concatenated with the compose banner, placeholders
+ * intact. Used when no project config is available to render coordinates.
+ */
+export function shippedBriefTemplate(): string {
+  return composeOrchestrator(shippedFloorTemplate(), shippedPolicyTemplate());
+}
+
+/** Rendered package floor for a configured project. */
+export function renderFloorForProject(p: ProjectConfig): string {
+  return renderBriefTemplate(shippedFloorTemplate(), briefVarsForProject(p));
+}
+
+/** Rendered POLICY.md scaffold for a configured project. */
+export function renderPolicyForProject(p: ProjectConfig): string {
+  return renderBriefTemplate(shippedPolicyTemplate(), briefVarsForProject(p));
+}
+
+/**
+ * Composed session brief: rendered floor + POLICY scaffold (or a caller's policy).
+ *
+ * Setup writes the policy half to `POLICY.md` and this compose to
+ * `ORCHESTRATOR.md`. Later ticks recompose from the live POLICY.md so package
+ * floor updates apply without brief-upgrade.
+ */
+export function renderBriefForProject(p: ProjectConfig, policyText?: string): string {
+  return composeOrchestrator(renderFloorForProject(p), policyText ?? renderPolicyForProject(p));
 }
 
 /** Wizard-time path, via the project the answers describe. */
@@ -625,7 +658,7 @@ export function renderOrchestratorBrief(a: SetupAnswers): string {
 }
 
 /**
- * Writes the rendered brief and returns where it went.
+ * Writes `POLICY.md` + composed `ORCHESTRATOR.md`, and returns the composed path.
  *
  * Unconditional by design: the "do not clobber my edits" decision belongs to the
  * operator, is asked in the wizard, and arrives here as
@@ -634,10 +667,39 @@ export function renderOrchestratorBrief(a: SetupAnswers): string {
  * must get an overwrite.
  */
 export function writeOrchestratorBrief(a: SetupAnswers): string {
-  const path = orchestratorBriefPath(a);
-  mkdirSync(dirname(path), { recursive: true });
-  writeFileSync(path, renderOrchestratorBrief(a));
-  return path;
+  const project = buildProject(a);
+  const policyPath = policyPathForProject(project);
+  const orchestratorPath = briefPathForProject(project);
+  mkdirSync(dirname(orchestratorPath), { recursive: true });
+  const policy = renderPolicyForProject(project);
+  writeFileSync(policyPath, policy);
+  writeFileSync(orchestratorPath, composeOrchestrator(renderFloorForProject(project), policy));
+  return orchestratorPath;
+}
+
+/**
+ * Recompose `ORCHESTRATOR.md` from the package floor + live `POLICY.md`.
+ *
+ * Returns false when POLICY.md is missing (caller should migrate or set up).
+ */
+export function refreshComposedBriefForProject(p: ProjectConfig): boolean {
+  const policyPath = policyPathForProject(p);
+  if (!existsSync(policyPath)) return false;
+  const orchestratorPath = briefPathForProject(p);
+  mkdirSync(dirname(orchestratorPath), { recursive: true });
+  writeFileSync(
+    orchestratorPath,
+    composeOrchestrator(renderFloorForProject(p), readFileSync(policyPath, "utf8")),
+  );
+  return true;
+}
+
+/** @internal test helper — expose compose banner for assertions. */
+export const BRIEF_COMPOSE_BANNER = COMPOSE_BANNER;
+
+/** Backup-aware POLICY write used by migrate paths that already computed text. */
+export function writePolicyFile(path: string, content: string): string | undefined {
+  return writeWithBackup(path, content);
 }
 
 /**
@@ -861,11 +923,12 @@ export function summarisePlan(
     `  scope          ${a.reportScope} — ${chosen?.description ?? "unknown scope"}`,
   );
   if (a.writeOrchestratorBrief) {
+    const policyPath = briefPath.replace(/ORCHESTRATOR\.md$/, "POLICY.md");
     lines.push(
-      existsSync(briefPath)
-        ? `  brief          would OVERWRITE ${briefPath}`
-        : `  brief          would write ${briefPath}`,
-      "                 yours to edit afterwards — release policy lives there, not in this package",
+      existsSync(briefPath) || existsSync(policyPath)
+        ? `  brief          would OVERWRITE ${briefPath} + POLICY.md`
+        : `  brief          would write ${briefPath} + POLICY.md`,
+      "                 POLICY.md is yours — Releases/Reporting/Amendments; floor recomposes each tick",
     );
   } else {
     lines.push(
@@ -1002,7 +1065,7 @@ export const AMEND_AREAS: {
   },
   brief: {
     name: "orchestrator brief",
-    asks: `whether to render ${ORCHESTRATOR_BRIEF_NAME} — the one area that writes no config key`,
+    asks: `whether to write ${ORCHESTRATOR_BRIEF_NAME} + ${POLICY_BRIEF_NAME} — the one area that writes no config key`,
     describe: (p) => {
       const path = briefPathForProject(p);
       return existsSync(path) ? `written at ${path}` : `none at ${path}`;