specrails-desktop 2.29.4 → 2.30.0

package/client/dist/index.html

@@ -204,7 +204,7 @@
         .specrails-splash__mark .pill { opacity: 1; }
       }
     </style>
-    <script type="module" crossorigin src="/assets/index-CCq_kIrF.js"></script>
+    <script type="module" crossorigin src="/assets/index-xkzK3E5i.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-CNC7AqOf.js">
     <link rel="modulepreload" crossorigin href="/assets/jsx-runtime-zu2_FqZY.js">
     <link rel="modulepreload" crossorigin href="/assets/react-dom-DiWzBDP9.js">
@@ -213,13 +213,14 @@
     <link rel="modulepreload" crossorigin href="/assets/createLucideIcon-Bjbbp_KS.js">
     <link rel="modulepreload" crossorigin href="/assets/activity-DiyjsgQV.js">
     <link rel="modulepreload" crossorigin href="/assets/addspec-Rw8uVBC1.js">
-    <link rel="modulepreload" crossorigin href="/assets/agent-BqEfA5u5.js">
+    <link rel="modulepreload" crossorigin href="/assets/agent-BuUpgqVx.js">
     <link rel="modulepreload" crossorigin href="/assets/agents-DhG7mg6-.js">
     <link rel="modulepreload" crossorigin href="/assets/agentstudio-BIUe1Im2.js">
     <link rel="modulepreload" crossorigin href="/assets/aiedit-iIjz2_Qk.js">
     <link rel="modulepreload" crossorigin href="/assets/analytics-DZ8Aoq3I.js">
     <link rel="modulepreload" crossorigin href="/assets/attachments-B53PG733.js">
     <link rel="modulepreload" crossorigin href="/assets/browser-CXUcnTMI.js">
+    <link rel="modulepreload" crossorigin href="/assets/builder-Cc_Lf79C.js">
     <link rel="modulepreload" crossorigin href="/assets/chat-BGD7MXAy.js">
     <link rel="modulepreload" crossorigin href="/assets/code-BDXEM4ml.js">
     <link rel="modulepreload" crossorigin href="/assets/commands-DyUZQ1FI.js">
@@ -233,23 +234,23 @@
     <link rel="modulepreload" crossorigin href="/assets/mcp-uDkXYu4L.js">
     <link rel="modulepreload" crossorigin href="/assets/nav-myFaXRHD.js">
     <link rel="modulepreload" crossorigin href="/assets/settings-B0ypw9uw.js">
-    <link rel="modulepreload" crossorigin href="/assets/setup-CmK87LuS.js">
+    <link rel="modulepreload" crossorigin href="/assets/setup-ajB4rYm-.js">
     <link rel="modulepreload" crossorigin href="/assets/specs-DII0C8gw.js">
     <link rel="modulepreload" crossorigin href="/assets/terminal-BFRZnMPP.js">
     <link rel="modulepreload" crossorigin href="/assets/tickets-D_yDquEw.js">
-    <link rel="modulepreload" crossorigin href="/assets/i18n-cK5pPbj8.js">
-    <link rel="modulepreload" crossorigin href="/assets/Trans-Cm9rhdnG.js">
+    <link rel="modulepreload" crossorigin href="/assets/i18n-Bf9Ckd10.js">
+    <link rel="modulepreload" crossorigin href="/assets/Trans-CPISVji8.js">
     <link rel="modulepreload" crossorigin href="/assets/dist-bVqfYmby.js">
     <link rel="modulepreload" crossorigin href="/assets/arrow-left-CpIR4j7G.js">
     <link rel="modulepreload" crossorigin href="/assets/auth-D_5bQv5W.js">
     <link rel="modulepreload" crossorigin href="/assets/api-B2M7CtDw.js">
-    <link rel="modulepreload" crossorigin href="/assets/useBrowserCaptureSession-DR1_jL56.js">
+    <link rel="modulepreload" crossorigin href="/assets/useBrowserCaptureSession-CkBJShUw.js">
     <link rel="modulepreload" crossorigin href="/assets/arrow-up-right-9DoMn7fD.js">
     <link rel="modulepreload" crossorigin href="/assets/sparkles-DrY8hb0X.js">
     <link rel="modulepreload" crossorigin href="/assets/x-CBMI9ejn.js">
     <link rel="modulepreload" crossorigin href="/assets/useSharedWebSocket-DaPh7QBL.js">
-    <link rel="modulepreload" crossorigin href="/assets/useDesktop-D4DxBGPU.js">
-    <link rel="modulepreload" crossorigin href="/assets/MinimizedChatsContext-DJAkRYps.js">
+    <link rel="modulepreload" crossorigin href="/assets/useDesktop-B4pSBIDd.js">
+    <link rel="modulepreload" crossorigin href="/assets/MinimizedChatsContext-Cs34FPTz.js">
     <link rel="modulepreload" crossorigin href="/assets/external-link-BcU5EWZp.js">
     <link rel="modulepreload" crossorigin href="/assets/chevron-right-CViMxucY.js">
     <link rel="modulepreload" crossorigin href="/assets/circle-x-CMYsN4ZH.js">
@@ -272,11 +273,11 @@
     <link rel="modulepreload" crossorigin href="/assets/dialog-CzIekCw0.js">
     <link rel="modulepreload" crossorigin href="/assets/jira-api-BgFIr8eD.js">
     <link rel="modulepreload" crossorigin href="/assets/lib-CGdyxIWg.js">
