peaks-cli 1.3.1 → 1.3.2

package/dist/src/services/slice/slice-check-types.d.ts

@@ -58,4 +58,13 @@ export type SliceCheckOptions = {
      * tests (e.g. a docs-only or config-only slice).
      */
     skipTests: boolean;
+    /**
+     * When true, an `unit-tests` stage that fails is reported as `skipped`
+     * (with a `reason` naming the pre-existing failure count) instead of
+     * `failed`. Used to opt in to bypassing the 28 pre-existing Windows
+     * test failures documented in dogfood-2-f1-f4.md F17. Does NOT affect
+     * the other 3 stages (typecheck / review-fanout / gate-verify-pipeline).
+     * Default: false. The service treats `undefined` the same as `false`.
+     */
+    allowPreExistingFailures?: boolean;
 };

package/dist/src/services/workspace/migrate-service.js

@@ -1,5 +1,5 @@
 import { execFileSync } from 'node:child_process';
-import { mkdir, readFile, readdir, rm } from 'node:fs/promises';
+import { mkdir, readFile, readdir, rename, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isDirectory, pathExists } from '../../shared/fs.js';
 import { isPathInsideArtifactRoot, validateChangeIdOrThrow } from '../../shared/change-id.js';
@@ -325,6 +325,107 @@ async function planSession(sessionId, sessionPath) {
     }
     return { sessionId, path: sessionPath, empty: empty && plans.every((p) => p.skipped), files: plans, fallbackChangeId: fallback };
 }
+/**
+ * Slice 003 (2026-06-06-session-layout-canonicalize): one-shot
+ * consolidation of every top-level `.peaks/<sid>/` into
+ * `.peaks/_runtime/<sid>/`. Idempotent:
+ *
+ *   - If `.peaks/_runtime/<sid>/` does not exist → `fs.rename` the
+ *     top-level dir to the runtime location.
+ *   - If `.peaks/_runtime/<sid>/` already exists with the same
+ *     content → no-op, reported as `skipped-already-canonical`.
+ *   - If `.peaks/_runtime/<sid>/` already exists with different
+ *     content → log a conflict, do NOT overwrite.
+ *   - **F15 carve-out**: if `<sid>/rd/project-scan.md` differs from
+ *     the runtime copy already in place, log a
+ *     `f15-conflict-project-scan` and leave the file in place.
+ *
+ * Path-traversal is impossible because the target is always
+ * `peaks/_runtime/<sid>/` and the directory listing only returns
+ * names matching the session-id regex.
+ */
+async function migrateToRuntime(projectRoot, peaksRoot, apply) {
+    void projectRoot;
+    const plans = [];
+    const moved = [];
+    const skipped = [];
+    const conflicts = [];
+    const runtimeRoot = join(peaksRoot, '_runtime');
+    let topLevelEntries;
+    try {
+        topLevelEntries = await readdir(peaksRoot, { withFileTypes: true });
+    }
+    catch {
+        return { plans, moved, skipped, conflicts };
+    }
+    for (const entry of topLevelEntries) {
+        if (!entry.isDirectory())
+            continue;
+        if (PROTECTED_TOP_LEVEL_DIRS.has(entry.name))
+            continue;
+        if (!/^\d{4}-\d{2}-\d{2}-session-/.test(entry.name))
+            continue;
+        const sessionId = entry.name;
+        const fromPath = join(peaksRoot, sessionId);
+        const toPath = join(runtimeRoot, sessionId);
+        if (await isDirectory(toPath)) {
+            // F15 carve-out check
+            const fromScan = join(fromPath, 'rd', 'project-scan.md');
+            const toScan = join(toPath, 'rd', 'project-scan.md');
+            if (await pathExists(fromScan) && await pathExists(toScan)) {
+                const fromContent = await readFile(fromScan, 'utf8').catch(() => null);
+                const toContent = await readFile(toScan, 'utf8').catch(() => null);
+                if (fromContent !== null && toContent !== null && fromContent !== toContent) {
+                    plans.push({
+                        from: fromPath,
+                        to: toPath,
+                        sessionId,
+                        action: 'f15-conflict-project-scan',
+                        reason: 'F15 carve-out: top-level rd/project-scan.md differs from runtime copy; left in place.'
+                    });
+                    conflicts.push({
+                        from: fromScan,
+                        to: toScan,
+                        reason: 'f15-conflict-project-scan'
+                    });
+                    continue;
+                }
+            }
+            plans.push({
+                from: fromPath,
+                to: toPath,
+                sessionId,
+                action: 'skipped-already-canonical',
+                reason: 'target _runtime/<sid>/ already exists'
+            });
+            skipped.push(sessionId);
+            continue;
+        }
+        plans.push({
+            from: fromPath,
+            to: toPath,
+            sessionId,
+            action: 'moved',
+            reason: 'top-level session dir will be moved to _runtime/'
+        });
+        if (apply) {
+            try {
+                await mkdir(runtimeRoot, { recursive: true });
+                await rename(fromPath, toPath);
+                moved.push(sessionId);
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                conflicts.push({
+                    from: fromPath,
+                    to: toPath,
+                    reason: `rename failed: ${msg}`
+                });
+            }
+        }
+    }
+    return { plans, moved, skipped, conflicts };
+}
 async function gitMv(from, to, projectRoot) {
     const parentDir = join(to, '..');
     await mkdir(parentDir, { recursive: true });
@@ -470,6 +571,23 @@ export async function migrateWorkspace(options) {
             deletedSessions.push(session.sessionId);
         }
     }
