tldr-experts 0.27.0 → 0.28.1

package/CHANGELOG.md

@@ -1,5 +1,97 @@
 # Changelog
 
+## 0.28.1 — 2026-09-15
+
+### Fixed
+
+- **The note a story was reopened with now reaches the developer and the reviewer (closes #322).**
+  On a field run a person reopened a story with a note naming the exact gap two reviews had
+  refused it for; the next developer made a docstring-only commit and a reviewer approved it, and
+  neither turn had been shown the note. It was written only into `story.reopened` and read back
+  for a report line and #308's no-diff check — while the refusal for a `--for-fix` with no note
+  told the operator the note "is what scopes the fix round, and what the reviewer reads". Measured
+  before the fix: 0 of the post-reopen developer and reviewer prompts contained the note, for a
+  plain reopen and for `--for-fix`, and after a plain reopen the developer prompt had no
+  `## Previous attempt` either, so it was told nothing about why the story came back. Both
+  prompts now carry `## Why this story was reopened` — who signed it, whether it is a fix round,
+  the note verbatim — read off the same ledger value #308 already reads, so the prompt and the
+  refusal cannot name different notes; a story nobody reopened renders nothing new. The
+  reviewer's copy tells it that a diff leaving the named gap as it was is `changes`, but that
+  instruction is **prompt-advisory**: the framework does not enforce a `changes` verdict against
+  the note, and an `approve` is still accepted as the reviewer's judgement.
+- **`tldrx note --help` says where an operator note goes, and where it does not (closes #151,
+  docs only).** An `operator_note` is read by `run status`, `replay` and the dashboard and by no
+  prompt — so a note an owner wrote for the next stage's agents silently reached nobody. The gap
+  was the unwritten contract, not a missing reader: the help and the CLI reference now say the
+  note is for people and name `.agent/<stage>/dispatch-notes.md` as the channel that reaches
+  agents.
+
+## 0.28.0 — 2026-09-15
+
+### Added
+
+- **A story whose merge-up to its epic conflicts in a few of its own files gets one conflict
+  turn instead of a person (#286).** MEASURED on a field run: a story with a green DoD conflicted
+  bringing itself up to the epic (#268) in one counted test list both stories bumped, blocked
+  correctly — and nothing in the framework could resolve it: the developer holds no merge verb, a
+  plain reopen had no work, and a person did it in a scratch worktree; 1.5 h later the same story
+  conflicted again in four files. Now, when the conflict is in at most three files, every one in
+  the story's declared `touches` (the boundary matcher, `inSurface`), with no conflict turn since
+  its last `story.reopened` and an attempt left, the story is requeued the way #313 requeues a
+  red DoD — prior status, worktree kept, one attempt spent — and one new `story.conflict_turn`
+  event is written. Its next attempt is dispatched with the CURRENT epic tip merged into the
+  worktree and the merge left open (markers, `MERGE_HEAD`); the prompt names the files, the
+  story's intent and the stories that landed on the epic, and `git add` + `git commit` — verbs the
+  developer already holds — close it, with the DoD as judge. A marker guard in `git.ts`
+  (each conflicted file handed, any path it was renamed to, and every added or untracked path a
+  commit could sweep in, read for any `<<<<<<<`, `|||||||`
+  or `>>>>>>>` line — a lone `=======` heading underline is not a marker — plus `MERGE_HEAD`)
+  blocks, never requeues, a turn that left a marker in one of those files or never closed the
+  merge, naming the files — without it, measured
+  by mutation, markers were committed and merged onto the epic as `done`. Anything else still
+  blocks exactly as before, with the reason it got no turn appended. The bound is counted from
+  `events.jsonl`, so it holds across invocations, and `tldrx replay` says an agent, not a person,
+  resolved the merge. Headless only: the host's `--commit` half and an as-is settlement block as
+  they did.
+
+### Fixed
+
+- **`tldrx story reopen` on a `blocked` story also releases the dependents it alone was holding
+  (#312).** Reopening a blocked dependency left every dependent `blocked` with a
+  `dependency S<n> blocked` reason that had just gone stale, so each needed its own reopen —
+  measured three times in one day on a live run. Every `blocked` story whose recorded hold names
+  the reopened story (or a story released this way, transitively) now goes back to `todo` in the
+  same command when no other dependency still holds it. Each release is its own signed
+  `story.reopened` naming the dependency that caused it (additive `released_by` and `dependency`),
+  consuming no attempt. A dependent still held by another dependency, or blocked by a verdict
+  rather than a hold, stays `blocked`, and the output says which and why.
+- **`Recommended: A [src: …]` is a recommendation, and `seed check` reads the line the way the
+  loop does (#323).** On a live run the loop answered Q8's `Recommended: A — <why> [src: …]`
+  and left Q7's `Recommended: A [src: …]` for a person, parking an unattended run: the question
+  parser demanded a dash reason before any citation, while `seed check` tested only the
+  substring `Recommended:` and had passed the same shape clean — two derivations of "has a
+  recommendation" that disagreed. There is now one grammar and one reader
+  (`parseRecommendedLine`): the letter first, then any of its `)`, a `— <why>` and trailing
+  `[src: …]` tokens. `seed check` calls it and names, as exit-1 findings, a `Recommended:` line
+  it cannot read (`question-recommended-unreadable`, with the line and the shape expected) and
+  a letter naming none of the options the question lists (`question-recommended-option`). A
+  seed question that lists no options is not judged on its letter — the options are the What
+  stage's to write. A §2.7 block's unreadable line is still ignored rather than refused.
+- **An unattended run is no longer stranded by its own provenance, or by a refused check it could
+  fix itself (#231).** Measured 2026-09-14 on a `run auto` validation run (0.27.0): a What stage
+  wrote `[src: absent:.tldrx/memory/facts.yml#tenant-credits]`, true when written; the loop then
+  auto-answered that stage's questions, the new facts' `source:` maps read
+  `run: 260914-tenant-credits`, and `claim-sources` refused the absence on the run id. The refused
+  `auto` gate then waited for a person, who typed `reject --and-continue` with the finding —
+  intervention #2 of that run. Two fixes. An `absent:…#<needle>` over the workspace's
+  `facts.yml` no longer searches a fact's `source: {who, when, run, q, decided_by}` map — that is
+  who recorded it, not what it says; a map with any other key is searched in full, and a needle in
+  a fact's content still refuses, even on a fact this run just wrote. And under `--wait-gates`,
+  an `auto` gate refused by failed checks ALONE (a declared check, or `claim-sources` failing)
+  re-runs its stage once through the same `reject --and-continue` path, signed `run auto` with the
+  findings as the note; past that bound, or on a `human`/`agent` gate, or when questions, budget,
+  stories, boundary or status also hold it, the loop waits for a person as before and prints why.
+
 ## 0.27.0 — 2026-09-14
 
 ### Added

package/README.md

@@ -335,6 +335,8 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.28.1 | 2026-09-15 | `beta` | Two fixes so a reopened story's reason reaches the agents that need it. The developer and reviewer prompts now carry `## Why this story was reopened` — who signed it, whether it's a fix round, the note verbatim — off the same ledger value #308 reads, instead of the note reaching only a report line and #308's check (closes #322). `tldrx note --help` now says an operator note reaches no agent and names `dispatch-notes.md` as the channel that does (closes #151). |
+| 0.28.0 | 2026-09-15 | `beta` | Four changes that keep an unattended run moving instead of stranding on a person. A story whose merge-up to its epic conflicts in at most three of its own touched files gets one automated conflict turn instead of a person, guarded against committing conflict markers (#286). `story reopen` on a blocked story now releases every dependent it alone was holding, in the same command (#312). Seed's `Recommended:` line and the loop's question parser now share one grammar, so a citation-only recommendation no longer parks a run that `seed check` had already passed (#323). And an `absent:` needle over `facts.yml` no longer trips on a fact's own recording metadata, while an `auto` gate refused only by failed checks gets one automatic re-run before waiting for a person (#231). |
 | 0.27.0 | 2026-09-14 | `beta` | Five changes for unattended runs, from a planning audit and live field measurement. The `plan` check now refuses a plan with more waves than the framework carries per run (unless `waves.yml` names a `wave_cap_reason`), refuses a story scheduled before its `depends_on` allows, and flags a dod command siblings carry that one story doesn't (#316–#319). `tldrx run auto --rebalance-finished` moves a blocked phase's exact shortfall out of a finished phase's unspent ceiling before refusing, through `budget raise --take-from` itself, so the run ceiling never grows and no grant is ever assumed; every money refusal now names the unspent total and the exact command to fix it (#314). `tldrx ship` fetches and merges the base into the epic and re-runs the `done` stories' DoD before opening a PR, so a stale or red epic refuses instead of shipping a PR that comes back red (#315). A reviewer's budget floor rises from $1.00 to $2.00, matching what completed reviews actually cost, so a review no longer dies mid-diff on a floor that was never measured (#307). And a developer whose DoD goes red gets the story's next attempt instead of blocking on the first miss, with the kept output handed to the next attempt and the bound counted from `events.jsonl` so it holds across process restarts; a refused developer, a cap death, or a broken dod command still blocks immediately (#313). |
 | 0.26.1 | 2026-09-14 | `beta` | Three refusals that stop a bad state from settling quietly. A Build fix round whose developer lands no diff is refused before the DoD instead of closing `done` on an unmoved tree, because `commitIfDirty` hands back the old head sha on a clean commit and the existing "no commit to review" gate never fires for it — `workSince` is now asked on the success path too, for any story a person put back with a note. `tldrx ship` refuses an epic carrying a story the reviewer marked `changes`: it asks the ledger's `lastMerge` for every story not `done` and exits 2 naming the story, the merge and the handoff's reason, instead of opening a PR whose "Not done" list hid rejected code already merged into the diff. And a stage-failure line keeps the branch it names when the worktree path is wider than the line: the refusal puts the branches before the path, and `oneLine` keeps a line's head and tail instead of dropping the identifiers that sat at the end. |
 | 0.26.0 | 2026-09-14 | `beta` | Two field defects from the same class — a reader of an event payload trusting a field its writer never set — plus the ceiling that killed the turn that earned it. A wide story's measured `touches_widened` no longer throws after the turn has settled: the cap knows the three lists by name and drops them whole by count, every reader derives before/after through one function, and an executor that throws after paid turns leaves their rows and money in `run.yml` and saves before it emits. The cost surfaces then agree with each other: a turn whose result was lost to that fault reads as UNMETERED, LOWER BOUND on `tldrx cost` and in the Build handoff through the door other unmeasured turns already use, a turn still in flight reads as nothing, and a late result retires the lost mark instead of counting twice. Replay reads the reason a failed stage recorded instead of printing "no reason recorded" for every one. |

package/dist/hooks/answer-capture.js

@@ -1,24 +1,24 @@
 #!/usr/bin/env node
 import {
   conflictOf
-} from "./chunk-d0jhr5wh.js";
+} from "./chunk-c62y35wh.js";
 import {
   FactsStore,
   formatJaccard
-} from "./chunk-jpp137mb.js";
+} from "./chunk-48ctk154.js";
 import {
   parseHookInput,
   readStdin
-} from "./chunk-qzsxhsyj.js";
+} from "./chunk-khjm356r.js";
 import {
   EventLog,
   PHASE_ID_RE
-} from "./chunk-41k19q8t.js";
+} from "./chunk-abswp1vt.js";
 import {
   PHASE_IDS
-} from "./chunk-m1s8a6s0.js";
-import"./chunk-bznt6jb2.js";
-import"./chunk-ezfvp5kx.js";
+} from "./chunk-veffvzw5.js";
+import"./chunk-g7wz339n.js";
+import"./chunk-zvxgdssb.js";
 import {
   ADVISORY_KEY,
   MAX_FACT_CHARS,
@@ -28,7 +28,7 @@ import {
   renderQuestionBlock,
   replaceBlock,
   serializeQuestions
-} from "./chunk-5stgwp3g.js";
+} from "./chunk-khy21x6e.js";
 import {
   ITERATION_ONLY_SLOT,
   PROJECT_FRAMEWORK_DIR,
@@ -38,7 +38,7 @@ import {
   isScopedTemplate,
   parseYaml,
   scopedSlotOf
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/hooks/answer-capture.ts
 import { existsSync as existsSync5 } from "fs";

package/dist/hooks/budget-gate.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import {
   budgetGateDeny
-} from "./chunk-ka7768vx.js";
+} from "./chunk-q3d4xdhb.js";
 import {
   allow,
   deny,
   readPayload,
   runHook,
   toolInput
-} from "./chunk-t44983nq.js";
-import"./chunk-qzsxhsyj.js";
+} from "./chunk-tna1bz8r.js";
+import"./chunk-khjm356r.js";
 import {
   asRunBudget,
   currentActor,
@@ -22,10 +22,10 @@ import {
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-2qkbh9b6.js";
+} from "./chunk-e618k6te.js";
 import {
   EventLog
-} from "./chunk-41k19q8t.js";
+} from "./chunk-abswp1vt.js";
 import {
   cursorStage,
   hostTokensIn,
@@ -34,18 +34,18 @@ import {
   newestActiveRun,
   renderRunEconomies,
   runSpend
-} from "./chunk-yre2scxn.js";
-import"./chunk-bznt6jb2.js";
+} from "./chunk-hws2gnxj.js";
+import"./chunk-g7wz339n.js";
 import {
   noteDeprecations
-} from "./chunk-5stgwp3g.js";
+} from "./chunk-khy21x6e.js";
 import {
   PROJECT_WORK_DIR,
   findWorkspaceRoot,
   locateWork,
   parseYaml,
   stageYamlPath
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/hooks/budget-gate.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, statSync } from "node:fs";

package/dist/hooks/{chunk-jpp137mb.js → chunk-48ctk154.js}

@@ -3,7 +3,7 @@ import {
   withWorkspaceLock,
   workspaceRootOfFactsPath,
   writeAtomic
-} from "./chunk-ezfvp5kx.js";
+} from "./chunk-zvxgdssb.js";
 import {
   FACT_CONFIDENCES,
   FACT_DECIDERS,
@@ -15,7 +15,7 @@ import {
   isLive,
   isRetired,
   noteDeprecations
-} from "./chunk-5stgwp3g.js";
+} from "./chunk-khy21x6e.js";
 import {
   SRC_PATTERNS,
   asDocument,
@@ -28,7 +28,7 @@ import {
   requireString,
   requireVersion,
   result
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/core/facts/FactsStore.ts
 import { existsSync, readFileSync } from "node:fs";

package/dist/hooks/{chunk-41k19q8t.js → chunk-abswp1vt.js}

@@ -2,7 +2,7 @@ import {
   GATE_POLICIES,
   validateGatesPolicy,
   validateStagePolicy
-} from "./chunk-bznt6jb2.js";
+} from "./chunk-g7wz339n.js";
 import {
   asDocument,
   isRecord,
@@ -15,7 +15,7 @@ import {
   requireString,
   requireVersion,
   result
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/core/events/EventLog.ts
 import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
@@ -50,6 +50,7 @@ var EVENT_TYPES = [
   "story.reopened",
   "story.base_fastforwarded",
   "story.base_updated",
+  "story.conflict_turn",
   "story.review_retried",
   "story.work_rescued",
   "story.touches_widened",

package/dist/hooks/{chunk-d0jhr5wh.js → chunk-c62y35wh.js}

@@ -1,15 +1,15 @@
 import {
   findDuplicate
-} from "./chunk-jpp137mb.js";
+} from "./chunk-48ctk154.js";
 import {
   evidencePath,
   gateEvidencePath,
   parseEvidence
-} from "./chunk-41k19q8t.js";
+} from "./chunk-abswp1vt.js";
 import {
   openBlocks,
   parseQuestions
-} from "./chunk-5stgwp3g.js";
+} from "./chunk-khy21x6e.js";
 
 // src/core/distill/distill.ts
 var CONFLICT_THRESHOLD = 0.6;

package/dist/hooks/{chunk-2qkbh9b6.js → chunk-e618k6te.js}

@@ -1,6 +1,6 @@
 import {
   STAGE_TUNING_DEFAULTS
-} from "./chunk-bznt6jb2.js";
+} from "./chunk-g7wz339n.js";
 import {
   MAX_PLAN_STORIES,
   MAX_STORIES_PER_WAVE,
@@ -25,7 +25,7 @@ import {
   requireVersion,
   requireVersion1,
   result
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/hooks/lib/actor.ts
 function currentActor() {

package/dist/hooks/{chunk-0sy3tmfg.js → chunk-f6t1xc3f.js}

@@ -8240,7 +8240,7 @@ function resolveAbsent(ref, ctx, section, claim) {
   if (found === null)
     return OK;
   if (needle !== null)
-    return searchForNeedle(found, needle, path);
+    return searchForNeedle(found, needle, path, isWorkspaceFacts(found, ctx));
   const held = whatIsThere(found);
   if (held === null)
     return OK;
@@ -8248,7 +8248,7 @@ function resolveAbsent(ref, ctx, section, claim) {
 }
 var NEEDLE_MAX_BYTES = 512 * 1024;
 var EMPTY_PROBE_MAX_BYTES = 64 * 1024;
-function searchForNeedle(abs, needle, path) {
+function searchForNeedle(abs, needle, path, factsFile) {
   let stat;
   try {
     stat = statSync2(abs);
@@ -8271,12 +8271,35 @@ function searchForNeedle(abs, needle, path) {
   const lines = text.split(`
 `);
   for (let i = 0;i < lines.length; i++) {
-    if ((lines[i] ?? "").toLowerCase().includes(wanted)) {
+    const line = factsFile ? withoutFactProvenance(lines[i] ?? "") : lines[i] ?? "";
+    if (line.toLowerCase().includes(wanted)) {
       return refused(`\`${needle}\` IS at ${path}:${String(i + 1)} — that is a presence, not an absence`, abs);
     }
   }
   return OK;
 }
+function isWorkspaceFacts(abs, ctx) {
+  return normalize(abs) === normalize(join2(ctx.root, PROJECT_FRAMEWORK_DIR, "memory", "facts.yml"));
+}
+var PROVENANCE_KEYS = new Set(["who", "when", "run", "q", "decided_by"]);
+var SOURCE_OPEN_RE = /(^|[\s,{])source:\s*\{/;
+var PROVENANCE_ENTRY_RE = /^\s*([a-z_]+):\s*("(?:[^"\\]|\\.)*"|[^,{}"]*?)\s*([,}])/;
+function withoutFactProvenance(line) {
+  const open = SOURCE_OPEN_RE.exec(line);
+  if (open === null)
+    return line;
+  const start = open.index + (open[1] ?? "").length;
+  let at = open.index + open[0].length;
+  for (;; ) {
+    const entry = PROVENANCE_ENTRY_RE.exec(line.slice(at));
+    if (entry === null || !PROVENANCE_KEYS.has(entry[1] ?? ""))
+      return line;
+    at += entry[0].length;
+    if (entry[3] === "}")
+      break;
+  }
+  return line.slice(0, start) + " ".repeat(at - start) + line.slice(at);
+}
 function whatIsThere(abs) {
   let stat;
   try {

package/dist/hooks/{chunk-w685jj9h.js → chunk-fjeefnqr.js}

@@ -9,7 +9,7 @@ import {
   spentBasis,
   tallyOf,
   validateRunBudget
-} from "./chunk-2qkbh9b6.js";
+} from "./chunk-e618k6te.js";
 import {
   EventLog,
   OUTCOME_NOT_RECORDED,
@@ -22,12 +22,12 @@ import {
   isTerminal,
   stageAt,
   validateRunFile
-} from "./chunk-41k19q8t.js";
+} from "./chunk-abswp1vt.js";
 import {
   cursorStage,
   isAttendedByHostView,
   openRunViews
-} from "./chunk-yre2scxn.js";
+} from "./chunk-hws2gnxj.js";
 import {
   backupPathFor,
   isAlive,
@@ -36,20 +36,20 @@ import {
   workspaceRootOfRunDir,
   writeAtomic,
   yamlScalar
-} from "./chunk-ezfvp5kx.js";
+} from "./chunk-zvxgdssb.js";
 import {
   isAdvisory,
   noteDeprecations,
   openBlocks,
   parseQuestions
-} from "./chunk-5stgwp3g.js";
+} from "./chunk-khy21x6e.js";
 import {
   FRAMEWORK_ROOT,
   PLAN_STATUSES,
   listRunDirs,
   parseYaml,
   parseYamlRepairing
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/core/statusline/runSnapshot.ts
 import { existsSync as existsSync3, readFileSync as readFileSync4 } from "node:fs";
@@ -684,6 +684,7 @@ function statusWithOutcome(status, outcome) {
 
 // src/core/run/autoGate.ts
 var AUTO_GATE_ACTOR = "auto";
+var RETRYABLE_CONDITIONS = new Set(["checks", "claim-sources"]);
 var AUTO_GATE_REFUSED_PREFIX = "auto-gate refused — held by: ";
 var HELD_SEPARATOR = " · ";
 function heldByNote(note) {

package/dist/hooks/{chunk-bznt6jb2.js → chunk-g7wz339n.js}

@@ -1,6 +1,6 @@
 import {
   isRecord
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/core/run/stagePolicy.ts
 function validateStagePolicy(value, stageIds, issues, spec) {

package/dist/hooks/{chunk-yre2scxn.js → chunk-hws2gnxj.js}

@@ -1,7 +1,7 @@
 import {
   listRunDirs,
   parseYaml
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/hooks/lib/runFile.ts
 import { existsSync, readFileSync } from "node:fs";

package/dist/hooks/{chunk-qzsxhsyj.js → chunk-khjm356r.js}

@@ -1,6 +1,6 @@
 import {
   runtime
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/core/hooks/passthrough.ts
 async function readStdin() {

package/dist/hooks/{chunk-5stgwp3g.js → chunk-khy21x6e.js}

@@ -3,7 +3,7 @@ import {
   parseSrcToken,
   srcToken,
   withoutSrcToken
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/core/text/questions.ts
 var REQUIRED_METADATA_KEYS = ["id", "status", "area", "asked_by", "asked_at"];
@@ -11,7 +11,9 @@ var HEADING_RE = /^##\s+(Q\d{1,6})\s+·\s+(.+?)\s*$/;
 var METADATA_RE = /^<!--\s*(.*?)\s*-->$/;
 var WHY_RE = /^Why asked:\s*(.*)$/;
 var OPTION_RE = /^-\s+([A-E])\)\s*(.*)$/;
-var RECOMMENDED_RE = /^Recommended:[ \t]+([A-E])\)?[ \t]*(?:[—–-][ \t]+(.*))?$/;
+var RECOMMENDED_PREFIX_RE = /^Recommended:/;
+var RECOMMENDED_RE = /^Recommended:[ \t]+([A-E])\)?(?![^ \t])[ \t]*(.*)$/;
+var RECOMMENDED_REASON_RE = /^[—–-](?:[ \t]+(.*))?$/;
 var ANSWER_RE = /^\[Answer\]:[ \t]*(\S.*)$/;
 var ANSWER_SLOT_RE = /^\[Answer\]:/;
 var FOOTER_KEYS = ["answered_by", "answered_at", "fact"];
@@ -55,6 +57,7 @@ function buildBlock(startLine, lines) {
   let whySrc = null;
   const options = [];
   let recommended = null;
+  let sawRecommendedLine = false;
   let answer = "";
   let answerIndex = -1;
   let footer = null;
@@ -82,9 +85,10 @@ function buildBlock(startLine, lines) {
       options.push({ letter: option[1], text: option[2] });
       continue;
     }
-    const recommendation = RECOMMENDED_RE.exec(line);
-    if (recommendation !== null && recommendation[1] !== undefined && recommended === null) {
-      recommended = toRecommendation(recommendation[1], recommendation[2] ?? "");
+    if (RECOMMENDED_PREFIX_RE.test(line) && !sawRecommendedLine) {
+      sawRecommendedLine = true;
+      const reading = parseRecommendedLine(line);
+      recommended = reading.kind === "ok" ? reading.recommendation : null;
       continue;
     }
     if (ANSWER_SLOT_RE.test(line) && answerIndex === -1) {
@@ -109,13 +113,27 @@ function buildBlock(startLine, lines) {
     lines: [...lines]
   };
 }
-function toRecommendation(option, rest) {
-  const token = parseSrcToken(rest);
-  return {
-    option,
-    why: withoutSrcToken(rest).trim(),
-    src: token === null ? "" : token.refs.map((ref) => ref.raw).join(SRC_SEPARATOR)
-  };
+function parseRecommendedLine(line) {
+  if (!RECOMMENDED_PREFIX_RE.test(line))
+    return { kind: "absent" };
+  const match = RECOMMENDED_RE.exec(line.replace(/\s+$/, ""));
+  const option = match?.[1];
+  if (match === null || option === undefined)
+    return { kind: "unreadable", line };
+  let rest = (match[2] ?? "").trim();
+  const tokens = [];
+  for (let token = parseSrcToken(rest);token !== null; token = parseSrcToken(rest)) {
+    tokens.unshift(token.refs.map((ref) => ref.raw));
+    rest = withoutSrcToken(rest).replace(/[\s.,;:!?]+$/, "").trim();
+  }
+  let why = "";
+  if (rest !== "") {
+    const reason = RECOMMENDED_REASON_RE.exec(rest);
+    if (reason === null)
+      return { kind: "unreadable", line };
+    why = (reason[1] ?? "").trim();
+  }
+  return { kind: "ok", line, recommendation: { option, why, src: tokens.flat().join(SRC_SEPARATOR) } };
 }
 function parsePipeComment(inner) {
   const pairs = [];

package/dist/hooks/{chunk-ka7768vx.js → chunk-q3d4xdhb.js}

@@ -3,7 +3,7 @@ import {
   EMPTY_SECTION_RULE,
   noneBullet,
   srcRule
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/hooks/lib/messages.ts
 var GRAMMAR = "[src: <repo:path:line> | https://… | Q<n> | F<n> | $ <cmd> → exit <n> | graph:<node> | absent:<path>]";

package/dist/hooks/{chunk-t44983nq.js → chunk-tna1bz8r.js}

@@ -1,7 +1,7 @@
 import {
   parseHookInput,
   readStdin
-} from "./chunk-qzsxhsyj.js";
+} from "./chunk-khjm356r.js";
 
 // src/hooks/lib/decide.ts
 function deny(reason) {

package/dist/hooks/{chunk-m1s8a6s0.js → chunk-veffvzw5.js}

@@ -3,7 +3,7 @@ import {
   STAGE_TUNING_DEFAULTS,
   parseWorkflowGates,
   readStageTuning
-} from "./chunk-bznt6jb2.js";
+} from "./chunk-g7wz339n.js";
 import {
   PROJECT_FRAMEWORK_DIR,
   STAGES_DIR,
@@ -12,7 +12,7 @@ import {
   isRecord,
   loadWorkspace,
   parseYaml
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/core/run/workflowPreset.ts
 import { existsSync, readFileSync } from "node:fs";

package/dist/hooks/{chunk-n5bxz2cw.js → chunk-zrwq6r7k.js}

@@ -1,6 +1,6 @@
 import {
   toolInput
-} from "./chunk-t44983nq.js";
+} from "./chunk-tna1bz8r.js";
 
 // src/hooks/lib/wouldBe.ts
 import { existsSync, readFileSync } from "node:fs";

package/dist/hooks/{chunk-ezfvp5kx.js → chunk-zvxgdssb.js}

@@ -1,7 +1,7 @@
 import {
   PROJECT_FRAMEWORK_DIR,
   PROJECT_WORK_DIR
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/core/lock/workspaceLock.ts
 import { existsSync as existsSync2, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync2, rmSync as rmSync2, writeSync, closeSync } from "node:fs";

package/dist/hooks/claim-sources.js

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
 import {
   wouldBeContent
-} from "./chunk-n5bxz2cw.js";
+} from "./chunk-zrwq6r7k.js";
 import {
   claimSourcesDeny,
   claimSourcesEmptySectionDeny,
   claimSourcesMalformedDeny,
   claimSourcesUnresolvedDeny
-} from "./chunk-ka7768vx.js";
+} from "./chunk-q3d4xdhb.js";
 import {
   allow,
   deny,
@@ -16,8 +16,8 @@ import {
   postContext,
   readPayload,
   runHook
-} from "./chunk-t44983nq.js";
-import"./chunk-qzsxhsyj.js";
+} from "./chunk-tna1bz8r.js";
+import"./chunk-khjm356r.js";
 import {
   isHandoff,
   loadWorkspace,
@@ -25,7 +25,7 @@ import {
   toSrcContext,
   validateCitations,
   validateHandoff
-} from "./chunk-0sy3tmfg.js";
+} from "./chunk-f6t1xc3f.js";
 
 // src/hooks/claim-sources.ts
 await runHook("claim-sources", async () => {