[verified] feat: pin native protobuf and gRPC generation

Derive the recipe's runtime_version axis from the DGR-027 lock manifest
(exact upstream commit + ordered patch-stack byte digest) in new
meshnet_node.runtime_pin, failing closed on any lock/series/SHA256SUMS/
patch disagreement, and enforce pin discipline on runtime_version in both
the node and tracker identity implementations.

Also repair pre-existing backlog consistency: add missing DGR-022/DGR-027
completionNotes, regenerate the DGR-022/025/027 issue projections, and
relocate three pre-DGR legacy GLM issue files to issues/legacy/. Mark
DGR-025 passes=true with evidence at evidence/DGR-025/README.md.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.agents/skills/ask-matt/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ask-matt
-description: Ask which skill or flow fits your situation. A router over the user-invoked skills in this repo.
+description: Ask which skill or flow fits your situation. A router over the skills in this repo.
 disable-model-invocation: true
 ---
 
@@ -8,26 +8,28 @@ disable-model-invocation: true
 
 You don't remember every skill, so ask.
 
-A **flow** is a path through the skills. Most paths run along one **main flow**, and two **on-ramps** merge onto it. Everything else is standalone.
+A **flow** is a path through the skills. Most paths run along one **main flow**, and two **on-ramps** merge onto it. Everything else is standalone, or a vocabulary layer that runs underneath.
 
 ## The main flow: idea → ship
 
 The route most work travels. You have an idea and want it built.
 
-1. **`/grill-with-docs`** — sharpen the idea by interview. Start here when you **have a codebase**: it's stateful, retaining what it learns in `CONTEXT.md` and ADRs. (No codebase? Use `/grill-me` — see Standalone.)
+1. **`/grill-with-docs`** — sharpen the idea by interview. Start here when you **have a codebase**: it's stateful, retaining what it learns in `CONTEXT.md` and ADRs. (No codebase? Use `/grill-me` — see Standalone. Both run the same `/grilling` primitive; `grill-with-docs` is the one that leaves a paper trail.)
 2. **Branch — can you settle every question in conversation?** If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by **`/handoff`** in both directions (see Crossing sessions):
    - **`/handoff`** out, then open a fresh session against that file,
    - **`/prototype`** to answer the question with throwaway code,
    - **`/handoff`** back what you learned, and reference it from the original idea thread.
 3. **Branch — is this a multi-session build?**
-   - **Yes** → **`/to-prd`** (turn the thread into a PRD) → **`/to-issues`** (split the PRD into independently-grabbable issues). Because the issues are independent, **clear context between each one**: start a fresh session per issue and kick off **`/implement`** by passing it the PRD and the single issue to work on.
+   - **Yes** → **`/to-spec`** (turn the thread into a spec), then **`/to-tickets`** to split it into tracer-bullet tickets, each declaring its **blocking edges**. On a local tracker that's one file per ticket under `.scratch/<feature>/issues/`, worked blockers-first by hand; on a real tracker the edges become native blocking links, so any ticket whose blockers are done can be grabbed — kick off **`/implement`** per ticket, **clearing context between each one**.
    - **No** → **`/implement`** right here, in the same context window.
 
+   Either way, **`/implement`** builds each issue by driving **`/tdd`** internally — one red-green slice at a time — then closes out by running **`/code-review`**, a two-axis review (Standards + Spec) of the diff, before committing. Reach for **`/tdd`** on its own when you just want to build a concrete behaviour test-first without a full spec, and **`/code-review`** on its own whenever you want to review a branch or PR against a fixed point.
+
 ### Context hygiene
 
-Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-issues` — so the grilling, PRD, and issues all build on the same thinking. Each `/implement` then starts fresh, working from the issue.
+Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-tickets` — so the grilling, spec, and tickets all build on the same thinking. Each `/implement` then starts fresh, working from the ticket.
 
-The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~120k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-issues`, don't push on degraded — `/handoff` and continue in a fresh thread.
+The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~120k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-tickets`, don't push on degraded — `/handoff` and continue in a fresh thread.
 
 ## On-ramps
 
@@ -35,13 +37,26 @@ A starting situation that generates work, then merges onto the main flow.
 
 - **Bugs and requests piling up** → **`/triage`**. It moves issues through triage roles and produces agent-ready issues, which **`/implement`** later picks up.
 
-  Triage is only for issues **you didn't create** — bug reports, incoming feature requests, anything that arrives raw. Issues that `/to-issues` produced are already agent-ready, so **don't triage them**.
+  Triage is only for issues **you didn't create** — bug reports, incoming feature requests, anything that arrives raw. Tickets that `/to-tickets` produced are already agent-ready, so **don't triage them**.
+
+- **Something's broken** → **`/diagnosing-bugs`**. For the hard ones: the bug that resists a first glance, the intermittent flake, the regression that crept in between two known-good states. It refuses to theorise until it has a **tight feedback loop** — one command that already goes red on *this* bug — then fixes with a regression test. Its post-mortem hands off to **`/improve-codebase-architecture`** when the real finding is that there's no good seam to lock the bug down.
+
+- **A huge, foggy effort — a greenfield project or a huge feature build, too big for one session** → **`/wayfinder`**, the most cognitively demanding flow here. When the way from here to the destination isn't visible yet, it charts a **shared map** of **decision tickets** on the issue tracker and resolves them one at a time — producing **decisions, not deliverables** — until the fog is pushed back and the way is clear. Where **`/grill-with-docs`** sharpens an idea you can hold in one session, wayfinder is for the idea you can't — and it's slower and denser, so save it for exactly that, never a well-scoped feature.
+
+  When the map clears, **it hands off, it doesn't build**: merge onto the main flow at **`/to-spec`**, which collapses the map's linked decisions into a buildable plan, then `/to-tickets` and `/implement` as usual. Looping the map straight into `/implement` skips that collapse and throws the linked detail away — go straight to `/implement` only when the effort turned out genuinely small.
 
 ## Codebase health
 
 Not feature work — upkeep.
 
-- **`/improve-codebase-architecture`** — run whenever you have a spare moment to keep the codebase good for agents to operate in. It surfaces deepening opportunities; picking one _generates an idea_ you can take into the main flow at `/grill-with-docs`.
+- **`/improve-codebase-architecture`** — run whenever you have a spare moment to keep the codebase good for agents to operate in. It surfaces **deepening opportunities**; picking one _generates an idea_ you can take into the main flow at `/grill-with-docs`. It's the survey that finds the candidates; **`/codebase-design`** (below) is the bench you design the chosen one on.
+
+## Vocabulary underneath
+
+Two model-invoked references that run *beneath* the other skills — each the single source of truth for its vocabulary. Reach for them directly when the **words**, not the process, are the problem; or let the skills above pull them in.
+
+- **`/domain-modeling`** — sharpen the project's *domain* language: challenge a fuzzy term, resolve an overloaded word ("account" doing three jobs), record a hard-to-reverse decision as an ADR. It's the active discipline `/grill-with-docs` drives to keep `CONTEXT.md` a clean glossary.
+- **`/codebase-design`** — the deep-module vocabulary (module, interface, depth, seam, adapter, leverage, locality) for designing a module's *shape*: a lot of behaviour behind a small interface at a clean seam. `/tdd` and `/improve-codebase-architecture` both speak it.
 
 ## Crossing sessions
 
@@ -53,6 +68,8 @@ Not feature work — upkeep.
 Off the main flow entirely.
 
 - **`/grill-me`** — the same relentless interview as `/grill-with-docs`, but for when you have **no codebase**. Stateless: it saves nothing locally, builds no `CONTEXT.md`. Reach for it to sharpen any plan or design that doesn't live in a repo.
+- **`/prototype`** — a small, throwaway program that answers one design question: does this state model feel right, or what should this UI look like. Throwaway from day one — keep the answer, delete the code. It's the detour in step 2 of the main flow, but reach for it any time a design question is hard to settle on paper.
+- **`/research`** — delegate reading legwork to a **background agent**: it investigates a question against **primary sources**, then leaves a cited Markdown file in the repo. Keep working while it reads. The file it produces is something to take *into* the main flow at `/grill-with-docs` — research feeds the thinking, it doesn't replace it.
 - **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace.
 - **`/writing-great-skills`** — reference for writing and editing skills well.
 

.agents/skills/ask-matt/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Ask Matt"
+  short_description: "Find the right skill or workflow"
+policy:
+  allow_implicit_invocation: false

.agents/skills/grilling/SKILL.md

@@ -1,10 +1,12 @@
 ---
 name: grilling
-description: Interview the user relentlessly about a plan or design. Use when the user wants to stress-test a plan before building, or uses any 'grill' trigger phrases.
+description: Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.
 ---
 
-Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+Interview me relentlessly about every aspect of this until we reach a shared understanding. Walk down each branch of the decision tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
 
 Ask the questions one at a time, waiting for feedback on each question before continuing. Asking multiple questions at once is bewildering.
 
-If a question can be answered by exploring the codebase, explore the codebase instead.
+If a *fact* can be found by exploring the environment (filesystem, tools, etc.), look it up rather than asking me. The *decisions*, though, are mine — put each one to me and wait for my answer.
+
+Do not act on it until I confirm we have reached a shared understanding.

.agents/skills/grilling/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Grilling"
+  short_description: "Stress-test thinking one question at a time"

.agents/skills/handoff/SKILL.md

@@ -9,7 +9,7 @@ Write a handoff document summarising the current conversation so a fresh agent c
 
 Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
 
-Do not duplicate content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
 
 Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
 

.agents/skills/handoff/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Handoff"
+  short_description: "Compact a conversation into a handoff"
+policy:
+  allow_implicit_invocation: false

.agents/skills/implement/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: implement
-description: "Implement a piece of work based on a PRD or set of issues."
+description: "Implement a piece of work based on a spec or set of tickets."
 disable-model-invocation: true
 ---
 
-Implement the work described by the user in the PRD or issues.
+Implement the work described by the user in the spec or tickets.
 
 Use /tdd where possible, at pre-agreed seams.
 
 Run typechecking regularly, single test files regularly, and the full test suite once at the end.
 
-Once done, use /review to review the work.
+Once done, use /code-review to review the work.
 
 Commit your work to the current branch.

.agents/skills/implement/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Implement"
+  short_description: "Build work from a spec or tickets"
+policy:
+  allow_implicit_invocation: false

.agents/skills/improve-codebase-architecture/SKILL.md

@@ -17,6 +17,11 @@ This command is _informed_ by the project's domain model and built on a shared d
 
 ### 1. Explore
 
+**Scope before you scan — YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide *where* to look before you look:
+
+- If the user named a direction — a module, a subsystem, a pain point — take it, and skip the inference below.
+- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots — the files and areas that keep coming up — and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.
+
 Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
 
 Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
@@ -56,7 +61,7 @@ Do NOT propose interfaces yet. After the file is written, ask the user: "Which o
 
 ### 3. Grilling loop
 
-Once the user picks a candidate, run the `/grilling` skill to walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+Once the user picks a candidate, run the `/grilling` skill to walk the decision tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
 
 Side effects happen inline as decisions crystallize — run the `/domain-modeling` skill to keep the domain model current as you go:
 

.agents/skills/improve-codebase-architecture/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Improve Codebase Architecture"
+  short_description: "Find and grill architecture improvements"
+policy:
+  allow_implicit_invocation: false

.agents/skills/prototype/LOGIC.md

@@ -36,7 +36,7 @@ The right shape depends on the question:
 
 Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a TUI. Keep it pure: no I/O, no terminal code, no `console.log` for control flow. The TUI imports it and calls into it; nothing flows the other direction.
 
-This is what makes the prototype useful past its own lifetime. When the question's been answered, the validated reducer / machine / function set can be lifted into the real module — the TUI shell gets deleted.
+This is what makes the prototype useful past its own lifetime: when the question's been answered, the validated reducer / machine / function set can be lifted into the real module on its own.
 
 ### 4. Build the smallest TUI that exposes the state
 
@@ -66,9 +66,9 @@ If the host project has no task runner, just put the command at the top of the p
 
 Give the user the run command. They'll drive it themselves; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different" — those are the bugs in the _idea_, which is the whole point. If they want new actions added, add them. Prototypes evolve.
 
-### 7. Capture the answer
+### 7. Capture the answer and the prototype
 
