@cspeach/cli 1.1.23 → 1.1.25

package/dist/agent/loop.js

@@ -37,6 +37,10 @@ import { enrichUserMessage } from '../router/intent-extractor.js';
 import { resetRule8State, shouldGateRule8 } from '../repl/rule8-detector.js';
 import { consumeTodoSetThisTurn } from '../ui/todo-emitter.js';
 import { runSaveCommand, runPromoteCommand, detectArtifactSkill, offerAnswerBlockers } from '../projects/index.js';
+import { planLaneBlockForTurn } from '../projects/plan-lane.js';
+import { clearAppFlow, getAppFlow, setGapConfirmed, startAppFlow } from '../lane/app-flow.js';
+import { afterPlanSave, afterSpecGapSave, cleanSpecToken, extractSpecToken, FLOW_ENDED_LINE, gateAppFlowForTurn, resolveAppSpec, sameRealFile, STEP_1, STEP_3, } from '../lane/app-chain.js';
+import { shownToken } from '../lane/card.js';
 import { parseFromFlag, coerceDocFromFlagToAttachment } from '../skills/promotion-dispatch.js';
 import { input } from '@inquirer/prompts';
 import { withInquirer } from '../repl/inquirer-guard.js';
@@ -312,6 +316,10 @@ export async function maybeOfferSave(p) {
             confirm: isHeadless() ? undefined : inkAwareConfirm,
             log: (...lines) => lines.forEach((l) => p.emit(l)),
             promotedFrom: p.promotedFrom ?? null,
+            // Task 7 review round 2 — the app-flow lane only for the turn routed to
+            // the skill it saves (the /abap-plan turn that got the lane block); a plan
+            // found in another skill's output (detectArtifactSkill) never gets it.
+            ...(p.lane && p.skill === saveSkill ? { lane: p.lane } : {}),
         });
         // After a spec-gap file is saved, let a developer answer the open BLOCKER
         // questions inline (recorded as `answered` items in the SAME file) — the
@@ -328,6 +336,18 @@ export async function maybeOfferSave(p) {
                 log: (...lines) => lines.forEach((l) => p.emit(l)),
             });
         }