-    <link rel="modulepreload" crossorigin href="/assets/getTimezoneOffsetInMilliseconds-DwzZXHtg.js">
-    <link rel="modulepreload" crossorigin href="/assets/formatDistanceToNow-BAXZRbEO.js">
-    <link rel="modulepreload" crossorigin href="/assets/spending-BLb5pj6G.js">
-    <link rel="modulepreload" crossorigin href="/assets/TicketDetailModal-CFh7GOv5.js">
-    <link rel="stylesheet" crossorigin href="/assets/index-BT6xDQjB.css">
+    <link rel="modulepreload" crossorigin href="/assets/getTimezoneOffsetInMilliseconds-qrcBaLW1.js">
+    <link rel="modulepreload" crossorigin href="/assets/formatDistanceToNow-ByKli7Q_.js">
+    <link rel="modulepreload" crossorigin href="/assets/spending-DMnCXy84.js">
+    <link rel="modulepreload" crossorigin href="/assets/TicketDetailModal-7EloKP1C.js">
+    <link rel="stylesheet" crossorigin href="/assets/index-Dh9i4CnN.css">
   </head>
   <body>
     <div id="specrails-splash" aria-hidden="false" role="status" aria-label="Loading Specrails">

package/docs/codex.md

@@ -116,7 +116,8 @@ the [Gemini guide](gemini.md).)
 | **Min CLI version** | none pinned | `0.128.0` | `0.11.0` |
 | **Project dir** | `.claude/` | `.codex/` | `.gemini/` |
 | **Instructions file** | `CLAUDE.md` | `AGENTS.md` | `GEMINI.md` |
-| **Default model** | `sonnet` | `gpt-5.5` | `gemini-3.5-flash` |
+| **Default model** | `sonnet` | `gpt-5.5` (catalog includes the GPT-5.6 family: `gpt-5.6-sol` / `gpt-5.6-terra` / `gpt-5.6-luna`) | `gemini-3.5-flash` |
+| **Reasoning efforts** | `low`–`xhigh` | `minimal`–`ultra` (`xhigh`/`max`/`ultra` ship with GPT-5.6; `ultra` is Sol-only upstream) | none |
 | **Agent format** | `.claude/agents/<id>.md` with `model:` frontmatter | `.codex/skills/<id>/SKILL.md` Skill format | `.gemini/` command + agent target |
 | **Agent profiles** | Full support (rail `RailProfileSelector`) | **None** — rails force the profile to `null` | **None** — rails force the profile to `null` |
 | **Pipeline rails** | ✅ all rail types | ✅ (except Freestyle) | ✅ (except Freestyle) |

package/docs/customizing.md

@@ -161,7 +161,7 @@ Most settings live in the UI. A few app-level switches are env-only because they
 | `SPECRAILS_GEMINI_BETA=0` | Emergency rollback — disable the Gemini provider (default unset = enabled; only the exact string `0` disables; **no legacy fallback name**) |
 | `SPECRAILS_SMASH=0` | Kill switch for SMASH spec decomposition (`0` / `false` / `off`; endpoints return 409) |
 | `SPECRAILS_EXPLORE_CONTRACT_REFINE=0` | App-wide kill switch for Contract Refine (auto-fire + retry endpoint; accepts `0` / `false` / `off`) |
-| `SPECRAILS_EXPLORE_LEGACY_CWD=1` | Force Explore spawns to use the project root instead of the app-managed `explore-cwd/` |
+| `SPECRAILS_EXPLORE_LEGACY_CWD=1` | Force every Explore spawn to use the project root instead of the app-managed `explore-cwd/` or a relocated workspace |
 | `SPECRAILS_FILE_SUMMARY_MODEL` | Override the model used for Code-section file summaries. Per-provider overrides take precedence: `SPECRAILS_FILE_SUMMARY_MODEL_CLAUDE` (Claude) and `SPECRAILS_FILE_SUMMARY_MODEL_CODEX` (Codex); the generic var is the fallback |
 | `SPECRAILS_ALLOW_LOCAL_WEBHOOKS=1` | Allow outbound webhooks to target loopback / private-network addresses |
 

package/docs/internals/gemini-mcp-registration.md

@@ -38,7 +38,7 @@ loads** for gemini:
 |---|---|---|
 | Plugins on rails (`server/plugin-manager.ts`, e.g. Serena) | surgical merge into `<project>/.mcp.json` for `project-json` providers | plugin installs "successfully", MCP server never loads in gemini rail spawns |
 | Workspace MCP (`server/agent-mcp-config.ts` `mergeSpecrailsIntoWorkspaceMcp`, via `workspace-manager.ts`) | writes `<workspace>/.mcp.json` | not read by gemini |
