tldr-experts 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,71 @@
 # Changelog
 
+## 0.8.0 — 2026-09-04
+
+### Added
+
+- **`tldrx drive --tldr` — essentials only, for a run whose trail nobody will read.** It adds
+  one section to either mandate and stamps the header `· tldr ·`. The session reports in a
+  fixed shape — what `tldrx run status` already prints (phases, percentages, spend against the
+  ceiling, what is next) plus **at most three bullets of delta** — and stops narrating: no
+  recap of a sub-agent's report, no summary of a diff, no restating the status block in prose.
+  Free text is reserved for a strict blocker's guided question and for a correction.
+  It also turns off the half of the trail nothing consumes: no `tldrx note`, and gate evidence
+  at the template's minimum. A fact that must outlive the turn goes to `tldrx facts add`, which
+  every later prompt **does** read.
+  Measured on a ten-run workspace: of ~4.0 MB written, 2.16 MB is trail, and all **261**
+  declared stage `inputs:` contain **zero** occurrences of `handoff.md`, `retro.md` or
+  `gate-evidence` — ~445k tokens of output across those runs that no prompt ever reads back.
+  Operator notes alone are 133,689 B.
+  What `--tldr` deliberately does **not** do is drop the handoff: `claim-sources` is condition 5
+  of the seven `auto` conditions and runs whether or not a stage declared it, so a run without
+  one cannot close an `auto` or `agent` gate. The mandate briefs sub-agents to trim the *prose*
+  and never the `[src: …]` citations, and says why. `--tldr` works on `--attended` too — terse
+  output is orthogonal to who signs. Absence is today: without the flag both mandates render
+  byte-identically to before, and a test asserts it.
+- `MANDATE_TLDR_MAX_LINES` (`165`) bounds the `--tldr` variants; the standard mandate keeps the
+  tighter `MANDATE_MAX_LINES`. Two constants rather than one looser one, so the terse mode does
+  not spend every other run's skimmability budget.
+
+### Fixed
+
+- **`tldrx drive --unattended` told the driver four times to stop and never once to
+  continue, and the runs it drove did exactly that.** Measured over the eight driven runs
+  of a real workspace: 26 `budget.raised` and 26 `question.answered` events, and an owner
+  who had to type *"sigue con todas desatendido, no esperes por mi"* **inside** an
+  unattended run to restart a session the mandate had correctly halted. `grep -ic
+  "continue|keep going|proceed|do not stop|resume"` over `mandate.ts` returned `0`. The
+  unattended mandate now opens the discipline with a **`## Do not stop`** section that
+  defines the only thing that may halt a run — a STRICT blocker, one where no remaining
+  turn can proceed until the owner answers — and makes the driver **name the work the
+  blocker does not block** before it may call one strict. The three remaining halts are
+  narrowed to match: the preflight refusal is now *asked* rather than gone quiet on, the
+  budget bullet keeps "do not raise one, do not route around one" but no longer halts the
+  run (it asks, then keeps spending what the ceiling still funds), and the interrupt list
+  is strict blockers only, "never as a bare halt".
+- **A parked question is now a GUIDED question.** "State the question in one sentence" got
+  open prompts nobody could answer from a phone, so a product question stopped a run for
+  hours. Parking now asks for 2–5 lettered options with their consequences, what the run's
+  own docs and facts already decide, the option the driver would take, and what it will do
+  if no answer arrives. Both modes carry it.
+- **The old halt licence is gone.** "If the only safe version is *do nothing yet*, do
+  nothing yet and park it" was true about the write and read as true about the run. The
+  text now says which it means: not shipping an unguarded write is not the same as not
+  shipping anything.
+
+### Changed
+
+- **The ask channel is the console, and the framework stays agnostic about anything else.**
+  The mandate says *"Ask on the console, unless my launch message named another channel"* —
+  no chat vendor is named in shipped text, and a test asserts none ever is, so one
+  operator's bridge never becomes a dependency of everybody's run. A default the driver
+  falls back on when no answer reaches it is recorded as the **driver's** decision and may
+  never be cited back as the owner's — the distinction one run drew by hand and the text
+  now carries.
+- `MANDATE_MAX_LINES` moved once, `120` → `140`, with the reason recorded in the source.
+  The bound is still real and still asserted; the unattended mandate renders 137 lines and
+  the attended one 123. File formats remain `version: 1`.
+
 ## 0.7.0 — 2026-09-03
 
 ### Added

package/README.md