+        // App lane routing (Task 7) — the harness-owned /abap-app chain. Built
+        // from the exact saved path, never from model text. Outside an app flow
+        // (spec-gap) or without from.lane (plan) these do nothing. Review round 1:
+        // only when the turn was routed to the skill it saved — an artefact found
+        // in another skill's output (detectArtifactSkill) never moves the chain.
+        if (savedPath && p.appChain && p.skill === saveSkill) {
+            const hooks = { ...p.appChain, headless: isHeadless(), emit: p.emit };
+            if (saveSkill === 'abap-spec-gap')
+                await afterSpecGapSave(hooks, savedPath);
+            else if (saveSkill === 'abap-plan')
+                await afterPlanSave(hooks, savedPath);
+        }
     }
     catch (err) {
         p.emit('\n' + formatAttention({ text: 'Not saved as a project file', fact: String(err?.message ?? err) }).trimEnd());
@@ -444,6 +464,64 @@ export async function runTurn(params) {
     // prepend a "Promoted from..." block to the LLM input, and stash the
     // snapshot for the post-turn save hook so the saved envelope's
     // promotedFrom field is populated.
+    // App lane routing (Task 7) — stage 1 of the /abap-app chain. `/abap-app
+    // @<spec>` (no --from) starts the session's app flow with the cleaned,
+    // workspace-relative spec path and runs as abap-spec-gap, so the spec-gap
+    // skill body does the work. A spec that is missing or outside the workspace
+    // is refused with one line: no flow (a stale one is dropped), and the turn
+    // still runs as spec-gap so the skill can say what is wrong.
+    // I1 (final review) — only an explicit slash command, or a fresh classifier
+    // pick (the session was not already in abap-app), or any turn with no flow
+    // at the lane step (final residual 3), starts stage 1. A plain reply at the
+    // lane step ("ok", "use RAP") falls through to the gate and stays in the flow.
+    if (!readerChild && !params.ctx.subagent && params.skill === 'abap-app' && !parseFromFlag(params.userMessage).fromPath
+        && (params.explicitSlash === true || session.skill !== 'abap-app' || getAppFlow(session)?.expect !== 'lane')) {
+        // I5 — the lane step needs app_lane_resolve (flag-gated: local_build or
+        // standalone). Check the same visible list the turn would send, and
+        // refuse before any model call rather than failing at stage 2.
+        if (!toolsForContext(listTools(), params.ctx).some((t) => t.name === 'app_lane_resolve')) {
+            clearAppFlow(session);
+            const raw = extractSpecToken(params.userMessage);
+            const tok = raw === undefined ? '' : cleanSpecToken(raw);
+            emit(chalk.yellow('/abap-app needs local build tools.'));
+            emit(chalk.yellow('Run: cspeach config set local_build on'));
+            emit(chalk.yellow(`Then restart cspeach and run /abap-app ${shownToken(tok || undefined, 'spec')} again.`));
+            return;
+        }
+        const spec = await resolveAppSpec(params.ctx.cwd, params.userMessage);
+        if (spec.ok) {
+            startAppFlow(session, spec.rel);
+            emit(STEP_1);
+        }
+        else {
+            clearAppFlow(session);
+            emit(chalk.yellow(spec.line));
+        }
+        params = { ...params, skill: 'abap-spec-gap' };
+    }
+    else if (!readerChild && !params.ctx.subagent) {
+        // R11 (review round 1) — any turn that is not part of the flow's current
+        // step ends the flow, so a stale flow never changes a later run.
+        const gate = await gateAppFlowForTurn(session, {
+            skill: params.skill,
+            userMessage: params.userMessage,
+            explicitSlash: params.explicitSlash === true,
+            previousSkill: session.skill,
+            cwd: params.ctx.cwd,
+        });
+        // I4(a) — the flow ends here: say once, plainly, that this plan will not
+        // use the build lane. Interactive only (headless / one-shot keep no flow).
+        if (gate.ended && gate.hadState) {
+            const { isHeadless } = await import('../renderer/tty.js');
+            if (!isHeadless())
+                emit(chalk.yellow(FLOW_ENDED_LINE));
+        }
+    }
+    // Stage 3 — the /abap-plan --from turn of an app flow at its plan step.
+    if (!readerChild && !params.ctx.subagent && params.skill === 'abap-plan' && params.suppressSaveHook !== true
+        && parseFromFlag(params.userMessage).fromPath && getAppFlow(session)?.expect === 'plan') {
+        emit(STEP_3);
+    }
     let promotedFromForSave = null;
     let userMessageForLLM = params.userMessage;
     let userMessageForSave = params.userMessage;
@@ -463,12 +541,23 @@ export async function runTurn(params) {
         }
         const { fromPath, rest } = parseFromFlag(docAttach ? '' : params.userMessage);
         if (fromPath) {
+            // M4 — inside an /abap-app flow the open-items question is asked once:
+            // a yes at stage 2 (lane step) is recorded on the flow, and stage 3
+            // (plan step) skips it when it promotes the same real file.
+            const flowNow = !params.ctx.subagent ? getAppFlow(session) : undefined;
+            const confirmedGap = flowNow?.gapConfirmed;
             const result = await runPromoteCommand({
                 sourcePath: fromPath,
                 targetSkill: params.skill,
                 prompt: inkAwarePrompt,
                 confirm: inkAwareConfirm,
                 log: (...lines) => lines.forEach((l) => emit(l)),
+                // Final residual 4 — the same folder gateAppFlowForTurn resolves @X against.
+                cwd: params.ctx.cwd,
+                ...(flowNow?.expect === 'lane' && params.skill === 'abap-app'
+                    ? { onOpenWarningsConfirmed: (p) => setGapConfirmed(session, p) } : {}),
+                ...(flowNow?.expect === 'plan' && params.skill === 'abap-plan' && confirmedGap
+                    ? { skipOpenWarnings: (p) => sameRealFile(p, confirmedGap) } : {}),
             });
             if (!result) {
                 // User declined, source invalid, or unsupported target — skip the turn.
@@ -519,6 +608,27 @@ ${imageExpansion.error}`));
     if (!readerChild) {
         userMessageForLLM = await expandTextFileAttachments(userMessageForLLM, params.ctx.cwd, (line) => emit(chalk.dim(line)));
     }
+    // App lane routing (Task 6) — the /abap-plan creation turn inside an app
+    // flow gets the confirmed <lane_decision> block (read with the app-flow sha;
+    // a changed file is refused with a plain line). '' on every other turn, so
+    // the model input is unchanged. Resume turns add their own block.
+    if (!readerChild) {
+        const laneBlock = await planLaneBlockForTurn({
+            skill: params.skill,
+            session,
+            cwd: params.ctx.cwd,
+            emit: (line) => emit(chalk.yellow(line)),
+            resumeTurn: params.suppressSaveHook === true,
+        });
+        // M5 — the lane cannot be used: the refusal line is out; end the turn
+        // now (no model call) and end the flow, which cannot reach a saved plan.
+        if (laneBlock === null) {
+            clearAppFlow(session);
+            return;
+        }
+        if (laneBlock)
+            userMessageForLLM = `${userMessageForLLM}\n\n${laneBlock}`;
+    }
     // 2026-05-06: alongside the deterministic prompt-fact extraction
     // (package / transport / etc.), inject the connected SAP system's
     // release + platform + ABAP version. One CVERS query the first time
@@ -1454,6 +1564,18 @@ ${imageExpansion.error}`));
                         model: params.modelOverride ?? resolveModelRole('session_default', cfg) ?? session.model ?? 'unknown',
                         emit,
                         promotedFrom: promotedFromForSave,
+                        ...(() => {
+                            const flowLane = getAppFlow(session)?.lane;
+                            return flowLane ? { lane: { ...flowLane, cwd: params.ctx.cwd } } : {};
+                        })(),
+                        // Task 7 — subagent / reader turns never drive the app chain.
+                        ...(!readerChild && !params.ctx.subagent ? {
+                            appChain: {
+                                session,
+                                cwd: params.ctx.cwd,
+                                ...(params.ctx.pendingDispatch ? { queueNext: (cmd) => params.ctx.pendingDispatch.set(cmd) } : {}),
+                            },
+                        } : {}),
                     });
                 }
             }
