@cspeach/cli 1.0.0 → 1.1.1

package/dist/commands/plan-continue.js

@@ -0,0 +1,179 @@
+// src/commands/plan-continue.ts
+// C1 mid-phase-continue (2026-07-14) — re-attach a router-dispatched bare
+// "continue" turn to the post-phase chain (audit + next-phase offer) via the
+// persisted session.plan_in_flight marker. Design + seam analysis:
+// .superpowers/sdd/midphase-continue-report.md §4 (approved). ALL continuation
+// logic lives here so the repl.tsx wiring stays thin and mirror-safe; the
+// existing repl seam pins (finishPlanResume ×4, runPostPhaseChain ×2) hold
+// because this module — not repl.tsx — calls those functions.
+import { basename } from 'node:path';
+import { existsSync } from 'node:fs';
+import { leasePathFor, acquireRunLease } from '../projects/run-lease.js';
+import { readProjectFile } from '../projects/status.js';
+import { parsePlanContent, phaseWrites } from '../projects/plan-schema.js';
+import { statusesFromItems } from '../projects/plan-run.js';
+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';
+/**
+ * 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.
+ */
+const MANIFEST_BLOCK_RE = /<!--\s*(?:csforge|cspeach):plan-manifest\s*\n([\s\S]*?)\n\s*-->/g;
+/**
+ * Build the marker from the prepared resume the phase turn is about to run.
+ * `family` mirrors leasePathFor's family-base convention (version suffix
+ * stripped) — display/diagnostic identity, the lease itself re-derives it.
+ */
+export function buildPlanInFlight(prepared, attemptStartedAt) {
+    const family = basename(leasePathFor(prepared.path)).replace(/\.cspeach\.lock$/, '');
+    return {
+        path: prepared.path,
+        family,
+        phaseId: prepared.nextPhaseId,
+        attemptStartedAt,
+        ...(prepared.mode ? { mode: prepared.mode } : {}),
+        ...(prepared.effectiveMode ? { effectiveMode: prepared.effectiveMode } : {}),
+        ...(prepared.auditFlag ? { auditFlag: prepared.auditFlag } : {}),
+        ...(prepared.auditMode ? { auditMode: prepared.auditMode } : {}),
+    };
+}
+/**
+ * Foreign-manifest guard. Every plan manifest (full AND compact) carries a
+ * `title`; a differing title means the turn produced a NEW plan, not this
+ * continuation — the caller must NOT attach it to the in-flight phase (it
+ * runs the generic save instead so the artifact isn't lost).
+ * - 'none'  — no manifest block: phase still in flight, nothing to persist.
+ * - 'match' — attach: same title, titleless compact manifest, or unparseable
+ *             JSON (finishPlanResume owns loud extract failures).
+ * - 'foreign' — a different plan's manifest.
+ * The LAST block wins, matching collectTurnAssistantText/extractPlan reading
+ * the final manifest of a turn.
+ */
+export function classifyContinuationText(text, envelopeTitle) {
+    const blocks = [...text.matchAll(MANIFEST_BLOCK_RE)];
+    if (blocks.length === 0)
+        return 'none';
+    const raw = blocks[blocks.length - 1][1];
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.title === 'string' && parsed.title.trim().length > 0
+            && envelopeTitle.trim().length > 0 && parsed.title.trim() !== envelopeTitle.trim()) {
+            return 'foreign';
+        }
+    }
+    catch {
+        // Unparseable → 'match': hand it to finishPlanResume, whose extract
+        // failure path reports PHASE RESULT NOT PERSISTED loudly.
+    }
+    return 'match';
+}
+/**
+ * Resolve the in-flight marker to a live plan + phase and re-acquire the
+ * family lease (it was released when the interrupted turn ended). Order
+ * matters: file + phase are validated BEFORE the lease so a stale marker
+ * 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) {
+    const { marker } = args;
+    let path = marker.path;
+    if (!existsSync(path))
+        return { prepared: null, stale: true };
+    let envelope;
+    try {
+        envelope = readProjectFile(path);
+    }
+    catch {
+        return { prepared: null, stale: true };
+    }
+    // The marker may predate later phase-save rotations — same newest-version
+    // redirect preparePlanResume performs after its @token resolution.
+    const newer = findNewestVersion(path, envelope);
+    if (newer)
+        ({ path, envelope } = newer);
+    const parsed = parsePlanContent(envelope.content);
+    if (!parsed.ok)
+        return { prepared: null, stale: true };
+    const phase = parsed.content.phases.find((p) => p.id === marker.phaseId);
+    if (!phase)
+        return { prepared: null, stale: 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.
+    const lease = acquireRunLease(path, args.sessionId, { log: (l) => args.log(l) });
+    if (!lease.acquired) {
+        const holder = lease.holder;
+        args.log(`[plan] in-flight phase ${marker.phaseId} not re-attached — another session holds the run lease`
+            + (holder ? ` (session ${holder.sessionId}, pid ${holder.pid})` : '')
+            + '. Finish there or /abap-plan --resume here to take over.');
+        return { prepared: null, stale: false };
+    }
+    const prepared = {
+        path,
+        envelope,
+        statuses: statusesFromItems(envelope.interaction.items, parsed.content.phases),
+        nextPhaseId: marker.phaseId,
+        nextDelegateTo: phase.delegateTo,
+        nextPhaseWrites: phaseWrites(phase),
+        llmPrompt: '',
+        ...(marker.mode ? { mode: marker.mode } : {}),
+        ...(marker.effectiveMode ? { effectiveMode: marker.effectiveMode } : {}),
+        ...(marker.auditFlag ? { auditFlag: marker.auditFlag } : {}),
+        ...(marker.auditMode ? { auditMode: marker.auditMode } : {}),
+    };
+    return { prepared };
+}
+/**
+ * The continuation counterpart of the repl's finishPlanResume call sites:
+ * classify the turn text first (foreign-manifest guard), then reuse
+ * finishPlanResume verbatim — pending-audit injection, revision build,
+ * validation, handover projection all behave exactly as on a --resume turn.
+ * attemptStartedAt comes from the MARKER (the original phase turn), so the
+ * audit evidence window spans the interrupt.
+ */
+export async function finishPlanContinuation(args) {
+    const text = args.textOverride ?? collectTurnAssistantText(args.messages, args.messagesStart);
+    const cls = classifyContinuationText(text, args.prepared.envelope.title);
+    if (cls === 'none')
+        return { kind: 'none' };
+    if (cls === 'foreign') {
+        args.log(`[plan] this turn's manifest belongs to a different plan — NOT attached to in-flight phase ${args.marker.phaseId}.`);
+        return { kind: 'foreign' };
+    }
+    const outcome = await finishPlanResume({
+        prepared: args.prepared,
+        messages: args.messages,
+        messagesStart: args.messagesStart,
+        sessionId: args.sessionId,
+        attemptStartedAt: args.marker.attemptStartedAt,
+        auditMode: args.prepared.auditMode,
+        log: args.log,
+        ...(args.textOverride !== undefined ? { textOverride: args.textOverride } : {}),
+    });
+    return outcome ? { kind: 'saved', outcome } : { kind: 'not-persisted' };
+}
+/**
+ * The continuation counterpart of the repl's runPostPhaseChain call sites —
+ * executedPhaseId comes from the marker, run semantics (mode/audit flags)
+ * from the prepared object the marker rebuilt. Kept HERE so repl.tsx's
+ * runPostPhaseChain call-site count (structural seam pin ×2) is unchanged.
+ */
+export async function runContinuationChain(args) {
+    await runPostPhaseChain({
+        savedPath: args.outcome.savedPath,
+        executedPhaseId: args.marker.phaseId,
+        sessionId: args.sessionId,
+        cwd: args.cwd,
+        mode: args.prepared.effectiveMode ?? 'step',
+        modeFlag: args.prepared.mode,
+        auditMode: args.prepared.auditMode,
+        auditFlag: args.prepared.auditFlag,
+        attemptStartedAt: args.marker.attemptStartedAt,
+        subagentDispatches: args.subagentDispatches,
+        prompt: args.prompt,
+        queueDispatch: args.queueDispatch,
+        log: args.log,
+    });
+}