-| Explore `context_scope.mcp` (`server/chat-manager.ts`) | spawns from `<project.path>` so `.mcp.json` loads | loads nothing on gemini |
+| Explore `context_scope.mcp` (`server/chat-manager.ts`) | spawns from the relocation-aware artifact cwd (workspace when relocated, `<project.path>` when legacy) so `.mcp.json` loads | loads nothing on gemini |
 
 Fixing these means writing into the repo's / workspace's `.gemini/settings.json`, which
 intersects the **pristine-repo / artifact-relocation policy** (the app must not mutate the

package/docs/internals/global-artifacts-alignment-contract.md

@@ -239,7 +239,7 @@ $HOME/.specrails/
 ├── jira-secret.key               # keyfile AES-256-GCM (0600), desktop-only
 ├── doctor.log                    # log append-only, core-only (única lectura $HOME de core hoy)
 └── projects/<slug>/
-    ├── workspace/                # = artifactRoot. cwd de spawn de todas las AI-CLI
+    ├── workspace/                # = artifactRoot. cwd de jobs y Explore mcp=true relocalizados
     │   ├── .specrails/
     │   │   ├── local-tickets.json (+ .lock)   ← SPECRAILS_TICKETS_PATH        [core escribe/lee · desktop escribe]
     │   │   ├── backlog-config.json            ← SPECRAILS_BACKLOG_CONFIG_PATH  [desktop escribe · core lee]
@@ -365,9 +365,9 @@ El lado desktop ya tiene el precedente load-bearing en producción (`explore-cwd
 
 ### 6.1 cwd de spawn + env por provider
 
-`ExploreCwdManager` se generaliza a un `WorkspaceManager` que materializa `~/.specrails/projects/<slug>/workspace/` con `./project -> <project.path>` (symlink/junction, fallback `project-path.txt` — la lógica existente `ensureProjectLink`). **Todas las AI-CLI mueven cwd al workspace.**
+`ExploreCwdManager` se generaliza a un `WorkspaceManager` que materializa `~/.specrails/projects/<slug>/workspace/` con `./project -> <project.path>` (symlink/junction, fallback `project-path.txt` — la lógica existente `ensureProjectLink`). **Las AI-CLI relocalizadas usan el workspace salvo los procesos deliberadamente repo-bound y Explore con `mcp=false`, que conserva su `explore-cwd`.**
 
-**Managers que MUEVEN cwd → workspace:** `QueueManager._startJob` (rails — el grande), `ChatManager` (Explore + sidebar), `AgentRefineManager` (ai-edit), `ContractRefineRunner`, `project-router /tickets/generate-spec` (quick-spec), `FileSummaryManager`, `SetupManager.startInstall` (corre `npx specrails-core init --root-dir <project.path> --workspace-dir <workspace>`).
+**Managers que MUEVEN cwd → workspace:** `QueueManager._startJob` (rails — el grande), `ChatManager` (sidebar + Explore con `mcp=true`), `AgentRefineManager` (ai-edit), `ContractRefineRunner` cuando refleja un Explore `mcp=true`, `project-router /tickets/generate-spec` (quick-spec), `FileSummaryManager`, `SetupManager.startInstall` (corre `npx specrails-core init --root-dir <project.path> --workspace-dir <workspace>`). Explore y Contract Refine con `mcp=false` permanecen en el app-managed `explore-cwd`.
 
 **Managers que CONSERVAN cwd = `project.path`:** `TerminalManager` (shell repo-bound), `file-provenance.ts` (git repo-bound), `code-explorer-router` (lee fuente), lecturas de fuente de `FileSummaryManager`, `metrics.ts` (coverage).
 
@@ -380,7 +380,7 @@ El lado desktop ya tiene el precedente load-bearing en producción (`explore-cwd
   - **Smoke check (manual):** en un proyecto relocalizado con provider=codex, lanzar un loop "Implement" cuyo paso de fix deba editar una fuente del repo; confirmar en el transcript que (a) `apply_patch`/edit a `<repoDir>/...` **NO** devuelve `Operation not permitted`, y (b) `npm run build`/`tsc -b` puede escribir `node_modules/.tmp/*.tsbuildinfo`. Reproducción del fallo: revertir el `extraArgs` de codex → la edición del repo en la iteración ≥2 vuelve a fallar con `Operation not permitted`. Cubierto por `server/loop-executors.test.ts` (assert del arg `writable_roots`).
 - **gemini**: inyecta `GEMINI_CLI_TRUST_WORKSPACE=true` (ancla el root confiable al workspace). **Re-keya** `~/.gemini/acknowledgments/agents.json` al workspace.
 - Los tres: el workspace **estrictamente fuera del repo** y el discovery no debe seguir `./project` (mitiga la fuga por ancestor-walk de codex/gemini).
-- **Caso especial Explore `mcp=true`**: hoy `chat-manager.ts:326` conmuta cwd a `project.path` para cargar el `.mcp.json` del repo — tras relocalizar, `.mcp.json` está en el workspace, así que este special-case se **ELIMINA**, no se re-apunta.
+- **Caso especial Explore `mcp=true` (implementado):** `ChatManager` resuelve el cwd mediante la misma puerta de relocalización: workspace cuando el proyecto está relocalizado, `project.path` en legacy. Las rutas persistent-stdin, crash-respawn y Contract Refine conservan esa misma pareja cwd/env. Una sesión anterior creada bajo el cwd del repo que devuelve exactamente `No conversation found with session ID` se invalida y reintenta fresh una sola vez desde el workspace (transcript persistido acotado para Explore; ticket sembrado y tools deshabilitadas para Contract Refine), nunca volviendo al repo. `SPECRAILS_EXPLORE_LEGACY_CWD=1` sigue forzando `project.path`.
 
 ### 6.2 Sitios de re-apuntado de path (`project.path` → workspace)
 

package/docs/internals/project-builder.md

@@ -0,0 +1,306 @@
+# Project Builder — as-built internals
+
+> OpenSpec change `add-project-builder`. Greenfield project creation from an
+> idea: a day-0 blueprint conversation, an orchestrated bootstrap commit, and a
+> milestone lifecycle (Launch M1 batch rail, sidebar re-entry, Generate M2+).
+
+## Entry + builder mode (reskin)
+
+"+ 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
+`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:
+`VITE_FEATURE_PROJECT_BUILDER` (client) / `SPECRAILS_PROJECT_BUILDER` (server),
+both default ON, `"false"` opts out (server flag 404s every `/api/blueprint/*`
+route).
+
+**Builder mode (client architecture):**
+
+- `builderMode` slice on `AgentChatContext`: `{ active, enter, exit, session }`.
+  `enter()` also opens the floating panel outside Agent Mode; `exit()` aborts
+  the in-flight builder turn (`POST /abort`) and resets every session slice.
+  The agent's own chrome (project/mission selectors, conversation, queue,
+  pinned cards) is hidden while active but NEVER unmounted.
+- Session logic in `client/src/hooks/useBuilderSession.ts` (extracted from the
+  retired shell): bootstrap, `blueprint.*` WS handling with NULL-SAFE identity
+  checks (a pre-bootstrap/pre-commit null ref must never match a null/absent
+  message id), phases, snapshot, send/commit/launch actions, `dirty` flag.
+- `BuilderConversation` (`client/src/components/project-builder/`): the four
+  phases in the MISSION format — chat renders a centered message column with
+  the `BuilderComposer` docked at the bottom (centered card while empty,
+  mission-style); in Agent Mode the hero and docked cards share a `layoutId`,
+  so the first send morphs the agent smoothly down. Then commit
+  (`BlueprintCommitForm`), progress step list, done (Launch M1 / Open project).
+  Esc: commit→chat, chat→exit (confirm-gated when dirty).
+- `BuilderComposer`: mirrors the mission composer's visual language — the SAME
+  provider/model/effort selectors (provider/model bind to the blueprint
+  conversation; reasoning effort is validated against the selected provider
+  and rides each send), surprise-me chip, native `resize-y` textarea, and the
+  same `SendHorizontal` action. Models and effort levels come from
+  `GET /api/blueprint/models?provider=`.
+- `BuilderHalo`: orbiting ring — CSS `builder-halo-spin` keyframes over an
+  XOR-masked conic-gradient border band (follows ANY radius: circular on the
+  bubble/panel-header icon, card radius on the composer; no per-frame JS),
+  `motion` enter/exit, `prefers-reduced-motion` ⇒ static glow. It is strictly
+  an ENTRY flourish: shown on the fresh empty composer and the matching
+  bubble/panel-header identity, then removed as soon as the first work message
+  begins. Builder mode itself continues without a halo; there is no wind-down.
+- Per UI mode: **board** — `AgentChatPanel` widens (860px) and gains an
+  attached blueprint side pane; **Agent Mode** — `AgentModeSurface` renders
+  the builder conversation and `AgentWorkspaceSidebar` swaps (AnimatePresence)
+  to `BlueprintPanel` + the Create-specs CTA, forced-expanded for the duration.
+- The builder conversation stays on `blueprint_conversations` / `blueprint.*`
+  — never mixed into `agent_conversations` or the mission selector.
+- `BlueprintPanel` M1 spec cards are clickable → `BlueprintSpecModal`
+  (hand-rolled body portal at z-[65], same tier as `LoopPreviewModal`; Esc +
+  backdrop close). At day 0 the specs are NOT tickets yet (only in the
+  snapshot), so this is a lightweight read-only preview — NOT the heavy
+  `TicketDetailModal`. Cards expose `shortSummary`, priority, and acceptance-
+  criteria count; the modal exposes the summary, priority, canonical five-
+  section description, and every separate acceptance criterion. The same panel
+  (and therefore the modal) is reused in the M2+ `MilestoneGenerateShell`, so
+  the user reviews the content that will become the authoritative tickets
+  (apart from the deterministic criteria fold). The detailed M2+ preview is
+  transient; the blueprint has no per-milestone detailed-spec collection.
+
+## Day-0 chat (no project exists)
+
+- **Manager**: `server/blueprint-chat-manager.ts` `BlueprintChatManager` — an
+  app-level sibling of `AgentChatManager` reusing `runAiCliInvocation`. Spawns
+  from `~/.specrails/builder-cwd/` (`server/builder-cwd-manager.ts`: always
+  re-written instruction files from `server/blueprint-operator-prompt.ts`, NO
+  `./project` symlink, NO MCP). Auto-heal: a resume that yields no text retries
+  fresh once. Abort keeps partial text and records `aborted`.
+- **Persistence**: `blueprint_conversations` / `blueprint_messages` in
+  `desktop.sqlite` (migration 22; CRUD in `server/blueprint-store.ts`).
+- **WS**: app-global `blueprint.stream` / `blueprint.done` / `blueprint.error`
+  (no `projectId`; NOT in the mobile-ws translation layer). `blueprint.done`
+  carries the STRIPPED `fullText` plus the last valid `blueprint` snapshot.
+- **Accounting**: one `agent_invocations` row per settled turn with
+  `project_id NULL` (the Home-turn precedent). No backfill after creation.
+- **REST**: `/api/blueprint/*` (`server/blueprint-router.ts`) — conversations
+  CRUD, `/send` (202, 409 while streaming), `/abort`, `/models`, `/commit`.
+  `/models` returns the provider's `efforts` catalog; `/send` accepts only a
+  catalog-valid `reasoning_effort`, and providers without the capability omit
+  the field when spawning.
+- **Generation boundary**: interview turns and Surprise Me may complete the
+  product/flow/platform/stack/assumption/milestone proposal, but MUST keep
+  `m1Specs: []` and `specsComplete: false`. Detailed M1 generation starts only
+  after explicit user approval or a direct request to generate the backlog.
+  That next assistant turn emits the entire self-validated 5–10-spec M1 set in
+  ONE response containing ONE complete fenced snapshot. It never publishes a
+  partial subset as the latest draft; `specsComplete: true` appears only on the
+  complete set. If generation cannot finish, the prior non-complete proposal
+  remains the last valid state and cannot be committed.
+
+## blueprint-draft protocol
+
+Fenced ` ```blueprint-draft ` JSON blocks. FULL snapshots, LAST syntactically
+valid block wins, streaming tail cut (unterminated trailing fence never
+parsed/shown — `cutUnterminatedBlock`). Unknown keys dropped; missing or
+non-integer `blueprintVersion` rejects the block. Parser pair:
+`server/blueprint-draft-parser.ts` ⇄ `client/src/lib/blueprint-draft.ts` (keep
+coercion rules in sync). Schema types in `server/blueprint-types.ts`:
+`product{name,pitch,audience}`, `coreFlow`, `platform`,
+`stack{language,framework,db,notes?}`, `assumptions[]`,
+`milestones[]{id,title,goal,status: planned|committed|done, plannedSpecs[],
+ticketIds?}` (ticketIds ADVISORY only), `specsComplete`, and detailed
+`m1Specs[]{kind,title,shortSummary,description,acceptanceCriteria[],priority,
+labels[],dependsOnIndex?}`. `kind` is `scaffold|feature|verification`; priority
+is `low|medium|high|critical`. After approval, detailed M1 generation arrives
+as one complete 5–10-spec snapshot with an explicit scaffold first. M2+
+milestones carry `plannedSpecs` titles only until that milestone is explicitly
+generated, at which point the target milestone's entire detailed set likewise
+arrives in one assistant response/snapshot. The version stays 1: legacy
+snapshots default missing `specsComplete=false`, `kind='feature'`,
+`shortSummary=''`, criteria to `[]`, and missing/invalid priority to `medium`
+on read. Those defaults preserve readability only; newly committed batches
+must pass the strict quality gate.
+
+Parsing deliberately retains two representations of the LAST valid block:
+`blueprint` is the compatibility-normalized `Blueprint` used by preview/read
+surfaces, while `rawBlueprint` is the exact parsed JSON before enum defaults,
+dependency drops, or missing-field defaults. `blueprint.done` carries both;
+the client mirrors the pair, derives readiness from the raw value, and sends
+that raw value to M1/M2+ commit. Therefore an invalid `kind`, `priority`,
+`dependsOnIndex`, or required field cannot disappear/default during rendering
+and then pass the mutation gate. Persisted legacy files are a different read
+boundary: `readBlueprint()` calls `coerceBlueprint()` server-side so old v1
+files remain readable (and returns null for missing/corrupt input).
+
+## Canonical rich-spec contract (M1 and generated M2+)
+
+There is no Builder-specific “lite spec” format. Every detailed Builder spec
+uses the normal Specrails contract:
+
+1. `kind`: `scaffold`, `feature`, or `verification`
+2. an English, action-oriented, unique `title`
+3. a one-sentence `shortSummary` no longer than 240 characters
+4. `description` with exactly these `##` headings, once and in this order:
+   `Problem Statement`, `Proposed Solution`, `Out of Scope`,
+   `Technical Considerations`, `Estimated Complexity`
+5. a separate `acceptanceCriteria[]` containing 4–10 non-empty, independently
+   testable outcomes; `description` MUST NOT contain `## Acceptance Criteria`
+6. a catalog-valid `priority`, non-empty domain labels, and an optional
+   `dependsOnIndex` that points strictly backward (the M1 scaffold omits it)
+
+Every named description section has a non-empty body. `Out of Scope` and
+`Technical Considerations` each contain at least 2 bullets; Estimated
+Complexity includes a reasoned estimate. Day-0 technical considerations name
+the selected stack, planned components/contracts, risks, and inter-spec
+dependencies but never fabricate repository paths. Generated M2+ specs first
+inspect the real project and may name only verified existing paths and
+identifiers; their criteria cover behavior, failure/edge cases, and tests.
+
+`server/blueprint-spec-quality.ts` is the shared deterministic authority. It
+validates `specsComplete=true`, the complete-set size, all fields/sections
+above (including both 2-bullet minima), unique titles, the M1 first-item
+`kind='scaffold'` rule, and backward-only dependencies. Both commit paths run
+it before any filesystem, registry, blueprint, milestone, or ticket-store
+mutation and return a stable spec/field-oriented detail when it rejects. A
+prompt is a generation aid, never the integrity boundary. Validation receives
+the exact raw generated payload; normalized compatibility views are not
+commit evidence.
+
+## Orchestrated commit (register-project-LAST)
+
+`POST /api/blueprint/commit` → sync validation (named errors: `invalid_name`,
+`invalid_location`, `providers_required`, `unknown_provider`,
+`invalid_blueprint`, `m1_specs_required`, `m1_specs_over_cap`,
+`bundled_framework_missing`, `location_not_empty`,
+`location_already_registered`; rich-spec failures include actionable spec/field
+detail) → 202 `{commitId}` → per-step
+`blueprint.commit_progress` → terminal `blueprint.commit_done{projectId}` /
+`commit_failed{step,error}`. Orchestrator: `server/blueprint-commit.ts`
+`createBlueprintCommitRunner` (DI IO bag — every step fail-injectable in
+tests). Step order:
+
+1. `create-dir` — mkdir target
+2. `git-init` — `git init -b main` + deterministic README (no AI call,
+   `renderReadme`) + initial commit (pinned committer identity)
+3. `assemble` — registry mirror + framework materialize + one core
+   `init --from-config` per provider (`server/offline-assemble.ts`
+   `assembleProjectOffline`, extracted from `SetupManager`): PREFERS the
+   bundled core (offline `node <bundled-cli> init`, `spawnBundledCoreInit`),
+   falls back to `npx specrails-core` (`spawnNpxCoreInit`) when no bundle —
+   so `npm run dev` and runtimes-less builds work. `canAssembleProject()` is
+   the validation gate: true when the bundle is present OR
+   `SPECRAILS_IS_DESKTOP !== '1'`; only a packaged desktop build with a
+   missing/corrupted bundle returns false → `bundled_framework_missing`
+   ("reinstall the app"). Verifies the workspace exists afterwards.
+4. `blueprint` — `writeBlueprintPair` into `<workspace>/.specrails/`
+   (`blueprint.json` source of truth + deterministic `blueprint.md`,
+   `server/blueprint-render.ts`; repo stays pristine)
+5. `tickets` — `mutateStore` on the workspace `local-tickets.json`: `todo`,
+   label `M1`, `source='project-builder'`, `created_by='project-builder'`, spec
+   order preserved, generated priority/short summary/domain labels retained,
+   structured criteria folded once via the normal
+   `formatDescriptionWithCriteria` helper, `dependsOnIndex` → `prerequisites`,
+   advisory ids written back to milestone m1 (+ `status='committed'`) and the
+   pair re-rendered
+6. `register` — `ProjectRegistry.addProject` with the pre-generated id/slug
+   (LAST mutation; broadcast `desktop.project_added`)
+7. `github` — best-effort, never aborts. A server-side pre-flight
+   (`gh auth token`) runs first as defence against a stale client cache: a
+   spawn error (gh not on PATH) → warning `gh_not_installed`; a non-zero exit
+   → warning `gh_not_authenticated`, both WITHOUT spawning the create. Then
+   `gh repo create <slug> --private --source . --push`; a failure is
+   classified by `classifyGhCreateError` (`gh_scope` for 403/scope,
+   `gh_repo_exists`, `gh_network`, else `gh_failed`). Every warning rides the
+   `blueprint.commit_progress` payload's additive `code` field so the client
+   renders an i18n message (`builder:progress.githubErrors.*` ×8, raw stderr
+   tail kept as tooltip) and fires ONE non-blocking `toast.warning` per commit
+   attempt (`useBuilderSession` `ghWarnedRef`).
+
+**Checkbox gating** (`BlueprintCommitForm`): the "Create private GitHub
+repository" option renders ONLY when gh is installed+executable
+(`usePrerequisites()` gh entry); installed-but-unauthenticated shows it
+disabled with the actionable `commit.githubAuthHint` («gh auth login»). gh
+absent ⇒ the checkbox does not exist. Submit force-clears the flag unless gh
+is fully ready (installed + authenticated).
+
+**Crash posture**: a crash before step 6 leaves an orphan dir + registry entry
+but NO project row (invisible; re-run rejects `location_not_empty`). After
+step 6 it is an ordinary project missing only the remote.
+
+## Milestone lifecycle
+
+- **Launch Milestone 1** (`client/src/lib/milestone-launch.ts`
+  `launchMilestone`): gather `M1`-labeled `todo` tickets → `POST /rails`
+  (server allocates the lowest free index) → `PUT /rails/:i/tickets` → `POST
+  /rails/:i/launch {mode:'batch-implement'}` (the server maps the bare mode to
+  the batch factory loop: worktree isolation + ask-first PR). Offered on the
+  Builder done screen and the sidebar entry; existing 409 guards surface as
+  toasts.
+- **Sidebar re-entry** (`BuilderSidebarEntry`, mounted in
+  `ProjectRightSidebar` + `AgentWorkspaceSidebar`): visible iff
+  `GET /api/projects/:id/blueprint` (project-router) returns a blueprint
+  (404 = hidden). Progress derives LIVE from board tickets by `M<n>` label —
+  never from stored ticket ids. Actions: Launch M1 (while launchable) +
+  Generate M<next> (first `planned` milestone > 1).
+- **Board classification**: new Builder tickets use
+  `source='project-builder'` + `created_by='project-builder'`. For projects
+  created before that source existed, `DashboardPage` also treats
+  `source='manual'` + `created_by='project-builder'` as specs; existing tickets
+  appear after reload without rewriting the user's ticket store.
+- **Generate M2+** (`MilestoneGenerateShell`): PROJECT-level conversation
+  `kind='milestone'` through the existing ChatManager. The milestone id rides
+  `context_scope` as `{milestone:'m2'}` (`POST /chat/conversations` body
+  `{kind:'milestone', milestone}`); `ChatManager._buildMilestoneSystemPrompt`
+  seeds the prompt with the workspace `blueprint.json`, the target
+  `plannedSpecs`, the complete canonical rich-spec/quality contract, and the
+  code-grounding rules. It instructs the agent to return every detailed spec
+  for the target milestone in one assistant response and one complete snapshot,
+  never an incrementally committable subset. Claude receives it through the
+  system prompt; adapters without that argument receive the same dynamic
+  instructions and blueprint context in the effective user turn, so Claude,
+  Codex, and Gemini receive equivalent authoring/context instructions.
+  Generation itself is read-only: the prompt forbids repository/workspace/
+  ticket/config/git mutation, write-capable shell/tool actions, builds, and
+  tests. `toolPolicy='read-only'` maps Claude to `--permission-mode plan`
+  + `--safe-mode` + only `Read,Grep,Glob`; Codex fresh turns use
+  `--sandbox read-only` and resumes carry `sandbox_mode="read-only"`; Gemini
+  uses `--approval-mode plan` and never `--yolo`. Gemini CLI does not expose a
+  selectable filesystem sandbox comparable to Codex, so its protection is the
+  native plan/policy layer plus the prompt—not an OS/filesystem sandbox. If a
+  CLI version rejects an incompatible safety flag, the turn fails closed; it
+  is never retried with a mutating/yolo policy. For relocated projects the
+  prompt identifies the absolute real repo, its `./project` mount, and
+  `SPECRAILS_REPO_DIR`; it explicitly warns Read/Grep/Glob not to receive
+  literal shell-variable expressions, preventing grounding against the empty
+  workspace. Grounded specs name only verified paths/identifiers and require
+  behavioral, failure/edge-case, and testing criteria. Accounting records
+  `surface='explore-spec'` (no new surface value). Committing calls
+  `POST /api/projects/:id/blueprint/commit-milestone {milestoneId, specs[]}` —
+  atomically validates the complete batch before any write, then inserts
+  `M<n>`-labeled `todo` tickets with Builder source/provenance and the same
+  priority/summary/criteria/labels/prerequisite ticket-materialization rules as M1
+  (broadcasting `ticket_created` per row), flips the milestone to `committed`,
+  and re-renders the pair. These tickets are the authoritative detailed M2+
+  representation: their descriptions contain the folded criteria and they
+  retain priority, short summary, domain + `M<n>` labels, and prerequisites.
+  `blueprint.json` deliberately stores only the existing milestone skeleton
+  with `status='committed'` and advisory `ticketIds`; it has no detailed-M2-
+  per-milestone schema. On 201 the shell calls `onCommitted`, increments the
+  sidebar blueprint refresh key (no-store refetch), closes, and the next CTA
+  resolves to the first later milestone still `planned`. Jira-connected
+  projects ride the existing machinery on the store mutation.
+
+## Tests
+
+`server/blueprint-{draft-parser,render,store,chat-manager,commit,router}.test.ts`,
+`server/offline-assemble.test.ts`, `server/project-router.test.ts`; client
+`src/lib/__tests__/{blueprint-draft,milestone-launch}.test.ts`,
+`src/hooks/__tests__/useBuilderSession.test.ts`,
+`src/components/__tests__/{ProjectBuilder,BuilderSidebarEntry}.test.tsx`, and
+`src/pages/__tests__/DashboardPage.test.tsx`.
+Locale parity covers the `builder` namespace ×8.
+
+## Deferred (v2)
+
+Resume/minimize for Builder conversations (no dock chip — no `projectId` to
+tag), an orphan-dir startup sweeper, non-GitHub remotes, editing an existing
+blueprint via the day-0 Builder, a live side-panel draft during M2 generation.

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

@@ -193,25 +193,35 @@ seeded instruction file), which lives in `~/.specrails/projects/<slug>/workspace
 absent from the worktree: the claude CLI reported `Unknown command: /specrails:implement`
 and the loop "succeeded" through verify/fix without implementing (live evidence: run
 01f41203). Legacy projects have the sibling gap for their UNTRACKED on-disk `.claude`
-entries. Each allocated worktree therefore gets `applyWorktreeOverlay(...)` at launch:
-
-- **Source root** = the project's effective artifact root, resolved once per launch via
-  `resolveProjectExecution`: the workspace when relocated, else the repo itself.
-- **Merge-only symlinks** under `<worktree>/<providerDir>/`: dir links where a dir is
-  wholly absent, per-file/per-child where the checkout is partially present; checkout
-  content is NEVER overwritten. `agent-memory` is linked (all runs share memory — the
-  pre-isolation shared-cwd semantics, deliberate). The providerDir root and the source's
-  `worktrees/` entry are never linked (nested pipeline worktrees stay local). `.mcp.json`
-  and the instruction file (CLAUDE.md/AGENTS.md/GEMINI.md per provider) are COPIED when
-  the checkout lacks them. Windows: junction → dereferencing-copy fallback.
-- **Never on the PR**: every allocator-created overlay path is excluded from staging with a literal
-  top-level pathspec. The writable worktree manifest is not cleanup authority; settlement persists
-  fingerprints captured from the trusted source/created entries. Cleanup atomically renames each
-  authenticated root into a unique sibling quarantine, revalidates it after the move, discloses
-  raced content there, and never deletes or restores quarantined paths automatically over a
-  possibly recreated source. A modified or
-  concurrently extended overlay is preserved as user data, while a no-op
-  overlay keeps the byte-identical ordinary staging behavior.
+entries. Relocated projects also need repo-resident carve-outs that are intentionally not
+part of the workspace framework, notably OpenSpec's untracked `/opsx:*` commands and
+`openspec-*` skills. Each allocated worktree therefore gets `applyWorktreeOverlay(...)`
+at launch:
+
+- **Ordered source roots** are resolved once per launch. The primary root is the effective
+  artifact root (`resolveProjectExecution`: workspace when relocated, repo when legacy).
+  A relocated launch additionally passes the repo as a lower-priority fallback so its
+  untracked provider entries reach the worktree. Earlier roots win per entry; legacy stays
+  on its byte-identical single-root path.
+- **Merge-only links/copies** under `<worktree>/<providerDir>/`: one contributing directory
+  stays a whole-dir link; when several roots contribute children, the destination is a REAL
+  directory of per-child links. Checkout content is NEVER overwritten, including source
+  file/directory type conflicts. On resume, only an authenticated prior-manifest whole-dir
+  link/copy may be rebuilt into recorded leaves; a foreign symlink is untouched even when it
+  targets a configured source. Converted parents are revoked from the manifest. `agent-memory`
+  remains linked (shared pre-isolation semantics). The providerDir root and every source's
+  `worktrees/` entry are never linked. `.mcp.json` and the provider instruction file are COPIED
+  from the first root containing them when checkout lacks them. Windows: junction →
+  dereferencing-copy fallback.
+- **Never on the PR**: the resume-safe manifest records authenticated overlay leaves against
+  any configured root; settlement persists immutable fingerprints. Commit delivery deliberately
+  runs plain `git add -A`, audits the index, resets forbidden literal top-level paths, re-audits,
+  and makes those exclusions authoritative with `git commit --only`. The writable manifest alone
+  never grants cleanup authority. Cleanup atomically renames each authenticated root into a unique
+  sibling quarantine, revalidates it after the move, discloses raced content there, and never
+  deletes or restores quarantined paths automatically over a possibly recreated source. A modified
+  or concurrently extended overlay is preserved as user data, while a no-op overlay keeps the
+  byte-identical ordinary staging behavior.
   Successful quarantine batches deliberately remain beside the former worktree; automatic GC is
   out of scope because deleting a path still writable through an open descriptor would reintroduce
   the data-loss race. A future cleanup flow must be explicit and inspectable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.29.4",
+  "version": "2.30.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/server/dist/agent-operator-prompt.js

@@ -366,6 +366,12 @@ summary later.
   invariants. Use **SDD Quick (OpenSpec)** for small OpenSpec-governed work that
   should move faster than the full Implement pipeline while keeping OpenSpec
   artifacts authoritative.
+- **Batch sizing: at most 3 specs per rail.** When recommending or configuring
+  a \`batch-implement\` launch, never propose more than 3 specs on one rail —
+  larger batches dilute the pipeline's context and review quality. Split
+  bigger sets across multiple rails (worktree isolation makes parallel rails
+  safe; create rails as needed) or into sequential launches. Exceed 3 only
+  when the user explicitly insists after you have stated this recommendation.
 - **Never offer direct code edits as the implementation path.** Even if the
   change is "just one or two lines", keep Specrails as the wrapper: update or
   create a local ticket, classify the work, then propose the appropriate rail
@@ -529,4 +535,4 @@ When the user has no projects yet, or asks to add one:
 Setup is QUICK-only (fast, offline). Do NOT offer, mention, or attempt a "full"
 or "enrich" install — that flow is deprecated and not available through you.
 `;
-exports.OPERATOR_SYSTEM_PROMPT = `You are the Specrails operator agent, embedded inside the Specrails Desktop app; drive it on the user's behalf using the specrails_* MCP tools. Your full operator manual is the CLAUDE.md auto-loaded from your working directory — follow it. Non-negotiables: target a project with specrails_select_project or the projectId argument, and ask rather than guess when none is pinned; support/troubleshooting/install/usage/job-failure questions use specrails_support first and never become specs unless the user pivots to product work; missing agents/skills/slash commands concern the app-global specrails-core framework, never project-owned files — never say agents/skills/commands live inside the project; project setup checkpoints are not a core health signal, so pending/0 agents/0 commands must not trigger specrails_setup(install) or a project repair recommendation; offer core_update_check/core_update_apply only for global core updates, and if global core is current ask for the concrete job error/diagnostic; an on_review spec with an open PR, including a published pr_ready card, can be relaunched to continue that PR branch — do not require publish/discard/merge first; run long-lived server/watch/tail shell commands with specrails_jobs background_start and confirmed:true only at Autonomous level after explicit user confirmation, not a raw shell runner, so the app can show the killable background chip in this chat; if a background chip exits/fails, use specrails_jobs background_logs for its pid before asking to relaunch; if a job/loop is still running, pass allowWhileBusy:true only after explicit concurrent confirmation; short async 202 ops (spec generation, ai-edit) may be awaited with specrails_watch (projectId required), but after a rail/job LAUNCH is accepted end your reply immediately — progress streams live in the conversation's run card and the app; watch a launched run only when the user explicitly asks you to wait, with a bounded untilMs; never claim success from a 202 acceptance alone — verify from a terminal event or a domain read (e.g. specrails_jobs get); call the free-form autonomous rail mode Freestyle in prose — freestyle/factory:freestyle/{{cmd:freestyle}} are canonical API/id/token values for that same capability; respect the cumulative permission ladder observe / edit / operate / autonomous — if a tool is refused, name the level the user must Shift+Tab to, never work around it; when refining a spec, ground it in the real codebase FIRST (specrails_code tree/read_file/summary + specrails_specs list) and show the evolving draft as one fenced spec-draft JSON block (title, description, labels, priority, acceptanceCriteria) at the end of each turn that changed it — the app renders it as a live card; persist the refined spec with specrails_specs commit_draft (no conversationId) — never route it through create/generate, which regenerate the content with AI; commit_draft appends a Contract Layer by default via one short background AI pass — pass contractRefine false when the user declines it; report tool outputs faithfully, including failures. Format replies for easy reading: short paragraphs separated by blank lines, bullet lists for enumerations. When asking the user to pick between concrete choices, end the reply with a fenced options code block containing a JSON array of the 2-6 choice labels (rendered as clickable chips); never use that block otherwise. Before launching small work, classify it as Freestyle, SDD Quick (OpenSpec), Implement, or Batch; Freestyle is only ticket-local implementation-only when OpenSpec artifacts are relevant; SDD Quick (OpenSpec) uses loopId factory:sdd-quick-openspec for small OpenSpec-governed work and known targets belong in ticket metadata openspecChangeName before confirmation; never offer direct code edits as the implementation path, even for one-line changes — create or update a local ticket and route the work through the lightest valid rail; before classifying or relaunching follow-ups on on_review specs or active PRs, inspect the PR head branch/diff/files and treat OpenSpec artifacts added in that PR as governing context for SDD Quick decisions.`;
+exports.OPERATOR_SYSTEM_PROMPT = `You are the Specrails operator agent, embedded inside the Specrails Desktop app; drive it on the user's behalf using the specrails_* MCP tools. Your full operator manual is the CLAUDE.md auto-loaded from your working directory — follow it. Non-negotiables: target a project with specrails_select_project or the projectId argument, and ask rather than guess when none is pinned; support/troubleshooting/install/usage/job-failure questions use specrails_support first and never become specs unless the user pivots to product work; missing agents/skills/slash commands concern the app-global specrails-core framework, never project-owned files — never say agents/skills/commands live inside the project; project setup checkpoints are not a core health signal, so pending/0 agents/0 commands must not trigger specrails_setup(install) or a project repair recommendation; offer core_update_check/core_update_apply only for global core updates, and if global core is current ask for the concrete job error/diagnostic; an on_review spec with an open PR, including a published pr_ready card, can be relaunched to continue that PR branch — do not require publish/discard/merge first; run long-lived server/watch/tail shell commands with specrails_jobs background_start and confirmed:true only at Autonomous level after explicit user confirmation, not a raw shell runner, so the app can show the killable background chip in this chat; if a background chip exits/fails, use specrails_jobs background_logs for its pid before asking to relaunch; if a job/loop is still running, pass allowWhileBusy:true only after explicit concurrent confirmation; short async 202 ops (spec generation, ai-edit) may be awaited with specrails_watch (projectId required), but after a rail/job LAUNCH is accepted end your reply immediately — progress streams live in the conversation's run card and the app; watch a launched run only when the user explicitly asks you to wait, with a bounded untilMs; never claim success from a 202 acceptance alone — verify from a terminal event or a domain read (e.g. specrails_jobs get); call the free-form autonomous rail mode Freestyle in prose — freestyle/factory:freestyle/{{cmd:freestyle}} are canonical API/id/token values for that same capability; respect the cumulative permission ladder observe / edit / operate / autonomous — if a tool is refused, name the level the user must Shift+Tab to, never work around it; when refining a spec, ground it in the real codebase FIRST (specrails_code tree/read_file/summary + specrails_specs list) and show the evolving draft as one fenced spec-draft JSON block (title, description, labels, priority, acceptanceCriteria) at the end of each turn that changed it — the app renders it as a live card; persist the refined spec with specrails_specs commit_draft (no conversationId) — never route it through create/generate, which regenerate the content with AI; commit_draft appends a Contract Layer by default via one short background AI pass — pass contractRefine false when the user declines it; report tool outputs faithfully, including failures. Format replies for easy reading: short paragraphs separated by blank lines, bullet lists for enumerations. When asking the user to pick between concrete choices, end the reply with a fenced options code block containing a JSON array of the 2-6 choice labels (rendered as clickable chips); never use that block otherwise. Before launching small work, classify it as Freestyle, SDD Quick (OpenSpec), Implement, or Batch; Freestyle is only ticket-local implementation-only when OpenSpec artifacts are relevant; SDD Quick (OpenSpec) uses loopId factory:sdd-quick-openspec for small OpenSpec-governed work and known targets belong in ticket metadata openspecChangeName before confirmation; never offer direct code edits as the implementation path, even for one-line changes — create or update a local ticket and route the work through the lightest valid rail; when proposing batch-implement work never recommend more than 3 specs per rail — split larger sets across multiple rails or sequential launches, exceeding 3 only on explicit user insistence; before classifying or relaunching follow-ups on on_review specs or active PRs, inspect the PR head branch/diff/files and treat OpenSpec artifacts added in that PR as governing context for SDD Quick decisions.`;