@@ -1691,6 +1813,8 @@ ${imageExpansion.error}`));
                     })();
                     const isInteractiveTool = block.name === 'ask_question' ||
                         block.name === 'request_approval' ||
+                        // App lane routing (Task 5): shows the lane card from inside the handler.
+                        block.name === 'app_lane_resolve' ||
                         willTripBatchGate;
                     // Interactive tools block on the USER. PAUSE the turn-status row (don't
                     // just relabel it): a live 250ms tick repaints the dynamic frame and

package/dist/classifier/client.js

@@ -1,7 +1,27 @@
 const RULES = [
+    // abap-app (app lane routing slice 1, 2026-10-01) — building an app FROM a
+    // spec / requirements document. FIRST so a spec-document build beats every
+    // stack-specific rule below (fiori-build, rap, cap, spec-gap, generate). A
+    // direct request without a spec document never matches and keeps its skill.
+    // Review round 1 (I2): a whole-prompt guard keeps "spec gap(s)" prompts on
+    // abap-spec-gap (whitespace only — a hyphenated spec-gap-….json file name
+    // does not trip it).
+    { skill: 'abap-app', patterns: [
+            /^(?![\s\S]*\bspec\s+gaps?\b)[\s\S]*?\b(build|create|make|develop)\b[^.?!\n]{0,60}\b(app|application)\b[^.?!\n]{0,60}(\bspec(s|ification)?\b|\brequirements?\s+(doc|document|file|sheet)\b|\.(docx|pdf|xlsx)\b)/i,
+            /^(?![\s\S]*\bspec\s+gaps?\b)[\s\S]*?(\bspec(s|ification)?\b|\brequirements?\s+(doc|document|file|sheet)\b|\.(docx|pdf|xlsx)\b)[^.?!\n]{0,60}\b(build|create|make|develop)\b[^.?!\n]{0,30}\b(app|application)\b/i,
+        ] },
     { skill: 'abap-atc-fix', patterns: [/atc\s+(fix|auto\s+fix)|abap\s+test\s+cockpit.*fix/i] },
     { skill: 'abap-cca', patterns: [/custom\s+code\s+analysis|\bcca\b|clean\s+core\s+(assessment|analysis)/i] },
     { skill: 'abap-cloud-check', patterns: [/cloud\s+ready|clean\s+core(?!\s+(assessment|analysis))|s\/4hana\s+cloud\s+check/i] },
+    // abap-cap (2026-10-01) MUST precede abap-data-model ("CDS domain model"
+    // would hit its bare `domain`) and abap-fiori-build / abap-rap (a CAP app
+    // ships a Fiori Elements UI). Side-by-side / BTP framing → CAP.
+    // Review round 1 (I1): narrowed so no prompt that routed before abap-cap
+    // existed changes skill — "a cap on the quantity", "RAP/Fiori on BTP",
+    // "BTP destination in ZCL_X", "the CDS model ZI_X", "side by side" diffs.
+    // A bare BTP mention counts only when no RAP/ABAP/Fiori/UI5/Z-object word
+    // appears anywhere in the prompt.
+    { skill: 'abap-cap', patterns: [/\b(sap\s+)?cap\b(?=\s+(app|application|project|service|model|backend|extension|handler)s?\b)|\b(in|with|using|use)\s+(sap\s+)?cap\b|cloud\s+application\s+programming|\bcds\s+(model|service)\b(?!\s+(definition|[zy]\w*))|side.?by.?side\s+(app|application|extension)|^(?![\s\S]*\b(rap|abap|fiori|ui5|[zy]\w*_\w+)\b)[\s\S]*\bbtp\b/i] },
     { skill: 'abap-data-model', patterns: [/data\s+model|ddic\s+(design|structure)|domain|data\s+element|create\s+(a\s+)?z[_\w]*\s+(table|structure)|new\s+(z[_\w]*\s+)?(table|structure|domain)/i] },
     { skill: 'abap-design', patterns: [/solution\s+architecture|object\s+list|design\s+the\s+solution/i] },
     { skill: 'abap-handover', patterns: [/technical\s+documentation|object\s+catalog|doc(ument)?\s+package|handover/i] },
@@ -61,12 +81,17 @@ const RULES = [
     { skill: 'abap-transport-analysis', patterns: [/transport\s+analysis|pre.release\s+transport|transport\s+readiness/i] },
     { skill: 'abap-transport', patterns: [/transport\s+(create|release|list)|\bcts\b|release.*request/i] },
 ];
-if (RULES.length !== 33) {
+/** The skill each offline rule routes to, in rule order (one rule per skill). */
+export const RULE_SKILLS = Object.freeze(RULES.map((r) => r.skill));
+// 2026-10-01: 33 + abap-app + abap-cap = 35. The four merged-away donors
+// (abap-cloud-check, abap-document, abap-performance, abap-radar) keep their
+// rules: their .claude/skills folders are still on disk and still resolve.
+if (RULES.length !== 35) {
     // Warn-not-throw — managed-mode users never exercise classify() (the proxy
     // does server-side classification), so a module-load crash would break
     // them for a local-only consistency check. Unit tests assert the exact
     // count.
-    console.warn(`[classifier] RULES drift: expected 33, got ${RULES.length} — reconcile with .claude/skills/`);
+    console.warn(`[classifier] RULES drift: expected 35, got ${RULES.length} — reconcile with .claude/skills/`);
 }
 export function classify(prompt) {
     for (const rule of RULES) {

package/dist/commands/plan-continue.js

@@ -16,6 +16,7 @@ import { findNewestVersion } from './plan-resume.js';
 import { collectTurnAssistantText } from '../agent/turn-assistant-text.js';
 import { finishPlanResume } from './plan-resume.js';
 import { runPostPhaseChain } from './plan-chain.js';
+import { loadPlanLaneForRun } from '../projects/plan-lane.js';
 /**
  * The same block shape loop.ts's manifest-on-interrupt hook scans for.
  * E2 dual-read: accept both the legacy `csforge:` and current `cspeach:` prefixes.
@@ -76,7 +77,7 @@ export function classifyContinuationText(text, envelopeTitle) {
  * never leaves a fresh lock behind. Every null return means "run a normal
  * turn"; `stale` additionally tells the caller to clear the marker.
  */
-export function preparePlanContinuation(args) {
+export async function preparePlanContinuation(args) {
     const { marker } = args;
     let path = marker.path;
     if (!existsSync(path))
@@ -99,6 +100,14 @@ export function preparePlanContinuation(args) {
     const phase = parsed.content.phases.find((p) => p.id === marker.phaseId);
     if (!phase)
         return { prepared: null, stale: true };
+    // App lane routing — same gate as preparePlanResume: pinned read, record
+    // re-validation, stored phases checked against the lane. Before the lease,
+    // so a paused plan never leaves a lock behind. Lane-less plans pass.
+    const laneGate = await loadPlanLaneForRun(args.cwd ?? process.cwd(), parsed.content);
+    if (!laneGate.ok) {
+        args.log(...laneGate.lines);
+        return { prepared: null, stale: false, paused: true };
+    }
     // Lease LAST: a stale marker (missing file / unknown phase) must never leave
     // a fresh lock behind. A LIVE other-session holder is contention, NOT stale —
     // the marker stays so the user can finish there or take over via --resume.
@@ -122,6 +131,7 @@ export function preparePlanContinuation(args) {
         ...(marker.effectiveMode ? { effectiveMode: marker.effectiveMode } : {}),
         ...(marker.auditFlag ? { auditFlag: marker.auditFlag } : {}),
         ...(marker.auditMode ? { auditMode: marker.auditMode } : {}),
+        ...(laneGate.rec ? { laneRecord: laneGate.rec } : {}),
     };
     return { prepared };
 }

package/dist/commands/plan-resume.js

@@ -54,6 +54,7 @@ import { FLOORPLAN_TO_TEMPLATE } from '../tools/fiori/floorplan-map.js';
 import { getCurrentTransport, setCurrentTransport } from '../repl/current-transport.js';
 import { askYesNo, isYes } from '../projects/yes-no.js';
 import { formatAttention, formatInfo } from '../renderer/notice-shape.js';
+import { checkLaneConsistency, loadPlanLaneForRun, renderLaneBlock } from '../projects/plan-lane.js';
 /**
  * Parse and STRIP the per-run chaining-mode (`--guarded` / `--step`) and
  * audit off-switch (`--audit` / `--no-audit`) flags from a plan-resume body.
@@ -227,6 +228,19 @@ export async function preparePlanResume(args) {
         return null;
     }
     let content = pc.content;
+    // App lane routing (Task 6, Review Focus 3) — a plan made for a lane reads
+    // the decision file with the sha it recorded, BEFORE anything else happens
+    // (no transport adoption, no lease, no phase). A changed or missing file
+    // pauses the plan; the edited lane is never used. Plans without from.lane
+    // skip this entirely.
+    // R5 fix round: the stored phases must also fit the lane, checked here
+    // before any phase, lease or transport work.
+    const laneGate = await loadPlanLaneForRun(args.cwd, content);
+    if (!laneGate.ok) {
+        args.log(...laneGate.lines);
+        return null;
+    }
+    const laneRecord = laneGate.rec;
     // Transport display on resume (2026-07-09) — adopt the plan's dedicated
     // transport into the session so the `tr <TRKORR>` status segment shows it.
     // A fresh process resuming mid-plan runs no sap_transport_create (the
@@ -400,6 +414,7 @@ export async function preparePlanResume(args) {
             auditMode: effectiveAudit,
             reauditPhaseId,
             reauditPhaseIds,
+            ...(laneRecord ? { laneRecord } : {}),
         };
     }
     if (!next) {
@@ -449,7 +464,13 @@ export async function preparePlanResume(args) {
             ruleBlocks.push(`<rule file="${rel}" missing="true"/>  <!-- not found locally — apply built-in Forge defaults -->`);
         }
     }
-    const planState = JSON.stringify({ title: envelope.title, version: envelope.version, statuses, content }, null, 2);
+    // App lane routing (Task 6): the lane ref is CLI-owned — the model sees the
+    // <lane_decision> block below, never the decision file path. A lane-less
+    // plan passes `content` itself (byte-identical plan_state).
+    const stateContent = content.from.lane
+        ? { ...content, from: (({ lane: _lane, ...rest }) => rest)(content.from) }
+        : content;
+    const planState = JSON.stringify({ title: envelope.title, version: envelope.version, statuses, content: stateContent }, null, 2);
     // A2 (defects D23/D30) — compact write-back: the model re-emitting the
     // full plan content every phase cost ~6–10k output tokens/phase at Opus
     // pricing for data the envelope already holds. The resume turn emits
@@ -502,6 +523,9 @@ export async function preparePlanResume(args) {
         ...ruleBlocks,
         '</phase_rules>',
         '',
+        // App lane routing (Task 6): the lane decision, so design and build phases
+        // stay in the lane. Absent ⇒ nothing added (byte-identical prompt).
+        ...(laneRecord ? [renderLaneBlock(laneRecord), ''] : []),
         // A1 (2026-06-10, defect D23): the old contract let the model ask a
         // continuation question and keep executing phases in-turn — a 6-phase
         // run snowballed to a 3.24M-token context because the turn never
@@ -531,6 +555,7 @@ export async function preparePlanResume(args) {
         nextPhaseWrites: phaseWrites(next),
         llmPrompt, mode: flags.mode, effectiveMode,
         auditFlag: flags.audit, auditMode: effectiveAudit,
+        ...(laneRecord ? { laneRecord } : {}),
     };
 }
 /**
@@ -729,6 +754,18 @@ export async function finishPlanResume(args) {
         args.log(`[plan] re-run: /abap-plan --resume @${basename(args.prepared.path)}`);
         return null;
     }
+    // App lane routing (Task 6, Review Focus 4) — the write-back may restructure
+    // the plan (full shape) or overlay a phase; it must still fit the lane.
+    if (args.prepared.laneRecord) {
+        const conflict = checkLaneConsistency(extract.content, args.prepared.laneRecord);
+        if (conflict) {
+            args.log('');
+            args.log(`[plan] PHASE RESULT NOT PERSISTED — ${conflict}`);
+            args.log('[plan] The plan envelope is unchanged. Check what the phase actually built, then');
+            args.log(`[plan] re-run: /abap-plan --resume @${basename(args.prepared.path)}`);
+            return null;
+        }
+    }
     const nowIso = new Date().toISOString();
     const statuses = extract.statuses;
     const executedId = args.prepared.nextPhaseId;

package/dist/lane/app-chain.js

@@ -0,0 +1,297 @@
+// App lane routing slice 1, Task 7 — the harness-owned /abap-app chain.
+//
+//   stage 1  /abap-app @<spec>            → runs as abap-spec-gap
+//   stage 2  /abap-app --from @<specgap>  → lane card (app_lane_resolve, Task 5)
+//   stage 3  /abap-plan --from @<specgap> → plan with the lane block (Task 6)
+//   start    Yes → /abap-plan --resume @<saved plan> --guarded
+//
+// Every command queued here is built by CLI code from a path the CLI itself
+// produced (the saved spec-gap / plan envelope). Model text never reaches a
+// queued command. Headless (M2, what is true): no card is ever shown and no
+// build starts — the start command is printed, never queued. The lane tool
+// (app_lane_resolve) still queues the plan step (/abap-plan --from …) when
+// the rules decide the lane; after a headless spec-gap save the CLI says to
+// run /abap-app in an interactive session (no flow survives the process).
+import { promises as fs, statSync } from 'node:fs';
+import path from 'node:path';
+import { readProjectFile } from '../projects/status.js';
+import { parsePlanContent } from '../projects/plan-schema.js';
+import { buildResumeCommand } from '../commands/plan-resume.js';
+import { canonicalLanePath } from './paths.js';
+import { cardLine, interactiveRunLine, shownToken } from './card.js';
+import { clearAppFlow, getAppFlow, setSpecGap } from './app-flow.js';
+import { chainFromToken } from './chain-token.js';
+import { containSpecPath, specDisplayPath, SpecProtectedError } from './roots.js';
+import { resolveAtTokenAsync } from '../projects/workspace.js';
+import { parseFromFlag } from '../skills/promotion-dispatch.js';
+export const STEP_1 = 'Step 1 of 3: finding the gaps in the spec.';
+export const STEP_2 = 'Step 2 of 3: choosing the build lane.';
+export const STEP_3 = 'Step 3 of 3: planning the build.';
+export const START_QUESTION = 'Start building now? It runs every phase and stops only for your answers, SAP approvals or a failed check.';
+/** Trailing characters a sentence puts after a token: `see @spec.md.` / `(@spec.md)`. */
+const TRAILING_PUNCT = /[.,;:!?)\]}>]+$/;
+/**
+ * The first `@<token>` of a /abap-app message, as typed. `@"a b.docx"` and
+ * `@'a b.docx'` keep their inner spaces. Undefined when there is none.
+ */
+export function extractSpecToken(message) {
+    const m = /(?:^|\s)@(?:"([^"\r\n]+)"|'([^'\r\n]+)'|(\S+))/.exec(message);
+    if (!m)
+        return undefined;
+    return m[1] ?? m[2] ?? m[3];
+}
+/**
+ * Clean a spec token: no leading `@`, no surrounding quotes, no trailing
+ * sentence punctuation (a file name never ends in `.`, `,` or `)`).
+ */
+export function cleanSpecToken(raw) {
+    let t = raw.trim();
+    // Punctuation can sit outside the quotes (`@"a b.md".`), so strip, unquote, strip.
+    for (let i = 0; i < 2; i++) {
+        t = t.replace(/^@/, '').replace(TRAILING_PUNCT, '');
+        const q = /^(["'])([\s\S]*)\1$/.exec(t);
+        if (q)
+            t = q[2];
+        t = t.trim();
+    }
+    return t;
+}
+const NOT_STARTED = 'The app flow did not start.';
+/**
+ * Resolve the /abap-app spec token to a stable path (forward slashes):
+ * cwd-relative inside cwd, absolute for a spec in the workspace folder outside
+ * cwd. The token is looked up with resolveAtTokenAsync — the same lookup the
+ * @-attachment expansion uses — so the pinned spec and the analysed spec are
+ * the same file. Refused, with one plain line, when the message names no
+ * file, the name is ambiguous, the file leaves cwd and the workspace folder
+ * (also through a link), sits in a protected place, or does not exist. The
+ * stored value is what app_lane_resolve's `sameFile` compares, and that check
+ * (like readSpecText) uses the same containment (lane/roots.ts).
+ */
+export async function resolveAppSpec(cwd, message) {
+    const raw = extractSpecToken(message);
+    const tok = raw === undefined ? '' : cleanSpecToken(raw);
+    // M3 — the plain example, then the usual 'did not start' sentence.
+    if (tok === '')
+        return { ok: false, line: `Name the spec file with @, for example: /abap-app @specs/my-app.docx\n${NOT_STARTED}` };
+    const shown = cardLine(tok);
+    const outside = { ok: false, line: `The spec file must be inside this folder or the workspace folder: ${shown}. ${NOT_STARTED}` };
+    const missing = { ok: false, line: `Spec file not found: ${shown}. ${NOT_STARTED}` };
+    if (tok.includes('\0'))
+        return outside;
+    let found;
+    try {
+        const r = await resolveAtTokenAsync(tok, cwd);
+        if (r.kind === 'notFound')
+            return missing;
+        if (r.kind === 'ambiguous') {
+            return { ok: false, line: `More than one file matches ${shown}. Use the full name. ${NOT_STARTED}` };
+        }
+        found = r.path;
+    }
+    catch {
+        return missing;
+    }
+    // I3 — inside cwd OR the workspace folder, string + realpath contained,
+    // denylist kept (the same rule app_lane_resolve applies to the spec).
+    let abs;
+    let real;
+    try {
+        ({ abs, real } = await containSpecPath(cwd, path.resolve(cwd, found)));
+    }
+    catch (e) {
+        if (e instanceof SpecProtectedError) {
+            return { ok: false, line: `The spec file is in a protected folder and cannot be read: ${shown}. ${NOT_STARTED}` };
+        }
+        return e?.code === 'ENOENT' ? missing : outside;
+    }
+    let isFile = false;
+    try {
+        isFile = statSync(real).isFile();
+    }
+    catch {
+        isFile = false;
+    }
+    if (!isFile)
+        return missing;
+    return { ok: true, rel: specDisplayPath(cwd, abs) };
+}
+/** The skill that runs each chain step. */
+const STEP_SKILL = { 'spec-gap': 'abap-spec-gap', lane: 'abap-app', plan: 'abap-plan' };
+const norm = (s) => s.trim().replace(/\s+/g, ' ');
+/** Shown once when a turn ends a flow that already has a spec-gap file or a lane (interactive only). */
+export const FLOW_ENDED_LINE = 'The /abap-app run ended here; this plan will not use the build lane. Run /abap-app again to use it.';
+/** Real path, case-folded on Windows. Undefined when the file cannot be resolved. */
+async function realKey(p) {
+    try {
+        const r = path.resolve(await fs.realpath(p));
+        return process.platform === 'win32' ? r.toLowerCase() : r;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** True when both paths name the same existing real file (realpath compare, never strings). */
+export async function sameRealFile(a, b) {
+    const [x, y] = await Promise.all([realKey(a), realKey(b)]);
+    return x !== undefined && x === y;
+}
+/**
+ * I4(b) — true when a typed `--from @X` resolves (same lookup as the promote
+ * flow) to the flow's own spec-gap file. Paths are compared after realpath,
+ * never as strings.
+ */
+async function fromNamesFlowGap(cwd, userMessage, specGapPath) {
+    if (!specGapPath)
+        return false;
+    const { fromPath } = parseFromFlag(userMessage);
+    if (!fromPath)
+        return false;
+    let found;
+    try {
+        const r = await resolveAtTokenAsync(fromPath, cwd);
+        if (r.kind !== 'path')
+            return false;
+        found = path.resolve(cwd, r.path);
+    }
+    catch {
+        return false;
+    }
+    const [a, b] = await Promise.all([realKey(found), realKey(specGapPath)]);
+    return a !== undefined && a === b;
+}
+/**
+ * R11 — runs at the top of every top-level turn except the stage-1 turn (which
+ * restarts the flow). The flow survives only a turn that is part of its
+ * current step:
+ * - the exact command the CLI queued (or printed) for this step; or
+ * - I4(b): the step's own `--from` command typed by hand, when its `@X`
+ *   resolves (realpath) to the flow's spec-gap file —
+ *   `/abap-app --from @X` at the lane step, `/abap-plan --from @X` at the
+ *   plan step; or
+ * - a plain reply (not a slash command) while the session is already in the
+ *   step's skill and the reply is routed to it.
+ * Any other turn — another slash command, a reply routed elsewhere — ends it.
+ */
+export async function gateAppFlowForTurn(session, t) {
+    const flow = getAppFlow(session);
+    if (!flow)
+        return { ended: false, hadState: false };
+    const stepSkill = STEP_SKILL[flow.expect];
+    if (t.explicitSlash) {
+        if (flow.queued !== undefined && norm(`/${t.skill} ${t.userMessage}`) === norm(flow.queued)) {
+            return { ended: false, hadState: false };
+        }
+        if ((flow.expect === 'lane' || flow.expect === 'plan') && t.skill === stepSkill
+            && await fromNamesFlowGap(t.cwd, t.userMessage, flow.specGapPath)) {
+            return { ended: false, hadState: false };
+        }
+    }
+    else if (t.skill === stepSkill && t.previousSkill === stepSkill) {
+        return { ended: false, hadState: false };
+    }
+    clearAppFlow(session);
+    return { ended: true, hadState: flow.specGapPath !== undefined || flow.lane !== undefined };
+}
+/** The plan start command, built from the exact saved path (the offerNextPhaseAutoRun rule). */
+export function startCommand(savedPlanPath) {
+    if (!/^[A-Za-z0-9._-]+$/.test(path.basename(savedPlanPath)))
+        return undefined;
+    return `${buildResumeCommand(savedPlanPath)} --guarded`;
+}
+/** The saved plan's `from.lane`, or undefined (not a plan, unreadable, no lane). */
+export function savedPlanLane(savedPath) {
+    try {
+        const env = readProjectFile(savedPath);
+        if (env.artefactType !== 'plan')
+            return undefined;
+        const pc = parsePlanContent(env.content);
+        return pc.ok ? pc.content.from.lane : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * After a spec-gap save inside an app flow that is at its spec-gap step:
+ * record the saved path and queue stage 2. Runs once per flow (R11): a later
+ * spec-gap save, or no app flow, does nothing (no line, no queue).
+ */
+export async function afterSpecGapSave(h, savedPath) {
+    const flow = getAppFlow(h.session);
+    if (!flow || flow.expect !== 'spec-gap' || flow.specGapPath !== undefined)
+        return;
+    const t = await chainFromToken(h.cwd, savedPath);
+    if (h.headless) {
+        // I4(c) — no flow survives a headless / one-shot run: point at the
+        // interactive chain instead of a command that would run without its flow.
+        if (t)
+            setSpecGap(h.session, savedPath, `/abap-app --from ${t.token}`);
+        else
+            clearAppFlow(h.session);
+        h.emit(interactiveRunLine(flow.specToken));
+        return;
+    }
+    if (!t) {
+        // I4(b)/(c) — the flow stays at the lane step with nothing queued: the
+        // user's own `/abap-app --from @<file>` keeps it (the gate compares real paths).
+        setSpecGap(h.session, savedPath);
+        h.emit(`The saved spec-gap file cannot be queued as a command. To go on, run: /abap-app --from ${shownToken(path.basename(savedPath), 'spec-gap file')}`);
+        return;
+    }
+    const cmd = `/abap-app --from ${t.token}`;
+    setSpecGap(h.session, savedPath, cmd);
+    if (!h.queueNext) {
+        h.emit(`Next: ${cmd}`);
+        return;
+    }
+    h.queueNext(cmd);
+    h.emit(STEP_2);
+}
+/**
+ * After a plan save: when the saved plan carries `from.lane`, offer to start
+ * the guarded run. Inside an active app flow the flow's lane must be the
+ * plan's lane. A plan without `from.lane` → nothing.
+ */
+export async function afterPlanSave(h, savedPath) {
+    const lane = savedPlanLane(savedPath);
+    if (!lane)
+        return;
+    const flow = getAppFlow(h.session);
+    if (flow && (flow.expect !== 'plan' || !flow.lane
+        || canonicalLanePath(flow.lane.path) !== canonicalLanePath(lane.path) || flow.lane.sha256 !== lane.sha256)) {
+        return;
+    }
+    const end = () => { if (flow)
+        clearAppFlow(h.session); };
+    const cmd = startCommand(savedPath);
+    if (!cmd) {
+        h.emit('The plan file name cannot be used in a command. Run /abap-plan --resume @<plan file> --guarded yourself.');
+        end();
+        return;
+    }
+    if (h.headless || !h.queueNext) {
+        h.emit(`Start building with: ${cmd}`);
+        end();
+        return;
+    }
+    const confirm = h.confirm ?? (async (req) => {
+        const { askConfirm } = await import('../ui/confirm-request.js');
+        return askConfirm(req);
+    });
+    const res = await confirm({
+        id: 'app-start-build',
+        tag: 'QUESTION',
+        title: START_QUESTION,
+        choices: [{ value: 'yes', label: 'Yes' }, { value: 'no', label: 'No' }],
+        initial: 0,
+        aliases: { y: 'yes', n: 'no' },
+    });
+    if (res.value === 'yes' && !res.cancelled) {
+        h.queueNext(cmd);
+    }
+    else {
+        h.emit(`Start it later with: ${cmd}`);
+    }
+    end();
+}