@cspeach/cli 1.1.30 → 1.1.32

package/README.md

@@ -77,6 +77,14 @@ session abc123 │ S4H │ /abap-explain │ 2 turns │ 487 tok │ $0.07 │ s
 
 On `/exit` you get a session summary + the `cspeach --resume <id>` command in plain text so you can pick up where you left off.
 
+To pick up an earlier session:
+
+- `cspeach --continue` (or `-c`) — continue the latest session in this folder
+- `cspeach --resume` — pick a session from this folder, or all folders
+- `cspeach --resume <id>` — works from any folder
+
+Files always save in the folder you start CSPeach in.
+
 ## UI modes
 
 An interactive terminal gets the standard display (the Ink frame). `/ui auto` (the default) picks it for you; `/ui ink` asks for it explicitly. Both save to `~/.cspeach/config.toml` under `[ui]` and apply after a relaunch.
@@ -111,7 +119,9 @@ cspeach whoami                   show signed-in identity + plan/trial
 cspeach logout                   clear local auth
 cspeach config add-sap           add a SAP system
 cspeach doctor                   diagnose install + connectivity
-cspeach --resume                 resume a prior session
+cspeach --continue, -c           continue the latest session in this folder
+cspeach --resume                 pick a session from this folder, or all folders
+cspeach --resume <id>            works from any folder
 cspeach --upgrade                pull the latest CLI release
 cspeach --version
 ```

package/dist/agent/loop.js

@@ -3,6 +3,7 @@ import { basename } from 'node:path';
 import { dispatchTool } from './tool-dispatch.js';
 import { listTools, getTool, isStandalone, toolsForContext, toAnthropicTools } from '../tools/index.js';
 import { saveSession } from '../session/store.js';
+import { tagSessionOnSave } from '../session/project-match.js';
 import { recordCompletedToolCall } from '../session/pending.js';
 import { loadConfig } from '../config/loader.js';
 import { resolveModelRole, resolveEffort, modelAcceptsEffort, resolveAutoCompactThreshold, callModelFor } from '../models/resolve.js';
@@ -17,7 +18,7 @@ import { nextWritingActivity } from '../renderer/fence-state.js';
 import { renderToolCallTop, renderToolCallBottom, startToolSpinner, startThinkingSpinner, isWidgetSuppressedTool, toolActivityText, toolHeartbeatLabel } from '../renderer/tool-widget.js';
 import { formatToolErrorSummary } from '../sap-errors/parse-adt-exception.js';
 import { startThinkingHeartbeat } from '../renderer/thinking-heartbeat.js';
-import { isDeclaredOneShot } from '../renderer/tty.js';
+import { isDeclaredOneShot, isHeadless } from '../renderer/tty.js';
 import { USER_STOP_REASON } from '../session/interrupt-reason.js';
 import { writeStdout, stdoutFlow } from '../renderer/transcript-flow.js';
 import { formatFailure, formatAttention, formatInfo } from '../renderer/notice-shape.js';
@@ -40,6 +41,9 @@ 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 { afterRebuildTurn } from '../journey/rebuild.js';
+import { afterJourneyTurn, gateJourneyForTurn, journeyAsk, journeyCardConfirm, journeyStoppedOnError, journeyTurnBlock, pauseJourneyForInterruptedTurn } from '../journey/chain.js';
+import { addJourneyLeftOut, addJourneySkips, getJourneyFlow } from '../journey/flow.js';
 import { afterPlanSave, afterSpecGapNotSaved, 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';
@@ -68,6 +72,7 @@ import { CacheKeepalive, snapshotParams, recordLastRequest, isCacheablePrompt, n
 import { maybeColdPrune } from './cold-prune.js';
 import { createAdtLock, serializeAdt } from '../tools/subagent/adt-serial.js';
 import { hasReaderReadTools, INTERRUPTED_LINE } from '../tools/subagent/reader-prompt.js';
+import { openStatusPage } from '../util/open-in-browser.js';
 /**
  * Author identity for project-file metadata. Reads CSPEACH_AUTHOR_NAME first,
  * then platform USER/USERNAME, then a generic fallback. Role is fixed to
@@ -98,11 +103,11 @@ const SAVE_HOOK_SKILLS = new Set([
     'abap-upgrade-fix',
     'abap-upgrade-verify',
     'abap-upgrade-merge',
-    // 2026-05-09: CCA pipeline manifest envelopes. /abap-cca emits a
-    // <!-- csforge:cca-manifest --> block wrapping the heavy project.json
-    // detail at .cspeach/cca/projects/<slug>/. /abap-cca-merge produces
+    // 2026-05-09: CCA pipeline manifest envelopes. /abap-cca-merge produces
     // a consolidated cca-assessment from N parallel consultant slices.
-    'abap-cca',
+    // 2026-10-06: the thin /abap-cca (1.1.31) reads the estate inventory and
+    // writes no envelope, so it is no longer a save-hook skill. An old
+    // cca-manifest in a turn is still offered through detectArtifactSkill.
     'abap-cca-merge',
     // 2026-05-10: v0.7 trio chain. /abap-modernize emits modernize-result;
     // /abap-test emits test-coverage. Both accept cca-assessment via --from
@@ -283,7 +288,10 @@ export async function maybeOfferSave(p) {
         if (!detected)
             return;
         saveSkill = detected;
-        p.emit(formatInfo(`${detected} output found in this turn (routed as ${p.skill}) · offering to save it`).trimEnd());
+        // Inside a journey the triage is saved as part of the step: nothing to offer.
+        if (!(p.journey && detected === p.skill)) {
+            p.emit(formatInfo(`${detected} output found in this turn (routed as ${p.skill}) · offering to save it`).trimEnd());
+        }
     }
     // B5 (2026-06-11) — defect D2: in headless runs the artifact IS the point
     // of the run, so the "Save as project file? [y/N]" prompt defaults YES
@@ -327,6 +335,9 @@ export async function maybeOfferSave(p) {
             // found in another skill's output (detectArtifactSkill) never gets it.
             ...(p.lane && p.skill === saveSkill ? { lane: p.lane } : {}),
             onNotSaved: (reason) => { notSaved = reason; },
+            ...(p.onProjectId ? { onProjectId: p.onProjectId } : {}),
+            // Never headless: a headless journey queues nothing.
+            ...(p.journey && !isHeadless() && p.skill === saveSkill ? { journey: p.journey } : {}),
         });
         // 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
@@ -405,6 +416,49 @@ function readerRunFrom(content, start) {
 function stripModelDate(model) {
     return model?.replace(/-\d{8}$/, '');
 }
+/**
+ * Guided clean-core journey (Task 4) — what the triage save needs from the
+ * journey: its card (Ink card slot or a typed line), a typed reason, the
+ * session skips, the pause, and the page the triage was shown.
+ */
+function journeySaveFor(session, emit) {
+    const page = getJourneyFlow(session)?.page;
+    return {
+        card: journeyCardConfirm(emit),
+        // Esc on "Why keep it?" pauses the journey, as Esc on the card does.
+        ask: journeyAsk(),
+        skip: (keys) => addJourneySkips(session, { decide: new Set(keys) }),
+        leaveForLater: (keys) => addJourneyLeftOut(session, keys),
+        pause: () => {
+            const line = pauseJourneyForInterruptedTurn(session);
+            if (line)
+                emit(line);
+        },
+        ...(page ? { page } : {}),
+    };
+}
+/**
+ * Guided clean-core journey (Task 3) — the chain's hooks from a top-level
+ * turn: the session's SAP client, the pending-dispatch slot, the turn's abort
+ * signal (Ctrl-C reaches a running check), the turn's own output.
+ */
+function journeyHooks(params, emit) {
+    const ctx = params.ctx;
+    const standaloneTurn = isStandalone(ctx);
+    return {
+        session: ctx.session,
+        cwd: ctx.cwd,
+        headless: isHeadless(),
+        emit,
+        ...(ctx.pendingDispatch ? { queueNext: (cmd, origin) => ctx.pendingDispatch.set(cmd, origin) } : {}),
+        ...(!standaloneTurn && ctx.adt ? { adt: ctx.adt } : {}),
+        ...(ctx.sapAlias ? { sapAlias: ctx.sapAlias } : {}),
+        ...(standaloneTurn ? { noSap: true } : {}),
+        ...(params.signal ? { signal: params.signal } : {}),
+        // Task 6 — the status page opens in the browser after Yes on its card.
+        openFile: (file) => openStatusPage(file),
+    };
+}
 export async function runTurn(params) {
     // Task 18 — a reader subagent runs INSIDE the parent's turn: it must not
     // reset the parent's Rule 8 batch counter, drain the parent's steering
@@ -470,6 +524,19 @@ export async function runTurn(params) {
         else
             console.log(line);
     }
+    // Guided clean-core journey (Task 3) — the journey survives only its own
+    // queued step (or a plain reply inside it); any other turn ends the chain
+    // with one line. No journey → nothing happens here.
+    if (!readerChild && !params.ctx.subagent) {
+        const journeyGate = gateJourneyForTurn(session, {
+            skill: params.skill,
+            userMessage: params.userMessage,
+            explicitSlash: params.explicitSlash === true,
+            previousSkill: session.skill,
+        });
+        if (journeyGate.ended && journeyGate.line && !isHeadless())
+            emit(journeyGate.line);
+    }
     // Phase J — `--from @<source>` phase promotion.
     // If the user typed `/abap-design --from @./spec-gap.cspeach.json` (or the
     // estimate equivalent), strip the flag, validate + snapshot the source,
@@ -642,6 +709,11 @@ ${imageExpansion.error}`));
         }
         if (laneBlock)
             userMessageForLLM = `${userMessageForLLM}\n\n${laneBlock}`;
