specrails-desktop 2.36.0 → 2.42.2

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

@@ -5,17 +5,32 @@
 // BUILDER_SYSTEM_PROMPT is the compact equivalent passed via --system-prompt
 // to providers that support a dedicated system-prompt argument.
 //
+// The spec DEPTH bar comes from the shared premium contract
+// (spec-contract-prompt.ts) so the Builder, M2+ generation and the agent's
+// super-spec mode never drift; generation itself is app-driven and batched
+// (blueprint-generation.ts) so depth is no longer capped by one reply's
+// output budget.
+//
 // BYTE-STABILITY CONTRACT: both constants must stay static (no timestamps, no
-// interpolation, no live data) so provider prompt caching can work on turn 2+.
+// interpolation of live data) so provider prompt caching can work on turn 2+.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BUILDER_SYSTEM_PROMPT = exports.BUILDER_INSTRUCTIONS = void 0;
+exports.SPEC_DEPTH_FLOORS = exports.SINGLE_RESPONSE_MODE_LINE = exports.BUILDER_SYSTEM_PROMPT = exports.BUILDER_INSTRUCTIONS = void 0;
+exports.buildSnapshotRepairPrompt = buildSnapshotRepairPrompt;
+const spec_contract_prompt_1 = require("./spec-contract-prompt");
+Object.defineProperty(exports, "SPEC_DEPTH_FLOORS", { enumerable: true, get: function () { return spec_contract_prompt_1.SPEC_DEPTH_FLOORS; } });
+const blueprint_generation_1 = require("./blueprint-generation");
+const EXAMPLE_SPEC_JSON = JSON.stringify(spec_contract_prompt_1.PREMIUM_SCAFFOLD_EXAMPLE, null, 2)
+    .split('\n')
+    .map((line, i) => (i === 0 ? line : `    ${line}`))
+    .join('\n');
 exports.BUILDER_INSTRUCTIONS = `# Specrails Project Builder
 
 You are the Specrails Project Builder: a conversational product architect in
 Specrails Desktop. Help the user turn a raw idea into an approved project
-blueprint and then a rich Milestone-1 backlog. No project or repository exists
-yet: you cannot inspect code, claim that paths exist, or create anything on
-disk. The app performs the commit after the user reviews the result.
+blueprint and then a rich, premium Milestone-1 backlog. No project or
+repository exists yet: you cannot inspect code, claim that paths exist, or
+create anything on disk. The app performs the commit after the user reviews
+the result.
 
 Conversational prose follows the user's language. Every generated spec field
 (\`title\`, \`shortSummary\`, \`description\`, \`acceptanceCriteria\`, and
@@ -29,10 +44,21 @@ blocks. Rules:
 - Every block is a FULL snapshot of the whole blueprint, never a delta. The
   app uses the last valid block, so re-emit everything currently known.
 - Emit at most one block per message and put it at the END of the message.
-- Use valid JSON: double quotes, no comments, and no trailing commas.
+  Nothing follows the closing fence.
+- The fence language is EXACTLY \`blueprint-draft\` (\`\`\`blueprint-draft).
+  A \`\`\`json fence or a bare fence is NOT a snapshot: the app would show the
+  raw JSON in the chat and the panel would stay empty.
+- Use strictly valid JSON: double quotes only, no comments, no trailing
+  commas, no nested code fences inside the block, and no prose inside it.
+- Inside JSON strings escape every newline as \\n and every double quote as
+  \\". Markdown descriptions therefore travel as ONE line per string.
+- The app validates every block. If it tells you a block was rejected or cut
+  off, answer with ONLY the complete corrected snapshot — no prose.
+- When nothing changed since your last accepted snapshot you may omit the
+  block; the app keeps the last accepted state.
 - All keys below are required except \`stack.notes\` and \`dependsOnIndex\`:
 
-\`\`\`json
+\`\`\`blueprint-draft
 {
   "blueprintVersion": 1,
   "product": { "name": "...", "pitch": "...", "audience": "..." },
@@ -46,19 +72,16 @@ blocks. Rules:
   ],
   "specsComplete": false,
   "m1Specs": [
-    {
-      "kind": "scaffold",
-      "title": "Scaffold the runnable project foundation",
-      "shortSummary": "Initialize a reproducible foundation that every later walking-skeleton slice can build on.",
-      "description": "## Problem Statement\\nThe approved project has a README and selected stack, but contributors cannot yet install, run, or verify a working application.\\n\\n## Proposed Solution\\nInitialize the selected stack with deterministic development, build, test, and CI commands while preserving the existing README.\\n\\n## Out of Scope\\n- Product features beyond a minimal runnable shell\\n- Production deployment and environment provisioning\\n\\n## Technical Considerations\\n- Pin compatible runtime and dependency versions for reproducible setup\\n- Keep the first application and test boundaries minimal but executable\\n\\n## Estimated Complexity\\nMedium - the foundation must align local development, automated tests, and CI without implementing product behavior.",
-      "acceptanceCriteria": ["A clean checkout installs successfully with the documented command.", "The development command starts the minimal application without an error.", "The automated test command passes from a clean checkout.", "CI executes the build and test commands on every proposed change."],
-      "priority": "high",
-      "labels": ["M1", "foundation"]
-    }
+    ${EXAMPLE_SPEC_JSON}
   ]
 }
 \`\`\`
 
+The example above is the mandatory first spec at the DEPTH every spec must
+reach: a narrative problem, a journey plus the five \`###\` sub-blocks, three
+placed exclusions, labelled technical bullets and six behavioural criteria.
+Shorter is a defect, not a style.
+
 ## Interview and approval gate
 
 - Ask questions for at most three assistant turns. After that, propose concrete
@@ -83,36 +106,9 @@ blocks. Rules:
 - If an idea is beyond the walking skeleton, park it as an M2+ title rather
   than expanding M1 into a waterfall.
 
-## Canonical detailed-spec contract
-
-Every detailed M1 spec must satisfy all of these rules:
-
-- \`kind\` is exactly \`scaffold\`, \`feature\`, or \`verification\`.
-- \`title\` is concise, action-oriented, unique in the batch, and in English.
-- \`shortSummary\` is one useful English sentence, no more than 240 characters.
-- \`description\` is English markdown with exactly these five \`##\` headings,
-  once each and in this order:
-  1. \`## Problem Statement\` — who has the problem, when, why it matters, and
-     the user or product value of solving it.
-  2. \`## Proposed Solution\` — the concrete behavior and planned components or
-     contracts that deliver the thin outcome.
-  3. \`## Out of Scope\` — at least two honest bullets naming adjacent work that
-     this spec deliberately defers.
-  4. \`## Technical Considerations\` — at least two bullets covering the selected stack,
-     planned components and interfaces, risks, invariants, testing strategy,
-     and dependencies on earlier specs where relevant.
-  5. \`## Estimated Complexity\` — Low, Medium, High, or Very High plus one
-     sentence explaining what drives the estimate.
-- Do NOT put an \`## Acceptance Criteria\` heading in \`description\`. Criteria
-  live only in the separate \`acceptanceCriteria\` array; the app folds them
-  into the ticket deterministically at commit time.
-- \`acceptanceCriteria\` contains 4–10 non-empty, independent, testable outcomes,
-  not implementation steps. Cover the intended behavior, observable failure or
-  edge cases, and relevant automated verification.
-- \`priority\` is exactly \`low\`, \`medium\`, \`high\`, or \`critical\` and
-  reflects delivery urgency/risk rather than implementation complexity.
-- \`labels\` includes \`M1\` plus at least one concise domain label such as
-  \`frontend\`, \`api\`, \`data\`, \`auth\`, \`testing\`, or \`infra\`.
+## Canonical detailed-spec contract (premium bar)
+
+${(0, spec_contract_prompt_1.premiumSpecContract)('day0')}
 - \`m1Specs[0]\` is \`kind: "scaffold"\` and omits \`dependsOnIndex\`. It
   states that the repository already contains a README and defines concrete
   install, run, test, and CI outcomes for the selected stack.
@@ -120,30 +116,62 @@ Every detailed M1 spec must satisfy all of these rules:
   item, and the integer must point strictly backward to an earlier array index.
   Never point forward or to the same spec.
 
+## Generation protocol (app-driven batches)
+
+Premium depth does not fit ten specs in one reply, so the APP drives
+generation in turns. Follow the phase the app is in:
+
+1. **Outline** — right after approval, emit ONE \`blueprint-draft\` FULL
+   snapshot listing the whole 5–10-spec walking skeleton with every spec's
+   \`kind\`, \`title\`, \`shortSummary\`, \`priority\`, \`labels\` and
+   \`dependsOnIndex\` decided, but \`description: ""\` and
+   \`acceptanceCriteria: []\` for every spec, and \`specsComplete: false\`.
+   One line of prose at most ("Outline ready — writing the specs next.").
+2. **Detail turns** — the app then sends \`APP CONTINUE\` naming
+   ${blueprint_generation_1.SPECS_PER_DETAIL_TURN} specs by index and title. Reply with ONE fenced
+   \`spec-detail\` block per named spec and nothing else:
+   \`{ "index": <0-based m1Specs index>, "spec": { …the complete premium spec… } }\`.
+   Write each spec at full depth; keep the outline's kind, priority, labels and
+   dependency. Do not re-emit the blueprint-draft block on detail turns.
+3. **Audit turn** — when the app sends \`APP AUDIT\`, audit the whole batch
+   against the contract and reply with ONE fenced \`spec-audit\` block:
+   \`{ "specsComplete": true|false, "issues": [...], "fixes": [ { "index": n, "spec": {…} } ] }\`
+   — complete corrected specs in \`fixes\`, \`specsComplete: true\` only when
+   every spec passes.
+4. **Corrections** — when the app lists audit problems, reply with
+   \`spec-detail\` blocks for ONLY the affected specs (complete corrected spec
+   objects), never the whole snapshot.
+
+Only when the app says \`GENERATION MODE: single response\` (a provider that
+cannot resume sessions) do you instead emit every spec complete inside one
+\`blueprint-draft\` snapshot in one reply, prioritising per-spec depth over
+prose, with \`specsComplete: true\` only after self-auditing all of them. If a
+complete audited batch cannot be produced in that mode, keep
+\`m1Specs: []\` and \`specsComplete: false\` and explain what blocked it.
+
 ## Day-0 grounding
 
 There is no codebase to inspect. Ground technical details in the selected
 stack, planned components, intended contracts/data shapes, known risks, and
-inter-spec dependencies. Never invent or imply existing repository paths,
-filenames, modules, functions, identifiers, migrations, or test files.
-
-## Generation and completion
-
-- After approval, generate the complete 5–10-spec walking skeleton in one
-  response and one FULL snapshot. Never expose a partial detailed-spec batch as
-  a result the user must manually ask you to continue.
-- If the complete batch cannot fit or cannot pass validation, keep
-  \`m1Specs: []\` and \`specsComplete: false\`, explain what prevented completion,
-  and wait for a fresh generation request. Do not emit partially generated specs.
-- Before setting \`specsComplete: true\`, self-audit the entire snapshot: schema
-  fields, exact five headings and order, English content, 4–10 criteria, valid
-  priority, M1 plus domain labels, unique titles, scaffold first, and strictly
-  backward dependencies. Set it true only if every spec passes. If anything
-  fails, keep it false and repair the snapshot first.
+inter-spec dependencies. Label every module, path, table or route you
+introduce as planned; never invent or imply an EXISTING repository path,
+filename, module, function, identifier, migration, or test file.
 
 ## Boundaries
 
 - Never claim to have created files, repositories, tickets, or projects.
 - Never include secrets, real API keys, or license-restricted code in specs.
 `;
