peaks-loop 3.0.0

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

@@ -0,0 +1,130 @@
+/**
+ * Type envelope for the `peaks workspace reconcile` CLI command.
+ *
+ * The reconcile command scans `.peaks/2026-MM-DD-session-<6hex>/` directories
+ * under the project root, identifies a canonical session via a 4-tier
+ * heuristic (active-skill binding -> most-recent session.json mtime ->
+ * most-recent any-file mtime -> dir-name sort), re-points
+ * `.peaks/.session.json`, and (optionally) deletes empty / abandoned
+ * session dirs older than a configurable age threshold.
+ *
+ * Types are hand-rolled, no new top-level dependencies.
+ */
+export type SessionEntry = {
+    /** Directory name (e.g. "2026-06-04-session-89f7cb"). */
+    sessionId: string;
+    /** Absolute path to the session directory. */
+    path: string;
+    /** mtime of `session.json` inside the dir in ms since epoch; null if missing. */
+    lastActivity: number | null;
+    /**
+     * Count of files under the session dir, EXCLUDING `session.json`
+     * (which is auto-generated by `peaks workspace init`). A count of
+     * 0 means the dir is empty / abandoned.
+     */
+    artifactCount: number;
+};
+export type DeletionCandidateReason = 'empty-or-auto-only' | 'older-than-threshold';
+export type ReconcileResult = {
+    /** Absolute project root the command operated on. */
+    projectRoot: string;
+    /** All discovered `.peaks/2026-MM-DD-session-<6hex>/` directories, sorted by name. */
+    sessions: SessionEntry[];
+    /** The session id selected by the 4-tier canonical heuristic. */
+    canonicalSessionId: string | null;
+    /**
+     * The tier that decided the canonical pick (1..4), where tier 1 is
+     * active-skill and tier 4 is lexicographic last. Null when there are
+     * no sessions at all.
+     */
+    canonicalSource: 'active-skill' | 'latest-session-json-mtime' | 'latest-any-file-mtime' | 'dir-name-sort' | null;
+    /** The session id the binding pointed at before reconcile. Null if no prior binding. */
+    repointedFrom: string | null;
+    /** The session id the binding now points at. Null if there were no sessions. */
+    repointedTo: string | null;
+    /** Sessions that match the age-threshold + empty-or-auto-only deletion rule. */
+    deletionCandidates: SessionEntry[];
+    /** Actual deletions performed (only populated when `apply === true`). */
+    deleted: string[];
+    /** Sessions that WOULD be deleted if `--apply` were set (only populated when `apply === false`). */
+    wouldDelete: string[];
+    /** Age threshold in ms used to compute deletion candidates. */
+    ageThresholdMs: number;
+    /** Whether `--apply` was set. */
+    apply: boolean;
+    /** Whether the canonical session id differs from the prior binding. */
+    repointed: boolean;
+    /**
+     * Old-path runtime files that `migrateOldRuntimeState` moved into
+     * `.peaks/_runtime/` during this reconcile run. Each entry is the
+     * legacy path relative to the project root (e.g. ".peaks/.session.json",
+     * ".peaks/.active-skill.json", ".peaks/sop-state"). Empty when the
+     * tree is already on the new layout (idempotent re-runs return []).
+     *
+     * Added in slice 2026-06-05-peaks-runtime-layer; additive — older
+     * consumers can ignore this field.
+     */
+    migratedFiles: string[];
+    /**
+     * Count of legacy per-session sub-agent state files moved from
+     * `.peaks/_runtime/<sid>/system/{subagent-progress,progress-spawn}.json` into
+     * `.peaks/_sub_agents/<sid>/` during this reconcile run.
+     *
+     * Added in slice 2026-06-06-sub-agent-spawn-bug-and-decouple. The
+     * detailed list of moved files is not surfaced here (the count is
+     * what the CLI summary and QA test assert on); the underlying
+     * `migrateSubAgentState` helper returns the full path list for
+     * forensics. Additive — older consumers can ignore this field.
+     */
+    subAgentStateMigrated: number;
+    /**
+     * Errors encountered during the migration step. Each entry has a
+     * `kind: 'migrate'` discriminator so consumers can tell migration
+     * errors apart from deletion errors. The shape is additive.
+     */
+    errors: Array<{
+        sessionId: string;
+        message: string;
+    } | {
+        kind: 'migrate';
+        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;
+    /** When true, actually `rm -rf` the deletion candidates. */
+    apply: boolean;
+    /**
+     * Age threshold in milliseconds; sessions whose mtime-based
+     * `lastActivity` is older than this AND whose `artifactCount === 0`
+     * (or 1 if the only file is `session.json`) are deletion candidates.
+     * Default: 7 days in the CLI layer.
+     */
+    olderThanMs: number;
+};

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

@@ -0,0 +1,13 @@
+/**
+ * Type envelope for the `peaks workspace reconcile` CLI command.
+ *
+ * The reconcile command scans `.peaks/2026-MM-DD-session-<6hex>/` directories
+ * under the project root, identifies a canonical session via a 4-tier
+ * heuristic (active-skill binding -> most-recent session.json mtime ->
+ * most-recent any-file mtime -> dir-name sort), re-points
+ * `.peaks/.session.json`, and (optionally) deletes empty / abandoned
+ * session dirs older than a configurable age threshold.
+ *
+ * Types are hand-rolled, no new top-level dependencies.
+ */
+export {};

package/dist/src/services/workspace/sid-naming-guard.d.ts

@@ -0,0 +1,17 @@
+/**
+ * SID naming guard. Enforces the "two-axis" convention from spec §0:
+ * session id: YYYY-MM-DD-session-<3-6 chars lowercase alnum>
+ * change id: kebab-case
+ *
+ * Spec §8.7 — bare forms (sid-3 / sid-h / sid-r / unknown-sid) are
+ * blocked at write time, NOT tolerated. After slice
+ * 2026-06-27-archive-feature-removal the quarantine dir was removed;
+ * bare sids are now rejected by callers using `assertValidSessionId`
+ * instead.
+ */
+export declare const SID_FORMAT_DESCRIPTION = "<YYYY-MM-DD>-session-<3-6 chars lowercase alnum>, e.g. 2026-06-11-session-abc123";
+export declare function isValidSessionId(sid: string): boolean;
+export declare function isValidChangeId(cid: string): boolean;
+export declare function isBareSid(name: string): boolean;
+export declare function assertValidSessionId(sid: string): void;
+export declare function assertValidChangeId(cid: string): void;

package/dist/src/services/workspace/sid-naming-guard.js

@@ -0,0 +1,34 @@
+/**
+ * SID naming guard. Enforces the "two-axis" convention from spec §0:
+ * session id: YYYY-MM-DD-session-<3-6 chars lowercase alnum>
+ * change id: kebab-case
+ *
+ * Spec §8.7 — bare forms (sid-3 / sid-h / sid-r / unknown-sid) are
+ * blocked at write time, NOT tolerated. After slice
+ * 2026-06-27-archive-feature-removal the quarantine dir was removed;
+ * bare sids are now rejected by callers using `assertValidSessionId`
+ * instead.
+ */
+export const SID_FORMAT_DESCRIPTION = '<YYYY-MM-DD>-session-<3-6 chars lowercase alnum>, e.g. 2026-06-11-session-abc123';
+const VALID_SID_REGEX = /^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])-session-[0-9a-z]{3,6}$/;
+const BARE_SID_REGEX = /^(sid-[a-z0-9]+|unknown-sid)$/;
+const VALID_CHANGE_ID_REGEX = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+export function isValidSessionId(sid) {
+    return VALID_SID_REGEX.test(sid);
+}
+export function isValidChangeId(cid) {
+    return VALID_CHANGE_ID_REGEX.test(cid);
+}
+export function isBareSid(name) {
+    return BARE_SID_REGEX.test(name);
+}
+export function assertValidSessionId(sid) {
+    if (!isValidSessionId(sid)) {
+        throw new Error(`NAMING_INVALID: session id "${sid}" does not match required format ${SID_FORMAT_DESCRIPTION}`);
+    }
+}
+export function assertValidChangeId(cid) {
+    if (!isValidChangeId(cid)) {
+        throw new Error(`NAMING_INVALID: change id "${cid}" must be kebab-case (lowercase alnum and dashes only)`);
+    }
+}