+    // Slice 003: the `--to-runtime` step. When set, move every
+    // top-level `.peaks/<sid>/` to `.peaks/_runtime/<sid>/`. Idempotent.
+    // The F15 carve-out (rd/project-scan.md) is honored: when the
+    // top-level `<sid>/rd/project-scan.md` differs from the runtime
+    // `<sid>/rd/project-scan.md` already in place, the file is
+    // left at the top-level and a conflict is recorded.
+    let toRuntimePlans = [];
+    let toRuntimeMoved = [];
+    let toRuntimeSkipped = [];
+    let toRuntimeConflicts = [];
+    if (options.toRuntime === true) {
+        const result = await migrateToRuntime(options.projectRoot, peaksRoot, options.apply);
+        toRuntimePlans = result.plans;
+        toRuntimeMoved = result.moved;
+        toRuntimeSkipped = result.skipped;
+        toRuntimeConflicts = result.conflicts;
+    }
     return {
         projectRoot: options.projectRoot,
         sessions: sessionPlans,
@@ -479,6 +597,10 @@ export async function migrateWorkspace(options) {
         wouldDeleteSessions: wouldDeleteSessions,
         conflicts,
         apply: options.apply,
-        totalFilesMoved: options.apply ? moved.length : 0
+        totalFilesMoved: options.apply ? moved.length : 0,
+        toRuntimePlans,
+        toRuntimeMoved,
+        toRuntimeSkipped,
+        toRuntimeConflicts
     };
 }

package/dist/src/services/workspace/migrate-types.d.ts

@@ -53,14 +53,48 @@ export type MigrateSessionPlan = {
     /** The fallback change-id derived from the session's most recent `rd/requests/` entry. Null if no requests exist. */
     fallbackChangeId: string | null;
 };
