omp-conductor 0.13.0 → 0.15.0

package/src/availability.ts

@@ -0,0 +1,165 @@
+/**
+ * Mechanical operator availability in an IANA timezone (#273).
+ *
+ * This module owns the clock decision. Callers supply `now`; neither a model nor
+ * process-local memory decides whether an interruption is allowed. UTC-minute
+ * scanning for the next transition is intentional: evaluating the same local
+ * predicate across real instants handles skipped and repeated DST wall-clock
+ * minutes without inventing an offset conversion of our own.
+ */
+
+import { WEEKDAYS, type InterruptCategory, type ReportingPolicy, type Weekday, type WeeklyAvailability } from "./types.ts";
+
+const MINUTE_MS = 60_000;
+const TRANSITION_HORIZON_MS = 15 * 24 * 60 * MINUTE_MS;
+
+const formatters = new Map<string, Intl.DateTimeFormat>();
+interface CachedTransition {
+  from: number;
+  until: number;
+  open: boolean;
+  nextTransitionAt?: number;
+}
+
+const transitions = new WeakMap<WeeklyAvailability, CachedTransition>();
+
+
+function formatter(timezone: string): Intl.DateTimeFormat {
+  const existing = formatters.get(timezone);
+  if (existing !== undefined) return existing;
+  const created = new Intl.DateTimeFormat("en-GB", {
+    timeZone: timezone,
+    weekday: "short",
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    hourCycle: "h23",
+  });
+  formatters.set(timezone, created);
+  return created;
+}
+
+interface LocalMinute {
+  day: Weekday;
+  date: string;
+  clock: string;
+}
+
+function localMinute(at: number, timezone: string): LocalMinute {
+  const parts = formatter(timezone).formatToParts(new Date(at));
+  const get = (type: Intl.DateTimeFormatPartTypes): string =>
+    parts.find((part) => part.type === type)?.value ?? "";
+  return {
+    day: get("weekday").slice(0, 3).toLowerCase() as Weekday,
+    date: `${get("year")}-${get("month")}-${get("day")}`,
+    clock: `${get("hour")}:${get("minute")}`,
+  };
+}
+
+function previousDay(day: Weekday): Weekday {
+  const index = WEEKDAYS.indexOf(day);
+  return WEEKDAYS[(index + WEEKDAYS.length - 1) % WEEKDAYS.length]!;
+}
+
+/** Whether `at` falls inside the configured local weekly window. */
+export function availabilityOpen(window: WeeklyAvailability | undefined, at: number): boolean {
+  if (window === undefined) return true;
+  const local = localMinute(at, window.timezone);
+  if (window.start < window.end) {
+    return window.days.includes(local.day) && local.clock >= window.start && local.clock < window.end;
+  }
+  // Overnight: a selected day opens at `start` and remains open on the next
+  // local day until `end`.
+  return (
+    (window.days.includes(local.day) && local.clock >= window.start) ||
+    (window.days.includes(previousDay(local.day)) && local.clock < window.end)
+  );
+}
+
+export type InterruptDisposition = "interrupt" | "digest" | "availability";
+
+export function availabilityDisposition(
+  window: WeeklyAvailability | undefined,
+  category: InterruptCategory,
+  at: number,
+): Exclude<InterruptDisposition, "digest"> {
+  if (window === undefined || availabilityOpen(window, at) || window.bypass.includes(category)) {
+    return "interrupt";
+  }
+  return "availability";
+}
+
+/**
+ * Decide one tier-2 category. `digest` means the category policy itself defers
+ * it; `availability` means it was otherwise interruptible and may be released
+ * when the configured window next opens.
+ */
+export function interruptDisposition(
+  policy: ReportingPolicy | undefined,
+  category: InterruptCategory,
+  at: number,
+): InterruptDisposition {
+  if (policy !== undefined && !policy.interruptOn.includes(category)) return "digest";
+  return availabilityDisposition(policy?.availability, category, at);
+}
+
+export interface AvailabilityState {
+  mode: "always" | "working" | "quiet";
+  timezone?: string;
+  nextTransitionAt?: number;
+  bypass: InterruptCategory[];
+}
+
+/** Current mode plus the first real instant at which that mode changes. */
+export function availabilityState(policy: ReportingPolicy | undefined, now: number): AvailabilityState {
+  const window = policy?.availability;
+  if (window === undefined) return { mode: "always", bypass: [] };
+
+  const from = Math.floor(now / MINUTE_MS) * MINUTE_MS;
+  let cached = transitions.get(window);
+  if (cached === undefined || from < cached.from || from >= cached.until) {
+    const open = availabilityOpen(window, now);
+    const end = now + TRANSITION_HORIZON_MS;
+    let cursor = from + MINUTE_MS;
+    while (cursor <= end && availabilityOpen(window, cursor) === open) cursor += MINUTE_MS;
+    cached = {
+      from,
+      until: cursor,
+      open,
+      ...(cursor > end ? {} : { nextTransitionAt: cursor }),
+    };
+    transitions.set(window, cached);
+  }
+
+  const { open, nextTransitionAt } = cached;
+  return {
+    mode: open ? "working" : "quiet",
+    timezone: window.timezone,
+    ...(nextTransitionAt === undefined ? {} : { nextTransitionAt }),
+    bypass: [...window.bypass],
+  };
+}
+
+/** Stable operator-facing local timestamp for status and tick prompts. */
+export function formatZonedMinute(at: number, timezone: string): string {
+  const local = localMinute(at, timezone);
+  return `${local.date} ${local.clock} ${timezone} (${new Date(at).toISOString()})`;
+}
+
+/** One prompt sentence; the runtime gate, not this prose, owns the decision. */
+export function availabilityPrompt(policy: ReportingPolicy | undefined, now: number): string {
+  const state = availabilityState(policy, now);
+  if (state.mode === "always") {
+    return "Operator availability (mechanical): 24-hour interrupts; no working-hours window is configured.";
+  }
+  const until =
+    state.nextTransitionAt === undefined || state.timezone === undefined
+      ? "the next configured transition"
+      : formatZonedMinute(state.nextTransitionAt, state.timezone);
+  const bypass = state.bypass.length === 0 ? "none" : state.bypass.join(", ");
+  return state.mode === "working"
+    ? `Operator availability (mechanical): working until ${until}; outside-hours bypass: ${bypass}.`
+    : `Operator availability (mechanical): quiet until ${until}; only these categories bypass quiet hours: ${bypass}.`;
+}