package/dist/src/services/workspace/workspace-claude-settings-materializer.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Workspace Service -- consumer `.claude/settings.local.json` materialization.
+ *
+ * v2.18.3 file-split: this module is the extracted sub-tree of the
+ * pre-split `workspace-service.ts`. It hosts the 3 helpers
+ * (`materializeClaudeSettingsLocal`, `writeOfflineTemplateCopy`,
+ * `upsertPeaksGitignoreSnippet`) plus the `PEAKS_GITIGNORE_*`
+ * constants. The high-level `initWorkspace` orchestrator lives in
+ * the parent module and calls into this sibling. Function signatures
+ * and behaviour are unchanged (verbatim move).
+ */
+/**
+ * Materialize the consumer-project `.claude/settings.local.json` and
+ * ensure the consumer's `.peaks/.gitignore` covers it. Returns a
+ * `claudeSettings` descriptor that the caller surfaces in the JSON
+ * envelope.
+ *
+ * The function is idempotent: re-running on an already-materialized
+ * project is a no-op (the file is rewritten only when its content
+ * diverges from the current peaks-cli release's template, which
+ * keeps the consumer up to date as the template evolves).
+ *
+ * Even when the caller passes `noClaudeHooks: true`, the function
+ * still writes a copy of the template at
+ * `.peaks/.claude-settings-template.json` so the user has an offline
+ * recovery path: copy the file contents into
+ * `.claude/settings.local.json` manually. The recovery path is
+ * documented in
+ * `skills/peaks-solo/references/anchoring-and-session-info.md`.
+ *
+ * Slice 2026-06-13-selfheal-claude-settings-template: the offline copy
+ * is now ALSO drift-checked (via `templateContentMatches`) so stale
+ * on-disk copies from earlier peaks-cli releases (which lacked the
+ * `node -e "..."` wrapper) get refreshed automatically on the next
+ * init. The action taken on the offline copy is surfaced in
+ * `claudeSettings.offlineTemplate.action`.
+ */
+export declare function materializeClaudeSettingsLocal(projectRoot: string, noClaudeHooks: boolean): Promise<{
+    action: 'written' | 'refreshed' | 'already-current' | 'skipped';
+    path: string;
+    offlineTemplate: {
+        action: 'written' | 'refreshed' | 'already-current';
+        path: string;
+    };
+}>;

