specrails-desktop 2.64.1 → 2.65.0

package/server/dist/modules/loops/runtime/loop-factory.js

@@ -1,8 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FACTORY_LOOPS = exports.FACTORY_REVISION_LOOP_ID = void 0;
+exports.FACTORY_LOOPS = exports.FACTORY_REVISION_LOOP_ID = exports.FLOW_SPEC_LOOP_ID = void 0;
+exports.supportsFlowSpec = supportsFlowSpec;
 exports.factoryLoopsForCapabilities = factoryLoopsForCapabilities;
 exports.getFactoryLoop = getFactoryLoop;
+exports.canonicalFactoryLoopId = canonicalFactoryLoopId;
 exports.isFactoryLoopId = isFactoryLoopId;
 exports.factoryLoopMode = factoryLoopMode;
 exports.factoryLoopForMode = factoryLoopForMode;
@@ -21,6 +23,7 @@ exports.factoryLoopForMode = factoryLoopForMode;
  * (which are random) and the rail resolver can recognise a factory loop.
  */
 const loop_core_factory_1 = require("./loop-core-factory");
+const loop_flow_spec_recipe_1 = require("./loop-flow-spec-recipe");
 const loop_templates_1 = require("./loop-templates");
 const GREEN_GOAL = 'Stop only when the latest verification step reports {{const:VERIFICATION_PASS}} and the history proves every acceptance criterion is implemented across all required tickets and repositories, with the relevant behavioral checks and configured tests/build passing. Green baseline checks, setup, or planning alone do not prove completion.';
 // Factory loops run the WHOLE architect→developer→reviewer pipeline inside a
@@ -58,6 +61,23 @@ const SDD_QUICK_OPENSPEC_FACTORY = {
     mode: 'loop',
     graph: (0, loop_templates_1.opsxLifecycleGraph)(),
 };