package/src/board.ts

@@ -7,6 +7,7 @@ import {
   codeGraphFromHealthz,
   fleetLayers,
   probeTelegramHealth,
+  workerPhasesFromHealthz,
   type FleetLayers,
   type TelegramHealth,
 } from "./fleet.ts";
@@ -922,36 +923,6 @@ export function renderBoard(
   ].join("\n");
 }
 
-export function workerPhasesFromHealthz(
-  body: string | undefined,
-  project: string,
-): ReadonlyMap<number, WorkerPausePhase> {
-  const phases = new Map<number, WorkerPausePhase>();
-  if (body === undefined) return phases;
-  try {
-    const payload = JSON.parse(body) as unknown;
-    if (payload === null || typeof payload !== "object") return phases;
-    if (Reflect.get(payload, "project") !== project) return phases;
-    const workers = Reflect.get(payload, "workers");
-    if (!Array.isArray(workers)) return phases;
-    for (const worker of workers) {
-      if (worker === null || typeof worker !== "object") continue;
-      const issue = Reflect.get(worker, "issue");
-      const phase = Reflect.get(worker, "phase");
-      if (
-        Number.isSafeInteger(issue) &&
-        (issue as number) > 0 &&
-        (phase === "pausing" || phase === "paused")
-      ) {
-        phases.set(issue as number, phase);
-      }
-    }
-  } catch {
-    // An unreadable health body means no trustworthy pause phase.
-  }
-  return phases;
-}
-
 async function probeBoardHealth(project: ProjectConfig): Promise<BoardHealthProbe> {
   const layers = fleetLayers(project.name);
   const record = livingDaemon();
@@ -966,8 +937,24 @@ async function probeBoardHealth(project: ProjectConfig): Promise<BoardHealthProb
   else if (health?.ok !== true) daemon = "unreachable";
   else {
     try {
-      const payload = JSON.parse(health.body ?? "null") as { project?: unknown };
-      daemon = payload.project === project.name ? "ok" : "other-project";
+      const payload = JSON.parse(health.body ?? "null") as unknown;
+      if (payload === null || typeof payload !== "object") {
+        daemon = "unreachable";
+      } else if (Reflect.get(payload, "project") === project.name) {
+        daemon = "ok";
+      } else {
+        const projects = Reflect.get(payload, "projects");
+        daemon =
+          Array.isArray(projects) &&
+          projects.some(
+            (entry) =>
+              entry !== null &&
+              typeof entry === "object" &&
+              Reflect.get(entry, "project") === project.name,
+          )
+            ? "ok"
+            : "other-project";
+      }
     } catch {
       daemon = "unreachable";
     }

package/src/brief-upgrade.ts

@@ -575,7 +575,7 @@ export function formatBriefReport(path: string, layout: BriefLayout, missing: re
     return [
       `brief ${path}`,
       "",
-      "No brief here yet. Run /conductor setup and say yes to writing ORCHESTRATOR.md;",
+      "No brief here yet. Run `omp-conductor setup brief` and say yes to writing ORCHESTRATOR.md;",
       "it writes POLICY.md beside it, which is the half you then own.",
     ].join("\n");
   }

package/src/briefs/orchestrator.md

@@ -16,8 +16,10 @@ Point the heartbeat at the workspace that holds `ORCHESTRATOR.md` /
 `POLICY.md` — a `.conductor-tick.json` whose default message re-reads both.
 
 This floor ships conservative so an unedited `POLICY.md` is still a safe fleet.
-To tailor Releases and Project context, ask an omp session to read
-`skill://conductor-onboarding` and onboard you.
+To tailor Releases and Project context, run `omp-conductor setup brief`: it asks
+the judgment questions no repo reading can answer, then reads your repos to draft
+the rest and shows each draft for confirmation. Editing `POLICY.md` by hand does
+the same job.
 
 ---
 
@@ -154,6 +156,7 @@ to notice it unaided.
 | `undisclosed-file` | The PR touched a file the report never mentioned. | Open the diff for that file. An undisclosed edit is usually incidental — a lockfile, a formatter — and occasionally the whole story. |
 | `changed-line-missing` | The report disclosed nothing at all. | Read the diff before merging; you have no summary of it. |
 | `unmatched-claim` | The report named a file the PR never touched. | Weak on its own. Two or three together mean the report was written from memory rather than from `git diff`, so trust the rest of it less. |
+| `report-format-unparsed` | The audit could not parse the report's format. | Not a trust signal against the worker — read the diff directly. |
 | `test-file-deleted` | A test file left the tree and no rename explains it. | The one that most deserves a human. Was the behaviour it defended deleted too, or only its test? |
 | `test-disabled` | A `.skip` / `.only` / `xit` / `t.Skip` marker was added. | Ask what turned red. A skip added in the same PR as the change it stopped failing is the shape to look for. |
 | `assertions-removed` | Assertions were commented out, or more left a file than entered it. | Compare against the issue's acceptance criteria: an assertion removed because the spec changed is fine, one removed because it failed is not. |
@@ -230,25 +233,52 @@ Keep the queue worth draining.
 See **Reporting** below. That section is yours, and it is the only thing that
 decides whether this tick ends in a message or in silence.
 
+Whenever the reporting policy defers material outcomes to a digest, record each
+ordinary outcome as soon as it happens:
+
+```bash
+omp-conductor event record \
+  --category merge \
+  --summary "#42 merged" \
+  --evidence "https://github.com/acme/api/pull/42"
+```
+
+This command sends nothing. It writes the outcome to the durable digest ledger.
+Use a short lowercase category, a one-line summary, and the issue, PR, release,
+run, or URL that proves the result. Do not keep an outcome only in session memory
+or in a Markdown scratch file. A later due-digest prompt lists the owed rows
+with their ids. Include the rows you use by passing its printed `--events` and
+`--notices` arguments to `omp-conductor report --kind digest`; omitted rows stay
+owed. When policy permits material outcomes to interrupt, report them directly
+instead.
+
 *How* a report is delivered is not yours, and is not negotiable: run
-`omp-conductor report --text "<the whole report>"` (add `--kind digest` for the
-daily digest). It persists the text before anything is sent and prints a report
-report id; the daemon retries until it lands and `omp-conductor status` lists whatever
-has not. Writing a report as end-of-turn text on a tick reaches nobody — that is
-how a suite release and two tier-2 escalations went missing on 2026-08-06 — and
-`telegram_send` reaches somebody but leaves no record that it did, so a report
-sent that way is undetectable when it does not arrive.
+`omp-conductor report --text "<the whole report>"` (add `--kind digest` plus
+the ledger row ids printed in the tick prompt for a digest). It persists the
+text before anything is sent and prints a durable handoff id: a report id when
+delivery is allowed, or a held-notice id until a digest or working-hours
+catch-up claims it. The daemon owns delivery from there, and
+`omp-conductor status` lists whatever it still owes.
+Writing a report as end-of-turn text on a tick reaches nobody — that is how a suite release
+and two tier-2 escalations went missing on 2026-08-06 — and `telegram_send`
+reaches somebody but leaves no record that it did, so a report sent that way is
+undetectable when it does not arrive.
 
 A report is an update. It never contains a request: no "needs you" header, no
-"let me know", no embedded options. Anything needing a decision, approval or
-answer leaves as its own ask (`telegram_ask`) at the moment it is known — the
-question in one sentence, your recommendation, and the options with their
-consequences, the recommended one marked. Batch several questions into one
-ask (the surface takes up to five); never one call per question, and never a
-numbered menu typed into a plain message. Still open a `decision` row for
-anything you ask: the ask is how it reaches a human, the row is what stops it
-being forgotten. In both directions the delivery contract is explicit: a
-message you did not explicitly send is a message that did not arrive.
+"let me know", no embedded options. Use `telegram_ask` for each decision,
+approval, or answer that you need. Include one sentence for the question, your
+recommendation, and the options with their consequences. Mark the recommended
+option. Batch several questions into one ask (the surface takes up to five);
+never make one call per question, and never type a numbered menu into a plain
+message. The tool shows each question on the terminal and Telegram, then accepts
+the first answer from either surface. A returned answer proves an answer, not
+Telegram delivery. If the question must demonstrably reach the operator through
+Telegram, send it separately with `telegram_send` and prefix its text
+`QUESTION:` so the autonomous-tick gate applies the decision category. Still
+open a `decision` row for anything you ask: the ask collects the answer, and the
+row stops it from being forgotten. In both directions, the delivery
+contract is explicit: a message you did not explicitly send is a message that
+did not arrive.
 
 ## Human messages
 
@@ -259,10 +289,11 @@ text you merely write reaches nobody — if you do not call `telegram_send`, the
 person gets silence. While handling any turn, produce no visible commentary
 between tool calls — reasoning stays in thinking, actions stay in tools.
 
-If the answer needs a decision from the operator (a choice, a yes/no, an
-approval), ask it with `telegram_ask` — never a numbered-options message via
-`telegram_send`, and never the generic `ask` UI. A cancelled or errored
-`telegram_ask` is a delivery failure, not an answer.
+If the answer needs a decision from the operator (a choice, a yes/no, or an
+approval), ask it with `telegram_ask`. Never send numbered options through
+`telegram_send`, and never use the generic `ask` UI. The tool returns the first
+answer from the terminal or Telegram. A returned answer proves an answer, not
+Telegram delivery. A cancelled or errored `telegram_ask` is not an answer.
 
 A message may also reach you **mid-tick** (delivery is steering: it arrives
 between two of your tool calls). Treat it as an interrupt, not a new tick:
@@ -280,6 +311,13 @@ arrived, and never batch the answer "for the report" — the person is waiting n
 Promote rather than improvise. Escalating is a successful outcome; guessing is
 not.
 
+The tick prompt carries the runtime's mechanical operator-availability state.
+Escalate tier 2 normally; do not infer working hours or bypass the configured
+gate yourself. Outside the configured window, the daemon holds non-bypass
+categories durably for the daily digest or one catch-up report when the window
+opens. Configured bypass categories still page immediately. With no window,
+interrupt behavior remains 24-hour.
+
 ## Hard boundaries
 
 Not yours to relax:
@@ -385,9 +423,11 @@ Four controls stop different work:
   spend a failure or continuation budget. Use it when the operator explicitly
   ends obsolete or already-delivered work. A salvage failure keeps the tree and
   names the path; recover that copy before any forced unblock.
-- **Fleet dispatch:** `omp-conductor pause` stops new claims and work-starting
-  mutations. Work admitted before the pause may still complete, and completion
-  verbs and releases remain available.
+- **Fleet dispatch:** `omp-conductor hold` stops new claims and work-starting
+  mutations. Work admitted before it may still complete, and completion verbs and
+  releases remain available. Note it also disarms ticks, so it silences *you*:
+  stopping the fleet is the operator's call, and the right move is to report that
+  it needs stopping rather than to run this yourself.
 - **Orchestrator ticks:** `omp-conductor disarm` removes the operator-owned
   `ARMED` marker so ticks skip. It does not pause workers or stop processes.
 
@@ -458,12 +498,13 @@ The protocol, in order:
    stand, then the lines you propose. A diff, not a description of one. This full
    text is what you *apply* on a yes — it is not what you send.
 2. **Ask, once — a single yes/no question, written for a phone.** Explicitly
-   call `telegram_ask`; never use the generic `ask` UI. Confirm that the tool
-   delivered the question to the configured Telegram chat. It is mounted on a
-   locally injected tick only once your operator has configured the bridge's
-   notify destination, and a tick that lacks it says so in its own text. When it
-   does, send the same single yes/no question with `telegram_send` and treat
-   your operator's later reply as the answer — never assume one. Telegram renders
+   call `telegram_ask`; never use the generic `ask` UI. The tool shows the
+   question on the terminal and Telegram, then returns the first answer from
+   either surface. A returned answer proves an answer, not Telegram delivery.
+   If the proposal must demonstrably reach the operator through Telegram, send
+   the compact question separately with `telegram_send`. If `telegram_ask` is
+   unavailable, send the same single yes/no question with `telegram_send`.
+   Wait for the operator's later reply, and never assume one. Telegram renders
    none of your markdown, so asterisks and backticks arrive as literal characters:
    - Lead with one plain sentence: what changes, and why, in your own words.
    - Then show only the lines that actually change, compact, under two short

package/src/briefs/policy.md

@@ -52,46 +52,55 @@ propose the corrected steps.
 
 ## Project context (filled during onboarding)
 
-Empty until an onboarding session fills it in: the product in a paragraph, a map
-of which repo owns what, and the grooming guidance Duty 2 needs to judge priority
-and spot issues that would collide. Ask an omp session to read
-`skill://conductor-onboarding` to have it written.
+Empty until setup fills it in: the product in a paragraph, a map of which repo
+owns what, the grooming guidance Duty 2 needs to judge priority and spot issues
+that would collide, and where the roadmap lives. `omp-conductor setup` asks for
+the last of those and proposes the rest.
 
 ## Reporting
 
-Your report scope is **`{{REPORT_SCOPE}}`**. All three scopes, spelled out:
-
-- **`escalations`** — you speak when a human is needed, and once a day otherwise.
-  That is: every tier-2 escalation immediately, carrying the issue link and the
-  single question; plus one daily digest naming what merged, what is green and
-  waiting on a merge, and what is stuck and why. Every other tick is silent.
-- **`decisions`** — tier-2 escalations immediately, and a fleet-stopping
-  condition immediately; every other material event is held and delivered as one
-  message with the next tick report. A merge at 10:04 and a green PR at 10:09
-  arrive together at the 10:15 tick, not as two pings.
+The live report scope and availability window come from conductor config on
+every tick; the tick's `Reporting` and `Operator availability` lines are
+authoritative. All four scopes, spelled out:
+
+- **`escalations`** — you speak when a human is needed, and otherwise wait for
+  the configured digest. That is: every tier-2 escalation when operator
+  availability permits, carrying the issue link and the single question; plus
+  a digest naming what merged, what is green and waiting on a merge, and what is
+  stuck and why.
+- **`decisions`** — tier-2 escalations and fleet-stopping conditions interrupt
+  when operator availability permits; every other material event is held and
+  delivered in the configured digest instead of as its own ping.
 - **`material`** — everything in `escalations`, plus each material event as it
-  happens: a run reaching a green PR (with the link), a run that failed twice, an
-  issue you pulled off the queue, a cap that stopped the fleet. A tick where
-  nothing changed still says nothing — "no change" is not an event.
-
-**Delivery.** Never rely on end-of-turn text reaching anyone. The only delivery
-paths are `omp-conductor report` (reports — persisted, daemon-retried),
-`telegram_send` (a person who is waiting), and `telegram_ask` (a decision).
-Everything else is noise or silence. Hand every reportable event to the
-conductor's outbox:
+  happens when operator availability permits: a run reaching a green PR (with
+  the link), a run that failed twice, an issue you pulled off the queue, a cap
+  that stopped the fleet. Outside configured hours, non-bypass interruptions
+  wait for the next configured digest or opening. A tick where nothing changed
+  still says nothing.
+- **`quiet`** — tier-2 escalations, fleet stops, and confirmed failures may
+  interrupt when operator availability permits; everything else waits for one
+  daily rollup.
+
+**Delivery.** Never rely on end-of-turn text reaching anyone. The provable
+delivery paths are `omp-conductor report` (reports — persisted and retried by
+the daemon) and `telegram_send` (direct messages). `telegram_ask` is the decision
+primitive, not Telegram delivery evidence. Everything else is noise or silence.
+Hand every reportable event to the conductor's outbox:
 
 ```
 omp-conductor report --text "<the whole report>"          # a material event
 omp-conductor report --text "<the whole digest>" --kind digest
 ```
 
-The command persists the text *before* anything is sent and prints a report id;
-from there the daemon owns delivery and retries until it lands, so a report
-survives you being compacted, interrupted, or restarted mid-sentence. That is
-the difference between a report and a claim about one: check for the report id,
-and never say something was reported without it. Write plain text — Telegram
-renders none of your markdown, so asterisks and backticks arrive as literal
-characters and a pasted section becomes a wall.
+The command persists the text *before* anything is sent and prints a durable
+handoff id. During quiet hours a material report becomes a held-notice id for
+the next digest or working-hours catch-up; otherwise it becomes a report id and
+the daemon retries delivery until it lands. Both survive you being compacted,
+interrupted, or restarted mid-sentence. That is the difference between a report
+and a claim about one: check for the handoff id, and never say something was
+reported without it. Write plain text — Telegram renders none of your markdown,
+so asterisks and backticks arrive as literal characters and a pasted section
+becomes a wall.
 
 The digest is at-most-once per day and the ledger decides that, not your memory:
 a second `--kind digest` on the same day is refused and tells you which report
@@ -100,12 +109,15 @@ was lost mid-send is retried and arrives marked as a possible repeat; that is
 deliberate, and a duplicate you can spot by its report id is the cheaper of the
 two mistakes. `omp-conductor status` lists anything still undelivered.
 
-`telegram_send` is still the right call for talking to a person who is waiting —
-an answer to their message, or a question of your own. It is not a report: it
-leaves no record that anything went out. And a `cancelled` or errored
-`telegram_ask` is a delivery failure, not an answer: re-deliver the question with
-with `telegram_send`, or report the channel as broken. It is never "asked once, no
-reply, dropped".
+`telegram_send` is still the right call for direct delivery to a person who is
+waiting — an answer to their message, or a question of your own. It is not a
+report: it leaves no record that anything went out. `telegram_ask` is the right
+call for a decision. It shows the question on the terminal and Telegram, then
+returns the first answer from either surface. A returned answer proves an
+answer, not Telegram delivery. A cancelled or errored `telegram_ask` is not an
+answer: re-deliver the question with `telegram_send`, prefixing its text
+`QUESTION:` so an autonomous tick applies the decision category, or report the
+channel as broken. It is never "asked once, no reply, dropped".
 
 Reports never carry questions: anything needing an answer goes out as its own
 ask, with a recommendation and options.

package/src/briefs/probes/gates.md

@@ -0,0 +1,51 @@
+You are reading one repository to answer a single question for an operator who is
+configuring an automated dispatcher. You have been given
+reading tools only: there is no shell, no editor and no verb here, so reading and
+answering is the whole of what you can do.
+
+## The question
+
+What are the **pre-push gates** for `{{REPO}}` (branch `{{BRANCH}}`)? A pre-push
+gate is a command a change must pass locally *before* it is pushed, and the answer
+is only useful if it matches what CI actually runs.
+
+## Where to look
+
+In this order, stopping when you have enough:
+
+1. CI workflow definitions — `.github/workflows/*.yml`, or the equivalent for
+   whatever CI this repo uses. This is the authority: it is what will fail a PR.
+2. `package.json` scripts, `Makefile`, `justfile`, `Taskfile.yml`, `tox.ini`,
+   `pyproject.toml`, `Cargo.toml`.
+3. Any `CONTRIBUTING.md` / `AGENTS.md` / `CLAUDE.md` that names a pre-push
+   routine.
+
+## Three traps, each of which produces a wrong answer
+
+- **Whole tree, not source directory.** If CI lints the repository and a script
+  lints only `src/`, the gate is the repository-wide command. A gate narrower than
+  CI is how a lint error reaches the runners with nobody watching.
+- **Cheap only.** Gates run on a shared host, many at once. Include type checks,
+  lint and unit tests. **Exclude** docker builds, image builds, production builds,
+  browser/e2e suites, and anything that needs a service or a credential — CI owns
+  those.
+- **An honest "no gates" is a real answer.** If this repo genuinely has no cheap
+  local check, say so with an empty list. Inventing a plausible `npm test` for a
+  repo that has no test script produces a gate that fails on every push.
+
+Each gate needs the **`cwd` it runs from**, relative to the repository root, as a
+monorepo's checks usually do not run from the top. Use `"."` for the root.
+
+## Answer
+
+One fenced JSON block, nothing else after it:
+
+```json
+{
+  "gates": [{ "cmd": "bun run check", "cwd": "." }],
+  "evidence": "one line naming the files you read that establish these"
+}
+```
+
+`evidence` is what lets the operator judge your answer without repeating your
+reading. Name files, not impressions.

package/src/briefs/probes/project-context.md

@@ -0,0 +1,59 @@
+You are reading one repository to draft a section of an operator's standing brief.
+You have been given reading tools only: there is no shell,
+no editor and no verb here, so reading and answering is the whole of what you can
+do.
+
+## What you are writing
+
+The `## Project context` section of `POLICY.md`, which a supervising orchestrator
+session re-reads on **every** tick. Keep it **under 40 lines**: a brief nobody
+finishes reading is a brief that gets skimmed.
+
+It needs exactly four things, in this order.
+
+1. **The product in one paragraph.** What it does, for whom. Not a feature list.
+2. **A repo map** — one line per routing key below, naming what that repo owns in
+   the operator's vocabulary. This is what turns a routing label into a judgement.
+3. **Grooming guidance.** Which repos ship together, so a change in one is known
+   to need a matching PR in the other. And which *kinds* of issue touch the same
+   files: those must not be queued concurrently, because two agents editing one
+   file produce two pull requests that cannot both merge.
+4. **Where the roadmap lives, and how to judge priority against it** — in one
+   line.
+
+## Where you are
+
+Your working directory holds **one directory per routing repo**, each a shallow
+clone, listed below. Read across all of them — that is what makes items 2 and 3
+answerable, and a draft written from one repo has to guess the rest.
+
+In each, read the `README` (what it is for, and who uses it), whatever top-level
+architecture doc exists (`docs/`, `ARCHITECTURE.md`, an ADR directory) for which
+repo owns which concern, and `AGENTS.md` / `CONTRIBUTING.md` for the repo's own
+rules — those outrank the brief.
+
+## Stated inputs — these are given, not yours to decide
+
+The routing keys this project dispatches to, and the directory each was cloned
+into. Refer to repos by their **routing key**, never by the directory name — the
+directory is scratch, the key is what an issue carries:
+
+{{REPOS}}
+
+The operator's own answer about the roadmap and the current priority:
+
+> {{ROADMAP}}
+
+**Item 4 must quote that answer.** You are reading a repository, which shows what
+is open and never what matters; the operator supplied the ranking and it is not
+yours to improve. If the quote above is empty, write item 4 as a single line
+saying the operator has not named a roadmap yet, and nothing more.
+
+## Answer
+
+One fenced markdown block containing the section and nothing else — start it at
+the `## Project context` heading. No preamble, no commentary after it.
+
+Write what the repository supports. Where you are guessing, say so in the text
+itself in a few words: the operator edits this file, and a marked guess is one
+they can correct, while a confident invention is one they will not notice.