package/dist/src/services/workspace/workspace-claude-settings-materializer.js

@@ -0,0 +1,194 @@
+/**
+ * Workspace Service -- consumer `.claude/settings.local.json` materialization.
+ *
+ * v2.18.3 file-split: this module is the extracted sub-tree of the
+ * pre-split `workspace-service.ts`. It hosts the 3 helpers
+ * (`materializeClaudeSettingsLocal`, `writeOfflineTemplateCopy`,
+ * `upsertPeaksGitignoreSnippet`) plus the `PEAKS_GITIGNORE_*`
+ * constants. The high-level `initWorkspace` orchestrator lives in
+ * the parent module and calls into this sibling. Function signatures
+ * and behaviour are unchanged (verbatim move).
+ */
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { buildClaudeSettingsLocalJson, CLAUDE_SETTINGS_LOCAL_FILENAME, templateContentMatches } from './claude-settings-template.js';
+/**
+ * The peaks-managed snippet appended to the consumer project's
+ * `.peaks/.gitignore` so the local-only settings file never lands
+ * in a commit. Marked with a managed-by header so we can detect (and
+ * not double-append) on subsequent inits.
+ */
+const PEAKS_GITIGNORE_HEADER = '# >>> peaks-cli managed snippet (slice 2.0.1-bug3) — do not edit by hand';
+const PEAKS_GITIGNORE_FOOTER = '# <<< peaks-cli managed snippet';
+const PEAKS_GITIGNORE_SNIPPET = [
+    PEAKS_GITIGNORE_HEADER,
+    '# Consumer-project .claude/settings.local.json: written by `peaks workspace init`',
+    '# to bypass Claude Code [Fact-Forcing Gate] for .peaks/** writes. Local-only.',
+    '.claude/settings.local.json',
+    '# Offline template copy (.peaks/.claude-settings-template.json): written by',
+    '# `peaks workspace init` as a manual-recovery anchor. The source-of-truth is',
+    '# peaks-cli\'s own `buildClaudeSettingsLocalJson()` — NOT this committed copy.',
+    '# Gitignored so the init flow\'s drift-driven refresh does not show up as',
+    '# "modified" in `git status` on every release bump. Recovery path: re-run',
+    '# `peaks workspace init` to regenerate; or copy from peaks-cli source.',
+    '.peaks/.claude-settings-template.json',
+    PEAKS_GITIGNORE_FOOTER,
+    ''
+].join('\n');
+/**
+ * Materialize the consumer-project `.claude/settings.local.json` and
+ * ensure the consumer's `.peaks/.gitignore` covers it. Returns a
+ * `claudeSettings` descriptor that the caller surfaces in the JSON
+ * envelope.
+ *
+ * The function is idempotent: re-running on an already-materialized
+ * project is a no-op (the file is rewritten only when its content
+ * diverges from the current peaks-cli release's template, which
+ * keeps the consumer up to date as the template evolves).
+ *
+ * Even when the caller passes `noClaudeHooks: true`, the function
+ * still writes a copy of the template at
+ * `.peaks/.claude-settings-template.json` so the user has an offline
+ * recovery path: copy the file contents into
+ * `.claude/settings.local.json` manually. The recovery path is
+ * documented in
+ * `skills/peaks-solo/references/anchoring-and-session-info.md`.
+ *
+ * Slice 2026-06-13-selfheal-claude-settings-template: the offline copy
+ * is now ALSO drift-checked (via `templateContentMatches`) so stale
+ * on-disk copies from earlier peaks-cli releases (which lacked the
+ * `node -e "..."` wrapper) get refreshed automatically on the next
+ * init. The action taken on the offline copy is surfaced in
+ * `claudeSettings.offlineTemplate.action`.
+ */
+export async function materializeClaudeSettingsLocal(projectRoot, noClaudeHooks) {
+    const settingsRel = CLAUDE_SETTINGS_LOCAL_FILENAME;
+    const settingsPath = join(projectRoot, settingsRel);
+    const template = buildClaudeSettingsLocalJson();
+    const serialized = JSON.stringify(template, null, 2) + '\n';
+    // Always drop (or self-heal) a copy of the template under .peaks/
+    // so the --no-claude-hooks recovery flow has a known source-of-truth
+    // on disk. The file is gitignored by the snippet below.
+    const offlineAction = await writeOfflineTemplateCopy(projectRoot, serialized);
+    const offlineTemplate = {
+        action: offlineAction,
+        path: '.peaks/.claude-settings-template.json'
+    };
+    if (noClaudeHooks) {
+        return { action: 'skipped', path: settingsRel, offlineTemplate };
+    }
+    // Best-effort: ensure .claude/ exists, then write the file. We do
+    // not assertSafeSettingsPath here (the .claude/ dir is local to
+    // the consumer and we trust it on first init; the existing
+    // hooks-settings-service applies the safety check for the Bash
+    // gate-enforce path).
+    await mkdir(join(projectRoot, '.claude'), { recursive: true });
+    let action = 'written';
+    if (existsSync(settingsPath)) {
+        try {
+            const { readFile } = await import('node:fs/promises');
+            const existing = await readFile(settingsPath, 'utf8');
+            if (existing === serialized) {
+                action = 'already-current';
+            }
+            else {
+                action = 'refreshed';
+            }
+        }
+        catch {
+            // Treat any read failure as "needs refresh" so the consumer
+            // always ends up with a valid template on disk.
+            action = 'refreshed';
+        }
+    }
+    if (action !== 'already-current') {
+        await writeFile(settingsPath, serialized, 'utf8');
+    }
+    // Ensure the consumer's .peaks/.gitignore covers the local-only
+    // settings file. The snippet is appended only when the header is
+    // missing, so subsequent inits do not double-append.
+    await upsertPeaksGitignoreSnippet(projectRoot);
+    return { action, path: settingsRel, offlineTemplate };
+}
+/**
+ * Always write (or refresh) a copy of the template at
+ * `.peaks/.claude-settings-template.json` so the user has a known
+ * source-of-truth on disk for the manual recovery flow. The file is
+ * GITIGNORED (added to `.peaks/.gitignore` by
+ * `upsertPeaksGitignoreSnippet`) — the source-of-truth lives in
+ * peaks-cli's own `buildClaudeSettingsLocalJson()`, NOT in any
+ * committed copy. Gitignoring it ensures the init flow's drift-driven
+ * refresh does not show up as "modified" in `git status` on every
+ * peaks-cli release bump.
+ *
+ * Recovery path for users who need to re-create their
+ * `.claude/settings.local.json`: re-run `peaks workspace init`
+ * (the file is regenerated); or copy the template straight from
+ * peaks-cli source (`src/services/workspace/claude-settings-template.ts`).
+ *
+ * Slice 2026-06-13-selfheal-claude-settings-template: drift-check via
+ * `templateContentMatches` BEFORE writing. If the on-disk copy's
+ * parsed hooks tree matches the current `buildClaudeSettingsLocalJson()`
+ * output, the write is skipped (`already-current`). If the file is
+ * missing, it is written (`written`). If it exists but has drifted
+ * (e.g. an earlier release's template without the `node -e "..."`
+ * wrapper, or a user-customised copy), it is rewritten (`refreshed`).
+ * The CLI caller surfaces a warning when `refreshed` because manual
+ * edits the user may have made would be overwritten.
+ *
+ * Returns the action taken so the caller can surface it in the
+ * envelope. Read failures are treated as drift so a malformed
+ * on-disk file always self-heals on the next init.
+ */
+async function writeOfflineTemplateCopy(projectRoot, serialized) {
+    const copyPath = join(projectRoot, '.peaks', '.claude-settings-template.json');
+    await mkdir(join(projectRoot, '.peaks'), { recursive: true });
+    let action = 'written';
+    if (existsSync(copyPath)) {
+        try {
+            const { readFile } = await import('node:fs/promises');
+            const existing = await readFile(copyPath, 'utf8');
+            if (templateContentMatches(serialized, existing)) {
+                action = 'already-current';
+            }
+            else {
+                action = 'refreshed';
+            }
+        }
+        catch {
+            // Treat any read failure as drift so the file self-heals.
+            action = 'refreshed';
+        }
+    }
+    if (action !== 'already-current') {
+        await writeFile(copyPath, serialized, 'utf8');
+    }
+    return action;
+}
+/**
+ * Append the peaks-managed `.claude/settings.local.json` snippet to
+ * the consumer project's `.peaks/.gitignore`. Preserves any user-
+ * managed entries above the snippet. Idempotent: re-running on a
+ * project that already has the snippet is a no-op.
+ */
+async function upsertPeaksGitignoreSnippet(projectRoot) {
+    const gitignorePath = join(projectRoot, '.peaks', '.gitignore');
+    await mkdir(join(projectRoot, '.peaks'), { recursive: true });
+    let existing = '';
+    if (existsSync(gitignorePath)) {
+        try {
+            const { readFile } = await import('node:fs/promises');
+            existing = await readFile(gitignorePath, 'utf8');
+        }
+        catch {
+            existing = '';
+        }
+    }
+    if (existing.includes(PEAKS_GITIGNORE_HEADER)) {
+        return;
+    }
+    const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+    const next = existing + separator + (existing.length > 0 ? '\n' : '') + PEAKS_GITIGNORE_SNIPPET;
+    await writeFile(gitignorePath, next, 'utf8');
+}

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

