@cspeach/cli 1.1.30 → 1.1.32

package/dist/projects/clean-core-confirm.js

@@ -1,3 +1,5 @@
+import { shown, shownUpTo } from '../register/atc-file.js';
+import { STEPS, stepOf } from '../journey/clean-core.js';
 const WORD = {
     keep: 'keep', exception: 'accepted exception', fix: 'fix', rebuild: 'rebuild beside the core', retire: 'retire',
 };
@@ -5,11 +7,42 @@ export function rowWords(r) {
     const parts = [WORD[r.disposition]];
     if (r.level)
         parts.push(`level ${r.level}`);
+    // Step 2 (F3): a target is said only when the proposal named one; the record keeps the legacy A, which is no target.
     if (r.disposition === 'fix' || r.disposition === 'rebuild')
-        parts.push(`target ${r.targetLevel ?? 'A'}`);
+        parts.push(r.targetLevel ? `target ${r.targetLevel}` : 'no target set');
     return `${parts.join(', ')}${r.reason ? `, because: ${r.reason}` : ''}`;
 }
 const DECIDE_HINT = 'cspeach team decide <TYPE> <NAME> <decision>';
+/** What a recorded reason keeps (records.ts). */
+const MAX_ROW_REASON = 300;
+const RULE_ROW = {
+    keep: 'keep', fix: 'fix', rebuild: 'rebuild', 'retire-candidate': 'retire',
+};
+/** A "Rule <id>: " the reason starts with — written by the model, so code checks it. */
+const RULE_PREFIX = /^\s*rule\s+[A-Za-z0-9_-]{1,20}\s*:\s*/i;
+/**
+ * The row read against the rule that decides its object. Agrees (same
+ * disposition): the reason starts "Rule <id>: " (the rule's note when the row
+ * gave none). Differs: the row stays the model's, and `differs` is the fact
+ * line "Differs from rule <id>: <why>". No rule: a "Rule <id>:" the model
+ * wrote is taken off — the row is CSPeach's judgement. The person still
+ * answers the card either way.
+ */
+export function ruleRow(r, p) {
+    const own = (r.reason ?? '').replace(RULE_PREFIX, '').trim();
+    if (!p)
+        return { row: own === r.reason ? r : { ...r, reason: own } };
+    const id = shown(p.ruleId);
+    const why = shownUpTo(p.why, 200);
+    // Agrees = same disposition, and the same target when the rule itself names one (owner ruling, review 9 #7).
+    const targetDiffers = p.targetFrom === 'rule' && p.target !== undefined && r.targetLevel !== p.target;
+    if (RULE_ROW[p.disposition] !== r.disposition || targetDiffers) {
+        return { row: own === r.reason ? r : { ...r, reason: own }, differs: `Differs from rule ${id}: ${why}` };
+    }
+    // Prefix + reason stay within the 300 the record keeps (records.ts would cut the end); cut by code point.
+    const head = `Rule ${id}: `;
+    return { row: { ...r, reason: head + Array.from(own || why).slice(0, Math.max(0, MAX_ROW_REASON - head.length)).join('') } };
+}
 export async function confirmCleanCoreRows(ex, a) {
     if (!a.joined) {
         // Review Focus 4: the file is still saved; say why nothing is recorded.
@@ -21,8 +54,9 @@ export async function confirmCleanCoreRows(ex, a) {
         return ex;
     }
     const rows = [];
-    for (const r of ex.content.adjudications) {
-        const answer = await a.confirm(`Record ${r.objectType} ${r.objectName}: ${rowWords(r)}?`, { default: 'n' });
+    for (const given of ex.content.adjudications) {
+        const { row: r, differs } = a.rules ? ruleRow(given, a.rules(keyOf(given))) : { row: given, differs: undefined };
+        const answer = await a.confirm(`Record ${r.objectType} ${r.objectName}: ${rowWords(r)}?${differs ? ` (${differs})` : ''}`, { default: 'n' });
         rows.push({ ...r, confirmed: answer === 'y' });
     }
     const yes = rows.filter((r) => r.confirmed).length;
@@ -34,3 +68,158 @@ export async function confirmCleanCoreRows(ex, a) {
         items: ex.items.map((i) => ({ ...i, status: byId.get(i.id) ? 'confirmed' : 'declined' })),
     };
 }
+export const KEEP_QUESTION = 'Why keep it?';
+/** "Yes to the remaining n shown" is offered once this many rows are answered. */
+const OFFER_REST_AFTER = 3;
+const MAX_KEEP_REASON = 300;
+/** A long reason wraps onto at most this many rows of the card. */
+export const FACT_ROWS = 5;
+const keyOf = (r) => `${r.objectType.trim().toUpperCase()}|${r.objectName.trim().toUpperCase()}`;
+/** The person's reason as one plain line: escapes, control characters and line breaks go; at most 300 characters. */
+export function cleanKeepReason(raw) {
+    // Cut by code point, so an emoji at the edge is never split in half.
+    return Array.from(shownUpTo(raw ?? '', Number.POSITIVE_INFINITY)).slice(0, MAX_KEEP_REASON).join('').trim();
+}
+/** The proposal in words, without the reason (the reason is a fact line on the card). */
+function proposalWords(r) {
+    return rowWords({ ...r, reason: '' });
+}
+export async function decideCleanCoreRows(ex, j) {
+    const all = ex.content.adjudications;
+    const ruled = all.map((r) => (j.rules ? ruleRow(r, j.rules(keyOf(r))) : { row: r, differs: undefined }));
+    const rows = ruled.map(({ row }) => ({ ...row, confirmed: false }));
+    const tally = { total: all.length, yes: [], kept: [], skipped: [], cancelled: false };
+    const footnote = `Step ${stepOf('DECIDE')} of ${STEPS}`;
+    let answered = 0;
+    rowLoop: for (let i = 0; i < rows.length; i++) {
+        const r = rows[i];
+        const type = shown(r.objectType);
+        const name = shown(r.objectName);
+        const left = rows.length - i;
+        const why = shownUpTo(r.reason ?? '', MAX_KEEP_REASON);
+        let canKeep = true;
+        let settled = false;
+        for (let tries = 0; tries < 20 && !settled; tries++) {
+            const offerRest = answered >= OFFER_REST_AFTER && left >= 2;
+            const res = await j.card({
+                id: 'journey-row',
+                tag: 'QUESTION',
+                title: `Record ${type} ${name}: ${proposalWords({ ...r, objectType: type, objectName: name })}?`,
+                facts: [...(why ? [`Why: ${why}`] : []), ...(ruled[i].differs ? [ruled[i].differs] : []), `Row ${i + 1} of ${rows.length}.`],
+                choices: [
+                    { value: 'yes', label: 'Yes' },
+                    ...(canKeep ? [{ value: 'keep', label: 'Keep as is' }] : []),
+                    { value: 'skip', label: 'Skip' },
+                    ...(offerRest ? [{ value: 'all', label: `Yes to the remaining ${left} shown` }] : []),
+                ],
+                initial: 0,
+                aliases: { y: 'yes', ...(canKeep ? { k: 'keep' } : {}), s: 'skip', ...(offerRest ? { a: 'all' } : {}) },
+                footnote,
+                // The reason is the point of the card: it wraps, never cut to one row.
+                wrapFacts: FACT_ROWS,
+            });
+            if (res.cancelled || res.value === null) {
+                tally.cancelled = true;
+                break rowLoop;
+            }
+            if (res.value === 'all' && offerRest) {
+                for (let k = i; k < rows.length; k++) {
+                    rows[k] = { ...rows[k], confirmed: true };
+                    tally.yes.push(keyOf(rows[k]));
+                }
+                break rowLoop;
+            }
+            if (res.value === 'yes') {
+                rows[i] = { ...r, confirmed: true };
+                tally.yes.push(keyOf(r));
+                settled = true;
+                continue;
+            }
+            if (res.value === 'skip') {
+                tally.skipped.push(keyOf(r));
+                j.skip([keyOf(r)]);
+                settled = true;
+                continue;
+            }
+            if (res.value === 'keep' && canKeep) {
+                if (!r.level) {
+                    j.log(`No level is known for ${type} ${name}, so it cannot be kept as is. Choose Yes or Skip.`);
+                    canKeep = false;
+                    continue;
+                }
+                let said;
+                try {
+                    said = await j.ask(KEEP_QUESTION);
+                }
+                catch {
+                    tally.cancelled = true;
+                    break rowLoop;
+                }
+                const reason = cleanKeepReason(said);
+                if (!reason) {
+                    j.log(`A keep needs a reason. Nothing was recorded for ${type} ${name} yet.`);
+                    continue;
+                }
+                rows[i] = { ...r, disposition: 'exception', targetLevel: null, reason, confirmed: true };
+                tally.kept.push({ key: keyOf(r), type: r.objectType.toUpperCase(), name: r.objectName.toUpperCase(), level: r.level });
+                settled = true;
+            }
+        }
+        // Asked over and over with no usable answer: a Skip, never "answered" with nothing recorded.
+        if (!settled) {
+            j.log('No reason given — skipped for now.');
+            tally.skipped.push(keyOf(r));
+            j.skip([keyOf(r)]);
+        }
+        answered += 1;
+    }
+    const byId = new Map(rows.map((r) => [r.id, r.confirmed]));
+    return {
+        extract: {
+            ...ex,
+            content: { ...ex.content, adjudications: rows },
+            items: ex.items.map((it) => ({ ...it, status: byId.get(it.id) ? 'confirmed' : 'declined' })),
+        },
+        tally,
+    };
+}
+/**
+ * The lines after the rows are written: one per kept row, then the count
+ * ("4 of 5 rows recorded; 1 kept by decision; 0 skipped."). "Recorded" counts
+ * the rows recorded as proposed; a row the project refused is not counted.
+ */
+export function journeyRowLines(t, refused) {
+    const out = new Set(refused.map((k) => k.trim().toUpperCase()));
+    const kept = t.kept.filter((k) => !out.has(k.key));
+    const yes = t.yes.filter((k) => !out.has(k.toUpperCase())).length;
+    return [
+        ...kept.map((k) => `✓ Recorded: ${shown(k.type)} ${shown(k.name)} — kept at ${k.level}, reason recorded.`),
+        `${yes} of ${t.total} rows recorded; ${kept.length} kept by decision; ${t.skipped.length} skipped.`,
+    ];
+}
+/**
+ * The working-list line inside a journey: the person keeps "your list", never
+ * a file name, a team word or a command to type (Task 7). Null: nothing to say.
+ */
+export function journeyListLine(kind) {
+    if (kind === 'updated')
+        return 'Your list is updated.';
+    if (kind === 'held')
+        return 'Your list is open in another program, so it was not updated. Close it; your next decision updates it.';
+    if (kind === 'unreadable')
+        return 'Your list could not be updated: the folder could not be read right now.';
+    return null;
+}
+/** Inside a journey, on a laptop with no project open here (the triage is saved; nothing recorded). */
+export const JOURNEY_NOT_IN_PROJECT_LINE = 'Not recorded: no record is kept in this folder yet.';
+/** Page objects the triage did not answer, in one line: up to five named, then how many more. */
+export function leftOutLine(keys) {
+    const named = keys.slice(0, 5).map((k) => {
+        const [type = '', name = ''] = k.split('|');
+        return `${shown(type)} ${shown(name)}`.trim();
+    });
+    const more = keys.length - named.length;
+    const one = keys.length === 1;
+    return `${keys.length.toLocaleString('en-US')} ${one ? 'object' : 'objects'} on this page ${one ? 'was' : 'were'} not in the triage: `
+        + `${named.join(', ')}${more > 0 ? ` (and ${more.toLocaleString('en-US')} more)` : ''}. Left for later — say carry on to look at them again.`;
+}

package/dist/projects/detail-path.js

@@ -63,10 +63,10 @@ function realOrNull(p) {
 /**
  * The real path of the first candidate that exists, is a regular file, stays
  * inside `<base>/<first two segments of rel>/` after links are followed, and
- * is not denylisted relative to `cwd`. null otherwise.
+ * is not denylisted relative to its own deny root (default `cwd`). null otherwise.
  */
 function firstContained(cands, cwd) {
-    for (const { base, rel, keep } of cands) {
+    for (const { base, rel, keep, denyRoot } of cands) {
         const realBase = realOrNull(path.resolve(base));
         const real = realOrNull(path.join(path.resolve(base), ...rel.split('/')));
         if (!realBase || !real)
@@ -76,7 +76,7 @@ function firstContained(cands, cwd) {
         const inner = path.relative(folder, real);
         if (inner === '' || inner.startsWith('..') || path.isAbsolute(inner))
             continue;
-        if (isDenylistedPath(real, cwd).blocked)
+        if (isDenylistedPath(real, denyRoot ?? cwd).blocked)
             continue;
         try {
             if (!statSync(real).isFile())
@@ -109,7 +109,12 @@ export async function resolveDetailFile(detailPath, domain, cwd) {
     const segs = rel.split('/');
     if (segs[0].toLowerCase() === '.cspeach') {
         try {
-            cands.push({ base: await workspaceFolderFor(cwd), rel: segs.slice(1).join('/'), keep: 1 });
+            // Judged against the folder that holds the workspace `.cspeach` — the
+            // seat work root for a team folder (Task 14 fix round 1), so the seat
+            // opening applies there and a team folder on another drive or share
+            // cannot make the path look foreign; the start folder for a solo folder.
+            const ws = await workspaceFolderFor(cwd);
+            cands.push({ base: ws, rel: segs.slice(1).join('/'), keep: 1, denyRoot: path.dirname(ws) });
         }
         catch { /* no workspace — project root only */ }
     }

package/dist/projects/extract-clean-core.js

@@ -48,6 +48,9 @@ export function extractCleanCoreDecision(markdown) {
                 throw new Error(`${id}: a row needs an object type and a name`);
             if (disposition === 'exception' && !reason)
                 throw new Error(`${id}: an accepted exception needs a reason`);
+            // Spec 2026-10-06 §7: a retire is a candidate the lead confirms; it never travels without what was checked.
+            if (disposition === 'retire' && !reason)
+                throw new Error(`${id}: a retire needs a reason: say what was checked`);
             const moves = disposition === 'fix' || disposition === 'rebuild';
             rows.push({
                 id, objectType: type.toUpperCase(), objectName: name.toUpperCase(), level: letter(level, id), disposition,

package/dist/projects/migration.js

@@ -1,115 +1,14 @@
 /**
- * One-time workspace-default migration prompt.
+ * One-time `.abapforge/` → `.cspeach/` output-namespace migration offer.
  *
- * Why this exists: until 2026-05-07 the default workspace was `~/CSPeach/`
- * — a single global folder per user. As of 2026-05-08 the default is
- * project-rooted (`<git-root>/.cspeach/`), so a consultant working on
- * customer A and customer B no longer has both customers' artefacts
- * piling into one folder.
- *
- * For users with files already in `~/CSPeach/`, the switch needs to ask
- * once: keep the old global, move into the new project, or leave both
- * alone. The answer is recorded in `config.migration_prompted`; the
- * prompt fires exactly once.
- *
- * Three branches:
- *   - "move":         renameSync every artefact from ~/CSPeach/ into the
- *                     resolved project workspace. Old folder cleaned.
- *   - "keep_global":  set workspace_folder = '~/CSPeach', preserving the
- *                     pre-2026-05-08 behaviour for users who liked it.
- *   - "leave":        do nothing — old folder stays as-is, new artefacts
- *                     go to the project workspace. User can manually
- *                     copy whatever they want later.
- *
- * The prompt is interactive (via the supplied async prompt callback);
- * one-shot mode skips it entirely (caller passes a no-op).
+ * The old first-run workspace prompt (2026-05-08, which could pin
+ * `workspace_folder`) was removed 2026-10-08: files now save in the folder
+ * you start in. See workspace-retire.ts for the offer that retires the key.
  */
 import { existsSync, mkdirSync, readdirSync, renameSync, rmdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
-import os from 'node:os';
 import { loadConfig, saveConfig } from '../config/loader.js';
-import { defaultWorkspaceFor } from './workspace.js';
 import { OUTPUT_ROOT, LEGACY_ROOT } from './output-paths.js';
-/**
- * Run the migration prompt if and only if it hasn't run before AND
- * there's actually something to migrate. No-op otherwise. Always sets
- * `migration_prompted: true` after running so the next invocation
- * skips this whole module.
- */
-export async function maybePromptWorkspaceMigration(deps) {
-    const cfg = await loadConfig();
-    if (cfg.migration_prompted === true)
-        return;
-    // If user already pinned workspace_folder, they've already chosen —
-    // mark prompted, skip the dialog. The pin survives.
-    if (cfg.workspace_folder !== undefined && cfg.workspace_folder.trim().length > 0) {
-        await saveConfig({ ...cfg, migration_prompted: true });
-        return;
-    }
-    const oldWorkspace = join(os.homedir(), 'CSPeach');
-    if (!existsSync(oldWorkspace)) {
-        await saveConfig({ ...cfg, migration_prompted: true });
-        return;
-    }
-    let oldFiles;
-    try {
-        oldFiles = readdirSync(oldWorkspace).filter((f) => f.endsWith('.cspeach.json') || f.endsWith('.txt') || f.endsWith('.md'));
-    }
-    catch {
-        await saveConfig({ ...cfg, migration_prompted: true });
-        return;
-    }
-    if (oldFiles.length === 0) {
-        await saveConfig({ ...cfg, migration_prompted: true });
-        return;
-    }
-    const newWorkspace = defaultWorkspaceFor(process.cwd());
-    let choice;
-    try {
-        choice = await deps.prompt({
-            fileCount: oldFiles.length,
-            oldWorkspace,
-            newWorkspace,
-        });
-    }
-    catch {
-        // User Ctrl+C'd the prompt — leave migration_prompted unset so the
-        // dialog re-fires next session. Better than silently committing to
-        // a default they never saw.
-        return;
-    }
-    if (choice === 'move') {
-        try {
-            mkdirSync(newWorkspace, { recursive: true });
-            for (const f of oldFiles) {
-                const src = join(oldWorkspace, f);
-                const dst = join(newWorkspace, f);
-                if (existsSync(dst)) {
-                    deps.log(`(skipping ${f} — already exists in new workspace)`);
-                    continue;
-                }
-                renameSync(src, dst);
-            }
-            deps.log(`Moved ${oldFiles.length} file(s) → ${newWorkspace}`);
-        }
-        catch (err) {
-            deps.log(`Migration failed: ${err.message}. Old folder left untouched.`);
-        }
-    }
-    else if (choice === 'keep_global') {
-        await saveConfig({
-            ...cfg,
-            workspace_folder: oldWorkspace,
-            migration_prompted: true,
-        });
-        deps.log(`Workspace pinned to ${oldWorkspace}.`);
-        return; // saveConfig already done
-    }
-    else {
-        deps.log(`Leaving ${oldWorkspace} alone. New artefacts go to ${newWorkspace}.`);
-    }
-    await saveConfig({ ...cfg, migration_prompted: true });
-}
 /**
  * Recursively move every entry under `srcDir` into `dstDir`, MERGING into
  * existing directories rather than clobbering them. Files that already exist

package/dist/projects/plan-lane.js

@@ -10,10 +10,12 @@
 //   (Review Focus 4).
 // - renderLaneBlock is the <lane_decision> context block for the plan-creation
 //   turn and every resumed phase. It never carries the file path.
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
 import { cardLine } from '../lane/card.js';
 import { canonicalLanePath } from '../lane/paths.js';
 import { getAppFlow } from '../lane/app-flow.js';
-import { laneRootFor } from '../lane/roots.js';
+import { cliHomeRefusal, laneRootFor } from '../lane/roots.js';
 import { LaneShaMismatchError, readPinnedLaneDecision } from '../lane/store.js';
 /** Shown on the plan-creation turn (and at save) when the file no longer matches the card. */
 export const LANE_CHANGED_AT_CREATE = 'The lane decision file changed after you confirmed it. Run /abap-app again.';
@@ -37,24 +39,72 @@ export function validateLaneRecord(rec) {
     return null;
 }
 /**
- * Pinned read + re-validation. Never throws. `cwd` is the caller's folder;
- * the file is read relative to its lane root (I3: the folder that holds the
- * workspace `.cspeach`), the same root the lane card wrote it under.
+ * 2026-10-08 — the folder that holds the plan file's `.cspeach`: the root its
+ * relative pins (`from.lane.path`, `from.specGap.path`) were written against.
+ * Undefined when there is no plan path, or the plan does not sit directly in
+ * a `.cspeach` folder (then it adds no root). Task 14 — also undefined when
+ * that folder is the home folder, holds a CLI home as its `.cspeach`, or sits
+ * in a CLI home (`cspeachRoot()` or `~/.cspeach`), real paths compared —
+ * except exactly the seat working root `<cspeachRoot()>/work/<id>`
+ * (cliHomeRefusal, the lane root rule).
  */
-export async function readPlanLane(cwd, ref) {
-    let rec;
+export function planRootOf(planPath) {
+    if (!planPath)
+        return undefined;
+    const dir = path.dirname(path.resolve(planPath));
+    if (path.basename(dir).toLowerCase() !== '.cspeach')
+        return undefined;
+    const root = path.dirname(dir);
+    return cliHomeRefusal(root) === null ? root : undefined;
+}
+/** Candidate roots for a plan's pins: the plan's own root first, then the current rule. */
+export async function planPinRoots(cwd, planPath) {
+    const roots = [planRootOf(planPath), await laneRootFor(cwd)];
+    return roots.filter((r, i, a) => !!r && a.indexOf(r) === i);
+}
+/**
+ * Pinned read + re-validation. Never throws. `cwd` is the caller's folder.
+ * The file is read relative to the plan file's own root (`planPath`, the
+ * folder holding its `.cspeach`) first, then the lane root for cwd (the
+ * folder that holds the working `.cspeach`). The first root that HAS the file
+ * decides: a changed (sha mismatch) or refused file there is final — never
+ * fall through to another root past it.
+ */
+export async function readPlanLane(cwd, ref, planPath) {
+    const rel = canonicalLanePath(ref.path);
+    const roots = await planPinRoots(cwd, planPath);
+    let lastErr;
+    for (let i = 0; i < roots.length; i++) {
+        const root = roots[i];
+        const isLast = i === roots.length - 1;
+        // Only a root without the file is skipped; any other outcome there is final.
+        if (!isLast && !(await entryExists(path.resolve(root, rel))))
+            continue;
+        let rec;
+        try {
+            rec = await readPinnedLaneDecision(root, rel, ref.sha256);
+        }
+        catch (e) {
+            if (e instanceof LaneShaMismatchError)
+                return { ok: false, mismatch: true, message: e.message };
+            lastErr = e;
+            break;
+        }
+        const bad = validateLaneRecord(rec);
+        if (bad)
+            return { ok: false, mismatch: false, message: `The lane decision file ${cardLine(rel)} is not valid: ${bad}` };
+        return { ok: true, rec };
+    }
+    return { ok: false, mismatch: false, message: cardLine(lastErr instanceof Error ? lastErr.message : String(lastErr)) };
+}
+async function entryExists(abs) {
     try {
-        rec = await readPinnedLaneDecision(await laneRootFor(cwd), canonicalLanePath(ref.path), ref.sha256);
+        await fs.lstat(abs);
+        return true;
     }
-    catch (e) {
-        if (e instanceof LaneShaMismatchError)
-            return { ok: false, mismatch: true, message: e.message };
-        return { ok: false, mismatch: false, message: cardLine(e instanceof Error ? e.message : String(e)) };
+    catch {
+        return false;
     }
-    const bad = validateLaneRecord(rec);
-    if (bad)
-        return { ok: false, mismatch: false, message: `The lane decision file ${cardLine(canonicalLanePath(ref.path))} is not valid: ${bad}` };
-    return { ok: true, rec };
 }
 /**
  * Controller ruling R5 — per-lane whitelist of delegate x layer. A phase whose
@@ -160,11 +210,11 @@ export function checkRequiredDeploy(content, rec) {
  * re-validate it and check the stored phases against it. Lane-less plans pass
  * with no record. On failure, `lines` is what to print; the plan is paused.
  */
-export async function loadPlanLaneForRun(cwd, content) {
+export async function loadPlanLaneForRun(cwd, content, planPath) {
     const ref = content.from.lane;
     if (!ref)
         return { ok: true };
-    const lr = await readPlanLane(cwd, ref);
+    const lr = await readPlanLane(cwd, ref, planPath);
     if (!lr.ok) {
         return { ok: false, lines: [lr.mismatch ? laneChangedOnResume(ref.path) : `${lr.message} The plan is paused.`] };
     }

package/dist/projects/plan-sources.js

@@ -26,6 +26,7 @@ import { readProjectFile } from './status.js';
 import { buildPromotedFromSnapshot } from './promote.js';
 import { assertRealPathContained } from '../tools/_filesystem-shared.js';
 import { laneRootFor, workspaceFolderFor } from '../lane/roots.js';
+import { planRootOf } from './plan-lane.js';
 /** A spec-gap envelope file name (`...spec-gap-<4hex>-v<N>[-n].cspeach.json`). */
 const SPEC_GAP_FILE_RE = /-spec-gap-[0-9a-f]{4}-v\d+(?:-\d+)?\.cspeach\.json$/i;
 /** Path relative to `root` ('/'-separated) when inside it, else absolute. */
@@ -64,25 +65,30 @@ async function containedIn(abs, root) {
 }
 /**
  * Find and read the plan's spec-gap file. Candidates: `from.specGap.path`,
- * then the lane decision's `specGap.path`; each resolved against the project
+ * then the lane decision's `specGap.path`; each resolved against the plan
+ * file's own root (the folder holding its `.cspeach`, 2026-10-08), the project
  * folder and cwd. A candidate is used only when it is a spec-gap file name,
- * sits (real path) inside cwd or the workspace folder, parses as a spec-gap
+ * sits (real path) inside cwd, the workspace folder, the project folder or
+ * the plan's root, parses as a spec-gap
  * envelope, and — when the plan holds a promotedFrom snapshot — is the SAME
  * envelope (id match). Returns undefined when none qualifies.
  */
-async function readLiveSpecGap(cwd, content, promotedFrom, laneRecord) {
+async function readLiveSpecGap(cwd, content, promotedFrom, laneRecord, planPath) {
     const recorded = [content.from.specGap?.path, laneRecord?.specGap?.path]
         .filter((p) => typeof p === 'string' && p.trim() !== '');
     if (recorded.length === 0)
         return undefined;
     const root = await laneRootFor(cwd).catch(() => path.resolve(cwd));
     const ws = await workspaceFolderFor(cwd).catch(() => undefined);
+    const planRoot = planRootOf(planPath);
+    const bases = [planRoot, root, path.resolve(cwd)].filter((b, i, a) => !!b && a.indexOf(b) === i);
     for (const rec of recorded) {
         if (!SPEC_GAP_FILE_RE.test(path.basename(rec)))
             continue;
-        for (const base of [root, path.resolve(cwd)]) {
+        for (const base of bases) {
             const abs = path.resolve(base, rec);
-            if (!(await containedIn(abs, cwd)) && !(await containedIn(abs, ws)) && !(await containedIn(abs, root)))
+            if (!(await containedIn(abs, cwd)) && !(await containedIn(abs, ws)) && !(await containedIn(abs, root)) &&
+                !(await containedIn(abs, planRoot)))
                 continue;
             let env;
             try {
@@ -95,7 +101,7 @@ async function readLiveSpecGap(cwd, content, promotedFrom, laneRecord) {
                 continue;
             if (promotedFrom && promotedFrom.id !== env.id)
                 continue;
-            return { env, shownPath: relOrAbs(root, abs) };
+            return { env, shownPath: relOrAbs(base === planRoot ? planRoot : root, abs) };
         }
     }
     return undefined;
@@ -109,7 +115,7 @@ export async function resolvePlanSources(args) {
     const pf = args.envelope.promotedFrom && args.envelope.promotedFrom.artefactType === 'spec-gap'
         ? args.envelope.promotedFrom : null;
     try {
-        const live = await readLiveSpecGap(args.cwd, args.content, pf, args.laneRecord);
+        const live = await readLiveSpecGap(args.cwd, args.content, pf, args.laneRecord, args.planPath);
         if (live) {
             const snap = await buildPromotedFromSnapshot(live.env);
             const createdSha = args.content.from.specGap?.sha256 ?? pf?.sha256;