+export type MigrateOptions = {
+    projectRoot: string;
+    /** When true, actually `git mv` the files + `rm -rf` the emptied session dirs. */
+    apply: boolean;
+    /**
+     * Slice 003 (2026-06-06-session-layout-canonicalize): when true, the
+     * command performs the **session-dir consolidation** — moves every
+     * top-level `.peaks/<sid>/` to `.peaks/_runtime/<sid>/`. Idempotent;
+     * conflicts (target exists with different content) are logged but
+     * never overwrite. With `apply: false` (the default), the response
+     * lists what WOULD move + the conflicts.
+     *
+     * Mutually exclusive with the reviewable-content migration: the
+     * `--to-runtime` step is the data side of slice 003, while the
+     * default `migrate` step is the cross-cutting content side
+     * (reviewable files → retrospective). Both run when both flags are
+     * set; the order is `--to-runtime` first (so the cross-cutting
+     * step sees the canonical tree) and then the reviewable-content
+     * step.
+     */
+    toRuntime?: boolean;
+};
+export type MigrateToRuntimeFilePlan = {
+    /** Absolute source path (top-level `.peaks/<sid>/`). */
+    from: string;
+    /** Absolute target path (`.peaks/_runtime/<sid>/`). */
+    to: string;
+    /** The session id the dir belongs to. */
+    sessionId: string;
+    /** 'moved' or 'skipped-already-canonical' or 'conflict'. */
+    action: 'moved' | 'skipped-already-canonical' | 'conflict-target-exists-with-different-content' | 'f15-conflict-project-scan';
+    /** Human-readable reason for the action (for the conflicts list). */
+    reason: string;
+};
 export type MigrateResult = {
     /** Absolute project root the command operated on. */
     projectRoot: string;
     /** All discovered legacy session dirs, sorted by name. */
     sessions: MigrateSessionPlan[];
-    /** All moves the apply step WOULD perform (only populated when `apply === false` as well, for symmetry). */
+    /** All moves the apply step WOULD perform (only populated when `apply: false` as well, for symmetry). */
     wouldMove: MigrateFilePlan[];
-    /** All moves actually performed (only populated when `apply === true`). */
+    /** All moves actually performed (only populated when `apply: true`). */
     moved: MigrateFilePlan[];
     /** Sessions that became empty after the move and were/will be removed. */
     deletedSessions: string[];
@@ -76,9 +110,18 @@ export type MigrateResult = {
     apply: boolean;
     /** Total files moved or scheduled to move. */
     totalFilesMoved: number;
-};
-export type MigrateOptions = {
-    projectRoot: string;
-    /** When true, actually `git mv` the files + `rm -rf` the emptied session dirs. */
-    apply: boolean;
+    /**
+     * Slice 003: per-session-dir move plans for the `--to-runtime` step.
+     * Empty when `toRuntime` was not set. Conflicts include both the
+     * top-level/<sid>/ → _runtime/<sid>/ collisions AND the F15 carve-out
+     * for `rd/project-scan.md`.
+     */
+    toRuntimePlans?: MigrateToRuntimeFilePlan[];
+    toRuntimeMoved?: string[];
+    toRuntimeSkipped?: string[];
+    toRuntimeConflicts?: Array<{
+        from: string;
+        to: string;
+        reason: string;
+    }>;
 };

package/dist/src/services/workspace/reconcile-service.d.ts

@@ -75,6 +75,39 @@ export declare function applyDeletions(candidates: SessionEntry[], apply: boolea
         message: string;
     }>;
 };
