peaks-loop 3.0.0

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

@@ -0,0 +1,127 @@
+/**
+ * Type envelope for the `peaks workspace migrate` CLI command.
+ *
+ * The migrate command is the downstream-project counterpart to the
+ * one-time Phase 5 migration script that ran on the peaks-cli self-host
+ * for slice 2026-06-05-change-id-as-unit-of-work. Where
+ * `peaks workspace reconcile` only handles the top-level runtime state
+ * files (`.peaks/.session.json`, `.peaks/.active-skill.json`,
+ * `.peaks/sop-state/` → `.peaks/_runtime/`), `peaks workspace migrate`
+ * handles the much bigger case: legacy reviewable content under
+ * `.peaks/_runtime/<session-id>/<role>/<file>` → `.peaks/retrospective/<change-id>/<role>/<file>`.
+ *
+ * Each legacy session dir typically contains multiple change-ids worth
+ * of work (the old layout allowed one session to host several slices).
+ * Change-id resolution uses a 4-tier per-file heuristic (filename
+ * regex → content H1 → body frontmatter → per-session fallback to the
+ * most-recent `<change-id>` in `rd/requests/`).
+ *
+ * Types are hand-rolled, no new top-level dependencies.
+ */
+export type MigrateFilePlan = {
+    /** Absolute source path (under `.peaks/_runtime/<session-id>/...`). */
+    from: string;
+    /** Absolute target path (under `.peaks/retrospective/<change-id>/...`). */
+    to: string;
+    /** The session dir this file came from. */
+    sessionId: string;
+    /** The session-id the file is being routed to (target dir under `.peaks/retrospective/<target-session-id>/<role>/`). */
+    targetSessionId: string;
+    /** The role inferred from the file's path (rd/qa/prd/ui/sc). */
+    role: 'prd' | 'ui' | 'rd' | 'qa' | 'sc' | 'system' | 'unknown';
+    /** Path of the file relative to the session dir, e.g. `rd/tech-doc.md`. */
+    relativePath: string;
+    /**
+     * Which tier of the 4-tier heuristic produced the change-id. Null
+     * when the file is not a per-slice artifact (e.g. cross-cutting
+     * `rd/project-scan.md` or `qa/.initiated`).
+     */
+    source: 'filename-regex' | 'content-h1' | 'content-frontmatter' | 'session-fallback' | 'cross-cutting' | null;
+    /** True if the file was skipped (e.g. `session.json`, cross-cutting, conflict). */
+    skipped?: boolean;
+    /** Why the file was skipped (only set when `skipped === true`). */
+    skipReason?: 'transient-runtime' | 'conflict' | 'no-change-id' | 'unsupported-role';
+};
+export type MigrateSessionPlan = {
+    sessionId: string;
+    /** Absolute path to the session dir. */
+    path: string;
+    /** True if the dir is empty / only has `session.json`. */
+    empty: boolean;
+    /** All files in the dir, planned. */
+    files: MigrateFilePlan[];
+    /** 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/_runtime/<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/_runtime/<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). */
+    wouldMove: MigrateFilePlan[];
+    /** 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[];
+    /** Sessions that WOULD become empty (dry-run only). */
+    wouldDeleteSessions: string[];
+    /** Files that already exist at the target (collision). Dry-run reports; apply skips + warns. */
+    conflicts: Array<{
+        from: string;
+        to: string;
+        reason: string;
+    }>;
+    /** Whether `--apply` was set. */
+    apply: boolean;
+    /** Total files moved or scheduled to move. */
+    totalFilesMoved: number;
+    /**
+     * 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/migrate-types.js

@@ -0,0 +1,21 @@
+/**
+ * Type envelope for the `peaks workspace migrate` CLI command.
+ *
+ * The migrate command is the downstream-project counterpart to the
+ * one-time Phase 5 migration script that ran on the peaks-cli self-host
+ * for slice 2026-06-05-change-id-as-unit-of-work. Where
+ * `peaks workspace reconcile` only handles the top-level runtime state
+ * files (`.peaks/.session.json`, `.peaks/.active-skill.json`,
+ * `.peaks/sop-state/` → `.peaks/_runtime/`), `peaks workspace migrate`
+ * handles the much bigger case: legacy reviewable content under
+ * `.peaks/_runtime/<session-id>/<role>/<file>` → `.peaks/retrospective/<change-id>/<role>/<file>`.
+ *
+ * Each legacy session dir typically contains multiple change-ids worth
+ * of work (the old layout allowed one session to host several slices).
+ * Change-id resolution uses a 4-tier per-file heuristic (filename
+ * regex → content H1 → body frontmatter → per-session fallback to the
+ * most-recent `<change-id>` in `rd/requests/`).
+ *
+ * Types are hand-rolled, no new top-level dependencies.
+ */
+export {};

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

@@ -0,0 +1,188 @@
+/**
+ * Reconcile service for `.peaks/2026-MM-DD-session-<6hex>/` directories.
+ *
+ * Reconcile scans the project root's `.peaks/` directory, identifies a
+ * canonical session via a 4-tier heuristic, re-points
+ * `.peaks/_runtime/session.json` (the canonical new home of the
+ * binding; legacy `.peaks/.session.json` is read-only back-compat),
+ * and (optionally, with apply === true) deletes empty / abandoned
+ * session dirs older than olderThanMs.
+ *
+ * As of slice 2026-06-05-peaks-runtime-layer the top-level orchestrator
+ * also runs `migrateOldRuntimeState` at the start so pre-migration
+ * trees have their `.peaks/.session.json` / `.peaks/.active-skill.json`
+ * / `.peaks/sop-state/` files moved into `.peaks/_runtime/`.
+ *
+ * Pure hand-rolled; uses only node:fs, node:path, and the existing
+ * session-manager helper for writing the binding. No new dependencies.
+ */
+import type { ReconcileOptions, ReconcileResult, SessionEntry } from './reconcile-types.js';
+/**
+ * Walk the project root's `.peaks/` directory and return an entry per
+ * session dir matching the standard naming pattern, sorted by name
+ * ascending (the most recent is last by sort order, since the date
+ * prefix dominates the lexicographic order).
+ *
+ * Each entry's `lastActivity` is the mtime of the inner `session.json`
+ * file, or null if that file is missing. `artifactCount` is the count
+ * of files under the dir excluding `session.json` itself.
+ */
+export declare function discoverSessions(projectRoot: string): SessionEntry[];
+/**
+ * 4-tier canonical selection. Tiers evaluated in order; first one that
+ * yields a session id wins.
+ *
+ *   1. active-skill sessionId, if it matches a real entry
+ *   2. entry with the most recent `session.json` mtime
+ *   3. entry with the most recent mtime of any file inside it
+ *   4. entry whose dir name sorts last lexicographically
+ */
+export declare function pickCanonicalSession(entries: SessionEntry[], activeSkillSessionId: string | null): {
+    sessionId: string;
+    source: ReconcileResult['canonicalSource'];
+} | null;
+/**
+ * Write `.peaks/.session.json` to bind the project to `canonicalSessionId`.
+ * Preserves the projectRoot. The previous binding is returned so the CLI
+ * can surface the re-point delta.
+ */
+export declare function repointSessionJson(projectRoot: string, canonicalSessionId: string, repointedFrom: string | null): {
+    repointedFrom: string | null;
+    repointedTo: string;
+};
+/**
+ * Identify deletion candidates. A session is a candidate when:
+ *   - the resolved `lastActivity` is older than `ageThresholdMs`, AND
+ *   - the dir is "empty or auto-only" (artifactCount === 0, OR the
+ *     only file is `session.json` which is auto-generated).
+ *
+ * If `lastActivity` is null (no `session.json` inside), the session's
+ * own dir mtime is used as a fallback so empty dirs without inner
+ * metadata are still fair-game.
+ */
+export declare function findDeletionCandidates(entries: SessionEntry[], ageThresholdMs: number): SessionEntry[];
+/**
+ * Apply or report deletion of the given candidates. When `apply` is
+ * false, just return `wouldDelete` and do not touch disk. When `apply`
+ * is true, actually `rm -rf` each dir and accumulate any per-dir
+ * errors in the result.
+ */
+export declare function applyDeletions(candidates: SessionEntry[], apply: boolean): {
+    deleted: string[];
+    wouldDelete: string[];
+    errors: Array<{
+        sessionId: string;
+        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).
+ *
+ * Move the legacy runtime files at:
+ *   - `.peaks/.session.json`
+ *   - `.peaks/.active-skill.json`
+ *   - `.peaks/sop-state/`
+ * into their new canonical home at:
+ *   - `.peaks/_runtime/session.json`
+ *   - `.peaks/_runtime/active-skill.json`
+ *   - `.peaks/_runtime/sop-state/`
+ *
+ * Behavior:
+ *   - Idempotent: re-running on a tree that is already on the new
+ *     layout produces `migratedFiles: []`.
+ *   - Best-effort: uses `fs.renameSync` (atomic on POSIX, best-effort
+ *     on Windows) and falls back to `copyFileSync` + `unlinkSync` if
+ *     rename throws (e.g. cross-device move on Windows). Errors are
+ *     collected per file and returned in the `errors` array so the
+ *     reconcile envelope can surface them without blocking the rest of
+ *     the migration.
+ *   - Creates `.peaks/_runtime/` on demand if any of the old paths
+ *     are present.
+ *
+ * @returns `{ migratedFiles, errors }`. `migratedFiles` lists the
+ *   *old* relative paths (e.g. `.peaks/.session.json`) that were
+ *   successfully moved, in move order. `errors` lists per-file
+ *   failures with the old path and a human-readable message.
+ */
+export declare function migrateOldRuntimeState(projectRoot: string): {
+    migratedFiles: string[];
+    errors: Array<{
+        path: string;
+        message: string;
+    }>;
+};
+/**
+ * One-time sub-agent state migration (slice 2026-06-06-sub-agent-spawn-bug-and-decouple).
+ *
+ * Move the legacy per-session sub-agent state files at:
+ *   - `.peaks/_runtime/<sid>/system/subagent-progress.json`
+ *   - `.peaks/_runtime/<sid>/system/progress-spawn.json`
+ * into the new canonical home at:
+ *   - `.peaks/_sub_agents/<sid>/subagent-progress.json`
+ *   - `.peaks/_sub_agents/<sid>/progress-spawn.json`
+ *
+ * Behavior:
+ *   - Idempotent: re-running on a tree that is already on the new layout
+ *     produces `migratedFiles: []`.
+ *   - Best-effort: uses `fs.renameSync` and falls back to `copyFileSync +
+ *     unlinkSync` if rename throws (e.g. cross-device move on Windows).
+ *   - Empty `<sid>/system/` dir removal (R-2 guard): the legacy `system/`
+ *     subdir is only removed when it has zero other files, so a tree where
+ *     the user had unrelated content in `system/` is left untouched.
+ *   - New-path-wins: when both old and new files exist, the old file is
+ *     removed (the new path is authoritative).
+ *
+ * Walks every discovered session — not just the canonical one — so a user
+ * with 6 pre-migration sessions gets all of them migrated in one reconcile
+ * pass.
+ *
+ * @returns `{ migratedFiles, errors }`. `migratedFiles` lists the *old*
+ *   relative paths (e.g. `.peaks/_runtime/<sid>/system/subagent-progress.json`) that
+ *   were successfully moved. `errors` lists per-file failures.
+ */
+export declare function migrateSubAgentState(projectRoot: string): {
+    migratedFiles: string[];
+    errors: Array<{
+        path: string;
+        message: string;
+    }>;
+};
+/**
+ * Top-level orchestrator. Wires migration (added in slice
+ * 2026-06-05-peaks-runtime-layer), discovery, canonical pick, re-point,
+ * deletion-candidate selection, and deletion into a single result.
+ */
+export declare function reconcileWorkspace(options: ReconcileOptions): ReconcileResult;