tldr-experts 0.3.0

package/templates/run.yml

@@ -0,0 +1,24 @@
+# schema: draft
+# Written to tldrx-work/<yymmdd>-<slug>/run.yml. Concept §5.
+#
+# THE execution path and the resume point. Together with events.jsonl this is the
+# dashboard's only data source. If it is not in here, it did not happen.
+version: 1
+run_id: "260828-example-slug"
+scope: feature
+workflow: feature
+status: pending          # pending | running | awaiting-answer | awaiting-gate | blocked | done | abandoned
+budget_usd: 25
+created_at: null
+
+phases:
+  - id: "01-what"
+    stage: what
+    status: pending
+    expert: null
+    model: null
+    cost_usd: 0
+    started_at: null
+    ended_at: null
+    inputs: []
+    outputs: []

package/templates/story.md

@@ -0,0 +1,55 @@
+---
+# Written to tldrx-work/<run>/03-plan/stories/<id>.md. Spec §2.13.
+#
+# The front matter is the machine-read half: `dod-gate` and `tldrx approve` read
+# it, and the Build phase cuts `story/<id>` from the epic branch on the strength
+# of it. Everything below the closing `---` is for the human who picks this up
+# cold — except the fenced ```dod block, which is executed, not read.
+version: 1
+id: S1
+epic: E1
+title: "Materialise the leaderboard read model"
+repo: example
+status: todo                 # todo | in_progress | review | done | blocked
+depends_on: []               # story ids that must be DONE first, e.g. [S2]
+touches:
+  - "src/features/leaderboard/"
+acceptance:
+  - "Top-50 ranks render from the materialised view, newest hunt first"
+  - "A hunt completed while the page is open moves the player within one refresh"
+test_plan:
+  - "Unit: rank ordering with ties, empty table, single player"
+  - "Integration: HuntCompleted refreshes the view"
+evidence: []                 # filled by Build — commands run, files written, PR
+---
+
+# S1 · Materialise the leaderboard read model
+
+> One repo, one branch, one Definition of Done. If this story needs a change in a
+> second repo, that is a second story with `depends_on` pointing here.
+
+## Context
+
+Why this story exists, in two or three sentences, each ending in a `[src: …]`
+token. Read it as the only briefing the Build agent gets.
+
+## Acceptance criteria
+
+Restate the front matter's `acceptance` list here in prose if it helps a reader;
+the front matter is what is checked.
+
+## Definition of done
+
+**Every command below must equal a `.tldrx/workspace.yml` command verbatim** — a
+story may not invent one — and every one of them must exit `0` before `status:`
+may be written as `done`. `dod-gate` re-runs them; your word for it is not evidence.
+
+```dod
+npm run test
+npm run lint
+```
+
+## Evidence
+
+Filled by Build. One bullet per proof, each ending in a `[src: …]` token — a
+command source (`$ npm run test → exit 0`) belongs here.

package/templates/watcher.md