+/**
+ * Sync the single `change/<canonicalSessionId>/` live marker under
+ * `.peaks/_runtime/change/`. The marker is an EMPTY directory (no
+ * symlinks, no manifest, no content). Slice 006 collapses the F3
+ * per-change-id symlink layer to a single live marker so the
+ * `change/` layer is a single sentinel — easy for the LLM to
+ * navigate, easy for tests to assert on.
+ *
+ * Steps:
+ *   1. Ensure `.peaks/_runtime/change/` exists.
+ *   2. List its entries.
+ *   3. Remove every entry whose name is NOT `<canonicalSessionId>/`
+ *      (no-op for those whose name matches).
+ *   4. If `<canonicalSessionId>/` is missing, create it (empty).
+ *   5. Return the diff for telemetry.
+ *
+ * Path-traversal guards: the canonical session id is validated by
+ * the caller (`SESSION_ID_PATTERN` in the session-manager helper).
+ * The function only ever operates under the project-root-resolved
+ * `.peaks/_runtime/change/` dir, so the resolved paths cannot
+ * escape the project tree.
+ *
+ * @returns `{ removed, created, error }`:
+ *   - `removed`: list of entry names that were deleted (e.g. `['<oldSid>/']`).
+ *   - `created`: name of the new marker (e.g. `'<newSid>/'`) or null
+ *     when the canonical marker already existed (no-op).
+ *   - `error`: error message string or null.
+ */
+export declare function syncChangeMarker(projectRoot: string, canonicalSessionId: string): {
+    removed: string[];
+    created: string | null;
+    error: string | null;
+};
 /**
  * One-time migration step (added in slice 2026-06-05-peaks-runtime-layer).
  *

package/dist/src/services/workspace/reconcile-service.js

@@ -55,59 +55,75 @@ function runtimeNewBasename(oldBasename) {
  * of files under the dir excluding `session.json` itself.
  */
 export function discoverSessions(projectRoot) {
+    const runtimeRoot = join(projectRoot, '.peaks', '_runtime');
     const peaksRoot = join(projectRoot, '.peaks');
-    if (!existsSync(peaksRoot))
-        return [];
-    let names;
-    try {
-        names = readdirSync(peaksRoot);
-    }
-    catch {
-        return [];
-    }
+    // As of slice 003, the canonical home for session dirs is
+    // `.peaks/_runtime/<sid>/`. The legacy top-level layout is
+    // read for back-compat (one minor release) so pre-migration
+    // trees keep working. Both are scanned; duplicates (same sid
+    // in both homes) are de-duplicated with the canonical home
+    // winning.
+    const seen = new Set();
     const entries = [];
-    for (const name of names) {
-        if (!SESSION_ID_PATTERN.test(name))
-            continue;
-        const dir = join(peaksRoot, name);
-        let stat;
+    const collect = (root) => {
+        if (!existsSync(root))
+            return;
+        let names;
         try {
-            // lstatSync: false for symlinks (prevents rm -rf from following a
-            // malicious symlink that points outside the project root).
-            stat = lstatSync(dir);
+            names = readdirSync(root);
         }
         catch {
-            continue;
+            return;
         }
-        if (!stat.isDirectory())
-            continue;
-        const metaPath = join(dir, META_FILE);
-        let lastActivity = null;
-        if (existsSync(metaPath)) {
-            try {
-                lastActivity = statSync(metaPath).mtimeMs;
-            }
-            catch {
-                lastActivity = null;
-            }
+        for (const name of names) {
+            if (!SESSION_ID_PATTERN.test(name))
+                continue;
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            scanSessionDir(root, name, entries);
         }
-        let childNames;
+    };
+    collect(runtimeRoot);
+    collect(peaksRoot);
+    entries.sort((a, b) => a.sessionId.localeCompare(b.sessionId));
+    return entries;
+}
+function scanSessionDir(peaksRoot, name, entries) {
+    const dir = join(peaksRoot, name);
+    let stat;
+    try {
+        stat = lstatSync(dir);
+    }
+    catch {
+        return;
+    }
+    if (!stat.isDirectory())
+        return;
+    const metaPath = join(dir, META_FILE);
+    let lastActivity = null;
+    if (existsSync(metaPath)) {
         try {
-            childNames = readdirSync(dir);
+            lastActivity = statSync(metaPath).mtimeMs;
         }
         catch {
-            childNames = [];
+            lastActivity = null;
         }
-        let artifactCount = 0;
-        for (const child of childNames) {
-            if (child === META_FILE)
-                continue;
-            artifactCount += 1;
-        }
-        entries.push({ sessionId: name, path: dir, lastActivity, artifactCount });
     }
-    entries.sort((a, b) => a.sessionId.localeCompare(b.sessionId));
-    return entries;
+    let childNames;
+    try {
+        childNames = readdirSync(dir);
+    }
+    catch {
+        childNames = [];
+    }
+    let artifactCount = 0;
+    for (const child of childNames) {
+        if (child === META_FILE)
+            continue;
+        artifactCount += 1;
+    }
+    entries.push({ sessionId: name, path: dir, lastActivity, artifactCount });
 }
 /**
  * 4-tier canonical selection. Tiers evaluated in order; first one that
@@ -299,6 +315,76 @@ function readActiveSkillSessionId(projectRoot) {
     }
     return null;
 }
+/**
+ * Sync the single `change/<canonicalSessionId>/` live marker under
+ * `.peaks/_runtime/change/`. The marker is an EMPTY directory (no
+ * symlinks, no manifest, no content). Slice 006 collapses the F3
+ * per-change-id symlink layer to a single live marker so the
+ * `change/` layer is a single sentinel — easy for the LLM to
+ * navigate, easy for tests to assert on.
+ *
+ * Steps:
+ *   1. Ensure `.peaks/_runtime/change/` exists.
+ *   2. List its entries.
+ *   3. Remove every entry whose name is NOT `<canonicalSessionId>/`
+ *      (no-op for those whose name matches).
+ *   4. If `<canonicalSessionId>/` is missing, create it (empty).
+ *   5. Return the diff for telemetry.
+ *
+ * Path-traversal guards: the canonical session id is validated by
+ * the caller (`SESSION_ID_PATTERN` in the session-manager helper).
+ * The function only ever operates under the project-root-resolved
+ * `.peaks/_runtime/change/` dir, so the resolved paths cannot
+ * escape the project tree.
+ *
+ * @returns `{ removed, created, error }`:
+ *   - `removed`: list of entry names that were deleted (e.g. `['<oldSid>/']`).
+ *   - `created`: name of the new marker (e.g. `'<newSid>/'`) or null
+ *     when the canonical marker already existed (no-op).
+ *   - `error`: error message string or null.
+ */
+export function syncChangeMarker(projectRoot, canonicalSessionId) {
+    const root = resolve(projectRoot);
+    const changeDir = join(root, '.peaks', '_runtime', 'change');
+    const removed = [];
+    let created = null;
+    let error = null;
+    try {
+        if (!existsSync(changeDir)) {
+            mkdirSync(changeDir, { recursive: true });
+        }
+        const markerPath = join(changeDir, canonicalSessionId);
+        let existingNames = [];
+        try {
+            existingNames = readdirSync(changeDir);
+        }
+        catch {
+            existingNames = [];
+        }
+        for (const name of existingNames) {
+            if (name === canonicalSessionId)
+                continue;
+            const stale = join(changeDir, name);
+            try {
+                rmSync(stale, { recursive: true, force: true });
+                removed.push(name);
+            }
+            catch (e) {
+                // Best-effort: a single un-deletable entry must not abort the
+                // sync (the caller gets the rest of the diff).
+                error = e instanceof Error ? e.message : String(e);
+            }
+        }
+        if (!existsSync(markerPath)) {
+            mkdirSync(markerPath, { recursive: true });
+            created = canonicalSessionId;
+        }
+    }
+    catch (e) {
+        error = e instanceof Error ? e.message : String(e);
+    }
+    return { removed, created, error };
+}
 /**
  * One-time migration step (added in slice 2026-06-05-peaks-runtime-layer).
  *
@@ -445,6 +531,36 @@ export function reconcileWorkspace(options) {
     }
     const deletionCandidates = findDeletionCandidates(sessions, ageThresholdMs);
     const deletionResult = applyDeletions(deletionCandidates, apply);
+    // Slice 006: sync the single `change/<canonicalSessionId>/` live
+    // marker (replaces the F3 per-change-id symlink layer). The marker
+    // is an empty dir; the function removes every other entry under
+    // `.peaks/_runtime/change/`. Idempotent. This step is independent
+    // of the apply flag — syncing the marker is a derived-state write,
+    // not a destructive side effect.
+    const changeMarker = canonical === null
+        ? { removed: [], created: null, error: 'no canonical session' }
+        : syncChangeMarker(projectRoot, canonical.sessionId);
+    // Slice 006: clean up the F3-introduced `.peaks/_runtime/<sid>/system/`
+    // subdir under EVERY session dir (not just the canonical one). The
+    // subdir was created eagerly by `initWorkspace` (F3) but was never
+    // used. The cleanup is idempotent: re-running on a tree without the
+    // subdir is a no-op. We walk every discovered session, not just the
+    // canonical one, because the user has 6 F3 sessions with the cruft
+    // and the spec says all of them must be removed. Logged in the
+    // systemCleaned array.
+    const systemCleaned = [];
+    for (const session of sessions) {
+        const systemDir = join(session.path, 'system');
+        if (existsSync(systemDir)) {
+            try {
+                rmSync(systemDir, { recursive: true, force: true });
+                systemCleaned.push(systemDir);
+            }
+            catch {
+                // Best-effort: a locked subdir does not block the rest of reconcile.
+            }
+        }
+    }
     return {
         projectRoot,
         sessions,
@@ -459,6 +575,8 @@ export function reconcileWorkspace(options) {
         apply,
         repointed,
         migratedFiles: migration.migratedFiles,
-        errors: [...migrateErrors, ...deletionResult.errors]
+        errors: [...migrateErrors, ...deletionResult.errors],
+        changeMarker,
+        systemCleaned
     };
 }

package/dist/src/services/workspace/reconcile-types.d.ts

@@ -78,6 +78,31 @@ export type ReconcileResult = {
         path: string;
         message: string;
     }>;
+    /**
+     * Slice 006 (2026-06-06-change-folder-simplify-and-lazy-role-subdirs):
+     * result of syncing the single `change/<canonicalSessionId>/` live
+     * marker under `.peaks/_runtime/change/`. The marker is an empty
+     * directory; every other entry under `change/` is removed. The
+     * `removed` array lists entry names that were deleted (e.g.
+     * `['<oldSid>/']`); `created` is the name of the new marker (or
+     * `null` when the canonical marker already existed — no-op);
+     * `error` is the first error message (if any) encountered during
+     * the sync. Additive — older consumers can ignore this field.
+     * Replaces the F3 `changeLinks` field.
+     */
+    changeMarker: {
+        removed: string[];
+        created: string | null;
+        error: string | null;
+    };
+    /**
+     * Slice 006: list of absolute paths to `.peaks/_runtime/<sid>/system/`
+     * subdirs that were removed by this reconcile run. The F3
+     * `initWorkspace` eagerly created the `system/` subdir; slice 006
+     * deletes it during reconcile. Empty when the canonical session
+     * had no `system/` subdir. Additive.
+     */
+    systemCleaned: string[];
 };
 export type ReconcileOptions = {
     projectRoot: string;