simt-dev 0.4.0 → 0.6.0

package/docs/decisions/ADR-059-the-version-a-repository-runs-is-the-one-it-pinned.md

@@ -1,6 +1,6 @@
 # ADR-059 — The version a repository runs is the one it pinned, and the gate refuses otherwise
 
-Status: **accepted** · 2026-10-12 · affects all repos
+Status: **accepted** · 2026-10-12 · affects all repos · ruling 3's no-npm install and remedy superseded by [ADR-098](ADR-098-the-fourth-channel-is-one-file-and-it-needs-no-toolchain.md)
 
 ## Context
 

package/docs/decisions/ADR-097-the-channels-publish-by-hand-and-the-version-rides-in-as-an-input.md

@@ -0,0 +1,71 @@
+# ADR-097 — the channels publish by hand, and the version rides in as an input
+
+Status: **accepted** · 2026-10-25 · ruling 3's Homebrew precondition is superseded by [ADR-098](ADR-098-the-fourth-channel-is-one-file-and-it-needs-no-toolchain.md), which also restates what each channel now waits on
+
+**Affects:** `.github/workflows/publish.yml`,
+`.github/workflows/publish-channels.yml`, `scripts/publish-local.mjs`,
+`docs/decisions/ADR-058-one-tool-three-channels-and-the-order-is-forced.md`
+
+## Context
+
+ADR-058 ruled the three channels and the order between them — npm first, PyPI and
+Homebrew only once the npm version is live — and its ruling 7 also pinned the
+mechanics: the two channel jobs lived inside `publish.yml`, next to the staging job,
+and a maintainer re-ran them through "Re-run failed jobs" once `npm stage approve` had
+landed. The same ruling recorded why no `workflow_dispatch` could replace that:
+on a dispatch, `github.ref_name` is the branch, and the version guard would compare a
+tag against a branch.
+
+Running it that way taught something the ruling did not predict. The channel jobs fail
+on every release **by design** — the stage is not approvable until a human decides, so
+a healthy release hours in is a release whose run is red. A run that is red when
+nothing is wrong is the argument ADR-058 itself used against a gate that is red on the
+day it lands: it teaches the reader to ignore red. And the only supported recovery is
+re-running part of an old run, an action buried in the run page's retry menu rather
+than in anything a maintainer can name.
+
+The branch problem stays, but it points at a different fix. A dispatch cannot carry a
+tag in `ref_name`, but it doesn't have to: the version is one string, it is already
+written in exactly one place (`package.json`), and the maintainer who just approved
+the stage knows it — they typed or copied it to get here.
+
+## Ruling
+
+1. **`publish.yml` owns npm staging and stops there.** The tag workflow keeps the
+   version guard and the staging job, and no longer carries a job designed to sit red
+   for hours. A green publish run means "staged", and nothing in it promises more.
+
+2. **The channels run from `.github/workflows/publish-channels.yml`, a
+   `workflow_dispatch` whose `version` input is the release (e.g. `0.5.0`).** The
+   version is the *input*, not the ref, which is what dissolves the branch-vs-tag
+   failure ADR-058 recorded: the input travels into the guard, and the guard refuses
+   to run unless tag `v<version>` exists on the default branch's history and its
+   checkout's `package.json` agrees with it. A dispatch cannot guess; the input makes
+   guessing impossible.
+
+3. **The ordering ruling is unchanged.** Both channel jobs still begin with the check
+   that `npm view` serves the version (PyPI) and that the tarball is downloadable
+   (Homebrew), and both still name the remedy — `npm stage approve <stage-id>` —
+   when it is not. What moved is who runs the steps and how the version travels;
+   what did not move is that npm is live before either channel publishes.
+
+4. **The channel jobs keep their identity unchanged.** PyPI still publishes with
+   trusted publishing against the `pypi` environment; Homebrew still audits, renders
+   and pushes the formula to the tap. Nothing about the artefacts changed, so ADR-058
+   rulings 1–6 read as written.
+
+## Consequences
+
+A maintainer's release tour is two named actions instead of one retry:
+
+```
+npm stage approve <stage-id>
+gh workflow run publish-channels.yml -f version=<VER>
+```
+
+Red is honest again: a red channel run means a channel defect, and the release page
+carries no run whose expected end state is red. `scripts/publish-local.mjs` keeps its
+role as the not-CI twin — it mirrors `publish.yml` for npm and
+`publish-channels.yml` for the two channels, and its header now says exactly that,
+because a twin of a file whose name no longer holds what it did is a comment that
+misdescribes the artefact (the estate's own rule against decoration that lies).

package/docs/decisions/ADR-098-the-fourth-channel-is-one-file-and-it-needs-no-toolchain.md

@@ -0,0 +1,149 @@
+---
+simt-affects: ["scripts/build-sea.mjs", "src/distribute/release.mjs", "src/locate.mjs", "src/package-version.mjs", "src/hooks/shim.mjs", "src/ci/workflow.mjs", ".github/workflows/publish.yml", ".github/workflows/publish-channels.yml", "Formula/simt-dev.rb", "scripts/release-formula.mjs", "scripts/publish-local.mjs", ".gitignore", "test/binary.test.mjs", "test/ci.test.mjs", "test/packaging.test.mjs"]
+simt-supersedes: [{ adr: "ADR-058", ruling: 5 }, { adr: "ADR-058", ruling: 7, kind: "narrowed" }, { adr: "ADR-059", ruling: 3, kind: "superseded" }, { adr: "ADR-097", ruling: 3, kind: "narrowed" }]
+---
+
+# ADR-098 — The fourth channel is one file, and it needs no toolchain
+
+Status: **accepted** · 2026-10-26 · supersedes ADR-058 ruling 5 · narrows ADR-058 ruling 7 and ADR-097 ruling 3 · supersedes ADR-059 ruling 3
+
+Affects: `scripts/build-sea.mjs`, `src/distribute/release.mjs`, `src/locate.mjs`,
+`src/hooks/shim.mjs`, `src/ci/workflow.mjs`, `.github/workflows/publish.yml`,
+`.github/workflows/publish-channels.yml`, `Formula/simt-dev.rb`,
+`scripts/release-formula.mjs`, `scripts/publish-local.mjs`, `test/binary.test.mjs`
+
+## Context
+
+Review 0002's S35 ruled that no estate repository and no CI runner may be unable to
+obtain this tool, and ADR-059 shipped its first half: the remedy and the consumer CI
+step branch by repository kind. The half that did not ship is the one this record
+settles. For a repository without npm — a Gradle build, a Connect IQ project — every
+channel that existed needed a toolchain the repository does not have: the npm tarball
+needs npm, the wheel needs a Python, and the formula, until this record, declared
+`depends_on "node"` and so installed a command that could not start without one. The CI
+step that stood in for the missing channel ran `npm i -g simt-dev@<v>`, which needs the
+npm the repository kind is defined by not having. The one repository where the gate had
+no toolchain already was also the one where obtaining the tool required installing one.
+
+Two properties of the package made the alternative cheap. It has zero runtime
+dependencies and no build step (ADR-012), so "packaging" is copying ~1.3 MB of text
+around a pinned runtime; and the text reads its own shipped files — `rules/`,
+`templates/`, `docs/decisions/` — relative to `import.meta.url`, so it needs real files
+at real paths, not a module graph. Node's single-executable-application support embeds
+a script in an official node binary, and postject injects that blob into any target's
+copy of one; the missing half was a payload that materializes as a tree.
+
+## Ruling
+
+1. **A fourth artefact is released: one file per target, carrying the same payload the
+   npm tarball ships.** `scripts/build-sea.mjs` collects exactly `package.json`'s
+   `files` set plus `package.json` itself, and wraps it in a pinned official node base
+   at the version `engines` names. The targets are `darwin-arm64`, `darwin-x64` and
+   `linux-x64` — the set the one-line remedy and the consumer CI step can name — and a
+   platform outside it gets a loud 404, never a silent install of nothing. Each asset is
+   published to the GitHub release beside its `.sha256`, with a build-provenance
+   attestation binding the digest to the tag workflow's OIDC identity.
+
+2. **The payload materializes as real files before the tool runs.** The SEA entry is a
+   small CommonJS bootstrap (Node 22's SEA host runs the entry as CJS, whatever the
+   entry's own shape) that writes the embedded file set into
+   `${XDG_CACHE_HOME:-$HOME/.cache}/simt-dev/<node version>/<digest>/` and then imports
+   `bin/simt.mjs` from there. The digest is a hash of the canonical payload, so one
+   directory per payload, written to a staging directory and renamed into place, with a
+   marker file making a second run a no-op. Real files at real paths are what keep every
+   `import.meta.url`-relative read in `src/` working unmodified; a bootstrap that inlined
+   the tool instead would have to re-implement each one.
+
+3. **Determinism is the release contract, and the release checks it.** The same tree
+   builds byte-identical assets on any host: the node base is pinned, the SEA config uses
+   relative paths so no checkout path lands in the blob, and darwin binaries are ad-hoc
+   codesigned with a fixed identifier (without one, codesign derives the identifier from
+   the file path, which is what made two checkouts differ). Because of that, the tag
+   workflow re-builds each asset and fails the release when its checksum is not the one
+   `Formula/simt-dev.rb` in the tagged tree promises — the equality is checked, not
+   assumed.
+
+4. **Homebrew's artefact becomes the binary (supersedes ADR-058 ruling 5).** The formula
+   carries one `url`/`sha256` pair per target, selected by OS and CPU at install time,
+   and no longer declares `depends_on "node"`: the binary is the runtime. The "not
+   `std_npm_args`" half of ADR-058 ruling 5 stands unchanged — the formula still does no
+   build-time fetch of a package manager. `scripts/release-formula.mjs` patches each
+   pair by content, one url and the sha256 line that follows it, and refuses a formula
+   whose layout has drifted rather than patching blind.
+
+5. **The order each channel waits on is what that channel downloads (narrows ADR-058
+   ruling 7 and ADR-097 ruling 3).** PyPI still begins by checking that `npm view` serves
+   the version, because the npm channel is the one a maintainer has to approve by hand.
+   Homebrew now begins by checking that the release assets exist, because the formula
+   downloads those — a formula naming a tag whose binaries were never built installs a
+   404 just as surely as one naming an unapproved npm version. The ordering rule
+   survives; only its second premise moved.
+
+6. **The repository's own copy is checked before `PATH`, and the version pin still
+   decides.** The locator resolves `$SIMT_DEV_BIN`, then `node_modules`, then
+   `.simt/bin/simt`, then `PATH` — so the bytes a repository downloaded are the bytes its
+   gate runs, and a machine-wide install cannot shadow them. The dispatcher's version
+   comparison (ADR-059 rulings 1 and 2) is unchanged and still refuses a stale binary,
+   whatever path it was found by.
+
+7. **A repository without npm installs the binary with one command, and its CI needs no
+   Node (supersedes ADR-059 ruling 3's no-npm remedy).** The remedy the shim prints for
+   such a repository is one line — `curl` the asset for this machine into `.simt/bin` and
+   `chmod` it — with the platform derived at run time from `uname`, because the remedy is
+   committed text that a colleague on another machine will read. The generated consumer
+   workflow downloads the same asset, verifies it against the published `.sha256`, and
+   installs it into `.simt/bin` with no `setup-node` step at all; the install fails loudly
+   rather than letting a gate pass that never started. The remedy stays one line a reader
+   copies (it carries no checksum — the dispatcher re-verifies the version, and the
+   automated CI install is where the published checksum is checked).
+
+## Consequences
+
+- **The acceptance criterion is executable.** A Gradle fixture with every directory
+  containing `node` removed from `PATH` runs the release binary's `check` and its
+  `agent-hook` path, and the rendered hook shim hands over to `.simt/bin/simt` and
+  refuses when it is absent (`test/binary.test.mjs`). The test skips rather than fails on
+  a host that is not a release target or cannot reach `nodejs.org` for the base, because
+  a contributor's suite must still go green (ADR-031).
+- **One `files` list feeds three artefacts.** The npm tarball, the wheel and the binary
+  payload all derive from `package.json`'s `files`, so the parity ADR-058 ruled survives
+  the new artefact instead of being restated in a third place.
+- **The assets are large — one node runtime each.** That is the price of the only channel
+  a repository with no toolchain can use, and it is paid per release, not per install:
+  the payload is materialized once per node version and digest and reused after that.
+- **The formula's committed checksums are the deterministic build of this tree.** Editing
+  anything in the payload changes them, and a release whose build disagrees with the
+  formula fails at tag time — which is the moment the maintainer still has the tree in
+  front of them. The committed values are never a placeholder: they are what the next
+  tag of this tree must hash to.
+- **A repository that never downloads the binary is unaffected.** The locator's new
+  branch is one `[ -x … ]` test that is false when the path is absent, and the npm and
+  wheel channels do not consult it.
+
+## Rejected
+
+- **Bun and Deno `compile`.** Evaluated on their documented behaviour, not measured. The
+  package's `engines` floor is Node 22.20.0, its index is `node:sqlite` (ADR-089), and
+  every latency figure this plan records was taken on that runtime. A binary compiled by
+  another runtime would be the one channel not running the runtime the other three run,
+  so the records would stop describing it, and the estate would have to re-measure per
+  channel to say anything true about it. Node's SEA keeps every channel on the declared
+  runtime, and its base is an official node build — the thing that can be pinned and
+  attested byte-for-byte. If the floor ever moves to another runtime, the bootstrap is
+  the only part that needs rewriting, because the payload is plain files.
+- **A bundler that inlines the tool into one script.** The tool reads `rules/`,
+  `templates/` and its own decision records at run time; a bundle would have to
+  re-implement every `import.meta.url` root computation, and ADR-012's zero-dependency
+  rule leaves no bundler to depend on. The payload here is runtime-agnostic text; only
+  the wrapper is node-specific.
+- **An archive plus a runner script.** Two files is an install step, and the channel
+  exists so that a repository with no toolchain gets one file that runs.
+- **A checksum inside the one-line remedy.** The remedy is text a reader copies out of an
+  error message; adding a second verification command makes it no longer one line. The
+  download is TLS from the release, the dispatcher re-verifies the version the repository
+  pinned, and the automated install — the CI step, which no human is watching — is where
+  the published `.sha256` is checked before anything runs.
+- **`npm i -g simt-dev@<v>` for a repository without npm** (what ADR-059 ruling 3 ruled).
+  The command needs npm, which is the one thing the repository kind is defined by not
+  having; that this was the remedy for the kind it could not serve is the defect S35
+  found.

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "simt-dev",
-  "version": "0.4.0",
-  "description": "Shared agent rules, skills and git hooks for a repository: one command adopts a repo, and every gate it declares is probed before it is written.",
+  "version": "0.6.0",
+  "description": "An intelligence amplifier for AI coding agents: rules and dual gates adopted by one command, plus local retrieval, task briefs, benches and repo memory — deterministic by default, with local-model adapters that propose and never select.",
   "license": "Apache-2.0",
   "author": "Said Elimam",
   "private": false,
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/QuazarMedia/simt-dev"
+  },
   "engines": {
     "node": ">=22.20.0"
   },
@@ -14,7 +18,7 @@
     "linux"
   ],
   "bin": {
-    "simt": "bin/simt-dev.mjs"
+    "simt": "bin/simt.mjs"
   },
   "files": [
     "bin",
@@ -38,6 +42,6 @@
   ],
   "scripts": {
     "test": "node --test --test-concurrency=4 test/*.test.mjs",
-    "lint": "node bin/simt-dev.mjs doctor"
+    "lint": "node bin/simt.mjs doctor"
   }
 }