@@ -0,0 +1,68 @@
+---
+# Written to tldrx-work/<run>/05-watch/watchers/<feature>.md. Spec §2.16.
+#
+# One card per SHIPPED feature — one per epic whose stories reached `status: done`.
+# Everything on it is derived from what Build actually instrumented. A signal that
+# would be nice to have is not a signal; it is an `absent:` source and a `draft`
+# card that names what to instrument.
+version: 1
+id: leaderboard              # = the file name (leaderboard.md); [a-z0-9-]
+epic: E1                     # the epic this feature was built on
+title: "Player leaderboard"
+stories: [S1, S3]            # the DONE stories the card was written from
+repos: [api, lab]
+status: draft                # draft | verified — verified only when Signal has no `absent:` source
+---
+
+# leaderboard · Player leaderboard
+
+> How anyone would know this still works next month. Every list item under Signal,
+> Where, Healthy baseline and Looks broken when ends with a [src: …] token, and
+> that token points at the BUILT code — `<repo>:<path>:<line>` — at an `F<n>` fact,
+> or, when the code emits nothing at all, at `absent:<what you looked at>`.
+
+## Signal
+
+> The log line, metric or event that proves the feature works. Not "we should log
+> X" — the line that is in the code, at the line it is on.
+
+- `leaderboard.refreshed` is written on every view refresh [src: api:src/Leaderboard/RefreshHandler.cs:64]
+- No counter exists for a refresh that finds zero rows — add one before this is watchable [src: absent:api/src/Leaderboard]
+
+## Where
+
+> The dashboard, log stream, table or query console this is read in.
+
+- Application Insights → `traces`, filtered to the message above [src: F014]
+
+## Healthy baseline
+
+> A measured number and when it was taken. A guess belongs in Looks broken when as
+> an assumption, or nowhere.
+
+- 12–40 refreshes/hour during business hours, measured 2026-08-29 [src: F015]
+
+## Looks broken when
+
+> What the same signal looks like on the bad day, concretely enough to alert on.
+
+- Zero refreshes for 30 minutes while hunts are still completing [src: api:src/Leaderboard/RefreshHandler.cs:64]
+
+## Query
+
+> Copy-paste, in the query language of the place named under Where. One fenced
+> block, run once before it is written down.
+
+```kql
+traces
+| where message == "leaderboard.refreshed"
+| summarize count() by bin(timestamp, 1h)
+```
+
+## Sources
+
+> Everything cited above, once, with what it establishes. Free prose is allowed
+> here; the four checked sections above are the ones that must hold sourced items.
+
+- `RefreshHandler.cs:64` is the only place the event is emitted.
+- No dashboard exists yet; the query above is what a dashboard would run.

package/templates/waves.yml

@@ -0,0 +1,17 @@
+# Written to tldrx-work/<run>/03-plan/waves.yml. Spec §2.15.
+#
+# The execution order of the Plan, and the only file that says what may run at the
+# same time. Concept §9: "stories grouped by dependency; wave N+1 starts only when
+# wave N's epic branch is green", and "independent stories in the same wave run as
+# parallel sub-agents in separate worktrees".
+#
+# Both sentences make the same demand, and it is the rule the shape cannot enforce
+# on its own: every story's `depends_on` must land in an EARLIER wave. A dependency
+# inside the same wave is an error, not a warning — those two stories would be
+# handed to parallel agents that overwrite each other.
+#
+# File order IS execution order, so wave ids ascend. A story runs in exactly one wave.
+version: 1
+waves:
+  - {id: W1, stories: [S1, S2]}
+  - {id: W2, stories: [S3]}

package/templates/workspace.yml

@@ -0,0 +1,30 @@
+# schema: draft
+# Written by `tldrx init` to .tldrx/workspace.yml. Concept §4.1 and the v0.1
+# workspace-model addendum.
+#
+# mode: single  — cwd is itself a git repo
+# mode: multi   — cwd contains child dirs that are git repos; those are the repos.
+#                 One .tldrx/ at the root, always. Shared: memory/, experts/,
+#                 stages/, workflows/. Per repo: map/<repo>/, conventions/<repo>.md.
+version: 1
+mode: single
+root: "."
+detected_at: null
+
+repos:
+  - name: example
+    path: "."
+    languages: []
+    frameworks: []
+    # Commands are DISCOVERED, never assumed. An empty value means "not found",
+    # which is different from "there is none" — say which in the handoff.
+    commands:
+      install: ""
+      build: ""
+      test: ""
+      lint: ""
+      typecheck: ""
+
+# Cached from `claude mcp list` at init (it runs live health checks and is slow).
+# .mcp.json is the fast path; this is the verified one.
+mcp_servers: []

package/workflows/bugfix.yml