+        // Guided clean-core journey (final fix wave) — the queued triage turn says
+        // in its own prompt: no commands, CSPeach asks row by row. '' otherwise.
+        const journeyBlock = params.ctx.subagent ? '' : journeyTurnBlock(session, params.skill);
+        if (journeyBlock)
+            userMessageForLLM = `${userMessageForLLM}\n\n${journeyBlock}`;
     }
     // 2026-05-06: alongside the deterministic prompt-fact extraction
     // (package / transport / etc.), inject the connected SAP system's
@@ -866,7 +938,7 @@ ${imageExpansion.error}`));
     session.turn_seq = (session.turn_seq ?? Math.max(turnNumber - 1, session.lastAutoCompactTurn ?? 0)) + 1;
     // Snapshot session.messages.length at turn start so the save hook can
     // walk every assistant message added during this turn — not just the
-    // final one. Skills like /abap-cca emit their manifest in an early
+    // final one. Skills like /abap-cca-merge emit their manifest in an early
     // message before a closing ask_question widget; the final wrap-up
     // message ends the turn but doesn't carry the manifest. See
     // ./turn-assistant-text.ts for the full rationale.
@@ -1529,6 +1601,13 @@ ${imageExpansion.error}`));
         await turnStreamWriter.close(interruptedError !== null
             ? `_interrupted: ${session.turnInterruptedReason ?? 'unknown'}_`
             : undefined);