+/** Flow -> Spec (Flow mode, arch section 4.8): derives the spec of a Flow
+ *  worktree. Only a Flow hand-off launches it (the rails route answers 400
+ *  `flow_id_required` otherwise); listed with `launchable: false`. */
+exports.FLOW_SPEC_LOOP_ID = 'factory:flow-spec';
+const FLOW_SPEC_FACTORY = {
+    id: exports.FLOW_SPEC_LOOP_ID,
+    name: 'Flow → Spec',
+    description: 'Derives the spec of code built in a Flow session: writes the OpenSpec change from the diff and the conversation, verifies it, reviews coverage and archives it.',
+    mode: 'loop',
+    requiredCoreCapability: 'deriveChange',
+    launchable: false,
+    graph: (0, loop_flow_spec_recipe_1.flowSpecGraph)(),
+};
+/** Core advertises the workflow engine and the derive-change piece. */
+function supportsFlowSpec(capabilities) {
+    return capabilities?.engineV2 === 1 && capabilities.workflowDefinitions === 1 && capabilities.deriveChange === 1;
+}
 /** Legacy persisted id. Resolves to Quick SDD; no Revision loop is listed or run. */
 exports.FACTORY_REVISION_LOOP_ID = 'factory:revision';
 exports.FACTORY_LOOPS = [
@@ -89,12 +109,16 @@ const FACTORY_ALIASES = new Map([
 ]);
 const FACTORY_BY_ID = new Map([
     ...exports.FACTORY_LOOPS.map((f) => [f.id, f]),
+    [FLOW_SPEC_FACTORY.id, FLOW_SPEC_FACTORY],
     ...FACTORY_ALIASES,
 ]);
+/** Factory loops the selected Core can run. Flow -> Spec exists only with
+ *  `deriveChange` (no legacy variant: the graph is Core pieces only). */
 function factoryLoopsForCapabilities(capabilities) {
     if (capabilities?.engineV2 !== 1 || capabilities.workflowDefinitions !== 1)
         return exports.FACTORY_LOOPS;
-    return exports.FACTORY_LOOPS.map(factory => ({ ...factory, graph: (0, loop_core_factory_1.coreFactoryGraph)(factory.id === 'factory:implement' ? 'implement' : factory.id === 'factory:freestyle' ? 'freestyle' : 'quick-sdd', capabilities.implementationSteps === 1, capabilities.workflowAgentSteps === 1, capabilities) }));
+    const loops = exports.FACTORY_LOOPS.map(factory => ({ ...factory, graph: (0, loop_core_factory_1.coreFactoryGraph)(factory.id === 'factory:implement' ? 'implement' : factory.id === 'factory:freestyle' ? 'freestyle' : 'quick-sdd', capabilities.implementationSteps === 1, capabilities.workflowAgentSteps === 1, capabilities) }));
+    return supportsFlowSpec(capabilities) ? [...loops, { ...FLOW_SPEC_FACTORY, graph: (0, loop_flow_spec_recipe_1.flowSpecGraph)() }] : loops;
 }
 function getFactoryLoop(id, capabilities) {
     const legacy = FACTORY_BY_ID.get(id);
@@ -102,6 +126,10 @@ function getFactoryLoop(id, capabilities) {
         return undefined;
     return factoryLoopsForCapabilities(capabilities).find(factory => factory.id === legacy.id);
 }
+/** Canonical id of a factory loop or alias, independent of Core capabilities. */
+function canonicalFactoryLoopId(id) {
+    return FACTORY_BY_ID.get(id)?.id;
+}
 /** True for any `factory:*` loop id. */
 function isFactoryLoopId(id) {
     return typeof id === 'string' && id.startsWith('factory:');

package/server/dist/modules/loops/runtime/loop-flow-spec-recipe.js

@@ -0,0 +1,166 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FLOW_CHANGE_ID_MAX = exports.FLOW_CHANGES_REQUESTED_REASON = exports.FLOW_CHANGES_REQUESTED_END = exports.FLOW_CORRECTION_ROUNDS = exports.FLOW_DERIVATION_REPAIRS = exports.FLOW_SUMMARY_LIMIT_BYTES = exports.FLOW_SUMMARY_FILE = void 0;
+exports.flowChangeIdStem = flowChangeIdStem;
+exports.flowChangeId = flowChangeId;
+exports.flowSpecGraph = flowSpecGraph;
+/**
+ * Flow -> Spec recipe (feedback-2026-10 Flow mode, arch section 4.8). The code
+ * already exists — a Flow worktree the rail adopted — so the run DERIVES the
+ * OpenSpec change instead of planning one, then proves it like Implement:
+ *
+ *   derive-change ─pass→ check (verify) ─pass→ reviewer → review policy ─true→ archive → verify → done
+ *        │fail             │fail                               │false
+ *        └→ one repair     └──────────→ findings ←─────────────┘
+ *           visit                          │
+ *                       correction budget (2 rounds) ─exhausted→ changes-requested
+ *                                          │
+ *                       fixer (developer, fixer stance, WRITE) ─no change→ changes-requested
+ *                                          └→ derive again (the change is updated in place)
+ *
+ * Shape mirrors Core's reference definition
+ * (`src/agent-runtime/engine/__fixtures__/flow-spec.json`): strict OpenSpec
+ * validation and the archive preflight run INSIDE the `derive-change` piece,
+ * so its `fail` outcome is the validation repair loop. Coverage gaps never
+ * fail the piece; they reach the reviewer through `derivation.json`. A
+ * rejected review or failing check is no longer a dead end: a bounded fixer
+ * round repairs the code and tests, and the deriver re-syncs the artifacts
+ * with the code. Only when the rounds are exhausted (or a round changes
+ * nothing) does the run end at `changes-requested`, which Desktop presents as
+ * "the reviewer requested changes" with Back to Flow and Relaunch.
+ *
+ * Desktop data only: the roles (`deriver`, `developer` in the fixer stance,
+ * `reviewer`) and their instructions are Core's. Requires Core capability
+ * `deriveChange: 1`.
+ */
+/** Relative to `.specrails/pipeline/<runId>/`; written by Desktop before launch. */
+exports.FLOW_SUMMARY_FILE = 'flow-summary.md';
+/** Core's bound for the summary file (DERIVE_SUMMARY_LIMIT). */
+exports.FLOW_SUMMARY_LIMIT_BYTES = 32 * 1024;
+/** One repair visit of the deriver after a rejected derivation (reset by every correction round). */
+exports.FLOW_DERIVATION_REPAIRS = 1;
+/** Fixer rounds after a rejected review or a failing check before the run ends at `changes-requested`. */
+exports.FLOW_CORRECTION_ROUNDS = 2;
+/** The terminal of an exhausted (or fruitless) repair loop. */
+exports.FLOW_CHANGES_REQUESTED_END = 'changes-requested';
+/** Its completion reason (Core's reference text; Desktop recognises the end by its node id, not this text). */
+exports.FLOW_CHANGES_REQUESTED_REASON = 'Flow → Spec: the reviewer requested changes that {{run.correctionRounds}} correction round(s) did not resolve. Latest findings: {{run.latestFindings}}';
+/** OpenSpec change names: kebab-case, at most 64 characters (Core's `changeId`). */
+exports.FLOW_CHANGE_ID_MAX = 64;
+const FLOW_CHANGE_ID_FALLBACK = 'flow-change';
+/** Kebab-case stem of a Flow spec title (diacritics folded, ≤64, cut at a word boundary). */
+function flowChangeIdStem(title) {
+    const kebab = (title ?? '').normalize('NFKD').replace(/[\u0300-\u036f]/g, '').toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    if (!kebab)
+        return FLOW_CHANGE_ID_FALLBACK;
+    if (kebab.length <= exports.FLOW_CHANGE_ID_MAX)
+        return kebab;
+    const head = kebab.slice(0, exports.FLOW_CHANGE_ID_MAX);
+    if (kebab[exports.FLOW_CHANGE_ID_MAX] === '-')
+        return head;
+    const cut = head.lastIndexOf('-');
+    return (cut >= 24 ? head.slice(0, cut) : head).replace(/-+$/, '');
+}
+/**
+ * The OpenSpec change a Flow → Spec run derives: named after the spec title,
+ * never after addenda or the run id. A name another change already uses gets
+ * `-2`, `-3`… (within 64 characters).
+ */
+function flowChangeId(title, holder) {
+    const stem = flowChangeIdStem(title);
+    for (let n = 1; n <= 99; n++) {
+        const suffix = n === 1 ? '' : `-${n}`;
+        const id = `${stem.slice(0, exports.FLOW_CHANGE_ID_MAX - suffix.length).replace(/-+$/, '')}${suffix}`;
+        if (holder(id) !== 'taken')
+            return id;
+    }
+    throw new Error(`No free OpenSpec change name for "${stem}"`);
+}
+const REVIEW_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['approved', 'summary', 'issues', 'score'],
+    properties: {
+        approved: { type: 'boolean' },
+        summary: { type: 'string' },
+        issues: { type: 'array', maxItems: 100, items: { type: 'string' } },
+        score: { type: 'number', minimum: 0, maximum: 100 },
+    },
+};
+const FIX_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['summary', 'incomplete'],
+    properties: {
+        summary: { type: 'string' },
+        incomplete: { type: 'array', maxItems: 100, items: { type: 'string' } },
+    },
+};
+function flowSpecGraph() {
+    const change = '{{run.changeId}}';
+    const nodes = [{ id: 'start', type: 'start', position: { x: 0, y: 0 } }];
+    const edges = [];
+    const node = (id, label, kind, params, outcomes, x = 0) => {
+        nodes.push({ id, type: 'core', position: { x, y: nodes.length * 140 }, data: { kind, label, params } });
+        for (const [outcome, target] of Object.entries(outcomes))
+            edges.push({ id: `e-${id}-${outcome}`, source: id, target, label: outcome });
+    };
+    node('init', 'Initialize repair budgets', 'assign', { set: { derivationRepairs: 0, correctionRounds: 0, correctionLimit: exports.FLOW_CORRECTION_ROUNDS, latestFindings: '' } }, { next: 'derive', failed: 'failed' });
+    node('derive', 'Derive OpenSpec change', 'derive-change', { change, summaryPath: exports.FLOW_SUMMARY_FILE, feedback: '{{run.latestFindings}}' }, { pass: 'check', fail: 'repair-guard' });
+    node('repair-guard', 'Repair the derivation once', 'condition', { expr: `$vars.derivationRepairs < ${exports.FLOW_DERIVATION_REPAIRS}` }, { true: 'repair-count', false: 'failed' }, 360);
+    node('repair-count', 'Count derivation repair', 'assign', { increment: { derivationRepairs: 1 } }, { next: 'derive', failed: 'failed' }, 360);
+    node('check', 'Verify derived candidate', 'verify', { commands: 'configured', additionalCommandsFrom: 'derive' }, { pass: 'review', fail: 'check-findings', failed: 'failed' });
+    node('check-findings', 'Capture failing verification', 'assign', { set: { latestFindings: 'Host verification failed for the current candidate: {{outputs.check}}' } }, { next: 'correction-budget', failed: 'failed' }, 720);
+    node('review', 'Reviewer', 'role-turn', {
+        roleId: 'reviewer',
+        prompt: [
+            `Review OpenSpec change ${change}, derived from code that already exists in this worktree (a Flow session built it with the user).`,
+            'Judge whether the derived proposal, design, delta specs and checked tasks describe the real code faithfully: no invented requirements, nothing material left out.',
+            'Derivation coverage measured by Core (every changed file must appear in design.md "## Blast radius"): {{outputs.derive.derivation}}.',
+            'Treat EVERY file in unexplainedFiles as an issue. Inspect the real code and the host verification evidence: {{outputs.check}}.',
+            'Every issue must be actionable by a fixer (code or tests) or by the deriver (artifacts): name the file and what must change.',
+            'Return approved, summary, issues (empty when none) and score (0-100).',
+        ].join(' '),
+        structuredOutput: REVIEW_SCHEMA,
+        sessionContinuity: 'none',
+    }, { next: 'review-policy', invalid: 'failed', failed: 'failed' });
+    node('review-policy', 'Review acceptance policy', 'condition', { expr: '$outputs.review.structured.approved == true' }, { true: 'archive', false: 'review-findings' });
+    node('review-findings', 'Capture review findings', 'assign', { set: { latestFindings: '{{outputs.review.structured}}' } }, { next: 'correction-budget', failed: 'failed' }, 720);
+    node('correction-budget', 'Check the correction budget', 'condition', { expr: '$vars.correctionRounds < $vars.correctionLimit' }, { true: 'begin-correction', false: exports.FLOW_CHANGES_REQUESTED_END }, 720);
+    node('begin-correction', 'Count correction round', 'assign', { increment: { correctionRounds: 1 }, set: { derivationRepairs: 0 } }, { next: 'fix', failed: 'failed' }, 720);
+    node('fix', 'Fixer', 'role-turn', {
+        roleId: 'developer',
+        stance: 'fixer',
+        prompt: [
+            `Correct the code a Flow session built for OpenSpec change ${change} so the review can approve it.`,
+            'Findings to resolve (the reviewer\'s structured verdict, or the failing host verification): {{run.latestFindings}}.',
+            'Fix the defects the findings name. Add or extend the tests the findings ask for; creating a test file is allowed for that.',
+            'Tag every test that demonstrates an ADDED or MODIFIED requirement of the change\'s delta specs with `[spec:<capability>/<requirement-slug>]` in its title.',
+            'Never expand scope: no new features, effects, options or behaviour.',
+            'Do not edit anything under openspec/: Core re-derives proposal, design, specs and tasks from the code after your turn, so a finding about the artifacts needs no code change.',
+            'Revert code only when a finding says the behaviour was unrequested AND contradicts a stated Non-Goal.',
+            'Return summary and incomplete (each finding you could not resolve, with the reason).',
+        ].join(' '),
+        structuredOutput: FIX_SCHEMA,
+        sessionContinuity: 'none',
+    }, { next: 'fix-progress', invalid: 'failed', failed: 'failed' }, 720);
+    node('fix-progress', 'Check the correction changed the candidate', 'condition', { expr: 'exists($outputs.fix.candidateHash) && $outputs.fix.candidateHash != null && $outputs.fix.candidateHash != $outputs.check.candidateHash' }, { true: 'derive', false: exports.FLOW_CHANGES_REQUESTED_END }, 720);
+    node('archive', 'Archive OpenSpec', 'openspec-archive', { change, requiresVerified: true }, { next: 'verify', failed: 'failed' });
+    node('verify', 'Verify archived candidate', 'verify', { commands: 'configured', additionalCommandsFrom: 'derive' }, { pass: 'done', fail: 'failed', failed: 'failed' });
+    nodes.push({ id: 'done', type: 'end', position: { x: 0, y: nodes.length * 140 }, data: { outcome: 'success', requiresVerified: true } }, { id: 'failed', type: 'end', position: { x: 360, y: nodes.length * 140 }, data: { outcome: 'failure' } }, { id: exports.FLOW_CHANGES_REQUESTED_END, type: 'end', position: { x: 720, y: nodes.length * 140 }, data: { outcome: 'failure', reason: exports.FLOW_CHANGES_REQUESTED_REASON } });
+    edges.unshift({ id: 'e-start', source: 'start', target: 'init' });
+    return {
+        nodes,
+        edges,
+        config: {
+            maxIterations: 12,
+            maxTransitions: 100,
+            timeoutMinutes: 0,
+            aiStepTimeoutMinutes: 0,
+            change: 'new',
+            journal: 'ledger-only',
+            reviewerStepId: 'review',
+        },
+    };
+}

package/server/dist/modules/loops/runtime/loop-graph.js

@@ -16,7 +16,7 @@ exports.loopNeedsTicket = loopNeedsTicket;
 exports.interpolateSpec = interpolateSpec;
 exports.CORE_NODE_KINDS = ['prompt', 'role-turn', 'decider', 'condition', 'assign', 'verify', 'shell',
     'artifact-contract', 'openspec-validate', 'openspec-archive', 'approval', 'question', 'gate', 'map', 'join',
-    'component', 'implementation', 'implementation-step', 'end'];
+    'component', 'implementation', 'implementation-step', 'derive-change', 'end'];
 /** Mirror of Core's `getOutcomes(params)`: `verify` advertises `blocked` only when the node opts into host blockers. */
 function effectivePieceOutcomes(descriptor, params) {
     if (descriptor.kind === 'verify' && params?.hostBlockers !== true)

package/server/dist/modules/loops/runtime/loop-role-engines.js

@@ -22,6 +22,9 @@ exports.resolveLoopRoleEngine = resolveLoopRoleEngine;
 //   - `verifier` — every non-core ai-step of the factory loop (verify, fix,
 //     freestyle-less prose steps) and the provider a custom loop's ai-steps run on.
 //   - `decider`  — the Loop Decider (a cheap/fast model is the natural pick).
+//   - `triage`   — spec triage (launch-triage): one structured-output call per
+//     spec. Not a loop step: it is resolved by specs/runtime/triage.ts, whose
+//     default when absent is the primary provider's CHEAPEST priced model.
 // A rail whose engine is `roles` launches WITHOUT a provider override (Core
 // keeps the per-role settings) and resolves the loop steps from this file.
 //
@@ -35,7 +38,7 @@ const workspace_resolution_1 = require("../../../workspace-resolution");
 const provider_selection_1 = require("../../../provider-selection");
 /** The rail engine value meaning "per-role engines, no flattening override". */
 exports.ROLES_ENGINE = 'roles';
-exports.LOOP_ROLES = ['verifier', 'decider'];
+exports.LOOP_ROLES = ['verifier', 'decider', 'triage'];
 class LoopRoleEnginesError extends Error {
 }
 exports.LoopRoleEnginesError = LoopRoleEnginesError;