@@ -0,0 +1,26 @@
+# schema: draft
+# A scope is a workflow preset (concept v0.1 addendum). It biases the facilitator:
+# which stages run, at what depth, on what budget. Adding a scope = adding one yml.
+# The facilitator never hard-codes a scope.
+#
+# stages  — run in this order; every name must be a folder under stages/
+# skips   — stages deliberately NOT run, so the omission is a decision on record
+# depth   — minimal | light | standard | deep
+name: bugfix
+description: "Fix one specific defect, from a report or a log."
+stages: [what, how, plan, build, watch]
+skips: []
+depth: light
+default_budget_usd: 10
+# gates  — who closes each stage's gate: `human` waits for `tldrx approve`,
+#           `auto` lets the facilitator close it when the five spec §5 conditions
+#           hold (checks pass, no open question, spend within ceiling, the stage
+#           did not fail, claim-sources clean). Every stage still ENDS at a gate;
+#           this only says who signs it. A stage not named here is `human`.
+gates: {what: human, how: auto, plan: human, build: auto, watch: human}
+changes:
+  - "What = reproduce it, then find the root cause. A fix without a reproduction is a guess."
+  - "How = the minimal change that removes the cause, not the symptom."
+  - "Plan is usually a single story."
+  - "Watch = a regression watcher for this exact signal."
+  - "Market and UX questions are not asked."

package/workflows/docs.yml

@@ -0,0 +1,23 @@
+# schema: draft
+# A scope is a workflow preset (concept v0.1 addendum). It biases the facilitator:
+# which stages run, at what depth, on what budget. Adding a scope = adding one yml.
+# The facilitator never hard-codes a scope.
+#
+# stages  — run in this order; every name must be a folder under stages/
+# skips   — stages deliberately NOT run, so the omission is a decision on record
+# depth   — minimal | light | standard | deep
+name: docs
+description: "Write or repair documentation."
+stages: [what, build]
+skips: [how, plan, watch]
+depth: light
+default_budget_usd: 6
+# gates  — who closes each stage's gate: `human` waits for `tldrx approve`,
+#           `auto` lets the facilitator close it when the five spec §5 conditions
+#           hold (checks pass, no open question, spend within ceiling, the stage
+#           did not fail, claim-sources clean). Every stage still ENDS at a gate;
+#           this only says who signs it. A stage not named here is `human`.
+gates: {what: auto, build: human}
+changes:
+  - "Investigate, then write. The gate is a human actually reading it and saying it is right."
+  - "Every claim in the docs carries the same source rule as a handoff."

package/workflows/feature.yml

@@ -0,0 +1,22 @@
+# schema: draft
+# A scope is a workflow preset (concept v0.1 addendum). It biases the facilitator:
+# which stages run, at what depth, on what budget. Adding a scope = adding one yml.
+# The facilitator never hard-codes a scope.
+#
+# stages  — run in this order; every name must be a folder under stages/
+# skips   — stages deliberately NOT run, so the omission is a decision on record
+# depth   — minimal | light | standard | deep
+name: feature
+description: "Default. New capability, full loop, practical depth."
+stages: [what, how, plan, build, watch]
+skips: []
+depth: standard
+default_budget_usd: 25
+# gates  — who closes each stage's gate: `human` waits for `tldrx approve`,
+#           `auto` lets the facilitator close it when the five spec §5 conditions
+#           hold (checks pass, no open question, spend within ceiling, the stage
+#           did not fail, claim-sources clean). Every stage still ENDS at a gate;
+#           this only says who signs it. A stage not named here is `human`.
+gates: {what: human, how: auto, plan: human, build: auto, watch: human}
+changes:
+  - "No deltas — this is the baseline every other scope is described against."

package/workflows/hotfix.yml

