tldr-experts 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tldr-experts",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "tldr-experts: a lightweight, file-based AI development workflow. Installs the `tldrx` (and `tldr-experts`) command. Alpha.",
   "license": "MIT",
   "author": "Alan Martinez",
@@ -48,6 +48,8 @@
   "scripts": {
     "test": "bun test",
     "build": "bun scripts/build.ts",
+    "docs:dev": "cd docs-site && bun install && bun run dev",
+    "docs:build": "cd docs-site && bun install --frozen-lockfile && bun run build",
     "typecheck": "tsc --noEmit",
     "doctor": "bun bin/tldrx.ts doctor",
     "prepublishOnly": "bun run build"

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: a file-based AI development workflow. One loop, five phases, everything on disk. Alpha.",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "author": {
     "name": "Alan Martinez"
   }

package/plugin/skills/tldrx/SKILL.md

@@ -21,6 +21,11 @@ A facilitator, not an author. You read files, hand ONE sub-agent ONE task, write
 the result back, and stop at the gate. You hold no state between steps — the files
 are the state. You do not decide anything that is the human's to decide.
 
+The framework's `stages/`, `workflows/` and `templates/` live in the installed package —
+`$(npm root -g)/tldr-experts/` globally, `node_modules/tldr-experts/` locally, and
+`tldrx doctor` prints the exact path on its `framework` line. This project's overrides
+live in `.tldrx/stages/` and `.tldrx/workflows/`, and win. Never `find /` for them.
+
 ## Step 1, always
 
 ```
@@ -55,8 +60,11 @@ Never answer on their behalf, never pick a default, never "assume yes":
   edit `split.yml` if they want different runs.
 - a gate, an answer, or any ADR/decision document — quote it and ask.
 - a gate `tldrx status` reports as signed `by: auto` that they disagree with. It signs
-  only when its five conditions hold and cannot judge whether a decision was RIGHT: quote
-  the note — it carries all five measured values — and ask before revoking.
+  only when its seven conditions hold and cannot judge whether a decision was RIGHT: quote
+  the note — it carries all seven measured values — and ask before revoking.
+- a Build story left `blocked` that they want built anyway. Two reviewers judged the diff
+  and were not necessarily wrong; overruling them costs another two turns and is theirs to
+  decide. Quote `04-build/log/<id>.md` — it says what each verdict was and why — and ask.
 
 **You act** once they have said what they want — these are mechanical:
 
@@ -65,6 +73,11 @@ Never answer on their behalf, never pick a default, never "assume yes":
   after they said yes · `tldrx reject --run <id> --note "<their reason>"`, and
   `tldrx reject --run <id> --stage <phase>/<stage> --note "…"` to take back an
   approval already given (including one the harness signed `by: auto`).
+- `tldrx story reopen <id> --run <id> --note "<their reason>"` once they have said a
+  blocked story must be built anyway: it puts that one story back to `todo` and restarts
+  its attempt counter at 1 of 2, keeping every earlier attempt on the record. It does NOT
+  send the stage back — if the Build stage is at its gate, `tldrx reject` does that first,
+  and the reopen's own output names which one applies.
 - `tldrx questions lint --run <id>` when a stage wrote a `questions.md`: it exits 2
   if any block is invisible to the parser, and `--fix` converts it without changing
   a word. An unreadable file reads as "no questions" to everything downstream.
@@ -152,7 +165,7 @@ retries are where the money is) and `tldrx budget show`. Quote them, never the a
    from disk. A sub-agent reporting "ok" is not evidence.
 6. **Say which you are in: measured, inferred, or assumed.** Never blur them.
 7. **Stop at gates.** You never close one — not even an `auto` gate, which the
-   framework closes itself and only when all five of its conditions hold.
+   framework closes itself and only when all seven of its conditions hold.
 8. **A checked section holds at least one item.** Nothing to report is still an
    item: `- none [src: absent:<what you looked at>]`. Prose is refused.
 9. **`.tldrx/` and `tldrx-work/` are committed** — the files ARE the state. `init`

package/stages/build/stage.md

@@ -56,6 +56,11 @@ Per story, in `waves.yml` order:
   evidence and is never recorded as any.
 - A reviewer's `changes` requeues the story ONCE, with the review under
   `## Previous attempt`. A second `changes` blocks it.