@@ -75,14 +75,30 @@ Two commands and a prompt — and the prompt now ships with the package:
 ```bash
 tldrx drive --unattended        # print the mandate; paste it into the session that drives the run
 tldrx drive --attended          # the same disciplines, but every gate stays yours to sign
+tldrx drive --unattended --tldr # essentials only, for a run whose trail you will not read
 ```
 
 `tldrx drive` needs no workspace, opens no run and writes nothing: it prints the discipline the
 first real runs were driven by — the three-role protocol (developer → a **fresh** adversarial
 reviewer, never the author → the host verifying both in the code, not in their reports), evidence
-labelled `measured` / `inferred` / `assumed`, product questions parked rather than decided, the
-reviewer calibrated to the story's stakes, and the cost declared once. The two modes differ in
-exactly two places: who drives the turns, and who may close a gate.
+labelled `measured` / `inferred` / `assumed`, product questions parked as **guided** ones rather
+than decided, the reviewer calibrated to the story's stakes, and the cost declared once. The two
+modes differ in exactly two places: who drives the turns, and who may close a gate.
+
+**The unattended mandate leads with `## Do not stop`.** A run only ends early because the session
+decides to, so the text defines the one thing that may end it — a strict blocker, where no
+remaining turn can proceed until you answer — and makes the driver name the work a blocker does
+*not* block before it may halt for it. Everything short of that is parked as a guided question
+(lettered options, the option the driver would take, asked on the console unless your launch
+message names another channel) and the run carries on down every path the question does not block.
+
+**`--tldr` is for the runs you will not audit.** The session reports what `tldrx run status`
+already prints — phases, percentages, spend against the ceiling, what is next — plus at most three
+bullets of delta, and stops narrating. It also drops the half of the trail nothing consumes:
+measured across ten real runs, of ~4.0 MB written 2.16 MB is trail, and all 261 declared stage
+`inputs:` contain **zero** references to `handoff.md`, `retro.md` or `gate-evidence`. It is a
+reporting contract, not a quality setting — the evidence discipline and the gate checks are
+untouched, and handoffs keep their citations because `claim-sources` gates on them.
 
 The rest of this section is what that mandate says, in the shape you would type it by hand.
 
@@ -298,6 +314,7 @@ back on the registry is 0.3.0.
 
 | Version | Date | Status | Contains |
 |---|---|---|---|
+| 0.8.0 | 2026-09-04 | `beta` | the unattended mandate learns to keep going: a `## Do not stop` section that defines the one thing allowed to end a run early (a strict blocker, named against the work it does not block), product questions parked as **guided** ones with lettered options and a pre-declared fallback, and a budget stop that asks instead of halting — written against 26 `budget.raised` and 26 `question.answered` events on a real ten-run workspace where the owner had to re-authorise "unattended" mid-run. Plus `tldrx drive --tldr`: a reporting contract for runs nobody will audit — the `run status` block plus three bullets of delta, no operator notes, minimal gate evidence, handoffs trimmed of prose but never of the citations `claim-sources` gates on. The ask channel stays the console and the framework names no chat vendor |
 | 0.7.0 | 2026-09-03 | `beta` | Codex as a second honest automated runner: recorded JSONL contract, structured envelopes, role-based sandboxes, token/session provenance, and explicitly unmetered USD accounting; Claude remains the default and the pilot harness. Also absorbs the citation-honesty work previously staged as 0.6.2: a `file` src resolves against the branches the run RECORDED and NAMES the unmerged ref instead of passing in silence or breaking with the temp dir (#140), watcher cards name it the same way (#143), and every run close reports the questions nobody answered (#141) |
 | 0.6.1 | 2026-09-03 | `beta` | dogfooding fixes from the first fully-unattended runs: blocked stories never lose uncommitted work (rescue commits + `story.work_rescued`), a fix is only Resolved with a reachable sha, re-entered stages reconstruct their handoff from the ledger instead of degrading it, the Cost header reports the phase and names its lower bound (shared `spendBasis`), feature presets resolve their per-repo maps, Plan sees the command allowlist its gate enforces, the landing sells the unattended flow |
 | 0.6.0 | 2026-09-02 | `beta` | the dashboard suite — a "Now" hero strip, `--serve` live refresh, stage durations and gate notes on page and CLI, and a public demo generated from fixtures; honest dual-economy spend (metered + host, lower-bound named); gate provenance — `executed_by` + `authority` so a delegated signature never reads as a personal one, machine-signed reporting fixed; ONE `absent:` semantic shared by claim-sources and the auto gate; superseded stamps when an owner answer flips an earlier phase doc; run close commits its state and `ship` refuses a state-carrying epic; merge-wave gates `docs:build`, survives interruption and self-rewrite; a public-surface drift guard; env.yml validation (unique ids, tool cap) |

package/dist/tldrx.js

@@ -15274,11 +15274,17 @@ var ENTRIES = [
         name: "unattended",
         arg: null,
         meaning: "Nobody is watching. The mandate is for a session driving an `attended_by: host` run with `agent` gates: it drives every turn, signs a gate only over a written evidence note, and wakes a person for the four things that are still theirs."
+      },
+      {
+        name: "tldr",
+        arg: null,
+        meaning: "Essentials only, for a run whose trail you will not read. The mandate gains a reporting contract: after every commit and at every gate the session shows what `tldrx run status` prints plus at most three bullets of delta, and nothing else — no recaps, no diff summaries, no `tldrx note`. Sub-agents are briefed to keep handoffs and evidence notes at the minimum `claim-sources` still validates. Prose is trimmed; citations and gates are not. Works with either mode."
       }
     ],
     examples: [
       "tldrx drive --unattended",
       "tldrx drive --unattended 260901-leaderboard",
+      "tldrx drive --unattended --tldr",
       "tldrx drive --attended"
     ],
     exits: [EXIT_OK, EXIT_USAGE],