@@ -0,0 +1,24 @@
+# schema: draft
+# A scope is a workflow preset (concept v0.1 addendum). It biases the facilitator:
+# which stages run, at what depth, on what budget. Adding a scope = adding one yml.
+# The facilitator never hard-codes a scope.
+#
+# stages  — run in this order; every name must be a folder under stages/
+# skips   — stages deliberately NOT run, so the omission is a decision on record
+# depth   — minimal | light | standard | deep
+name: hotfix
+description: "Production is bleeding. Ship, then explain."
+stages: [what, build, watch]
+skips: [how, plan]
+depth: minimal
+default_budget_usd: 5
+# gates  — who closes each stage's gate: `human` waits for `tldrx approve`,
+#           `auto` lets the facilitator close it when the five spec §5 conditions
+#           hold (checks pass, no open question, spend within ceiling, the stage
+#           did not fail, claim-sources clean). Every stage still ENDS at a gate;
+#           this only says who signs it. A stage not named here is `human`.
+gates: {what: auto, build: human, watch: human}
+changes:
+  - "What collapses to a ten-line handoff: symptom, blast radius, the one change."
+  - "All gates collapse into one human approval."
+  - "Retro is MANDATORY at close — this is the scope that skips the most and so owes the most."

package/workflows/integration.yml

@@ -0,0 +1,24 @@
+# schema: draft
+# A scope is a workflow preset (concept v0.1 addendum). It biases the facilitator:
+# which stages run, at what depth, on what budget. Adding a scope = adding one yml.
+# The facilitator never hard-codes a scope.
+#
+# stages  — run in this order; every name must be a folder under stages/
+# skips   — stages deliberately NOT run, so the omission is a decision on record
+# depth   — minimal | light | standard | deep
+name: integration
+description: "Wire up an external API."
+stages: [what, how, plan, build, watch]
+skips: []
+depth: standard
+default_budget_usd: 30
+# gates  — who closes each stage's gate: `human` waits for `tldrx approve`,
+#           `auto` lets the facilitator close it when the five spec §5 conditions
+#           hold (checks pass, no open question, spend within ceiling, the stage
+#           did not fail, claim-sources clean). Every stage still ENDS at a gate;
+#           this only says who signs it. A stage not named here is `human`.
+gates: {what: human, how: auto, plan: human, build: auto, watch: human}
+changes:
+  - "What includes vendor-doc verification: fetch the official docs this run and cite the URL."
+  - "How = contracts plus the auth story, including what happens when the token expires."
+  - "Watch sits on the vendor calls: rate limits, error shapes, latency."

package/workflows/migration.yml

@@ -0,0 +1,24 @@
+# schema: draft
+# A scope is a workflow preset (concept v0.1 addendum). It biases the facilitator:
+# which stages run, at what depth, on what budget. Adding a scope = adding one yml.
+# The facilitator never hard-codes a scope.
+#
+# stages  — run in this order; every name must be a folder under stages/
+# skips   — stages deliberately NOT run, so the omission is a decision on record
+# depth   — minimal | light | standard | deep
+name: migration
+description: "Move a runtime, framework, dependency or data set from A to B."
+stages: [what, how, plan, build, watch]
+skips: []
+depth: deep
+default_budget_usd: 60
+# gates  — who closes each stage's gate: `human` waits for `tldrx approve`,
+#           `auto` lets the facilitator close it when the five spec §5 conditions
+#           hold (checks pass, no open question, spend within ceiling, the stage
+#           did not fail, claim-sources clean). Every stage still ENDS at a gate;
+#           this only says who signs it. A stage not named here is `human`.
+gates: {what: auto, how: auto, plan: auto, build: human, watch: human}
+changes:
+  - "What = an inventory plus a compatibility matrix, both derived from the code map."
+  - "How = the strategy call: big-bang versus strangler, stated with its rollback."
+  - "Plan waves by module, so a half-done migration is still a working system."

package/workflows/performance.yml

@@ -0,0 +1,23 @@
+# schema: draft
+# A scope is a workflow preset (concept v0.1 addendum). It biases the facilitator:
+# which stages run, at what depth, on what budget. Adding a scope = adding one yml.
+# The facilitator never hard-codes a scope.
+#
+# stages  — run in this order; every name must be a folder under stages/
+# skips   — stages deliberately NOT run, so the omission is a decision on record
+# depth   — minimal | light | standard | deep
+name: performance
+description: "Make something measurably faster."
+stages: [what, how, build, watch]
+skips: [plan]
+depth: standard
+default_budget_usd: 20
+# gates  — who closes each stage's gate: `human` waits for `tldrx approve`,
+#           `auto` lets the facilitator close it when the five spec §5 conditions
+#           hold (checks pass, no open question, spend within ceiling, the stage
+#           did not fail, claim-sources clean). Every stage still ENDS at a gate;
+#           this only says who signs it. A stage not named here is `human`.
+gates: {what: human, how: auto, build: auto, watch: human}
+changes:
+  - "What = a MEASURED baseline. No baseline, no scope — the run refuses to start."
+  - "Watch = the before/after comparison, on the same query, on the same data."