+        // Guided clean-core journey (Task 3, fix round 1) — the queued step was
+        // interrupted: pause the journey so "carry on" resumes it on the first try.
+        if (interruptedError !== null && !readerChild && !params.ctx.subagent) {
+            const journeyLine = pauseJourneyForInterruptedTurn(session);
+            if (journeyLine && !isHeadless())
+                emit(journeyLine);
+        }
         // Re-throw AFTER persistence so the outer REPL catch can render the
         // graceful error UX with full session-id + log-path context.
         if (interruptedError !== null)
@@ -1585,7 +1664,7 @@ ${imageExpansion.error}`));
             // a background block on the next REPL prompt.
             //
             // 2026-05-12: collect text from ALL assistant messages added during
-            // this turn, not just the final one. Skills like /abap-cca emit
+            // this turn, not just the final one. Skills like /abap-cca-merge emit
             // their manifest in an early message before a closing ask_question
             // widget; the final wrap-up message ends the turn but doesn't
             // carry the manifest. See ./turn-assistant-text.ts for details.
@@ -1597,6 +1676,7 @@ ${imageExpansion.error}`));
             // while the user was the one being waited on (Laeeq's dry run). Pause
             // for the whole hook — the row hides while paused — and resume after,
             // so any real work that follows (auto-compact) shows again.
+            let projectTagChanged = false;
             status.pause();
             try {
                 if (!params.suppressSaveHook) {
@@ -1618,12 +1698,20 @@ ${imageExpansion.error}`));
                             const flowLane = getAppFlow(session)?.lane;
                             return flowLane ? { lane: { ...flowLane, cwd: params.ctx.cwd } } : {};
                         })(),
+                        // Sessions/folders (Task 6) — the first save tags the session with
+                        // its folder's project id, only when the session belongs to this
+                        // folder (ruling 18). Saved to disk right after the hook.
+                        onProjectId: (id) => { if (tagSessionOnSave(session, process.cwd(), id))
+                            projectTagChanged = true; },
+                        // Guided clean-core journey (Task 4) — the queued triage's rows.
+                        ...(!readerChild && !params.ctx.subagent && getJourneyFlow(session)?.queued?.stage === 'DECIDE'
+                            ? { journey: journeySaveFor(session, emit) } : {}),
                         // 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) } : {}),
+                                ...(params.ctx.pendingDispatch ? { queueNext: (cmd, origin) => params.ctx.pendingDispatch.set(cmd, origin) } : {}),
                                 ...(params.ctx.sapAlias && params.ctx.sapAlias !== 'none' ? { sapAlias: params.ctx.sapAlias } : {}),
                             },
                         } : {}),
@@ -1634,6 +1722,41 @@ ${imageExpansion.error}`));
                 keepalive.disarm();
                 status.resume();
             }