@@ -46445,24 +46451,26 @@ function option3(argv, name) {
 var DRIVE_MODES = ["attended", "unattended"];
 var RULE = "-".repeat(78);
 var RUN_PLACEHOLDER = "<run>";
-function renderMandate(mode, version, run2) {
+function renderMandate(mode, version, run2, tldr = false) {
   const text5 = [
-    ...header2(mode, version, run2),
+    ...header2(mode, version, run2, tldr),
     ...preflight(mode),
     ...roles(),
     ...evidence(),
+    ...continuation(mode),
     ...parking(),
     ...calibration(),
     ...budget(),
+    ...reporting(tldr),
     ...driving(mode),
     ...gate2(mode)
   ].join(`
 `).trimEnd();
   return run2 === undefined ? text5 : text5.replaceAll(RUN_PLACEHOLDER, run2);
 }
-function header2(mode, version, run2) {
+function header2(mode, version, run2, tldr = false) {
   return [
-    `tldrx drive — session mandate · ${mode} · tldrx ${version}`,
+    `tldrx drive — session mandate · ${mode}${tldr ? " · tldr" : ""} · tldrx ${version}`,
     "",
     ...run2 === undefined ? [
       "Paste everything below the rule into the session that will drive the run, replacing <run>",
@@ -46496,7 +46504,8 @@ function preflight(mode) {
       '  `tldrx run gates set <stage>:agent --note "…"`, quoting MY delegation from the launch message.',
       "- BUDGET: `tldrx-work/<run>/budget.yml` exists. State the ceiling you will honour, in dollars.",
       "",
-      "Any one of the three you cannot establish: REFUSE to start, and name the command that failed.",
+      "Any one of the three you cannot establish: REFUSE to start, name the command that failed,",
+      "and put it to me as a guided question — a strict blocker is asked, never gone quiet on.",
       ""
     ];
   }
@@ -46552,23 +46561,74 @@ function evidence() {
     ""
   ];
 }
+function continuation(mode) {
+  if (mode !== "unattended")
+    return [];
+  return [
+    "## Do not stop",
+    "",
+    'Stopping is the failure this mandate exists to prevent, and "I had a question" is not one.',
+    "Halt only on a STRICT blocker: one where no remaining turn can proceed until I answer. Before",
+    "you call one strict, name the work it does NOT block — the next story, wave, stage or review —",
+    "and go do that first. Everything short of that you park as below, or decide and log; then",
+    "carry on. If you are truly blocked on every front, that is one line and a guided question, not",
+    "silence.",
+    ""
+  ];
+}
 function parking() {
   return [
-    "## Park product questions; do not decide them",
+    "## Park product questions as GUIDED ones; do not decide them, and do not halt for them",
     "",
-    "A product decision is not yours. Park it as a card the same turn you hit it:",
+    "A product decision is not yours to make — and it is not a reason to stop the run. Park it",
+    "the same turn you hit it, then carry on down every path it does not block:",
     "",
-    "- state the question in one sentence, and what it blocks;",
-    "- say what the docs and the run's own facts ALREADY decide about it, with the citation, so",
-    "  I am choosing between real options instead of re-deriving them;",
-    "- name the smallest guarded thing you can ship without the answer — or say there is none.",
+    "- the question in one sentence, and exactly what it blocks — and what it does NOT;",
+    "- 2–5 lettered options, each with its consequence. Never an open prompt;",
+    "- what the docs and the run's own facts ALREADY decide, cited, so I pick between real options;",
+    "- the option you would take and why, and what you will do if no answer reaches you;",
+    "- the smallest guarded thing you can ship without the answer — or say there is none.",
     "",
-    "An open question is never a licence to ship an unguarded write. If the only safe version is",
-    '"do nothing yet", do nothing yet and park it. `tldrx note <run> "…"` records the moment;',
+    "Ask on the console, unless my launch message named another channel; then use that one and say",
+    "so. An answer I never gave is not my decision: if you act on your own default, record it as",
+    "YOURS in those words, and never cite it back to me as mine.",
+    "",
+    "An open question is never a licence to ship an unguarded write — but not shipping the write is",
+    'not the same as not shipping anything. `tldrx note <run> "…"` records the moment;',
     '`tldrx answer <Qid> "…"` is mine to type.',
     ""
   ];
 }
+function reporting(tldr) {
+  if (!tldr)
+    return [];
+  return [
+    "## Report terse; do not narrate",
+    "",
+    "I am not reading this session for its prose, so write none. After every `--commit` and at",
+    "every gate, show me two things and nothing else:",
+    "",
+    "1. what `tldrx run status <run>` prints — it already carries the phases, the percentages, the",
+    "   spend against the ceiling and what is next. Do not retype any of it in words.",
+    "2. at most three bullets of DELTA since the last one: what landed, what is next, what was",
+    "   deferred or decided. Three is a cap, not a target.",
+    "",
+    "Free text is for two things only: a strict blocker's guided question, and a correction to",
+    "something you already told me. Not a recap of a sub-agent's report, not a summary of a diff I",
+    "can read myself, not the status block again in sentences.",
+    "",
+    "Write no `tldrx note` on this run. Nobody will audit it, and no prompt ever reads one back — a",
+    "fact that must outlive the turn is `tldrx facts add`, which every later prompt DOES read.",
+    "",
+    "Brief every sub-agent to keep its handoff minimal: the sections and the `[src: …]` citations",
+    "`claim-sources` validates, and nothing past them. Trim the prose, never the citations — the",
+    "handoff is a gate input, and one that fails the validator costs the gate you need to close.",
+    "",
+    "Same for the evidence note: the four H2 sections, the counts you actually measured, and",
+    "`caveats: []` when there are none. It is a signature, not a report.",
+    ""
+  ];
+}
 function calibration() {
   return [
     "## Calibrate the review to the stakes",
@@ -46595,8 +46655,9 @@ function budget() {
     "  $0.00 is a measurement, and a false one.",
     '- When the records are incomplete, report a floor and say it is one — "at least $4.10 across',
     '  the 6 turns that reported" — never a total that reads as complete.',
-    "- A ceiling raise is my decision. Do not raise one, and do not route around one: stop, say",
-    "  what the remaining work costs and why, and wait.",
+    "- A ceiling raise is my decision: do not raise one, and do not route around one. That is not",
+    "  a reason to halt the run — ask it as a guided question, say what the remaining work costs,",
+    "  and keep spending what the ceiling still funds. Stop only when the next turn has none left.",
     ""
   ];
 }
@@ -46650,9 +46711,10 @@ function gate2(mode) {
       "`refuse` and `sign-with-fixlist` are real verdicts — use them. A note that signs everything",
       "is a rubber stamp the framework will believe.",
       "",
-      "Interrupt me ONLY for: a new product decision · a budget-ceiling raise · work outside the",
-      "declared boundary · the final merge. Everything else you decide, and log. Never push — the",
-      "final merge is mine.",
+      "Interrupt me ONLY for a STRICT blocker — a new product decision, a ceiling raise, or work",
+      "outside the declared boundary that nothing else can proceed around — and always as the",
+      "guided question above, never as a bare halt. Everything else you decide, and log.",
+      "Never push — the final merge is mine.",
       ""
     ];
   }
@@ -46683,7 +46745,7 @@ function gate2(mode) {
 var driveCommand = {
   name: "drive",
   summary: "Print the session mandate for driving a run",
-  usage: "tldrx drive <--attended|--unattended> [<run>] [--run <id>]",
+  usage: "tldrx drive <--attended|--unattended> [--tldr] [<run>] [--run <id>]",
   subcommands: [],
   implemented: true,
   async run(argv) {
@@ -46704,7 +46766,8 @@ var driveCommand = {
     }
     const mode = attended2 ? "attended" : "unattended";
     const run2 = args.positionals[0] ?? stringFlag(args, "run") ?? theOneOpenRun();
-    process.stdout.write(`${renderMandate(mode, await frameworkVersion(), run2)}
+    const tldr = boolFlag(args, "tldr");
+    process.stdout.write(`${renderMandate(mode, await frameworkVersion(), run2, tldr)}
 `);
     return EXIT_OK;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tldr-experts",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "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.7.0",
+  "version": "0.8.0",
   "author": {
     "name": "Alan Martinez"
   }