+- An acceptance criterion that embeds a literal command or pattern is validated BEFORE
+  the edit — run against the current tree first, and a criterion that reports zero while
+  the goal says the work exists is broken, so the real inventory becomes the completion
+  test and the discrepancy goes in the handoff (the criterion text is not the story's to
+  edit). The developer prompt carries this rule verbatim.
 - A DoD failure or a merge conflict blocks that story only — the wave carries on.
 - Nothing pushes. No epic is merged into a default branch.
 

package/stages/build/stage.yml

@@ -22,7 +22,8 @@ model: sonnet
 effort: high
 budget_usd: 9
 timeout_s: 1800
-# Branches and commits are not revertible by a flag, so a dry run is refused
+# A stage that cuts branches and fans out per-story sub-agents has no ONE dispatch to
+# describe, so a dry run is refused
 # rather than half-honoured (spec §5, Build executor).
 dry_run_allowed: false
 

package/stages/plan/stage.md

@@ -52,6 +52,17 @@
 - `waves.yml`
 - `budget.yml`
 
+The first three are **schema'd files a machine parses**, not free markdown. Their exact
+front matter, id shapes, enums and size caps are under **Output schemas** below — read
+that section before writing any of them.
+
+## Output schemas
+
+_The framework renders this section from the validators that gate this stage, so it is the
+contract itself rather than a copy of it. If you are reading this sentence instead of a
+schema, the bundle was not assembled by `tldrx next`: read `src/core/schemas/story.ts`,
+`epic.ts` and `waves.ts` before writing anything._
+
 ## Gate
 
 Blocked on: **<human approval | checks green>** — `stage.yml`'s `gate.type`. What is

package/templates/budget.yml

@@ -4,6 +4,11 @@
 # ceiling_usd is a refusal, not a warning: a stage whose estimate exceeds what
 # remains does not start. spent_usd is rolled up from events.jsonl — never typed
 # by hand, never estimated by an agent.
+#
+# `economy:` is optional and says what these numbers are DENOMINATED IN:
+#   metered-usd  (the default) dollars a spawn may spend
+#   host-tokens  a host-session token allowance — not money, never a spawn cap
+# Leave it out and everything behaves as it always has. See spec §2.11.
 version: 1
 run: "260828-example-slug"
 ceiling_usd: 25

package/templates/epic.md

@@ -23,9 +23,11 @@ What this epic is for, sourced. Two or three sentences.
 
 ## Stories
 