-exports.BUILDER_SYSTEM_PROMPT = `You are the Specrails Project Builder. No repository exists yet. Converse in the user's language, but write every spec field in English. Emit at most one final fenced blueprint-draft JSON FULL snapshot per message. Before explicit blueprint approval or a direct request to generate specs, populate product/coreFlow/platform/stack/assumptions/milestones but ALWAYS keep m1Specs: [] and specsComplete: false; "surprise me" also proposes dimensions only and asks for approval. After approval generate the complete 5-10-spec M1 walking skeleton in one response and one FULL snapshot; never expose a partial batch the user must ask you to continue. If the complete batch cannot be produced and audited, emit m1Specs: [] with specsComplete: false instead of partial specs. Each spec has kind (scaffold|feature|verification), unique action-oriented title, one-sentence shortSummary <=240 characters, description with exactly these headings once and in order: ## Problem Statement, ## Proposed Solution, ## Out of Scope, ## Technical Considerations, ## Estimated Complexity; Out of Scope and Technical Considerations each contain at least two bullets; a separate acceptanceCriteria array of 4-10 independent testable outcomes (never an ## Acceptance Criteria section in description); priority low|medium|high|critical; labels including M1 and a domain label; and optional dependsOnIndex pointing strictly backward. m1Specs[0] is kind scaffold, omits dependsOnIndex, notes the repo already contains a README, and defines install/run/test/CI outcomes. Ground day-0 content in the selected stack, planned components/contracts, risks, tests, and spec dependencies; NEVER invent paths or existing identifiers. M2+ keeps title-only plannedSpecs. Set specsComplete true only after auditing all fields, five headings, English content, 4-10 criteria, labels, scaffold, unique titles, and dependencies. Never claim disk changes.`;
+exports.BUILDER_SYSTEM_PROMPT = `You are the Specrails Project Builder. No repository exists yet. Converse in the user's language, but write every spec field in English. Emit at most one final fenced blueprint-draft JSON FULL snapshot per message (fence language EXACTLY blueprint-draft — never json or a bare fence), at the END of the message, as strictly valid JSON (double quotes, newlines inside strings escaped as \\n, inner quotes escaped as \\", no trailing commas, no comments, no nested code fences, nothing after the closing fence). If the app reports that a block was rejected or cut off, reply with ONLY the complete corrected block. Before explicit blueprint approval or a direct request to generate specs, populate product/coreFlow/platform/stack/assumptions/milestones but ALWAYS keep m1Specs: [] and specsComplete: false; "surprise me" also proposes dimensions only and asks for approval. Generation is app-driven and batched: after approval emit ONE blueprint-draft OUTLINE snapshot (all 5-10 M1 specs with kind/title/shortSummary/priority/labels/dependsOnIndex, description "" and acceptanceCriteria [] for every spec, specsComplete false); when the app sends APP CONTINUE reply with one fenced spec-detail block per named spec ({ "index": n, "spec": {...complete spec...} }) and nothing else; when it sends APP AUDIT reply with one fenced spec-audit block ({ "specsComplete", "issues", "fixes": [{ "index", "spec" }] }); when it lists audit problems reply with spec-detail blocks for the affected specs only. Only if the app says GENERATION MODE: single response, emit every spec complete in one blueprint-draft snapshot with specsComplete true after self-auditing all of them, else m1Specs: [] with specsComplete: false. ${(0, spec_contract_prompt_1.premiumSpecContractCompact)('day0')} m1Specs[0] is kind scaffold, omits dependsOnIndex, notes the repo already contains a README, and defines install/run/test/CI outcomes; dependsOnIndex points strictly backward. M2+ keeps title-only plannedSpecs. Never claim disk changes.`;
+const REPAIR_PROMPTS = {
+    invalid_json: `APP CHECK: your last blueprint-draft block was REJECTED because it is not valid JSON. Re-emit the COMPLETE snapshot now — every field, every spec — as strictly valid JSON: double quotes only, newlines inside strings escaped as \\n, inner double quotes escaped as \\", no trailing commas, no comments, no nested code fences, nothing after the closing fence. Reply with ONLY the block.`,
+    truncated: `APP CHECK: your last blueprint-draft block was CUT OFF before its closing fence — the reply exceeded the output limit, so the app received nothing. Do NOT shorten the specs. If this was the outline, re-emit the complete outline snapshot (every spec with an empty description and empty criteria). If you were writing detailed specs in one reply, re-emit the snapshot with empty bodies as an OUTLINE and let the app request the detail spec by spec. Reply with ONLY the block, no prose.`,
+    quality: `APP CHECK: the deterministic audit rejected the batch. Fix EXACTLY the problems listed below — enrich, never trim — and reply with ONE fenced spec-detail block per AFFECTED spec ({ "index": <0-based m1Specs index>, "spec": { …the complete corrected spec… } }) and nothing else; do not re-emit the whole snapshot. Untouched specs keep their current content.`,
+};
+function buildSnapshotRepairPrompt(kind, detail) {
+    const base = REPAIR_PROMPTS[kind];
+    const trimmed = detail.trim();
+    return trimmed ? `${base}\n\nDetails:\n${trimmed}` : base;
+}
+/** Appended to the per-turn prompt for providers that cannot resume sessions. */
+exports.SINGLE_RESPONSE_MODE_LINE = 'GENERATION MODE: single response — this provider cannot resume sessions, so when you generate the specs emit every spec complete inside ONE blueprint-draft snapshot.';

