tldr-experts 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,6 +1,187 @@
 # Changelog
 
 
+## 0.11.0 — 2026-09-08
+
+### Fixed
+
+- **An answered decision now says who decided it, and what it binds to.** `tldrx answer`
+  wrote a fact with no attribution and no repo scope, so a superseded owner call and an
+  unattended driver default read identically in `facts.yml` and in every prompt built from
+  it. `--decided-by <owner|driver>` (last one wins, like any ordinary flag) and repeatable
+  `--repo <name>` land on the fact `answer` writes — `--decided-by` outside the closed set,
+  or `--repo` naming no workspace repo, is a usage refusal (exit 1) with nothing written, and
+  `--repo` passed twice scopes once. With neither flag the fact says "not stated," never a
+  guessed owner. `Fact.decided_by` is additive on `facts.yml`; `Fact.repos` already existed
+  and is required, not additive. (#169)
+- **Two signed facts that disagree produce a question, without an agent choosing to
+  notice.** The contradiction check now runs on every `answer`, scores the
+  new fact against the live ones in the same `area`, and — on a hit — RAISES an advisory
+  question (`asked_by: tldrx`, a new `advisory:` metadata key that opts a block out of
+  every reader that COUNTS open questions — the auto gate, `next`'s `awaiting_answer`
+  branch, `skip_if` and `tldrx status` — without hiding it from the readers that LIST
+  them, `tldrx questions` among them) rather than refusing the answer. The
+  new fact keeps `conflicts_with: [<id>]` naming the fact it contradicts (additive,
+  empty-omitted, unquoted) — which one is right is left to the question it raises, nothing in
+  the mechanism decides a "loser." "Not detected" never reads as "checked and agreed" — the
+  check is lexical, and honestly cannot catch what its own transcript produced here: three
+  differently-titled answers whose contents actually disagree. The new `fact.conflict_raised`
+  event (`{fact, conflicts_with, score, q, raised}`) joins the closed `EVENT_TYPES` enum.
+  (#169)
+- **A defect in a file no story declared has a sanctioned remedy and a visible home.**
+  Reaching it used to mean a hand edit to a story's `touches:` while the boundary card
+  described exactly the verb that edit needed and the CLI forbade it. Separately, and by
+  owner decision REPORT ONLY — no new gate condition, no new refusal, no new exit code — a
+  Build finding whose file matches no story's declared surface now reaches the Build
+  handoff, the PR body and the boundary card (only when a boundary trigger already draws
+  one), named as unowned rather than silently absorbed by whichever story happened to run
+  last. (#171)
+
+- **The developer bundle carries `result_schema` too, so both halves of one handshake make the
+  same promise.** Measured on disk in a real run: `.agent/<story>/pending.json` had no
+  `result_schema` while the reviewer bundle one directory down had one. The reviewer prompt says
+  in as many words to read the envelope shape out of the bundle and never from memory; the
+  developer had nothing to read it out of, so a host guessed the shape by copying a sibling
+  story's `result.json`, and a reviewer later "corrected" it from the other file. A developer
+  bundle — the Build story's, and every single-agent stage's — now carries the
+  `{outputs, questions_asked, notes}` envelope the spawned half is handed through
+  `claude --json-schema`, plus the `cost_usd` and `session_id` a host may declare and
+  `readResult` reads back. It is DERIVED from that schema rather than retyped, so a change to
+  the envelope cannot reach the spawn without reaching the bundle. The one thing the two halves
+  do not share is how strictly the schema is read, and that is now written down instead of
+  implied: a reviewer envelope is refused on its form, a developer envelope is coerced, and
+  `--commit --check` is what reports the difference.
+
+### Added
+
+- **`tldrx story widen <id> <path>... --note "<why>"`** — the verb the boundary card had
+  been pointing at while the CLI forbade the hand edit it described. Records
+  `story.touches_widened` (`{story, paths, note, before, after}`, joining the closed event
+  enum) and rewrites `touches:` through the same validated write every other command uses.
+  Refused (exit 2, nothing written) for a `done` story — naming `reopen --for-fix` as the
+  remedy — a `..` anywhere in a path (a substring test, not a segment one), a path already declared, an unknown story, or a plan the
+  story doesn't have; an unresolved run is exit 3 (not found), and `--for-fix` is not a flag
+  of `widen` itself and passing it is a usage refusal (exit 1). (#171)
+- **`tldrx budget grant <amount> --fact <id>`** — a ceiling that answers to a recorded
+  authorization instead of a bare number. Writes `authorized_usd` at run or phase scope, and
+  `authorized_by`/`authorized_at` always at the run level, citing the fact behind it (not
+  duplicated under a second key) — `--phase` scopes the amount, never the citation. Fires
+  `budget.granted` (`{amount_usd, fact, phase, note, ceiling_usd, previous_usd}`, joining the
+  closed event enum) — a second grant replaces the amount and the event records what it
+  replaced, `null` on the first grant; a non-positive amount is refused (exit 1, nothing
+  written), by the VALIDATOR as well as by the verb, so a hand-edited `authorized_usd: 0` —
+  which `grantFor` would otherwise read as a real $0 grant that blocks every later raise —
+  is a schema error rather than a record that quietly governs nothing. Absence is untouched:
+  no key still means no grant recorded, never `$0`. `on_grant_exceed` (default `warn`, distinct from and never confused with
+  `on_exceed`) says what a later `budget raise` past the grant does; `budget show` renders
+  the grant back and stays silent
+  when none is recorded. `--fact`/`--phase`/`--on-exceed` are refused (exit 1) on
+  `budget show` and `budget raise`, where recording a policy is not their job. All four keys
+  are additive on `budget.yml` — a file written before this change still loads and means no
+  grant. `DASHBOARD_MODEL_VERSION` is unchanged (3): `BudgetModel`/`BudgetPhaseModel` widen,
+  no existing field's meaning moved. (#170)
+- **`tldrx cost --stories`** — what a story cost against the ceiling its spawn was given,
+  one row per story, ceilings keyed off each `agent.spawned`'s `max_budget_usd` and money
+  keyed off the envelope's own metered `cost_usd`. A story with an unmetered turn among its
+  metered ones is named a lower bound, never handed the unqualified "inside the ceiling"
+  verdict; a story with no spawned ceiling is reported as absent, not as a zero; a run with
+  no story spawns says so instead of printing an empty table. The same arithmetic now
+  appends an over-ceiling clause to the Build handoff's existing cost line when the stories
+  behind it ran over. (#170)
+- **A run close, `run cancel`, `approve` and the Build handoff header all say how many of a
+  run's decisions name a decider.** One tally (`owner` / `driver` / not-stated), computed
+  once and read by all four surfaces; no sentence at all when the run recorded no facts,
+  never a confident zero. (#169)
+
+- **`workspace.yml` gains an optional `test_fast:` command — the developer iterates on it, and
+  the suite runs once at the Definition of Done.** A story's ```dod block must be byte-equal to
+  a `workspace.yml` command, and the developer prompt hands the sub-agent that same list with
+  "these commands are the only ones you may run". Between them, the only test instrument the
+  framework offered was the whole suite. Measured this week on three real workspaces: in one of
+  them that suite is 11,929 tests over 855 files, and a developer iterating a story ran it six
+  to ten times, on top of the two or three the Definition of Done itself pays for (preflight
+  once per run, cached; then once per attempt). The waste was never the gate — it was the
+  iteration loop, for which there was no faster instrument. `test_fast` is that instrument, and
+  it is deliberately not evidence: it is declared, so the developer may run it, and a ```dod
+  line equal to it is REFUSED with a sentence that names the slot rather than the generic "not
+  one of workspace.yml's commands", which would be false about a command the file plainly
+  declares. `tldrx init` does not guess it — no manifest says which subset of a suite is the
+  fast one, and a synthesised answer is exactly the conventional wisdom `command_probes:` exists
+  to keep out of this file — so the emitted `workspace.yml` carries the slot commented out with
+  a line saying what it is for, and nothing probes a slot nobody declared. When the workspace
+  declares one, the developer prompt says both halves: iterate on the fast command, and run the
+  declared full command once before you stop, because the gate re-runs it after. When it does
+  not, the prompt is byte-identical to the one before this existed. Additive: `version:` stays
+  `1`, and every workspace written without the slot loads and behaves exactly as it did.
+- **`tldrx next --commit --check` rehearses the commit and writes nothing, so a bad envelope
+  is caught while the turn is still open.** Measured on a real workspace this week: two reviews
+  were refused at `tldrx next --commit --review` because a `[src: …]` citation inside a `refuted`
+  finding was not the last thing on its line. Both refusals were correct; both arrived after the
+  turn had been paid for, and the host's answer was to ban `refuted` from the next thirty briefs
+  — a protocol feature switched off to dodge a late validator, which is the most expensive
+  possible outcome for a rule the framework got right. The reviewer cannot check itself: its
+  tools are `Read`, `Grep`, `Glob` and `Bash(git diff *)`, so there is no door to run a validator
+  through, and its prompt already states the end-of-line rule with a refused and an accepted
+  example generated from the reader's own patterns. What was missing was a way for the host to
+  ask "is this readable?" before saying the turn is done. `--check` validates the prepared
+  bundle's `result.json` through the SAME reader `--commit` uses — no second implementation of
+  the grammar, the dispositions or the verdict enum — prints every refusal verbatim with the
+  offending line, and exits `0` when `--commit` would read the envelope and `1` when it would
+  not. It takes no lock, moves no cursor, records no event and spends no attempt; the tests
+  compare `run.yml`, the story file and `events.jsonl` as bytes either side of the call. On a
+  developer bundle the reader is deliberately tolerant — a missing `outputs` is read as `[]`, a
+  non-string `notes` as `""` — so `--check` exits `0` and NAMES what is about to be coerced
+  rather than inventing a refusal the framework does not make. That naming goes down to the
+  ELEMENT, because the coercion that hides best is the one inside an array: `outputs` and
+  `questions_asked` are declared `items: {type: "string"}` and the reader silently FILTERS every
+  element that is not one, so `["good", 42, null, "also-good"]` is an array, passes any
+  whole-field type test, and still reaches the run as two entries. `--check` names each dropped
+  element by index and by the JSON of its value, through the same one-line predicate the reader
+  filters on — called, not restated, so the check cannot name a set the reader does not drop.
+  Nothing citable is lost in the bargain: a dropped element is by definition not a string, and a
+  `[src: …]` citation is a token inside one.
+
+### Changed
+
+- **The shipped stage and workflow money literals are labelled `[assumption]`**, and
+  deliberately NOT recalibrated: `tldrx init` copies no `stages/` into `.tldrx/`, so moving
+  one moves the ceiling of every workspace that never wrote an override, and this repo holds
+  no corpus to derive a new number from. `triage.budget_basis` (closed set: `model-guess` /
+  `owner-grant` / `preset`; additive on `RunFile`'s `triage:`, absent means nothing) records
+  which of the three produced a triage's numbers — `tldrx seed apply` always writes
+  `model-guess` today. `tldrx cost --stories` is the command that would produce the corpus a
+  recalibration needs. (#170)
+
+- **The Build stage ships `parallel: 2`, so a wave runs two stories at a time out of the box.**
+  `--parallel N` shipped in 0.3.1 and nothing used it: no shipped workflow and no shipped
+  stage file set it, so every workspace ran one story at a time by inheriting a code constant
+  nobody chose. Measured across three real workspaces over one week and 23 runs: runs of 34-43 h
+  wall clock whose per-story medians were 0.6-1.35 h — the wall clock was serialization, not work.
+  The stories of one wave are independent by construction (`waves.yml` puts every `depends_on` in
+  an EARLIER wave, and `validatePlan` refuses a plan that does not), so this is a schedule change
+  and not a correctness one; merges into the epic still happen serially, in the wave's listed
+  order, and so do the reviewers, whose merge base moves under them otherwise. Two rather than
+  more because one of those workspaces hit OOM kills at a wider fan-out — raise it per run with
+  `--parallel N`, or for good with `parallel: N` in your own `.tldrx/stages/build/stage.yml`.
+  `DEFAULT_PARALLEL` in code stays 1: the opinion belongs in the stage file an operator can read
+  and override, and the last resort stays the value that surprises nobody. The one thing
+  `parallel:` does not change is the `--prepare`/`--commit` handshake, which is per story and
+  stays sequential — that side cannot know how many sub-agents the host session will run. (#176)
+- **The "can this test fail?" check now names its instrument: one test file, not the whole
+  declared suite.** The drive mandate asked for the one check a reviewer cannot do — break the
+  line a new test covers and watch it go red — and the four stack packs asked the same question
+  under `## Checks`, telling the reader to "re-run the test command declared in
+  `.tldrx/workspace.yml`". That command IS the full suite by construction: a story's Definition
+  of Done is byte-equal to a `workspace.yml` command. So the words nobody read as "full suite"
+  bought exactly that, once per mutation — measured over a week of unattended runs on three real
+  workspaces, five mutations in a story meant five extra full suites, six to ten suite runs per
+  story, against a suite of 11,929 tests over 855 files in one of those workspaces. The check
+  keeps earning its place (it caught a test that only passed because base64 hid a raw id); what
+  was expensive was the instrument. The mandate and all four packs now scope the mutation re-run
+  to the single test file that covers the broken line, and say where the declared command
+  belongs: once, at the Definition of Done. The empty-slot clause is untouched — a workspace
+  that declares no test command is still named rather than quietly passed.
+
 ## 0.10.0 — 2026-09-07
 
 ### Fixed

package/README.md

@@ -163,8 +163,10 @@ its own refusal. See [10 Unattended mode](docs/guide/10-unattended-mode.md).
 | `security-patch` | auto | auto | — | human | human |
 | `migration` | auto | auto | auto | human | human |
 
-`--parallel <n>` on `next` / `run auto` builds that many of a wave's stories at once
-(merges still land in the wave's listed order; default 1 is unchanged).
+`--parallel <n>` on `next` / `run auto` builds that many of a wave's stories at once. The
+shipped Build stage declares `parallel: 2`, so a workspace that overrides nothing already runs
+two lanes; the code fallback stays 1, for a stage file that says nothing. Merges still land in
+the wave's listed order whatever the number is.
 
 A scope with `—` under `plan` does not run the Plan phase, and Build writes the one story that
 decision implies (`04-build/implicit-plan.yml`) from your What handoff rather than refusing;
@@ -314,6 +316,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.11.0 | 2026-09-08 | `beta` | governance that leaves a record: every answer says who decided it and what repo it binds, an advisory contradiction check raises a question that never stops a run and states its own limit, the close and the Build handoff count decided vs not-stated; `tldrx story widen` is the sanctioned way to grow a story's surface (a done story needs `reopen --for-fix` first) and a defect no story owns is named in the handoff, the PR body and the boundary card instead of absorbed; a budget grant is a recorded number in `budget.yml` that survives every writer, `budget raise` warns or refuses against it, presets are labelled as the assumptions they are, `triage.budget_basis` says where a figure came from and `tldrx cost --stories` measures each story against the ceiling its spawn was given, honest about lower bounds |
 | 0.10.0 | 2026-09-07 | `beta` | the mechanical blockers measured in real runs, fixed: a refused DoD command is recorded as refused (never a fabricated exit 126) in the event, the handoff, the review and retro logs, and the readers that used to recover it as green; the dirty-tree refusal prints the exact stash and pop commands and its true reason; the reviewer diffs the epic as it was before the merge (`epic_base` recorded on the story and the bundle) instead of an empty range; `tldrx init` probes each declared command once and records `command_probes` beside a `commands:` allowlist it never guesses; `tldrx ship` opens a PR whose body describes the change and its known defects, with the handoff folded underneath, and a state refusal that honours settled stories' declared touches; reviewer turns carry their token split and the spend basis reads it, so a whole provider no longer reads as absent |
 | 0.9.2 | 2026-09-07 | `beta` | the Build executor decomposed: 4,351 lines became an orchestrator plus eight modules under src/core/build/ (review ledger and phase cost, money caps, the DoD runner with its preflight cache, worktrees and epic-branch claims, the reviewer bundle and review round) — a pure refactor proven byte-for-byte by a golden guard over prompts, ordered events, run.yml rows and exit codes across three scenarios; no behaviour changed, every remaining hardening fix now lands in a file a reviewer can hold |
 | 0.9.1 | 2026-09-06 | `beta` | records and money that do not lie: a turn without a provider USD figure is unmetered, never a metered $0.00; a refusal no longer discards the turn's cost (banked first, deduped only against marked rows); an event over the 4096-byte cap spills its text beside the run and names it instead of losing every row of the invocation; preflight rows carry `command_hash` and their own `checked_at`, so a cached red is re-probed when the command changed, after 30 minutes, or under --prepare; the fix list writes back git's canonical 40-hex sha; `tldrx facts add` exists with owner/driver attribution rendered in prompts; run.yml rows carry the provider's token split only when reported |

package/dist/hooks/answer-capture.js

@@ -1,31 +1,41 @@
 #!/usr/bin/env node
 import {
-  FactsStore
-} from "./chunk-ecxt4p6n.js";
+  conflictOf
+} from "./chunk-bk7rkdzw.js";
+import {
+  FactsStore,
+  formatJaccard
+} from "./chunk-kqvbzyc0.js";
 import {
   parseHookInput,
   readStdin
-} from "./chunk-3rwbyema.js";
+} from "./chunk-6c84kjd7.js";
 import {
   EventLog,
   PHASE_ID_RE
-} from "./chunk-dtpjhddq.js";
-import"./chunk-gvs5fvve.js";
+} from "./chunk-9v45j71e.js";
+import"./chunk-tg7ppsxr.js";
 import {
+  ADVISORY_KEY,
   MAX_FACT_CHARS,
   detectAnswered,
   parseQuestions,
   recordAnswer,
+  renderQuestionBlock,
   replaceBlock,
   serializeQuestions
-} from "./chunk-14496ta8.js";
+} from "./chunk-wzzywf6c.js";
 import {
+  ITERATION_ONLY_SLOT,
+  PROJECT_FRAMEWORK_DIR,
   PROJECT_WORK_DIR,
-  factsPath
-} from "./chunk-f6d6cp4h.js";
+  commandProbeIssues,
+  factsPath,
+  parseYaml
+} from "./chunk-r1efatxk.js";
 
 // src/hooks/answer-capture.ts
-import { existsSync as existsSync3 } from "fs";
+import { existsSync as existsSync5 } from "fs";
 
 // src/hooks/lib/decide.ts
 function allow() {
@@ -67,6 +77,7 @@ function filePathOf(payload) {
 }
 
 // src/hooks/lib/workspace.ts
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 function locateWork(filePath) {
   if (filePath === "")
@@ -86,6 +97,111 @@ function locateWork(filePath) {
     relative: parts.slice(at + 2).join("/")
   };
 }
+var FALLBACK_DEFAULT_BRANCH = "main";
+function commandRolesOf(doc) {
+  const out = new Map;
+  const list = doc?.repos;
+  if (!Array.isArray(list))
+    return out;
+  for (const entry of list) {
+    if (typeof entry?.name !== "string")
+      continue;
+    const roles = new Map;
+    const cmds = entry.commands;
+    if (cmds !== null && typeof cmds === "object") {
+      for (const [role, value] of Object.entries(cmds)) {
+        if (typeof value !== "string" || value.trim() === "")
+          continue;
+        roles.set(role, value);
+      }
+    }
+    out.set(entry.name, roles);
+  }
+  return out;
+}
+function commandProbesOf(doc) {
+  const out = new Map;
+  const list = doc?.repos;
+  if (!Array.isArray(list))
+    return out;
+  for (const entry of list) {
+    if (typeof entry?.name !== "string")
+      continue;
+    const probes = new Map;
+    const raw = entry.command_probes;
+    if (raw !== null && typeof raw === "object" && !Array.isArray(raw)) {
+      for (const [slot, value] of Object.entries(raw)) {
+        if (commandProbeIssues(value, slot).length > 0)
+          continue;
+        probes.set(slot, value);
+      }
+    }
+    out.set(entry.name, probes);
+  }
+  return out;
+}
+function loadWorkspace(root) {
+  const repos = new Map;
+  const commands = new Set;
+  const repoCommands = new Map;
+  const commandRoles = new Map;
+  const commandProbes = new Map;
+  const iterationCommands = new Set;
+  const defaultBranches = new Map;
+  let seedTriageThresholdTokens = null;
+  const empty = () => ({
+    root,
+    repos,
+    commands,
+    repoCommands,
+    commandRoles,
+    commandProbes,
+    iterationCommands,
+    defaultBranches,
+    seedTriageThresholdTokens
+  });
+  const path = join(root, PROJECT_FRAMEWORK_DIR, "workspace.yml");
+  if (!existsSync(path))
+    return empty();
+  let doc;
+  try {
+    doc = parseYaml(readFileSync(path, "utf8"));
+  } catch {
+    return empty();
+  }
+  const triage = doc?.seed_triage;
+  if (triage !== null && typeof triage === "object") {
+    const tokens = triage.threshold_tokens;
+    if (typeof tokens === "number" && Number.isFinite(tokens) && tokens > 0) {
+      seedTriageThresholdTokens = tokens;
+    }
+  }
+  const list = doc?.repos;
+  if (!Array.isArray(list))
+    return empty();
+  const declared = commandRolesOf(doc);
+  const measured = commandProbesOf(doc);
+  for (const entry of list) {
+    if (typeof entry?.name !== "string")
+      continue;
+    repos.set(entry.name, typeof entry.path === "string" ? entry.path : ".");
+    defaultBranches.set(entry.name, typeof entry.default_branch === "string" && entry.default_branch !== "" ? entry.default_branch : FALLBACK_DEFAULT_BRANCH);
+    const own = [];
+    const roles = declared.get(entry.name) ?? new Map;
+    for (const value of roles.values()) {
+      commands.add(value);
+      if (!own.includes(value))
+        own.push(value);
+    }
+    repoCommands.set(entry.name, own);
+    commandRoles.set(entry.name, roles);
+    const fast = roles.get(ITERATION_ONLY_SLOT);
+    if (fast !== undefined)
+      iterationCommands.add(fast);
+    commandProbes.set(entry.name, measured.get(entry.name) ?? new Map);
+  }
+  return empty();
+}
 
 // src/hooks/lib/actor.ts
 function currentActor() {
@@ -97,10 +213,10 @@ function nowRfc3339() {
 }
 
 // src/core/answers/captureAnswers.ts
-import { existsSync as existsSync2, readFileSync as readFileSync2, writeFileSync } from "node:fs";
+import { existsSync as existsSync4, readFileSync as readFileSync4, writeFileSync } from "node:fs";
 
 // src/core/answers/stampSuperseded.ts
-import { appendFileSync, existsSync, readFileSync, statSync } from "node:fs";
+import { appendFileSync, existsSync as existsSync2, readFileSync as readFileSync2, statSync as statSync2 } from "node:fs";
 import { isAbsolute as isAbsolute2, join as join2, relative } from "node:path";
 var STAMP_MARKER = "tldrx:superseded";
 var AFFECTS_KEY = "affects";
@@ -140,7 +256,7 @@ function stampSuperseded(runDir, questionsPath, block, fact, at) {
   const questionsRel = runRelative(runDir, questionsPath) ?? "questions.md";
   const stamped = [];
   for (const doc of affectedDocs(runDir, questionsPath, block)) {
-    const text = readFileSync(doc.abs, "utf8");
+    const text = readFileSync2(doc.abs, "utf8");
     if (isStamped(text, fact))
       continue;
     const lead = text === "" ? "" : text.endsWith(`
@@ -165,7 +281,7 @@ function resolveInRun(runDir, raw) {
     const rel = runRelative(runDir, candidate);
     if (rel === null)
       continue;
-    if (!existsSync(candidate) || !statSync(candidate).isFile())
+    if (!existsSync2(candidate) || !statSync2(candidate).isFile())
       continue;
     return rel;
   }
@@ -185,7 +301,113 @@ function isEarlier(phase, than) {
   return Number(phase.slice(0, 2)) < Number(than.slice(0, 2));
 }
 
+// src/core/answers/reposFromAffects.ts
+function uniqueRepos(names) {
+  return [...new Set(names)];
+}
+function reposFromAffects(affects, repoNames) {
+  const repos = [];
+  const unresolved = [];
+  for (const raw of affects) {
+    const entry = raw.trim();
+    if (entry === "")
+      continue;
+    if (repoNames.has(entry)) {
+      repos.push(entry);
+      continue;
+    }
+    const colon = entry.indexOf(":");
+    if (colon <= 0)
+      continue;
+    const prefix = entry.slice(0, colon);
+    if (repoNames.has(prefix)) {
+      repos.push(prefix);
+      continue;
+    }
+    unresolved.push(entry);
+  }
+  return { repos: uniqueRepos(repos), unresolved };
+}
+
+// src/core/answers/raiseConflict.ts
+import { appendFileSync as appendFileSync2, existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
+import { join as join3 } from "node:path";
+
+// src/core/run/questionCards.ts
+var QUESTION_PHASES = ["01-what", "02-how", "03-plan", "04-build", "05-watch"];
+
+// src/core/answers/raiseConflict.ts
+var RAISED_BY = "tldrx";
+function nextQuestionId(runDir) {
+  let highest = 0;
+  for (const phase of QUESTION_PHASES) {
+    const path = join3(runDir, phase, "questions.md");
+    if (!existsSync3(path))
+      continue;
+    let blocks;
+    try {
+      blocks = parseQuestions(readFileSync3(path, "utf8")).blocks;
+    } catch {
+      continue;
+    }
+    for (const block of blocks) {
+      const n = Number.parseInt(block.id.slice(1), 10);
+      if (Number.isFinite(n) && n > highest)
+        highest = n;
+    }
+  }
+  return `Q${String(highest + 1)}`;
+}
+function raiseConflictQuestion(args) {
+  const id = nextQuestionId(args.runDir);
+  const block = renderQuestionBlock({
+    id,
+    title: `Which is right about ${args.area}: ${args.newFactId} or ${args.oldFactId}?`,
+    metadata: {
+      id,
+      status: "open",
+      area: args.area,
+      asked_by: RAISED_BY,
+      asked_at: args.at,
+      extra: [[ADVISORY_KEY, "true"]]
+    },
+    metadataIndex: -1,
+    whyAsked: `answering ${args.answeredQ} recorded ${args.newFactId}, which overlaps ${args.oldFactId}'s ` + `text at Jaccard ${formatJaccard(args.score)} on the question's wording, in the same area, ` + `and answers it differently — ${args.oldFactId}: "${oneLine(args.oldFactText)}" ` + `[src: ${args.oldFactId}]`,
+    whySrc: null,
+    options: [
+      { letter: "A", text: `${args.newFactId} is right — supersede ${args.oldFactId}` },
+      { letter: "B", text: `${args.oldFactId} is right — supersede ${args.newFactId}` },
+      { letter: "C", text: "Both are partly right — write the correction below" }
+    ],
+    answer: "",
+    answerIndex: -1,
+    footer: null,
+    startLine: -1,
+    lines: []
+  });
+  appendFileSync2(args.questionsPath, `
+${block}
+`, "utf8");
+  return { q: id, fact: args.newFactId, conflictsWith: args.oldFactId, score: args.score };
+}
+function oneLine(text) {
+  return text.replace(/\s+/g, " ").trim();
+}
+
 // src/core/answers/captureAnswers.ts
+function answerProvenance(block, overrides, repoNames, fallbackRepos) {
+  const override = overrides?.get(block.id);
+  const named = reposFromAffects(declaredAffects(block), repoNames ?? new Set);
+  const repos = override?.repos ?? (named.repos.length > 0 ? named.repos : fallbackRepos);
+  return {
+    repos,
+    unresolved: named.unresolved,
+    source: override?.decidedBy === undefined ? {} : { decided_by: override.decidedBy }
+  };
+}
+function unresolvedEntries(captured) {
+  return captured.flatMap((c) => c.unresolvedAffects.map((entry) => `${c.q}: affects: ${entry} names no repo in this workspace — it scoped nothing`));
+}
 var TRUNCATION_MARK = " …";
 function factTextFor(title, answer) {
   const whole = `${title} — ${answer}`;
@@ -197,28 +419,35 @@ function factWasTruncated(title, answer) {
   return `${title} — ${answer}`.length > MAX_FACT_CHARS;
 }
 function captureAnswers(questionsPath, ctx) {
-  if (!existsSync2(questionsPath))
+  if (!existsSync4(questionsPath))
     return [];
-  let doc = parseQuestions(readFileSync2(questionsPath, "utf8"));
+  let doc = parseQuestions(readFileSync4(questionsPath, "utf8"));
   const answered = detectAnswered(doc.blocks);
   if (answered.length === 0)
     return [];
   const log = EventLog.forRun(ctx.runDir);
   const captured = [];
   const recorded = [];
+  const clashes = [];
   FactsStore.update(factsPath(ctx.root), (store) => {
     for (const block of answered) {
       const area = block.metadata?.area ?? "unscoped";
       const truncated = factWasTruncated(block.title, block.answer);
+      const prov = answerProvenance(block, ctx.overrides, ctx.repoNames, []);
+      const text = factTextFor(block.title, block.answer);
+      const clash = conflictOf({ match: block.title, area, text }, store.active);
       const fact = store.append({
-        fact: factTextFor(block.title, block.answer),
+        fact: text,
         ...truncated ? { truncated: true } : {},
+        ...clash === null ? {} : { conflicts_with: [clash.fact.id] },
         area,
-        repos: [],
+        repos: prov.repos,
         kind: "answer",
         confidence: "stated",
-        source: { who: ctx.actor, when: ctx.at, run: ctx.run, q: block.id }
+        source: { who: ctx.actor, when: ctx.at, run: ctx.run, q: block.id, ...prov.source }
       });
+      if (clash !== null)
+        clashes.push({ block, area, factId: fact.id, hit: clash });
       doc = replaceBlock(doc, recordAnswer(block, { answered_by: ctx.actor, answered_at: ctx.at, fact: fact.id }));
       log.tryAppend({
         ts: ctx.at,
@@ -238,15 +467,58 @@ function captureAnswers(questionsPath, ctx) {
         cost_usd: 0,
         payload: { fact: fact.id, area: fact.area, kind: fact.kind, q: block.id }
       });
-      captured.push({ q: block.id, fact: fact.id, answer: block.answer, area });
+      captured.push({
+        q: block.id,
+        fact: fact.id,
+        answer: block.answer,
+        area,
+        unresolvedAffects: prov.unresolved
+      });
       recorded.push({ block, fact: fact.id });
     }
   });
   writeFileSync(questionsPath, serializeQuestions(doc), "utf8");
+  const raised = raiseAll(log, ctx, questionsPath, clashes);
   for (const item of recorded) {
     markSuperseded(log, ctx, questionsPath, item.block, item.fact);
   }
-  return captured;
+  return captured.map((answer) => {
+    const conflict = raised.get(answer.q);
+    return conflict === undefined ? answer : { ...answer, conflict };
+  });
+}
+function raiseAll(log, ctx, questionsPath, clashes) {
+  const raised = new Map;
+  for (const clash of clashes) {
+    const conflict = raiseConflictQuestion({
+      runDir: ctx.runDir,
+      questionsPath,
+      area: clash.area,
+      at: ctx.at,
+      newFactId: clash.factId,
+      oldFactId: clash.hit.fact.id,
+      oldFactText: clash.hit.fact.fact,
+      score: clash.hit.score,
+      answeredQ: clash.block.id
+    });
+    raised.set(clash.block.id, conflict);
+    log.tryAppend({
+      ts: ctx.at,
+      run: ctx.run,
+      stage: null,
+      type: "fact.conflict_raised",
+      actor: ctx.actor,
+      cost_usd: 0,
+      payload: {
+        fact: clash.factId,
+        conflicts_with: clash.hit.fact.id,
+        score: clash.hit.score,
+        q: clash.block.id,
+        raised: conflict.q
+      }
+    });
+  }
+  return raised;
 }
 function markSuperseded(log, ctx, questionsPath, block, fact) {
   try {
@@ -285,7 +557,7 @@ await runHook("answer-capture", async () => {
   if (event === "PostToolUse" && payload.tool_name !== "Write" && payload.tool_name !== "Edit")
     return;
   const filePath = filePathOf(payload);
-  if (!filePath.endsWith("questions.md") || !existsSync3(filePath))
+  if (!filePath.endsWith("questions.md") || !existsSync5(filePath))
     return;
   const location = locateWork(filePath);
   if (location === null)
@@ -295,10 +567,12 @@ await runHook("answer-capture", async () => {
     runDir: location.runDir,
     run: location.run,
     actor: currentActor(),
-    at: nowRfc3339()
+    at: nowRfc3339(),
+    repoNames: new Set(loadWorkspace(location.root).repos.keys())
   });
   if (captured.length === 0)
     return;
-  postContext(`tldrx: recorded ${captured.map((c) => `${c.q} \u2192 ${c.fact}`).join(", ")}`);
+  const unresolved = unresolvedEntries(captured);
+  postContext(`tldrx: recorded ${captured.map((c) => `${c.q} \u2192 ${c.fact}`).join(", ")}` + (unresolved.length === 0 ? "" : ` \u2014 ${unresolved.join("; ")}`));
 });
 allow();