omp-conductor 0.15.6 → 0.15.8

package/src/orchestrator-tick.ts

@@ -617,9 +617,14 @@ export { TELEGRAM_APPROVAL_TOOL };
  * Fails closed in the only sense that helps a fleet: the duties still run, but
  * the turn is told the approval primitive is missing *before* it can reach the
  * step that needs one. The fallback named here is the one the floor already
- * documents for a `telegram_ask` that never delivered — re-deliver with
- * `telegram_send` — so a session has one answer to "the ask did not happen",
- * not two. The last clause is the actual hazard #114 exposed: a turn that knows
+ * documents for a `telegram_ask` that never delivered — re-deliver the same
+ * question — so a session has one answer to "the ask did not happen", not two.
+ * It names `omp-conductor message` rather than `telegram_send` because this
+ * rule only ever reaches a locally injected turn: there is no inbound message
+ * to inherit a chat and topic from, and a bare send would answer a forum fleet
+ * in its main chat (#366).
+ *
+ * The last clause is the actual hazard #114 exposed: a turn that knows
  * it must ask, and cannot, is one inference away from recording an approval
  * nobody gave.
  *
@@ -630,7 +635,7 @@ export { TELEGRAM_APPROVAL_TOOL };
  */
 export const TICK_APPROVAL_UNAVAILABLE_RULE =
   `The ${TELEGRAM_APPROVAL_TOOL} tool is NOT mounted on this tick, so the package floor's yes/no amendment approval cannot be asked here. ` +
-  `If you have an amendment to propose, deliver the question with telegram_send, prefix its text with "QUESTION:", and wait for your operator's reply on a later turn. ` +
+  `If you have an amendment to propose, deliver the question with \`omp-conductor message --text "QUESTION: <the question>"\` — it resolves this project's own Telegram chat and topic — and wait for your operator's reply on a later turn. ` +
   `A returned telegram_ask answer proves an answer, not Telegram delivery. ` +
   `Never apply an amendment, or record one as approved, without an explicit answer you actually received.`;
 
@@ -1639,17 +1644,25 @@ function serialiseTelegramPayload(value: unknown): string {
   }
 }
 