package/server/dist/blueprint-router.js

@@ -3,9 +3,11 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isProjectBuilderEnabled = isProjectBuilderEnabled;
 exports.createBlueprintRouter = createBlueprintRouter;
 const express_1 = require("express");
+const blueprint_chat_manager_1 = require("./blueprint-chat-manager");
 const providers_1 = require("./providers");
 const runtime_1 = require("./providers/runtime");
 const blueprint_store_1 = require("./blueprint-store");
+const blueprint_spec_quality_1 = require("./blueprint-spec-quality");
 function isProjectBuilderEnabled() {
     return process.env.SPECRAILS_PROJECT_BUILDER !== 'false';
 }
@@ -48,7 +50,15 @@ function createBlueprintRouter(deps) {
             efforts: toolPolicy ? (0, providers_1.reasoningEffortsForModel)(adapter, model) : [],
         });
     });
-    router.get('/conversations', (_req, res) => {
+    // `?resumable=1` → the "continue where you left off" list: unfinished
+    // (never committed) conversations with at least one assistant reply, each
+    // with a snapshot summary — the durable answer to "I closed the panel and
+    // lost the specs".
+    router.get('/conversations', (req, res) => {
+        if (req.query.resumable === '1' || req.query.resumable === 'true') {
+            res.json({ conversations: (0, blueprint_store_1.listResumableBlueprintConversations)(desktopDb) });
+            return;
+        }
         res.json({ conversations: (0, blueprint_store_1.listBlueprintConversations)(desktopDb) });
     });
     router.post('/conversations', (req, res) => {
@@ -62,13 +72,36 @@ function createBlueprintRouter(deps) {
         const conversation = (0, blueprint_store_1.createBlueprintConversation)(desktopDb, { provider, model });
         res.status(201).json({ conversation });
     });
+    // Rehydration payload: transcript (block-only replies hidden — their raw
+    // payload stays in the row), the persisted snapshot pair, and its status so
+    // the panel resumes with the same readiness/repair affordances it had live.
     router.get('/conversations/:id', (req, res) => {
         const conversation = (0, blueprint_store_1.getBlueprintConversation)(desktopDb, String(req.params.id));
         if (!conversation) {
             res.status(404).json({ error: 'conversation not found' });
             return;
         }
-        res.json({ conversation, messages: (0, blueprint_store_1.listBlueprintMessages)(desktopDb, conversation.id) });
+        const snapshot = (0, blueprint_store_1.getBlueprintSnapshot)(desktopDb, conversation.id);
+        const audit = snapshot.rawBlueprint !== null ? (0, blueprint_spec_quality_1.auditRawBlueprintForM1)(snapshot.rawBlueprint) : null;
+        const messages = (0, blueprint_store_1.listBlueprintMessages)(desktopDb, conversation.id)
+            .filter((m) => m.content.trim() !== '')
+            .map(({ raw_content: _raw, ...rest }) => rest);
+        res.json({
+            conversation,
+            messages,
+            blueprint: snapshot.blueprint,
+            rawBlueprint: snapshot.rawBlueprint,
+            snapshot: snapshot.issue
+                ? { status: 'rejected', reason: snapshot.issue.reason, detail: snapshot.issue.detail }
+                : snapshot.blueprint
+                    ? {
+                        status: 'accepted',
+                        claimsComplete: audit?.claimsComplete ?? false,
+                        ...(audit && audit.claimsComplete && !audit.valid ? { qualityIssues: audit.issues } : {}),
+                    }
+                    : { status: 'none' },
+            snapshotUpdatedAt: snapshot.snapshotUpdatedAt,
+        });
     });
     router.patch('/conversations/:id', (req, res) => {
         const conversation = (0, blueprint_store_1.getBlueprintConversation)(desktopDb, String(req.params.id));
@@ -177,9 +210,28 @@ function createBlueprintRouter(deps) {
             }
             reasoningEffort = body.reasoning_effort;
         }
-        void manager.sendMessage(conversation.id, text, { model, reasoningEffort });
+        const intent = blueprint_chat_manager_1.BUILDER_TURN_INTENTS.includes(String(body.intent)) ? body.intent : undefined;
+        void manager.sendMessage(conversation.id, text, { model, reasoningEffort, ...(intent ? { intent } : {}) });
         res.status(202).json({ accepted: true });
     });
+    // Manual snapshot repair: re-ask the Builder for its last block (rejected
+    // JSON / cut-off reply) or for the audit fixes (claimed complete, gate
+    // disagreed). 202 + `blueprint.repairing` → streams → `blueprint.done`.
+    router.post('/conversations/:id/repair-snapshot', async (req, res) => {
+        const conversation = (0, blueprint_store_1.getBlueprintConversation)(desktopDb, String(req.params.id));
+        if (!conversation) {
+            res.status(404).json({ error: 'conversation not found' });
+            return;
+        }
+        const rawEffort = (req.body ?? {}).reasoningEffort;
+        const outcome = await manager.repairSnapshot(conversation.id, typeof rawEffort === 'string' ? { reasoningEffort: rawEffort } : {});
+        if (!outcome.ok) {
+            const status = outcome.reason === 'unknown_conversation' ? 404 : 409;
+            res.status(status).json({ error: outcome.reason });
+            return;
+        }
+        res.status(202).json({ accepted: true, kind: outcome.kind });
+    });
     router.post('/conversations/:id/abort', (req, res) => {
         const conversation = (0, blueprint_store_1.getBlueprintConversation)(desktopDb, String(req.params.id));
         if (!conversation) {

package/server/dist/blueprint-spec-fixtures.js

@@ -0,0 +1,85 @@
+"use strict";
+// Premium-bar spec fixtures shared by the server test suites (and usable by
+// any seam that needs a gate-valid detailed spec). Every builder here passes
+// `analyzeBuilderSpecBatch` under the raised floors (spec-contract-prompt.ts
+// SPEC_DEPTH_FLOORS): narrative problem, sub-blocked solution, ≥3 / ≥5
+// bullets, reasoned complexity, 6 behavioural criteria.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.premiumDescription = premiumDescription;
+exports.premiumCriteria = premiumCriteria;
+exports.premiumSpec = premiumSpec;
+function premiumDescription(opts = {}) {
+    const subject = opts.subject ?? 'the core workflow';
+    return [
+        '## Problem Statement',
+        `A home cook who opens the product today has no way to complete ${subject} end to end: the flow stops at the first screen, nothing is persisted, and nobody can tell whether the slice works. It matters now because every later Milestone-1 spec is defined as building on this slice.${opts.readme ? ' The repository already contains a README and nothing else.' : ''} A good outcome is a thin, runnable, tested version of ${subject} that a contributor can run from a clean checkout and a reviewer can exercise without guidance.`,
+        '',
+        '## Proposed Solution',
+        `1. The user opens the entry screen for ${subject} and sees the empty state.`,
+        '2. They provide the minimal input and submit it.',
+        '3. The system validates, persists and echoes the result on the next screen.',
+        '4. Reloading shows the persisted state; invalid input shows an inline error.',
+        '',
+        '### User experience',
+        'One screen with an empty state, a loading indicator while saving, an inline validation error and a success confirmation; the last successful input is remembered between visits.',
+        '',
+        '### Data model',
+        '`Entry { id: uuid, createdAt: timestamp, payload: text (1–500 chars), status: "draft" | "saved" }` (planned).',
+        '',
+        '### Interfaces & contracts',
+        '`POST /entries { payload } → 201 { id, status }`; `400 { error: "invalid_payload" }` on validation failure; `GET /entries/:id → 200 | 404` (planned).',
+        '',
+        '### Planned modules',
+        '- `src/features/entries/EntryScreen (planned)` — the screen and its states.',
+        '- `src/features/entries/entries-api (planned)` — request/response handling and validation.',
+        '- `src/data/entries-repository (planned)` — persistence behind one interface.',
+        '',
+        '### Key decisions',
+        '- Persist through a repository interface instead of calling the database from the screen, so later slices swap storage without touching UI; rejected: direct calls for speed.',
+        '- Validate on both client and server; rejected: server-only validation because the empty-state UX needs immediate feedback.',
+        '',
+        '## Out of Scope',
+        '- Social sharing and collaboration — deferred to the "Sharing" milestone because it needs accounts first.',
+        '- Advanced personalization and recommendations — deferred to a later milestone once real usage data exists.',
+        '- Offline editing — deferred; the walking skeleton assumes connectivity.',
+        '',
+        '## Technical Considerations',
+        '- **Architecture**: screen → api module → repository; no cross-layer imports.',
+        '- **Data & contracts**: the `Entry` shape and the `/entries` routes are frozen for later slices.',
+        '- **Failure handling & edge cases**: empty payload, over-long payload and a missing id each produce a distinct, tested error.',
+        '- **Security & privacy**: input is length-limited and escaped before rendering; no personal data beyond the payload.',
+        '- **Testing strategy**: unit — validation rules; integration — repository round trip; e2e — submit, reload, error path.',
+        '- **Dependencies**: builds on the scaffold spec; nothing else.',
+        '- **Risks & mitigations**: persistence schema churn — mitigated by the repository interface.',
+        '',
+        '## Estimated Complexity',
+        'Medium — the slice crosses UI, validation and persistence; the main uncertainty is the persistence setup on the chosen stack.',
+    ].join('\n');
+}
+function premiumCriteria(seed = '') {
+    const s = seed ? ` (${seed})` : '';
+    return [
+        `Given a clean checkout, when the user completes the primary happy path${s}, then the result is persisted and shown on the next screen.`,
+        `When the user submits an empty or over-long payload${s}, then an inline validation error names the rule and nothing is persisted.`,
+        `When the user opens the screen with no data${s}, then a deliberate empty state explains what to do first.`,
+        `When the page reloads after a successful save${s}, then the persisted state is shown again without re-entry.`,
+        `When the persistence layer is unavailable${s}, then the user sees an actionable error and the input is kept for retry.`,
+        `Automated unit, integration and end-to-end tests cover the happy path, the validation error and the persistence failure${s}, and pass in CI.`,
+    ];
+}
+function premiumSpec(index, over = {}) {
+    const scaffold = index === 0;
+    return {
+        kind: scaffold ? 'scaffold' : 'feature',
+        title: scaffold ? 'Scaffold the runnable project foundation' : `Deliver workflow slice ${index}`,
+        shortSummary: scaffold
+            ? 'Turn the README-only repository into an installable, runnable, testable application shell with CI.'
+            : `Deliver an independently testable workflow slice ${index} on top of the scaffold.`,
+        description: premiumDescription({ readme: scaffold, subject: scaffold ? 'the project foundation' : `workflow slice ${index}` }),
+        acceptanceCriteria: premiumCriteria(scaffold ? 'foundation' : `slice ${index}`),
+        priority: 'medium',
+        labels: ['M1', scaffold ? 'foundation' : 'workflow'],
+        ...(index > 0 ? { dependsOnIndex: index - 1 } : {}),
+        ...over,
+    };
+}

package/server/dist/blueprint-spec-quality.js

@@ -1,9 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BUILDER_SPEC_HEADINGS = void 0;
+exports.M1_BATCH_QUALITY_OPTIONS = exports.BUILDER_SPEC_HEADINGS = void 0;
 exports.analyzeBuilderSpecBatch = analyzeBuilderSpecBatch;
 exports.firstBuilderSpecQualityDetail = firstBuilderSpecQualityDetail;
 exports.analyzeTypedBuilderSpecs = analyzeTypedBuilderSpecs;
+exports.auditRawBlueprintForM1 = auditRawBlueprintForM1;
+exports.formatQualityIssuesForModel = formatQualityIssuesForModel;
+const spec_contract_prompt_1 = require("./spec-contract-prompt");
 exports.BUILDER_SPEC_HEADINGS = [
     'Problem Statement',
     'Proposed Solution',
@@ -14,8 +17,14 @@ exports.BUILDER_SPEC_HEADINGS = [
 const VALID_KINDS = new Set(['scaffold', 'feature', 'verification']);
 const VALID_PRIORITIES = new Set(['critical', 'high', 'medium', 'low']);
 const PLACEHOLDER_CRITERION = /^(?:todo|tbd|n\/?a|works?|test(?: it)?|criterion|acceptance criterion)$/i;
-function issue(issues, specIndex, field, code, message) {
-    issues.push({ specIndex, field, code, message });
+function issue(issues, specIndex, field, code, message, params = {}) {
+    issues.push({
+        specIndex,
+        field,
+        code,
+        message,
+        params: specIndex === null ? params : { n: specIndex + 1, ...params },
+    });
 }
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value)
@@ -51,7 +60,7 @@ function analyzeBuilderSpecBatch(input, options) {
         issue(issues, null, 'specsComplete', 'batch_incomplete', 'generation is not marked complete');
     }
     if (input.specs.length < options.minSpecs || input.specs.length > options.maxSpecs) {
-        issue(issues, null, 'm1Specs', 'spec_count', `requires ${options.minSpecs}-${options.maxSpecs} specs (received ${input.specs.length})`);
+        issue(issues, null, 'm1Specs', 'spec_count', `requires ${options.minSpecs}-${options.maxSpecs} specs (received ${input.specs.length})`, { min: options.minSpecs, max: options.maxSpecs, count: input.specs.length });
     }
     const titles = new Map();
     input.specs.forEach((raw, specIndex) => {
@@ -79,7 +88,7 @@ function analyzeBuilderSpecBatch(input, options) {
             const key = normalized(title);
             const prior = titles.get(key);
             if (prior !== undefined) {
-                issue(issues, specIndex, 'title', 'duplicate', `spec ${humanIndex} duplicates spec ${prior + 1} title`);
+                issue(issues, specIndex, 'title', 'duplicate', `spec ${humanIndex} duplicates spec ${prior + 1} title`, { other: prior + 1 });
             }
             else {
                 titles.set(key, specIndex);
@@ -101,10 +110,10 @@ function analyzeBuilderSpecBatch(input, options) {
             : [];
         const normalizedLabels = new Set(labels.map((value) => value.toUpperCase()));
         if (!normalizedLabels.has(label)) {
-            issue(issues, specIndex, 'labels', 'milestone_label', `spec ${humanIndex} labels must include ${label}`);
+            issue(issues, specIndex, 'labels', 'milestone_label', `spec ${humanIndex} labels must include ${label}`, { label });
         }
         if (labels.every((value) => value.toUpperCase() === label)) {
-            issue(issues, specIndex, 'labels', 'domain_label', `spec ${humanIndex} requires at least one domain label besides ${label}`);
+            issue(issues, specIndex, 'labels', 'domain_label', `spec ${humanIndex} requires at least one domain label besides ${label}`, { label });
         }
         const description = typeof spec.description === 'string' ? spec.description.trim() : '';
         const sections = h2Sections(description);
@@ -115,13 +124,22 @@ function analyzeBuilderSpecBatch(input, options) {
         }
         for (const heading of exports.BUILDER_SPEC_HEADINGS) {
             if (!(sections.bodies.get(heading) ?? '').trim()) {
-                issue(issues, specIndex, 'description', 'empty_section', `spec ${humanIndex} section "${heading}" cannot be empty`);
+                issue(issues, specIndex, 'description', 'empty_section', `spec ${humanIndex} section "${heading}" cannot be empty`, { heading });
+            }
+        }
+        // Depth floors (premium-milestone-progress D8): a restated title is not a
+        // problem statement and two lines are not a solution. Character floors are
+        // crude but deterministic — the prompt carries the real bar.
+        for (const [heading, min] of [['Problem Statement', spec_contract_prompt_1.SPEC_DEPTH_FLOORS.problemMinChars], ['Proposed Solution', spec_contract_prompt_1.SPEC_DEPTH_FLOORS.solutionMinChars]]) {
+            const body = (sections.bodies.get(heading) ?? '').trim();
+            if (body && body.length < min) {
+                issue(issues, specIndex, 'description', 'section_depth', `spec ${humanIndex} section "${heading}" is too thin (needs at least ${min} characters)`, { heading, min });
             }
         }
-        for (const heading of ['Out of Scope', 'Technical Considerations']) {
+        for (const [heading, min] of [['Out of Scope', spec_contract_prompt_1.SPEC_DEPTH_FLOORS.outOfScopeMinBullets], ['Technical Considerations', spec_contract_prompt_1.SPEC_DEPTH_FLOORS.technicalMinBullets]]) {
             const body = sections.bodies.get(heading) ?? '';
-            if (body && bulletCount(body) < 2) {
-                issue(issues, specIndex, 'description', 'section_bullets', `spec ${humanIndex} section "${heading}" requires at least two bullets`);
+            if (body && bulletCount(body) < min) {
+                issue(issues, specIndex, 'description', 'section_bullets', `spec ${humanIndex} section "${heading}" requires at least ${min} bullets`, { heading, min });
             }
         }
         const complexity = sections.bodies.get('Estimated Complexity') ?? '';
@@ -132,19 +150,19 @@ function analyzeBuilderSpecBatch(input, options) {
             issue(issues, specIndex, 'description', 'scaffold_readme', 'spec 1 must note that the repository already contains a README');
         }
         const criteria = Array.isArray(spec.acceptanceCriteria) ? spec.acceptanceCriteria : [];
-        if (criteria.length < 4 || criteria.length > 10) {
-            issue(issues, specIndex, 'acceptanceCriteria', 'criteria_count', `spec ${humanIndex} acceptanceCriteria requires 4-10 items`);
+        if (criteria.length < spec_contract_prompt_1.SPEC_DEPTH_FLOORS.criteriaMin || criteria.length > spec_contract_prompt_1.SPEC_DEPTH_FLOORS.criteriaMax) {
+            issue(issues, specIndex, 'acceptanceCriteria', 'criteria_count', `spec ${humanIndex} acceptanceCriteria requires ${spec_contract_prompt_1.SPEC_DEPTH_FLOORS.criteriaMin}-${spec_contract_prompt_1.SPEC_DEPTH_FLOORS.criteriaMax} items`, { count: criteria.length, min: spec_contract_prompt_1.SPEC_DEPTH_FLOORS.criteriaMin, max: spec_contract_prompt_1.SPEC_DEPTH_FLOORS.criteriaMax });
         }
         const seenCriteria = new Set();
         criteria.forEach((criterion, criterionIndex) => {
             const text = typeof criterion === 'string' ? criterion.trim() : '';
-            if (text.length < 10 || PLACEHOLDER_CRITERION.test(text)) {
-                issue(issues, specIndex, 'acceptanceCriteria', 'criterion_quality', `spec ${humanIndex} criterion ${criterionIndex + 1} must be a concrete testable outcome`);
+            if (text.length < spec_contract_prompt_1.SPEC_DEPTH_FLOORS.criterionMinChars || PLACEHOLDER_CRITERION.test(text)) {
+                issue(issues, specIndex, 'acceptanceCriteria', 'criterion_quality', `spec ${humanIndex} criterion ${criterionIndex + 1} must be a concrete testable outcome`, { criterion: criterionIndex + 1 });
                 return;
             }
             const key = normalized(text);
             if (seenCriteria.has(key)) {
-                issue(issues, specIndex, 'acceptanceCriteria', 'duplicate_criterion', `spec ${humanIndex} criterion ${criterionIndex + 1} is duplicated`);
+                issue(issues, specIndex, 'acceptanceCriteria', 'duplicate_criterion', `spec ${humanIndex} criterion ${criterionIndex + 1} is duplicated`, { criterion: criterionIndex + 1 });
             }
             seenCriteria.add(key);
         });
@@ -165,3 +183,26 @@ function firstBuilderSpecQualityDetail(report) {
 function analyzeTypedBuilderSpecs(specs, specsComplete, options) {
     return analyzeBuilderSpecBatch({ specs, specsComplete }, options);
 }
+/** M1 walking-skeleton gate options — the single definition shared by the
+ *  commit validator, the chat manager's post-turn audit, and the router. */
+exports.M1_BATCH_QUALITY_OPTIONS = {
+    milestoneLabel: 'M1',
+    minSpecs: 5,
+    maxSpecs: 10,
+    requireScaffold: true,
+};
+/** Audit an exact raw snapshot payload against the M1 gate. Tolerant of any
+ *  input shape (a non-object simply fails the gate). */
+function auditRawBlueprintForM1(rawBlueprint) {
+    const source = record(rawBlueprint);
+    const specs = Array.isArray(source?.m1Specs) ? source.m1Specs : [];
+    const report = analyzeBuilderSpecBatch({ specsComplete: source?.specsComplete, specs }, exports.M1_BATCH_QUALITY_OPTIONS);
+    return { ...report, claimsComplete: source?.specsComplete === true };
+}
+/** Compact, model-facing rendering of the audit (one line per issue). */
+function formatQualityIssuesForModel(issues, max = 40) {
+    const lines = issues.slice(0, max).map((i) => `- ${i.message}`);
+    if (issues.length > max)
+        lines.push(`- …and ${issues.length - max} more`);
+    return lines.join('\n');
+}