package/dist/commands/plan-gate.js

@@ -0,0 +1,154 @@
+// cspeach-cli/src/commands/plan-gate.ts
+//
+// Guarded phase-chaining gate (2026-07-03 agentic-flow design) — the PURE
+// decision of what happens between two plan phases. No fs, no config, no
+// I/O: the effective mode (config default, overridden by per-run
+// --guarded/--step flags — see parsePlanResumeFlags in plan-resume.ts)
+// arrives as an argument, and the caller (Task 6 wiring in the REPL's
+// offerNextPhase path) renders the returned decision.
+//
+// Semantics (binding, from the design doc):
+//   step    ⇒ always `prompt` — today's behaviour, one consent per phase.
+//   guarded ⇒ `stop`  when the PREVIOUS phase's audit is unresolved
+//                     ('audit-infra' for infra_failed, else 'audit-failed');
+//             `prompt` with 'write-phase' when the NEXT phase writes to SAP
+//                     (phaseWrites is fail-safe: undeclared ⇒ writes). This
+//                     prompt IS the stop — consent to RUN the phase; it does
+//                     NOT pre-approve the writes inside it;
+//             `auto`  otherwise (declared non-write phase, clean prior audit).
+//
+// Precedence: the audit stop wins over the write-phase prompt when both
+// apply — a hard stop must never be downgraded to a consent prompt.
+// Legacy envelopes (phases with no audit field) never stop the chain:
+// isAuditResolved(undefined) === true.
+import { phaseWrites } from '../projects/plan-schema.js';
+import { isAuditResolved } from '../projects/plan-run.js';
+/* ── guarded-run auto_approve override (Task 6, 2026-07-03) ────────────────
+ * Module-level flag consulted by tools/approval.ts BEFORE its auto-approve
+ * branch. The REPL sets it at guarded-chain start (right before the phase's
+ * runTurn) and clears it in a finally — so during a guarded auto-chained
+ * phase, every request_approval falls through to the interactive prompt even
+ * when the user's config says auto_approve. Rationale: auto_approve was
+ * consented for hand-driven turns; an auto-dispatched chain must not inherit
+ * that consent. When the flag is off, approval.ts behaviour is byte-identical
+ * (skill-mode compatibility). */
+let guardedRunActive = false;
+export function setGuardedRunActive(active) {
+    guardedRunActive = active;
+}
+export function isGuardedRunActive() {
+    return guardedRunActive;
+}
+/* ── plan-phase read-only enforcement (Task 7, 2026-07-03) ─────────────────
+ * Module-level flag consulted by tools/subagent/agent_run.ts. The REPL sets
+ * it around EVERY plan-resume phase turn (guarded AND step — unlike the
+ * guarded flag above) and clears it in the same finally — so any subagent
+ * dispatched from inside a plan phase is FORCED onto the read-only tool
+ * filter regardless of the model's `read_only` arg. Governance rule: inside
+ * plan phases, subagents can read, never write — the model cannot opt out.
+ * When the flag is off, agent_run's opt-in read_only behaviour is
+ * byte-identical (skill-mode compatibility). */
+let planPhaseActive = false;
+export function setPlanPhaseActive(active) {
+    planPhaseActive = active;
+}
+export function isPlanPhaseActive() {
+    return planPhaseActive;
+}
+/* Task 7 — per-phase subagent dispatch counter. agent_run increments it on
+ * every dispatch made while a plan phase is active; the REPL reads it
+ * (read+reset) in the runTurn finally that clears the plan-phase flag and
+ * threads the value to runPostPhaseChain, so the phase-end report can name
+ * how many subagents the phase used (fix-wave: consuming it in the chain
+ * alone leaked counts when the chain was skipped on error paths — the
+ * chain's read+reset is now only a fallback for turn-less callers). Lives
+ * HERE (not in agent_run.ts) so plan-chain never has to import the tool
+ * module — plan-gate is already the shared, pure, I/O-free home for
+ * plan-phase module state. */
+let planPhaseSubagentDispatches = 0;
+export function notePlanPhaseSubagentDispatch() {
+    planPhaseSubagentDispatches += 1;
+}
+export function getAndResetPlanPhaseSubagentDispatches() {
+    const n = planPhaseSubagentDispatches;
+    planPhaseSubagentDispatches = 0;
+    return n;
+}
+/* ── Task 10 — deviation backstop state (2026-07-03) ───────────────────────
+ * currentPhaseWrites: the DECLARED `writes` field of the plan phase executing
+ * THIS turn (null = outside phases). Set by the repl wiring alongside
+ * setPlanPhaseActive at both call sites, cleared to null in the same finally.
+ * tools/approval.ts consults it BEFORE rendering anything: guarded run +
+ * writes === false + a request_approval arriving anyway = a plan deviation —
+ * the write is DENIED without prompting (an unattended chain must never hang
+ * on an interactive approval), and the deviation flag below is raised.
+ * Fail-safe by construction: only an EXPLICIT false ever denies. */
+let currentPhaseWrites = null;
+export function setCurrentPhaseWrites(w) {
+    currentPhaseWrites = w;
+}
+export function getCurrentPhaseWrites() {
+    return currentPhaseWrites;
+}
+/* Task 10 — the "deviation occurred" flag, same read+reset pattern as the
+ * subagent counter above: approval.ts raises it (with the detail string) when
+ * it denies an undeclared write; plan-chain.ts reads+resets it at post-phase-
+ * chain start and turns it into blocked + lastStop:'deviation' + STOPPED
+ * banner. Lives HERE so plan-chain never imports the tool module. */
+/**
+ * The one detail string a deviation carries — shared so approval.ts (the
+ * raiser), plan-chain.ts (the persister) and the tests can never drift.
+ */
+export const PLAN_DEVIATION_DETAIL = 'phase declared writes:false but requested a write approval — chain stopped';
+let planDeviationDetail = null;
+export function notePlanDeviation(detail) {
+    planDeviationDetail = detail;
+}
+export function getAndResetPlanDeviation() {
+    const d = planDeviationDetail;
+    planDeviationDetail = null;
+    return d;
+}
+/**
+ * Banner shown for every non-auto guarded outcome. The resume hint uses the
+ * literal `@<plan>` placeholder on purpose — this module is pure and doesn't
+ * know the saved path; the caller may substitute the real basename.
+ */
+const banner = (reason, next) => `\n■ STOPPED — ${reason}\n  Resume with: /abap-plan --resume @<plan>  (next phase: ${next})\n`;
+export function decideNextPhaseGate(args) {
+    if (args.mode === 'step') {
+        // Step mode is today's behaviour verbatim — a plain consent prompt with
+        // no guarded decorations (no banner, no stopReason).
+        return { action: 'prompt' };
+    }
+    // Guarded. Hard stop first: an unresolved prior audit must never be
+    // downgraded to a runnable prompt by the write-phase branch below.
+    if (!isAuditResolved(args.prevPhaseAudit)) {
+        if (args.prevPhaseAudit?.state === 'infra_failed') {
+            return {
+                action: 'stop',
+                stopReason: 'audit-infra',
+                banner: banner('auditor infrastructure failure — verdict unknown (not a code finding)', args.nextPhase.id),
+            };
+        }
+        return {
+            action: 'stop',
+            stopReason: 'audit-failed',
+            banner: banner('prior phase audit is unresolved — fix the findings or explicitly waive them', args.nextPhase.id),
+        };
+    }
+    if (phaseWrites(args.nextPhase)) {
+        // The prompt IS the stop: consent to run the write phase. Writes inside
+        // the phase still go through their own approval flow — this never
+        // pre-approves them.
+        return {
+            action: 'prompt',
+            stopReason: 'write-phase',
+            // Task 3 review carry-over: the banner's resume hint already names the
+            // phase (`next phase: <id>`), so the reason string stays generic —
+            // naming it twice read as a rendering bug.
+            banner: banner('next phase writes to SAP — consent required to run it', args.nextPhase.id),
+        };
+    }
+    return { action: 'auto' };
+}