peaks-loop 4.0.0-beta.6 → 4.0.0-beta.8

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

@@ -1,130 +0,0 @@
-/**
- * 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

@@ -1,13 +0,0 @@
-/**
- * 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

@@ -1,17 +0,0 @@
-/**
- * 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

@@ -1,34 +0,0 @@
-/**
- * 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

@@ -1,45 +0,0 @@
-/**
- * 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-loop 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-code/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-loop 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

@@ -1,194 +0,0 @@
-/**
- * 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-loop managed snippet (slice 2.0.1-bug3) — do not edit by hand';
-const PEAKS_GITIGNORE_FOOTER = '# <<< peaks-loop 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-loop\'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-loop 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-loop 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-code/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-loop 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-loop'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-loop 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-loop 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

@@ -1,28 +0,0 @@
-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

@@ -1,46 +0,0 @@
-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 };
-}