@@ -0,0 +1,28 @@
+export interface RuntimeSessionInfo {
+    sid: string;
+    mtimeMs: number;
+    ageHours: number;
+}
+export interface CleanupOptions {
+    olderThanHours: number;
+    graceHours: number;
+}
+export interface CleanupResult {
+    deleted: string[];
+    skipped: {
+        sid: string;
+        reason: string;
+    }[];
+}
+export declare function runtimeDirPath(projectRoot: string): string;
+export declare function listRuntimeSessions(projectRoot: string): RuntimeSessionInfo[];
+export declare function planRuntimeCleanup(sessions: RuntimeSessionInfo[], options: CleanupOptions): {
+    eligible: string[];
+    skipped: {
+        sid: string;
+        reason: string;
+    }[];
+};
+export declare function executeRuntimeCleanup(projectRoot: string, options: CleanupOptions & {
+    apply: boolean;
+}): CleanupResult;

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

@@ -0,0 +1,46 @@
+import { existsSync, readdirSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+const RUNTIME_DIR = '_runtime';
+export function runtimeDirPath(projectRoot) {
+    return join(projectRoot, '.peaks', RUNTIME_DIR);
+}
+export function listRuntimeSessions(projectRoot) {
+    const dir = runtimeDirPath(projectRoot);
+    if (!existsSync(dir))
+        return [];
+    const now = Date.now();
+    return readdirSync(dir, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .map((e) => {
+        const sid = e.name;
+        const fullPath = join(dir, sid);
+        const stat = statSync(fullPath);
+        const ageHours = (now - stat.mtimeMs) / (1000 * 3600);
+        return { sid, mtimeMs: stat.mtimeMs, ageHours };
+    });
+}
+export function planRuntimeCleanup(sessions, options) {
+    const eligible = [];
+    const skipped = [];
+    const cutoffHours = options.olderThanHours + options.graceHours;
+    for (const s of sessions) {
+        if (s.ageHours >= cutoffHours) {
+            eligible.push(s.sid);
+        }
+        else {
+            skipped.push({ sid: s.sid, reason: `fresh: age=${s.ageHours.toFixed(1)}h < cutoff=${cutoffHours}h` });
+        }
+    }
+    return { eligible, skipped };
+}
+export function executeRuntimeCleanup(projectRoot, options) {
+    const sessions = listRuntimeSessions(projectRoot);
+    const plan = planRuntimeCleanup(sessions, options);
+    if (options.apply) {
+        const dir = runtimeDirPath(projectRoot);
+        for (const sid of plan.eligible) {
+            rmSync(join(dir, sid), { recursive: true, force: true });
+        }
+    }
+    return { deleted: plan.eligible, skipped: plan.skipped };
+}