tldr-experts 0.28.0 → 0.28.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 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

package/README.md

@@ -335,6 +335,7 @@ 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. |

package/dist/hooks/budget-gate.js

@@ -22,7 +22,7 @@ import {
   validateRunBudget,
   wouldExceed,
   wouldExceedHostTokens
-} from "./chunk-xhd77h0p.js";
+} from "./chunk-e618k6te.js";
 import {
   EventLog
 } from "./chunk-abswp1vt.js";

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

@@ -9,7 +9,7 @@ import {
   spentBasis,
   tallyOf,
   validateRunBudget
-} from "./chunk-xhd77h0p.js";
+} from "./chunk-e618k6te.js";
 import {
   EventLog,
   OUTCOME_NOT_RECORDED,

package/dist/hooks/session-start.js

@@ -20,14 +20,14 @@ import {
   runSnapshot,
   statusWithOutcome,
   whatIsWaiting
-} from "./chunk-kx45kt9n.js";
+} from "./chunk-fjeefnqr.js";
 import {
   expertsDir,
   loadExperts,
   pathsIntersect,
   readExpertDomain,
   stackExpertNames
-} from "./chunk-xhd77h0p.js";
+} from "./chunk-e618k6te.js";
 import {
   isFinished
 } from "./chunk-abswp1vt.js";

package/dist/hooks/statusline.js

@@ -2,8 +2,8 @@
 import {
   bar,
   runSnapshot
-} from "./chunk-kx45kt9n.js";
-import"./chunk-xhd77h0p.js";
+} from "./chunk-fjeefnqr.js";
+import"./chunk-e618k6te.js";
 import"./chunk-abswp1vt.js";
 import"./chunk-veffvzw5.js";
 import"./chunk-hws2gnxj.js";

package/dist/tldrx.js

@@ -16588,7 +16588,8 @@ var ENTRIES = [
     notes: [
       "It appends exactly one `operator_note` event and touches NOTHING else: run.yml and budget.yml are byte-identical across the call, no gate is signed or revoked, no cursor moves and no money is spent.",
       "It exists because there was no honest carrier for a maintenance action at the moment it happened. The alternatives people reached for were a FUTURE gate note (late, and attached to a decision the note is not about) and `tldrx reject` (which undoes work).",
-      "The note shows up in `tldrx run status` (the last few) and in `tldrx replay` (every one, in place)."
+      "The note shows up in `tldrx run status` (the last few) and in `tldrx replay` (every one, in place).",
+      "It is for PEOPLE reading `tldrx run status`, `tldrx replay` and the dashboard, and it never reaches an agent: no prompt reads `operator_note`. Context meant for the next agent goes in `tldrx-work/<run>/.agent/<stage>/dispatch-notes.md` (for one Build story, `.agent/<stage>/<story>/dispatch-notes.md`), beside that stage's `prompt.md`, which the next prompt inlines under `## Dispatch notes`."
     ]
   },
   {
@@ -26904,6 +26905,45 @@ function testFastRule(fast, full) {
     ]
   ];
 }