-| Story | Repo | Depends on | Status |
-|---|---|---|---|
-| S1 | example | — | todo |
+The `stories:` list in the front matter above is the membership, and it is the whole
+of it. Each story has its own file at `03-plan/stories/<id>.md`, and its status, its
+repo and its `depends_on` live in THAT file's front matter, where the Build phase
+writes them. None of it is copied here: a copy with no writer is wrong from the
+moment the first story lands (gh #50).
 
 ## Integration test
 

package/dist/hooks/chunk-kw4tffzf.js

@@ -1,139 +0,0 @@
-import {
-  hasSrcMarker,
-  parseSrcToken,
-  resolveSrc
-} from "./chunk-g395gk7e.js";
-
-// src/core/text/handoff.ts
-var HANDOFF_SECTIONS = ["Findings", "Decisions", "Unknowns", "Evidence ledger"];
-var H2_RE = /^##\s+(.+?)\s*$/;
-var BULLET_RE = /^(?: {0,3}-|\d{1,9}[.)])\s+(\S.*)$/;
-var CONTINUATION_RE = /^\s+\S/;
-function parseHandoff(text) {
-  const lines = text.split(`
-`);
-  const sections = [];
-  const headings = [];
-  let current = null;
-  let pending = null;
-  const flushBullet = () => {
-    if (pending === null)
-      return;
-    if (current !== null) {
-      const joined = pending.parts.join(" ");
-      current.bullets.push({ line: pending.line, text: joined, token: parseSrcToken(joined) });
-    }
-    pending = null;
-  };
-  const flush = () => {
-    flushBullet();
-    if (current !== null)
-      sections.push(current);
-    current = null;
-  };
-  for (let i = 0;i < lines.length; i++) {
-    const line = lines[i] ?? "";
-    const heading = H2_RE.exec(line);
-    if (heading !== null && heading[1] !== undefined) {
-      flush();
-      headings.push(heading[1]);
-      current = { name: heading[1], headingLine: i + 1, bullets: [] };
-      continue;
-    }
-    if (line.startsWith("# ")) {
-      flush();
-      continue;
-    }
-    if (current === null)
-      continue;
-    const bullet = BULLET_RE.exec(line);
-    if (bullet !== null && bullet[1] !== undefined) {
-      flushBullet();
-      pending = { line: i + 1, parts: [bullet[1]] };
-      continue;
-    }
-    if (pending !== null && CONTINUATION_RE.test(line)) {
-      pending.parts.push(line.trim());
-      continue;
-    }
-    flushBullet();
-  }
-  flush();
-  return { sections, headings };
-}
-function isHandoff(text) {
-  return missingSections(parseHandoff(text)).length === 0;
-}
-function missingSections(handoff) {
-  const present = handoff.headings;
-  const missing = [];
-  let cursor = 0;
-  for (const required of HANDOFF_SECTIONS) {
-    const at = present.indexOf(required, cursor);
-    if (at === -1)
-      missing.push(required);
-    else
-      cursor = at + 1;
-  }
-  return missing;
-}
-var MAX_BULLETS = 200;
-function validateHandoff(text, ctx) {
-  const handoff = parseHandoff(text);
-  const missing = missingSections(handoff);
-  const emptySections = [];
-  const unsourced = [];
-  const malformed = [];
-  const unresolved = [];
-  const unverified = [];
-  let bulletCount = 0;
-  const required = new Set(HANDOFF_SECTIONS);
-  for (const section of handoff.sections) {
-    if (!required.has(section.name))
-      continue;
-    if (section.bullets.length === 0) {
-      emptySections.push({ name: section.name, line: section.headingLine });
-    }
-    for (const bullet of section.bullets) {
-      bulletCount++;
-      if (bullet.token === null) {
-        if (hasSrcMarker(bullet.text)) {
-          malformed.push({
-            line: bullet.line,
-            message: "malformed citation — the `[src: …]` token must be the last thing on the line " + "(closing quotes, brackets and a final `.` are allowed after it, words are not)"
-          });
-        } else {
-          unsourced.push(bullet.line);
-        }
-        continue;
-      }
-      for (const error of bullet.token.errors) {
-        unresolved.push({ line: bullet.line, message: `[src: ${error.raw}] — ${error.message}` });
-      }
-      const claim = bullet.text.replace(bullet.token.raw, " ").trim();
-      for (const ref of bullet.token.refs) {
-        const resolution = resolveSrc(ref, ctx, section.name, claim);
-        const issue = { line: bullet.line, message: `[src: ${ref.raw}] — ${resolution.message ?? "unresolvable"}` };
-        if (resolution.outcome === "refused")
-          unresolved.push(issue);
-        else if (resolution.outcome === "unverified")
-          unverified.push(issue);
-      }
-    }
-  }
-  if (bulletCount > MAX_BULLETS) {
-    unresolved.push({ line: 0, message: `${bulletCount} bullets exceeds the ${MAX_BULLETS} cap` });
-  }
-  return {
-    ok: missing.length === 0 && emptySections.length === 0 && unsourced.length === 0 && malformed.length === 0 && unresolved.length === 0,
-    missingSections: missing,
-    emptySections,
-    unsourced,
-    malformed,
-    unresolved,
-    unverified,
-    bulletCount
-  };
-}
-
-export { isHandoff, validateHandoff };