-function telegramInterruptFromTool(
+/**
+ * A direct Telegram call, whatever surface it arrived on: the mounted tool, or
+ * the same device written through `xd://`. Both spellings reach the same bot,
+ * so every gate below reads them the same way.
+ */
+function directTelegramCall(
   toolName: string,
   input: Record<string, unknown>,
-): TelegramInterrupt | undefined {
+): { kind: TelegramInterrupt["kind"]; payload: Record<string, unknown>; reaction: boolean } | undefined {
   let kind: TelegramInterrupt["kind"];
+  let reaction: boolean;
   let payload: Record<string, unknown> = input;
 
   if (toolName === TELEGRAM_APPROVAL_TOOL) {
     kind = "question";
+    reaction = false;
   } else if (toolName === "telegram_send" || toolName === "telegram_react") {
     kind = "message";
+    reaction = toolName === "telegram_react";
   } else if (toolName === "write") {
     const path = input["path"];
     if (
@@ -1660,6 +1673,7 @@ function telegramInterruptFromTool(
       return undefined;
     }
     kind = path === "xd://telegram_ask" ? "question" : "message";
+    reaction = path === "xd://telegram_react";
     const content = input["content"];
     if (typeof content === "string") {
       try {
@@ -1672,6 +1686,46 @@ function telegramInterruptFromTool(
   } else {
     return undefined;
   }
+  return { kind, payload, reaction };
+}
+
+/** A named target that is really named: an empty string targets nothing. */
+function targetNamed(value: unknown): boolean {
+  if (typeof value === "number") return Number.isFinite(value);
+  return typeof value === "string" && value.trim() !== "";
+}
+
+/**
+ * The one `telegram_send` shape that silently leaves a forum topic: `thread_id`
+ * falls back to the active topic *only while `chat_id` is omitted*, so naming
+ * the chat alone delivers into the main chat instead of the thread the operator
+ * wrote in (#366). This package cannot rewrite another plugin's arguments, so
+ * the unsafe shape is refused with both safe ones spelled out — a reply the
+ * operator never sees in the thread they asked in is indistinguishable from
+ * silence, and it leaks the answer to everyone reading the main chat.
+ *
+ * Returns `undefined` for every other shape, including a call that names both.
+ */
+export function telegramTopicRoutingRefusal(payload: Record<string, unknown>): string | undefined {
+  if (!targetNamed(payload["chat_id"])) return undefined;
+  if (targetNamed(payload["thread_id"]) || targetNamed(payload["message_thread_id"])) return undefined;
+  return (
+    "Blocked: this project's Telegram is topic-routed, and thread_id defaults to the active topic only while chat_id is omitted — " +
+    "naming chat_id alone delivers into the main chat instead of the topic the message arrived in (#366). " +
+    "Nothing was sent. Answer in the active message's own topic by omitting BOTH chat_id and thread_id, or pass both together. " +
+    'On a locally injected tick there is no active topic to keep: run `omp-conductor message --text "<the message>"`, ' +
+    "which resolves this project's own chat and topic from config."
+  );
+}
+
+function telegramInterruptFromTool(
+  toolName: string,
+  input: Record<string, unknown>,
+): TelegramInterrupt | undefined {
+  const call = directTelegramCall(toolName, input);
+  if (call === undefined) return undefined;
+  let kind = call.kind;
+  const payload = call.payload;
   if (
     kind === "message" &&
     typeof payload["text"] === "string" &&
@@ -1725,6 +1779,34 @@ function telegramInterruptFromTool(
 
 type TelegramInterruptBlock = { block: true; reason: string };
 
+/**
+ * Topic routing is checked for **every** direct Telegram *delivery* this
+ * session makes, autonomous or not: the incident was a reply to a waiting
+ * human, which the autonomous gate below deliberately exempts (#366). A
+ * flat-chat project has no thread to lose and is left exactly as it was, and a
+ * reaction addresses an exact `message_id` — it carries no thread argument at
+ * all, so there is nothing there to get wrong.
+ */
+function telegramRoutingBlock(
+  configuredProject: string | undefined,
+  event: { toolName: string; input: Record<string, unknown> },
+): TelegramInterruptBlock | undefined {
+  const call = directTelegramCall(event.toolName, event.input);
+  if (call === undefined || call.reaction) return undefined;
+  let topicRouted: boolean;
+  try {
+    topicRouted = findProject(loadConfig(), configuredProject).escalation.telegramTopicId !== undefined;
+  } catch {
+    // An unreadable or ambiguous config says nothing about topics. The
+    // autonomous gate already fails closed on it for locally injected ticks,
+    // and a human-waiting reply must not become unanswerable because of it.
+    return undefined;
+  }
+  if (!topicRouted) return undefined;
+  const reason = telegramTopicRoutingRefusal(call.payload);
+  return reason === undefined ? undefined : { block: true, reason };
+}
+
 /**
  * A locally injected tick is an autonomous actor. Its direct Telegram calls
  * therefore pass through the same category and availability decision as daemon
@@ -2447,7 +2529,14 @@ export default function orchestratorTickExtension(pi: TickApi): void {
           ctx: unknown,
         ) => TelegramInterruptBlock | undefined,
       ): void;
-    }).on("tool_call", (event) => autonomousTelegramInterruptBlock(pi, session, event));
+    }).on(
+      "tool_call",
+      (event) =>
+        // Routing first: a call that cannot reach the right thread is refused
+        // whether or not the availability policy would have let it through.
+        telegramRoutingBlock(configuredProject, event) ??
+        autonomousTelegramInterruptBlock(pi, session, event),
+    );
   };
 
   pi.on("session_start", (_event, ctx) => {

package/src/reports.ts

@@ -37,7 +37,7 @@
  */
 
 import { availabilityDisposition, interruptDisposition } from "./availability.ts";
-import { readTelegramToken, sendTelegram, TelegramSendError } from "./escalate.ts";
+import { readTelegramToken, resolveProjectTopicId, sendTelegram, TelegramSendError } from "./escalate.ts";
 import { localDayKey } from "./digest-schedule.ts";
 import {
   DIGEST_BACKLOG_LIMIT,
@@ -284,10 +284,57 @@ export function telegramReportSend(p: ProjectConfig): ReportSend {
         "definitive",
       );
     }
-    return await sendTelegram(token, chatId, text, { topicId: p.escalation.telegramTopicId });
+    return await sendTelegram(token, chatId, text, { topicId: resolveProjectTopicId(p) });
   };
 }
 
+/**
+ * One direct message to the operator, addressed from config rather than from
+ * whichever chat last spoke to the session (#366).
+ *
+ * `telegram_send` keeps the active forum topic only while it names no chat, and
+ * a locally injected tick has no active message to inherit one from — so a
+ * fleet whose Telegram is a topic had no path from an autonomous turn into its
+ * own thread, and answers surfaced in the main chat instead. This addresses the
+ * project's configured chat and topic, and it is deliberately *not* a way past
+ * the operator's interrupt policy: the same availability decision an autonomous
+ * Telegram tool call gets is applied here, and a deferred message is durably
+ * held for the digest or the working-hours catch-up rather than sent anyway.
+ *
+ * The `QUESTION:` marker is the floor's own spelling for "this needs an
+ * answer", so one prefix means one category whichever surface it leaves by.
+ */
+export type OperatorMessageOutcome =
+  | { kind: "sent"; category: InterruptCategory }
+  | { kind: "held"; category: InterruptCategory; noticeId: string; reason: "availability" | "digest" };
+
+export function operatorMessageCategory(text: string): InterruptCategory {
+  return /^\s*QUESTION:\s/i.test(text) ? "decision-needed" : "material";
+}
+
+export async function deliverOperatorMessage(
+  project: ProjectConfig,
+  text: string,
+  deps: { store: Store; at: number; noticeId: string; send?: ReportSend },
+): Promise<OperatorMessageOutcome> {
+  const category = operatorMessageCategory(text);
+  const disposition = interruptDisposition(project.reporting, category, deps.at);
+  if (disposition !== "interrupt") {
+    deps.store.addHeldNotice({
+      id: deps.noticeId,
+      project: project.name,
+      category,
+      summary: text.split("\n", 1)[0]!.slice(0, 240),
+      detail: text,
+      createdAt: deps.at,
+      ...(disposition === "availability" ? { releaseOnAvailable: true } : {}),
+    });
+    return { kind: "held", category, noticeId: deps.noticeId, reason: disposition };
+  }
+  await (deps.send ?? telegramReportSend(project))(text);
+  return { kind: "sent", category };
+}
+
 /** Keep the mechanical catch-up comfortably inside Telegram's report wrapper. */
 const AVAILABILITY_REPORT_BODY_LIMIT = 3_200;
 const AVAILABILITY_REPORT_KEY_PREFIX = "availability/";

package/src/setup-discover.ts

@@ -0,0 +1,425 @@
+/** Deterministic, fail-open facts used to pre-fill the setup interview. */
+
+export const DISCOVERY_TIMEOUT_MS = 5_000;
+
+export interface DiscoveryRunResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  timedOut?: boolean;
+}
+
+export type DiscoveryRunner = (
+  argv: readonly string[],
+  opts?: { cwd?: string },
+) => Promise<DiscoveryRunResult>;
+
+export interface DiscoveredRepoFacts {
+  defaultBranch?: string;
+  labels?: string[];
+  environments?: string[];
+  requiredChecks?: string[];
+}
+
+export interface DiscoveredFacts extends DiscoveredRepoFacts {
+  trackerRepo?: string;
+  routingKey?: string;
+  cloneUrl?: string;
+  artefacts?: string[];
+  roadmaps?: string[];
+  evidence?: string[];
+  skipped?: string[];
+}
+
+export interface DiscoveryTarget {
+  cwd: string;
+}
+
+function jsonObject(raw: string): Record<string, unknown> | undefined {
+  try {
+    const value: unknown = JSON.parse(raw);
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+      ? (value as Record<string, unknown>)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Parse `gh repo view --json defaultBranchRef`. */
+export function defaultBranchFrom(raw: string): string | undefined {
+  const ref = jsonObject(raw)?.defaultBranchRef;
+  if (typeof ref !== "object" || ref === null || Array.isArray(ref)) return undefined;
+  const name = (ref as Record<string, unknown>).name;
+  return typeof name === "string" && name.trim() !== "" ? name.trim() : undefined;
+}
+
+/** Parse `gh label list --json name`. */
+export function labelsFrom(raw: string): string[] | undefined {
+  try {
+    const value: unknown = JSON.parse(raw);
+    if (!Array.isArray(value)) return undefined;
+    const names: string[] = [];
+    for (const row of value) {
+      if (typeof row !== "object" || row === null || Array.isArray(row)) return undefined;
+      const name = (row as Record<string, unknown>).name;
+      if (typeof name !== "string" || name.trim() === "") return undefined;
+      names.push(name.trim());
+    }
+    return names;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Parse GitHub's environments REST response. */
+export function environmentsFrom(raw: string): string[] | undefined {
+  const rows = jsonObject(raw)?.environments;
+  if (!Array.isArray(rows)) return undefined;
+  const names: string[] = [];
+  for (const row of rows) {
+    if (typeof row !== "object" || row === null || Array.isArray(row)) return undefined;
+    const name = (row as Record<string, unknown>).name;
+    if (typeof name !== "string" || name.trim() === "") return undefined;
+    names.push(name.trim());
+  }
+  return names;
+}
+
+/** Parse branch protection, or the branch's latest check-runs fallback. */
+export function requiredChecksFrom(raw: string): string[] | undefined {
+  const parsed = jsonObject(raw);
+  if (parsed === undefined) return undefined;
+  const names: string[] = [];
+  const protection = parsed.required_status_checks;
+  if (protection === null) return [];
+  if (typeof protection === "object" && protection !== null && !Array.isArray(protection)) {
+    const status = protection as Record<string, unknown>;
+    if (!Array.isArray(status.contexts) && !Array.isArray(status.checks)) return undefined;
+    if (Array.isArray(status.contexts)) {
+      for (const context of status.contexts) {
+        if (typeof context !== "string" || context.trim() === "") return undefined;
+        names.push(context.trim());
+      }
+    }
+    if (Array.isArray(status.checks)) {
+      for (const check of status.checks) {
+        if (typeof check !== "object" || check === null || Array.isArray(check)) return undefined;
+        const context = (check as Record<string, unknown>).context;
+        if (typeof context !== "string" || context.trim() === "") return undefined;
+        names.push(context.trim());
+      }
+    }
+    return [...new Set(names)];
+  }
+
+  const runs = parsed.check_runs;
+  if (!Array.isArray(runs)) return undefined;
+  for (const run of runs) {
+    if (typeof run !== "object" || run === null || Array.isArray(run)) return undefined;
+    const name = (run as Record<string, unknown>).name;
+    if (typeof name !== "string" || name.trim() === "") return undefined;
+    names.push(name.trim());
+  }
+  return [...new Set(names)];
+}
+
+/** Parse a package manifest into the npm artefact it publishes. */
+export function artefactsFromPackage(raw: string): string[] | undefined {
+  const manifest = jsonObject(raw);
+  const name = manifest?.name;
+  if (manifest?.private === true) return undefined;
+  return typeof name === "string" && name.trim() !== "" ? [name.trim()] : undefined;
+}
+
+/** Parse a recursive Git tree into repository package-manifest paths. */
+export function packagePathsFrom(raw: string): string[] | undefined {
+  // A truncated recursive tree is a partial view of a large repository: a
+  // single visible manifest cannot be trusted as "the" artefact, so the whole
+  // field is unavailable rather than guessed from the slice GitHub returned.
+  if (jsonObject(raw)?.truncated === true) return undefined;
+  const tree = jsonObject(raw)?.tree;
+  if (!Array.isArray(tree)) return undefined;
+  const paths: string[] = [];
+  for (const row of tree) {
+    if (typeof row !== "object" || row === null || Array.isArray(row)) return undefined;
+    const path = (row as Record<string, unknown>).path;
+    if (typeof path !== "string") return undefined;
+    if ((path === "package.json" || path.endsWith("/package.json")) && !path.includes("node_modules/")) {
+      paths.push(path);
+    }
+  }
+  return paths;
+}
+
+/** Parse open milestones into operator-facing roadmap choices. */
+export function milestonesFrom(raw: string): string[] | undefined {
+  try {
+    const value: unknown = JSON.parse(raw);
+    if (!Array.isArray(value)) return undefined;
+    const choices: string[] = [];
+    for (const row of value) {
+      if (typeof row !== "object" || row === null || Array.isArray(row)) return undefined;
+      const milestone = row as Record<string, unknown>;
+      if (typeof milestone.title !== "string" || milestone.title.trim() === "") return undefined;
+      choices.push(
+        typeof milestone.html_url === "string" && milestone.html_url.trim() !== ""
+          ? `${milestone.title.trim()} — ${milestone.html_url.trim()}`
+          : milestone.title.trim(),
+      );
+    }
+    return choices;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Parse `gh project list --format json` into operator-facing roadmap choices. */
+export function projectsFrom(raw: string): string[] | undefined {
+  const projects = jsonObject(raw)?.projects;
+  if (!Array.isArray(projects)) return undefined;
+  const choices: string[] = [];
+  for (const row of projects) {
+    if (typeof row !== "object" || row === null || Array.isArray(row)) return undefined;
+    const project = row as Record<string, unknown>;
+    if (project.closed === true) continue;
+    if (typeof project.title !== "string" || project.title.trim() === "") return undefined;
+    choices.push(
+      typeof project.url === "string" && project.url.trim() !== ""
+        ? `${project.title.trim()} — ${project.url.trim()}`
+        : project.title.trim(),
+    );
+  }
+  return choices;
+}
+
+/** Parse a Git remote URL into the `owner/repo` spelling setup accepts. */
+export function trackerRepoFrom(raw: string): string | undefined {
+  const remote = raw.trim().replace(/\/$/, "").replace(/\.git$/, "");
+  if (remote === "") return undefined;
+  let path: string;
+  try {
+    path = new URL(remote).pathname;
+  } catch {
+    const colon = remote.indexOf(":");
+    if (colon === -1) return undefined;
+    path = remote.slice(colon + 1);
+  }
+  const parts = path.split("/").filter(Boolean);
+  if (parts.length !== 2 || parts.some((part) => !/^[A-Za-z0-9._-]+$/.test(part))) return undefined;
+  return `${parts[0]}/${parts[1]}`;
+}
+
+/** The routing key of a single repository is its clone URL's repository name. */
+export function routingKeyFromCloneUrl(raw: string): string | undefined {
+  return trackerRepoFrom(raw)?.split("/")[1];
+}
+
+/** A bounded subprocess runner. Missing executables and every other fault are data. */
+export const runDiscovery: DiscoveryRunner = async (argv, opts = {}) => {
+  try {
+    const proc = Bun.spawn([...argv], {
+      ...(opts.cwd === undefined ? {} : { cwd: opts.cwd }),
+      stdin: "ignore",
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      try {
+        proc.kill("SIGKILL");
+      } catch {
+        // The child won the race and already exited.
+      }
+    }, DISCOVERY_TIMEOUT_MS);
+    try {
+      const [exitCode, stdout, stderr] = await Promise.all([
+        proc.exited,
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+      ]);
+      return { exitCode, stdout, stderr, ...(timedOut ? { timedOut: true } : {}) };
+    } finally {
+      clearTimeout(timer);
+    }
+  } catch (err) {
+    return { exitCode: -1, stdout: "", stderr: err instanceof Error ? err.message : String(err) };
+  }
+};
+
+async function attempted(
+  run: DiscoveryRunner,
+  argv: readonly string[],
+  opts?: { cwd?: string },
+): Promise<DiscoveryRunResult> {
+  try {
+    return await run(argv, opts);
+  } catch (err) {
+    return { exitCode: -1, stdout: "", stderr: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+function failure(result: DiscoveryRunResult): string {
+  if (result.timedOut === true) return `timed out after ${DISCOVERY_TIMEOUT_MS / 1_000}s`;
+  const lines = result.stderr.trim().split("\n").filter(Boolean);
+  return lines.slice(-2).join(" ") || `command exited ${result.exitCode}`;
+}
+
+function parsed<T>(
+  label: string,
+  result: DiscoveryRunResult,
+  parse: (raw: string) => T | undefined,
+  skipped: string[],
+): T | undefined {
+  if (result.exitCode !== 0) {
+    skipped.push(`${label}: ${failure(result)}`);
+    return undefined;
+  }
+  const value = parse(result.stdout);
+  if (value === undefined) skipped.push(`${label}: gh returned a malformed reply`);
+  return value;
+}
+
+/** Detailed facts and diagnostics consumed by the wizard's discovery hook. */
+async function discoverRepoFactsDetailed(
+  repo: string,
+  run: DiscoveryRunner,
+): Promise<DiscoveredFacts> {
+  const evidence: string[] = [];
+  const skipped: string[] = [];
+  try {
+    const owner = repo.split("/")[0] ?? repo;
+    const [branchReply, labelsReply, environmentsReply, milestonesReply, projectsReply] = await Promise.all([
+      attempted(run, ["gh", "repo", "view", repo, "--json", "defaultBranchRef"]),
+      attempted(run, ["gh", "label", "list", "--repo", repo, "--limit", "1000", "--json", "name"]),
+      attempted(run, ["gh", "api", `repos/${repo}/environments?per_page=100`]),
+      attempted(run, ["gh", "api", `repos/${repo}/milestones?state=open&per_page=100`]),
+      attempted(run, ["gh", "project", "list", "--owner", owner, "--limit", "100", "--format", "json"]),
+    ]);
+
+    const defaultBranch = parsed("default branch", branchReply, defaultBranchFrom, skipped);
+    const labels = parsed("labels", labelsReply, labelsFrom, skipped);
+    const environments = parsed("release environments", environmentsReply, environmentsFrom, skipped);
+    const milestones = parsed("open milestones", milestonesReply, milestonesFrom, skipped);
+    const projects = parsed("Projects boards", projectsReply, projectsFrom, skipped);
+
+    if (defaultBranch !== undefined) evidence.push(`default branch "${defaultBranch}" — gh repo view ${repo}`);
+    if (labels !== undefined) evidence.push(`labels (${labels.join(", ") || "none"}) — gh label list --repo ${repo}`);
+    if (environments !== undefined) {
+      evidence.push(`release environments (${environments.join(", ") || "none"}) — GitHub environments for ${repo}`);
+    }
+
+    let requiredChecks: string[] | undefined;
+    let artefacts: string[] | undefined;
+    if (defaultBranch !== undefined) {
+      const branch = encodeURIComponent(defaultBranch);
+      const [protectionReply, treeReply] = await Promise.all([
+        attempted(run, ["gh", "api", `repos/${repo}/branches/${branch}/protection`]),
+        attempted(run, ["gh", "api", `repos/${repo}/git/trees/${branch}?recursive=1`]),
+      ]);
+      requiredChecks = parsed("required checks", protectionReply, requiredChecksFrom, []);
+      let checkEvidence = `branch protection for ${repo}@${defaultBranch}`;
+      if (requiredChecks === undefined) {
+        const runsReply = await attempted(run, ["gh", "api", `repos/${repo}/commits/${branch}/check-runs?per_page=100`]);
+        requiredChecks = parsed("required checks", runsReply, requiredChecksFrom, skipped);
+        checkEvidence = `latest check runs for ${repo}@${defaultBranch}`;
+      }
+      if (requiredChecks !== undefined) {
+        evidence.push(`merge checks (${requiredChecks.join(", ") || "none"}) — ${checkEvidence}`);
+      }
+
+      let packagePaths: string[] | undefined;
+      if (jsonObject(treeReply.stdout)?.truncated === true) {
+        skipped.push(
+          "release artefacts: the repository's recursive Git tree was truncated, so the visible manifests may be a partial view; the published artefact is left for you to type",
+        );
+      } else {
+        packagePaths = parsed("release artefacts", treeReply, packagePathsFrom, skipped);
+      }
+      if (packagePaths?.length === 1) {
+        const manifest = await attempted(run, [
+          "gh",
+          "api",
+          "-H",
+          "Accept: application/vnd.github.raw+json",
+          `repos/${repo}/contents/${packagePaths[0]}`,
+        ]);
+        artefacts = parsed("release artefacts", manifest, artefactsFromPackage, skipped);
+        if (artefacts !== undefined) {
+          evidence.push(`release artefact "${artefacts[0]}" — ${packagePaths[0]} package name`);
+        }
+      }
+    }
+
+    const roadmaps = projects === undefined && milestones === undefined
+      ? undefined
+      : [...new Set([...(projects ?? []), ...(milestones ?? [])])];
+    if (roadmaps !== undefined && roadmaps.length > 0) {
+      evidence.push(`roadmap candidates — GitHub Projects and open milestones for ${repo}`);
+    }
+
+    return {
+      ...(defaultBranch === undefined ? {} : { defaultBranch }),
+      ...(labels === undefined ? {} : { labels }),
+      ...(environments === undefined ? {} : { environments }),
+      ...(requiredChecks === undefined ? {} : { requiredChecks }),
+      ...(artefacts === undefined ? {} : { artefacts }),
+      ...(roadmaps === undefined ? {} : { roadmaps }),
+      evidence,
+      skipped,
+    };
+  } catch (err) {
+    return {
+      evidence,
+      skipped: [...skipped, `repo discovery: ${err instanceof Error ? err.message : String(err)}`],
+    };
+  }
+}
+
+/** Discover the four exact repository facts exposed as the module's pure API. */
+export async function discoverRepoFacts(
+  repo: string,
+  run: DiscoveryRunner = runDiscovery,
+): Promise<DiscoveredRepoFacts> {
+  const found = await discoverRepoFactsDetailed(repo, run);
+  return {
+    ...(found.defaultBranch === undefined ? {} : { defaultBranch: found.defaultBranch }),
+    ...(found.labels === undefined ? {} : { labels: found.labels }),
+    ...(found.environments === undefined ? {} : { environments: found.environments }),
+    ...(found.requiredChecks === undefined ? {} : { requiredChecks: found.requiredChecks }),
+  };
+}
+
+/** Discover `owner/repo` from the checkout's origin, or return no value. */
+export async function discoverTrackerRepo(
+  cwd: string,
+  run: DiscoveryRunner = runDiscovery,
+): Promise<string | undefined> {
+  const result = await attempted(run, ["git", "remote", "get-url", "origin"], { cwd });
+  return result.exitCode === 0 ? trackerRepoFrom(result.stdout) : undefined;
+}
+
+/** Compose checkout and GitHub facts for the wizard's single discovery hook. */
+export async function discoverFacts(
+  target: DiscoveryTarget,
+  run: DiscoveryRunner = runDiscovery,
+): Promise<DiscoveredFacts> {
+  const origin = await attempted(run, ["git", "remote", "get-url", "origin"], { cwd: target.cwd });
+  if (origin.exitCode !== 0) {
+    return { evidence: [], skipped: [`tracker repo: ${failure(origin)}`] };
+  }
+  const trackerRepo = trackerRepoFrom(origin.stdout);
+  if (trackerRepo === undefined) {
+    return { evidence: [], skipped: ["tracker repo: origin is not an owner/repo Git remote"] };
+  }
+  const cloneUrl = origin.stdout.trim();
+  const repo = await discoverRepoFactsDetailed(trackerRepo, run);
+  return {
+    ...repo,
+    trackerRepo,
+    cloneUrl,
+    routingKey: routingKeyFromCloneUrl(cloneUrl),
+    evidence: [`tracker repo "${trackerRepo}" — git remote get-url origin`, ...(repo.evidence ?? [])],
+  };
+}