package/src/advice/advice.mjs

@@ -0,0 +1,229 @@
+// Model and effort advice, read from the repository's own bench history (plan 0003 R40).
+//
+// The mapping the design row asks for — task features to the cheapest tier that resolved
+// similar tasks — is data, not opinion: the records `bench run` stored on disk already say
+// which model classes resolved which mined tasks and what those runs cost. So the tier
+// ladder is the estate's own evidence sorted by price, and no vendor name is written into
+// the code: a repository whose history has one class of run gets advice about that class,
+// and one whose history has three gets a ladder with three steps.
+//
+// The properties this exists to keep:
+//
+//   * Advice, never a choice. The output is a sentence in the brief header along with the
+//     bench numbers behind it; the agent (or the human) names the model, not simt-dev
+//     (P2). Nothing here writes a model id into a config, a lock or a command.
+//   * Deterministic. No model, no network, no clock (P1): the same runs directory yields
+//     the same advice, so a reviewable claim about cost is possible.
+//   * Quiet in thin evidence. A neighborhood with no resolved run yields a caution, not a
+//     made-up tier; a history with no runs at all yields no advice line.
+//
+// The measure of "cheapest" follows the bench's own report: cost in dollars when the run
+// records or a prices table price the tokens, total tokens otherwise. Ordering by a number
+// that does not exist for any run would be nondeterminism, not economics.
+import { classifyTask } from '../brief/kind.mjs';
+import { computeRunCost, isRunResolved, loadPrices, loadRunRecords } from '../bench/report.mjs';
+import { loadTasks } from '../bench/tasks.mjs';
+import { CONFIG_DIR } from '../name.mjs';
+
+/**
+ * Every advice report carries its row's accept bar (ADR-076: a metric is a measurement or
+ * it is not claimed).
+ */
+export const METRIC_NOTE =
+  'advice is advisory until a held-out bench shows >= 25% cost cut at delta R >= -2 (plan 0003 R40)';
+
+const TIERS = ['small', 'default', 'frontier'];
+
+/**
+ * The ladder can specialize beyond kind only while there is still evidence to stand on:
+ * below this many same-kind tasks the kind is the whole neighborhood, and a narrower
+ * window makes evidence worse, not "more similar".
+ */
+const NARROW_MIN_POOL = 6;
+
+/** The narrowed window needs at least these resolved runs or it is not evidence either. */
+const NARROW_MIN_RESOLVED = 3;
+
+/** A file window is a step from the estimate in either direction — a factor of two in size. */
+const WINDOW_HALF = 2;
+
+function median(values) {
+  const sorted = [...values].sort((a, b) => a - b);
+  if (sorted.length === 0) return 0;
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+
+/**
+ * Tier for a rank in the cheapest-first ladder: thirds, not absolute cost — an estate's
+ * "frontier" relative to its own history means more than a number the code guessed.
+ * The cheapest of two observed classes is 'small' and the dearer one 'default'; a class
+ * is 'frontier' only once a ladder has three steps, because a two-step ladder cannot
+ * name a top third honestly.
+ */
+export function tierOfRank(rank, count) {
+  if (count < 3) return rank === 0 ? TIERS[0] : TIERS[1];
+  if (rank * 3 < count) return TIERS[0];
+  if (rank * 3 >= count * 2) return TIERS[2];
+  return TIERS[1];
+}
+
+/**
+ * Total tokens a usage report carries — the measure that exists even with no prices file.
+ */
+function tokensOf(usage = {}) {
+  const num = (v) => Number(v ?? 0);
+  return num(usage.input) + num(usage.cacheWrite ?? usage.cache_write) + num(usage.cacheRead ?? usage.cache_read) + num(usage.output);
+}
+
+/**
+ * Load bench history as advice-ready run rows.
+ *
+ * A descriptor missing for a run leaves the row with `kind: null`; such a run can join no
+ * neighborhood, which is the honest answer — a task whose prompt was never mined is a
+ * task whose kind would be a guess.
+ */
+export async function loadHistory(root) {
+  const [records, prices, tasks] = await Promise.all([
+    loadRunRecords(root),
+    // An unreadable prices file would throw out of a brief, whose callers only asked for
+    // a packet; the bench has its own report for surfacing a broken prices file loudly.
+    loadPrices(root).catch(() => null),
+    loadTasks(root),
+  ]);
+  const byId = new Map(tasks.map((task) => [task.id, task]));
+  const runs = records.map((record) => {
+    const descriptor = byId.get(record.task) ?? null;
+    return {
+      task: record.task,
+      model: record.model,
+      resolved: isRunResolved(record),
+      cost: computeRunCost(record, prices),
+      tokens: tokensOf(record.usage),
+      toolCalls: Number(record?.usage?.toolCalls ?? record?.usage?.tool_calls ?? 0),
+      files: Number(descriptor?.gold?.files ?? record?.diff?.files ?? 0),
+      kind: descriptor ? classifyTask(descriptor.prompt ?? '', { paths: [] }).kind : null,
+    };
+  });
+  return { runs };
+}
+
+/**
+ * Advise from bench history for one task's features.
+ *
+ * @param {{kind: string, files: number}} features the task kind, and the estimate of how
+ *   many files it will touch (the brief's scope size; a history run carries the mined
+ *   task's gold stat in the same role)
+ * @param {{runs: object[]}} history rows from loadHistory
+ * @returns null when the history holds no runs; otherwise `{ picked, caution }` where
+ *   `picked` is `{ line, basis, metric }` when a tier was named (and `caution` null), and
+ *   `caution` explains the missing neighborhood when no tier can honestly be named
+ */
+export function advise(features, history) {
+  const runs = history?.runs ?? [];
+  if (runs.length === 0) return null;
+  const kind = features.kind;
+  const sameKind = runs.filter((run) => run.kind === kind);
+  const taskCount = new Set(sameKind.map((run) => run.task)).size;
+  if (sameKind.length === 0) {
+    return {
+      picked: null,
+      caution: `bench history holds no ${kind} task, so no cheap tier was advised`,
+    };
+  }
+
+  // The measure is chosen once, across all resolved history: a ladder built on dollars
+  // while the pick ran on tokens would compare a number with a different number's name.
+  const measure = runs.some((run) => run.resolved && run.cost > 0) ? 'cost' : 'tokens';
+
+  // Kind decides the neighborhood. The file window only specializes a neighborhood that
+  // has already got evidence to spare (NARROW_MIN_*): a factor-of-two window around the
+  // estimate refines "bugfix" to "small bugfix" when the kind has runs to lend, and says
+  // nothing when it has not.
+  let pool = sameKind;
+  if (features.files > 0 && sameKind.length >= NARROW_MIN_POOL) {
+    const near = sameKind.filter(
+      (run) =>
+        run.files > 0 &&
+        run.files >= Math.ceil(features.files / WINDOW_HALF) &&
+        run.files <= features.files * WINDOW_HALF,
+    );
+    if (near.filter((run) => run.resolved).length >= NARROW_MIN_RESOLVED) pool = near;
+  }
+  const poolTaskCount = new Set(pool.map((run) => run.task)).size;
+
+  // The ladder orders every model class the estate ever ran, cheapest first, so the
+  // advice can say where its pick sits in the estate's whole history. Uncost evidence is
+  // still cost position: a class that never resolved one of these tasks occupies a rung
+  // in the price ladder, and the resolved floor below — not the ladder — decides whether
+  // the pick is allowed to stand on it.
+  const ladderValues = new Map();
+  for (const run of runs) {
+    const values = ladderValues.get(run.model) ?? [];
+    values.push(measure === 'cost' ? run.cost : run.tokens);
+    ladderValues.set(run.model, values);
+  }
+  const ladderNames = [...ladderValues.keys()].sort(
+    (a, b) => median(ladderValues.get(a)) - median(ladderValues.get(b)) || a.localeCompare(b),
+  );
+
+  const resolvedByModel = new Map();
+  for (const run of pool) {
+    if (!run.resolved) continue;
+    const values = resolvedByModel.get(run.model) ?? [];
+    values.push(measure === 'cost' ? run.cost : run.tokens);
+    resolvedByModel.set(run.model, values);
+  }
+
+  // "Resolved similar tasks" is a floor, not a style: a class that never resolved one of
+  // these tasks is cheaper because it failed for less money.
+  const qualifying = ladderNames.filter((model) => resolvedByModel.has(model));
+  if (qualifying.length === 0) {
+    return {
+      picked: null,
+      caution: `no model resolved any of the ${taskCount} ${kind} task${taskCount === 1 ? '' : 's'} in bench history, so no cheap tier was advised`,
+    };
+  }
+
+  // Ties break on the model name, so the same history always yields the same pick (P4).
+  const cheapest = [...qualifying].sort(
+    (a, b) => median(resolvedByModel.get(a)) - median(resolvedByModel.get(b)) || a.localeCompare(b),
+  )[0];
+  const ladderRank = ladderNames.indexOf(cheapest);
+  const tier = tierOfRank(ladderRank, ladderNames.length);
+
+  // Effort advice is relative to the estate too: heavier turns of tool use than the
+  // estate's own resolved median is what "plan first" means here.
+  const resolvedRuns = runs.filter((run) => run.resolved);
+  const estateToolCalls = median(resolvedRuns.map((run) => run.toolCalls));
+  const resolvedRunsOfCheapest = pool.filter((run) => run.resolved && run.model === cheapest);
+  const pickToolCalls = median(resolvedRunsOfCheapest.map((run) => run.toolCalls));
+  const effort = estateToolCalls > 0 && pickToolCalls > estateToolCalls ? 'plan first' : 'no plan mode';
+
+  const pickMedian = median(resolvedByModel.get(cheapest));
+  const pickUnit = measure === 'cost' ? `cost $${pickMedian.toFixed(4)}` : `tokens ${Math.round(pickMedian)}`;
+
+  return {
+    picked: {
+      line: `${tier} model, ${effort}`,
+      basis: `from ${poolTaskCount} ${kind} task${poolTaskCount === 1 ? '' : 's'} in bench history; cheapest that resolved: ${cheapest} (median ${pickUnit}); a human picks the model, this only ranks classes`,
+      metric: METRIC_NOTE,
+    },
+    caution: null,
+  };
+}
+
+/**
+ * The brief's door into advice (plan 0003 R40): history on disk in, advice out, or null
+ * when the history has no runs at all — a brief in a repository without bench history
+ * carries every other section and no made-up opinion about models.
+ *
+ * `kind` comes in already classified when the caller is the brief itself, so the packet
+ * never carries two opinions about one task.
+ */
+export async function briefAdvice(root, { task = '', scope = [], kind = null } = {}) {
+  const history = await loadHistory(root);
+  if (history.runs.length === 0) return null;
+  const known = kind ?? classifyTask(task, { paths: scope }).kind;
+  return advise({ kind: known, files: scope.length }, history);
+}