package/workflows/prototype.yml

@@ -0,0 +1,24 @@
+# schema: draft
+# A scope is a workflow preset (concept v0.1 addendum). It biases the facilitator:
+# which stages run, at what depth, on what budget. Adding a scope = adding one yml.
+# The facilitator never hard-codes a scope.
+#
+# stages  — run in this order; every name must be a folder under stages/
+# skips   — stages deliberately NOT run, so the omission is a decision on record
+# depth   — minimal | light | standard | deep
+name: prototype
+description: "Throwaway. Explicitly not for production."
+stages: [what, how, build]
+skips: [plan, watch]
+depth: minimal
+default_budget_usd: 12
+# gates  — who closes each stage's gate: `human` waits for `tldrx approve`,
+#           `auto` lets the facilitator close it when the five spec §5 conditions
+#           hold (checks pass, no open question, spend within ceiling, the stage
+#           did not fail, claim-sources clean). Every stage still ENDS at a gate;
+#           this only says who signs it. A stage not named here is `human`.
+gates: {what: auto, how: auto, build: human}
+changes:
+  - "Conventions gate is OFF. Definition of Done drops the test requirement."
+  - "Every artefact carries a NOT FOR PRODUCTION marker."
+  - "If it survives, it is re-run under the feature scope. It is not promoted in place."

package/workflows/refactor.yml

@@ -0,0 +1,24 @@
+# schema: draft
+# A scope is a workflow preset (concept v0.1 addendum). It biases the facilitator:
+# which stages run, at what depth, on what budget. Adding a scope = adding one yml.
+# The facilitator never hard-codes a scope.
+#
+# stages  — run in this order; every name must be a folder under stages/
+# skips   — stages deliberately NOT run, so the omission is a decision on record
+# depth   — minimal | light | standard | deep
+name: refactor
+description: "Pay down tech debt. Behaviour must not change."
+stages: [what, how, plan, build, watch]
+skips: []
+depth: standard
+default_budget_usd: 20
+# gates  — who closes each stage's gate: `human` waits for `tldrx approve`,
+#           `auto` lets the facilitator close it when the five spec §5 conditions
+#           hold (checks pass, no open question, spend within ceiling, the stage
+#           did not fail, claim-sources clean). Every stage still ENDS at a gate;
+#           this only says who signs it. A stage not named here is `human`.
+gates: {what: human, how: auto, plan: human, build: auto, watch: human}
+changes:
+  - "What = evidence of pain, measured: churn x complexity from map/hotspots.md."
+  - "Build gate is behaviour-preserving tests — written BEFORE the refactor, green on both sides."
+  - "Watch is optional; drop it when no runtime behaviour changed."

package/workflows/retro.yml

@@ -0,0 +1,20 @@
+# schema: draft
+# A scope is a workflow preset (concept v0.1 addendum). It biases the facilitator:
+# which stages run, at what depth, on what budget. Adding a scope = adding one yml.
+# The facilitator never hard-codes a scope.
+#
+# stages  — run in this order; every name must be a folder under stages/
+# skips   — stages deliberately NOT run, so the omission is a decision on record
+# depth   — minimal | light | standard | deep
+name: retro
+description: "Meta scope: read a finished run and propose what to keep."
+stages: []
+skips: [what, how, plan, build, watch]
+depth: minimal
+default_budget_usd: 3
+# gates — retro runs no stage from stages/, so there is no stage gate to place.
+#         `tldrx retro <run-id>` is a command a human runs, not a stage.
+changes:
+  - "Runs no stage from stages/. Driven by `tldrx retro <run-id>`, which reads events.jsonl."
+  - "Proposes three things: facts to remember, practices to change, stages to add."
+  - "Proposed stages land in stages/proposed/ and stay INERT until a human accepts them."