+var REOPEN_NOTE_HEADING = "## Why this story was reopened";
+function reopenNoteLines(reopen) {
+  const kind = reopen.fix ? "`tldrx story reopen --for-fix`: a done story reopened to land ONE named defect" : "`tldrx story reopen`: another run of attempts";
+  const fence = fenceFor(reopen.note);
+  return [
+    REOPEN_NOTE_HEADING,
+    "",
+    `A person (${reopen.actor === "" ? "actor not recorded" : reopen.actor}) put this story back with ${kind}.`,
+    "Their note, verbatim:",
+    "",
+    `${fence}text`,
+    reopen.note.replace(/\n$/, ""),
+    fence,
+    ""
+  ];
+}
+function developerReopenSection(reopen) {
+  if (reopen === undefined || reopen === null)
+    return [];
+  return [
+    ...reopenNoteLines(reopen),
+    "This note is part of your brief. The acceptance criteria above still decide the story, and the",
+    "note names what the person found missing or wrong against them: change what it names. A diff",
+    "that leaves the named gap as it was is not an answer to it, and the reviewer is shown this note.",
+    ""
+  ];
+}
+function reviewerReopenSection(reopen) {
+  if (reopen === undefined || reopen === null)
+    return [];
+  return [
+    ...reopenNoteLines(reopen),
+    "Judge the diff against this note as well as against the acceptance criteria: it names the gap",
+    "this attempt exists to close. If the diff leaves that gap as it was — it does not touch what the",
+    "note names, or it changes only comments or docs where the note asks for behaviour — the story is",
+    "not done: return `changes` and cite the note.",
+    ""
+  ];
+}
 var CONFLICT_TURN_HEADING = "## Merge in progress — resolve it first";
 function conflictTurnSection(parts) {
   const turn = parts.conflictTurn;
@@ -26996,6 +27036,7 @@ function buildDeveloperPrompt(parts) {
     "",
     ...dispatchNotesSection(parts.dispatchNotes),
     ...projectSkillsSection(parts.projectSkills),
+    ...developerReopenSection(parts.reopenNote),
     ...conflictTurnSection(parts),
     "## Investigate",
     "",
@@ -27141,6 +27182,7 @@ function buildReviewerPrompt(parts) {
     "",
     ...story.acceptance.map((item) => `- ${item}`),
     "",
+    ...reviewerReopenSection(parts.reopenNote),
     "## Definition of Done — already re-run by the facilitator",
     "",
     ...parts.dodResults.length === 0 ? ["- (no dod commands)"] : parts.dodResults.map((r) => dodRefused(r) ? `- \`${r.command}\` → REFUSED, never ran` : `- \`${r.command}\` → exit ${String(r.exitCode ?? "?")}`),
@@ -39182,6 +39224,7 @@ function reviewerPromptFor(parts) {
     branch: parts.branch,
     epicBranch: parts.epicBranch,
     diffBase: parts.diffBase,
+    reopenNote: parts.reopenNote,
     worktree: parts.worktree,
     conventions: renderConventions(parts.root, [parts.story.story.repo]),
     dodResults: parts.dod.map((r) => ({
@@ -41887,6 +41930,7 @@ class BuildSession {
   reviewerPrompt(story, dod, refusal, diffBase) {
     return reviewerPromptFor({
       diffBase,
+      reopenNote: this.reopenFor(story.planned),
       runDir: this.ctx.runDir,
       root: this.ctx.root,
       runId: this.ctx.runId,
@@ -42475,6 +42519,7 @@ class BuildSession {
       planNote: this.plan.implicit ? story.planned.note ?? IMPLICIT_STORY_NOTE : undefined,
       previousAttempt: story.previousAttempt,
       previousAttemptKind: story.previousAttemptKind,
+      reopenNote: this.reopenFor(story.planned),
       notInWorktree: story.notInWorktree,
       ...story.conflictTurn === undefined ? {} : { conflictTurn: story.conflictTurn },
       dispatchNotes: this.dispatchNotesFor(story.planned.story.id).body,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tldr-experts",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "description": "tldr-experts: an evidence-first, file-based AI development framework - five stages, a gate on every one, and every claim cited or refused. Installs the `tldrx` (and `tldr-experts`) command. Beta.",
   "license": "MIT",
   "author": "Alan Martinez",

package/plugin/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$doc": "Shape verified from https://code.claude.com/docs/en/plugins.md (Quickstart > Create the plugin manifest). Fields used here: name, description, version, author.name. Only plugin.json goes inside .claude-plugin/; skills/, agents/ and hooks/ live at the plugin root.",
   "name": "tldrx",
   "description": "tldr-experts: an evidence-first, file-based AI development framework. Five stages, a gate on every one, every claim cited or refused. Beta.",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "author": {
     "name": "Alan Martinez"
   }