+            // Sessions/folders (Task 6) — the session was saved before the hook;
+            // persist the project id the save just filled in. Best-effort.
+            if (projectTagChanged) {
+                try {
+                    await saveSession(session);
+                }
+                catch { /* tagging never fails the turn */ }
+            }
+            // Guided clean-core journey (Task 3) — the queued step's turn ended:
+            // derive the stage from the folder again and go on (the next code
+            // stage, a step card, or the next queued command).
+            if (!readerChild && !params.ctx.subagent && getJourneyFlow(session)?.queued) {
+                try {
+                    await afterJourneyTurn(journeyHooks(params, emit), {
+                        skill: params.skill,
+                        awaitingAnswer: session.awaitingSkillAnswer === true,
+                        assistantText,
+                    });
+                }
+                catch (err) {
+                    if (process.env['CSPEACH_DEBUG'] === '1')
+                        throw err;
+                    // Audit M-1: paused (not ended), so the line's "carry on" works; the
+                    // error is logged, and a second stop at the same step says so (follow-up a).
+                    emit(chalk.yellow(journeyStoppedOnError(session, params.ctx.cwd, err)));
+                }
+            }
+            // Step 2, Task 5 — a /abap-modernize rebuild handed off by the journey
+            // reads `started` once one of its turns wrote to SAP (F9).
+            if (!readerChild && !params.ctx.subagent) {
+                try {
+                    await afterRebuildTurn(session, params.skill);
+                }
+                catch { /* the row stays handed-off */ }
+            }
             // Phase 2 #9 (2026-05-16) — auto-compact end-of-turn hook.
             // Runs only on the success path (after maybeOfferSave) so an interrupted
             // turn never triggers a summariser call on partial state. The maybeAutoCompact

package/dist/cli.js

@@ -10,7 +10,7 @@ import { migrateLegacyByokKey, legacyByokKeyNotice, cleanStaleAuthTemps } from '
  * The verbs that make `cspeach project …` a mistyped team command rather than
  * a prompt somebody meant to send. See the check in `main`.
  */