package/workflows/security-patch.yml

@@ -0,0 +1,23 @@
+# schema: draft
+# A scope is a workflow preset (concept v0.1 addendum). It biases the facilitator:
+# which stages run, at what depth, on what budget. Adding a scope = adding one yml.
+# The facilitator never hard-codes a scope.
+#
+# stages  — run in this order; every name must be a folder under stages/
+# skips   — stages deliberately NOT run, so the omission is a decision on record
+# depth   — minimal | light | standard | deep
+name: security-patch
+description: "Respond to a CVE or a disclosed vulnerability."
+stages: [what, how, build, watch]
+skips: [plan]
+depth: minimal
+default_budget_usd: 10
+# gates  — who closes each stage's gate: `human` waits for `tldrx approve`,
+#           `auto` lets the facilitator close it when the five spec §5 conditions
+#           hold (checks pass, no open question, spend within ceiling, the stage
+#           did not fail, claim-sources clean). Every stage still ENDS at a gate;
+#           this only says who signs it. A stage not named here is `human`.
+gates: {what: auto, how: auto, build: human, watch: human}
+changes:
+  - "What and How are compressed into one pass: CVE -> affected surface, via the code map."
+  - "Build = patch. Watch = verify the surface is actually gone, not that the version string changed."

package/workflows/spike.yml

@@ -0,0 +1,23 @@
+# schema: draft
+# A scope is a workflow preset (concept v0.1 addendum). It biases the facilitator:
+# which stages run, at what depth, on what budget. Adding a scope = adding one yml.
+# The facilitator never hard-codes a scope.
+#
+# stages  — run in this order; every name must be a folder under stages/
+# skips   — stages deliberately NOT run, so the omission is a decision on record
+# depth   — minimal | light | standard | deep
+name: spike
+description: "Answer one question. Time-boxed and budget-boxed."
+stages: [what, how]
+skips: [plan, build, watch]
+depth: light
+default_budget_usd: 6
+# gates  — who closes each stage's gate: `human` waits for `tldrx approve`,
+#           `auto` lets the facilitator close it when the five spec §5 conditions
+#           hold (checks pass, no open question, spend within ceiling, the stage
+#           did not fail, claim-sources clean). Every stage still ENDS at a gate;
+#           this only says who signs it. A stage not named here is `human`.
+gates: {what: auto, how: human}
+changes:
+  - "Output is a decision memo, not code. Any code written is thrown away."
+  - "The budget ceiling is the point. When it is spent, you write up what you know."

package/workflows/upgrade.yml

@@ -0,0 +1,23 @@
+# schema: draft
+# A scope is a workflow preset (concept v0.1 addendum). It biases the facilitator:
+# which stages run, at what depth, on what budget. Adding a scope = adding one yml.
+# The facilitator never hard-codes a scope.
+#
+# stages  — run in this order; every name must be a folder under stages/
+# skips   — stages deliberately NOT run, so the omission is a decision on record
+# depth   — minimal | light | standard | deep
+name: upgrade
+description: "Bump one dependency. The automatable subset of a migration."
+stages: [what, plan, build, watch]
+skips: [how]
+depth: light
+default_budget_usd: 8
+# gates  — who closes each stage's gate: `human` waits for `tldrx approve`,
+#           `auto` lets the facilitator close it when the five spec §5 conditions
+#           hold (checks pass, no open question, spend within ceiling, the stage
+#           did not fail, claim-sources clean). Every stage still ENDS at a gate;
+#           this only says who signs it. A stage not named here is `human`.
+gates: {what: auto, plan: auto, build: auto, watch: human}
+changes:
+  - "How is skipped: the design is the vendor changelog. Cite it."
+  - "What = the breaking-change list for the exact version range being crossed."