-When the prototype has done its job, the answer to the question is the only thing worth keeping. If the user is around, ask what it taught them. If not, leave a `NOTES.md` next to the prototype so the answer can be filled in (or filled in by you, if you've watched the session) before the prototype gets deleted.
+Once the prototype has answered its question, capture the answer, then capture the prototype the way the [SKILL](SKILL.md) describes. The logic-specific mapping: the validated reducer / machine / function set lifts into the real module (the decision, absorbed); the TUI shell rides along to the throwaway branch that keeps the prototype as a primary source.
 
 ## Anti-patterns
 

.agents/skills/prototype/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: prototype
-description: Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.
-disable-model-invocation: true
+description: Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
 ---
 
 # Prototype
@@ -22,10 +21,6 @@ The two branches produce very different artifacts — getting this wrong wastes
 1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
 2. **One command to run.** Whatever the project's existing task runner supports — `pnpm <name>`, `python <path>`, `bun <path>`, etc. The user must be able to start it without thinking.
 3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE — wipe me" name.
-4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast and then delete it.
+4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast.
 5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
-6. **Delete or absorb when done.** When the prototype has answered its question, either delete it or fold the validated decision into the real code — don't leave it rotting in the repo.
-
-## When done
-
-The _answer_ is the only thing worth keeping from a prototype. Capture it somewhere durable (commit message, ADR, issue, or a `NOTES.md` next to the prototype) along with the question it was answering. If the user is around, that capture is a quick conversation; if not, leave the placeholder so they (or you, on the next pass) can fill in the verdict before deleting the prototype.
+6. **Capture it when done.** Fold any validated decision into the real code, then capture the prototype itself as a **primary source**: commit it to a throwaway branch, out of main, and leave a context pointer to that branch on the implementation issue. Capture the answer too — the verdict and the question it settled — in the issue or a commit. The main branch keeps only the validated decision.

.agents/skills/prototype/UI.md

@@ -97,12 +97,12 @@ Surface the URL (and the `?variant=` keys). The user will flip through whenever
 
 ### 6. Capture the answer and clean up
 
-Once a variant has won, write down which one and why (commit message, ADR, issue, or a `NOTES.md` next to the prototype if running AFK and the user hasn't responded yet). Then:
+Once a variant has won, capture the answer — which variant and why — then capture the prototype the way the [SKILL](SKILL.md) describes. Fold the winner into the real code and move the rest onto the throwaway branch, not into main:
 
-- **Sub-shape A** — delete the losing variants and the switcher; fold the winner into the existing page.
-- **Sub-shape B** — promote the winning variant to a real route, delete the throwaway route and the switcher.
+- **Sub-shape A** — fold the winner into the existing page; drop the losing variants and the switcher from main.
+- **Sub-shape B** — promote the winning variant to a real route; drop the throwaway route and the switcher from main.
 
-Don't leave variant components or the switcher lying around. They rot fast and confuse the next reader.
+The full set of variants is the primary source, so it lands on the throwaway branch, not the bin — variant components and the switcher left in the main branch rot fast and confuse the next reader.
 
 ## Anti-patterns
 

.agents/skills/prototype/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Prototype"
+  short_description: "Prototype to answer a design question"

.agents/skills/setup-matt-pocock-skills/SKILL.md

@@ -26,16 +26,18 @@ Look at the current repo to understand its starting state. Read whatever exists;
 - `docs/adr/` and any `src/*/docs/adr/` directories
 - `docs/agents/` — does this skill's prior output already exist?
 - `.scratch/` — sign that a local-markdown issue tracker convention is already in use
+- Is the `triage` skill installed? (a `triage` skill folder alongside this one, or `triage` in your available skills.) This decides whether Section B runs at all.
+- Monorepo signals — a `pnpm-workspace.yaml`, a `workspaces` field in `package.json`, or a populated `packages/*` with its own `src/`. Present only in a genuinely large multi-package repo; their absence means single-context, which is almost every repo.
 
 ### 2. Present findings and ask
 
-Summarise what's present and what's missing. Then walk the user through the three decisions **one at a time** — present a section, get the user's answer, then move to the next. Don't dump all three at once.
+Summarise what's present and what's missing. Then take the sections in order — one section, one answer, then the next.
 
-Assume the user does not know what these terms mean. Each section starts with a short explainer (what it is, why these skills need it, what changes if they pick differently). Then show the choices and the default.
+Lead each section with the recommended answer so the user can accept it in a word. Give a one-line explainer only when the choice genuinely branches; skip the section entirely when exploration already settled it (Section B when `triage` isn't installed, Section C when there's no monorepo).
 
 **Section A — Issue tracker.**
 
-> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-issues`, `triage`, `to-prd`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
+> Explainer: The "issue tracker" is where issues live for this repo. Skills like `to-tickets`, `triage`, `to-spec`, and `qa` read from and write to it — they need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
 
 Default posture: these skills were designed for GitHub. If a `git remote` points at GitHub, propose that. If a `git remote` points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer:
 
@@ -44,41 +46,26 @@ Default posture: these skills were designed for GitHub. If a `git remote` points
 - **Local markdown** — issues live as files under `.scratch/<feature>/` in this repo (good for solo projects or repos without a remote)
 - **Other** (Jira, Linear, etc.) — ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose
 
-If — and only if — the user picked **GitHub** or **GitLab**, ask one follow-up:
+Record the choice in `docs/agents/issue-tracker.md`. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted **off** — leave it off and don't raise it; a user who wants external PRs in the triage queue can flip the flag in the file later.
 
-> Explainer: Open-source repos often receive feature requests as pull requests, not just issues — a PR is an issue with attached code. If you turn this on, `/triage` pulls *external* PRs into the same queue and runs them through the same labels and states as issues (collaborators' in-flight PRs are left alone). Leave it off if PRs aren't a request surface for you.
+**Section B — Triage label vocabulary.** Skip this section entirely if the `triage` skill isn't installed (exploration told you) — an uninstalled skill needs no labels.
 
-- **PRs as a request surface** — yes / no (default: no). Record the answer in `docs/agents/issue-tracker.md`. For local-markdown and other trackers, skip this question — there are no PRs.
+If it is installed, ask exactly one question:
 
-**Section B — Triage label vocabulary.**
+> Do you want to keep the default triage labels? (recommended: **yes**)
 
-> Explainer: When the `triage` skill processes an incoming issue, it moves it through a state machine — needs evaluation, waiting on reporter, ready for an AFK agent to pick up, ready for a human, or won't fix. To do that, it needs to apply labels (or the equivalent in your issue tracker) that match strings *you've actually configured*. If your repo already uses different label names (e.g. `bug:triage` instead of `needs-triage`), map them here so the skill applies the right ones instead of creating duplicates.
+The defaults are the five canonical roles, each label string equal to its name: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. On **yes**, write them as-is. Only if the user says no — usually because their tracker already uses other names (e.g. `bug:triage` for `needs-triage`) — collect the overrides so `triage` applies existing labels instead of creating duplicates.
 
-The five canonical roles:
+**Section C — Domain docs.** Default to **single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. This fits almost every repo; write it without asking.
 
-- `needs-triage` — maintainer needs to evaluate
-- `needs-info` — waiting on reporter
-- `ready-for-agent` — fully specified, AFK-ready (an agent can pick it up with no human context)
-- `ready-for-human` — needs human implementation
-- `wontfix` — will not be actioned
-
-Default: each role's string equals its name. Ask the user if they want to override any. If their issue tracker has no existing labels, the defaults are fine.
-
-**Section C — Domain docs.**
-
-> Explainer: Some skills (`improve-codebase-architecture`, `diagnosing-bugs`, `tdd`) read a `CONTEXT.md` file to learn the project's domain language, and `docs/adr/` for past architectural decisions. They need to know whether the repo has one global context or multiple (e.g. a monorepo with separate frontend/backend contexts) so they look in the right place.
-
-Confirm the layout:
-
-- **Single-context** — one `CONTEXT.md` + `docs/adr/` at the repo root. Most repos are this.
-- **Multi-context** — `CONTEXT-MAP.md` at the root pointing to per-context `CONTEXT.md` files (typically a monorepo).
+Offer **multi-context** — a root `CONTEXT-MAP.md` pointing to per-context `CONTEXT.md` files — only when exploration found monorepo signals. Then confirm which layout they want.
 
 ### 3. Confirm and edit
 
 Show the user a draft of:
 
 - The `## Agent skills` block to add to whichever of `CLAUDE.md` / `AGENTS.md` is being edited (see step 4 for selection rules)
-- The contents of `docs/agents/issue-tracker.md`, `docs/agents/triage-labels.md`, `docs/agents/domain.md`
+- The contents of `docs/agents/issue-tracker.md`, `docs/agents/domain.md`, and `docs/agents/triage-labels.md` (the last only when `triage` is installed)
 
 Let them edit before writing.
 
@@ -101,7 +88,7 @@ The block:
 
 ### Issue tracker
 
-[one-line summary of where issues are tracked, plus whether external PRs are a triage surface]. See `docs/agents/issue-tracker.md`.
+[one-line summary of where issues are tracked]. See `docs/agents/issue-tracker.md`.
 
 ### Triage labels
 
@@ -112,12 +99,14 @@ The block:
 [one-line summary of layout — "single-context" or "multi-context"]. See `docs/agents/domain.md`.
 ```
 
-Then write the three docs files using the seed templates in this skill folder as a starting point:
+Include the `### Triage labels` sub-block, and write `docs/agents/triage-labels.md`, only when `triage` is installed and Section B ran. When it isn't, both are omitted.
+
+Then write the docs files using the seed templates in this skill folder as a starting point:
 
 - [issue-tracker-github.md](./issue-tracker-github.md) — GitHub issue tracker
 - [issue-tracker-gitlab.md](./issue-tracker-gitlab.md) — GitLab issue tracker
 - [issue-tracker-local.md](./issue-tracker-local.md) — local-markdown issue tracker
-- [triage-labels.md](./triage-labels.md) — label mapping
+- [triage-labels.md](./triage-labels.md) — label mapping (only if `triage` is installed)
 - [domain.md](./domain.md) — domain doc consumer rules + layout
 
 For "other" issue trackers, write `docs/agents/issue-tracker.md` from scratch using the user's description.

.agents/skills/setup-matt-pocock-skills/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Setup Matt Pocock Skills"
+  short_description: "Configure a repo for the skills"
+policy:
+  allow_implicit_invocation: false

.agents/skills/setup-matt-pocock-skills/issue-tracker-github.md

@@ -32,3 +32,14 @@ Create a GitHub issue.
 ## When a skill says "fetch the relevant ticket"
 
 Run `gh issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (`gh api` on the sub-issues endpoint). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies** — the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only — the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit <n> --add-assignee @me` — the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

.agents/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md

@@ -33,3 +33,14 @@ Create a GitLab issue.
 ## When a skill says "fetch the relevant ticket"
 
 Run `glab issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `glab issue create --label wayfinder:map`. (On GitLab tiers with native epics, an epic may hold the map instead; a labelled issue works everywhere.)
+- **Child ticket**: an issue carrying `Part of #<map>` at the top of its description and labels `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitLab's **native blocking link** — the canonical, UI-visible representation. Add it with the `/blocked_by #<n>` quick action, posted as a note (`glab issue note <child> --message "/blocked_by #<blocker>"`). Native blocking links are a Premium/Ultimate feature; on the free tier (or where unavailable) fall back to a `Blocked by: #<n>, #<n>` line at the top of the description. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: `glab issue list -F json` scoped to the map's children, drop any with an open blocker — a native `blocked_by` link to an open issue (`glab api projects/:id/issues/:iid/links`), or an open issue in the `Blocked by` line — or an assignee; first in map order wins.
+- **Claim**: `glab issue update <n> --assignee @me` — the session's first write.
+- **Resolve**: `glab issue note <n> --message "<answer>"`, then `glab issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md

@@ -1,12 +1,12 @@
 # Issue tracker: Local Markdown
 
-Issues and PRDs for this repo live as markdown files in `.scratch/`.
+Issues and specs (you may know a spec as a PRD) for this repo live as markdown files in `.scratch/`.
 
 ## Conventions
 
 - One feature per directory: `.scratch/<feature-slug>/`
-- The PRD is `.scratch/<feature-slug>/PRD.md`
-- Implementation issues are `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`
+- The spec is `.scratch/<feature-slug>/spec.md`
+- Implementation issues are one file per ticket at `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` — never a single combined tickets file
 - Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
 - Comments and conversation history append to the bottom of the file under a `## Comments` heading
 
@@ -17,3 +17,14 @@ Create a new file under `.scratch/<feature-slug>/` (creating the directory if ne
 ## When a skill says "fetch the relevant ticket"
 
 Read the file at the referenced path. The user will normally pass the path or the issue number directly.
+
+## Wayfinding operations
+
+Used by `/wayfinder`. The **map** is a file with one **child** file per ticket.
+
+- **Map**: `.scratch/<effort>/map.md` — the Notes / Decisions-so-far / Fog body.
+- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`research`/`prototype`/`grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
+- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
+- **Frontier**: scan `.scratch/<effort>/issues/` for files that are open, unblocked, and unclaimed; first by number wins.
+- **Claim**: set `Status: claimed` and save before any work.
+- **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer (gist + link) to the map's Decisions-so-far in `map.md`.

.agents/skills/setup-ts-deep-modules/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: setup-ts-deep-modules
+description: Wire dependency-cruiser into a TypeScript repo so each package is a deep module — implementation hidden in subfolders, reachable only through its entry-point files. User-invoked.
+disable-model-invocation: true
+---
+
+# Setup TS Deep Modules
+
+Make every package in this repo a **deep module**: a lot of behaviour behind a small interface. A package's public surface is its **entry points** — the files at the package root — and everything in its subfolders is hidden. This skill installs [dependency-cruiser](https://github.com/sverweij/dependency-cruiser) and the rules that make the entry points the only way in, then proves the rules bite.
+
+For the vocabulary (deep module, interface, seam, depth), run the `/codebase-design` skill — use its language throughout.
+
+## The shape this enforces
+
+```
+src/packages/
+  <name>/
+    index.ts        ← an entry point (public). Import this from outside.
+    client.ts       ← another entry point. Packages may expose SEVERAL.
+    lib/            ← implementation: hidden from outside, free to import each other.
+    tests/          ← co-located tests + fixtures (a subfolder, so private).
+```
+
+The public surface is the package's **root files** — not one designated `index.ts`. By convention implementation lives in `lib/` and tests in `tests/`, giving every package the same two-folder shape. The rule itself is general, though: *anything* in *any* subfolder is private, so you never extend the config to add a folder.
+
+Four rules, all `error`:
+
+1. **Entry-point boundary** — code outside a package (app code or another package) may import only that package's entry points (its root files), never anything in its subfolders.
+2. **Intra-package freedom** — a package's own files import each other freely.
+3. **Tests through the entry points** — files under `<pkg>/tests/` may import any package's entry points and their own `tests/` fixtures, but never any package's subfolder internals (not even their own). Integration tests across packages are fine; deep imports are not.
+4. **No cycles** — no dependency cycles.
+
+**Entry points, not a barrel.** Because the public surface is *every* root file, a package can expose several small entry points (`index.ts`, `client.ts`, `server.ts`) instead of funnelling everything through one giant `index.ts`. Barrel files that re-export a whole subtree are discouraged — keep entry points small and hide implementation in subfolders.
+
+Layering (which packages may depend on which) is a *different* concern and is left as a commented stub in the config for this repo to fill in.
+
+## Steps
+
+### 1. Detect the environment
+
+- **Package manager** — `pnpm-lock.yaml` → pnpm, `yarn.lock` → yarn, `bun.lockb` → bun, else npm. Use it for every command below (`pnpm`/`yarn`/`npm run`/`bunx`).
+- **Packages root** — if `src/` exists use `src/packages`, else `packages`. Confirm the choice with the user if the repo already has a different obvious convention.
+- **Existing config** — check for a `.dependency-cruiser.*` file. If one exists, do **not** overwrite it: merge the four rules and the options in, and tell the user what you added.
+
+**Done when:** package manager, packages root, and existing-config status are all known.
+
+### 2. Install dependency-cruiser
+
+Install `dependency-cruiser` as a devDependency with the detected package manager.
+
+**Done when:** `dependency-cruiser` is in `devDependencies`.
+
+### 3. Write the config
+
+Copy [`dependency-cruiser.config.cjs`](./dependency-cruiser.config.cjs) to the repo root as `.dependency-cruiser.cjs`. Set `PACKAGES_ROOT` to the root detected in step 1. The rules are path-depth based and extension-agnostic, so nothing else needs adapting.
+
+**Done when:** `.dependency-cruiser.cjs` exists with the correct `PACKAGES_ROOT`, and the four forbidden rules are present.
+
+### 4. Wire it into the checks
+
+- Add a `lint:boundaries` script: `depcruise <packages-root>` (or `depcruise src`).
+- Fold it into the repo's umbrella check command — the one that already runs typecheck (e.g. a `check` / `ci` / `validate` script). Do **not** touch `tsconfig` or add path aliases.
+- If there is no umbrella script, add `lint:boundaries` and tell the user to include it in CI.
+
+**Done when:** `lint:boundaries` exists and runs as part of the same command as typecheck.
+
+### 5. Scaffold the example package
+
+Create a committed `<packages-root>/example/` as a copy-me template:
+
+- `index.ts` — an entry point. Export one function that delegates to an internal file (so the package is visibly *deep*, not a pass-through).
+- `lib/impl.ts` — an internal file in a **subfolder**, imported by `index.ts`, not reachable from outside.
+- `tests/example.test.ts` — imports **only** `../index` (an entry point), and asserts against the public function.
+
+Tell the user this is a starter template to copy or delete.
+
+**Done when:** the example package exists, exposes its behaviour through a root entry point, and hides `impl` in a subfolder.
+
+### 6. Prove the rules bite
+
+This is the completion criterion for the whole skill — a config that doesn't fail on a violation is worthless.
+
+1. Run `lint:boundaries`. It must **pass** on the clean example.
+2. Temporarily add a deep import to `tests/example.test.ts` (e.g. `import { thing } from "../lib/impl"`). Run `lint:boundaries` again — it must **fail** with `tests-through-entrypoints`.
+3. Revert the deep import. Run once more — it must **pass**.
+
+**Done when:** you have observed a pass, then a fail on the deep import, then a pass again. If step 2 does not fail, the rules are not wired correctly — fix before finishing.
+
+### 7. Document the convention
+
+Write a `README.md` **in the packages folder** (`<packages-root>/README.md`) — next to the packages it governs — covering: the `src/packages/<name>/` layout (entry points at the root, `lib/` for implementation, `tests/` for tests), "import only through a package's entry points (its root files)", and how to run `lint:boundaries`. **Discourage barrel files** explicitly — expose several small entry points instead of re-exporting a whole subtree through one index. Keep it to the copy-me snippet plus the four rules in one paragraph each.
+
+Then add a **context pointer** to it from the repo's agent-instructions file — `CLAUDE.md` if present, else `AGENTS.md` (create `AGENTS.md` if neither exists). One line is enough, e.g. `Packages are deep modules — see [src/packages/README.md](./src/packages/README.md) before adding or importing one.` This is what makes an agent discover the boundary rule instead of tripping over it.
+
+**Done when:** `<packages-root>/README.md` exists and discourages barrels, and the repo's `CLAUDE.md`/`AGENTS.md` links to it.
+
+## Notes
+
+- The config's `$1` back-references (dependency-cruiser's group matching) are what let a package reach its own internals while outsiders can't — don't flatten them into separate per-package rules.
+- Public vs private is decided by **depth**: a package's root files are entry points; anything in a subfolder is private. The conventional subfolders are `lib/` (implementation) and `tests/`, but the rule doesn't hardcode them — any subfolder is private, so a new folder never needs a config change. Adding an entry point is just adding a root file — no barrel.
+- Packages are **flat**: one tier of immediate children under the root. A package's internals may nest as deep as you like; a package may not contain another package.
+- Use `.cjs` (not `.js`) so the config's `module.exports` works even in `"type": "module"` repos.

.agents/skills/setup-ts-deep-modules/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Setup TS Deep Modules"
+  short_description: "Enforce deep TypeScript modules"
+policy:
+  allow_implicit_invocation: false

.agents/skills/setup-ts-deep-modules/dependency-cruiser.config.cjs

@@ -0,0 +1,95 @@
+// @ts-check
+// Deep-module enforcement for dependency-cruiser.
+//
+// Each package under the packages root is a DEEP MODULE: a lot of behaviour
+// behind a small interface. A package's PUBLIC SURFACE is its ENTRY POINTS —
+// the files at the package root. Implementation lives in SUBFOLDERS and is
+// private — by convention `lib/` for implementation and `tests/` for tests,
+// though any subfolder is private. A package may expose several small entry
+// points (index.ts, client.ts, server.ts, …) — prefer that over one giant
+// barrel index.
+//
+// The only thing you should ever need to edit here is PACKAGES_ROOT.
+
+/** Where packages live. One immediate child dir per package (flat, no nesting). */
+const PACKAGES_ROOT = "src/packages";
+
+// --- derived patterns (no need to edit) -------------------------------------
+const R = PACKAGES_ROOT;
+/**
+ * A package's private internals: anything nested inside a package subfolder.
+ * The package's root files are its entry points and are NOT matched here —
+ * they stay importable from outside.
+ */
+const PACKAGE_INTERNALS = `^${R}/[^/]+/[^/]+/`;
+
+/** @type {import('dependency-cruiser').IConfiguration} */
+module.exports = {
+  forbidden: [
+    {
+      name: "entrypoint-boundary-from-app",
+      comment:
+        "App/root code may import a package's entry points (its root files), but nothing inside its subfolders.",
+      severity: "error",
+      from: { pathNot: `^${R}/` }, // importer is NOT inside any package
+      to: { path: PACKAGE_INTERNALS },
+    },
+    {
+      name: "entrypoint-boundary-across-packages",
+      comment:
+        "A package's own files import each other freely, but may reach OTHER packages only through their entry points — never their internals.",
+      severity: "error",
+      // importer is inside a package ($1), but is not a test file
+      from: { path: `^${R}/([^/]+)/`, pathNot: `^${R}/[^/]+/tests/` },
+      to: {
+        path: PACKAGE_INTERNALS,
+        pathNot: `^${R}/$1/`, // same package → intra-package freedom
+      },
+    },
+    {
+      name: "tests-through-entrypoints",
+      comment:
+        "A package's tests exercise it through its entry points like everyone else: they may import any package's entry points and their own tests/ fixtures, but never any package's internals — not even their own.",
+      severity: "error",
+      from: { path: `^${R}/([^/]+)/tests/` }, // a test file, in package $1
+      to: {
+        path: PACKAGE_INTERNALS,
+        pathNot: `^${R}/$1/tests/`, // own tests/ fixtures → allowed
+      },
+    },
+    {
+      name: "tests-folder-is-private",
+      comment:
+        "A package's tests/ folder is reachable only from tests — nothing else may import fixtures.",
+      severity: "error",
+      from: { pathNot: `^${R}/[^/]+/tests/` }, // importer is not itself a test
+      to: { path: `^${R}/[^/]+/tests/` },
+    },
+    {
+      name: "no-circular",
+      comment: "No dependency cycles. Scope to `^${R}/` if you want to allow cycles outside packages.",
+      severity: "error",
+      from: {},
+      to: { circular: true },
+    },
+
+    // --- Layering (optional, off by default) ----------------------------------
+    // Interface-hiding controls HOW you import (through the entry points).
+    // Layering controls WHICH packages may depend on which. Add your own rules
+    // here, e.g.:
+    //
+    // {
+    //   name: "ui-may-not-depend-on-billing",
+    //   severity: "error",
+    //   from: { path: `^${R}/ui/` },
+    //   to:   { path: `^${R}/billing/` },
+    // },
+  ],
+  options: {
+    doNotFollow: { path: "node_modules" },
+    tsConfig: { fileName: "tsconfig.json" },
+    enhancedResolveOptions: {
+      extensions: [".ts", ".tsx", ".js", ".jsx", ".json"],
+    },
+  },
+};

.agents/skills/tdd/SKILL.md

@@ -5,104 +5,32 @@ description: Test-driven development. Use when the user wants to build features
 
 # Test-Driven Development
 
-## Philosophy
+TDD is the red → green loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, the anti-patterns, and the rules of the loop. Every section applies on every cycle — consult them before and during the loop, not after.
 
-**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
+When exploring the codebase, read `CONTEXT.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.
 
-**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
+## What a good test is
 
-**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
+Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't. A good test reads like a specification — "user can checkout with valid cart" tells you exactly what capability exists — and survives refactors because it doesn't care about internal structure.
 
 See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
 
-## Anti-Pattern: Horizontal Slices
+## Seams — where tests go
 
-**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code."
+A **seam** is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.
 
-This produces **crap tests**:
+**Test only at pre-agreed seams.** Before writing any test, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You can't test everything — agreeing the seams up front is how testing effort lands on the critical paths and complex logic instead of every edge case.
 
-- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
-- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
-- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine
-- You outrun your headlights, committing to test structure before understanding the implementation
+Ask: "What's the public interface, and which seams should we test?"
 
-**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
+## Anti-patterns
 
-```
-WRONG (horizontal):
-  RED:   test1, test2, test3, test4, test5
-  GREEN: impl1, impl2, impl3, impl4, impl5
+- **Implementation-coupled** — mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior hasn't changed.
+- **Tautological** — the assertion recomputes the expected value the way the code does (`expect(add(a, b)).toBe(a + b)`, a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth — a known-good literal, a worked example, the spec.
+- **Horizontal slicing** — writing all tests first, then all implementation. Bulk tests verify _imagined_ behavior: you test the _shape_ of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in **vertical slices** instead — one test → one implementation → repeat, each test a **tracer bullet** that responds to what the last cycle taught you.
 
-RIGHT (vertical):
-  RED→GREEN: test1→impl1
-  RED→GREEN: test2→impl2
-  RED→GREEN: test3→impl3
-  ...
-```
+## Rules of the loop
 
-## Workflow
-
-### 1. Planning
-
-When exploring the codebase, read `CONTEXT.md` (if it exists) so that test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.
-
-Before writing any code:
-
-- [ ] Confirm with user what interface changes are needed
-- [ ] Confirm with user which behaviors to test (prioritize)
-- [ ] Identify opportunities for deep modules (small interface, deep implementation) — run the `/codebase-design` skill for the vocabulary and the testability checks
-- [ ] List the behaviors to test (not implementation steps)
-- [ ] Get user approval on the plan
-
-Ask: "What should the public interface look like? Which behaviors are most important to test?"
-
-**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
-
-### 2. Tracer Bullet
-
-Write ONE test that confirms ONE thing about the system:
-
-```
-RED:   Write test for first behavior → test fails
-GREEN: Write minimal code to pass → test passes
-```
-
-This is your tracer bullet - proves the path works end-to-end.
-
-### 3. Incremental Loop
-
-For each remaining behavior:
-
-```
-RED:   Write next test → fails
-GREEN: Minimal code to pass → passes
-```
-
-Rules:
-
-- One test at a time
-- Only enough code to pass current test
-- Don't anticipate future tests
-- Keep tests focused on observable behavior
-
-### 4. Refactor
-
-After all tests pass, look for [refactor candidates](refactoring.md):
-
-- [ ] Extract duplication
-- [ ] Deepen modules (move complexity behind simple interfaces)
-- [ ] Apply SOLID principles where natural
-- [ ] Consider what new code reveals about existing code
-- [ ] Run tests after each refactor step
-
-**Never refactor while RED.** Get to GREEN first.
-
-## Checklist Per Cycle
-
-```
-[ ] Test describes behavior, not implementation
-[ ] Test uses public interface only
-[ ] Test would survive internal refactor
-[ ] Code is minimal for this test
-[ ] No speculative features added
-```
+- **Red before green.** Write the failing test first, then only enough code to pass it. Don't anticipate future tests or add speculative features.
+- **One slice at a time.** One seam, one test, one minimal implementation per cycle.
+- **Refactoring is not part of the loop.** It belongs to the review stage (see the `code-review` skill), not the red → green implementation cycle.

.agents/skills/tdd/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "TDD"
+  short_description: "Test-driven red-green-refactor"

.agents/skills/tdd/tests.md

@@ -59,3 +59,19 @@ test("createUser makes user retrievable", async () => {
   expect(retrieved.name).toBe("Alice");
 });
 ```
+
+**Tautological tests**: Expected value restates the implementation, so the test passes by construction.
+
+```typescript
+// BAD: Expected value is recomputed the way the code computes it
+test("calculateTotal sums line items", () => {
+  const items = [{ price: 10 }, { price: 5 }];
+  const expected = items.reduce((sum, i) => sum + i.price, 0);
+  expect(calculateTotal(items)).toBe(expected);
+});
+
+// GOOD: Expected value is an independent, known literal
+test("calculateTotal sums line items", () => {
+  expect(calculateTotal([{ price: 10 }, { price: 5 }])).toBe(15);
+});
+```

.agents/skills/to-spec/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: to-spec
+description: Turn the current conversation into a spec and publish it to the project issue tracker — no interview, just synthesis of what you've already discussed.
+disable-model-invocation: true
+---
+
+This skill takes the current conversation context and codebase understanding and produces a spec (you may know this document as a PRD). Do NOT interview the user — just synthesize what you already know.
+
+The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
+
+## Process
+
+1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching.
+
+2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.
+
+Check with the user that these seams match their expectations.
+
+3. Write the spec using the template below, then publish it to the project issue tracker. Apply the `ready-for-agent` triage label - no need for additional triage.
+
+<spec-template>
+
+## Problem Statement
+
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+
+The solution to the problem, from the user's perspective.
+
+## User Stories
+
+A LONG, numbered list of user stories. Each user story should be in the format of:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Implementation Decisions
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this spec.
+
+## Further Notes
+
+Any further notes about the feature.
+
+</spec-template>

.agents/skills/to-spec/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "To Spec"
+  short_description: "Turn a conversation into a spec"
+policy:
+  allow_implicit_invocation: false

.agents/skills/to-tickets/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: to-tickets
+description: Break a plan, spec, or the current conversation into a set of tracer-bullet tickets, each declaring its blocking edges, published to the configured tracker — edges as text in one file per ticket locally, or native blocking links on a real tracker.
+disable-model-invocation: true
+---
+
+# To Tickets
+
+Break a plan, spec, or conversation into a set of **tickets** — tracer-bullet vertical slices, each declaring the tickets that **block** it.
+
+The issue tracker and triage label vocabulary should have been provided to you — run `/setup-matt-pocock-skills` if not.
+
+## Process
+
+### 1. Gather context
+
+Work from whatever is already in the conversation context. If the user passes a reference (a spec path, an issue number or URL) as an argument, fetch it and read its full body and comments.
+
+### 2. Explore the codebase (optional)
+
+If you have not already explored the codebase, do so to understand the current state of the code. Ticket titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching.
+
+Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change."
+
+### 3. Draft vertical slices
+
+Break the work into **tracer bullet** tickets.
+
+<vertical-slice-rules>
+
+- Each slice cuts a narrow but COMPLETE path through every layer (schema, API, UI, tests) — vertical, NOT a horizontal slice of one layer
+- A completed slice is demoable or verifiable on its own
+- Each slice is sized to fit in a single fresh context window
+- Any prefactoring should be done first
+
+</vertical-slice-rules>
+
+Give each ticket its **blocking edges** — the other tickets that must complete before it can start. A ticket with no blockers can start immediately.
+
+**Wide refactors are the exception to vertical slicing.** A **wide refactor** is one mechanical change — rename a column, retype a shared symbol — whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expand–contract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket — green is promised only there.
+
+### 4. Quiz the user
+
+Present the proposed breakdown as a numbered list. For each ticket, show:
+
+- **Title**: short descriptive name
+- **Blocked by**: which other tickets (if any) must complete first
+- **What it delivers**: the end-to-end behaviour this ticket makes work
+
+Ask the user:
+
+- Does the granularity feel right? (too coarse / too fine)
+- Are the blocking edges correct — does each ticket only depend on tickets that genuinely gate it?
+- Should any tickets be merged or split further?
+
+Iterate until the user approves the breakdown.
+
+### 5. Publish the tickets to the configured tracker
+
+Publish the approved tickets. **How** depends on the tracker `/setup-matt-pocock-skills` configured — the tickets are the same either way, only the shape of the blocking edges changes:
+
+- **Local files** → write one file per ticket under `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01` in dependency order (blockers first). Each file's "Blocked by" lists the numbers/titles it depends on. Use the per-ticket file template below — one ticket per file, never a single combined file.
+- **A real issue tracker (GitHub, Linear, …)** → publish one issue per ticket in dependency order (blockers first) so each ticket's blocking edges can reference real identifiers. Use the platform's native blocking / sub-issue relationship where it has one; otherwise set each ticket's "Blocked by" to the blocking issues. Apply the `ready-for-agent` triage label unless instructed otherwise — the tickets are agent-grabbable by construction.
+
+Work the **frontier**: any ticket whose blockers are all done. For a purely linear chain that means top to bottom.
+
+Do NOT close or modify any parent issue.
+
+<local-ticket-template>
+
+# <NN> — <Ticket title>
+
+**What to build:** the end-to-end behaviour this ticket makes work, from the user's perspective — not a layer-by-layer implementation list.
+
+**Blocked by:** the numbers/titles of the tickets that gate this one, or "None — can start immediately".
+
+**Status:** ready-for-agent
+
+- [ ] Acceptance criterion 1
+- [ ] Acceptance criterion 2
+
+</local-ticket-template>
+
+<issue-template>
+
+## Parent
+
+A reference to the parent issue on the tracker (if the source was an existing issue, otherwise omit this section).
+
+## What to build
+
+The end-to-end behaviour this ticket makes work, from the user's perspective — not layer-by-layer implementation.
+
+## Acceptance criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Blocked by
+
+- A reference to each blocking ticket, or "None — can start immediately".
+
+</issue-template>
+
+In either form, avoid specific file paths or code snippets — they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts — not a working demo, just the important bits.
+
+Work the frontier one ticket at a time with `/implement`, clearing context between tickets.

.agents/skills/to-tickets/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "To Tickets"
+  short_description: "Split a plan into tracer-bullet tickets"
+policy:
+  allow_implicit_invocation: false

.agents/skills/wayfinder/SKILL.md

@@ -1,9 +1,16 @@
 ---
 name: wayfinder
-description: Plan a huge chunk of work — more than one agent session can hold — as a shared map of investigation tickets on your issue tracker, and resolve them one at a time until the way to the goal is clear.
+description: Plan a huge chunk of work — more than one agent session can hold — as a shared map of decision tickets on your issue tracker, and resolve them one at a time until the way to the destination is clear.
+disable-model-invocation: true
 ---
 
-A loose idea has arrived — too big for one agent session, and wrapped in fog: the route from here to a plan isn't visible yet. This skill charts it as a **shared map** on the repo's issue tracker, then works its tickets one at a time. The map is domain-agnostic — engineering work, course content, whatever fits the shape.
+A loose idea has arrived — too big for one agent session, and wrapped in fog: the way from here to the **destination** isn't visible yet. Wayfinding is about finding that way, not charging at the destination. This skill charts the way as a **shared map** on the repo's issue tracker, then works its **decision tickets** — questions whose resolution is a decision, not slices of a build to execute — one at a time until the route is clear.
+
+The destination varies per effort, and naming it is the first act of charting — it shapes every ticket. It might be a spec to hand off and iterate on, a decision to lock before planning starts, or a change made in place like a data-structure migration. The map is domain-agnostic — engineering work, course content, whatever fits the shape.
+
+## Plan, don't do
+
+Wayfinder is **planning** by default: each ticket resolves a decision, and the map is done when the way is clear — nothing left to decide before someone goes and does the thing. The pull to just do the work is usually the signal you've reached the edge of the map and it's time to hand off. An effort can override this in its **Notes** — carrying execution into the map itself — but absent that, produce decisions, not deliverables.
 
 ## Refer by name
 
@@ -15,13 +22,17 @@ The map is a single issue on this repo's issue tracker, labelled `wayfinder:map`
 
 The map is an **index**, not a store. It lists the decisions made and points at the tickets that hold their detail; a decision lives in exactly one place — its ticket — so the map never restates it, only gists it and links.
 
-**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** Consult `docs/agents/issue-tracker.md` (the "Wayfinding operations" section) for how _this_ repo expresses them. If that doc is absent, default to the local-markdown tracker.
+**Where the map, its child tickets, blocking, and frontier queries physically live is tracker-specific.** The issue tracker should have been provided to you — run `/setup-matt-pocock-skills` if not. Consult the tracker doc's "Wayfinding operations" section for how _this_ repo expresses them. If no tracker has been provided, default to the local-markdown tracker.
 
 ### The map body
 
 The whole map at low resolution, loaded once per session. Open tickets are **not** listed — they are open child issues, found by query.
 
 ```markdown
+## Destination
+
+<what reaching the end of this map looks like — the spec, decision, or change this effort is finding its way to. One or two lines; every session orients to it before choosing a ticket.>
+
 ## Notes
 
 <domain; skills every session should consult; standing preferences for this effort>
@@ -32,9 +43,13 @@ The whole map at low resolution, loaded once per session. Open tickets are **not
 
 - [<closed ticket title>](link) — <one-line gist of the answer>
 
-## Fog
+## Not yet specified
 
-<!-- see "Fog of war" for what belongs here -->
+<!-- see "Fog of war": in-scope fog you can't ticket yet; graduates as the frontier advances -->
+
+## Out of scope
+
+<!-- see "Out of scope": work ruled beyond the destination; closed, never graduates -->
 ```
 
 ### Tickets
@@ -57,36 +72,48 @@ The answer isn't part of the body — it's recorded on resolution (see [Work thr
 
 ## Ticket Types
 
-- **Research**: Reading documentation, third-party APIs, or local resources like knowledge bases. Creates a markdown summary as a linked asset. Use when knowledge outside the current working directory is required.
-- **Prototype**: Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /prototype skill. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
-- **Grilling**: Conversation with the agent. Uses the /grilling and /domain-modeling skills. Asks one question at a time. The default case.
-- **Task**: Literal manual work that must be done before the discussion can move forward — nothing to decide, prototype, or research. Moving data, signing up for a service, provisioning access. The agent automates it where it can; otherwise it hands the human a precise checklist. Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.
+Every ticket is either **HITL** — human in the loop, worked *with* a human who speaks for themselves — or **AFK**, driven by the agent alone. A HITL ticket only resolves through that live exchange; the agent never stands in for the human's side of it (a grilling agent that answers its own questions has broken this).
+
+- **Research** (AFK): Reading documentation, third-party APIs, or local resources like knowledge bases to surface a fact a decision waits on. Resolved by a `/research` **subagent**. Use when knowledge outside the current working directory is required.
+- **Prototype** (HITL): Raise the fidelity of the discussion by making a cheap, rough, concrete artifact to react to — an outline, a rough take, a stub, or UI/logic code via the /prototype skill. Links the prototype as an asset. Use when "how should it look" or "how should it behave" is the key question.
+- **Grilling** (HITL): Conversation via the /grilling and /domain-modeling skills, one question at a time. The default case.
+- **Task** (HITL or AFK): Manual work that must happen before a *decision* can be made — nothing to decide, prototype, or research, but the discussion is blocked until it's done. Signing up for a service so its API can be judged, provisioning access, moving data so its shape can be seen. This is the one type that *does* rather than decides — and it earns its place by unblocking a decision, not by delivering the destination. The agent drives it alone where it can (AFK); otherwise it hands the human a precise checklist (HITL). Resolved when the work is done; the answer records what was done and any resulting facts (credentials location, new URLs, row counts) later tickets depend on.
 
 ## Fog of war
 
-The map is _deliberately_ incomplete: don't chart what you can't yet see. Beyond the tickets lies fog — the dim view of decisions and investigations you can tell are coming but can't yet pin down, because they hang on questions still open. Resolving a ticket clears the fog ahead of it, graduating whatever's now specifiable into fresh tickets — one at a time, until the way to the goal is clear and no tickets remain.
+The map is _deliberately_ incomplete: don't chart what you can't yet see. Beyond the live tickets lies the **fog of war** — the dim view of decisions and investigations you can tell are coming but can't yet pin down, because they hang on questions still open. Resolving a ticket clears the fog ahead of it, graduating whatever's now specifiable into fresh tickets — one at a time, until the way to the destination is clear and no tickets remain.
 
-The map's **Fog** section is where that dim view is written down: the suspected question, the area to revisit later, the risk you're deferring. Write as loosely or as fully as the view allows; it doubles as a signpost for collaborators reading where the effort is headed.
+The map's **Not yet specified** section is where that dim view is written down: the suspected question, the area to revisit later. It's the undiscovered frontier _toward_ the destination — everything here is in scope, just not sharp enough to ticket. Write as loosely or as fully as the view allows; it doubles as a signpost for collaborators reading where the effort is headed.
 
 **Fog or ticket?** The test is whether you can state the question precisely now — _not_ whether you can answer it now.
 
 - **Ticket when** the question is already sharp — even if it's blocked and you can't act on it yet.
-- **Fog when** you can't yet phrase it that sharply. Don't pre-slice fog into ticket-sized pieces: it's coarser than a ticket, and one patch may graduate into several tickets, or none, once the frontier reaches it.
+- **Not yet specified when** you can't yet phrase it that sharply. Don't pre-slice the fog into ticket-sized pieces: it's coarser than a ticket, and one patch may graduate into several tickets, or none, once the frontier reaches it.
 
-Fog excludes only what's already decided (that's Decisions so far) and what's already a ticket.
+**Not yet specified** excludes what's already decided (Decisions so far), what's already a live ticket, and what's out of scope (the next section).
+
+## Out of scope
+
+Fog only ever gathers _toward_ the destination. The destination fixes the scope, so work beyond it is **out of scope** — it isn't fog, and it doesn't belong in **Not yet specified**. It gets its own **Out of scope** section on the map: work you've consciously ruled out of _this_ effort. Scope, not sharpness, lands it here.
+
+Out-of-scope work never graduates — the frontier stops at the destination — so it returns only if the destination is redrawn, and then as a fresh effort, not a resumption.
+
+Ruling something out of scope is a scoping act, not a step on the route. When a ticket that already exists turns out to sit past the destination — mis-scoped in while charting, or exposed by a resolution — **close it** (a closed ticket is unambiguously off the frontier) and leave one line in the **Out of scope** section: the gist plus why it's out of scope, linking the closed ticket. It stays out of **Decisions so far**, which records the route actually walked — a scope boundary isn't a step on it.
 
 ## Invocation
 
-Two modes. Either way, **never resolve more than one ticket per session.**
+Two modes. Either way, **never resolve more than one ticket per session** — with the exception of research tickets.
 
 ### Chart the map
 
 User invokes with a loose idea.
 
-1. Run a `/grilling` and `/domain-modeling` session to surface the open decisions.
-2. **Create the map** (label `wayfinder:map`): Notes filled in, Decisions-so-far empty, Fog sketched.
-3. **Create the tickets you can specify now** as child issues of the map — then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the Fog.
-4. Stop — charting the map is one session's work; do not also resolve tickets.
+1. **Name the destination.** Run a `/grilling` and `/domain-modeling` session to pin down what this map is finding its way to — the spec, decision, or change. The destination fixes the scope, so it's settled first.
+2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** — the way to the destination is already clear, the whole journey small enough for one session — you don't need a map. Stop and ask the user how they'd like to proceed.
+3. **Create the map** (label `wayfinder:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**.
+4. **Create the tickets you can specify now** as child issues of the map — then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog — the **Not yet specified** section.
+5. **Fire the research subagents.** For each `research` ticket you just created, spin up a `/research` subagent to resolve it in parallel, capturing its findings on a throwaway `research/<name>` branch with a context pointer from the ticket.
+6. Stop — charting is one session's work; it hand-resolves nothing.
 
 ### Work through the map
 
@@ -96,6 +123,6 @@ User invokes with a map (URL or number). A ticket is **optional** — without on
 2. Choose the ticket. If the user named one, use it. Otherwise take the first frontier ticket in order. **Claim it**: assign it to yourself before any work.
 3. Resolve it — **zoom as needed**: fetch the full body of any related or closed ticket on demand; invoke the skills the `## Notes` block names. If in doubt, use `/grilling` and `/domain-modeling`.
 4. Record the resolution: post the answer as a **resolution comment**, **close** the issue, and **append a context pointer** to the map's Decisions-so-far.
-5. Add newly-surfaced tickets (create-then-wire); graduate any fog the answer has made specifiable, clearing each graduated patch from the Fog so it lives only as its new ticket. If the decision invalidates other parts of the map, update or delete those tickets.
+5. Add newly-surfaced tickets (create-then-wire); graduate any fog the answer has made specifiable, clearing each graduated patch from **Not yet specified** so it lives only as its new ticket. If the answer reveals a ticket — this one or another — sits beyond the destination, **rule it out of scope** rather than resolving it on the route. If the decision invalidates other parts of the map, update or delete those tickets.
 
 The user may run unblocked tickets in parallel, so expect other sessions to be editing the tracker concurrently.

.agents/skills/wayfinder/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Wayfinder"
+  short_description: "Map a large effort as decision tickets"
+policy:
+  allow_implicit_invocation: false

.agents/skills/writing-great-skills/GLOSSARY.md

@@ -158,6 +158,12 @@ _Failure mode._ Ending the current step before it is genuinely done, because the
 
 _Avoid_: premature closure, the rush, rushing, shortcutting
 
+### Negation
+
+_Failure mode._ Steering by prohibition — telling the agent what _not_ to do — which drags the forbidden behaviour into context and makes it _more_ available, not less. _Don't think of an elephant_, and the elephant is all there is; _never write verbose comments_, and verbosity is the pattern the agent has just read. The negation is a weak modifier the strongly-activated concept overruns, so the ban half-reads as an instruction to do the thing. Its **leading word** is the _elephant_: whatever a prohibition names into the frame. Cure: prompt the **positive** — describe the target behaviour ("write one-line comments") so the banned one is never spoken. A prohibition earns its place only as a hard guardrail on a behaviour you cannot phrase positively; even then, pair it with the positive target so attention lands on what to do.
+
+_Avoid_: ironic rebound, don't-prompting, the pink elephant
+
 ## Pruning
 
 Keeping a skill lean — each remedy paired with the failure it cures.

.agents/skills/writing-great-skills/SKILL.md

@@ -80,3 +80,4 @@ Use these to diagnose issues the user may be having with the skill.
 - **Sediment** — stale layers that settle because adding feels safe and removing feels risky. The default fate of any skill without a pruning discipline.
 - **Sprawl** — a skill simply too long, even when every line is live and unique. Hurts readability and maintainability and wastes tokens. The cure is the ladder: disclose **reference** behind pointers, and split by **branch** or sequence so each path carries only what it needs.
 - **No-op** — a line the model already obeys by default, so you pay load to say nothing. The test: does it change behaviour versus the default? A weak leading word (_be thorough_ when the agent is already thorough-ish) is a no-op; the fix is a stronger word (_relentless_), not a different technique.
+- **Negation** — steering by prohibition backfires: _don't think of an elephant_ names the elephant and makes it more available, not less. Prompt the **positive** — state the target behaviour so the banned one is never spoken; keep a prohibition only as a hard guardrail you can't phrase positively, and even then pair it with what to do instead.

.agents/skills/writing-great-skills/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Writing Great Skills"
+  short_description: "Principles for predictable skills"
+policy:
+  allow_implicit_invocation: false

.claude/memory/MEMORY.md

@@ -2,11 +2,9 @@
 
 - [Product selling points](product-selling-points.md) — key differentiators and landing page angles for neuron-tai
 - [User profile](user-profile.md) — who Dobromir is and how to work with him
-- [Project status](project-status.md) — 35/35 stories done; alpha hardening next
+- [Project status](project-status.md) — US-001…US-035 done; US-036…US-050 in docs/prd.json; alpha hardening + scratch features next
 - **Alpha hardening** — `.scratch/alpha-hardening/` (22 issues, ADRs 0016–0019, [README](../../.scratch/alpha-hardening/README.md), [handoff](../../.scratch/alpha-hardening/handoff.md))
 - [Alpha hardening navigation](alpha-hardening-navigation.md) — locked fraud/auth decisions, Bucket-1 order, handoff pointers
-- **Node capability admission** — `.scratch/node-capability-admission/` (P0 plan: generic doctor/real-forward validation, fail-closed readiness, tracker admission gate; [PRD](../../.scratch/node-capability-admission/PRD.md), [README](../../.scratch/node-capability-admission/README.md), ADR-0023)
+- **Node capability admission** — `.scratch/node-capability-admission/` (P0 plan; [ADR-0023](../../docs/adr/0023-model-agnostic-node-capability-admission.md), [ADR-0026](../../docs/adr/0026-node-assignment-ownership-and-managed-placement.md))
 - **Distributed relay performance** — relay `/rpc` requester sockets are persistent per Route Session and Activation Seam as of 2026-07-10; `request_id` remains unique per activation while `X-Meshnet-Session` remains stable for KV state. Next low-risk priorities: persistent direct/loopback HTTP, seam byte/latency telemetry, then trace-driven zstd tuning.
-- **Distributed GGUF direction** — benchmark-gated native runtime: compare controlled Transformers/safetensors and whole-model llama.cpp lanes before expensive work; ship only for measured speed or model-fit advantage. Public parallelism is contiguous Shards in an Inference Route; concurrency comes from per-node continuous batching across isolated Route Sessions, while tensor/expert collectives stay inside optional trusted composite providers. Native data plane uses versioned Protobuf over long-lived gRPC/HTTP2 seam streams, with existing relay carrying the same opaque frames when needed. llama.cpp/GGML remains the substrate behind a project-owned standalone worker and small pinned fork; vLLM is an optional complete managed provider and concept donor, not a fork. Nakshatra, `prima.cpp`, `llama-gguf`, LiGGUF and historical GPUStack are source/test donors only. Active plan: [README](../../.scratch/distributed-gguf-runtime/README.md), [architecture](../../.scratch/distributed-gguf-runtime/architecture.md), [PRD](../../.scratch/distributed-gguf-runtime/PRD.md), [Ralph backlog](../../.scratch/distributed-gguf-runtime/prd.json). Research: [landscape](../../docs/research/distributed-gguf-landscape.md), [GitHub follow-up](../../docs/research/distributed-gguf-github-followup.md), [vLLM](../../docs/research/vllm-distributed-gguf-assessment.md).
-- [DGR ROCm setup](dgr-rocm-setup.md) — version-matched TheRock SDK layout, relocated devel payload, verified `gfx1151` HIP llama.cpp build, and GPU-diagnostic boundary.
-- **DGR-004 llama.cpp boundary** — `packages/node/native/llama/` locks `e920c523e3b8a0163fe498af5bf90df35ff51d25`, with a one-patch CMake marker and fail-closed clean materialize/apply/build/smoke harness. This is infrastructure only; stock GLM dense fallback remains uncertified.
+- **Distributed GGUF direction** — benchmark-gated native runtime: compare controlled Transformers/safetensors and whole-model llama.cpp lanes before expensive work; ship only for measured speed or model-fit advantage. Public parallelism is contiguous Shards in an Inference Route; concurrency comes from per-node continuous batching across isolated Route Sessions, while tensor/expert collectives stay inside optional trusted composite providers. Native data plane uses versioned Protobuf over long-lived gRPC/HTTP2 seam streams, with existing relay carrying the same opaque frames when needed. llama.cpp/GGML remains the substrate behind a project-owned standalone worker and small pinned fork; vLLM is an optional complete managed provider and concept donor, not a fork. Nakshatra, `prima.cpp`, `llama-gguf`, LiGGUF and historical GPUStack are source/test donors only. Active plan: [README](../../.scratch/distributed-gguf-runtime/README.md), [architecture](../../.scratch/distributed-gguf-runtime/architecture.md), [PRD](../../.scratch/distributed-gguf-runtime/PRD.md), [Ralph backlog](../../.scratch/distributed-gguf-runtime/prd.json). ADR: [0024](../../docs/adr/0024-distributed-gguf-runtime.md). Research: [landscape](../../docs/research/distributed-gguf-landscape.md), [GitHub follow-up](../../docs/research/distributed-gguf-github-followup.md), [vLLM](../../docs/research/vllm-distributed-gguf-assessment.md).

.claude/memory/alpha-hardening-navigation.md

@@ -20,13 +20,13 @@ Active workstream (started 2026-07-04): alpha hardening of the money/trust path.
 
 **Launch-readiness grilling (2026-07-06):** Locked launch plan — devnet dev/test run now, then **real mainnet SOL/USDT** (not devnet, not a new public token) for the first cohort: friends (API clients) + hired VPS/VPC hosts (our own test infra, not third-party volunteers — stake-free, risk-free if something breaks, not a long-term topology). Pricing: clients are the only party spending real money; nodes only accumulate off-chain credit and get paid in batches (30min dev / 24h later) — a failed distribution leaves funds parked, not lost, so mainnet-vs-devnet mixups are lower-risk than initially assumed. TAI token: do NOT issue/list now — ADR-0002 already locks listing behind $50k volume + 25 nodes/15 wallets plus an unresolved securities-review gate; only a dormant mainnet mint (cheap, ~few $ SOL) for name/branding reservation is in scope, bundled with treasury-key work, not before it. Treasury custody: bare keypair file (current runbook 02) is not acceptable for real funds — plan is **free native SPL multisig** (`spl-token create-multisig`, no protocol fee unlike Squads' 0.5 SOL), 2-of-3 signers, at least one cold/offline, others one-per-hired-VPS-provider to avoid correlated compromise (not yet built — ops task, no issue filed). Stake/slash asymmetry (registry/slash is a local Python adapter per ADR-0007, not on-chain) accepted for now since hired hosts are our own infra and friends aren't node operators — revisit before opening to real third-party node operators. A mainnet-vs-devnet boot guardrail was proposed and explicitly declined by the owner given the safe-by-default money flow above.
 
-**Two new issues from this session, both `ready-for-agent`:**
-- **21 — Honest-noise calibration corpus** (`.scratch/alpha-hardening/issues/21-honest-noise-calibration-corpus.md`) rescoped from "prod gate" to a **hard alpha-release blocker**. Confirmed by code read: `verify_activation_proofs()` (`packages/validator/meshnet_validator/audit.py:94-127`) returns bool only, no raw divergence value; fleet-dispatch exists but wrong shape (`server.py:2998-3104`, pinned routes + latency, not full-fleet + TOPLOC divergence); storage wrong shape (`registry_events` has no divergence/hardware columns). Three-part build: (1) surface raw TOPLOC distance from audit.py, (2) extend dispatch to hit every registered node with fixed prompt/seed, (3) new SQLite table keyed by node+GPU+dtype. Small-fleet exception granted (N = actual hired-VPS fleet size). Hired VPS hosts stay stake-free until this closes.
-- **23 — Dynamic HF-benchmarked pricing** (`.scratch/alpha-hardening/issues/23-dynamic-hf-pricing.md`), high priority but not a release blocker. Pricing today is 100% static (`DEFAULT_PRICE_PER_1K_TOKENS = 0.02`, `billing.py:21`; `model_presets.json` has no per-model price). Target: 80% of cheapest comparable provider on `https://huggingface.co/inference/models` (per-provider-per-model marketplace, `?search=` query param works, no confirmed JSON API — plain scrape attempted first, escalate to headless browser only if the table isn't in raw HTML). Human-verified `hf_aliases` + `hf_verified_match_note` (params/quantization) per model, not auto-discovered matching. Reuses the `_settlement_loop` daemon-thread pattern for a daily refresh; falls back silently to the static default on any failure.
+**Two new issues from this session:**
+- **21 — Honest-noise calibration corpus** — `Status: ready-for-human` (engineering done 2026-07-06; blocked on human fleet calibration run before mainnet launch).
+- **23 — Dynamic HF-benchmarked pricing** — `Status: done` (see `23-dynamic-hf-pricing_completed.md`).
 
 Both are already migrated into `.scratch/alpha-hardening/prd.json` (AH-021 updated, AH-023 added) and the README index — ready for Ralph to pick up unattended.
 
-**Ralph note:** `scripts/ralph_progress.py` tracks `docs/prd.json` (35/35 done) and does NOT see `.scratch/alpha-hardening/issues/`. No ralph loop is running and no `.ralph-tui/` state exists. `.scratch/alpha-hardening/prd.json` now has 23 stories (AH-001…AH-023); point Ralph at that file for the alpha-hardening branch. Do NOT use `ralph auto --parallel` on server.py-touching issues — 21 and 23 both touch `server.py`/`billing.py`/`audit.py`; if run in the same Ralph pass, run them serially, not in parallel (merge-conflict risk, same lesson as 03/04 previously).
+**Ralph note:** `scripts/ralph_progress.py` tracks `docs/prd.json` (US-001…US-047; base 35/35 done, friends-test arc 36–47 open/in-progress). Alpha hardening uses `.scratch/alpha-hardening/prd.json` (AH-001…AH-023). Point Ralph at the prd.json for the branch you're running.
 
 **Why:** three audits agreed the alpha blockers are unauthenticated gossip (anyone can inject billing events), the free-credit faucet, and ephemeral bans.
 **How to apply:** work test-first per issue acceptance criteria; use `.venv`; `cryptography` belongs in node deps (wallet.py imports it — causes many of the 24 "failures" in a fresh env). See [[project-status]] and [[autonomous-work-style]].

.claude/memory/project-status.md

@@ -6,7 +6,18 @@ metadata:
   type: project
 ---
 
-# Project Status (2026-07-02)
+# Project Status (2026-07-13)
+
+## Selected-node model placement (2026-07-14)
+
+- Admin Model placement now opens a node selector for load and release; the control-plane accepts optional `node_id` and targets only that registry assignment. Multi-model serving remains supported through `ADD_SHARD` and `max_loaded_shards`.
+- Total node pool resource values are rendered from `/v1/network/map`'s `node.capacity` contract. Route selection remains assignment/capability/throughput/queue based; capacity is used for placement and falls back to tracker defaults only if a node truly omits it.
+
+## Distributed inference performance (2026-07-14)
+
+`DIP-001` is done in `.scratch/distributed-inference-performance/`: the deterministic two-node Route Session stub benchmark covers direct/relay plus cached/stateless prefill and decode. Its JSON and concise summary explicitly attribute model execution, activation encode/decode, compression, connection setup, relay queueing, local HTTP forwarding, and end-to-end seam latency. `PYTHONPATH=packages/node pytest -q tests/test_route_session_benchmark.py` passed (7); the fixture assertion checks output-token identity and connection attempts.
+
+> Doc reconciliation 2026-07-13: `docs/prd.json` tracks US-001…US-050 (048 memory budget, 049 mainnet pilot, 050 Qwen demand placement). ADRs 0025–0026 added (TAI phase B/C, assignment ownership).
 
 All 35 user stories in docs/prd.json are done (35/35), including the reward-system arc US-030…US-035 completed 2026-07-02:
 
@@ -33,6 +44,10 @@ Historical handoff note: `/mnt/c/Users/popov/Downloads/neuron-tai-alpha-handoff-
 
 Planning is ready at `.scratch/node-capability-admission/` with five sequential Ralph stories and ADR-0023. The design is model-agnostic: a Node must validate its selected Model Artifact/shard with a bounded real forward before Tracker routing; Qwen3.6 is only an optional development fixture. P0 adds a versioned local recipe-manifest/report contract, `meshnet-node doctor`, fail-closed startup admission, and tracker route gating. It intentionally excludes dynamic recipe/dependency installation and the future signed Node updater.
 
+## Gitea DGR sync (2026-07-17)
+
+Gitea is ahead of the local Markdown backlog with open DGR-022..DGR-071. The first executable P0 dependency frontier is DGR-022 (Shard lifecycle and structured status RPCs), DGR-023 (reproducible protobuf generation), DGR-025 (artifact/runtime recipe identity), and DGR-027 (llama.cpp provenance manifest). DGR-021, the named-tensor stream envelope prerequisite for DGR-022/023/025, is closed. DGR-022 is the next dependency-ordered issue and blocks DGR-024, DGR-033, and DGR-037.
+
 ## Windows CUDA node (working as of 2026-07-01)
 - miniforge3 base env, torch 2.7.1+cu118, torchvision 0.22.x+cu118
 - RTX 4060 Laptop GPU, 8 GB VRAM, benchmark index ~11,200

.gitignore

@@ -20,6 +20,7 @@ dist/
 !.env.testnet
 .rocm-local/*
 .pytest-tmp/*
+.cache/
 
 # Local tracker/node sqlite databases (never commit runtime state)
 *.sqlite

.ralph-tui/config.toml

@@ -1,12 +0,0 @@
-# Ralph TUI Configuration
-# Generated by setup wizard
-# See: ralph-tui config help
-
-configVersion = "2.1"
-tracker = "json"
-agent = "opencode"
-maxIterations = 0
-autoCommit = true
-
-[trackerOptions]
-[agentOptions]

.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md

@@ -1,319 +1,57 @@
-# Ralph execution context: Performant Concurrent Distributed GGUF Runtime
+# Ralph context: Distributed GGUF Runtime
 
-Status: authoritative context for every fresh Ralph iteration
-Last updated: 2026-07-13
+> **Specification status:** planning artifacts only. No distributed GGUF runtime is implemented. DGR-017 cleanup is complete; no runtime implementation story has completion credit. `prd.json` is authoritative.
 
-## Mandatory startup sequence
+## Mandatory startup for every fresh story
 
-Before changing code, every Ralph agent must:
+1. Read this file and authoritative `prd.json` completely.
+2. Read the generated source issue named in the selected story description.
+3. Read every dependency evidence README; legacy DGR-001..016 evidence is provenance only.
+4. Read `docs/adr/0024-distributed-gguf-runtime.md`, root `CONTEXT.md`, `.claude/memory/MEMORY.md`, and relevant live source/tests.
+5. Inspect `git status`; preserve unrelated work. Never infer implementation from planning text or old pass states.
+6. If blocked or oversized, keep `passes: false` and write an honest `BLOCKED.md`/`DECOMPOSITION.md`; never weaken criteria or fabricate evidence.
 
-1. Read this file completely.
-2. Read the selected issue under `.scratch/distributed-gguf-runtime/issues/`.
-3. Read `.scratch/distributed-gguf-runtime/GLM-5.2-MAX-ALPHA-ROADMAP.md`, `.scratch/distributed-gguf-runtime/ADR-0020-distributed-gguf-runtime.md`, and the relevant part of `architecture.md`.
-4. Read `.claude/memory/MEMORY.md` and root `CONTEXT.md` for current project vocabulary and constraints.
-5. Inspect the current implementation and tests; do not assume historical scratch text describes live code.
-6. Read the evidence/handoff directories for every declared dependency.
-7. Inspect `git status` and preserve all pre-existing working-tree changes.
+## Locked scope
 
-A fresh Ralph iteration has no conversational memory. These files are the context contract.
+- Existing Meshnet Tracker routing, load balancing, billing, telemetry, relay, and provider semantics are backend-agnostic and are **not redesigned**. GGUF contributes exact compatibility, range/capacity, queue/load, seam-cost, health/reliability, and certification inputs only.
+- The data plane is a standalone project-owned C++ Shard worker with gRPC/Protobuf and a project-owned `ShardEngine` boundary.
+- llama.cpp is fetched at one exact commit into an ignored workspace from an in-repo manifest, then a numbered minimal patch stack is applied. There is no submodule, vendored tree, or permanent-fork dependency.
+- llama.cpp owns DeepSeek V4 graphs, mHC, MoE, attention, hash routing, and kernels. Meshnet adds only range-ownership hooks, typed boundary/local-state adapters, worker integration, and parity/certification.
+- Quantization and placement are dynamic recipe inputs. The 2–4 and 10+ stage layouts are certification scenarios, never product constants.
+- Per-shard Hot KV and V4 CSA/HCA/SWA/indexer/compressor state remain local and keyed by route session/epoch. The WAN seam carries the typed mHC 4×4096 residual boundary, positions, token-ID sideband where required, and schema/cache expectations—not per-layer caches.
+- Route changes use cache miss plus re-prefill/restart. There is no WAN KV or V4 auxiliary-cache migration.
+- CPU/CUDA/ROCm/Vulkan/Metal compile lanes are planned; only exact real-hardware-certified backend/model/recipe lanes may be advertised.
+- Alpha requires correctness and the pre-locked useful-speed gate. MTP is reserved and off for alpha; its ownership contract, implementation, and benchmark are required before beta.
 
-## Story sizing and interruption rule
+## Target identities
 
-Each story is intended to fit one focused Ralph context. Before implementation, estimate whether every acceptance criterion can be completed and verified in the current iteration.
+- DeepSeek V4 official target SHA: `60d8d70770c6776ff598c94bb586a859a38244f1`.
+- llama.cpp V4 support lineage began at PR 24162 / merge `8c146a8366304c871efc26057cc90370ccf58dad`; DGR-027 later pins one exact validated current commit.
+- V4 scope: 43 main layers plus MTP; mHC 4×4096 boundary; 256 routed + 1 shared experts with six routed active; token IDs required for the first three hash-routed layers.
+- Exact split-GGUF artifacts are provisioned to mounted-drive storage with a complete hashed manifest and resumable verification; no model artifact may be placed under `/home`.
 
-If the story is too large, an external dependency is unavailable, or the context/provider limit prevents completion:
+## Control/data-plane contract
 
-- Do not weaken criteria.
-- Do not mark the issue done or set `passes: true`.
-- Avoid leaving an unverified cross-cutting partial implementation when a smaller safe spike is possible.
-- Write `evidence/<TASK-ID>/DECOMPOSITION.md` or `BLOCKED.md` with the exact blocker, current verified state, proposed child stories, dependency graph and rollback/continuation instructions.
-- Stop for supervised review.
+Meshnet continues to own registration, coverage, existing route selection/load balancing, route epochs/sessions, direct/relay behavior, capability admission, cancellation, telemetry, billing, validation, and attribution. The GGUF adapter exposes measured inputs to those existing mechanisms. Direct seams use long-lived gRPC streams; relay seams carry byte-identical protobuf frames opaquely.
 
-If interrupted after code changes, record every changed file, command result and unresolved invariant so the next fresh loop can verify rather than guess.
+The project-owned `ShardEngine` hides llama.cpp internals. A worker loads one exact artifact/recipe/range identity. Default tests use fake/tiny fixtures. Real runs are opt-in, preserve raw metrics, and never download models under `/home`.
 
-## Product objective
+## Gitea issue synchronization
 
-Build performant, concurrent distributed inference that combines consumer machines to serve top open models that exceed one node's RAM/VRAM.
+Gitea is a projection of `prd.json`, never a competing source of truth. Before and after every supervised Ralph run, invoke:
 
-The alpha target is the exact pinned GLM-5.2 `UD-IQ1_S` artifact served with `reasoning_effort=max` across physical consumer machines. Dense Llama is a structural fixture. Synthetic workers, dense-attention compatibility fallback, a smaller model, or a single host cannot satisfy target alpha. The immutable target contract and resource envelope are in `GLM-5.2-MAX-ALPHA-ROADMAP.md`.
-
-A distributed demo is not success. The product must provide:
-
-- Useful measured prefill and decode speed.
-- Multiple concurrent Route Sessions.
-- No KV/token cross-talk.
-- Bounded memory, queues, cancellation and failures.
-- Real execution on every participating node.
-- A model-fit or performance advantage over the current Transformers/safetensors route.
-
-## Critical-path architecture
-
-```text
-Existing Meshnet control plane
-        |
-Versioned Protobuf over gRPC/HTTP2
-        |
-Project-owned standalone C++ Shard worker
-        |
-Small exact-commit llama.cpp patch stack
+```bash
+python3 scripts/ralph_gitea_sync.py sync
 ```
 
-Meshnet remains the only control plane and owns:
+For a complete Ralph invocation with automatic state reconciliation, use:
 
-- Tracker registration, Coverage Map, route selection and route epochs.
-- Route Sessions and Activation Seams.
-- Direct/relay routing.
-- Capability admission.
-- Cancellation, Generation Telemetry and backpressure.
-- Billing, validation and per-node work attribution.
-
-Do not introduce another scheduler/control plane from vLLM, Nakshatra, prima.cpp, llama-gguf, GPUStack or another project.
-
-## Runtime decisions that are not open
-
-1. Public-network Shards are contiguous transformer layer ranges.
-2. llama.cpp/GGML is the native GGUF execution substrate.
-3. The project owns a small standalone worker and a narrow pinned llama.cpp patch stack.
-4. The native Shard protocol is Protocol Buffers over gRPC/HTTP2.
-5. One long-lived bidirectional stream serves one Route Session Activation Seam.
-6. The public activation boundary is a versioned named-tensor bundle.
-7. Hot KV State remains local to the node serving the Shard.
-8. `(Route Session ID, route epoch)` maps to an isolated llama sequence or bounded context.
-9. Concurrency uses continuous batching of compatible active sessions inside each node.
-10. Transformers/safetensors remains the correctness and performance baseline.
-11. vLLM may be an optional complete managed provider and concept donor; it is not forked into public Shards.
-12. Tensor/expert collectives are deferred to a trusted composite provider, not public WAN routes.
-13. Unsupported architectures/backends remain registered-but-dark until real certification passes.
-14. Alpha failure retries from token zero; unverified KV is never migrated silently.
-15. Model artifacts must remain on mounted-drive storage and never under `/home`.
-16. Unified system RAM and integrated-GPU memory are one physical pool and must never be double-counted for admission.
-17. Alpha requires native GLM-5.2 MoE, DSA, and IndexShare semantics; MTP/speculative decoding and 1M-context certification are post-alpha.
-18. DGR-006 amends the decode fast path to carry a versioned `TensorBundle` and defines a typed tail logits/token result; the current single-`NamedTensor` fast path is insufficient for GLM sidebands.
-19. Alpha reserves at least `max(20% of physical usable memory, 8 GiB)` per node outside weight-plus-Q8-KV placement and uses a same-switch wired 2.5 GbE minimum route.
-
-Changing one of these requires an explicit ADR update and human review, not an incidental story implementation.
-
-## Performance discipline
-
-GGUF performance is a hypothesis. Never write “GGUF is faster” without measurements.
-
-DGR-001 locks controlled benchmark lanes and thresholds. DGR-014 enforces the final distributed comparison.
-
-Always distinguish:
-
-- Weight quantization from activation/compute/KV dtype.
-- Runtime/kernel gains from quantization/model-fit gains.
-- Single-request latency from aggregate concurrency throughput.
-- Synthetic unit coverage from real distributed acceptance.
-
-Required metrics where applicable:
-
-```text
-TTFT
-prefill tokens/sec
-decode tokens/sec
-aggregate throughput
-p50/p95 latency
-seam bytes and latency
-queue and batch occupancy
-RSS and VRAM
-KV pressure
-output-quality drift
-failures and cleanup
+```bash
+scripts/ralph-gitea-run.sh ralph-tui run --prd .scratch/distributed-gguf-runtime/prd.json --agent claude --model sonnet --iterations 1 --no-tui --no-setup --direct-merge --no-sandbox
 ```
 
-Do not weaken or move performance thresholds after seeing implementation results.
+The sync creates/reconciles one Gitea issue per `DGR-*` story, creates missing labels/milestones, closes issues whose `passes` is true, marks the selected next eligible story `status:in-progress`, and marks blocked stories `status:blocked`. `gitea-issues.json` is a derived mapping only.
 
-## Transport discipline
+## Evidence and completion
 
-Do not invent a raw TCP protocol, new WebSocket protocol, QUIC layer or bespoke binary control format.
-
-The `.proto` schema is the semantic contract. Direct transport uses gRPC. Existing relay infrastructure may carry the same serialized protobuf frames as opaque binary.
-
-Protocol requirements:
-
-- Schema/version negotiation.
-- Request/work ID.
-- Route Session ID and route epoch.
-- Exact Model Artifact/runtime recipe fingerprint.
-- Shard range and effective overlap-safe start.
-- Prefill/decode/release/cancel phases.
-- Position/token range and idempotency step.
-- Named tensors with shape, dtype, byte order and bounded fragments.
-- Compression/checksum.
-- Cache expectation/result.
-- Deadlines, cancellation, flow control and structured status.
-
-Avoid per-token channel creation and unbounded unary payloads. Generated code and build tooling must be reproducible; do not require manual copying.
-
-## Native runtime discipline
-
-Reuse llama.cpp for GGUF, mmap, kernels, architecture graphs, tokenizer, KV, sequences and heterogeneous backends.
-
-The project patch stack is limited to:
-
-- Range-aware tensor registration/loading.
-- Endpoint-specific embedding/final head ownership.
-- Architecture-defined intermediate input/output.
-- Intermediate output before final norm/head.
-- Layer-filtered KV and session mapping.
-
-Do not place Meshnet routing, transport, billing or authentication inside llama.cpp. Keep patches numbered, scoped, pinned and upstreamable.
-
-Dense Llama is first only as a cheap range/boundary fixture. GLM-5.2 is the explicit product adapter and alpha target immediately afterward. Qwen3/Qwen3-MoE is post-alpha. Do not generalize through unchecked tensor-name substitutions.
-
-## Existing code seams to inspect first
-
-- `packages/node/meshnet_node/model_backend.py` — backend abstraction.
-- `packages/node/meshnet_node/torch_server.py` — reference ranged execution and session behavior.
-- `packages/node/meshnet_node/activation_compression.py` — current activation framing/compression.
-- `packages/node/meshnet_node/route_session_benchmark.py` — existing benchmark infrastructure.
-- `packages/tracker/meshnet_tracker/server.py` — registration, route and proxy behavior.
-- `packages/tracker/meshnet_tracker/capability.py` — fail-closed capability admission.
-- `tests/test_real_model_backend.py` — real backend coverage.
-- `tests/test_tracker_routing.py` — route/session behavior.
-- `tests/test_tracker_capability_admission.py` — recipe admission.
-- `tests/test_route_session_benchmark.py` and `tests/test_manual_route_benchmark.py` — benchmark patterns.
-- `docs/adr/0008-binary-activation-wire-format.md` — existing wire compatibility.
-- `docs/adr/0012-start-layer-overlapping-shards.md` — effective start semantics.
-- `docs/adr/0022-sharded-per-node-kv-cache.md` — Hot KV State contract.
-- `docs/adr/0023-model-agnostic-node-capability-admission.md` — certification/admission.
-
-Do not edit generated `build/`, `__pycache__`, egg-info, Ralph logs or unrelated scratch features.
-
-## Planned source layout
-
-Use these paths unless current code inspection proves a better project-consistent location. If changed, document the reason in task evidence.
-
-```text
-packages/node/native/
-  proto/shard_runtime.proto
-  cmake/
-  llama/
-    UPSTREAM_COMMIT
-    patches/
-  gguf_worker/
-  tests/
-
-packages/node/meshnet_node/
-  native_protocol/
-  gguf_backend.py
-  runtime_recipe.py
-
-.scratch/distributed-gguf-runtime/evidence/<TASK-ID>/
-  README.md
-  commands.txt
-  results.json or other machine-readable evidence
-```
-
-Generated protobuf/C++ build outputs belong in build directories unless packaging explicitly requires checked-in generated Python modules. The story must document the generation command and version.
-
-## Story output map
-
-| Story | Required durable outputs |
-|---|---|
-| DGR-001 | benchmark harness/tests; `evidence/DGR-001/performance-contract.json`; raw/summary benchmark evidence |
-| DGR-002 | `packages/node/native/proto/shard_runtime.proto`; reproducible Python/C++ generation/build wiring; protocol round-trip/compatibility tests; `evidence/DGR-002/` |
-| DGR-003 | exact runtime-recipe/fingerprint implementation and admission tests; `evidence/DGR-003/` |
-| DGR-004 | exact upstream pin, numbered patch series, reproducible fetch/apply/build smoke; `evidence/DGR-004/` |
-| DGR-005 | dense-Llama range ownership loader and memory evidence; `evidence/DGR-005/` |
-| DGR-006 | decode `TensorBundle` protocol amendment, typed tail-result contract, architecture boundary adapter/parity tests and results; `evidence/DGR-006/` |
-| DGR-007 | concurrent session/KV manager, isolation/cleanup tests; `evidence/DGR-007/` |
-| DGR-008 | standalone C++ gRPC worker, fake-model integration tests, lifecycle evidence; `evidence/DGR-008/` |
-| DGR-009 | Meshnet backend/registration/relay integration and tests; `evidence/DGR-009/` |
-| DGR-010 | real local two-process commands, raw metrics and parity report; `evidence/DGR-010/` |
-| DGR-011 | two-machine configuration, commands, hardware/network manifest and raw results; `evidence/DGR-011/` |
-| DGR-012 | continuous scheduler/admission implementation and 1/2/4/8 concurrency report; `evidence/DGR-012/` |
-| DGR-013 | failure/cancel/restart test matrix and resource-cleanup evidence; `evidence/DGR-013/` |
-| DGR-014 | immutable final comparison against DGR-001 thresholds and ship/stop recommendation; `evidence/DGR-014/` |
-| DGR-015 | Qwen3-family adapter, architecture-specific parity/admission/performance evidence; `evidence/DGR-015/` |
-| DGR-016 | narrow upstream patches/tests, design note and human-ready outreach package; `evidence/DGR-016/` |
-| DGR-017 | exact GLM-5.2/GGUF target manifest, resource planner, immutable alpha contract and upstream status; `evidence/DGR-017/` |
-| DGR-018 | verified whole-model `UD-IQ1_S` oracle with native GLM semantic evidence; `evidence/DGR-018/` |
-| DGR-019 | explicit range-owned GLM MoE/MLA/DSA/IndexShare adapter, fixtures and parity; `evidence/DGR-019/` |
-| DGR-020 | real multi-node GLM-5.2 Max target evidence and immutable `alpha`/`stop` verdict; `evidence/DGR-020/` |
-
-## Dependency handoff rule
-
-For every dependency listed by Ralph:
-
-1. Confirm its `passes` state in `prd.json`.
-2. Read `.scratch/distributed-gguf-runtime/evidence/<DEPENDENCY-ID>/README.md`.
-3. Verify referenced source paths and commands still exist.
-4. Do not repeat completed work unless verification exposes a concrete defect.
-5. If dependency evidence is missing or contradictory, stop and repair the dependency instead of guessing.
-
-## Testing and hardware rules
-
-Default tests must be deterministic, GPU-free, model-download-free and API-credit-free.
-
-Real model tests require:
-
-```text
-MESHNET_ENABLE_REAL_INFERENCE_TESTS=1
-```
-
-On this machine:
-
-- Use `.venv-rocm` for real Radeon 8060S ROCm execution.
-- The default Python 3.14 `.venv` is unsuitable for real ROCm inference.
-- Resolve model storage through the machine-specific `.env.<hostname>` configuration.
-- Never download model artifacts under `/home`.
-- Real acceptance must exercise actual Tracker-routed CPU/GPU computation; synthetic workers are only unit tests.
-
-Record exact:
-
-- Model/revision and Artifact hash.
-- Quantization and runtime recipe.
-- Host/hardware/backend/driver.
-- Commands and environment names without secrets.
-- Raw output and metrics.
-- Whether the evidence is synthetic, local-real, or multi-machine-real.
-
-## Worktree and commit discipline
-
-This repository may contain pre-existing changes from research or another feature.
-
-- Inspect `git status` before editing.
-- Never reset, checkout over, stash, delete or reformat unrelated changes.
-- Stage only files belonging to the selected story.
-- Exclude `.ralph-tui`, iteration logs, caches, generated builds, FUSE artifacts and unrelated scratch work.
-- Keep one scoped commit per completed story when the supervising loop requests commits.
-- Do not modify `passes` for another story.
-
-## Mandatory finish/handoff sequence
-
-Before emitting `<promise>COMPLETE</promise>`:
-
-1. Verify every acceptance criterion with real command output or file evidence.
-2. Run story-specific gates and repository quality gates.
-3. Write `.scratch/distributed-gguf-runtime/evidence/<TASK-ID>/README.md` containing:
-   - Summary of changes.
-   - Exact files changed.
-   - Commands run and their real results.
-   - Performance/correctness evidence.
-   - Known limitations and deferred work.
-   - Compatibility or migration notes.
-   - Clear handoff for dependent stories.
-4. Save machine-readable evidence beside it when the story produces metrics or schemas.
-5. Update the source issue status to `done` only after all gates pass.
-6. Preserve failures honestly. Never fabricate model, benchmark, test or hardware output.
-
-## Authoritative references
-
-Active decisions:
-
-- `.scratch/distributed-gguf-runtime/README.md`
-- `.scratch/distributed-gguf-runtime/implementation-strategy.md`
-- `.scratch/distributed-gguf-runtime/architecture.md`
-- `.scratch/distributed-gguf-runtime/ADR-0020-distributed-gguf-runtime.md`
-- `.scratch/distributed-gguf-runtime/PRD.md`
-- `.scratch/distributed-gguf-runtime/prd.json`
-
-Source research:
-
-- `docs/research/distributed-gguf-landscape.md`
-- `docs/research/distributed-gguf-github-followup.md`
-- `docs/research/vllm-distributed-gguf-assessment.md`
-
-If historical notes conflict with these files, the active decisions above win.
+Each story writes `/run/media/popov/d/DEV/repos/d-popov.com/AI/.claude/worktrees/distributed-gguf-runtime/.scratch/distributed-gguf-runtime/evidence/<DGR-ID>/README.md` with exact files, commands/results, limitations, identities, and dependent-story handoff. Only `prd.json` may record `passes`; DGR-017 and DGR-018 are complete and DGR-019 onward remain false. Generated Markdown and Gitea issues cannot override it. One scoped commit per story is expected during future execution.

.scratch/distributed-gguf-runtime/README.md

@@ -1,48 +1,32 @@
-# Performant concurrent distributed GGUF runtime
+# Distributed GGUF Runtime planning workspace
 
-Status: active benchmark-gated implementation program.
+> **Specification status:** planning artifacts only. No distributed GGUF runtime is implemented. DGR-017 cleanup is complete; no runtime implementation story has completion credit. `prd.json` is authoritative.
 
-## Objective
 
-Serve the exact pinned GLM-5.2 `UD-IQ1_S` artifact in `reasoning_effort=max` mode across consumer machines with useful measured performance. Dense Llama is a structural fixture; the real multi-node GLM target is the alpha release gate.
+## Locked scope
 
-See **[GLM-5.2 Max distributed alpha roadmap](GLM-5.2-MAX-ALPHA-ROADMAP.md)** for the target identity, minimum hardware, immutable acceptance matrix, and revised execution order. The 224-GiB figure is an experimental hard-fit floor; recommended topology is 5×64 GiB or 3×96/128 GiB after the required per-node reserve.
+- Existing Meshnet Tracker routing, load balancing, billing, telemetry, relay, and provider semantics are backend-agnostic and are **not redesigned**. GGUF contributes exact compatibility, range/capacity, queue/load, seam-cost, health/reliability, and certification inputs only.
+- The data plane is a standalone project-owned C++ Shard worker with gRPC/Protobuf and a project-owned `ShardEngine` boundary.
+- llama.cpp is fetched at one exact commit into an ignored workspace from an in-repo manifest, then a numbered minimal patch stack is applied. There is no submodule, vendored tree, or permanent-fork dependency.
+- llama.cpp owns DeepSeek V4 graphs, mHC, MoE, attention, hash routing, and kernels. Meshnet adds only range-ownership hooks, typed boundary/local-state adapters, worker integration, and parity/certification.
+- Quantization and placement are dynamic recipe inputs. The 2–4 and 10+ stage layouts are certification scenarios, never product constants.
+- Per-shard Hot KV and V4 CSA/HCA/SWA/indexer/compressor state remain local and keyed by route session/epoch. The WAN seam carries the typed mHC 4×4096 residual boundary, positions, token-ID sideband where required, and schema/cache expectations—not per-layer caches.
+- Route changes use cache miss plus re-prefill/restart. There is no WAN KV or V4 auxiliary-cache migration.
+- CPU/CUDA/ROCm/Vulkan/Metal compile lanes are planned; only exact real-hardware-certified backend/model/recipe lanes may be advertised.
+- Alpha requires correctness and the pre-locked useful-speed gate. MTP is reserved and off for alpha; its ownership contract, implementation, and benchmark are required before beta.
 
-## Critical path
+## Target identities
 
-```text
-Meshnet control plane
-  -> versioned gRPC/Protobuf Shard protocol
-  -> project-owned standalone C++ worker
-  -> small pinned llama.cpp patch stack
-```
+- DeepSeek V4 official target SHA: `60d8d70770c6776ff598c94bb586a859a38244f1`.
+- llama.cpp V4 support lineage began at PR 24162 / merge `8c146a8366304c871efc26057cc90370ccf58dad`; DGR-027 later pins one exact validated current commit.
+- V4 scope: 43 main layers plus MTP; mHC 4×4096 boundary; 256 routed + 1 shared experts with six routed active; token IDs required for the first three hash-routed layers.
+- Exact split-GGUF artifacts are provisioned to mounted-drive storage with a complete hashed manifest and resumable verification; no model artifact may be placed under `/home`.
 
-Transformers/safetensors remains the correctness baseline. vLLM remains an optional complete managed provider and a design donor; it is not forked into the public mesh.
+## Navigation
 
-## Planning artifacts
-
-- **[Mandatory Ralph context](RALPH-CONTEXT.md)** — read first in every fresh iteration
-- [Task evidence contract](evidence/README.md)
-- [Implementation strategy](implementation-strategy.md)
-- [Current architecture](architecture.md)
-- [PRD](PRD.md)
-- [Ralph backlog](prd.json)
-- [ADR-0020](ADR-0020-distributed-gguf-runtime.md)
-- [Milestones](milestones.md)
-- [Issues](issues/)
-- [Distributed GGUF research](../../docs/research/distributed-gguf-landscape.md)
-- [GitHub follow-up](../../docs/research/distributed-gguf-github-followup.md)
-- [vLLM assessment](../../docs/research/vllm-distributed-gguf-assessment.md)
-
-## Ralph execution
-
-Use supervised one-story iterations for this high-risk runtime:
-
-```bash
-ralph-tui run \
-  --prd .scratch/distributed-gguf-runtime/prd.json \
-  --agent claude --model opus \
-  --iterations 1 --no-tui --no-setup --verify
-```
-
-Inspect the diff, run the story gates, and commit one verified story before the next iteration. Real-model stories require the explicit environment gate and mounted-drive model storage.
+- [`prd.json`](prd.json) — sole authoritative 55-story backlog, DGR-017..071.
+- [`PRD.md`](PRD.md) — human-readable projection of goals, gates, and all stories.
+- [`RALPH-CONTEXT.md`](RALPH-CONTEXT.md) — mandatory fresh-session context.
+- [`architecture.md`](architecture.md), [`implementation-strategy.md`](implementation-strategy.md), [`milestones.md`](milestones.md) — design and execution sequence.
+- [`issues/`](issues/) — generated story specs; files 01..16 are retained legacy artifacts pending DGR-017.
+- [`evidence/`](evidence/) — provenance and future per-story handoffs.

.scratch/distributed-gguf-runtime/architecture.md

@@ -1,264 +1,45 @@
-# Performant Concurrent Distributed GGUF Architecture
+# Distributed GGUF Runtime architecture
 
-Status: current target architecture
-Last updated: 2026-07-13
+> **Specification status:** planning artifacts only. No distributed GGUF runtime is implemented. DGR-017 cleanup is complete; no runtime implementation story has completion credit. `prd.json` is authoritative.
 
-## Product invariant
 
-The system exists to serve high-quality models that exceed one consumer node's memory while retaining useful interactive speed and aggregate concurrency. A feature that only produces a distributed demo but is slower, globally serialized, or impossible to operate on consumer hardware is not complete.
+## Locked scope
 
-The alpha target is the exact pinned GLM-5.2 `UD-IQ1_S` artifact in `reasoning_effort=max` mode. Its target-specific architecture/resource/acceptance contract is [GLM-5.2-MAX-ALPHA-ROADMAP.md](GLM-5.2-MAX-ALPHA-ROADMAP.md). Dense Llama is a structural fixture, not the product target.
+- Existing Meshnet Tracker routing, load balancing, billing, telemetry, relay, and provider semantics are backend-agnostic and are **not redesigned**. GGUF contributes exact compatibility, range/capacity, queue/load, seam-cost, health/reliability, and certification inputs only.
+- The data plane is a standalone project-owned C++ Shard worker with gRPC/Protobuf and a project-owned `ShardEngine` boundary.
+- llama.cpp is fetched at one exact commit into an ignored workspace from an in-repo manifest, then a numbered minimal patch stack is applied. There is no submodule, vendored tree, or permanent-fork dependency.
+- llama.cpp owns DeepSeek V4 graphs, mHC, MoE, attention, hash routing, and kernels. Meshnet adds only range-ownership hooks, typed boundary/local-state adapters, worker integration, and parity/certification.
+- Quantization and placement are dynamic recipe inputs. The 2–4 and 10+ stage layouts are certification scenarios, never product constants.
+- Per-shard Hot KV and V4 CSA/HCA/SWA/indexer/compressor state remain local and keyed by route session/epoch. The WAN seam carries the typed mHC 4×4096 residual boundary, positions, token-ID sideband where required, and schema/cache expectations—not per-layer caches.
+- Route changes use cache miss plus re-prefill/restart. There is no WAN KV or V4 auxiliary-cache migration.
+- CPU/CUDA/ROCm/Vulkan/Metal compile lanes are planned; only exact real-hardware-certified backend/model/recipe lanes may be advertised.
+- Alpha requires correctness and the pre-locked useful-speed gate. MTP is reserved and off for alpha; its ownership contract, implementation, and benchmark are required before beta.
 
-## Existing control plane
+## Target identities
 
-Meshnet remains the only public control plane:
+- DeepSeek V4 official target SHA: `60d8d70770c6776ff598c94bb586a859a38244f1`.
+- llama.cpp V4 support lineage began at PR 24162 / merge `8c146a8366304c871efc26057cc90370ccf58dad`; DGR-027 later pins one exact validated current commit.
+- V4 scope: 43 main layers plus MTP; mHC 4×4096 boundary; 256 routed + 1 shared experts with six routed active; token IDs required for the first three hash-routed layers.
+- Exact split-GGUF artifacts are provisioned to mounted-drive storage with a complete hashed manifest and resumable verification; no model artifact may be placed under `/home`.
 
-- Tracker registration, Coverage Map, route scoring and assignment.
-- Contiguous Shards and overlap-safe effective starts.
-- Stable Route Sessions and route epochs.
-- Local per-Shard Hot KV State in the reference backend.
-- Direct/relay transport, cancellation and backpressure.
-- Generation Telemetry, billing, validation and per-node attribution.
-- Model-agnostic capability admission.
-
-No external engine replaces these responsibilities.
-
-## Runtime topology
+## Topology
 
 ```text
-OpenAI-compatible client
-        |
-Gateway / Tracker Node
-        |
-ordered Inference Route
-        |
-        +-- head Shard: tokenizer/embedding + early layers
-        |       local weights and Hot KV State
-        |
-        +-- middle Shard(s): architecture boundary + owned layers
-        |       local weights and Hot KV State
-        |
-        +-- tail Shard: final layers + norm/head/sampling
-                local weights and Hot KV State
+existing Meshnet Tracker/control plane
+  -> existing backend-agnostic route/load-balancing decision
+  -> direct gRPC or existing opaque relay
+  -> project-owned standalone C++ Shard worker
+  -> project-owned ShardEngine
+  -> pinned upstream llama.cpp + numbered range/boundary/state hook patches
+  -> GGUF mmap, upstream V4 graph/kernels, local per-shard state
 ```
 
-Weights never move in the per-request hot path. Every node opens and verifies its local Model Artifact before becoming routable.
+A route is ordered contiguous half-open ranges. Head owns token embedding; tail owns final norm/head/sampling. Compatibility fingerprints bind source/split hashes, tokenizer, architecture adapter, typed boundary, runtime pin/patches, backend, quant, activation/compute/KV layout, range, and certification.
 
-## Primary execution substrate
+## V4 boundary and state
 
-```text
-project-owned C++ Shard worker
-        |
-small exact-commit llama.cpp patch stack
-        |
-GGUF mmap, quantized kernels, architecture graphs,
-KV/sequence operations, CPU/CUDA/HIP/Vulkan/Metal backends
-```
+The inter-stage boundary is semantic and versioned: mHC 4×4096 residual, positions, token IDs only where the first three hash-routed layers require them, and cache/schema expectations. CSA/HCA/SWA/indexer/compressor/KV state belongs to upstream layer execution on the owning worker and is isolated by `(route_session_id, route_epoch)`. On loss, return cache miss and re-prefill/restart. Never serialize those caches into the WAN bundle.
 
-The patch stack adds only the missing local execution seam:
+## Concurrency, failure, and admission
 
-1. Range-aware tensor registration/loading.
-2. Endpoint-specific embedding and final head ownership.
-3. Architecture-defined intermediate input.
-4. Architecture-defined pre-tail boundary output.
-5. Layer-filtered KV and external session mapping.
-
-The worker owns protocol translation and process lifecycle. llama.cpp never receives Tracker, relay, billing or volunteer-network code.
-
-## Shard data plane
-
-Use Protocol Buffers and gRPC over HTTP/2.
-
-### Service shape
-
-- Unary capability and health.
-- Bidirectional Route Session stream.
-- Explicit release and cancellation.
-- Metrics suitable for capability admission and route scoring.
-
-### Session stream
-
-One long-lived stream represents one Route Session Activation Seam. It amortizes connection setup and inherits HTTP/2 flow control. Every message carries enough identity to reject stale or incompatible work.
-
-```text
-schema version
-request/work id
-Route Session id
-route epoch
-Model Artifact hash
-runtime recipe fingerprint
-Shard begin/end and effective start
-prefill/decode/release/cancel phase
-position and token range
-idempotency step id
-cache expectation/result
-named tensor bundle
-compression/checksum
-```
-
-Prefill tensors are split into bounded ordered frames. Decode messages carry one-step architecture boundary bundles and remain small. DGR-006 amends the current v1 decode fast path—which carries only one `NamedTensor`—to carry a versioned `TensorBundle`, while preserving compact one-tensor encoding and explicit compatibility behavior.
-
-Tail completion is not inferred from an activation tensor name. The protocol exposes a typed logits and/or sampled-token result, and exact sampling parameters plus chat-template/reasoning mode are bound to request/runtime identity.
-
-Direct nodes use gRPC. Nodes requiring the existing relay carry the same protobuf frames as opaque binary through the relay session. This preserves one semantic protocol instead of maintaining separate direct and relay payload contracts.
-
-## Architecture boundary
-
-The public boundary is a versioned named-tensor bundle:
-
-```text
-bundle schema/version
-architecture adapter and boundary point
-named tensors
-per-tensor shape, dtype and byte order
-payload fragments
-compression/checksum
-```
-
-Dense Llama may use one residual tensor. Other adapters may require more. vLLM's Llama and Qwen3-MoE PP paths demonstrate a boundary with both `hidden_states` and `residual`; therefore the generic protocol must not assume one anonymous tensor.
-
-GLM-5.2 normally exchanges a 6,144-element hidden state. If a memory-balanced Shard boundary splits an IndexShare Full producer from Shared consumers, the bundle also carries the typed top-k index sideband. The planner prefers boundaries that keep an IndexShare ownership group local, but the protocol validates the sideband rather than assuming it never crosses a seam.
-
-Only the head owns token embedding. Only the tail owns final normalization, LM head and sampling. Middle Shards exchange the architecture-defined pre-tail boundary, not final normalized embeddings.
-
-## Hot KV State and concurrency
-
-```text
-(Route Session id, route epoch)
-       -> local llama sequence or bounded context
-       -> KV for owned layers only
-       -> lease, memory accounting and lifecycle
-```
-
-Required operations:
-
-- Prefill append.
-- Decode append.
-- Truncate after rejected speculative positions if later enabled.
-- Explicit release.
-- TTL/LRU eviction.
-- Cache-miss response.
-- Stale-epoch rejection.
-
-A node must not clear global KV on a new stream or serialize all requests behind one logical serving sequence.
-
-## Continuous batching
-
-Autoregressive dependencies remain sequential inside one Route Session. Aggregate throughput comes from batching compatible decode steps across active sessions:
-
-```text
-time 0: session A token 1 + session B token 8 + session C token 3
-          -> one llama batch for this Shard
-
-time 1: next ready positions from active sessions
-          -> next llama batch
-```
-
-The node scheduler:
-
-- Admits work against weight, KV, scratch and queue budgets.
-- Keeps per-session token positions and outputs separate.
-- Prevents long prefill from starving decode.
-- Applies bounded backpressure.
-- Reports active sessions, queue depth, batch occupancy, KV pressure and throughput.
-
-The initial deterministic gate is four concurrent sessions on a small model without cross-talk. Hardware-specific limits are measured and advertised through capability admission.
-
-## Parallelism boundaries
-
-| Mechanism | First-runtime use |
-|---|---|
-| Layer/pipeline parallelism | Public Inference Route across contiguous Shards |
-| Continuous batching | Inside every node across active Route Sessions |
-| Data parallelism | Multiple complete routes for independent requests |
-| Tensor parallelism | Deferred to a trusted composite node/managed cluster |
-| Expert parallelism | Deferred to a trusted composite node/managed cluster |
-| Disaggregated prefill | Deferred until core route performance passes |
-| Speculative decoding | Deferred optimization |
-
-Public WAN tensor/expert collectives are rejected for the first runtime because their per-layer communication and static rank assumptions conflict with heterogeneous volunteer nodes.
-
-## Optional providers
-
-### Transformers/safetensors
-
-Remains:
-
-- Correctness/reference backend.
-- Fallback for unsupported architectures.
-- Baseline for performance and output quality.
-
-### vLLM
-
-May run unmodified as a complete model or managed TP/PP/EP cluster represented as one logical provider. Its internal ranks are not independently routed or rewarded.
-
-Borrow only concepts such as named bundles, continuous batching, typed compatibility fingerprints, explicit transfer lifecycle and load telemetry.
-
-### Whole-model llama.cpp
-
-Provides a local proxy backend, correctness oracle and performance baseline. It is not the native distributed milestone.
-
-## Artifact and recipe compatibility
-
-A routable recipe identifies separately:
-
-- Source Model Artifact hash and optional derivative/slice hash.
-- Architecture and adapter version.
-- Tokenizer revision and vocabulary.
-- Weight quantization.
-- Activation interchange dtype/schema.
-- Backend compute dtype and backend implementation.
-- KV dtype/layout.
-- RoPE/context parameters.
-- llama.cpp commit and project patch version.
-- Shard range and endpoint ownership.
-
-Compatibility fails closed. Similar quantization labels or model names are not enough.
-
-## Admission and failure
-
-A recipe becomes routable only after a real local and distributed forward passes. Synthetic tests remain unit coverage.
-
-Alpha failure behavior:
-
-- Deadline or node loss cancels the Route Session.
-- Every node releases KV and queued buffers.
-- Uncertain mutations are not replayed silently.
-- Retry starts from token zero on a newly compatible route.
-- No cross-node KV import is trusted until a later signed/compatible snapshot protocol exists.
-
-## Performance release contract
-
-Before native development proceeds, compare the current Transformers/safetensors backend with whole-model llama.cpp under controlled model/hardware/quality lanes.
-
-Final release compares distributed GGUF with distributed safetensors using thresholds locked before seeing final results.
-
-Required measurements:
-
-- TTFT.
-- Prefill and decode tokens/sec.
-- Aggregate concurrency throughput.
-- p50/p95 latency.
-- Seam bytes and latency.
-- Queue/batch occupancy.
-- RSS, VRAM and KV pressure.
-- Output-quality drift.
-- Cancellation/failure cleanup.
-
-The GGUF path ships only if it is faster at acceptable quality or enables a larger otherwise-unroutable model at useful measured speed.
-
-## Implementation sequence
-
-1. Preserve completed DGR-001 performance and DGR-002 protocol contracts.
-2. DGR-017 locks exact GLM-5.2 Max artifact, resource, and alpha acceptance identity.
-3. Define exact recipe identity and pin one reproducible llama.cpp boundary.
-4. Run two lanes in parallel: DGR-018 establishes the whole-model `UD-IQ1_S` oracle on 224+ GiB usable memory, while DGR-005/DGR-006 implement range loading and named boundary parity with a cheap dense fixture.
-5. DGR-019 adds explicit GLM-5.2 MoE/MLA/DSA/IndexShare semantics after both lanes pass.
-6. Implement local KV; build and integrate the standalone worker.
-7. Pass local two-process and real two-physical-machine execution.
-8. Harden cancellation, node loss, restart, and cleanup required by alpha.
-9. DGR-020 executes the exact multi-node target and emits immutable `alpha` or `stop`.
-10. Post-alpha: continuous batching, final comparison, longer context, MTP, and package optimization.
-11. Prepare narrow upstream patches/tests; add Qwen as later architecture expansion.
-
-See [the Ralph backlog](prd.json) and [implementation strategy](implementation-strategy.md).
+Compatible sessions may be continuously batched within a worker while retaining isolated positions/state. Admission bounds weights, local state/KV, scratch, fragments, and queues. Uncertain cross-route mutation is not replayed. Registration can show an uncertified lane, but existing admission keeps it unroutable until signed/versioned real-hardware evidence exists.

.scratch/distributed-gguf-runtime/decision-framework.md

@@ -1,270 +1,40 @@
-# Distributed GGUF Decision Framework
-
-> **Superseded for active implementation decisions.** The grill was resolved on 2026-07-13. Use [implementation-strategy.md](implementation-strategy.md), [architecture.md](architecture.md), [ADR-0020](ADR-0020-distributed-gguf-runtime.md), and [prd.json](prd.json). This file remains as historical decision rationale.
-
-This framework is for grilling open decisions. It keeps decisions tied to project vocabulary and implementation gates instead of vague "distributed inference" language.
-
-## Core Vocabulary
-
-Use the existing domain terms this way:
-
-- **Shard**: contiguous transformer layer range. This is the compute, routing, cache, and reward unit.
-- **Shard Swarm**: storage/download group for artifacts needed by a shard.
-- **Inference Route**: ordered node sequence that covers all layers for one request.
-- **Route Session**: one active request bound to one inference route and stable session id.
-- **Hot KV State**: live per-shard cache held by the route node during a route session.
-- **Prefix Snapshot**: persisted route-session state used for reuse or failover, not the hot decode path.
-- **Artifact Manifest**: canonical mapping from model artifacts to semantic model parts and runtime support.
-- **Generation Telemetry**: realtime progress for a route session, including phase and tokens/sec, independent of whether token deltas are streamed.
-
-## The Five Planes
-
-### 1. Control Plane
-
-Owner: Tracker.
-
-Responsibilities:
-
-- node registry
-- coverage map
-- route selection
-- rebalance directives
-- route-session creation
-- health and telemetry
-- client-visible Generation Telemetry
-- billing/audit records
-
-Must not do:
-
-- serve hot KV during every token
-- become the only place model artifacts can be fetched
-
-### 2. Artifact Plane
-
-Owner: Shard Swarms, local node storage, optional CDN/bootstrap mirrors.
-
-Responsibilities:
-
-- GGUF/safetensors/tokenizer download
-- content-addressed verification
-- local artifact inventory
-- artifact-to-layer mapping
-- cache eviction
-
-Must not do:
-
-- define execution order by file split alone
-- imply that a downloaded file chunk equals a Shard
-
-### 3. Execution Plane
-
-Owner: active Inference Route.
-
-Responsibilities:
-
-- chunked prefill
-- one-step decode
-- hidden-state transfer across activation seams
-- start-layer handling for overlapping shards
-- backpressure
-
-Must not do:
-
-- resend full context activations during decode
-- require cross-node tensor parallel all-reduce for public v1
-
-### 4. Session State Plane
-
-Owner: route nodes for hot KV; cache servers only for snapshots.
-
-Responsibilities:
-
-- per-shard local KV ownership
-- cache allocation and eviction
-- cache ABI compatibility
-- session close/release
-- optional prefix snapshots
-
-Must not do:
-
-- centralize hot KV in a remote service
-- let a replacement node continue from incompatible state
-
-### 5. Economics And Trust Plane
-
-Owner: tracker plus settlement/validation components.
-
-Responsibilities:
-
-- distinguish storage/seeding work from inference work
-- account for prefill and decode separately
-- record route participation
-- sample validation events
-- slash proven fraud
-
-Must not do:
-
-- pay a node for merely holding files as if it generated tokens
-- hide public-swarm privacy limits from clients
-
-## Hard Invariants
-
-These are the framework rules unless we deliberately write a new ADR:
-
-1. Public-network Shards are contiguous layer ranges.
-2. Hot KV State is local to the node serving that Shard in that Route Session.
-3. Artifact distribution and route execution are separate systems.
-4. Decode seam payload must be `O(hidden_size)`.
-5. Prefill may be `O(sequence_length * hidden_size)`, but only in bounded chunks.
-6. The tracker chooses routes; nodes do not negotiate route topology peer-to-peer.
-7. Model/backend-specific cache internals stay behind backend capability reports.
-8. PyTorch remains the correctness/reference backend while llama.cpp/GGUF becomes the performance backend.
-9. Streaming responses are preferred when feasible; Generation Telemetry is always required.
-
-## Resolved Gates
-
-### Gate 1: Public Shard Semantics
-
-Decision: public-network Shards are contiguous transformer layer ranges. Tensor-parallel or ring-style execution is allowed only inside one trusted node, one colocated pod, or a future composite node abstraction.
-
-Rationale:
-
-- Layer ranges match the existing `Shard`, `Coverage Map`, `Inference Route`, billing, and fraud vocabulary.
-- Public volunteer nodes should not require cross-node all-reduce or tight per-layer synchronization in v1.
-- Existing projects such as prima.cpp and Distributed Llama can still inform local-cluster/backend execution without becoming the public routing primitive.
-
-Consequences:
-
-- Artifact Manifests must map files/tensors to semantic layer ranges.
-- Route selection remains ordered layer coverage.
-- Rewards can be attributed to layer-range work.
-- Hot KV State is naturally owned by the node serving that layer range for the Route Session.
-
-### Gate 2: Hot KV Strategy
-
-Decision: v1 rejects centralized hot KV. Hot KV State is local to the node serving the relevant Shard in the active Route Session. Cache servers may store Prefix Snapshots for reuse, retry, or failover, but they are not in the per-token decode path.
-
-Rationale:
-
-- Decode is the tight loop; adding remote cache I/O there makes latency and bandwidth worse at the worst point.
-- Local KV naturally follows layer-range Shard ownership.
-- Centralized hot KV increases privacy exposure and creates consistency problems.
-- Prefix Snapshots preserve the useful part of central storage without making it mandatory for every generated token.
-
-Consequences:
-
-- Route Session must be sticky.
-- Failover is limited in alpha unless a compatible Prefix Snapshot exists.
-- Cache servers are optimization infrastructure, not required runtime infrastructure.
-- Route repair requires compatible model revision, layer range, backend cache ABI, and snapshot position.
-
-### Gate 3: First Runtime Proof
-
-Decision: prove distributed Route Session and Hot KV State semantics in the existing PyTorch route before modifying llama.cpp/GGUF.
-
-Rationale:
-
-- PyTorch exposes model internals and cache objects more directly, so it is the fastest way to validate the distributed protocol.
-- The current distributed PyTorch route already has the right high-level shape but disables cache and recomputes full prompts.
-- Fixing that path gives us a reference implementation for correctness tests, telemetry, session lifecycle, and wire protocol behavior.
-- llama.cpp/GGUF should receive a clear target ABI rather than becoming both the protocol experiment and the performance backend at once.
-
-Consequences:
-
-- Issue 02 precedes issue 05.
-- llama.cpp collaboration has a concrete target ABI.
-- The PyTorch route remains the architecture-coverage/reference backend even after GGUF becomes the preferred performance path.
-- The first success metric is eliminating full-prompt recompute in distributed decode.
-
-### Gate 3A: Client Feedback During Latency
-
-Decision: streaming responses are preferred when feasible, and realtime Generation Telemetry is required regardless of streaming support.
-
-Rationale:
-
-- The product optimizes for access to large capable models, so some latency is acceptable.
-- Users still need confidence that the route is alive and roughly how fast it is generating.
-- Streaming token deltas give the best user experience when the backend exposes them cleanly.
-- Tokens/sec remains useful during prefill, queueing, and any backend that cannot stream token deltas.
-
-Consequences:
-
-- The gateway should stream token deltas through an OpenAI-compatible response when possible.
-- The gateway must expose progress through SSE, WebSocket, or polling.
-- The final answer can be delivered after completion only as a fallback.
-- Telemetry must include route phase, generated token count, and rolling tokens/sec.
-- Non-streaming clients still need realtime telemetry.
-
-### Gate 4: llama.cpp Collaboration Shape
-
-Decision: target upstreamable `libllama`/ggml hooks instead of planning around a permanent fork.
-
-Rationale:
-
-- llama.cpp changes quickly across model support, quantization, kernels, and hardware backends.
-- A permanent fork would become expensive to maintain and would lag upstream improvements.
-- A short-lived prototype branch is acceptable if it proves the API and makes upstream collaboration concrete.
-- Keeping tracker/routing logic outside llama.cpp makes the upstream ask smaller and cleaner.
-
-Consequences:
-
-- Need a minimal reproducible localhost demo before asking upstream to carry the design.
-- Need to separate "what llama.cpp should expose" from "what our tracker does".
-- Desired upstream surface is layer-range execution, hidden-state boundary I/O, partial loading/introspection, and per-session KV ownership.
-- If upstream rejects the shape, we revisit whether to carry a narrow adapter fork or keep GGUF distributed execution as experimental.
-
-### Gate 5: First Model Target
-
-Decision: use a two-tier model target. Use a small, boring, llama.cpp-supported GGUF model for the first protocol smoke test. Use `deepseek-ai/DeepSeek-V4-Flash` as the first serious large-model target. Keep GLM-5.2 and Ornith as later support audits.
-
-Rationale:
-
-- The first protocol proof should isolate route/session/KV bugs from model-architecture bugs.
-- DeepSeek-V4-Flash is a strong first serious target because it is much smaller than 1.6T-class models while still being large enough to validate the product thesis.
-- DeepSeek-V4-Flash still has architecture-specific risks, so it should not be the first smoke test.
-- GLM-5.2 and Ornith remain valuable targets, but they add DSA/MLA/hybrid attention uncertainty.
-
-Consequences:
-
-- 128K cache accounting can be modeled now.
-- The first "real" target-model audit is DeepSeek-V4-Flash support in PyTorch, vLLM/SGLang, and any available GGUF/llama.cpp quantization path.
-- Production support waits for backend capability reports and exact cache ABI support.
-
-### Gate 6: Failure Semantics
-
-Decision: alpha fails Route Sessions on route-node loss instead of attempting automatic route repair.
-
-Rationale:
-
-- Route repair requires compatible Prefix Snapshots, cache ABI checks, replacement-node selection, billing correction, and client stream/error recovery.
-- Local Hot KV State means a replacement node cannot continue unless it has compatible state at the same position.
-- Fail-fast keeps the first implementation correct while the session/KV protocol is still being proven.
-
-Consequences:
-
-- Better observability and explicit errors are required.
-- Snapshotting becomes a later feature, not a blocker for first inference.
-- Generation Telemetry must report the last known phase and failure reason.
-- Client or gateway retry starts a new Route Session from scratch.
-
-### Gate 7: Transport
-
-Decision: keep binary HTTP for v1 activation transfer instead of jumping immediately to QUIC, WebRTC, or a custom transport.
-
-Rationale:
-
-- ADR-0008 already defines binary activation bodies with HTTP headers.
-- HTTP keeps the first implementation debuggable with the existing server stack and tooling.
-- The core risk is route/session/KV correctness, not transport optimization.
-- QUIC/WebRTC can be introduced later behind the same activation protocol once semantics are proven.
-
-Consequences:
-
-- Focus benchmark work on payload shape, chunking, and cache behavior first.
-- QUIC/WebRTC can be introduced as an optimization behind the same activation protocol.
-- v1 implementation can reuse the current HTTP routing, relay, and observability infrastructure.
-- Transport abstraction should be kept narrow enough that HTTP can be replaced later without changing backend cache semantics.
-
-## Grilling Progress
-
-Gates 1, 2, 3, 3A, 4, 5, 6, and 7 are resolved. The remaining work is to convert the resolved framework into implementation-ready issue briefs and prototype milestones.
+# Distributed GGUF Runtime decision framework
+
+> **Specification status:** planning artifacts only. No distributed GGUF runtime is implemented. DGR-017 cleanup is complete; no runtime implementation story has completion credit. `prd.json` is authoritative.
+
+## Decision order
+
+1. DGR-019 locks comparable lanes and thresholds before results.
+2. DGR-020 runs safetensors and whole-model llama.cpp only, then returns `go`, `optimize baseline`, or `stop`.
+3. Dense and V4 work must prove parity, independent per-stage execution, local-state isolation, bounded failure, and measured resources.
+4. DGR-054 returns `alpha`, `optimize measured bottleneck`, or `stop`; MTP is explicitly off.
+5. Post-alpha optimizations must be selected from profiles, not assumptions.
+6. DGR-070 returns `beta`, `targeted optimization`, or `stop/rollback`, and requires MTP and the exact certified hardware/recipe matrix.
+
+## Interpretation rules
+
+- Quant/model-fit gains are separate from runtime/kernel/transport gains.
+- Fixture, real-model, real-hardware, and release evidence are never interchangeable.
+- 2–4 and 10+ stages are certification scenarios only.
+- Existing routing policy is certified, not redesigned.
+- Build success is not hardware certification; dark lanes remain unroutable.
+- Route loss uses cache miss and re-prefill/restart, never WAN cache migration.
+
+## Locked scope
+
+- Existing Meshnet Tracker routing, load balancing, billing, telemetry, relay, and provider semantics are backend-agnostic and are **not redesigned**. GGUF contributes exact compatibility, range/capacity, queue/load, seam-cost, health/reliability, and certification inputs only.
+- The data plane is a standalone project-owned C++ Shard worker with gRPC/Protobuf and a project-owned `ShardEngine` boundary.
+- llama.cpp is fetched at one exact commit into an ignored workspace from an in-repo manifest, then a numbered minimal patch stack is applied. There is no submodule, vendored tree, or permanent-fork dependency.
+- llama.cpp owns DeepSeek V4 graphs, mHC, MoE, attention, hash routing, and kernels. Meshnet adds only range-ownership hooks, typed boundary/local-state adapters, worker integration, and parity/certification.
+- Quantization and placement are dynamic recipe inputs. The 2–4 and 10+ stage layouts are certification scenarios, never product constants.
+- Per-shard Hot KV and V4 CSA/HCA/SWA/indexer/compressor state remain local and keyed by route session/epoch. The WAN seam carries the typed mHC 4×4096 residual boundary, positions, token-ID sideband where required, and schema/cache expectations—not per-layer caches.
+- Route changes use cache miss plus re-prefill/restart. There is no WAN KV or V4 auxiliary-cache migration.
+- CPU/CUDA/ROCm/Vulkan/Metal compile lanes are planned; only exact real-hardware-certified backend/model/recipe lanes may be advertised.
+- Alpha requires correctness and the pre-locked useful-speed gate. MTP is reserved and off for alpha; its ownership contract, implementation, and benchmark are required before beta.
+
+## Target identities
+
+- DeepSeek V4 official target SHA: `60d8d70770c6776ff598c94bb586a859a38244f1`.
+- llama.cpp V4 support lineage began at PR 24162 / merge `8c146a8366304c871efc26057cc90370ccf58dad`; DGR-027 later pins one exact validated current commit.
+- V4 scope: 43 main layers plus MTP; mHC 4×4096 boundary; 256 routed + 1 shared experts with six routed active; token IDs required for the first three hash-routed layers.
+- Exact split-GGUF artifacts are provisioned to mounted-drive storage with a complete hashed manifest and resumable verification; no model artifact may be placed under `/home`.

.scratch/distributed-gguf-runtime/evidence/DGR-017/README.md

@@ -1,275 +1,114 @@
-# DGR-017 — Lock the GLM-5.2 Max target and alpha contract
+# DGR-017 evidence — superseded backlog cleanup
 
-Status: **done**. Every acceptance criterion is met with real command output.
+**Completed:** 2026-07-16
+**Branch:** `ralph/distributed-gguf-runtime`
+**Planning checkpoint before cleanup:** `81b1fa6`
+**Authority:** `.scratch/distributed-gguf-runtime/prd.json`
 
-Evidence class: **real upstream metadata + deterministic arithmetic**. No weight
-payload was downloaded, no model was loaded, no GPU was used, and no benchmark was
-run — and none is claimed. This story makes the target *reviewable before* the
-216.7 GB download, which is exactly its job.
+## Outcome
 
-## 1. Summary
+The old DGR-001…016 completion claims and active artifacts were reconciled against the live branch. No old pass state transferred to the new implementation roadmap.
 
-The alpha target is now pinned, planned, and sealed:
+The active `packages/` and `tests/` trees were restored exactly to `origin/master`. The branch therefore no longer exposes a nominal GGUF startup path backed by unimplemented transport methods, a protobuf-only native scaffold, or isolated synthetic scheduler/cache/failure modules as if they were a working distributed GGUF runtime.
 
-- **Identity.** `zai-org/GLM-5.2` @ `b4734de4facf877f85769a911abafc5283eab3d9` and
-  `unsloth/GLM-5.2-GGUF` @ `abc55e72527792c6e77069c99b4cb7de16fa9f23`, quantization
-  `UD-IQ1_S`, six shards, 216,715,360,960 bytes, every shard's LFS SHA-256 resolved.
-- **Architecture.** The config/tokenizer/chat-template metadata the runtime cannot
-  shard without, hashed at the pinned revision.
-- **Resources.** A deterministic planner that counts unified memory once, applies the
-  `max(20% , 8 GiB)` reserve, and reports the arithmetic minimum and the recommended
-  node count as two different numbers.
-- **Contract.** The roadmap's section-5 acceptance matrix as a machine-readable,
-  digest-sealed document, locked before the target ever runs and cross-bound to the
-  exact manifest and architecture-snapshot digests.
-- **Upstream.** A refreshed llama.cpp/donor status report.
+## Classification and disposition
 
-Three findings are worth a reader's attention.
+### Retained
 
-**Every number in the roadmap reproduced from primary sources.** The 216,715,360,960
-byte total, the 201.832 GiB figure, the whole KV table (0.73 / 0.77 / 0.89 / 1.68 GiB
-at 16K, through 46.62 / 49.41 / 56.98 / 107.25 GiB at 1M), and the whole tier table
-(9 / 6 / 4 / 3 / 2 arithmetic minimum nodes) fall out of the exact config and the
-exact shard bytes. The roadmap was not approximating. The planner is written as a
-*reproduction* of those tables, so if the arithmetic ever stops matching, a test says
-which numbers moved.
+- Accepted ADRs and repository research, including `docs/research/colibri-implementation-audit.md`.
+- The authoritative 55-story roadmap `DGR-017…071` and its generated issue specifications.
+- The real public-relay smoke benchmark, moved with provenance to `legacy-public-relay-smoke-benchmark.json`.
+- Git history containing the complete superseded implementation/reference work.
 
-**The roadmap's "recommended" column is an imbalance factor of exactly 1.10.** Nodes
-= `ceil(total x 1.10 / budget)` yields 10 / 6 / 5 / 3 / 3 for the 32 / 48 / 64 / 96 /
-128 GiB tiers — precisely the roadmap's recommendations. That constant is now named
-(`PLACEMENT_IMBALANCE_FACTOR`) and documented as a placeholder for measured
-per-tensor placement, not a fudge factor to be tuned once results are in.
+### Removed from the active tree
 
-**224 GiB aggregate does not actually fit.** Two 112 GiB nodes hit the 224 GiB
-"hard-fit floor" exactly, and still come up **23.5 GiB short** once each node honours
-its reserve. That is what makes 224 GiB an *experimental floor* rather than an
-envelope, and it is now a test, not a caveat in prose. Relatedly, the 2×128 and 4×64
-"fit probe" topologies fit with only **2.08 GiB of headroom across the entire route** —
-which is why they require measured placement evidence and are not the recommendation.
+- Legacy issue specifications DGR-001…016 and their stale/blocked/synthetic evidence directories.
+- The nonfunctional `gguf_backend` startup path whose gRPC execution methods raised not-implemented errors.
+- Synthetic/reference-only boundary, Hot KV, scheduler, failure, recipe, ownership, and native-protocol modules that were not a real llama.cpp Shard runtime.
+- The protobuf round-trip-only native scaffold, placeholder llama.cpp patch, generated bindings/build workspace, and associated tests.
+- Tracker/admission/source modifications coupled to that superseded scaffold.
 
-## 2. Files changed
+### Confirmed absent and still required
 
-New — runtime-loadable package (single source of truth):
+- Real standalone C++ gRPC Shard worker.
+- Exact pinned llama.cpp manifest and verified patch stack.
+- Range-aware GGUF tensor ownership and real ranged execution.
+- Real Shard-local llama.cpp KV/V4 auxiliary state.
+- DeepSeek V4 boundary adapter and ranged parity.
+- Real multi-machine DeepSeek V4 alpha or beta acceptance.
 
-| Path | What |
-|---|---|
-| `packages/node/meshnet_node/glm_alpha/__init__.py` | Public surface |
-| `packages/node/meshnet_node/glm_alpha/manifest.py` | Target manifest + architecture snapshot; fail-closed identity |
-| `packages/node/meshnet_node/glm_alpha/planner.py` | Memory / KV / seam planner; unified-memory de-duplication |
-| `packages/node/meshnet_node/glm_alpha/contract.py` | Immutable, digest-sealed alpha acceptance contract |
-| `packages/node/meshnet_node/glm_alpha/data/target-manifest.json` | The six pinned shards, sizes, SHA-256, URLs, licenses |
-| `packages/node/meshnet_node/glm_alpha/data/architecture-snapshot.json` | Pinned architecture + config/template hashes |
-| `packages/node/meshnet_node/glm_alpha/data/alpha-contract.json` | Sealed acceptance thresholds (`aab23220…`) |
-| `scripts/refresh_glm_target_manifest.py` | Re-resolve/verify pins from upstream metadata (`--check` / `--write`) |
-| `tests/test_glm_alpha_target.py` | 97 deterministic offline tests (99 after the late-review repair — see §4a) |
+These remain `passes: false` in DGR-018…071.
 
-New — evidence:
+## Before-cleanup baseline
 
-- `.scratch/distributed-gguf-runtime/evidence/DGR-017/README.md` (this file)
-- `.../commands.txt` — exact commands and real results
-- `.../resource-plan.json` — generated tier/route/seam/KV plan
-- `.../upstream-status.json` — refreshed llama.cpp and donor status
+Command:
 
-Modified:
-
-- `.scratch/distributed-gguf-runtime/issues/17-...md` — `Status: done`
-- `.scratch/distributed-gguf-runtime/prd.json` — DGR-017 `passes: true` (this story only)
-- `.ralph-tui/progress.md` — learnings
-
-The data files live **in the package**, not in evidence, because the runtime must load
-them (DGR-018 verifies downloads against these digests; DGR-003 folds the manifest
-digest into the recipe fingerprint). Duplicating them into evidence would create two
-sources of truth that could drift.
-
-## 3. Acceptance criteria
-
-| Criterion | Where it is proven |
-|---|---|
-| Pin both repos by exact observed revision; `UD-IQ1_S` is the alpha quant | `target-manifest.json`; `test_manifest_pins_both_repositories_by_exact_revision` |
-| Six filenames, exact bytes, LFS SHA-256, aggregate GB/GiB, license, URLs, no payload download | HF `paths-info` API (LFS pointer metadata); `test_manifest_resolves_all_six_shards…`, `test_manifest_aggregate_bytes_are_exact_and_self_consistent` |
-| Snapshot + hash architecture-critical config/tokenizer/chat-template metadata | `architecture-snapshot.json`; `test_snapshot_captures_the_architecture_critical_metadata`, `test_snapshot_hashes_the_config_and_chat_template_bytes` |
-| Deterministic minimum-node calc from exact bytes, Q8_0 KV @16K/c1, imbalance, reserve | `planner.plan_topology`; `test_topology_planner_reproduces_the_published_tier_table` |
-| 224 GiB is a hard-fit floor, not an envelope; recommend 5×64 or 3×96/128 | `test_224_gib_aggregate_is_a_hard_fit_floor_not_an_operational_envelope`, `test_the_recommended_topologies_are_five_by_64_or_three_by_96_or_128` |
-| Unified memory counted once; additive RAM+VRAM rejected | `NodeMemory.from_host`; `test_adding_integrated_gpu_memory_to_system_ram_is_rejected`, `test_unified_memory_is_counted_once` |
-| 2.5 GbE minimum / 10 GbE recommended; serial latency modelled apart from bandwidth | `planner.plan_seams`; `test_2_5_gbe_is_the_alpha_minimum_and_10_gbe_is_recommended`, `test_serial_seam_latency_is_modelled_separately_from_bandwidth` |
-| Identity/semantic/target-run/performance/reliability/storage criteria locked before execution | `alpha-contract.json` (sealed, `locked_before_target_execution: true`); `test_the_contract_locks_every_roadmap_acceptance_section` |
-| Refresh upstream llama.cpp + donor status; no broad fork/scheduler | `upstream-status.json`; `adoption_state: none adopted` |
-| Tests reject changed revisions, missing shards, coordinated digest/config substitutions, inconsistent bytes, duplicate unified memory, malformed telemetry, and post-result threshold mutation | 97 tests; see §5 |
-| Targeted pytest passes | `97 passed` |
-| Installed wheel includes and loads all locked JSON resources | Real wheel build/install plus `load_locked_target()` outside the source tree |
-| `compileall packages tests` | exit 0 |
-| `git diff --check` | exit 0 |
-| Default tests deterministic, download-free, credit-free, GPU-free | Pure JSON + arithmetic; the only network code is an opt-in script excluded from the suite |
-| Full deterministic `pytest -q` | **852 passed, 13 skipped** on final rerun |
-
-## 4. Real results
-
-```
-scripts/refresh_glm_target_manifest.py --check  -> match upstream (exit 0)
-pytest -q tests/test_glm_alpha_target.py        -> 97 passed
-build + install wheel; load_locked_target()     -> INSTALLED_WHEEL_PASS
-compileall -q packages tests                    -> exit 0
-git diff --check                                -> exit 0
-pytest -q                                       -> 852 passed, 13 skipped (253.30s)
+```bash
+.venv-rocm/bin/python -m pytest -q \
+  tests/test_performance_contract.py tests/test_native_shard_protocol.py \
+  tests/test_gguf_ownership.py tests/test_boundary_adapter.py \
+  tests/test_hot_kv_state.py tests/test_gguf_backend.py \
+  tests/test_batch_scheduler.py tests/test_failure_semantics.py \
+  tests/test_llama_worker_build.py tests/test_node_admission.py \
+  tests/test_node_capability.py tests/test_tracker_capability_admission.py
 ```
 
-Controller review found and fixed four gaps before the commit was accepted:
+Result:
 
-1. the initial wheel omitted `glm_alpha/data/*.json`, despite source-tree tests passing;
-2. the self-sealed contract did not bind the manifest/snapshot digests, so coordinated
-   shard-hash or architecture substitutions could be accepted;
-3. `--check` followed moving repository HEAD instead of validating immutable pins;
-4. non-finite resource telemetry could bypass ordinary range checks.
+```text
+216 passed, 2 skipped, 1 failed, 1 warning
+```
 
-Each failure now has either an adversarial regression test or a real installed-wheel /
-live-metadata gate. None of the provisional agent results were accepted on trust.
+The failure was a synthetic capability-test helper `KeyError: 'compatibility_fingerprint'`. The warning was a pre-existing heartbeat-thread `SystemExit` warning.
 
-The intermittent tracker cancellation race that DGR-001 and DGR-002 both recorded as
-flaky on a clean tree failed once in the final validation (`404` after the request
-completed), then passed **5/5** in isolation and passed in the integrated full-suite
-rerun above. This story touches no tracker code; the failed run is retained in
-`commands.txt` rather than hidden.
+## Cleanup verification
 
-### 4a. Late independent-review repair (2026-07-14)
+### Source equality
 
-During delayed DGR-003 review, two contract-continuity defects were found and
-fixed here: v1 now has an independently trusted digest pinned in code
-(`test_resealing_a_mutated_v1_contract_is_rejected`) and parsed nested contract
-state is recursively immutable. This added two tests; the suite is now
-**99 passed** (`commands.txt` §7 records the exact runs). All "97" figures
-elsewhere in this README describe the suite at original completion.
+Command:
 
-Planner output (`resource-plan.json`):
+```bash
+git diff --quiet origin/master -- packages tests
+```
 
-| Route | Fits | Headroom |
-|---|---|---:|
-| 5×64 GiB unified (recommended) | yes | +53.28 GiB |
-| 3×96 GiB unified (recommended) | yes | +27.68 GiB |
-| 3×128 GiB unified (recommended) | yes | +104.48 GiB |
-| 4×64 GiB (fit probe) | yes | **+2.08 GiB** |
-| 2×128 GiB (fit probe) | yes | **+2.08 GiB** |
-| 2×112 GiB (= 224 GiB floor) | **no** | −23.52 GiB |
-| 3×64 GiB | no | −49.12 GiB |
+Result:
 
-## 5. How the "no silent swap" claim is earned
+```text
+packages_tests_match_origin_master=yes
+```
 
-The story's whole purpose is to stop a later agent from changing the target after
-seeing a result. Each of those moves now has a test that names it:
+The staged cleanup removes approximately 15.3k obsolete source/test/evidence lines from the active branch.
 
-- swap the artifact → `test_a_changed_gguf_revision_is_rejected`
-- pin a branch instead of a commit → `test_a_branch_name_is_not_an_acceptable_revision_pin`
-- drop a shard → `test_a_missing_shard_is_rejected`
-- shrink a shard so it "fits" → `test_a_shard_size_edited_to_make_the_model_look_smaller_is_rejected`
-- change a valid-looking shard SHA without changing bytes → `test_coordinated_shard_hash_substitution_is_rejected_by_contract`
-- change internally consistent architecture metadata → `test_internally_consistent_architecture_substitution_is_rejected_by_contract`
-- take the bigger quant quietly → `test_swapping_in_a_different_quantization_is_rejected`
-- add iGPU "VRAM" to system RAM → `test_adding_integrated_gpu_memory_to_system_ram_is_rejected`
-- count one machine twice → `test_the_same_machine_counted_twice_in_a_route_is_rejected`
-- lower the speed floor → `test_lowering_the_speed_floor_after_seeing_a_result_is_rejected`
-- call a slow pass an alpha → `test_relabelling_a_speed_failure_as_a_pass_is_rejected`
-- admit the dense fallback → `test_admitting_the_dense_attention_fallback_after_the_fact_is_rejected`
-- shrink the reserve → `test_relaxing_the_per_node_reserve_after_the_fact_is_rejected`
+### Cleanup-relevant regression suite
 
-**Contract continuity is fail-closed.** The document’s `contract_sha256` detects
-accidental edits, and the approved v1 digest is pinned independently in code. A caller
-that changes a threshold and re-seals it under `glm-5.2-max-alpha/v1` is rejected by
-`test_resealing_a_mutated_v1_contract_is_rejected`; amendments require a new supported
-contract identity under human review. Parsed nested state is recursively immutable,
-so thresholds cannot change between validation and use; `to_dict()` returns an isolated
-copy rather than exposing the validated object.
+Command:
 
-## 6. Upstream status — the gating risk for DGR-004/DGR-018
+```bash
+.venv-rocm/bin/python -m pytest -q \
+  tests/test_node_admission.py tests/test_node_capability.py \
+  tests/test_tracker_capability_admission.py \
+  tests/test_kv_cache_distributed.py tests/test_real_distributed_inference.py
+```
 
-Refreshed against live GitHub on 2026-07-13. One item **changed** since the roadmap:
+Result:
 
-- **#24231 is now MERGED** (2026-07-11) — a generic `GGML_OP_LIGHTNING_INDEXER` exists.
-- #24770 MERGED (2026-06-20) — GLM-5.2 loads via a **dense-MLA compatibility path**.
-- **#25407 still OPEN** (updated today) — the real GLM DSA/IndexShare wiring.
-- #24730 still OPEN — the umbrella GLM-5.2 support request.
+```text
+119 passed, 2 skipped, 1 warning in 15.90s
+```
 
-**No released upstream llama.cpp performs native GLM-5.2 DSA + IndexShare today.** A
-stock pin taken now would load the artifact and emit text through the dense fallback —
-which the alpha contract explicitly refuses (`dense_attention_fallback_satisfies_alpha:
-false`). DGR-018 must therefore prove those paths are *active*, not that output appeared.
+The warning is the same pre-existing heartbeat-thread `SystemExit` warning.
 
-Donor policy holds, and the evidence now supports it more strongly than before: PR
-#25407 is **12 files, +414/−7**. The semantics alpha needs are small enough to track
-and reproduce upstream. That is the argument against adopting Mesh-LLM's 261-patch
-fork — recorded as a donor (Apache-2.0, branch head `9bd18f15`, 2026-07-12), nothing
-adopted here.
+### Known `origin/master` limitations
 
-## 7. Limitations and deferred work
+The wider routing run produced `210 passed, 2 skipped, 4 failed, 1 warning`. Each failure reproduced individually while `packages/` and `tests/` matched `origin/master` exactly:
 
-- **No artifact was downloaded or loaded.** Sizes and SHA-256 come from Hugging Face
-  LFS pointer metadata. DGR-018 must verify the digests against the real files on
-  mounted storage before route admission. A matching size with a wrong hash is exactly
-  the failure this manifest exists to catch, and only a local verify can catch it.
-- **`PLACEMENT_IMBALANCE_FACTOR = 1.10` is a planning assumption, not a measurement.**
-  It reproduces the roadmap's recommendations, but the real per-node share depends on
-  exact tensor bytes (embeddings, output head, dense vs MoE layers, shared experts,
-  indexer tensors, quant block alignment). DGR-019 must replace it with measured
-  placement. Until then, arithmetic-minimum topologies (2×128, 4×64) stay fit probes.
-- **KV numbers are planning estimates, not admission truth.** The planner deliberately
-  budgets the *conservative* indexer layout (keys across all 78 layers, not just the 21
-  Full ones) so a route admitted here cannot be surprised by the implementation it
-  actually gets. The runtime must still report measured allocated/resident MLA and
-  indexer cache per shard.
-- **Peak scratch is unmodelled.** The reserve exists precisely because backend
-  workspaces and graph scratch are not predictable from the artifact; measured peak
-  must land inside the reserve, and the contract requires that evidence.
-- **Upstream is moving fast.** #25407 was updated the same day it was observed. Refresh
-  `upstream-status.json` before DGR-004 picks a llama.cpp pin. The manifest script's
-  `--check` deliberately validates the immutable Hugging Face pins, not moving HEAD.
+- `test_tracker_models_endpoint_lists_registered_hf_repo_and_short_name_alias`
+- `test_torch_node_applies_tracker_load_shard_directive`
+- `test_shard_heal_cycle_surviving_node_covers_dead_peers_gap`
+- `test_a_node_with_an_unusable_precision_covers_no_layers`
 
-## 8. Compatibility and migration notes
+They are recorded as pre-existing baseline defects and were not repaired or hidden by this cleanup story.
 
-- Purely additive. No existing module, wire format, or test changed. Nothing in this
-  story is on a live request path.
-- `meshnet_node.glm_alpha` has **no heavy imports** — no torch, no transformers, no
-  network at import time — so a tracker or planner can read the target contract without
-  paying for a model runtime.
-- Re-pinning is deliberately awkward: `--write` follows current HEAD and leaves the
-  existing contract binding invalid until a new contract is reviewed and sealed.
-  `--check` uses revision-specific APIs and exits non-zero rather than healing any
-  integrity drift in the already locked target.
+## Dependency handoff
 
-## 9. Handoff to dependent stories
-
-**DGR-003 (recipe identity):** fold `TargetManifest.digest`
-(`0b6aed04479d204902bb64c0203f1a46cab26a47b378ecccf85237b63f6c1962`) and
-`ArchitectureSnapshot.digest` (`253fbd94…`) into the runtime recipe fingerprint. The
-GLM fields the roadmap asks you to add (DSA/IndexShare metadata, context max, expert
-counts) are already resolved in `architecture-snapshot.json` — read them, do not
-re-derive them by hand. Populate the DGR-002 `Fingerprint` message; do not invent a
-second identity struct.
-
-**DGR-004 (llama.cpp pin):** read `upstream-status.json` first. Any pin taken before
-#25407 merges gives you the dense-MLA fallback, which cannot satisfy alpha. Track
-#25407 (12 files) as a numbered patch; do not adopt the Mesh-LLM fork.
-
-**DGR-018 (whole-model oracle):** the six digests in `target-manifest.json` are what you
-verify the download against. Your host needs ≥224 GiB runtime-accessible memory — and
-note that 224 GiB is the *floor*, not a comfortable target (see §1). Prove DSA,
-IndexShare, shared expert, and the Max template are **active**; the contract's
-`require_rendered_reasoning_effort_marker` is `<|system|>Reasoning Effort: Max`. Assert
-the rendered marker, not the request field: the template's only non-max level is
-`'high'`, so *every other value — including an absent one — renders Max*, and "the
-request said max" proves nothing.
-
-**DGR-019 (GLM semantics):** the IndexShare split is **21 Full producer layers and 57
-Shared consumers**, in a `[full, full, full] + repeating [shared, shared, shared, full]`
-pattern. Prefer shard boundaries that keep an ownership group whole; the 8 KiB
-(2048 × int32) top-k sideband is the cost when you cannot. Replace
-`PLACEMENT_IMBALANCE_FACTOR` with measured per-tensor placement.
-
-**DGR-020 (alpha verdict):** load the target with `load_locked_target()`. It verifies
-the contract seal and cross-binds the manifest and architecture snapshot before
-returning them. Judge against
-`contract.threshold(section, key)` — an unlocked threshold raises rather than
-defaulting, so a criterion cannot be invented at read time. The verdict is `alpha` or
-`stop`; there is no third outcome, and a quality pass with a speed failure is `stop`.
-
-**Everyone:** unified system RAM and integrated-GPU memory are one pool. Build nodes
-with `NodeMemory.from_host(..., unified=True)` and it is impossible to write the
-double-count; pass a GPU size alongside `unified=True` and it raises rather than
-silently ignoring the argument.
+DGR-018 and later stories must start from the cleaned upstream-equivalent runtime tree. Reuse concepts from superseded commits only by explicitly porting the smallest verified slice under the new story’s contracts, tests, and evidence gates. Git history is provenance, not completion evidence.

.scratch/distributed-gguf-runtime/evidence/DGR-017/legacy-public-relay-smoke-benchmark.json

@@ -0,0 +1,83 @@
+{
+  "schema_version": 1,
+  "executed_at_utc": "2026-07-15T10:41:14Z",
+  "test_kind": "public-relay-single-node-streaming-smoke-benchmark",
+  "target": {
+    "public_chat_endpoint": "https://meshnet.2.d-popov.com/v1/chat/completions",
+    "relay_url": "wss://meshnet.2.d-popov.com/ws",
+    "model": "qwen2.5-0.5b-instruct",
+    "quantization": "bfloat16"
+  },
+  "recovery": {
+    "problem": "The local node's capability proof had expired and its port-7000 HTTP server had wedged with CLOSE-WAIT sockets.",
+    "action": "Gracefully restarted the local public-tracker meshnet-node process on port 7000.",
+    "startup_validation": {
+      "device": "cuda",
+      "capability_proof_ms": 336,
+      "node_id": "7j77FsPY-b32476219492",
+      "relay_addr": "wss://meshnet.2.d-popov.com/rpc/7j77FsPY1evV8tuf-7000"
+    }
+  },
+  "tracker_admission_after_recovery": {
+    "node_id": "7j77FsPY-b32476219492",
+    "alive": true,
+    "status": "ready",
+    "capability_state": "admitted",
+    "routable": true,
+    "route_hops": 1
+  },
+  "client_measurements": {
+    "warmup": {
+      "http_status": 200,
+      "ttft_ms": 420.8,
+      "elapsed_ms": 610.23,
+      "response_text": "MeshNet Relay Benchmark Passed"
+    },
+    "runs": [
+      {
+        "run": 1,
+        "ttft_ms": 376.04,
+        "elapsed_ms": 458.65,
+        "response_text": "relay benchmark pass"
+      },
+      {
+        "run": 2,
+        "ttft_ms": 258.33,
+        "elapsed_ms": 336.71,
+        "response_text": "relay benchmark pass"
+      },
+      {
+        "run": 3,
+        "ttft_ms": 288.26,
+        "elapsed_ms": 363.2,
+        "response_text": "relay benchmark pass"
+      }
+    ],
+    "p50_ttft_ms": 288.26,
+    "p50_elapsed_ms": 363.2
+  },
+  "tracker_relay_evidence": [
+    {
+      "status": 200,
+      "relay": true,
+      "node_id": "7j77FsPY-b32476219492",
+      "tokens": 11,
+      "elapsed_seconds": 0.1686,
+      "tokens_per_sec": 65.2541
+    },
+    {
+      "status": 200,
+      "relay": true,
+      "node_id": "7j77FsPY-b32476219492",
+      "tokens": 11,
+      "elapsed_seconds": 0.1891,
+      "tokens_per_sec": 58.1799
+    }
+  ],
+  "scope_and_remaining_work": {
+    "validated": "Public HTTPS chat endpoint routed a streaming request through the tracker relay to the local CUDA node and completed with HTTP 200.",
+    "not_validated": "Two-node shard routing was not run because the remote node 5gMLrmyB-88f5cba044d0 still had an expired capability proof and was not routable.",
+    "next_gate": "Refresh the remote node capability proof, then load a multi-node-compatible assignment and repeat the benchmark through the public tracker relay."
+  },
+  "reproduction": "Use a valid bearer API key with the public /v1/chat/completions endpoint and stream a short qwen2.5-0.5b-instruct request. Do not connect directly to private node HTTP endpoints; the tracker relay is the required path."
+}

.scratch/distributed-gguf-runtime/evidence/DGR-018/README.md

@@ -0,0 +1,204 @@
+# DGR-018 evidence — canonical Ralph and Gitea metadata schema
+
+**Completed:** 2026-07-16
+**Branch:** `ralph/distributed-gguf-runtime`
+**Authority:** `.scratch/distributed-gguf-runtime/prd.json`
+**Dependency:** DGR-017 (`evidence/DGR-017/README.md`) — cleaned backlog reconciled to `origin/master`; no old pass state transferred.
+
+## Objective
+
+Make `prd.json` the validated source from which Markdown (and, later, Gitea) issues
+can be generated losslessly, per
+`.scratch/distributed-gguf-runtime/issues/018-define-canonical-ralph-and-gitea-metadata-schema.md`.
+
+## Pre-existing state found (not caused by this story)
+
+Before any change in this session, `git status` showed `.scratch/distributed-gguf-runtime/prd.json`
+already modified in the working tree relative to `HEAD` (commit `369b207`), with no corresponding
+progress-log entry. Diffing against `HEAD` showed the working copy had **dropped** prd.json's
+top-level `sourceOfTruth`, `qualityGates`, `metadataSchema`, `milestones`, and `supersededStories`
+objects, while `userStories` itself was byte-identical to `HEAD`. This looked like an abandoned,
+uncommitted partial edit from a prior session, not intentional current work — those fields are
+exactly the schema/quality-gate/audit-provenance content this story depends on, and their loss
+wasn't explained by any acceptance criterion. They were restored (see "Changes" below) rather than
+silently accepted or discarded, per the instruction to investigate unexplained working-tree state
+before building on top of it.
+
+## Changes
+
+### `scripts/ralph_prd_schema.py` (new)
+
+Single module providing:
+
+- **Parse:** `load_prd(path)` — JSON load with clear `PrdValidationError`s for missing file /
+  invalid JSON / non-object document.
+- **Canonical schema registry:** `STORY_FIELDS` (name → required/type), `EXECUTION_MODES`,
+  `EVIDENCE_CLASSES`, `HARDWARE_FLAGS`, `UPSTREAM_FLAGS`, `TRIAGE_VALUES`. Covers every field named
+  in the acceptance criteria: stable `id`/`title`, `labels`, `milestone`, derived `type`
+  (`derive_type`), `dependsOn`, derived `blocks`, `triage`, `evidenceClass`, and
+  `hardware`/`model`/`upstream` flags.
+- **Structural validation:** `validate_schema(data)` — required fields, types, enum membership,
+  ID convention, `type:`/`priority:` label cardinality, non-empty `acceptanceCriteria`.
+- **Semantic validation:** `validate_semantics(data)` — unique IDs, unique titles, `dependsOn`
+  resolves to known stories (no self-dependency), dependency graph is acyclic (with a reported
+  cycle path on failure), `blocks` matches the dependency graph exactly (sorted set equality, not
+  superset), and `evidencePath` matches the per-story convention.
+- **Fresh vs. in-progress backlog:** `validate_fresh_backlog(data)` additionally requires every
+  story to start `passes: false` (for a backlog that hasn't started execution yet);
+  `validate_backlog(data)` is the composed check for a real, in-flight backlog where some stories
+  have legitimately completed.
+- **Self-consistency check:** `validate_metadata_schema_consistency(data)` — when prd.json declares
+  its own `metadataSchema`/`qualityGates` (as this one now does), verifies that self-documentation
+  hasn't drifted from what the validator actually enforces (enum sets, required/optional field
+  lists, presence of `qualityGates` and `generatedArtifactDisclaimer`). This is a no-op for minimal
+  fixture PRDs that don't carry that documentation.
+- **Generation (one-directional, prd.json → artifact):** `render_issue_markdown(story, data)`
+  renders the exact Markdown convention already used by
+  `.scratch/distributed-gguf-runtime/issues/*.md`, sourcing the "Shared quality gates" bullets from
+  `data["qualityGates"]` and the leading disclaimer from
+  `data["metadataSchema"]["generatedArtifactDisclaimer"]` (falling back to a module default only
+  when `data` omits them) — not from a duplicated Python string literal.
+  `to_gitea_issue_payload(story, data)` wraps the same body into a Gitea create-issue-shaped payload
+  (`title`, `body`, `labels`, `milestone`).
+- **Authority guard:** `check_generated_markdown_authority(text, disclaimer=...)` rejects generated
+  Markdown that's missing the disclaimer or that contains a conflicting authority claim (e.g. "this
+  file is authoritative"). There is deliberately no Markdown → prd.json parser, so a generated
+  artifact structurally cannot feed `passes` (or anything else) back into the authoritative source.
+- CLI: `python scripts/ralph_prd_schema.py validate <prd.json> [--fresh]` and
+  `... render <prd.json> <STORY-ID>`.
+
+### `.scratch/distributed-gguf-runtime/prd.json`
+
+- Restored the top-level `sourceOfTruth`, `qualityGates`, `milestones`, and `supersededStories`
+  objects to their `HEAD` content (see "Pre-existing state" above); `userStories` was already
+  identical to `HEAD` and is unchanged in content.
+- Extended `metadataSchema` (previously incomplete for this story's own acceptance criteria) with:
+  `requiredStoryFields` now also lists `notes` and `blocks` (present on all 55 stories); new
+  `optionalStoryFields: ["completionNotes"]`; new `hardwareValues`/`upstreamValues` enums (`model`
+  is documented as an open convention, not a closed enum, since quantization/model targets are
+  dynamic recipe inputs per `RALPH-CONTEXT.md`); new `typeDerivation` and `labelConventions`
+  (reserved prefixes, cardinality); new `generatedArtifactDisclaimer` (the exact string generated
+  artifacts must start with); extended `dependencyRules`/`authorityRule` prose to match what the
+  validator enforces.
+- Reworded `sourceOfTruth`'s stale "All stories are unimplemented ... passes=false" clause, which
+  was no longer accurate once DGR-017 completed.
+- Marked `DGR-018.passes = true` with `completionNotes` recording this story's outcome.
+
+### `.scratch/distributed-gguf-runtime/issues/018-define-canonical-ralph-and-gitea-metadata-schema.md`
+
+Regenerated via `render_issue_markdown` to reflect `passes: true` (checked acceptance criteria,
+"completed" status line, "Verified evidence" handoff line) — matching the same convention DGR-017's
+issue file already used for a completed story.
+
+### `tests/test_ralph_prd_schema.py` (new)
+
+108 deterministic, model-download-free, GPU-free tests:
+
+- **Parse** (4 tests): real backlog parses to 55 stories; missing file, invalid JSON, and
+  non-object documents raise `PrdValidationError`.
+- **Structural/semantic validation against the real backlog** (7 tests): passes `validate_schema`,
+  `validate_semantics`, and the composed `validate_backlog`; unique IDs/titles; all `dependsOn`
+  resolve; `blocks` matches the derived dependency graph for all 55 stories; no cycle; every
+  `passes: true` story carries `completionNotes` and an existing evidence README (a durable
+  invariant, not a hardcoded list of which stories have completed — that list will keep growing).
+- **Structural/semantic failure-mode fixtures** (13 tests): missing required field, bad enum, wrong
+  type, empty `acceptanceCriteria`, multiple `type:` labels, duplicate ID, duplicate title, unknown
+  dependency, self-dependency, dependency cycle, mismatched `blocks`, bad `evidencePath`.
+- **Fresh-backlog invariant** (3 tests): accepts all-`false`, rejects a premature `passes: true`,
+  and confirms `validate_backlog` (the in-progress variant) permits completed stories.
+- **prd.json-as-source-of-truth for boilerplate** (9 tests): `qualityGates`/`metadataSchema`
+  self-consistency checks (no-op without them, catches a drifted enum, catches a missing
+  `qualityGates`), `quality_gate_bullets` flattening order, `authority_disclaimer` precedence and
+  fallback, and 3 tests asserting the real backlog's declared schema matches the code, its 7
+  quality-gate bullets are intact, and its disclaimer matches the module default.
+- **`derive_type`** (4 tests): label-derived type, release-gate synthetic type for HITL gate
+  stories, `None` when absent, and confirmation that the real backlog's two release-gate stories
+  (`DGR-054`, `DGR-070`) derive `release-gate`.
+- **Markdown generation round trips** (55 parametrized + 6 tests): `render_issue_markdown` for
+  every story `DGR-017`..`DGR-071` is byte-for-byte identical to the corresponding file already in
+  `.scratch/distributed-gguf-runtime/issues/`; determinism; leading disclaimer; `Blocks (derived)`
+  rendering (`None` vs. listed); checkbox reflects `passes`; filename convention.
+- **Authority-claim rejection** (4 tests): accepts real generated text, rejects a missing
+  disclaimer, rejects an overriding claim, and confirms every committed issue file in
+  `.scratch/distributed-gguf-runtime/issues/` passes the check.
+- **Gitea payload generation** (3 tests): payload shape, body carries no information beyond what's
+  in prd.json, and every real story's payload is well-formed and authority-clean.
+
+## Commands and results
+
+```bash
+python3 -m pytest -q tests/test_ralph_prd_schema.py
+```
+```text
+108 passed in 0.16s
+```
+
+```bash
+python3 -m compileall -q packages tests
+```
+Exit code 0, no output (all files compile).
+
+```bash
+git diff --check
+```
+Exit code 0 (no whitespace errors).
+
+```bash
+python3 scripts/ralph_prd_schema.py validate .scratch/distributed-gguf-runtime/prd.json
+```
+```text
+OK: 55 stories validated.
+```
+
+```bash
+python3 scripts/ralph_prd_schema.py validate .scratch/distributed-gguf-runtime/prd.json --fresh
+```
+```text
+ERROR: DGR-017: fresh backlog requires passes=false, got True
+ERROR: DGR-018: fresh backlog requires passes=false, got True
+2 validation error(s).
+```
+Expected: `--fresh` is the invariant for a backlog that hasn't started execution; this backlog has
+legitimately completed two stories, so it correctly fails that stricter check while passing the
+plain (in-progress) `validate` command above.
+
+### Baseline: full repository suite (ad hoc `python3`, not a project venv)
+
+```bash
+python3 -m pytest -q
+```
+```text
+20 failed, 776 passed, 13 skipped, 2 warnings in 244.17s (0:04:04)
+```
+None of the failures touch `scripts/ralph_prd_schema.py` or `tests/test_ralph_prd_schema.py`
+(neither file existed before this story; this story adds no changes to `packages/`). Four of the
+20 failures reproduce exactly the pre-existing baseline defects DGR-017's evidence already recorded
+(`test_tracker_models_endpoint_lists_registered_hf_repo_and_short_name_alias`,
+`test_torch_node_applies_tracker_load_shard_directive`,
+`test_shard_heal_cycle_surviving_node_covers_dead_peers_gap`,
+`test_a_node_with_an_unusable_precision_covers_no_layers`). The remaining 16 (activation
+compression, dynamic routing, gossip/relay, manual route benchmark, openai gateway, TOPLoC
+calibration dispatch, tracker control plane) include a `ModuleNotFoundError: langchain` failure,
+indicating this ad hoc `python3` lacks the project's `dev` extras (`langchain-openai`, etc.) rather
+than a real regression; this environment has no project virtualenv (e.g. no `.venv-rocm`) to run
+against instead. Not investigated further as out of scope for this story.
+
+## Limitations
+
+- No real Gitea instance or API integration exists; `to_gitea_issue_payload` defines the payload
+  shape (title/body/labels/milestone) only. Creating issues against a live Gitea server is future
+  work, not claimed here.
+- `model` is intentionally validated as an open string, not a closed enum, per
+  `RALPH-CONTEXT.md`'s "Quantization and placement are dynamic recipe inputs" constraint; the schema
+  documents (`metadataSchema.modelConvention`) but does not restrict its value set.
+- Validation and generation were exercised only against this feature's `prd.json`
+  (`.scratch/distributed-gguf-runtime/prd.json`); `docs/prd.json` and other `.scratch/*/prd.json`
+  files in this repo use a materially different (simpler) shape and are out of scope.
+
+## Dependency handoff
+
+DGR-021 and DGR-025 (this story's derived `blocks`) may treat `prd.json`'s `metadataSchema`,
+`qualityGates`, and this validator/generator as stable. Any future field addition to a story shape
+must extend `STORY_FIELDS` in `scripts/ralph_prd_schema.py` and the corresponding
+`metadataSchema.requiredStoryFields`/`optionalStoryFields` in `prd.json` together —
+`validate_metadata_schema_consistency` fails closed if they drift apart.

.scratch/distributed-gguf-runtime/evidence/DGR-021/README.md

@@ -0,0 +1,101 @@
+# DGR-021 evidence — versioned named-tensor activation envelope
+
+**Completed:** 2026-07-17
+**Branch:** `distributed-gguf-runtime`
+**Authority:** `.scratch/distributed-gguf-runtime/prd.json`
+**Dependency:** DGR-018 (`evidence/DGR-018/README.md`) — canonical backlog schema / issue projection contract
+
+## Objective
+
+Establish the backend-neutral activation envelope used by direct and relayed Shard traffic, with stable versioning, named tensors, bounded fragmentation, checksum validation, and reserved extensibility for future state.
+
+## Changes
+
+### `packages/node/meshnet_node/protocol.py` (new)
+
+Added a self-contained activation-envelope module with:
+
+- `SCHEMA_NAME = "meshnet.activation-stream"` and `SCHEMA_VERSION = 1`
+- `TensorFragment`
+  - bounded byte fragments with offset, compression tag, checksum, and extension preservation
+  - deterministic `to_dict()` / `from_dict()` round-trip
+- `NamedTensor`
+  - named tensor metadata: `name`, `shape`, `dtype`, `byte_order`, `compression`, `checksum`, `fragments`
+  - fragmentation via `from_bytes(..., max_fragment_bytes=...)`
+  - checksum validation over reconstructed tensor bytes
+  - unknown-field preservation via `extensions`
+- `ActivationEnvelope`
+  - top-level fields for `request_id`, `work_id`, `route_session`, `route_epoch`, `shard_start`, `effective_start`, `phase`, `position`, and `idempotency_step`
+  - reserved extension fields for `token_id_sideband`, `architecture_state`, `recurrent_state`, and `mtp`
+  - deterministic canonical serialization (`to_bytes`) and round-trip parsing (`from_bytes`)
+  - size-limit enforcement (`to_bytes(max_bytes=...)`)
+  - conversion from a live `TensorPayload` into the envelope and back again
+
+### `packages/node/meshnet_node/model_backend.py`
+
+Extended `TensorPayload` with envelope conversion helpers:
+
+- `TensorPayload.to_envelope(...)`
+- `TensorPayload.from_envelope(...)`
+
+These keep the existing activation payload interface intact while exposing the new versioned envelope as the shared protocol layer.
+
+### `tests/test_activation_envelope.py` (new)
+
+Added focused deterministic tests covering:
+
+- deterministic envelope serialization and round-trip parsing
+- tensor fragmentation and checksum validation
+- unknown-field preservation at both envelope and tensor levels
+- size-limit rejection
+- `TensorPayload` ↔ envelope round-trip
+
+### `.scratch/distributed-gguf-runtime/prd.json`
+
+Marked `DGR-021.passes = true` and added completion notes recording the envelope implementation and verification commands.
+
+## Commands and results
+
+```bash
+pytest -q tests/test_activation_envelope.py
+```
+
+```text
+5 passed in 0.06s
+```
+
+```bash
+pytest -q tests/test_activation_envelope.py tests/test_kv_cache_distributed.py -k 'session_is_stable_and_decode_payloads_are_single_token or large_prefill_activation_survives_zstd_compressed_hop'
+```
+
+```text
+..                                                                       [100%]
+2 passed, 21 deselected in 1.84s
+```
+
+```bash
+python3 -m compileall packages/node/meshnet_node tests/test_activation_envelope.py
+```
+
+```text
+Listing 'packages/node/meshnet_node'...
+Listing 'packages/node/meshnet_node/native_protocol'...
+Compiling 'tests/test_activation_envelope.py'...
+```
+
+```bash
+git diff --check
+```
+
+```text
+No whitespace errors
+```
+
+## Limitations
+
+- The envelope is implemented as a canonical deterministic JSON contract with dataclasses and conversion hooks, not generated `.proto` classes. The environment had `protobuf` available but not the `grpc_tools` generation toolchain, so I did not materialize a compiled proto artifact here.
+- The direct/relayed HTTP/WebSocket transports remain byte-oriented; the envelope is the shared structured contract layered above those transports.
+
+## Dependency handoff
+
+DGR-022 and later shard-control stories can reuse the envelope contract and its `TensorPayload` conversion hooks as the stable activation metadata layer. Future work that requires generated protobuf code can replace the JSON serialization with a generated wire codec without changing the top-level field contract defined here.

.scratch/distributed-gguf-runtime/evidence/DGR-022/README.md

@@ -0,0 +1,46 @@
+# DGR-022 evidence — Shard lifecycle and structured status RPC contract
+
+**Completed:** 2026-07-17
+**Branch:** `ralph/distributed-gguf-runtime`
+**Authority:** `.scratch/distributed-gguf-runtime/prd.json`
+
+## Outcome
+
+Implemented the versioned, backend-neutral lifecycle/status contract consumed by a future generated gRPC binding. The contract keeps Meshnet routing, identity, authentication policy, billing, and llama.cpp ownership outside the worker contract.
+
+## Implemented
+
+- `packages/node/meshnet_node/shard_lifecycle.py`
+  - capability, health, session, cancellation, release, and metrics RPC names
+  - schema version negotiation and fail-closed unsupported-version handling
+  - structured status/error taxonomy with retryability and details
+  - lifecycle state machine for prefill/decode/cancel/release transitions
+  - monotonic idempotency-step enforcement and duplicate rejection
+  - bounded frame/byte flow control with cancellation-aware waits
+  - explicit cache expectation/result types
+  - deadline policy and TLS/auth transport hooks
+  - deterministic contract serialization round-trip
+- `tests/test_shard_lifecycle.py`
+  - contract round-trip and RPC coverage
+  - unsupported-version rejection
+  - malformed transition and idempotency rejection
+  - cancellation/release behavior
+  - bounded flow-control behavior
+  - TLS hook and incomplete-contract fail-closed behavior
+
+## Verification
+
+```text
+$ PYTHONPATH=packages/node pytest -q tests/test_shard_lifecycle.py tests/test_activation_envelope.py
+17 passed in 0.10s
+```
+
+The existing DGR-021 activation-envelope tests remain green alongside DGR-022.
+
+## Scope limitation
+
+This story defines the lifecycle/status contract only. Generated Python/C++ protobuf bindings and the concrete `shard_runtime.proto` generation pipeline are DGR-023 and remain separate.
+
+## Dependency handoff
+
+DGR-023 may consume the RPC names, status taxonomy, version identity, deadlines, flow-control limits, and TLS/auth hooks when the canonical `.proto` schema and toolchain are provisioned.

.scratch/distributed-gguf-runtime/evidence/DGR-023/README.md

@@ -0,0 +1,126 @@
+# DGR-023 evidence — reproducible Python and C++ protobuf/gRPC generation
+
+**Status:** complete after controller verification and independent-review repairs on 2026-07-17.
+
+**Authority:** live Gitea issue #7. The local PRD is a secondary projection.
+
+## Implemented contract
+
+- Python generation requires exactly `grpcio-tools==1.82.1`; the generator checks installed distribution metadata and rejects missing or different versions with an actionable exact install command.
+- The C++ bootstrap builds one ignored toolchain prefix from exact inputs:
+  - Protobuf release `33.1` (`protobuf-config` version `33.1.0`);
+  - Abseil release `20250814.1`;
+  - gRPC C++ `1.82.1` at commit `acccf84c0df20487d64101f528e5d426541ca4e5`;
+  - gRPC's exact-commit submodules for c-ares, RE2, OpenSSL, and zlib.
+- Protobuf is configured with local dependencies only after the exact Abseil build. gRPC uses the installed Protobuf/Abseil packages and commit-pinned module dependencies, avoiding unpinned system development packages and download fallbacks.
+- CMake requires exact Protobuf `33.1.0` and gRPC `1.82.1`, requires the exported `gRPC::grpc_cpp_plugin` target, and always generates/builds both message and service stubs in the ignored build tree.
+- Python bindings remain committed package output; `--check` regenerates into a temporary directory and compares output. C++ bindings are never committed.
+- The C++ conformance test parses Python-produced vectors, validates fields/CRC32C, and emits `cpp_roundtrip.binpb`; Python compares that artifact byte-for-byte.
+
+## Defects found and fixed
+
+1. A relative bootstrap prefix was resolved after entering the temporary source directory, so successful output was deleted by cleanup. The script now canonicalizes the caller-relative destination first. The regression executes `--print-prefix` from a temporary working directory and validates the resulting path behavior.
+2. The original native path omitted gRPC C++ and accepted any discoverable plugin. The bootstrap now builds exact gRPC/plugin sources, and CMake rejects absent/incompatible versions.
+3. The Python script named the `grpcio-tools` pin but did not validate the installed distribution. It now refuses mismatched versions.
+4. Protobuf ignored a stale provider option and attempted to download a different Abseil. The build was stopped; exact Abseil is now built first and Protobuf uses `LOCAL_DEPENDENCIES_ONLY`.
+5. The host lacked OpenSSL development headers. Rather than add a floating system dependency, gRPC now uses the submodule pinned by its exact commit.
+6. Documentation uses `bash scripts/bootstrap_native_toolchain.sh ...`, so a normal checkout does not depend on executable-mode preservation.
+
+## Verified toolchain
+
+```text
+cmake version 4.4.0
+c++ (GCC) 15.2.1 20260123 (Red Hat 15.2.1-7)
+libprotoc 33.1
+protobuf CMake package 33.1.0
+grpcio-tools 1.82.1
+grpcio 1.82.1
+protobuf Python runtime 7.35.1
+gRPC C++ 1.82.1
+commit acccf84c0df20487d64101f528e5d426541ca4e5
+grpc_cpp_plugin sha256 995ca8ac620fe83532b649a7c8c0a9341c7003da927fe0e4a8f821bfc579206d
+```
+
+The native toolchain and generated/build artifacts live under ignored mounted-drive `build/` paths; model/build artifacts were not stored under `/home`.
+
+## Commands and results
+
+```bash
+bash scripts/bootstrap_native_toolchain.sh build/native-toolchain
+```
+
+```text
+passed from a clean build directory
+libprotoc 33.1
+gRPC 1.82.1 commit acccf84c0df20487d64101f528e5d426541ca4e5
+grpc_cpp_plugin sha256 995ca8ac620fe83532b649a7c8c0a9341c7003da927fe0e4a8f821bfc579206d
+```
+
+```bash
+cmake -S packages/node/native -B build/native \
+  -DCMAKE_PREFIX_PATH="$PWD/build/native-toolchain"
+cmake --build build/native -j"$(nproc)"
+test -f build/native/shard_runtime.grpc.pb.cc
+test -f build/native/shard_runtime.grpc.pb.h
+test -f build/native/libshard_runtime_grpc.a
+ctest --test-dir build/native --output-on-failure
+```
+
+```text
+Pinned gRPC 1.82.1: building ShardRuntime service stubs
+shard_runtime_proto built
+shard_runtime_grpc built
+1/1 shard_protocol_conformance passed
+```
+
+```bash
+python3 -m pytest -q tests/test_native_shard_protocol.py
+```
+
+```text
+50 passed, 2 optional-path skips
+```
+
+All DGR-023-required checks were selected explicitly:
+
+```bash
+python3 -m pytest -q -rs tests/test_native_shard_protocol.py \
+  -k 'cpp_and_python_agree_byte_for_byte or generated_python_stubs_match_the_proto or native_toolchain_bootstrap or wrong_grpcio'
+```
+
+```text
+4 passed, 48 deselected
+```
+
+```bash
+python3 scripts/generate_native_protocol.py --check
+python3 scripts/generate_protocol_goldens.py --check
+python3 scripts/ralph_prd_schema.py validate .scratch/distributed-gguf-runtime/prd.json
+python3 -m compileall -q packages tests
+git diff --check
+```
+
+```text
+generated stubs are up to date
+conformance vectors are up to date
+OK: 55 stories validated
+compileall passed
+git diff --check passed
+```
+
+## Changed files
+
+- `scripts/bootstrap_native_toolchain.sh`
+- `scripts/generate_native_protocol.py`
+- `packages/node/native/CMakeLists.txt`
+- `packages/node/native/README.md`
+- `tests/test_native_shard_protocol.py`
+- `.scratch/distributed-gguf-runtime/evidence/DGR-023/README.md`
+- `.scratch/distributed-gguf-runtime/prd.json` (secondary completion projection only)
+
+## Limitations and dependency handoff
+
+- This story proves exact schema/message/service generation and cross-language conformance. It does not implement or run the standalone worker service itself; DGR-033/DGR-037 own worker behavior.
+- The plugin SHA is evidence for this verified build. Reproducibility authority is the exact gRPC commit plus its submodule graph, not an assumption that different compilers produce byte-identical executables.
+- No model, GPU, API credits, or model download was used.
+- DGR-024 and DGR-037 may consume this completed generation dependency but must provide their own transport/worker evidence.

.scratch/distributed-gguf-runtime/evidence/DGR-025/README.md

@@ -0,0 +1,210 @@
+# DGR-025 evidence — exact artifact and runtime recipe identity
+
+**Completed:** 2026-07-17
+**Branch:** `ralph/fable-architecture-loop` (Claude Fable architecture lane)
+**Authority:** `.scratch/distributed-gguf-runtime/prd.json`
+**Dependencies:** DGR-018 (`evidence/DGR-018/README.md` — canonical backlog schema and
+issue projection), DGR-021 (`evidence/DGR-021/README.md` — versioned activation
+envelope). Both read before changing code.
+
+## Objective
+
+Ensure the tracker and worker only combine numerically and operationally
+compatible shards: fingerprint every axis that moves the numbers, bind shards to
+exact half-open ranges, fail closed on any mismatch, and keep uncertified
+recipes registered-but-dark.
+
+## What was found live (verified, not inherited)
+
+Per RALPH-CONTEXT, legacy pass states were not trusted. The DGR-003-lineage
+identity core was inspected and exercised live before any change:
+
+- `packages/node/meshnet_node/runtime_recipe.py` — node-side identity:
+  domain-separated digests (`meshnet.model-artifact.v1`,
+  `meshnet.runtime-recipe.v1`, `meshnet.shard-binding.v1`) over the source
+  artifact SHA (`source_digest`, with split artifacts bound to their exact
+  source via `DerivativeBinding`), tokenizer revision (pin-enforced),
+  architecture adapter + architecture/config digest, boundary and protocol
+  schema versions, backend, weight quantization, activation/compute dtypes, and
+  KV dtype/layout (`RECIPE_AXES`). Shard ranges are half-open
+  (`shard_start`/`shard_end`, end-exclusive, protocol convention) with no
+  topology or quant constants anywhere; `check_route` accepts any tiling of
+  `[0, layer_count)`. Route, handshake (`check_handshake`), and session-open
+  (`check_session_open`) checks fail closed with structured `RouteMismatch`
+  reasons mapped to specific protocol error codes (`handshake_error`).
+- `packages/tracker/meshnet_tracker/recipe.py` — deliberately independent
+  tracker re-derivation (no `meshnet_node` import); declared fingerprints are
+  recomputed, never trusted (`parse_identity`, `FingerprintMismatch`). The
+  `CertificationLedger` keeps every registered recipe dark until a real
+  distributed forward — at least 2 distinct nodes, whole-model coverage,
+  non-synthetic, tokens actually generated — certifies it; dark recipes may
+  route only to certify.
+- The two implementations are pinned by committed conformance vectors
+  (`tests/data/recipe_fingerprint_vectors.json`).
+
+Live verification of that pre-existing core before changes:
+`PYTHONPATH=packages/node:packages/tracker python3 -m pytest -q tests/test_runtime_recipe_identity.py`
+→ `45 passed`; plus `tests/test_native_identity_emission.py`,
+`tests/test_tracker_capability_admission.py`, `tests/test_node_admission.py`
+→ `59 passed`.
+
+## Gap found and closed (this story's change)
+
+**The `runtime_version` recipe axis was a label, not a pin.** It was an opaque
+caller-supplied string: nothing derived it from the DGR-027 lock manifest, and
+neither identity implementation rejected a moving reference (`"latest"` was
+accepted), so two workers could run different llama.cpp pins or patch stacks
+under one label and still agree on the recipe digest. The acceptance criterion
+explicitly requires fingerprinting the "runtime pin/patch stack".
+
+### Changed files
+
+- `packages/node/meshnet_node/runtime_pin.py` (new) — derives the canonical
+  `runtime_version` axis value from the DGR-027 lock workspace
+  (`packages/node/native/llama`):
+  `<runtime>@<40-hex upstream commit>+patchstack.<sha256>` where the stack
+  digest commits, under the `meshnet.runtime-patch-stack.v1` domain, to the
+  *ordered* `(patch name, patch bytes sha256)` stack. Fails closed on: missing
+  or malformed `UPSTREAM_LOCK.json`, unknown schema version, non-40-hex/moving
+  commit, `UPSTREAM_COMMIT` disagreement, any disagreement among the lock's
+  `patch_series`, `patches/series`, and `patches/SHA256SUMS`, a missing patch
+  file, or a patch whose bytes don't match their recorded digest. Reads the
+  committed manifest only; fetching/patching stays with
+  `scripts/llama_cpp_dependency.py` (DGR-027).
+- `packages/node/meshnet_node/runtime_recipe.py` — `runtime_version` is now
+  pin-enforced (`_require_pin`) exactly like `tokenizer_revision`; for the
+  llama.cpp backend it must also match the canonical
+  `llama.cpp@<40-hex>+patchstack.<64-hex>` grammar.
+- `packages/node/meshnet_node/native_backend.py` — the production native
+  identity seam no longer accepts a caller-supplied runtime string. It derives
+  `runtime_version` directly through `load_runtime_pin()` from the committed
+  lock and rejects a non-llama backend at this llama.cpp-specific boundary.
+- `packages/tracker/meshnet_tracker/recipe.py` — the independent tracker
+  implementation applies the same backend-specific grammar before re-deriving
+  the recipe digest, so forged operator labels cannot register or certify.
+- `tests/test_runtime_pin_identity.py` and
+  `tests/test_native_identity_emission.py` — deterministic tests cover lock
+  derivation, production native emission, and node/tracker rejection of the
+  forged values from independent review. Conformance vectors were regenerated
+  through `scripts/gen_recipe_fingerprint_vectors.py` for the tightened wire
+  contract.
+
+### Backlog-consistency repair (pre-existing damage, honestly recorded)
+
+`tests/test_ralph_prd_schema.py` had 4 pre-existing failures before this story
+touched anything, left by prior sessions and the alternate-history merge:
+
+- DGR-022 and DGR-027 were marked `passes: true` without `completionNotes` and
+  without regenerated issue projections. Added their `completionNotes`
+  (explicitly labeled as added during this repair, content drawn from their own
+  evidence READMEs) and regenerated
+  `issues/022-…` / `issues/027-…` via `scripts/ralph_prd_schema.py render`.
+- Three pre-DGR legacy GLM alpha issue files (`18-…`, `19-…`, `20-…`,
+  committed 2026-07-14, before DGR-018 established the generated-only
+  convention; they carry no authority disclaimer because they are *not*
+  generated from prd.json) were relocated via `git mv` to
+  `issues/legacy/` — preserved as provenance, out of the generated namespace.
+
+### prd.json
+
+Marked `DGR-025.passes = true` with `completionNotes`; regenerated
+`issues/025-define-exact-artifact-and-runtime-recipe-identity.md`.
+
+## Acceptance criteria → evidence
+
+1. **Fingerprint all axes** — `RECIPE_AXES` + `ArtifactIdentity` cover source
+   artifact SHA, tokenizer revision, architecture adapter/version (adapter axis
+   + architecture/config digest), boundary schema (boundary + protocol schema
+   versions), backend, quant, activation/compute dtype, KV/state layout; the
+   runtime pin/patch stack is now committed via the derived `runtime_version`
+   axis (`runtime_pin.py`). Verified by `test_runtime_recipe_identity.py` and
+   `test_runtime_pin_identity.py`.
+2. **Exact half-open range, no hardcoded topology/quant** — `ShardIdentity`
+   end-exclusive ranges, `DerivativeBinding` coverage checks, `check_route`
+   tiling over arbitrary layouts; quant/dtype values are open strings
+   (dynamic recipe inputs). Verified by `test_runtime_recipe_identity.py`
+   (routes of 1, 2, and 5 shards; no product constants).
+3. **Fail closed on any mismatch** — artifact, adapter, boundary/schema, cache
+   layout, backend, and runtime mismatches each produce structured
+   `RouteMismatch` reasons and protocol error codes; the tracker recomputes
+   digests and rejects inconsistent claims; moving runtime references are now
+   rejected on both sides.
+4. **Registered-but-dark** — `CertificationLedger`: unknown recipes cannot be
+   certified, registered recipes are dark, only a real ≥2-distinct-node
+   whole-model non-synthetic forward promotes; verified by
+   `test_runtime_recipe_identity.py` / `test_tracker_capability_admission.py`.
+5. **Gates + this handoff** — below.
+
+## Commands and results
+
+```bash
+PYTHONPATH=packages/node:packages/tracker python3 -m pytest -q tests/test_runtime_pin_identity.py
+```
+```text
+23 passed in 0.15s
+```
+
+```bash
+PYTHONPATH=packages/node:packages/tracker python3 -m pytest -q \
+  tests/test_runtime_pin_identity.py tests/test_runtime_recipe_identity.py \
+  tests/test_native_identity_emission.py tests/test_tracker_capability_admission.py \
+  tests/test_node_admission.py tests/test_node_capability.py tests/test_recipe_benchmark.py
+```
+```text
+202 passed, 1 warning in 5.38s
+```
+
+```bash
+PYTHONPATH=packages/node:packages/tracker python3 -m pytest -q tests/test_ralph_prd_schema.py
+```
+```text
+108 passed
+```
+(4 failed before this story's backlog repair; 0 after.)
+
+```bash
+python3 -m compileall -q packages tests   # exit 0
+git diff --check                          # exit 0
+python3 scripts/ralph_prd_schema.py validate .scratch/distributed-gguf-runtime/prd.json
+# OK: 55 stories validated.
+```
+
+Default tests are model-download-free, API-credit-free, and GPU-free; no model
+artifact was touched and nothing was written under `/home`.
+
+## Limitations
+
+- The production native identity seam now derives the manifest pin and cannot
+  accept an operator-supplied runtime label. It still cannot attest that the
+  running binary was built from those locked bytes. Embedding the patched-tree
+  hash at build time and echoing it through the DGR-022 status contract belongs
+  with DGR-028+/DGR-031; real distributed certification remains the final trust
+  boundary.
+- The DGR-027-recorded blocker stands: `0002-dense-llama-owned-range-loader.patch`
+  does not apply cleanly against the pin (DGR-028). That does not affect this
+  story: the identity commits to the patch *bytes as committed*, which is
+  precisely what makes a later repaired patch a *different* runtime identity.
+- No native/CMake change was made, so the native build/CTest gate is not
+  applicable; no llama.cpp patch content was changed, so apply/check/reverse
+  verification is not applicable (and is blocked by the DGR-028 defect anyway).
+- Tracker routing, load balancing, billing, telemetry, and relay semantics are
+  untouched; the only behavior change outside the new module is the stricter
+  (fail-closed) rejection of moving `runtime_version` values.
+
+## Dependency handoff
+
+- **DGR-026** (split-GGUF provisioning): bind each provisioned split via
+  `DerivativeBinding` to the exact source digest recorded in its hashed
+  manifest; the per-split `shard_binding_digest` is what certification pins.
+- **DGR-031** (`ShardEngine`): construct worker identity through
+  `shard_identity_from_native_report` and populate `runtime_version` from
+  `meshnet_node.runtime_pin.load_runtime_pin().runtime_version` — never from an
+  operator string. A build-time echo of the patched-tree hash through the
+  status contract would close the manifest-vs-binary gap noted above.
+- **DGR-041** (capability registration): the tracker already re-derives and
+  fail-closes on presented identities (`parse_identity`); register recipes
+  through the `CertificationLedger` so they arrive dark.
+- **DGR-044** (DeepSeek V4 Flash target): pin the target's artifact identity
+  the same way `glm_alpha_artifact` does — read locked manifests, never restate
+  digests — and note `layer_count` must count the routed transformer stack the
+  route tiles, excluding MTP (reserved for beta).

.scratch/distributed-gguf-runtime/evidence/DGR-027/README.md

@@ -0,0 +1,72 @@
+# DGR-027 evidence — exact llama.cpp provenance manifest and fetch workspace
+
+**Completed implementation:** 2026-07-17  
+**Branch:** `ralph/dgr-small-terra`  
+**Authority:** live Gitea issue #11. The controller fetched and claimed the issue
+through the Gitea API before launch; the isolated agent received that exact body.
+
+## Changed files
+
+- `packages/node/native/llama/UPSTREAM_LOCK.json`
+- `packages/node/native/llama/PATCH-STACK.md`
+- `scripts/llama_cpp_dependency.py`
+- `tests/test_llama_cpp_dependency.py`
+- `.scratch/distributed-gguf-runtime/evidence/DGR-027/README.md`
+
+## Provenance and retrieval contract
+
+`UPSTREAM_LOCK.json` records the upstream Git URL, immutable 40-character
+commit `e920c523e3b8a0163fe498af5bf90df35ff51d25`, expected Git tree
+`6c91a11407a3a3fb160f5dac705f9c59718f54f1`, MIT license, and the sole
+retrieval method: `git-clone-detached-commit` into `build/llama.cpp/source`.
+
+`python3 scripts/llama_cpp_dependency.py fetch` has no branch, tag, ref, or
+repository override. On a first fetch it clones the manifest URL, checks out
+the detached commit, and verifies commit, tree, required upstream blobs,
+license, and cleanliness. If the workspace already exists, it makes no network
+request and accepts it only after the same verification. Dirty or mismatched
+caches fail closed. The build directory is already ignored by `.gitignore`.
+
+## Verification
+
+| Command | Result |
+| --- | --- |
+| `python3 -m pytest -q tests/test_llama_cpp_dependency.py` | `7 passed in 0.22s` |
+| `python3 -m compileall packages tests` | passed |
+| `git diff --check` | passed (no output) |
+| `python3 scripts/llama_cpp_dependency.py inspect` | passed; reports exact commit/tree, retrieval workspace, MIT license, and two-patch stack |
+| `python3 scripts/llama_cpp_dependency.py fetch --workspace /tmp/not-llama-workspace` | failed closed with status 2: workspace outside the locked ignored build root |
+| symlinked workspace regression | passed; both a `build/` ancestor symlink and a final `source` symlink escaping the repository are refused |
+| attached-branch cache regression | passed; an exact commit on a local branch is refused until checked out as detached HEAD |
+| ignored/excluded injection regression | passed; a file hidden by `.git/info/exclude` is detected and refused |
+| tracked injection regression | passed; modified tracked content hidden by both `assume-unchanged` and `skip-worktree` is content-hashed and refused |
+| executable-mode regression | passed on the POSIX fixture for both index flags; the mounted project workspace has `core.filemode=false`, so its exact index tree is the canonical mode record and physical mode bits are not treated as meaningful |
+| `git check-ignore -v build/llama.cpp/source` | passed; `.gitignore:6:build/` |
+| `git diff --summary` and `git ls-files build packages/node/native/llama` | no source checkout or new submodule introduced; only manifest/docs/patches/native wrapper are tracked |
+| `python3 scripts/llama_cpp_dependency.py fetch` (controller network lane) | passed; fetched the exact detached commit and verified HEAD `e920c523e3b8a0163fe498af5bf90df35ff51d25` and tree `6c91a11407a3a3fb160f5dac705f9c59718f54f1` in the ignored workspace |
+| `python3 scripts/llama_cpp_dependency.py apply --source-dir build/llama.cpp/source` | failed on the pre-existing `0002-dense-llama-owned-range-loader.patch` as a corrupt patch at line 26; this is an explicit DGR-028 blocker and no native-build claim is made |
+
+The targeted test suite creates a local Git fixture to prove offline cache reuse
+after full identity verification, then proves a dirty cache is rejected. It
+also proves the CLI rejects a repository/branch override and an arbitrary
+workspace.
+
+## Limitations
+
+- The controller successfully materialized and verified the exact upstream
+  commit/tree, so the DGR-027 fetch and offline-cache boundary has real upstream
+  evidence rather than fixture-only evidence.
+- The existing `0002-dense-llama-owned-range-loader.patch` is malformed and
+  cannot pass `git apply --check` against the exact pin. DGR-027 changes no patch
+  file; repairing and certifying the numbered patch stack belongs to DGR-028.
+  Until that story closes, the repository must not claim patched-tree, native
+  CMake/CTest, or reverse-apply certification.
+- No model, API credits, GPU, or model artifact storage was used.
+
+## Dependency handoff
+
+DGR-028, DGR-029, and DGR-044 must invoke the manifest-owned `fetch` command
+before touching llama.cpp source. They may use only the verified
+`build/llama.cpp/source` checkout and must record any native build, CTest, and
+patch apply/check/reverse evidence against the exact manifest pin. DGR-017's
+cleanup remains provenance only and grants no inherited completion credit.

.scratch/distributed-gguf-runtime/evidence/README.md

@@ -1,15 +1,15 @@
-# Ralph task evidence
+# Distributed GGUF Runtime evidence
 
-Each completed story creates `evidence/<TASK-ID>/README.md`. Fresh dependent iterations must read it before coding.
+> **Specification status:** planning artifacts only. No distributed GGUF runtime is implemented. DGR-017 cleanup is complete; no runtime implementation story has completion credit. `prd.json` is authoritative.
 
-Required README sections:
+## Authority and classes
 
-1. Summary and acceptance decision.
-2. Exact files changed.
-3. Commands run and real exit/results.
-4. Correctness, performance and hardware evidence classification.
-5. Known limitations and deferred work.
-6. Compatibility/migration notes.
-7. Explicit handoff for each dependent story.
+Evidence supports but never overrides `prd.json`. Valid classes are `model-free`, `fixture`, `real-model`, `real-hardware`, and `release`; lower classes cannot satisfy higher-class acceptance. Legacy DGR-001..016 directories remain unchanged for DGR-017 provenance audit and confer no completion credit.
 
-Store raw machine-readable metrics, manifests and protocol artifacts beside the README. Never store secrets, model weights, build outputs or Ralph iteration logs here.
+## Future story layout
+
+Each DGR-017..071 story writes `evidence/<ID>/README.md` with summary, exact changed files, exact commands and real outputs, limitations, compatibility/migration notes, and dependent-story handoff. Machine-readable contracts, manifests, metrics, and raw logs live beside it. Never fabricate output.
+
+Real runs record exact model SHA and all split hashes, tokenizer, quant/recipe, llama.cpp pin+patch identity, backend/driver/toolchain, host/hardware/network, commands/environment (without secrets), raw parity/performance/resource results, and evidence class. Models live on configured mounted-drive storage, never `/home`.
+
+Routing certification records prove only the exact exercised backend/model/recipe lane. Compile-only, fixture, failed, or unavailable lanes remain registered-dark. V4 cache/state evidence must show KV and CSA/HCA/SWA/indexer/compressor data remain shard-local/session-keyed; route recovery evidence must show cache miss plus re-prefill/restart, not migration.

.scratch/distributed-gguf-runtime/gitea-issues.json

@@ -0,0 +1,335 @@
+{
+  "repository": "https://git.d-popov.com/popov/neuron-tai",
+  "stories": {
+    "DGR-017": {
+      "number": 1,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/1",
+      "state": "closed",
+      "status": "completed"
+    },
+    "DGR-018": {
+      "number": 2,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/2",
+      "state": "closed",
+      "status": "completed"
+    },
+    "DGR-019": {
+      "number": 3,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/3",
+      "state": "open",
+      "status": "ready"
+    },
+    "DGR-020": {
+      "number": 4,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/4",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-021": {
+      "number": 5,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/5",
+      "state": "closed",
+      "status": "completed"
+    },
+    "DGR-022": {
+      "number": 6,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/6",
+      "state": "open",
+      "status": "ready"
+    },
+    "DGR-023": {
+      "number": 7,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/7",
+      "state": "open",
+      "status": "ready"
+    },
+    "DGR-024": {
+      "number": 8,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/8",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-025": {
+      "number": 9,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/9",
+      "state": "open",
+      "status": "ready"
+    },
+    "DGR-026": {
+      "number": 10,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/10",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-027": {
+      "number": 11,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/11",
+      "state": "open",
+      "status": "ready"
+    },
+    "DGR-028": {
+      "number": 12,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/12",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-029": {
+      "number": 13,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/13",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-030": {
+      "number": 14,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/14",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-031": {
+      "number": 15,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/15",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-032": {
+      "number": 16,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/16",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-033": {
+      "number": 17,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/17",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-034": {
+      "number": 18,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/18",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-035": {
+      "number": 19,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/19",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-036": {
+      "number": 20,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/20",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-037": {
+      "number": 21,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/21",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-038": {
+      "number": 22,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/22",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-039": {
+      "number": 23,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/23",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-040": {
+      "number": 24,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/24",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-041": {
+      "number": 25,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/25",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-042": {
+      "number": 26,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/26",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-043": {
+      "number": 27,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/27",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-044": {
+      "number": 28,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/28",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-045": {
+      "number": 29,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/29",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-046": {
+      "number": 30,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/30",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-047": {
+      "number": 31,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/31",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-048": {
+      "number": 32,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/32",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-049": {
+      "number": 33,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/33",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-050": {
+      "number": 34,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/34",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-051": {
+      "number": 35,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/35",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-052": {
+      "number": 36,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/36",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-053": {
+      "number": 37,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/37",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-054": {
+      "number": 38,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/38",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-055": {
+      "number": 39,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/39",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-056": {
+      "number": 40,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/40",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-057": {
+      "number": 41,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/41",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-058": {
+      "number": 42,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/42",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-059": {
+      "number": 43,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/43",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-060": {
+      "number": 44,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/44",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-061": {
+      "number": 45,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/45",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-062": {
+      "number": 46,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/46",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-063": {
+      "number": 47,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/47",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-064": {
+      "number": 48,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/48",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-065": {
+      "number": 49,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/49",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-066": {
+      "number": 50,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/50",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-067": {
+      "number": 51,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/51",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-068": {
+      "number": 52,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/52",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-069": {
+      "number": 53,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/53",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-070": {
+      "number": 54,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/54",
+      "state": "open",
+      "status": "blocked"
+    },
+    "DGR-071": {
+      "number": 55,
+      "url": "https://git.d-popov.com/popov/neuron-tai/issues/55",
+      "state": "open",
+      "status": "blocked"
+    }
+  }
+}

.scratch/distributed-gguf-runtime/implementation-strategy.md

@@ -1,247 +1,40 @@
-# Focused implementation strategy: performant concurrent distributed inference
+# Distributed GGUF Runtime implementation strategy
 
-Status: Accepted planning direction
-Last updated: 2026-07-13
+> **Specification status:** planning artifacts only. No distributed GGUF runtime is implemented. DGR-017 cleanup is complete; no runtime implementation story has completion credit. `prd.json` is authoritative.
 
-## Product objective
+## Execution model
 
-Enable clients to run top open models that do not fit on one consumer machine by combining independently owned model Shards into performant, concurrent Inference Routes.
+Execute one numerically ordered, dependency-ready story per fresh Ralph context. Read `RALPH-CONTEXT.md`, source issue, and dependency evidence first; use TDD/fixture-first verification; finish with exact evidence. `prd.json` is the only state authority.
 
-The alpha-release target is the exact `zai-org/GLM-5.2` model, pinned by revision and served with `reasoning_effort=max`, using the smallest published Unsloth `UD-IQ1_S` GGUF across physical consumer machines. See [GLM-5.2-MAX-ALPHA-ROADMAP.md](GLM-5.2-MAX-ALPHA-ROADMAP.md). Dense Llama remains a cheap structural fixture; Qwen expansion is post-alpha.
+## Sequence
 
-The project is not trying to reproduce every vLLM feature or support every inference engine. It is optimizing for:
+1. **M0 DGR-017..020:** reconcile legacy reality, lock metadata/performance contracts, and run the independent whole-model baseline.
+2. **M1 DGR-021..033:** protocol/lifecycle/codegen, exact identities and split artifacts, pinned upstream/patches, CPU then accelerator builds, `ShardEngine`, fixtures, fake worker.
+3. **M2 DGR-034..043:** dense ranged ownership/boundary/parity/local state, worker integration, supervision/direct-relay, and measured GGUF inputs to unchanged routing.
+4. **M3 DGR-044..054:** pin/inventory V4, adapt upstream boundary/local state/MoE/hash execution, pass parity and real 2–4 scenario, then enforce alpha with MTP off.
+5. **M4 DGR-055..067:** batching/backpressure/failure/recovery/long-context, existing-routing 10+ certification, real scale, measured optimization/compression, MTP contract+implementation, hardware certification.
+6. **M5 DGR-068..071:** packages, human upstream collaboration, beta gate (including MTP), and pin/patch/certification maintenance.
 
-1. Models larger than one node's RAM/VRAM.
-2. Useful interactive decode speed on consumer CPU, AMD, NVIDIA, Vulkan, and mixed routes where certified.
-3. Multiple concurrent Route Sessions without cache corruption or global serialization.
-4. A lean runtime with one control plane and one primary GGUF engine.
-5. Measured improvement over the existing Transformers/safetensors implementation.
+## Guardrails
 
-## Current reality
 
-The existing project already owns the differentiating distributed control plane:
+## Locked scope
 
-- Tracker-selected contiguous Shards.
-- Stable Route Sessions.
-- Local per-Shard Hot KV State in the Transformers reference backend.
-- Binary Activation Seams.
-- Relay/direct routing, cancellation, telemetry, billing, and capability admission.
-- Persistent relay and direct transport optimizations.
+- Existing Meshnet Tracker routing, load balancing, billing, telemetry, relay, and provider semantics are backend-agnostic and are **not redesigned**. GGUF contributes exact compatibility, range/capacity, queue/load, seam-cost, health/reliability, and certification inputs only.
+- The data plane is a standalone project-owned C++ Shard worker with gRPC/Protobuf and a project-owned `ShardEngine` boundary.
+- llama.cpp is fetched at one exact commit into an ignored workspace from an in-repo manifest, then a numbered minimal patch stack is applied. There is no submodule, vendored tree, or permanent-fork dependency.
+- llama.cpp owns DeepSeek V4 graphs, mHC, MoE, attention, hash routing, and kernels. Meshnet adds only range-ownership hooks, typed boundary/local-state adapters, worker integration, and parity/certification.
+- Quantization and placement are dynamic recipe inputs. The 2–4 and 10+ stage layouts are certification scenarios, never product constants.
+- Per-shard Hot KV and V4 CSA/HCA/SWA/indexer/compressor state remain local and keyed by route session/epoch. The WAN seam carries the typed mHC 4×4096 residual boundary, positions, token-ID sideband where required, and schema/cache expectations—not per-layer caches.
+- Route changes use cache miss plus re-prefill/restart. There is no WAN KV or V4 auxiliary-cache migration.
+- CPU/CUDA/ROCm/Vulkan/Metal compile lanes are planned; only exact real-hardware-certified backend/model/recipe lanes may be advertised.
+- Alpha requires correctness and the pre-locked useful-speed gate. MTP is reserved and off for alpha; its ownership contract, implementation, and benchmark are required before beta.
 
-The missing production path is a native GGUF execution worker that can load and execute only an assigned layer range while retaining local Hot KV State for concurrent Route Sessions.
+## Target identities
 
-Whole-model llama.cpp, vLLM, and existing Transformers serving remain baselines or optional route kinds. They are not substitutes for native distributed Shards.
+- DeepSeek V4 official target SHA: `60d8d70770c6776ff598c94bb586a859a38244f1`.
+- llama.cpp V4 support lineage began at PR 24162 / merge `8c146a8366304c871efc26057cc90370ccf58dad`; DGR-027 later pins one exact validated current commit.
+- V4 scope: 43 main layers plus MTP; mHC 4×4096 boundary; 256 routed + 1 shared experts with six routed active; token IDs required for the first three hash-routed layers.
+- Exact split-GGUF artifacts are provisioned to mounted-drive storage with a complete hashed manifest and resumable verification; no model artifact may be placed under `/home`.
 
-## Performance hypothesis—not an assumption
-
-GGUF itself is a format. Performance comes from llama.cpp/GGML's quantized kernels, memory layout, mmap, backend scheduling, and reduced working set.
-
-Quantized GGUF may be faster or may merely fit a larger model. Comparisons against safetensors must report both speed and quality because BF16 safetensors and Q4/Q8 GGUF are not numerically equivalent.
-
-Before expensive native work, establish controlled lanes. DGR-001 remains immutable; DGR-017 adds a target-specific fit and semantics contract without rewriting DGR-001 evidence:
-
-- Same model architecture and upstream revision.
-- Same machine, prompt set, context, output length, sampling policy, and concurrency.
-- Transformers/safetensors BF16 or the current production recipe.
-- llama.cpp GGUF F16/BF16 or Q8 correctness lane where available.
-- Q4_K_M or selected production quantization performance/fit lane.
-- TTFT, prefill tok/s, decode tok/s, p50/p95 latency, RSS, VRAM, artifact size, energy where available, and output-quality drift.
-
-The program proceeds only if llama.cpp/GGUF provides at least one meaningful advantage recorded in a machine-readable performance contract:
-
-- Better decode or aggregate throughput at acceptable quality; or
-- Materially lower memory that makes the target model routable while preserving useful throughput.
-
-## Parallelism we will use
-
-### Public Inference Route: layer/pipeline parallelism
-
-Each node independently executes one contiguous Shard. Activations cross seams; weights and Hot KV State remain local.
-
-This is the only public cross-machine model-parallel primitive in the first runtime.
-
-### Per-node continuous batching
-
-Autoregressive tokens remain sequential within one generation. Throughput comes from batching decode steps from multiple active Route Sessions inside each node using llama.cpp batches and sequence IDs or bounded context pools.
-
-This is essential. A worker that globally serializes sessions is not production-ready.
-
-### Multiple complete routes: data parallelism
-
-The Tracker may select multiple complete routes for independent requests. This increases network throughput and availability without requiring collectives between routes.
-
-### Trusted composite node: optional tensor/expert parallelism
-
-Tensor parallelism and expert parallelism require frequent collectives and tight compatibility. They may be used later inside one operator-controlled composite node or managed cluster exposed as one logical provider. They are not public WAN routing primitives.
-
-### Deferred mechanisms
-
-- Disaggregated prefill and KV transfer.
-- Speculative decoding.
-- Cross-route prefix snapshots.
-- Route repair with KV migration.
-- Public tensor/expert parallel collectives.
-
-They remain out of the critical path until the native layer route passes performance and concurrency gates.
-
-## Reuse decisions
-
-### llama.cpp/GGML: primary runtime substrate
-
-Reuse:
-
-- GGUF parsing and mmap.
-- Quantized kernels.
-- CPU, CUDA, HIP/ROCm, Vulkan, Metal, and other supported backends.
-- Tokenizer and model architecture implementations.
-- KV and sequence operations.
-- Backend scheduler and graph execution.
-
-Maintain a small exact-commit fork only for the missing local seam:
-
-- Range-aware tensor ownership/loading.
-- Architecture-defined boundary input/output.
-- Intermediate boundary output without tail normalization.
-- Layer-filtered KV and sequence mapping.
-
-Keep networking, Tracker logic, billing, and public protocol outside llama.cpp. Upstream generic hooks where possible.
-
-### vLLM: concepts and optional managed backend
-
-Use unmodified vLLM only as:
-
-- A whole-model node backend.
-- A managed TP/PP/EP cluster represented as one logical provider.
-- A performance/correctness baseline.
-
-Adapt concepts, not runtime code:
-
-- Named intermediate tensor bundles.
-- Continuous batching and request-owner maps.
-- Versioned KV-transfer compatibility fingerprints.
-- Explicit send/receive/abort/failure lifecycle.
-- Load telemetry and unbiased route selection.
-
-Do not fork vLLM for public Shards and do not transplant PagedAttention, Torch process groups, or GGUF-plugin kernels into the llama.cpp worker.
-
-### Nakshatra, prima.cpp, llama-gguf, LiGGUF, GPUStack
-
-Use as source and test donors only:
-
-- Nakshatra: partial-GGUF patches, daemon concepts, replay cases.
-- prima.cpp: selected tensor ownership and local-layer KV evidence.
-- llama-gguf: small protocol and integration-test patterns.
-- LiGGUF: Q8 activation transport and tensor-reduction reference.
-- historical GPUStack: resource preflight and role-oriented placement.
-
-Do not adopt or fork their repositories wholesale.
-
-### Mesh-LLM GLM branch: focused test/patch donor only
-
-Use its GLM-5.2 branch to study DSA, IndexShare, stage-local KV, and sideband tests. Do not import its scheduler, discovery/control plane, package manager, or broad llama.cpp patch stack. Every adopted idea must be independently understood, minimized, attributed, and tested against our exact pin.
-
-## Battle-proven transport decision
-
-Use gRPC over HTTP/2 with Protocol Buffers for the native C++ Shard worker protocol.
-
-Why:
-
-- Mature Python and C++ implementations.
-- Bidirectional streaming.
-- HTTP/2 flow control and connection reuse.
-- Deadlines, cancellation, status codes, TLS, authentication interceptors, and generated schemas.
-- Avoids inventing a socket protocol.
-
-Scope boundary:
-
-- OpenAI-compatible client/Gateway APIs remain HTTP/SSE.
-- Tracker/control APIs remain existing project interfaces.
-- One long-lived bidirectional gRPC stream serves one Route Session Activation Seam.
-- Existing relay/WebSocket infrastructure may carry the same versioned protobuf frames as opaque binary when direct gRPC reachability is unavailable.
-- Large prefill tensors are chunked into bounded frames; decode bundles stay small.
-- No QUIC/WebRTC/custom transport in this milestone.
-
-The public boundary uses a versioned named-tensor bundle rather than one anonymous tensor because architecture boundaries can require more than `hidden_states`. DGR-006 updates the current single-`NamedTensor` decode fast path to carry the same bundle semantics and adds an explicit typed tail logits/token result with sampling/template identity.
-
-Minimum identity:
-
-```text
-schema version
-request/work id
-Route Session id and route epoch
-Model Artifact and runtime recipe fingerprint
-Shard range and effective start
-phase: prefill/decode/release/cancel
-position/token range
-named tensors with shape/dtype/byte order
-compression and checksum
-idempotency step id
-cache expectation/result
-```
-
-## Concurrency model
-
-A native worker must not use one global serving sequence or one lock around all model execution.
-
-Required ownership:
-
-```text
-(Route Session id, route epoch)
-    -> local sequence/context
-    -> Shard-local Hot KV State
-    -> bounded lease and memory accounting
-```
-
-The node scheduler:
-
-- Admits sessions against model memory and KV budget.
-- Forms compatible decode batches from active sessions.
-- Preserves per-session position and route order.
-- Applies bounded queues and backpressure.
-- Cancels/releases independently.
-- Reports queue, batch, KV, prefill, decode, and seam telemetry.
-
-Initial deterministic gate: at least four concurrent sessions on a small certified model with no token/KV cross-talk. Final concurrency targets are hardware/recipe-specific and recorded by capability admission rather than hardcoded globally.
-
-## Stage gates
-
-### Gate A: performance hypothesis
-
-Controlled safetensors-versus-GGUF benchmark produces a signed/reproducible report and locks thresholds. Stop native work if there is no meaningful speed or fit benefit.
-
-### Gate B: local range parity
-
-Two local processes own disjoint GGUF ranges and match whole-model llama.cpp within the certified numerical tolerance for prefill and greedy decode.
-
-### Gate C: concurrent KV
-
-Multiple Route Sessions prefill/decode concurrently with isolated local KV, bounded memory, cancellation, and release.
-
-### Gate D: real distributed route
-
-Two physical machines execute one model that uses both Shards. Synthetic activation tests do not satisfy this gate.
-
-### Gate E: consumer-hardware performance
-
-On certified consumer hardware, the GGUF route beats the current distributed safetensors route under the locked performance contract or enables a larger otherwise-unroutable model at useful measured speed.
-
-### Gate F: exact GLM-5.2 alpha target
-
-After the generic dense fixture proves range and boundary mechanics, certify explicit GLM-5.2 MoE, MLA KV, DSA, IndexShare, and NextN policy. Alpha requires the exact `UD-IQ1_S` target across physical consumer nodes, native Max-mode semantics, locked parity/usefulness/performance thresholds, and bounded failure cleanup. Qwen3/Qwen3-MoE is later architecture expansion.
-
-## Scope discipline
-
-The following do not block the first production candidate:
-
-- New cryptocurrency/economics work.
-- New artifact P2P protocol.
-- QUIC or WebRTC.
-- vLLM fork.
-- Whole-repository Nakshatra/prima adoption.
-- Every GGUF architecture.
-- Automatic route repair.
-- Prefix snapshot migration.
-- Speculative decoding.
-- A large-model marketing demo before small-model parity and concurrency pass.
-
-Every optimization must preserve output contract, session isolation, cancellation, resource cleanup, capability admission, and per-node attribution.
+DGR-020 cannot use distributed results. DGR-054 does not depend on MTP. DGR-070 depends on DGR-066. Compile support and scenario success never imply general routability.

.scratch/distributed-gguf-runtime/issues/017-reconcile-and-clean-the-superseded-dgr-backlog.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-017: Reconcile and clean the superseded DGR backlog
+
+- **Status / triage:** completed; `passes: true`
+- **Execution mode:** `AFK`
+- **Milestone:** `M0`
+- **Dependencies:** None
+- **Blocks (derived):** `DGR-018`, `DGR-019`, `DGR-027`, `DGR-054`
+- **Labels:** `area:provenance`, `area:cleanup`, `type:audit`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/017-reconcile-and-clean-the-superseded-dgr-backlog.md`, and evidence READMEs for dependencies (none) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Audit implementation reality, void inherited completion credit, and clean misleading backlog/stub baggage while preserving attributable evidence and accepted research.
+
+## Acceptance criteria
+
+- [x] Compare the branch, old DGR-001..016 issue/pass states, evidence, and actual runtime sources; classify each output as reusable, reference-only, blocked, obsolete, or absent.
+- [x] Record an authoritative old-to-new disposition and provenance; explicitly give no completion credit to any new story and note absent implementation/evidence.
+- [x] Remove or archive only artifacts the audit proves obsolete while preserving accepted ADRs, useful research, raw benchmark evidence, and attributable reusable work.
+- [x] Protect ignored build workspaces, generated protobuf outputs, Ralph logs, and model artifacts from accidental commits, and document every retained legacy artifact.
+- [x] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Verified evidence: `.scratch/distributed-gguf-runtime/evidence/DGR-017/README.md`. Legacy evidence remains provenance only and grants no implementation completion credit.

.scratch/distributed-gguf-runtime/issues/018-define-canonical-ralph-and-gitea-metadata-schema.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-018: Define canonical Ralph and Gitea metadata schema
+
+- **Status / triage:** completed; `passes: true`
+- **Execution mode:** `AFK`
+- **Milestone:** `M0`
+- **Dependencies:** `DGR-017`
+- **Blocks (derived):** `DGR-021`, `DGR-025`
+- **Labels:** `area:planning`, `area:gitea`, `type:infrastructure`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/018-define-canonical-ralph-and-gitea-metadata-schema.md`, and evidence READMEs for dependencies (DGR-017) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Make `prd.json` the validated source from which Markdown and Gitea issues can later be generated losslessly.
+
+## Acceptance criteria
+
+- [x] Define fields for stable ID/title, labels, milestone, type, `dependsOn`, derived `blocks`, triage, evidence class, and hardware/model/upstream flags.
+- [x] Validate that all stories start `passes: false`, use known dependencies, and have unique stable IDs.
+- [x] Reject cycles, missing dependencies, mismatched generated `blocks`, duplicate titles/IDs, and generated artifacts claiming authority over `prd.json`.
+- [x] Add deterministic model-free tests for parse, validation, and generation round trips.
+- [x] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Verified evidence: `.scratch/distributed-gguf-runtime/evidence/DGR-018/README.md`. Legacy evidence remains provenance only and grants no implementation completion credit.

.scratch/distributed-gguf-runtime/issues/019-lock-alpha-and-beta-performance-contracts.md

@@ -0,0 +1,40 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-019: Lock alpha and beta performance contracts
+
+- **Status / triage:** specification only; `ready-for-human`; `passes: false`
+- **Execution mode:** `HITL`
+- **Milestone:** `M0`
+- **Dependencies:** `DGR-017`
+- **Blocks (derived):** `DGR-020`, `DGR-044`, `DGR-054`
+- **Labels:** `area:performance`, `type:contract`, `priority:p0`, `gate:hitl`, `ready-for-human`
+- **Evidence class:** `release`
+- **Hardware:** `required`
+- **Model:** `generic+deepseek-v4`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/019-lock-alpha-and-beta-performance-contracts.md`, and evidence READMEs for dependencies (DGR-017) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Freeze useful speed, correctness, memory-fit, and stop/go thresholds before implementation results are visible.
+
+## Acceptance criteria
+
+- [ ] Define controlled safetensors, whole-model GGUF, dense distributed GGUF, and V4 Flash distributed lanes with fixed prompts, context/output lengths, sampling, concurrency, hardware, and metrics.
+- [ ] Alpha requires correctness plus a human-approved useful-speed threshold; beta adds concurrency, long-context, failure, and sustained-throughput thresholds.
+- [ ] Separate quantization/model-fit gains from runtime, transport, batching, and kernel gains.
+- [ ] Treat quants and 2–4/10+ stage counts only as named certification scenarios; no product logic may hardcode them.
+- [ ] Lock thresholds and stop conditions in versioned machine-readable data before benchmark result ingestion.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-019/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/020-run-the-controlled-whole-model-gguf-baseline.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-020: Run the controlled whole-model GGUF baseline
+
+- **Status / triage:** specification only; `ready-for-human`; `passes: false`
+- **Execution mode:** `HITL`
+- **Milestone:** `M0`
+- **Dependencies:** `DGR-019`
+- **Blocks (derived):** `DGR-054`
+- **Labels:** `area:performance`, `type:benchmark`, `priority:p0`, `gate:hitl`, `ready-for-human`
+- **Evidence class:** `real-hardware`
+- **Hardware:** `required`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/020-run-the-controlled-whole-model-gguf-baseline.md`, and evidence READMEs for dependencies (DGR-019) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Execute the locked safetensors and whole-model llama.cpp lanes before distributed implementation results can influence the decision.
+
+## Acceptance criteria
+
+- [ ] Run the exact DGR-019 safetensors and whole-model llama.cpp benchmark lanes with locked prompts, lengths, sampling, concurrency, hardware, and artifact/runtime identities.
+- [ ] Record raw machine-readable correctness, TTFT, prefill/decode, throughput, latency, memory, artifact-size, failure, and quality-drift metrics without ingesting distributed implementation results.
+- [ ] Separate quantization/model-fit effects from runtime/kernel effects and preserve failed or unavailable lanes honestly.
+- [ ] Publish a threshold-based `go`, `optimize baseline`, or `stop` decision without changing the locked contract.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-020/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/021-define-the-versioned-named-tensor-stream-envelope.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-021: Define the versioned named-tensor stream envelope
+
+- **Status / triage:** completed; `passes: true`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-018`
+- **Blocks (derived):** `DGR-022`, `DGR-023`, `DGR-025`, `DGR-031`, `DGR-035`, `DGR-046`
+- **Labels:** `area:protocol`, `type:infrastructure`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/021-define-the-versioned-named-tensor-stream-envelope.md`, and evidence READMEs for dependencies (DGR-018) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Establish the backend-neutral protobuf envelope used by direct and relayed Shard activation traffic.
+
+## Acceptance criteria
+
+- [x] Define schema version, request/work ID, route session/epoch, shard range/effective start, phase, position, and idempotency step.
+- [x] Define named tensors with shape, dtype, byte order, bounded fragments, compression identity, and checksum.
+- [x] Reserve extensible fields for token-ID sidebands, architecture state, recurrent state, and MTP without claiming implementations.
+- [x] Add deterministic serialization, fragmentation, checksum, unknown-field, and size-limit tests.
+- [x] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Verified evidence: `.scratch/distributed-gguf-runtime/evidence/DGR-021/README.md`. Legacy evidence remains provenance only and grants no implementation completion credit.

.scratch/distributed-gguf-runtime/issues/022-define-shard-lifecycle-and-structured-status-rpcs.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-022: Define Shard lifecycle and structured status RPCs
+
+- **Status / triage:** completed; `passes: true`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-021`
+- **Blocks (derived):** `DGR-024`, `DGR-033`, `DGR-037`
+- **Labels:** `area:protocol`, `area:lifecycle`, `type:infrastructure`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/022-define-shard-lifecycle-and-structured-status-rpcs.md`, and evidence READMEs for dependencies (DGR-021) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Complete the gRPC contract for worker capability, health, sessions, cancellation, release, and metrics.
+
+## Acceptance criteria
+
+- [x] Define capability, health, bidirectional session stream, cancellation, release, and metrics RPCs.
+- [x] Specify deadlines, cancellation propagation, bounded flow control, cache expectations/results, and structured error taxonomy.
+- [x] Specify TLS/auth hooks without moving Meshnet authentication or billing into the worker.
+- [x] Add compatibility tests for supported versions and fail-closed tests for unsupported versions and malformed lifecycle transitions.
+- [x] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Verified evidence: `.scratch/distributed-gguf-runtime/evidence/DGR-022/README.md`. Legacy evidence remains provenance only and grants no implementation completion credit.

.scratch/distributed-gguf-runtime/issues/023-make-python-and-c-protobuf-generation-reproducible.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-023: Make Python and C++ protobuf generation reproducible
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-021`
+- **Blocks (derived):** `DGR-024`, `DGR-037`
+- **Labels:** `area:protocol`, `area:build`, `type:tooling`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/023-make-python-and-c-protobuf-generation-reproducible.md`, and evidence READMEs for dependencies (DGR-021) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Generate identical Python/C++ protocol bindings without manual copying or checked-in build debris.
+
+## Acceptance criteria
+
+- [ ] Pin protoc, gRPC, and plugin versions or declare a verified compatible range.
+- [ ] Generate Python and C++ bindings into out-of-tree build/package locations through documented commands.
+- [ ] Add Python↔C++ round-trip and descriptor compatibility tests.
+- [ ] A clean checkout regenerates bindings deterministically or fails with an actionable toolchain error.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-023/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/024-implement-in-memory-fake-grpc-seam-transport.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-024: Implement in-memory fake gRPC seam transport
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-022`, `DGR-023`
+- **Blocks (derived):** `DGR-033`, `DGR-042`
+- **Labels:** `area:protocol`, `area:testing`, `type:vertical-slice`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `fake`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/024-implement-in-memory-fake-grpc-seam-transport.md`, and evidence READMEs for dependencies (DGR-022, DGR-023) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Exercise the complete streaming protocol deterministically before a real model or worker exists.
+
+## Acceptance criteria
+
+- [ ] Provide a fake bidirectional stream supporting prefill fragments, decode fast-path frames, release, cancel, and structured errors.
+- [ ] Test flow-control blocking, deadlines, malformed fragments, checksum failure, duplicates, and stale epochs.
+- [ ] Verify direct and opaque-relay framing preserve identical protobuf bytes.
+- [ ] Tests require no sockets outside localhost, model downloads, or native accelerator.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-024/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/025-define-exact-artifact-and-runtime-recipe-identity.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-025: Define exact artifact and runtime recipe identity
+
+- **Status / triage:** completed; `passes: true`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-018`, `DGR-021`
+- **Blocks (derived):** `DGR-026`, `DGR-031`, `DGR-041`, `DGR-044`
+- **Labels:** `area:identity`, `area:admission`, `type:domain`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/025-define-exact-artifact-and-runtime-recipe-identity.md`, and evidence READMEs for dependencies (DGR-018, DGR-021) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Ensure the tracker and worker only combine numerically and operationally compatible shards.
+
+## Acceptance criteria
+
+- [x] Fingerprint source artifact SHA, tokenizer revision, architecture adapter/version, boundary schema, runtime pin/patch stack, backend, quant, activation/compute dtype, and KV/state layout.
+- [x] Bind each shard to an exact half-open range without hardcoding a topology or quant.
+- [x] Fail closed on any artifact, adapter, boundary, cache, backend, or runtime mismatch.
+- [x] Unsupported recipes remain registered-but-dark until real-hardware evidence certifies them.
+- [x] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Verified evidence: `.scratch/distributed-gguf-runtime/evidence/DGR-025/README.md`. Legacy evidence remains provenance only and grants no implementation completion credit.

.scratch/distributed-gguf-runtime/issues/026-provision-exact-split-gguf-artifacts-outside-home.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-026: Provision exact split-GGUF artifacts outside /home
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-025`
+- **Blocks (derived):** `DGR-044`, `DGR-045`
+- **Labels:** `area:artifacts`, `area:provenance`, `type:tooling`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/026-provision-exact-split-gguf-artifacts-outside-home.md`, and evidence READMEs for dependencies (DGR-025) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Make exact split-GGUF inputs reproducibly available from mounted-drive storage without embedding a quantization or topology assumption in product code.
+
+## Acceptance criteria
+
+- [ ] Create an exact manifest that binds the source artifact, tokenizer/revision, every split file name, size, range/role, and cryptographic hash.
+- [ ] Provide resumable, hash-verifying download/provision tooling targeting configured mounted-drive storage; refuse paths under `/home` and incomplete or mismatched splits.
+- [ ] Keep quantization and split topology as manifest/recipe inputs with no hardcoded quant, node count, or range layout.
+- [ ] Add deterministic model-download-free tests using tiny local split fixtures, including interrupted resume, missing split, hash mismatch, and `/home` rejection.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-026/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/027-add-exact-llama-cpp-provenance-manifest-and-fetch-workspace.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-027: Add exact llama.cpp provenance manifest and fetch workspace
+
+- **Status / triage:** completed; `passes: true`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-017`
+- **Blocks (derived):** `DGR-028`, `DGR-029`, `DGR-044`
+- **Labels:** `area:upstream`, `area:build`, `type:provenance`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/027-add-exact-llama-cpp-provenance-manifest-and-fetch-workspace.md`, and evidence READMEs for dependencies (DGR-017) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Pin llama.cpp exactly through an in-repo manifest while fetching source only into an ignored build workspace.
+
+## Acceptance criteria
+
+- [x] Manifest records upstream URL, exact commit, expected source archive/tree hash, license, and retrieval method.
+- [x] Fetch tooling verifies identity before use and refuses an unpinned branch/tag.
+- [x] Source is fetched into an ignored build workspace; no submodule, vendored source tree, or permanent fork is introduced.
+- [x] Offline reuse is supported only after the cached tree’s exact identity is verified.
+- [x] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Verified evidence: `.scratch/distributed-gguf-runtime/evidence/DGR-027/README.md`. Legacy evidence remains provenance only and grants no implementation completion credit.

.scratch/distributed-gguf-runtime/issues/028-implement-numbered-patch-stack-apply-and-verification.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-028: Implement numbered patch-stack apply and verification
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-027`
+- **Blocks (derived):** `DGR-029`, `DGR-034`, `DGR-069`
+- **Labels:** `area:upstream`, `area:patches`, `type:tooling`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/028-implement-numbered-patch-stack-apply-and-verification.md`, and evidence READMEs for dependencies (DGR-027) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Maintain a minimal auditable llama.cpp delta with one numbered patch per concern.
+
+## Acceptance criteria
+
+- [ ] Add deterministic apply/check/reverse verification against the exact manifest pin.
+- [ ] Separate range loading, boundary I/O, filtered state, and worker hooks into scoped patches.
+- [ ] Record upstream file/API assumptions and fail with the first incompatible patch when the pin changes.
+- [ ] Verify license/attribution and prove no Meshnet routing, billing, relay, or authentication code enters the patch stack.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-028/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/029-create-the-native-cmake-skeleton-and-deterministic-cpu-lane.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-029: Create the native CMake skeleton and deterministic CPU lane
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-027`, `DGR-028`
+- **Blocks (derived):** `DGR-030`, `DGR-034`
+- **Labels:** `area:build`, `type:toolchain`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/029-create-the-native-cmake-skeleton-and-deterministic-cpu-lane.md`, and evidence READMEs for dependencies (DGR-027, DGR-028) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Establish an out-of-tree standalone native build with a deterministic CPU lane before accelerator matrix work.
+
+## Acceptance criteria
+
+- [ ] Create the standalone native CMake target/skeleton and isolated out-of-tree configure/build preset for CPU.
+- [ ] Build and run a deterministic model-free CPU smoke/CTest lane from a clean checkout with actionable toolchain failures.
+- [ ] Keep fetched upstream sources, generated bindings, and all build outputs ignored and out of tree.
+- [ ] Ensure build success alone does not advertise any backend/model/recipe capability.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-029/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/030-add-accelerator-build-presets-and-native-ci-matrix.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-030: Add accelerator build presets and native CI matrix
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-029`
+- **Blocks (derived):** `DGR-053`, `DGR-067`, `DGR-068`
+- **Labels:** `area:build`, `area:hardware`, `type:toolchain`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `optional`
+- **Model:** `generic`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/030-add-accelerator-build-presets-and-native-ci-matrix.md`, and evidence READMEs for dependencies (DGR-029) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Compile all required accelerator lanes reproducibly while keeping untested real-hardware capabilities registered-dark.
+
+## Acceptance criteria
+
+- [ ] Add isolated out-of-tree presets for CUDA, ROCm, Vulkan, and Metal without changing the deterministic CPU default.
+- [ ] Add a native CI/build matrix that reports unavailable SDKs as explicit unavailable/skipped lanes rather than false success.
+- [ ] Compile each available lane and preserve exact compiler, SDK, upstream pin, patch-stack, and build-option evidence.
+- [ ] Keep every backend/model/recipe lane registered-dark until a separate real-hardware certification record exists.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-030/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/031-introduce-the-project-owned-shardengine-interface.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-031: Introduce the project-owned `ShardEngine` interface
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-021`, `DGR-025`
+- **Blocks (derived):** `DGR-032`, `DGR-034`, `DGR-035`, `DGR-037`
+- **Labels:** `area:engine`, `type:architecture`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/031-introduce-the-project-owned-shardengine-interface.md`, and evidence READMEs for dependencies (DGR-021, DGR-025) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Isolate worker/protocol code from llama.cpp internals behind a stable project-owned engine contract.
+
+## Acceptance criteria
+
+- [ ] Define load, capabilities, prefill/decode, boundary/logits result, cancel, release, health, and metrics operations.
+- [ ] Use project-owned request/result/state types; expose no `ggml_tensor`, llama context, scheduler, or ABI-owned structure.
+- [ ] Reserve typed MTP and architecture auxiliary-state hooks without enabling them.
+- [ ] Add contract tests proving fake and future llama implementations obey identical lifecycle semantics.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-031/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/032-implement-deterministic-fake-shardengine.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-032: Implement deterministic fake `ShardEngine`
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-031`
+- **Blocks (derived):** `DGR-033`
+- **Labels:** `area:engine`, `area:testing`, `type:fixture`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `fake`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/032-implement-deterministic-fake-shardengine.md`, and evidence READMEs for dependencies (DGR-031) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Provide an engine fixture that deterministically transforms typed boundary bundles and session state.
+
+## Acceptance criteria
+
+- [ ] Support head, middle, tail, prefill, decode, cancellation, and release with deterministic outputs.
+- [ ] Model isolated session/epoch state and deterministic cache-miss/stale-epoch failures.
+- [ ] Support configurable delay, memory pressure, malformed output, and crash injection.
+- [ ] Contract tests distinguish fixture evidence from real-model certification.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-032/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/033-build-a-standalone-fake-c-grpc-shard-worker.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-033: Build a standalone fake C++ gRPC Shard worker
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M1`
+- **Dependencies:** `DGR-022`, `DGR-024`, `DGR-032`
+- **Blocks (derived):** `DGR-036`, `DGR-040`
+- **Labels:** `area:worker`, `area:grpc`, `type:vertical-slice`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `fake`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/033-build-a-standalone-fake-c-grpc-shard-worker.md`, and evidence READMEs for dependencies (DGR-022, DGR-024, DGR-032) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove the standalone worker process, stream, lifecycle, and supervision shape before llama.cpp integration.
+
+## Acceptance criteria
+
+- [ ] A standalone C++ executable serves the complete lifecycle and stream RPC contract using the fake engine.
+- [ ] Python integration tests cover startup, health, capability, fragmented prefill, decode, release, cancellation, and graceful shutdown.
+- [ ] Bounded messages, deadlines, flow control, and independent session cancellation are enforced.
+- [ ] The worker exposes neither llama.cpp RPC nor arbitrary graph execution.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-033/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/034-implement-dense-llama-range-aware-gguf-ownership.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-034: Implement dense-Llama range-aware GGUF ownership
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-028`, `DGR-029`, `DGR-031`
+- **Blocks (derived):** `DGR-035`, `DGR-037`, `DGR-051`
+- **Labels:** `area:llama`, `area:weights`, `type:runtime`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `dense-llama`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/034-implement-dense-llama-range-aware-gguf-ownership.md`, and evidence READMEs for dependencies (DGR-028, DGR-029, DGR-031) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Load only the dense-Llama tensors owned by a shard range.
+
+## Acceptance criteria
+
+- [ ] Load only `blk.N.*` tensors in the assigned range, embeddings only at the head, and norm/output or tied output only at the tail.
+- [ ] Derive authoritative range and endpoint ownership from the loaded engine state.
+- [ ] Reject invalid/gapped/out-of-model ranges and unexpected required tensors.
+- [ ] Real-model evidence shows mapped/resident memory scales with owned tensors rather than full artifact size.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-034/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/035-implement-dense-architecture-boundary-input-output.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-035: Implement dense architecture boundary input/output
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-021`, `DGR-031`, `DGR-034`
+- **Blocks (derived):** `DGR-036`, `DGR-037`, `DGR-069`
+- **Labels:** `area:llama`, `area:boundary`, `type:runtime`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `dense-llama`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/035-implement-dense-architecture-boundary-input-output.md`, and evidence READMEs for dependencies (DGR-021, DGR-031, DGR-034) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Execute dense head/middle/tail ranges through an architecture-defined residual boundary.
+
+## Acceptance criteria
+
+- [ ] Head accepts token IDs and owns embedding; middle/tail bypass embedding and accept a named boundary bundle.
+- [ ] Non-tail returns the unnormalized residual before final norm/head and before tail-only row pruning.
+- [ ] Tail returns logits or sampled-token output under an explicit contract.
+- [ ] Uncertified architectures and incompatible boundary schemas fail closed.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-035/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/036-prove-dense-fixture-and-real-model-range-parity.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-036: Prove dense fixture and real-model range parity
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-033`, `DGR-035`
+- **Blocks (derived):** `DGR-039`
+- **Labels:** `area:parity`, `area:testing`, `type:certification`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `dense-llama`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/036-prove-dense-fixture-and-real-model-range-parity.md`, and evidence READMEs for dependencies (DGR-033, DGR-035) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove the engine/protocol seam before adding session concurrency.
+
+## Acceptance criteria
+
+- [ ] Model-free two-stage tests pass through two fake worker processes with disjoint ranges.
+- [ ] A small real dense GGUF passes whole-model versus two-range prefill parity.
+- [ ] At least 32 greedy decode tokens match the locked tolerance.
+- [ ] Evidence distinguishes deterministic fixture proof from opt-in real-model proof.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-036/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/037-bind-llama-cpp-to-the-standalone-worker.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-037: Bind llama.cpp to the standalone worker
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-022`, `DGR-023`, `DGR-031`, `DGR-034`, `DGR-035`
+- **Blocks (derived):** `DGR-038`, `DGR-039`, `DGR-040`, `DGR-051`
+- **Labels:** `area:worker`, `area:llama`, `type:vertical-slice`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `dense-llama`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/037-bind-llama-cpp-to-the-standalone-worker.md`, and evidence READMEs for dependencies (DGR-022, DGR-023, DGR-031, DGR-034, DGR-035) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Replace the fake engine with the pinned llama.cpp `ShardEngine` implementation without changing the public worker contract.
+
+## Acceptance criteria
+
+- [ ] Worker loads exactly one artifact/recipe/range identity and rejects mismatched stream requests.
+- [ ] All execution passes through `ShardEngine`; llama.cpp implementation types remain private.
+- [ ] Health and metrics expose loaded identity, authoritative ownership, memory, and execution state.
+- [ ] Graceful shutdown releases model/session resources; injected process death is observable and bounded.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-037/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/038-implement-isolated-shard-local-hot-kv-state.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-038: Implement isolated shard-local Hot KV State
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-037`
+- **Blocks (derived):** `DGR-039`, `DGR-052`, `DGR-055`, `DGR-069`
+- **Labels:** `area:kv-cache`, `area:concurrency`, `type:runtime`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `dense-llama`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/038-implement-isolated-shard-local-hot-kv-state.md`, and evidence READMEs for dependencies (DGR-037) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Map each route session and epoch to isolated state containing only locally owned layers.
+
+## Acceptance criteria
+
+- [ ] Map `(route_session_id, route_epoch)` to an isolated llama sequence or bounded context.
+- [ ] Support prefill/decode append, truncate, release, TTL/LRU eviction, cache miss, and stale-epoch rejection.
+- [ ] Four concurrent sessions complete without token, KV, position, or cancellation cross-talk.
+- [ ] Release/eviction returns memory to the configured budget without affecting other sessions.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-038/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/039-pass-local-two-process-dense-acceptance.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-039: Pass local two-process dense acceptance
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-036`, `DGR-037`, `DGR-038`
+- **Blocks (derived):** `DGR-054`
+- **Labels:** `area:integration`, `area:parity`, `type:certification`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `dense-llama`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/039-pass-local-two-process-dense-acceptance.md`, and evidence READMEs for dependencies (DGR-036, DGR-037, DGR-038) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Establish the first real, independently executing distributed GGUF route on one host.
+
+## Acceptance criteria
+
+- [ ] Two worker processes open disjoint dense ranges and both execute real prefill/decode work.
+- [ ] Whole-model parity, 32-token greedy decode, four-session isolation, cancellation, and cleanup pass.
+- [ ] Record TTFT, prefill/decode rates, seam bytes/latency, RSS/VRAM, KV, queue, and failure metrics.
+- [ ] Killing one worker returns a bounded structured failure rather than hanging.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-039/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/040-add-node-side-native-worker-supervision.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-040: Add node-side native worker supervision
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-033`, `DGR-037`
+- **Blocks (derived):** `DGR-041`, `DGR-042`, `DGR-055`, `DGR-058`
+- **Labels:** `area:node`, `area:supervision`, `type:integration`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/040-add-node-side-native-worker-supervision.md`, and evidence READMEs for dependencies (DGR-033, DGR-037) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Let the existing node service safely start, probe, stop, and restart the standalone worker.
+
+## Acceptance criteria
+
+- [ ] Supervision owns process startup, readiness, log capture, graceful shutdown, and bounded forced termination.
+- [ ] Startup verifies worker binary, artifact identity, recipe, and range before registration.
+- [ ] Crashes or health loss make the capability unavailable without corrupting the Transformers backend.
+- [ ] Tests use the fake worker and deterministic crash injection.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-040/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/041-register-native-shard-capabilities-without-redesigning-meshnet.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-041: Register native Shard capabilities without redesigning Meshnet
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-025`, `DGR-040`
+- **Blocks (derived):** `DGR-043`
+- **Labels:** `area:meshnet`, `area:admission`, `type:integration`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/041-register-native-shard-capabilities-without-redesigning-meshnet.md`, and evidence READMEs for dependencies (DGR-025, DGR-040) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Adapt native worker identity and capacity to existing backend-agnostic capability admission.
+
+## Acceptance criteria
+
+- [ ] Registration carries exact recipe fingerprint, authoritative range, backend, memory/KV capacity, concurrency, and certification status.
+- [ ] Existing tracker, billing, routing, telemetry, and provider semantics remain backend-agnostic.
+- [ ] Uncertified backend/model/recipe combinations are visible but unroutable.
+- [ ] Existing Transformers registration and route tests remain unchanged in behavior.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-041/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/042-carry-native-frames-through-direct-and-existing-relay-seams.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-042: Carry native frames through direct and existing relay seams
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-024`, `DGR-040`
+- **Blocks (derived):** `DGR-054`, `DGR-058`
+- **Labels:** `area:meshnet`, `area:relay`, `area:grpc`, `type:integration`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/042-carry-native-frames-through-direct-and-existing-relay-seams.md`, and evidence READMEs for dependencies (DGR-024, DGR-040) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Use direct gRPC where available and the existing relay as opaque protobuf transport without redesigning relay behavior.
+
+## Acceptance criteria
+
+- [ ] Direct paths use the long-lived gRPC activation stream.
+- [ ] Relayed paths carry byte-identical versioned protobuf frames through the existing relay contract.
+- [ ] Request/work identity, cancellation, deadlines, telemetry, billing correlation, and per-node attribution survive both paths.
+- [ ] Fake-worker tests cover direct, relay, disconnect, cancellation, and bounded buffering.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-042/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/043-expose-gguf-compatibility-and-measured-cost-inputs-to-existing-routing.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-043: Expose GGUF compatibility and measured cost inputs to existing routing
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M2`
+- **Dependencies:** `DGR-041`
+- **Blocks (derived):** `DGR-053`, `DGR-054`, `DGR-059`, `DGR-061`
+- **Labels:** `area:tracker`, `area:routing`, `type:integration`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/043-expose-gguf-compatibility-and-measured-cost-inputs-to-existing-routing.md`, and evidence READMEs for dependencies (DGR-041) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Adapt exact GGUF recipe/range compatibility and measured capacity, queue, seam-cost, health, and reliability data into the existing backend-agnostic routing inputs without redesigning routing or load balancing.
+
+## Acceptance criteria
+
+- [ ] Expose exact recipe, range coverage, capacity, queue/load, seam-cost, health, reliability, backend, and certification measurements through existing tracker input contracts.
+- [ ] Prove existing routing forms complete compatible coverage and excludes dark or mismatched candidates using its current backend-agnostic mechanisms.
+- [ ] Regression-test unchanged Transformers behavior and unchanged tracker routing, load-balancing, billing, relay, and provider semantics.
+- [ ] Regression-test that no quant, stage count, fixed split, architecture, backend sequence, or DeepSeek-specific policy is hardcoded.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-043/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/044-pin-the-deepseek-v4-flash-target-contract.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-044: Pin the DeepSeek V4 Flash target contract
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-019`, `DGR-025`, `DGR-026`, `DGR-027`
+- **Blocks (derived):** `DGR-045`
+- **Labels:** `area:deepseek-v4`, `area:provenance`, `type:contract`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/044-pin-the-deepseek-v4-flash-target-contract.md`, and evidence READMEs for dependencies (DGR-019, DGR-025, DGR-026, DGR-027) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Fix the alpha/beta model identity and upstream maturity assumptions before implementing the adapter.
+
+## Acceptance criteria
+
+- [ ] Pin Hugging Face target SHA `60d8d70770c6776ff598c94bb586a859a38244f1`.
+- [ ] Record the selected GGUF provenance and exact source binding without assuming one quant.
+- [ ] Record that llama.cpp support began with PR 24162/commit `8c146a8` and remains maturing; the build manifest still pins one exact validated upstream commit.
+- [ ] Record 43 main layers plus MTP and all known architecture-specific state obligations.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-044/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/045-inventory-v4-gguf-tensors-and-layer-ownership.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-045: Inventory V4 GGUF tensors and layer ownership
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-026`, `DGR-044`
+- **Blocks (derived):** `DGR-046`, `DGR-047`, `DGR-050`
+- **Labels:** `area:deepseek-v4`, `area:weights`, `type:research-spike`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `none`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/045-inventory-v4-gguf-tensors-and-layer-ownership.md`, and evidence READMEs for dependencies (DGR-026, DGR-044) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Derive exact head, repeated-layer, tail, expert, auxiliary-state, and MTP ownership from the pinned artifact.
+
+## Acceptance criteria
+
+- [ ] Produce a machine-readable inventory tied to the target SHA and exact GGUF artifact.
+- [ ] Classify embeddings, 43 main layers, final head, MTP, mHC, attention variants, indexer/compressor, and MoE tensors.
+- [ ] Validate half-open range ownership and fail on unclassified required tensors.
+- [ ] Inventory tooling works across quants without embedding quant names in architecture logic.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-045/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/046-define-the-v4-typed-architecture-boundary-schema.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-046: Define the V4 typed architecture boundary schema
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-021`, `DGR-045`
+- **Blocks (derived):** `DGR-047`, `DGR-048`, `DGR-049`
+- **Labels:** `area:deepseek-v4`, `area:boundary`, `type:protocol`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `model-free`
+- **Hardware:** `none`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/046-define-the-v4-typed-architecture-boundary-schema.md`, and evidence READMEs for dependencies (DGR-021, DGR-045) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Define the exact cross-stage V4 architecture boundary while keeping per-layer attention and auxiliary caches shard-local.
+
+## Acceptance criteria
+
+- [ ] Define a versioned named bundle for the mHC 4×4096 residual boundary, positions, token-ID sideband where required, and schema/cache expectations.
+- [ ] Explicitly exclude per-layer CSA, HCA, SWA, indexer, compressor, KV, and MTP caches/state from the WAN boundary; those remain local to the owning shard and session/epoch.
+- [ ] Reserve typed MTP boundary fields but mark MTP execution unsupported and unroutable for alpha.
+- [ ] Fingerprint independently of quant/topology and fail closed on missing, incompatible, incorrectly shaped, or stale boundary/cache expectations.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-046/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/047-adapt-the-upstream-v4-mhc-boundary-for-ranged-ownership.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-047: Adapt the upstream V4 mHC boundary for ranged ownership
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-045`, `DGR-046`
+- **Blocks (derived):** `DGR-048`, `DGR-049`, `DGR-050`, `DGR-051`
+- **Labels:** `area:deepseek-v4`, `area:mhc`, `type:runtime`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/047-adapt-the-upstream-v4-mhc-boundary-for-ranged-ownership.md`, and evidence READMEs for dependencies (DGR-045, DGR-046) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Add range-boundary adapters around upstream llama.cpp V4 mHC execution without reimplementing the V4 graph or kernels.
+
+## Acceptance criteria
+
+- [ ] Represent and validate the upstream V4 4×4096 mHC boundary without flattening semantic axes.
+- [ ] Add only head/intermediate/tail range ownership and boundary conversion hooks around the pinned upstream llama.cpp graph.
+- [ ] Compare deterministic fixture vectors and single-process ranged outputs with upstream whole-model execution.
+- [ ] Document that llama.cpp owns V4 mHC graph/kernels and that quantized storage does not alter the logical boundary schema.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-047/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/048-carry-token-id-sideband-through-the-first-three-hash-routed-layers.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-048: Carry token-ID sideband through the first three hash-routed layers
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-046`, `DGR-047`
+- **Blocks (derived):** `DGR-051`
+- **Labels:** `area:deepseek-v4`, `area:routing-state`, `type:runtime`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/048-carry-token-id-sideband-through-the-first-three-hash-routed-layers.md`, and evidence READMEs for dependencies (DGR-046, DGR-047) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Ensure any stage containing the first three hash-routed layers receives exact token identities.
+
+## Acceptance criteria
+
+- [ ] Head emits token IDs in the typed sideband for boundaries that require them.
+- [ ] Intermediate stages preserve or consume the sideband according to their layer range.
+- [ ] Routes splitting before, within, and after the first three layers pass deterministic partition tests.
+- [ ] Missing or mismatched token IDs fail closed rather than silently selecting incorrect experts.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-048/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/049-keep-v4-attention-and-auxiliary-state-shard-local.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-049: Keep V4 attention and auxiliary state shard-local
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-046`, `DGR-047`
+- **Blocks (derived):** `DGR-051`
+- **Labels:** `area:deepseek-v4`, `area:attention`, `type:runtime`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/049-keep-v4-attention-and-auxiliary-state-shard-local.md`, and evidence READMEs for dependencies (DGR-046, DGR-047) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Bind V4 CSA/HCA/SWA/indexer/compressor and KV state to the owning shard session/epoch rather than transferring caches over the WAN.
+
+## Acceptance criteria
+
+- [ ] Map CSA, HCA, SWA, indexer, compressor, and KV ownership from the pinned upstream graph to each owned layer range.
+- [ ] Key all such caches/state by route session and epoch with bounded lifecycle, memory accounting, stale-epoch rejection, release, and eviction.
+- [ ] Prove cross-stage messages carry only the typed architecture boundary and cache expectations, never per-layer cache contents.
+- [ ] On route change or state loss, use explicit cache miss and re-prefill/restart; do not migrate V4 caches across workers.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-049/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/050-validate-upstream-v4-moe-and-hash-routing-execution-under-ranged-ownership.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-050: Validate upstream V4 MoE and hash-routing execution under ranged ownership
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-045`, `DGR-047`
+- **Blocks (derived):** `DGR-051`
+- **Labels:** `area:deepseek-v4`, `area:moe`, `type:runtime`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/050-validate-upstream-v4-moe-and-hash-routing-execution-under-ranged-ownership.md`, and evidence READMEs for dependencies (DGR-045, DGR-047) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Validate the pinned upstream llama.cpp V4 MoE and hash-routing graph when layers are range-owned, without reimplementing routing or expert kernels in Meshnet.
+
+## Acceptance criteria
+
+- [ ] Load range-owned tensors for 256 routed plus one shared expert and validate upstream execution activates six routed experts where specified.
+- [ ] Validate the first three upstream hash-routed layers receive exact token-ID sideband across splits before, within, and after them.
+- [ ] Compare upstream whole-model and ranged router/expert outputs, shared-expert contribution, and malformed sideband failures.
+- [ ] Document that llama.cpp owns V4 MoE, attention, hash routing, graph, and kernels; no expert-parallel WAN collective or Meshnet reimplementation is introduced.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-050/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/051-assemble-the-deepseek-v4-flash-shardengine-adapter.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-051: Assemble the DeepSeek V4 Flash `ShardEngine` adapter
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-034`, `DGR-037`, `DGR-047`, `DGR-048`, `DGR-049`, `DGR-050`
+- **Blocks (derived):** `DGR-052`, `DGR-060`, `DGR-065`, `DGR-069`
+- **Labels:** `area:deepseek-v4`, `area:engine`, `type:vertical-slice`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/051-assemble-the-deepseek-v4-flash-shardengine-adapter.md`, and evidence READMEs for dependencies (DGR-034, DGR-037, DGR-047, DGR-048, DGR-049, DGR-050) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Assemble range ownership hooks and boundary/local-state adapters around upstream llama.cpp V4 execution behind the stable ShardEngine interface.
+
+## Acceptance criteria
+
+- [ ] Support valid head, middle, tail, and whole-model ranges over all 43 main layers using the pinned upstream llama.cpp V4 graph/kernels.
+- [ ] Integrate exact range ownership, mHC boundary, positions, required token-ID sideband, and shard-local session/epoch state adapters.
+- [ ] Report MTP reserved-but-not-executable for alpha and reject unsupported split points or cache expectations.
+- [ ] Include exact adapter/schema/runtime/artifact identity and valid split restrictions without reimplementing V4 MoE, attention, mHC, or hash routing.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-051/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/052-pass-local-v4-whole-model-versus-ranged-parity.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-052: Pass local V4 whole-model versus ranged parity
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-038`, `DGR-051`
+- **Blocks (derived):** `DGR-053`, `DGR-054`
+- **Labels:** `area:deepseek-v4`, `area:parity`, `type:certification`, `priority:p0`, `ready-for-agent`
+- **Evidence class:** `real-model`
+- **Hardware:** `optional`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/052-pass-local-v4-whole-model-versus-ranged-parity.md`, and evidence READMEs for dependencies (DGR-038, DGR-051) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove V4 prefill and decode correctness locally before network certification.
+
+## Acceptance criteria
+
+- [ ] Compare pinned whole-model llama.cpp with at least two valid ranged partitions.
+- [ ] Prefill intermediates and locked-length greedy decode pass architecture-specific tolerances.
+- [ ] Test splits around the first three hash-routed layers and at least one CSA/HCA/SWA/indexer/compressor transition.
+- [ ] Four concurrent sessions pass KV/state isolation and cleanup.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-052/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/053-certify-a-real-2-4-stage-v4-route.md

@@ -0,0 +1,40 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-053: Certify a real 2–4-stage V4 route
+
+- **Status / triage:** specification only; `ready-for-human`; `passes: false`
+- **Execution mode:** `HITL`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-030`, `DGR-043`, `DGR-052`
+- **Blocks (derived):** `DGR-054`, `DGR-062`, `DGR-067`
+- **Labels:** `area:deepseek-v4`, `area:hardware`, `type:certification`, `priority:p0`, `gate:hitl`, `ready-for-human`
+- **Evidence class:** `real-hardware`
+- **Hardware:** `required`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/053-certify-a-real-2-4-stage-v4-route.md`, and evidence READMEs for dependencies (DGR-030, DGR-043, DGR-052) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove real Tracker-selected V4 execution across physical machines before alpha.
+
+## Acceptance criteria
+
+- [ ] Run one documented 2–4-stage certification scenario using exact compatible artifacts/recipes; the count and chosen quant are evidence inputs, not product constants.
+- [ ] Actual CPU/GPU work executes on every stage; fake workers do not satisfy acceptance.
+- [ ] Record parity, TTFT, prefill/decode speed, seam cost, memory, cache/state isolation, cancellation, and cleanup.
+- [ ] Tracker selection remains dynamic and rejects an injected incompatible backend/recipe.
+- [ ] Only the exact real-hardware lanes exercised become eligible for advertisement.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-053/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/054-enforce-the-deepseek-v4-flash-alpha-gate.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-054: Enforce the DeepSeek V4 Flash alpha gate
+
+- **Status / triage:** specification only; `ready-for-human`; `passes: false`
+- **Execution mode:** `HITL`
+- **Milestone:** `M3`
+- **Dependencies:** `DGR-017`, `DGR-019`, `DGR-020`, `DGR-039`, `DGR-042`, `DGR-043`, `DGR-052`, `DGR-053`
+- **Blocks (derived):** `DGR-055`, `DGR-065`, `DGR-066`, `DGR-068`
+- **Labels:** `area:deepseek-v4`, `area:release`, `milestone:alpha`, `priority:p0`, `gate:hitl`, `ready-for-human`
+- **Evidence class:** `release`
+- **Hardware:** `required`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/054-enforce-the-deepseek-v4-flash-alpha-gate.md`, and evidence READMEs for dependencies (DGR-017, DGR-019, DGR-020, DGR-039, DGR-042, DGR-043, DGR-052, DGR-053) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Release alpha only when V4 is correct and clears the pre-locked useful-speed requirement.
+
+## Acceptance criteria
+
+- [ ] Evaluate correctness, model fit, TTFT, prefill/decode speed, seam cost, memory, and failure rate against DGF-004 without changing thresholds.
+- [ ] Separate quant/model-fit gains from runtime/transport gains.
+- [ ] Decision is `alpha`, `optimize measured bottleneck`, or `stop`; failures cannot be relabeled as certification.
+- [ ] Alpha documentation states MTP is reserved but not implemented and identifies every dark hardware lane.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-054/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/055-implement-compatible-continuous-decode-batching.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-055: Implement compatible continuous decode batching
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M4`
+- **Dependencies:** `DGR-038`, `DGR-040`, `DGR-054`
+- **Blocks (derived):** `DGR-056`, `DGR-057`
+- **Labels:** `area:scheduler`, `area:batching`, `type:performance`, `priority:p1`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/055-implement-compatible-continuous-decode-batching.md`, and evidence READMEs for dependencies (DGR-038, DGR-040, DGR-054) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Batch compatible active sessions without violating route, recipe, position, or architecture state.
+
+## Acceptance criteria
+
+- [ ] Batch only sessions with compatible engine, recipe, phase, boundary schema, and state layout.
+- [ ] Preserve per-session positions, sequence IDs, outputs, cancellation, and accounting.
+- [ ] Decode receives bounded service while prefill remains schedulable.
+- [ ] Deterministic 1/2/4/8 concurrency tests show no cross-session corruption.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-055/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/056-enforce-bounded-admission-queues-and-backpressure.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-056: Enforce bounded admission, queues, and backpressure
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M4`
+- **Dependencies:** `DGR-055`
+- **Blocks (derived):** `DGR-057`, `DGR-058`, `DGR-060`
+- **Labels:** `area:scheduler`, `area:backpressure`, `type:performance`, `priority:p1`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/056-enforce-bounded-admission-queues-and-backpressure.md`, and evidence READMEs for dependencies (DGR-055) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prevent weight, KV, state, scratch, and stream buffers from exceeding admitted capacity.
+
+## Acceptance criteria
+
+- [ ] Admission accounts separately for weights, KV/state, scratch, in-flight fragments, and queue slots.
+- [ ] Queue and stream limits produce structured retryable or terminal responses.
+- [ ] Prefill cannot starve decode and one route session cannot monopolize queue capacity.
+- [ ] Telemetry reports active sessions, queue depth/time, batch occupancy, memory pressure, and rejects.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-056/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/057-benchmark-batching-saturation-and-fairness.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-057: Benchmark batching saturation and fairness
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M4`
+- **Dependencies:** `DGR-055`, `DGR-056`
+- **Blocks (derived):** `DGR-061`, `DGR-063`, `DGR-070`
+- **Labels:** `area:performance`, `area:batching`, `type:benchmark`, `priority:p1`, `ready-for-agent`
+- **Evidence class:** `real-hardware`
+- **Hardware:** `required`
+- **Model:** `dense-llama+deepseek-v4`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/057-benchmark-batching-saturation-and-fairness.md`, and evidence READMEs for dependencies (DGR-055, DGR-056) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Identify useful concurrency and saturation points without assuming one global batch size.
+
+## Acceptance criteria
+
+- [ ] Run controlled concurrency 1/2/4/8 and record aggregate throughput, per-request p50/p95, TTFT, queue time, occupancy, and memory.
+- [ ] Measure dense and V4 lanes separately where hardware permits.
+- [ ] Verify bounded fairness and no prefill/decode starvation.
+- [ ] Produce machine-readable saturation recommendations consumed by capability reporting, not hardcoded constants.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-057/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/058-harden-worker-and-stream-failure-semantics.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-058: Harden worker and stream failure semantics
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M4`
+- **Dependencies:** `DGR-040`, `DGR-042`, `DGR-056`
+- **Blocks (derived):** `DGR-059`, `DGR-060`, `DGR-061`
+- **Labels:** `area:reliability`, `area:failure`, `type:hardening`, `priority:p1`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/058-harden-worker-and-stream-failure-semantics.md`, and evidence READMEs for dependencies (DGR-040, DGR-042, DGR-056) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Ensure malformed input, process death, transport reset, and cancellation terminate cleanly.
+
+## Acceptance criteria
+
+- [ ] Test worker death, stream reset, malformed bundle, checksum failure, deadline, cache miss, stale epoch, and partial fragment loss.
+- [ ] Cancellation propagates across all stages and releases KV/state, queue entries, and fragment buffers.
+- [ ] Duplicate steps are idempotent; uncertain mutations are never silently replayed.
+- [ ] Billing/work outcomes distinguish completed, cancelled, failed, and unverified work.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-058/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/059-implement-alpha-safe-route-recovery.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-059: Implement alpha-safe route recovery
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M4`
+- **Dependencies:** `DGR-043`, `DGR-058`
+- **Blocks (derived):** `DGR-070`
+- **Labels:** `area:recovery`, `area:routing`, `type:hardening`, `priority:p1`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/059-implement-alpha-safe-route-recovery.md`, and evidence READMEs for dependencies (DGR-043, DGR-058) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Recover from route loss without importing or continuing unverified state.
+
+## Acceptance criteria
+
+- [ ] On route loss or local-state cache miss, restart from token zero or re-prefill on a newly compatible route according to the locked alpha contract.
+- [ ] Never import KV, CSA, HCA, SWA, indexer, compressor, recurrent, or MTP cache/state across workers.
+- [ ] Keep exact same-route duplicate delivery idempotent while cross-route continuation fails closed.
+- [ ] Test direct/relay loss, cache miss, replacement selection, client cancellation, and billing reconciliation.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-059/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/060-certify-v4-long-context-state-correctness.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-060: Certify V4 long-context state correctness
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M4`
+- **Dependencies:** `DGR-051`, `DGR-056`, `DGR-058`
+- **Blocks (derived):** `DGR-062`, `DGR-064`, `DGR-065`, `DGR-066`, `DGR-070`
+- **Labels:** `area:deepseek-v4`, `area:long-context`, `type:certification`, `priority:p1`, `ready-for-agent`
+- **Evidence class:** `real-hardware`
+- **Hardware:** `required`
+- **Model:** `deepseek-v4-flash`
+- **Upstream:** `yes`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/060-certify-v4-long-context-state-correctness.md`, and evidence READMEs for dependencies (DGR-051, DGR-056, DGR-058) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Prove V4’s KV and auxiliary state remain correct and bounded at long contexts.
+
+## Acceptance criteria
+
+- [ ] Exercise pre-locked context lengths covering multiple prefill chunks and sustained decode.
+- [ ] Validate KV plus CSA/HCA/SWA/indexer/compressor state positions across every stage.
+- [ ] Measure memory growth, fragment sizes, TTFT, decode degradation, cancellation latency, and cleanup.
+- [ ] Cache mismatch, truncation, and context-limit behavior fail deterministically.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-060/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.

.scratch/distributed-gguf-runtime/issues/061-certify-existing-routing-with-10-gguf-stage-candidates.md

@@ -0,0 +1,39 @@
+<!-- GENERATED FROM prd.json — DO NOT EDIT AS AN INDEPENDENT SOURCE. prd.json IS AUTHORITATIVE. -->
+# DGR-061: Certify existing routing with 10+ GGUF stage candidates
+
+- **Status / triage:** specification only; `ready-for-agent`; `passes: false`
+- **Execution mode:** `AFK`
+- **Milestone:** `M4`
+- **Dependencies:** `DGR-043`, `DGR-057`, `DGR-058`
+- **Blocks (derived):** `DGR-062`, `DGR-063`
+- **Labels:** `area:tracker`, `area:scale`, `type:simulation`, `priority:p1`, `ready-for-agent`
+- **Evidence class:** `fixture`
+- **Hardware:** `none`
+- **Model:** `generic`
+- **Upstream:** `no`
+
+## Objective / description
+
+Fresh Ralph session: read `.scratch/distributed-gguf-runtime/RALPH-CONTEXT.md`, source issue `.scratch/distributed-gguf-runtime/issues/061-certify-existing-routing-with-10-gguf-stage-candidates.md`, and evidence READMEs for dependencies (DGR-043, DGR-057, DGR-058) before changing code. Inspect live source/tests rather than trusting legacy pass states. Objective: Certify that existing backend-agnostic routing consumes GGUF compatibility and measured-cost inputs for a 10+ candidate scenario without algorithm or policy redesign.
+
+## Acceptance criteria
+
+- [ ] Generate deterministic pools with 10+ compatible GGUF stage candidates plus slower, overloaded, unhealthy, and incompatible alternatives.
+- [ ] Run the existing routing implementation unchanged and verify complete coverage, compatibility, acyclicity, and use of measured inputs.
+- [ ] Regression-test that no stage count, quant, fixed split, architecture, or backend sequence is encoded in production routing policy.
+- [ ] Verify existing route recomputation reacts to measured load/failure while tracker, load-balancing, billing, relay, and provider semantics remain unchanged.
+- [ ] Applicable shared quality gates in `prd.json` pass, and the evidence handoff records exact commands/results, changed files, limitations, and dependency handoff.
+
+## Shared quality gates
+
+- Targeted deterministic tests pass; Python changes also pass `python -m compileall packages tests`.
+- `git diff --check` passes.
+- Default tests are model-download-free, API-credit-free, and GPU-free.
+- Evidence README records exact changed files, commands/results, limitations, and dependency handoff; no fabricated evidence or inherited completion credit.
+- Native changes pass focused out-of-tree CMake build and CTest; patch changes verify clean apply/check/reverse against the exact llama.cpp pin.
+- Runs are opt-in and record exact artifact/split hashes, runtime/upstream pin, backend/driver, hardware, network, commands, and raw metrics. Model artifacts use configured mounted-drive storage and never `/home`.
+- Preserve existing Transformers behavior and backend-agnostic Tracker routing/load balancing/billing/relay semantics unless an explicit versioned contract says otherwise. One scoped story commit is expected during execution, but this specification-materialization change is not committed.
+
+## Evidence handoff
+
+Write and verify `.scratch/distributed-gguf-runtime/evidence/DGR-061/README.md`. Until every criterion and applicable gate has real evidence, this story remains `passes: false`. Legacy evidence is provenance only, not completion credit.