specrails-desktop 2.64.1 → 2.65.0

package/docs/internals/openspec-workflow.md

@@ -275,6 +275,38 @@ These are handy for tooling that wants to surface the artifact set without parsi
 
 ---
 
+## Requirement traceability in CI
+
+With a Core that announces `specTrace: 1` (contract 5.5), every OpenSpec requirement has a stable id `<capability>/<slug>` (from `### Requirement: <name>` in `openspec/specs/<capability>/spec.md`: accents removed, lowercase, every run of non-alphanumerics one `-`). A test claims a requirement with `[spec:<capability>/<slug>]` anywhere in its title, or a `// spec: <capability>/<slug>` comment (`# spec:` in Python and shell) on the line before it.
+
+Add the check after your test suite so CI fails when a requirement the change adds, modifies or renames has no passing tagged test:
+
+```jsonc
+// package.json
+{
+  "scripts": {
+    "test": "vitest run",
+    "spec:check": "specrails-core pipeline trace --check --tests-passed"
+  }
+}
+```
+
+```yaml
+# .github/workflows/ci.yml (job steps)
+- run: npm ci
+- run: npm test
+- run: npm run spec:check   # exits 1 and names each touched requirement that is not demonstrated
+```
+
+- `--tests-passed` tells the scanner the suite already passed in this job (CI has no Specrails verification receipt). Run it only after the tests.
+- Without `--check` the command only reports (exit 0, never fails), which is useful to see `Requirements demonstrated X/Y` locally: `npx specrails-core pipeline trace`.
+- `--change <name>` limits the check to one change; `--tests <glob>` restricts which files count as tests; `--json` prints the report. Inside an installed project the same scanner ships as `node .specrails/runtime/trace.mjs --check --tests-passed`.
+- `specrails-core` must be available to CI (a dev dependency or `npx specrails-core@<version>`).
+
+In a run, Core writes the same report as `spec-trace.json` after each passing verification; the review packet shows it as **Requirements demonstrated X/Y** and loop economics sums it per loop. See [existing-project anchoring](existing-project-anchoring.md#requirement-traceability).
+
+---
+
 ## Further reading
 
 - [CLI reference](../cli.md) — the `specrails-desktop` CLI and its verbs

package/docs/internals/operations-runbook.md

@@ -89,6 +89,36 @@ cp -r ~/.specrails/ ~/specrails-backup-$(date +%Y%m%d)/
 
 Your project source code and each project's `.specrails/` folder (specs, profiles, plugins) live in your repos, not here — they are not part of this backup.
 
+## Metrics baseline export
+
+`npm run metrics:baseline` ([scripts/metrics-baseline.mjs](../../scripts/metrics-baseline.mjs))
+captures a delivery-economics baseline from local data. It reads the registry
+(`~/.specrails/desktop.sqlite`, or `$SPECRAILS_REGISTRY_HOME/.specrails/…` like the
+server) and every registered project's `jobs.sqlite` strictly read-only, so it is
+safe while the app runs.
+
+```bash
+npm run metrics:baseline                                   # last 28 days, all projects
+npm run metrics:baseline -- --since 2026-10-01 --until 2026-10-15 --project darkera --out ~/metrics
+```
+
+`--project` accepts a slug or id and may repeat; `--since`/`--until` take a date or
+ISO timestamp (window `[since, until)` on the delivery's `created_at`). Output is
+`baseline-<YYYY-MM-DD>.json` and `.csv` in `--out` (default `~/.specrails/metrics/`;
+paths inside the repository are refused), plus a per-loop summary table on stdout.
+
+One row per Safe-PR delivery (`rail_pr_deliveries`). The JSON adds `byLoop`, `byTicket`
+and `totals` rollups (deliveries, merged/discarded/superseded/failed, cost per priced
+delivery, review/fixer rounds per delivery, median build and on_review time).
+
+| Field | Source and semantics |
+| --- | --- |
+| `costUsd`, `estimatedCostUsd` | `ai_invocations` attributed like `sumInvocationCostForRuns`: `loop_run_id` in `run_ids`, `surface_ref_id` = run id, or `<runId>:merge:*`. `costUsd` includes estimated rows; `estimatedCostUsd` is the pricing-table portion. **`null` means no priced rows (unknown), never $0.** `unpricedInvocations`/`costComplete` show partial coverage. Multi-ticket launches attribute per ticket via `ai_invocations.ticket_id`. |
+| `reviewRounds`, `fixerRounds` | `loop_step` events of the delivery's runs whose node is `reviewer`/`fixer`. |
+| `buildDurationMs` | delivery `created_at` → latest attributed loop run `finished_at`. |
+| `onReviewMsApprox` | Approximate: build settle → `updated_at` for decided rows that succeeded; open `on_review` rows run to the window end (`onReviewOpen`). There is no dedicated on_review timestamp. |
+| `decision`, `isContinuation`, `supersedesDeliveryId`, `revisionOf` | Copied from the delivery row; discards are `decision = 'discarded'`. |
+
 ## Troubleshooting
 
 ### Port already in use

package/docs/internals/profiles.md

@@ -120,9 +120,12 @@ template/duplicate/edit and rail execution remain available.
 
 ## 6. Troubleshooting
 
-- **Upgrade banner on Agents page** — run
-  `npx specrails-core@^4.12.0 update` in the project to bring it up to date
-  (profiles need ≥ 4.1.0; the version the app installs is `^4.12.0`).
+- **Upgrade banner on Agents page** — the project's workspace was assembled
+  by a Core older than 4.1.0 (profiles need ≥ 4.1.0). The app installs Core 6
+  (`CORE_PACKAGE_SPEC` in `server/core-package.ts`). The banner's **Open Core
+  updates** button opens **Settings → Updates**; update Core there (see
+  [Core runtime updates](core-runtime-updates.md)) and stale workspaces are
+  re-assembled automatically after the swap.
 - **Save disabled with "N issues to resolve"** — the live validator
   enforces the baseline trio (`sr-architect`, `sr-developer`, `sr-reviewer`)
   and routing ordering. Among the rules: a `default: true` routing rule (if

package/docs/internals/programmatic-agent-runtime.md

@@ -4,6 +4,8 @@ Desktop owns the Implement, Freestyle and Quick SDD workflow graphs and their lo
 
 This is the only implementation engine in the current source tree. It applies to implementation rail steps and their Core completion check. Mission chat and unrelated AI features keep their existing transports. Provider-native implementation prompts and skills are not invoked inside the programmatic phases.
 
+The bridge passes Desktop's environment to Core, and Core's provider CLIs inherit it. `coreProviderEnv` adds `GEMINI_CLI_TRUST_WORKSPACE=true` (unless the host set a value) because Gemini CLI exits 55 in a folder that was never trusted interactively, which includes every rail worktree. Desktop already trusts the admitted workspace this way for its own Gemini spawns.
+
 ## Build the paired source
 
 Use Node **22.22.3+** for Core; Node **22.22.3** matches Desktop's native CI runtime. Provider requirements can be higher. Both repositories' dependencies must be installed.
@@ -143,6 +145,12 @@ Desktop launches `node <Core>/dist/agent-runtime/cli.js` with structured argv (`
 
 Provider invocation/cancellation supports native macOS processes and Windows executables/npm shims. Actual provider behavior still depends on the installed CLI version and capabilities. The offline tests cover fake CLI/ACP frames, Windows argv rules, a local HTTP coding fixture and real verification subprocesses; live provider smoke tests and Windows CI remain separate validation.
 
+## Failure diagnosis (contract 5.8)
+
+Core 5.8 adds `failure` to `runtime-result` and `runtime-status` for a run that ended `failed` or `blocked`: `{ kind, phase?, rounds?, resetAt?, detail?, resumablePhase?, confidence }` with `kind` one of `tests_failed`, `provider_limit`, `environment`, `blocked`, `timeout`, `tool_inactivity`, `crash`, `unknown` (see Core's `docs/agent-runtime.md#failure-classification`). The bridge forwards it untouched as `AiStepResult.failure`; the loop run manager hands it, with the loop's own signals (stall reason, provider-limit notice, Core's fixed blocker sentences, `completion.blocker`), to the [recovery module](../../server/modules/recovery/README.md), which validates it and persists the resulting diagnosis in `loop_runs.failure_diagnosis` in the same commit as the outcome. An older Core sends no `failure`: Desktop derives a diagnosis from those signals and otherwise stores `unknown` with low confidence, never a guessed cause. Desktop never reads the capability: an absent field is simply an absent classification.
+
+The diagnosis card (client feature [recovery](../../client/src/features/recovery/README.md)) shows it on Job Detail, the mission run card and, as a sentence, the inbox row. Its remedies are the app's existing actions: runtime resume, run again / relaunch, opening the spec (addenda), the host blocker's required action, and the log at the failing step.
+
 ## Definition catalog compatibility (D0)
 
 Desktop accepts optional `engineVersion`, `nodeKindsVersion`, `nodeKinds` and

package/docs/internals/project-builder.md

@@ -16,7 +16,7 @@
 "+ Add Project" shows an **Existing | New** pre-screen (`AddProjectDialog`,
 `chooser-existing` / `chooser-new` cards) when both `FEATURE_PROJECT_BUILDER`
 (client) and the parent-wired `onOpenBuilder` callback are present. *Existing*
-continues into the unchanged AddProjectDialog/setup-wizard flow; *New* calls
+continues into the AddProjectDialog register flow (silent background workspace assembly, no wizard); *New* calls
 `AgentChatContext.builderMode.enter()` — the AGENT transforms into the Builder
 (change `reskin-project-builder-into-agent-panel`; the original full-screen
 `ProjectBuilderShell` overlay is deleted). Flags:

package/docs/internals/review-packet.md

@@ -59,7 +59,12 @@ GET /rails/pr-deliveries/:id/packet
       └─ resolveAcceptCapability()  git remote + `gh auth token`
 ```
 
-Nothing in the read path re-reads a mutable store, spawns a model, or writes.
+`agentActions` ("What the agent did") counts the delivery runs' rows in the
+[agent actions audit](agent-actions-audit.md) by kind and lists the runs that
+have rows, each with a JSONL/CSV export. It is `null` when nothing was recorded.
+Unlike the frozen fields above it reads the live log, so retention can shrink it.
+
+Apart from `agentActions`, nothing in the read path re-reads a mutable store, spawns a model, or writes.
 Composing the same delivery twice returns an identical document.
 
 ## Variants
@@ -138,14 +143,15 @@ older clients drop the whole PR card — and supersession already means "a newer
 attempt replaced the previous one". Version lineage, crash-restore and
 one-active-generation-per-rail all come free from the shipped machinery.
 
-**The loop.** `factory:revision` is the fourth factory loop: `{{cmd:revise}}` (a
-distilled step that applies the one requested change on top of the branch and
-then runs the reviewer role (`sr-reviewer`) over the resulting diff, so packet v2 keeps its reviewer
-tier) followed by the standard `{{cmd:verify}}`. No Architect step — the plan and
-the code already exist. It is resolvable by id but deliberately NOT listed in the
-public catalog: its prompt consumes `{{const:REVISION_REQUEST}}`, which only a
-revision launch injects. The router forces this loop for any revision whatever
-the rail's stored mode is; without that, every tweak would re-run implement.
+**The loop.** There is no dedicated Revision loop. `factory:revision` survives
+only as a legacy persisted id: `loop-factory.ts` aliases it to
+`factory:sdd-quick-openspec` (SDD Quick) and it is neither listed nor run as its
+own graph. A revision launch without an explicit workflow (no `loopId` and no
+`mode` in the body) runs SDD Quick; an explicit `loopId`/`mode` takes
+precedence. The revision intent travels as `{{const:REVISION_REQUEST}}`, which
+`rail-isolated-launch.ts` fills from the revision seed and the loop executors
+append to each AI step's prompt, so the run applies the requested change on top
+of the delivered branch instead of re-running Implement from scratch.
 
 **Fresh session by contract** (`server/modules/execution/runtime/revision-seed.ts`). The run is seeded from
 durable state — the instruction, the frozen spec, the branch that carries the
@@ -210,6 +216,69 @@ two surfaces disagree about what the same person had chosen. With
 `VITE_FEATURE_NARRATED_PROGRESS=false` both surfaces render byte-identically to
 their pre-change behaviour, with no toggle at all.
 
+## Changes tab (in-app diff review)
+
+The packet has two tabs, **Overview** (everything above) and **Changes**
+(`?tab=changes`). The Changes tab answers "what did it change, and what did the
+reviewer flag where?" without leaving the app. It is read-only and agent-directed:
+there are no person-to-person threads; human review stays on GitHub.
+
+**Server** (`server/modules/delivery/runtime/delivery-changes.ts`, routes in
+`rails-router.ts`, endpoints in the [API reference](api-reference.md)):
+
+- Source: the delivery head (settled `delivery_sha`, else the assembled branch;
+  per-unit `finalSha`/branch when there is none) against its **merge-base** with
+  `base_branch`, so a base that moved on does not leak in. A multi-repository
+  delivery resolves the repository's frozen source path like the packet.
+- Git is the hardened, cwd-scoped reader (`gitExecEnv`, `--literal-pathspecs`,
+  `--no-ext-diff --no-textconv`), only `diff` / `merge-base` / `rev-parse`. A ref
+  from the database that starts with `-` is refused; the file endpoint only
+  accepts a path the diff itself lists.
+- The list is `--raw -z` (status, blob ids) joined with `--numstat -z` (counts;
+  `-`/`-` = binary). `hash` = old+new blob ids, so it changes exactly when the
+  file's diff does. One file is parsed lazily; past 4000 lines it returns a
+  capped diff with `truncated` and the client offers "Load full file diff".
+- Annotations (`collectAnnotations`) are read from durable rows only: the
+  reviewer's `acceptance.findings`, anchored by **Core contract 5.9**
+  `acceptance.findingLocations` (`{ finding, path, line?, endLine? }`, validated
+  and re-indexed by `readFindingLocations` in `delivery-evidence.ts`, stored in
+  the runtime evidence as `findingLocations`); review-brief risks whose `ref` is a
+  bare `path[:line[-end]]` and `untested` files; and the comments of a PR
+  follow-up that carry a path/line. Anything without a location keeps
+  `location: null`.
+
+**Client** (`client/src/features/delivery/components/review-packet/ChangesTab.tsx`,
+model in `lib/changes-model.ts`):
+
+- File tree (ARIA `tree`, virtualised) with status letter, `+`/`−` and a viewed
+  tick; the diff (unified or split, persisted per viewer) is a virtualised row
+  list, one file at a time. Numbers in the gutter are buttons; Shift extends.
+- Annotations render under their line. One that names a file but a line outside
+  the displayed hunks pins to the file header; one that names no file of the
+  change (or no place at all, e.g. every finding from an older run) is listed
+  above the tree. Nothing is dropped.
+- "Ask agent for a change" files a **spec addendum** (`review-feedback`, the
+  existing carrier: `POST /tickets/:id/addenda`) containing `path:lines`, the
+  selected snippet and the note, then toasts with a link to the spec. It does
+  not launch a run; the next run on the spec is briefed with it
+  ([spec addenda](spec-addenda.md)). "Ask for changes" on the Overview starts one.
+- "Open in editor" builds `vscode://file/<abs>:<line>`, `cursor://file/…` or
+  `idea://open?file=…&line=…` (`client/src/lib/open-in-editor.ts`) and hands it to
+  the shell opener; the editor is a per-machine preference in Settings ▸ Code
+  (default VS Code). The Tauri `shell:allow-open` scope allows those three
+  schemes. The file path is the retained worktree when it still exists
+  (`rootKind: 'worktree'`), else the project checkout, where the review branch
+  may not be checked out.
+- "Viewed" marks live in `localStorage` per viewer, project, delivery and file,
+  keyed to the file's `hash`; a changed diff reads as unviewed again ("Changed
+  since you viewed it").
+- Keys (not while typing): `j`/`k` files, `n`/`p` annotations, `v` viewed; all in
+  the cheatsheet. Annotation cards are focusable.
+
+Limits: the diff is the committed state; uncommitted edits are not shown. Past
+2000 files the list is truncated (flagged). Split layout clips very long lines
+instead of scrolling horizontally.
+
 ## Flags
 
 - `SPECRAILS_REVIEW_PACKET=false` → the packet route 404s.
@@ -231,3 +300,86 @@ Observed: the section rendered the spec's *Proposed Solution* digest as raw mark
 Observed: a delivery built by the programmatic agent runtime (core-host) rendered **"The AI did not report any verification"** and **"No reviewer score"** although the host had run `npm test` (exit 0, output persisted) and the reviewer returned a structured verdict (score 92). The harvest only knew the legacy loop channels — the `VERIFICATION:` prose sentinel and `openspec/changes/**/confidence-score.json` — neither of which that runtime produces. Fix (`server/modules/delivery/runtime/delivery-evidence.ts` `readRuntimeEvidence`, wired from `rail-isolated-launch.ts` via the new `EvidenceHarvestUnit.runtimeDir` = `<workspace>/.specrails/pipeline/<runId>`): read `state.json` `verification.commands[]` (+ each `verification/evidence/<id>.json` for exit code, duration, bounded output and `origin`), `acceptance.checks[]` / `acceptance.findings[]`, and the reviewer step output in `agent-workflow/<runId>/checkpoint.json` (`approved`, `score`, `aspects`, `issues`, `summary`). Every field is bounded; a malformed file degrades to nothing.
 
 Tier placement (`review-packet.ts` `buildProof`): commands whose `origin` includes `host` are **app-verified** (`proof.hostCommandPassed|Failed` with exit code + seconds + output tail) — the runtime executed them and recorded the exit code, which is a measurement, not a claim; non-host acceptance checks, the reviewer summary and findings are **ai-reported** (`proof.acceptanceCheckPassed|Failed`, `proof.reviewerSummary`, `proof.reviewerFinding`); the structured verdict fills `confidence` (score/aspects/issues→flags) ONLY when no file-based score exists, so the **reviewer-score** tier and the human-review band work unchanged. `proof.noVerificationReported` is emitted only when no channel reported anything. Older deliveries heal lazily: `GET …/packet` runs `healRuntimeEvidence` over units lacking `runtime` and persists the result (`updatePrDeliverySettleEvidence`), so a packet stops claiming silence once the pipeline dir exists. Still never a numeric test-count claim: the "70 passed" line rides inside the labelled raw output, not as a number the app asserts.
+
+## 2026-10-22 — "What to look at": the reviewer's risk brief first (review-risk-brief-surfaces)
+
+Core contract 5.3 adds an advisory reviewer brief (`reviewBrief: 1` from `runtime api`):
+behaviour changes, invariants touched, untested paths, up to five severity-ordered risks
+(`file:line` refs), human checks and (Phase 3) spec divergences. The approval gate never reads it.
+
+- **Gate.** `coreAnnouncesReviewBrief()` (`delivery-evidence.ts`) probes the active Core. Without the
+  capability `harvestDeliveryEvidence` never reads a brief and the persisted evidence is
+  byte-identical to before; nothing below renders.
+- **Harvest** (`readUnitReviewBrief`, at settle, before worktree release): first
+  `<pipeline>/<runId>/review-brief.json` (`{schemaVersion:1, change, approved, score, recordedAt,
+  brief|null, diagnostic?}`, engine 1); then the engine 2 committed scopes (`implementation` →
+  `review.brief`/`review.briefDiagnostic`, a reviewer `implementation-step`, or the selected reviewer
+  role turn) — definition runs do not put it in `runtime-result`; then `confidence-score.json` →
+  `brief` (approved verdicts). The record is stored on the unit as `reviewBrief` inside the existing
+  `settle_evidence` JSON column, so no migration was needed. Normalization (`review-brief.ts`) is
+  tolerant: entries that break the contract are dropped and counted (`droppedEntries`), risks are
+  re-sorted high → low and capped at five; an unreadable or unknown-version file becomes a record
+  with a `diagnostic` instead of a throw. `healRuntimeEvidence(..., { reviewBrief: true })` fills the
+  brief for older or recovered rows when the packet is opened.
+- **Packet.** `whatToLookAt` merges units (each entry keeps its `ticketId`) in a fixed order —
+  risks (high first), behaviour changes, invariants touched, untested paths, human checks,
+  divergences — plus Core's or Desktop's diagnostics. It is `null` when no unit carries anything to
+  show, and the page renders the section (`WhatToLookAt.tsx`) right after the verdict, before the
+  measured facts. `riskSummary` (`highCount`/`mediumCount`/`lowCount`/`top`/`diagnostic`) is the
+  cheap analytics hook. File refs render as monospace text, not links: the packet links no files
+  elsewhere and the Code explorer shows the base checkout, not the delivery branch.
+- **Cards.** `toPrDeliverySnapshot` derives `riskSummary` from `settle_evidence` (only when a brief
+  exists) and carries it on `rail.pr_state` and the mission card envelope; `TopRiskLine` shows the
+  severity chip and the top risk on the mission card and the dashboard strip.
+- **Honesty.** The brief is AI-reported advice, labelled as such; it adds no numeric verification
+  claim and no decision depends on it.
+
+## 2026-10-22 — Derivation (Flow → Spec)
+
+A delivery of the `factory:flow-spec` loop ([Flow mode](flow-mode.md)) carries
+`packet.derivation`, rendered as the **Derivation** card before "What to watch
+out for". Source: the `derive-change` scope of Core's `runtime status`
+(`output.derivation`; when only `output.derivationPath` is present the harvest
+reads that `derivation.json`, ≤ 512 KB), projected by
+`projectDefinitionRuntimeEvidence` into `settle_evidence.units[].runtime.derivation`
+(`parseDerivation`: counts clamped, unexplained list capped at 200 with the
+remainder in `unexplainedOmitted`). The latest derive attempt wins, so a
+repaired derivation supersedes the rejected one.
+
+- Coverage (`explained/files`) and the unexplained file list are Core's own
+  measurement from git: app-verified.
+- The deriver's `confidence` is AI-reported and labelled as such.
+- `{ status: 'unavailable' }` for a Flow → Spec delivery whose report could
+  not be read; `null` for every other loop.
+- `packet.flowSettlement` (`specRewrite`, `jiraCreate`, `jiraReview`) comes from
+  the Flow module's `flow_effects` rows; a `failed` spec rewrite shows a note
+  that the spec kept its Flow draft.
+
+The draft PR body adds one line (`buildDerivationLine`):
+`> Derived from a Flow session: OpenSpec change \`x\`, N/M changed files explained by its design (K unexplained — see the review packet).`
+
+## 2026-10-22 — Requirements demonstrated, baseline and "Needs human eyes"
+
+Three advisory sections, each gated on a Core capability and absent (`null`)
+otherwise, so older packets read exactly as before. They render after "What to
+look at"; none ever gates a decision. Source and rules in
+[existing-project anchoring](existing-project-anchoring.md).
+
+- **Needs human eyes** (`packet.needsHumanEyes`, Core `rulesInventory: 1`): the
+  project's `humanOnly` rules from `.specrails/rules.json`, frozen into
+  `settle_evidence.humanRules` when the delivery settles.
+- **Requirements demonstrated X/Y** (`packet.requirementsDemonstrated`, Core
+  `specTrace: 1`): `settle_evidence.units[].specTrace` (Core's
+  `spec-trace.json`) merged across units. Lists undemonstrated requirements
+  first (the ones this change touches are flagged), then demonstrated ones with
+  their first tagged test, then tags that match no requirement. App-verified:
+  Core crossed test tags with the verification receipt; a trace without a
+  receipt says so.
+- **Spec created where the work passed** (`packet.baseline`, Core
+  `baselineOnTouch: 1`): one entry per unit whose run planned a baseline
+  (`baseline.json`): status (`planned`, `passed`, `failed`, `violated`), the
+  module described, the as-built requirements per capability with how many are
+  demonstrated, Core's reason when it blocked, and the baseline's own cost.
+  The cost line in the header adds "baseline $X of it" when every baseline
+  reported a cost.
+

package/docs/internals/safe-pr-review-flow.md

@@ -104,11 +104,98 @@ them to the backlog. Existing-PR no-change cards only dismiss their borrowed fol
 **`merge-local` (remote-less acceptance).** Legal only without a real PR. Both surfaces confirm
 because it advances the local integration branch. Exact delivered commits are first assembled away
 from the user's checkout; only a complete conflict-free result may advance the still-at-the-original-
-HEAD integration branch. Compatible staged, unstaged, untracked and ignored local files survive;
-Git refuses an overwrite with a retryable `merge_local_blocked` response. If the user is on another
-branch or detached HEAD, a temporary checkout claims the base without switching the user's checkout.
-A base already held by another worktree remains untouched and reports `integration_branch_busy`.
-Both temporary checkouts use non-force cleanup, including after a Git runner exception.
+HEAD integration branch. Compatible staged, unstaged, untracked and ignored local files survive.
+If the user is on another branch or detached HEAD, a temporary checkout claims the base without
+switching the user's checkout. A base already held by another worktree remains untouched and
+reports `integration_branch_busy`. Both temporary checkouts use non-force cleanup, including after a
+Git runner exception.
+
+**Uncommitted work that overlaps the delivery (proactive local integration,
+[local-stash.ts](../../server/modules/delivery/runtime/local-stash.ts),
+[local-changes.ts](../../server/modules/delivery/adapters/decisions/local-changes.ts)).** Still under
+the repository lock and the decision lease, after the isolated assembly and before the fast-forward:
+
+1. The checkout's dirty paths (`git status -z --untracked-files=all`, never ignored, minus
+   `PR_NEVER_STAGE_PATHSPEC_ROOTS`) are compared with `git diff --name-only <head> <assembled>`
+   (exact, nested and case-folded). No overlap ⇒ today's behaviour: Git's non-forced fast-forward
+   keeps the work in place. Overlap (or a fast-forward refused for local changes) ⇒
+   `git stash push --include-untracked -m "specrails: before integrating #<ids> (<deliveryId>)"`
+   with the same exclusions. The entry is proven by `refs/stash` moving to a commit whose subject
+   carries the delivery id, and recorded by **commit sha** in `rail_pr_deliveries.local_stash`
+   (migration 83, `LocalStashRecord`) *before* the branch moves. That write is lease-independent
+   (`setPrDeliveryLocalStash`), like a safety archive. Ignored files are never stashed, so an ignored
+   collision still returns `merge_local_blocked` / `dirty`.
+2. The fast-forward runs exactly as before. If it fails, the branch did not move and the stash is
+   applied straight back.
+3. After the verified advance, `git stash apply <sha>` (never `pop`). A clean apply drops the entry
+   located by sha (`stash@{n}` is resolved at that moment, never stored) ⇒ `restored`. If the apply
+   conflicts or refuses, only the stash's own paths (index, worktree and untracked trees) that were
+   clean right before the apply are put back to `HEAD`. Other files, including newer edits, are not
+   touched, and the stash is **kept** ⇒ `needs_attention`, `restoreBranch =
+   specrails/restore-local-<sha8>`, the terminal transition stays `merged` / `delivered` with
+   `status_code = local_changes_attention`.
+   **Specrails-managed generated files** (`isSpecrailsManagedPath`: the OpenSpec skills/commands
+   that setup's `openspec init` writes and `openspec init/update` regenerates for every tool dir —
+   `<.tool>/skills/openspec-*/**`, `<.tool>/{commands,prompts,workflows}/opsx…`) are not the
+   person's work. They are still stashed (a fast-forward refuses any dirty tracked file), but when
+   *every* conflict is managed the apply is settled in place — those paths take the integrated
+   (delivered) version, the rest stays applied, the stash is dropped ⇒ `restored`. This was the
+   real-use trigger: 20 `.claude|.codex/skills/openspec-*/SKILL.md` regenerated on both sides.
+   Managed paths are not excluded from the overlap/stash (excluding them would make Git refuse the
+   fast-forward) and partial-file managed blocks (e.g. an instruction-file block) are not covered.
+3b. **Server-side restoration of a conflicting stash**
+   ([local-restore-branch.ts](../../server/modules/delivery/runtime/local-restore-branch.ts)).
+   Mission agents run read-only, so they are never asked to write: the origin mission gets one
+   *report-only* automatic turn (`local-changes:<deliveryId>` turn key — what happened, that
+   Specrails is restoring on the branch, no git/shell instructions). Specrails itself then, in the
+   background (`startLocalRestoreBranch`, tracked by `waitForLocalRestores`):
+   - under the repository lock, `createWorktree` cuts `specrails/restore-local-<sha8>` from the
+     integrated target into `<worktrees root>/restore-local-<sha8>/` and runs
+     `git stash apply <sha>` there. An untracked-vs-now-tracked collision (which makes the apply
+     refuse) is set aside, applied, then written back as a two-sided conflict block; managed files
+     take the integrated version. An existing branch of that name is never borrowed (`failed`).
+   - no conflict left ⇒ committed at once ("Restore local changes from before integrating #N"),
+     `restore.status = ready`, `resolvedBy = clean`. The worktree apply is onto the same tree as
+     the checkout, so this mainly happens for identical untracked collisions and managed files.
+   - otherwise `resolving`: the write-capable resolver runs **outside the lock, confined to that
+     worktree** (cwd/repoDir = the worktree). Default
+     ([local-restore-resolver.ts](../../server/modules/delivery/runtime/local-restore-resolver.ts))
+     is the same AI merge-resolver the parallel merge-back uses (`{{cmd:resolve-merge}}` +
+     MERGE_SAFE, headless rail-job spawn) with a keep-both-intents, nothing-destructive prompt;
+     tests inject `localRestoreResolver`. Specrails then verifies (still on the branch, descends
+     from the target, no marker/unmerged path), stages and commits ⇒ `ready` / `resolvedBy =
+     resolver`, else `failed` with `detail` and the remaining paths. A newer state (discard,
+     restart) always wins over a late resolver result.
+   - `ready` carries `files` (numstat vs the base) for review. Nothing touches the target branch
+     and the stash is kept until the person clicks:
+     `POST /rails/pr-local-changes/bring-back` (target checked out, branch tip unchanged, no
+     overlapping uncommitted edits; a moved target is merged *into* the restore branch first, in
+     its worktree, aborted on conflict; then `git merge --ff-only`; only then the stash is dropped
+     and the worktree/branch removed ⇒ `restored`, `brought_back`) or
+     `POST /rails/pr-local-changes/discard-branch` (force-removes the worktree/branch, the stash is
+     **kept**; refused while `resolving`).
+4. `POST /rails/pr-local-changes/restore` ("Restore my changes") re-attempts the apply under the
+   repository lock and refuses while any decision lease is held (`operation_in_progress`). Still
+   conflicting ⇒ step 3b (idempotent while a branch is `resolving`/`ready`; a `failed` one is
+   removed and retried). A wrong
+   branch or re-dirtied stash paths answer `409 local_restore_blocked` without touching anything.
+   An already-applied stash (crash between apply and drop) is only dropped; a stash the person
+   dropped is `released`. Leaving the held states moves `local_changes_attention` back to
+   `merged` / `cleanup_incomplete`.
+5. Startup recovery (`recoverLocalStashes`, after ticket-effect replay, before admission opens)
+   re-applies every `saved` record while the same branch is checked out. It first adopts a
+   Specrails stash whose record never landed (crash right after `git stash push`) from its
+   message. Conflicts follow step 3/3b. A resolver interrupted by the restart is settled `failed`
+   (its worktree kept for Discard / retry); a `needs_attention` record without a restore branch
+   (recorded before 3b existed) starts one.
+
+Response bodies carry `localChanges { state, stashName, stashSha, restoreBranch, conflictPaths,
+restore? }`; snapshots/cards carry `localStash` (with `restore`, no filesystem path). The mission card
+renders `LocalStashNotice`: note, conflicting files, Restore, copyable stash name, and per restore
+status — resolving (spinner), ready (restored files with +/−, managed-files note, **Bring them back
+to <branch>**, **Discard the restored branch**), failed (detail, Discard, Restore again). The dashboard strip
+closes on `merged`, so it only shows the toast. Multi-repo children record the stash on the child
+row; the group card does not surface it yet.
 
 ## Launch and recovery wiring (`server/modules/delivery/runtime/rail-isolated-launch.ts`)
 
@@ -380,7 +467,8 @@ attached and ready for Verify so that explicit decision can commit terminal tick
   reopening the stale attachment. A valid reopen returns to draft or ready according to GitHub;
   an exact merge racing the action terminalizes, while an exact still-closed result reports failure.
 - **merge-local** — builds the complete merge in an isolated temporary checkout and advances the
-  revalidated base only after all branches succeed, preserving compatible local work. A missing
+  revalidated base only after all branches succeed, preserving compatible local work (overlapping
+  uncommitted work is stashed by sha, re-applied, and kept on conflict; see above). A missing
   immutable delivery object never falls back to a branch that may have moved.
 
 Terminal discard/merge/completion inserts `rail_pr_ticket_effects` in the same SQLite transaction
@@ -400,6 +488,8 @@ Conventional, open-source-style naming for everything the user sees on GitHub. A
 logic in `server/modules/delivery/runtime/pr-naming.ts` (branches + titles) and `server/modules/delivery/runtime/pr-body.ts` (canonical body +
 diff collection), fully unit-tested.
 
+- **Flow → Spec deliveries** add one derivation line to the body (coverage of the derived
+  OpenSpec change, from the settle evidence; see [review packet](review-packet.md)).
 - **`<ref>`** — the ticket's Jira key when Jira-linked, else the local ticket number. **JIRA
   ALWAYS PREVAILS**, resolved per ticket at naming/body time with no HTTP: the authoritative
   `jira_links` row (`getLinkByLocalId`, tombstoned links ignored) wins over the ticket's
@@ -436,6 +526,14 @@ diff collection), fully unit-tested.
   fails — diff problems can only degrade the body, NEVER block PR creation. The v1
   `buildBatchPrBody` and its "_Draft PR produced by specrails — the engineer owns the merge._"
   footer are gone.
+- **Reviewer risk brief in the PR body** (review-risk-brief-surfaces) — when the delivery's
+  `settle_evidence` carries the reviewer brief (Core `reviewBrief: 1`), `create.ts` merges the
+  units' briefs (`buildWhatToLookAt`) and `buildReviewBriefBlock` adds a short `## What to look at`
+  block right under the summary paragraph: high and medium risks (severity, area, text, `file:line`),
+  untested paths and human checks as an unchecked task list, under an "advisory, not a verification
+  result" line. Low risks, behaviour changes and invariants stay in the review packet. No brief
+  (older Core, no reviewer verdict) or nothing to list ⇒ no block, so the body is byte-identical
+  to before. The cost footer stays last. The brief never feeds a decision or the approval gate.
 
 ## The sync contract (two surfaces, zero desync)
 
@@ -507,6 +605,32 @@ is superseded atomically and run on that PR head. A stale
 concurrent request receives 409 before it can allocate or claim anything. Legacy / non-isolated
 launches are unaffected.
 
+## Review WIP limit
+
+The project setting `reviewWipLimit` (null = no limit) caps how many deliveries wait for review.
+`server/modules/delivery/domain/review-wip.ts` counts top-level rows in `building`, `on_review`,
+`pr_draft` or `pr_ready`. `building` counts because it lands on review when it settles, and only
+counting it keeps the cap exact under Launch all. Per-repository children, `no_changes`,
+`implementation_failed`, `pr_failed`, `pr_closed` and terminal rows do not count.
+
+`runtime/review-wip-gate.ts` is bound per project as `ProjectContext.reviewWipGate`. The launch
+route checks it right after the daily budget gate, before relaunch restoration, worktree allocation
+or any spawn. A new delivery at the limit gets
+**409 `{ error: 'review_wip_limit_reached', limit, pending: [{ deliveryId, railIndex, ticketIds, since }], detail, action }`**.
+An admitted launch holds an in-memory reservation for its rail until the response finishes (the
+delivery row then exists), so parallel launches cannot overshoot.
+
+Continuations add no review work and are exempt (`launchAddsReviewWip`): `revisionOfDeliveryId`,
+Relaunch of a recorded delivery, `targetPrNumber`/`followUp`, and any launch on a rail that still owns an
+active delivery. The relaunch guard above only lets the last case through as that delivery's
+continuation; anything else gets `pr_decision_pending`. `since` is the delivery's `created_at`.
+
+Surfaces: the rails header badge "In review N/L" lists the pending deliveries. At the limit, Play is
+disabled with a tooltip on rails that would open a new delivery. Launch all starts at most the
+remaining capacity in board order and its dialog names the held rails. MCP `launch_all` reports
+`review-wip-limit` skips and mobile relays the 409 unchanged. The mission operator prompt explains
+the refusal.
+
 ## Explicit target PR (deliver-rail-into-existing-pr)
 
 The launch body accepts an optional `targetPrNumber` — the user's explicit designation of an
@@ -618,6 +742,11 @@ kill-switch-off legacy path. The `needs_review`-clearing and failure-revert bran
   cost/duration); `onRailDiscard(ticketIds, refId)` (configured `discardStatus`, else logical
   todo).
 
+- Flow specs (`metadata.flow` still `active`/`paused` at settle) are excluded
+  from the settle-time `onRailReview`: their Flow settlement creates the issue
+  (`enqueuePromote`, key `flow:<flowId>:create`) and only then transitions it
+  with `onRailReview([ticketId], deliveryId)`. See [Flow mode](flow-mode.md#settlement).
+
 ## Origin link (as-built)
 
 Persisted end state: `rail_pr_deliveries.origin_surface` + `origin_conversation_id`, written at