-const TEAM_SUBCOMMANDS = new Set(['init', 'join', 'lane', 'refresh', 'status', 'outbox', 'rule', 'leave']);
+const TEAM_SUBCOMMANDS = new Set(['init', 'join', 'lane', 'refresh', 'status', 'outbox', 'rule', 'rules', 'target', 'decide', 'leave', 'export']);
 export async function main(argv) {
     // NO_COLOR (piece 2 §1.2) — before ANY output, for every command (REPL,
     // one-shot, doctor, login, help, config …).
@@ -67,6 +67,20 @@ export async function main(argv) {
         sapAlias = parsed.sapAlias;
         args = parsed.rest;
     }
+    // 2026-10-08 (sessions/folders) — `--continue` / `-c`: the latest session of this folder.
+    if (args[0] === '--continue' || args[0] === '-c') {
+        if (args[1] !== undefined && !args[1].startsWith('-')) {
+            console.error(chalk.red('error: --continue takes no session id. To pick one: cspeach --resume'));
+            return 1;
+        }
+        // Like --resume: a trailing flag is refused (--sap-alias / --no-sap were taken out above).
+        if (args[1] !== undefined) {
+            console.error(chalk.red(`error: --continue takes no other flag, not '${args[1]}'. Usage: cspeach --continue`));
+            return 1;
+        }
+        const { runContinue } = await import('./session/resume.js');
+        return runContinue({ sapAlias, noSap });
+    }
     if (args[0] === '--resume') {
         // Final batch 5 — `--resume --one-shot "…"`: a flag is never a session id.
         if (args[1]?.startsWith('-')) {
@@ -153,17 +167,10 @@ export async function main(argv) {
         const { input } = await import('@inquirer/prompts');
         const { loadConfig } = await import('./config/loader.js');
         const cfg = await loadConfig();
-        const open = async (url) => {
-            const { spawn } = await import('node:child_process');
-            // On Windows, `start` is a cmd builtin and needs a shell; spawn the URL via cmd /c.
-            if (process.platform === 'win32') {
-                spawn('cmd', ['/c', 'start', '', url], { detached: true, stdio: 'ignore' }).unref();
-            }
-            else {
-                const cmd = process.platform === 'darwin' ? 'open' : 'xdg-open';
-                spawn(cmd, [url], { detached: true, stdio: 'ignore' }).unref();
-            }
-        };
+        // The shared opener (util/open-in-browser.ts): https only, never through
+        // cmd or a shell; rejects when nothing opened, so login prints its own line.
+        const { loginOpener } = await import('./util/open-in-browser.js');
+        const open = loginOpener();
         return runLoginCommand({
             proxyUrl: cfg.proxy_url,
             open,
@@ -202,7 +209,10 @@ export async function main(argv) {
                 return {
                     sql: (q, max) => adt.sqlQuery(q, max),
                     system: { sid: name },
-                    atc: { runSet: (refs, variant, opts) => adt.atcRunSet(refs, variant, opts) },
+                    atc: {
+                        runSet: (refs, variant, opts) => adt.atcRunSet(refs, variant, opts),
+                        findingDocument: (href) => adt.atcFindingDocument(href),
+                    },
                 };
             },
             ask: async (question) => {
@@ -231,9 +241,14 @@ export async function main(argv) {
     // a PAID prompt on a machine that is configured and logged in. A hint, not
     // an alias: the old family does not run, and nothing is renamed back.
     if (args[0] === 'project' && TEAM_SUBCOMMANDS.has(args[1] ?? '')) {
-        console.log('Unknown command: cspeach project. Team projects use: cspeach team init|join|lane|refresh|status|outbox|rule|leave');
+        console.log('Unknown command: cspeach project. Team projects use: cspeach team init|join|lane|refresh|status|outbox|rule|rules|target|decide|leave|export');
         return 1;
     }
+    // Sessions/folders (2026-10-08): sort project files from earlier builds into their folders. Copy only.
+    if (args[0] === 'files' && args[1] === 'sort') {
+        const { runFilesSort } = await import('./projects/sort-command.js');
+        return runFilesSort(args.slice(2), { log: (s) => console.log(s), cwd: process.cwd() });
+    }
     if (args[0] === 'analyze' && args[1] === 'project-context') {
         const { runProjectContextImpactCommand } = await import('./commands/project-context-impact.js');
         return runProjectContextImpactCommand(args.slice(2));
@@ -270,7 +285,8 @@ Usage:
   cspeach --one-shot "<prompt>"     Same as above, explicit flag
   cspeach --sap-alias <name>        Use a specific SAP alias (overrides default)
   cspeach --no-sap                  Start without a SAP system (paste-mode skills only)
-  cspeach --resume [id]             Resume a previous session (list if no id)
+  cspeach --continue, -c            Continue the latest session in this folder
+  cspeach --resume [id]             Pick a session from this folder (or all folders); an id works anywhere
   cspeach config add-sap            Add a SAP system interactively
   cspeach config standalone         Set the standalone SAP profile (no system)
   cspeach standards init            Capture your team's ABAP development standards
@@ -283,18 +299,33 @@ Usage:
   cspeach login                     Sign in via device-code flow
   cspeach logout                    Sign out (keep keychain key, if any)
   cspeach whoami                    Print current account info
+  cspeach team discover            Read the whole estate from SAP into this folder (read only)
+  cspeach team start <packages>     Start a team project in this folder: object list, first check, you own it all
+  cspeach team start --for "FI and SD" --developers "James Miller, me"   Lead: set up by name from this folder's discovery; one lane each
   cspeach team init <folder>        Lead: pull the object list from SAP, start a team project
-  cspeach team join <folder>        Record your results against a team project (on this laptop only)
+  cspeach team join <folder> [--as "<name>"]   Record your results against a team project (on this laptop only), under the lane owner's name
   cspeach team lane add|list        Lead: who owns which packages
+  cspeach team lane move --packages <names> --to <developer>   Lead: move packages by name (lanes of names only)
+  cspeach team lane propose --developers "A,B" [--apply]   Lead: a first cut of the lanes, balanced by the work
+  cspeach team focus "<label>" --packages … --reason "…"   Lead: what the team works on now (focus list | clear <label>)
+  cspeach team priority show|set|reset   The priority rules; set and reset are the lead's
+  cspeach team plan move|scope|defer|set|note|history   Lead: per-object plan changes, each with a reason
+  cspeach team plan import <file.xlsx> [--yes]   Lead: read back the Plan sheet edited in Excel; shows the changes, asks once
   cspeach team refresh --lane <id>  Measure with ATC: what is verified, what did not hold
+  cspeach team refresh --all --per-package [--again]   One record per package; skips packages already measured
   cspeach team status [folder]      Where every object stands, who owns it, what is proven
   cspeach team outbox               What this laptop has recorded, and where
-  cspeach team rule T N <d>         Lead: settle a conflicting decision
-  cspeach team decide T N <d>       Record a clean-core decision: keep, fix, rebuild, retire or exception
+  cspeach team rule T N <d>         Lead: settle a conflicting decision (a retire needs --reason)
+  cspeach team rules [on|off|set|add|remove|reset]   The decision rules: anyone views them, the lead changes them (also /rules in a session)
+  cspeach team decide T N <d>       Record a clean-core decision: keep, fix, rebuild, retire or exception (a retire needs --reason)
+  cspeach team target <A-D> --reason "…" [--packages P1,P2] [--variant <NAME>]   Lead: the level fixes are proven against (team target clear removes it)
   cspeach team fixed T N            Claim a fix; the next refresh checks it
+  cspeach team rebuild built T N --app <APP>   Say a rebuild is built (the report then reads built, not yet checked)
   cspeach team sheet                Write your working list (Excel) from the team project
   cspeach team report               Lead: the combined workbook and status page, in reports
+  cspeach team export [--out <folder>] [--always | --never]   The CSV files for your own tools, in reports/exports (--always: with every report; --never: stop that)
   cspeach team leave                Stop recording
+  cspeach files sort [--apply <plan>] [--clean <plan>]   Sort files from earlier builds into their folders (copies; --clean deletes checked originals)
   cspeach analyze project-context   Compare flag-on vs flag-off session metrics
   cspeach --upgrade                 Upgrade to latest via npm
   cspeach --version                 Print version

package/dist/commands/config-set.js

@@ -212,7 +212,7 @@ const UNSET_ONLY_KEYS = new Set(['standalone']);
  * remains), keeping the top-level entry in `file_keys` is what stops sparse
  * save from dropping the now-default-equal parent table.
  */
-function unsetConfigKey(cfg, key) {
+export function unsetConfigKey(cfg, key) {
     const parts = key.split('.');
     const top = parts[0];
     const obj = cfg;

package/dist/commands/help.js

@@ -6,6 +6,7 @@ import { paint } from '../renderer/theme.js';
 import { uiWidth, truncateToWidth } from '../renderer/ui-width.js';
 // I2's shortcuts table and note — one source for the `?` sheet and /help.
 import { SHORTCUT_ROWS, SHORTCUTS_NOTE } from '../ui/widgets/shortcuts-sheet.js';
+import { BUNDLED_RUNS } from '../runs/runs.js';
 // Workflow order: plan → understand → modify → build → upgrade → ship.
 const CATEGORY_ORDER = [
     'Pre-Coding',
@@ -26,11 +27,20 @@ const fixed = (s) => () => s;
  * follows the cost display mode (credits for managed customers).
  */
 export const HELP_GROUPS = [
+    // Guided runs (spec 2026-10-08 §3.2) — above "Work on SAP", one row per
+    // declared run, from the bundled declarations (RUN.md), never from code.
+    { title: 'Guided runs', rows: BUNDLED_RUNS.map((r) => ({
+            name: r.entry,
+            description: fixed(`${r.title} — ${r.steps.length} steps. Also: ${r.alias}`),
+            // The RUN.md body paragraph (spec §3.1, "one paragraph for /help").
+            detail: r.paragraph,
+        })) },
     { title: 'Work on SAP', rows: [
             { name: '/transport [TR]', description: fixed('View or set the transport for this session') },
             { name: '/mode [advisory|gated|auto]', description: fixed('Set the write mode (Shift+Tab also cycles)') },
             { name: '/safety-mode on|off|status', description: fixed('Turn the Forge Rule confirmation cards on or off') },
             { name: '/rewind', description: fixed('Undo a write from this session (Esc Esc)') },
+            { name: '/rules', description: fixed("View or change the team project's decision rules") },
             { name: '/reroute <skill>', description: fixed('Re-run your last prompt with a different skill') },
         ] },
     { title: 'Local files', rows: [
@@ -102,8 +112,13 @@ export function printHelp(emit = (s) => console.log(s)) {
     for (const group of HELP_GROUPS) {
         emit('');
         emit(groupTitle(group.title));
-        for (const r of group.rows)
+        for (const r of group.rows) {
             emit(row(r.name, r.description()));
+            // A row's detail (a guided run's paragraph) wraps in full, dim, under the description column.
+            if (r.detail)
+                for (const l of wrapDescription(r.detail, descWidth, Number.MAX_SAFE_INTEGER))
+                    emit(`${continuationIndent}${paint('dim', l)}`);
+        }
         if (group.title === 'Work on SAP') {
             // Skills live under "Work on SAP", one dim sub-heading per category.
             for (const category of CATEGORY_ORDER) {

package/dist/commands/plan-chain.js

@@ -28,6 +28,7 @@ import { readProjectFile } from '../projects/status.js';
 import { parsePlanContent } from '../projects/plan-schema.js';
 import { statusesFromItems, computeNextPhaseForRun, isPhaseSatisfiedForRun, planCompletionLines, phaseDisplayTitle, } from '../projects/plan-run.js';
 import { savedLocation } from '../projects/saved-lines.js';
+import { afterPlanComplete } from '../journey/rebuild.js';
 import { clearPlanGrant, getPlanGrant, getGrantTransport, installPlanGrant, noteDeltaOffered, offeredDeltaObjects, planGrantAllowed, } from '../approvals/plan-grant.js';
 import { collectPlannedObjects, plannedObjectFacts } from '../projects/plan-objects.js';
 import { isDeployPhase } from '../projects/plan-lane.js';
@@ -251,6 +252,8 @@ async function postPhaseChain(args) {
             const nextAfter = computeNextPhaseForRun(after.content.phases, st);
             if (built && !nextAfter) {
                 args.log('', ...planCompletionLines(after.content.phases));
+                // Step 2 (C5): a rebuild whose plan this is now reads "built, not yet checked".
+                await afterPlanComplete(cur);
                 args.log(`Plan file: ${savedLocation(cur, args.cwd)}`);
             }
             else if (!built && auditFailed && !stopShown) {

package/dist/commands/plan-continue.js

@@ -119,7 +119,7 @@ export async function preparePlanContinuation(args) {
     // 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);
+    const laneGate = await loadPlanLaneForRun(args.cwd ?? process.cwd(), parsed.content, path);
     if (!laneGate.ok) {
         args.log(...laneGate.lines);
         return { prepared: null, stale: false, paused: true };

package/dist/commands/plan-gate.js

@@ -31,8 +31,24 @@ let guardedRunActive = false;
 export function setGuardedRunActive(active) {
     guardedRunActive = active;
 }
+/* Guided clean-core journey (2026-10-07, Task 3) — the journey's own share of
+ * the same override, kept apart so a plan turn's set/clear and the journey's
+ * start/end never undo each other. Off ⇒ byte-identical to before. */
+let journeyRunActive = false;
+export function setJourneyRunActive(active) {
+    journeyRunActive = active;
+}
+/* Step 2 (final review I2) — the rebuild hand-off's share. The journey ends
+ * (its share off) BEFORE it queues the rebuild skill; that queued turn is
+ * auto-dispatched, so it must not inherit auto_approve either. Set just before
+ * the queue, cleared after the first top-level turn that follows the hand-off
+ * turn (journey/rebuild.ts afterRebuildTurn), whatever its skill. */
+let rebuildRunActive = false;
+export function setRebuildRunActive(active) {
+    rebuildRunActive = active;
+}
 export function isGuardedRunActive() {
-    return guardedRunActive;
+    return guardedRunActive || journeyRunActive || rebuildRunActive;
 }
 /* ── plan-phase read-only enforcement (Task 7, 2026-07-03) ─────────────────
  * Module-level flag consulted by tools/subagent/agent_run.ts. The REPL sets

package/dist/commands/plan-resume.js

@@ -53,6 +53,7 @@ import { acquireRunLease, releaseRunLease } from '../projects/run-lease.js';
 import { validateEnvelope } from '../projects/validate.js';
 import { collectTurnAssistantText } from '../agent/turn-assistant-text.js';
 import { getAuthorIdentity } from '../agent/loop.js';
+import { afterPlanComplete } from '../journey/rebuild.js';
 import { DEFAULT_PLAN_MODE } from './plan-gate.js';
 import { FLOORPLAN_TO_TEMPLATE } from '../tools/fiori/floorplan-map.js';
 import { getCurrentTransport, setCurrentTransport } from '../repl/current-transport.js';
@@ -260,7 +261,7 @@ export async function preparePlanResume(args) {
     // 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);
+    const laneGate = await loadPlanLaneForRun(args.cwd, content, path);
     if (!laneGate.ok) {
         args.log(...laneGate.lines);
         return null;
@@ -632,7 +633,7 @@ export async function preparePlanResume(args) {
     // 2026-10-04 (plan sources) — the spec-gap items this phase reads, in full,
     // from the file the plan was made from (or the plan's creation snapshot).
     // A phase must never have to hunt the folder for its gap answers.
-    const sourcesBlock = renderPlanSourcesBlock(await resolvePlanSources({ cwd: args.cwd, envelope, content, ...(laneRecord ? { laneRecord } : {}) }), next);
+    const sourcesBlock = renderPlanSourcesBlock(await resolvePlanSources({ cwd: args.cwd, envelope, content, planPath: path, ...(laneRecord ? { laneRecord } : {}) }), next);
     const llmPrompt = [
         `Resume execution of the project plan "${envelope.title}" (envelope v${envelope.version}).`,
         '',
@@ -981,14 +982,9 @@ export async function finishPlanResume(args) {
         logNotSaved(args, 'the updated plan did not pass its own checks', `revision failed validation: ${check.error.message}`);
         return null;
     }
-    let outDir;
-    try {
-        outDir = await ensureWorkspace();
-    }
-    catch {
-        outDir = process.cwd();
-    }
-    const savedPath = await saveProject(revision, { cwd: outDir });
+    // 2026-10-08 — the new version is saved beside the plan file, wherever it
+    // is (an old git root, a copied folder), so a plan family never splits.
+    const savedPath = await savePlanVersion(revision, args.prepared.path, args.log);
     // Task 8 — regenerate the write-only markdown handover projection beside
     // the envelope. Best-effort: a failed projection write logs one dim line
     // and never blocks the run (the envelope is the source of truth).
@@ -1024,6 +1020,9 @@ export async function finishPlanResume(args) {
         if (!next && provisionalPhases.every((p) => isPhaseSatisfied(statuses[p.id], p.audit))) {
             // C2 (D24): same chain as preparePlanResume — single source in plan-run.ts.
             args.log(...planCompletionLines(provisionalPhases));
+            // Step 2 (C5): the live run finished — a rebuild whose plan this is reads built.
+            // Not at the re-opened complete plan above (preparePlanResume).
+            await afterPlanComplete(args.prepared.path);
         }
         else if (!next) {
             const blocked = provisionalPhases.filter((p) => statuses[p.id] === 'blocked').map((p) => phaseDisplayTitle(p, provisionalPhases));
@@ -1048,6 +1047,23 @@ export async function finishPlanResume(args) {
         nextTitle: next ? phaseDisplayTitle(next, extract.content.phases) : null,
     };
 }
+/**
+ * Final fix wave, item 5 — save a new plan version beside the plan file. When
+ * that write fails (a read-only or missing folder), save it in the working
+ * folder instead, so the run's progress is never lost, and say where.
+ */
+async function savePlanVersion(revision, planPath, log) {
+    const beside = dirname(planPath);
+    try {
+        return await saveProject(revision, { cwd: beside });
+    }
+    catch {
+        const ws = await ensureWorkspace();
+        const saved = await saveProject(revision, { cwd: ws });
+        log(`Could not save beside the plan in ${beside}. Saved in ${ws} instead.`);
+        return saved;
+    }
+}
 /**
  * Shared revision writer for audit verdicts and chain-stop records: load the
  * envelope, patch ONE phase (audit and/or status) + content.lastStop,
@@ -1103,14 +1119,8 @@ async function savePlanPatch(envelopePath, phaseId, patch, log) {
     if (!check.ok) {
         throw new Error(`audit revision failed validation: ${check.error.message}`);
     }
-    let outDir;
-    try {
-        outDir = await ensureWorkspace();
-    }
-    catch {
-        outDir = dirname(envelopePath);
-    }
-    const saved = await saveProject(revision, { cwd: outDir });
+    // 2026-10-08 — saved beside the plan file (the working folder only as a fallback).
+    const saved = await savePlanVersion(revision, envelopePath, log ?? console.log);
     // Task 8 — every envelope save in the plan flow regenerates the markdown
     // handover. This is the single chokepoint for ALL chain writes:
     // applyAuditResult and applyPhaseResolution both route through here.