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

package/dist/cli/commands/workflow-plan-commands.js

@@ -0,0 +1,163 @@
+import { fail, getErrorMessage } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { readPlan } from '../../services/workflow/plan-reader.js';
+import { refreshPlan } from '../../services/workflow/plan-refresher.js';
+import { detectTrigger } from '../../services/workflow/plan-trigger-detector.js';
+import { getSessionId } from '../../services/session/session-manager.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+const VALID_TYPES = ['security', 'perf'];
+// F-1 (slice 025 security): reject session ids that look like path
+// traversal payloads. Canonical pattern is YYYY-MM-DD-<slug>.
+const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-[a-z][a-z0-9-]*[a-z0-9]$/;
+// F-1 (slice 025 security): reject rids that contain path separators,
+// null bytes, or traversal sequences.
+const REQUEST_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+function isPlanType(value) {
+    return VALID_TYPES.includes(value);
+}
+function isValidSessionId(value) {
+    return SESSION_ID_PATTERN.test(value);
+}
+function isValidRequestId(value) {
+    return REQUEST_ID_PATTERN.test(value);
+}
+function resolveSessionId(io, command, projectRoot, explicit, asJson) {
+    if (explicit !== undefined && explicit.length > 0) {
+        if (!isValidSessionId(explicit)) {
+            printResult(io, fail(command, 'INVALID_SESSION_ID', 'session id must match YYYY-MM-DD-slug pattern', { sessionId: explicit }, ['Use --session-id <YYYY-MM-DD-slug>']), asJson === true);
+            process.exitCode = 1;
+            return null;
+        }
+        return explicit;
+    }
+    const sid = getSessionId(projectRoot);
+    if (sid === null || sid === undefined) {
+        printResult(io, fail(command, 'NO_ACTIVE_SESSION', 'No active session — pass --session-id explicitly or run peaks workspace init', { projectRoot }, ['Run peaks workspace init or pass --session-id <YYYY-MM-DD-slug>']), asJson === true);
+        process.exitCode = 1;
+        return null;
+    }
+    // Defensive: even active-session resolution must satisfy the pattern.
+    if (!isValidSessionId(sid)) {
+        printResult(io, fail(command, 'INVALID_SESSION_ID', 'session id must match YYYY-MM-DD-slug pattern', { sessionId: sid }, ['Use --session-id <YYYY-MM-DD-slug>']), asJson === true);
+        process.exitCode = 1;
+        return null;
+    }
+    return sid;
+}
+function resolveProjectRoot(projectArg) {
+    if (projectArg === undefined || projectArg === '') {
+        return findProjectRoot(process.cwd()) ?? process.cwd();
+    }
+    return projectArg;
+}
+function runPlanRead(io, options) {
+    if (!isPlanType(options.type)) {
+        printResult(io, fail('workflow.plan.read', 'INVALID_TYPE', `Unsupported plan type: ${options.type}`, { supportedTypes: VALID_TYPES }, ['Use --type security or --type perf']), options.json === true);
+        process.exitCode = 1;
+        return;
+    }
+    const projectRoot = resolveProjectRoot(options.project);
+    const sessionId = resolveSessionId(io, 'workflow.plan.read', projectRoot, options.sessionId, options.json);
+    if (sessionId === null)
+        return;
+    try {
+        const result = readPlan({ type: options.type, project: projectRoot, sessionId });
+        printResult(io, result, options.json === true);
+    }
+    catch (error) {
+        printResult(io, fail('workflow.plan.read', 'READ_FAILED', getErrorMessage(error), null, ['Check that --project is a valid repo root with a peaks session']), options.json === true);
+        process.exitCode = 1;
+    }
+}
+function runPlanRefresh(io, options) {
+    if (!isPlanType(options.type)) {
+        printResult(io, fail('workflow.plan.refresh', 'INVALID_TYPE', `Unsupported plan type: ${options.type}`, { supportedTypes: VALID_TYPES }, ['Use --type security or --type perf']), options.json === true);
+        process.exitCode = 1;
+        return;
+    }
+    const projectRoot = resolveProjectRoot(options.project);
+    const sessionId = resolveSessionId(io, 'workflow.plan.refresh', projectRoot, options.sessionId, options.json);
+    if (sessionId === null)
+        return;
+    try {
+        const result = refreshPlan({
+            type: options.type,
+            project: projectRoot,
+            sessionId,
+            apply: options.apply === true
+        });
+        printResult(io, result, options.json === true);
+    }
+    catch (error) {
+        printResult(io, fail('workflow.plan.refresh', 'REFRESH_FAILED', getErrorMessage(error), null, ['Check that --project is a valid repo root and the session exists']), options.json === true);
+        process.exitCode = 1;
+    }
+}
+function runPlanDetectTrigger(io, options) {
+    if (options.rid === undefined || options.rid === '') {
+        printResult(io, fail('workflow.plan.detect-trigger', 'MISSING_RID', 'Missing --rid', null, ['Pass --rid <request-id>']), options.json === true);
+        process.exitCode = 1;
+        return;
+    }
+    if (!isValidRequestId(options.rid)) {
+        printResult(io, fail('workflow.plan.detect-trigger', 'INVALID_RID', 'request id must match [A-Za-z0-9][A-Za-z0-9._-]*', { rid: options.rid }, ['Pass --rid <alphanumeric.request-id>']), options.json === true);
+        process.exitCode = 1;
+        return;
+    }
+    const projectRoot = resolveProjectRoot(options.project);
+    const sessionId = resolveSessionId(io, 'workflow.plan.detect-trigger', projectRoot, options.sessionId, options.json);
+    if (sessionId === null)
+        return;
+    try {
+        const result = detectTrigger({
+            project: projectRoot,
+            rid: options.rid,
+            sessionId,
+            ...(options.refresh === true ? { manualOverride: true } : {})
+        });
+        printResult(io, result, options.json === true);
+    }
+    catch (error) {
+        printResult(io, fail('workflow.plan.detect-trigger', 'DETECT_FAILED', getErrorMessage(error), null, ['Check that --project is a valid repo root and --rid is set']), options.json === true);
+        process.exitCode = 1;
+    }
+}
+export function registerWorkflowPlanCommands(program, io) {
+    let workflowCmd = program.commands.find((c) => c.name() === 'workflow');
+    if (workflowCmd === undefined) {
+        workflowCmd = program.command('workflow').description('Plan workflow routing dry-run graphs');
+    }
+    const plan = workflowCmd
+        .command('plan')
+        .description('Read, refresh, or detect-trigger for security / perf plans (slice 025)');
+    addJsonOption(plan
+        .command('read')
+        .description('Read the project-level plan envelope (exists, path, hash, refreshedAt)')
+        .requiredOption('--type <type>', 'plan type: security or perf')
+        .option('--project <path>', 'project root', process.cwd())
+        .option('--session-id <sid>', 'session id (defaults to the active session)')).action((options) => {
+        runPlanRead(io, options);
+    });
+    addJsonOption(plan
+        .command('refresh')
+        .description('Regenerate the plan (deterministic, idempotent; --apply to write)')
+        .requiredOption('--type <type>', 'plan type: security or perf')
+        .option('--project <path>', 'project root', process.cwd())
+        .option('--session-id <sid>', 'session id (defaults to the active session)')
+        .option('--apply', 'write the plan to disk (default is dry-run preview)')).action((options) => {
+        runPlanRefresh(io, options);
+    });
+    addJsonOption(plan
+        .command('detect-trigger')
+        .description('Detect whether a plan refresh is warranted for the slice diff')
+        .requiredOption('--rid <rid>', 'request identifier')
+        .option('--project <path>', 'project root', process.cwd())
+        .option('--session-id <sid>', 'session id (defaults to the active session)')
+        .option('--refresh', 'force triggered=true (manual override)')).action((options) => {
+        runPlanDetectTrigger(io, options);
+    });
+}
+// Re-export for tests that need a programmatic entry point.
+export { runPlanRead as _runPlanRead };
+export { runPlanRefresh as _runPlanRefresh };
+export { runPlanDetectTrigger as _runPlanDetectTrigger };

package/dist/cli/commands/workspace/clean-command.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `peaks workspace clean` — slice 0.5 Task 9 (runtime-only after
+ * slice 2026-06-27-archive-feature-removal).
+ *
+ * Prunes _runtime/<sid>/ directories older than --older-than hours.
+ * Dry-run by default; pass --apply to commit. The previous
+ * The legacy sub-agents / bare-sid cleanup axis (which moved bare
+ * sids to a forensic dir) was removed when the archive dir was
+ * retired; bare sids are now blocked at write time. sids
+ * are now blocked at write time by `sid-naming-guard.ts`.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../../cli-helpers.js';
+export declare function registerWorkspaceCleanCommand(workspace: Command, _io: ProgramIO): void;

package/dist/cli/commands/workspace/clean-command.js

@@ -0,0 +1,49 @@
+/**
+ * `peaks workspace clean` — slice 0.5 Task 9 (runtime-only after
+ * slice 2026-06-27-archive-feature-removal).
+ *
+ * Prunes _runtime/<sid>/ directories older than --older-than hours.
+ * Dry-run by default; pass --apply to commit. The previous
+ * The legacy sub-agents / bare-sid cleanup axis (which moved bare
+ * sids to a forensic dir) was removed when the archive dir was
+ * retired; bare sids are now blocked at write time. sids
+ * are now blocked at write time by `sid-naming-guard.ts`.
+ */
+import { executeRuntimeCleanup } from '../../../services/workspace/workspace-clean-service.js';
+import { resolveCanonicalProjectRoot } from '../../../services/config/config-service.js';
+import { getErrorMessage } from '../../cli-helpers.js';
+export function registerWorkspaceCleanCommand(workspace, _io) {
+    workspace
+        .command('clean')
+        .description('Clean stale workspace artifacts (dry-run by default; pass --apply to commit). ' +
+        'Prunes _runtime/<sid>/ directories older than --older-than hours ' +
+        '(with --grace-hours safety window).')
+        .option('--older-than <hours>', 'age threshold in hours (default 168 = 7d)', '168')
+        .option('--grace-hours <hours>', 'safety grace period in hours added to --older-than (default 24)', '24')
+        .option('--apply', 'actually write changes (default is dry-run)')
+        .option('--project <path>', 'project root (defaults to current directory)', process.cwd())
+        .option('--json', 'emit a JSON envelope { ok, data } to stdout')
+        .action((opts) => {
+        try {
+            const projectRoot = resolveCanonicalProjectRoot(opts.project);
+            const apply = opts.apply === true;
+            const result = executeRuntimeCleanup(projectRoot, {
+                olderThanHours: Number.parseInt(opts.olderThan, 10),
+                graceHours: Number.parseInt(opts.graceHours, 10),
+                apply
+            });
+            if (opts.json === true) {
+                process.stdout.write(JSON.stringify({ ok: true, data: { dryRun: !apply, deleted: result.deleted, skipped: result.skipped } }) + '\n');
+            }
+        }
+        catch (error) {
+            if (opts.json === true) {
+                process.stdout.write(JSON.stringify({ ok: false, error: getErrorMessage(error) }) + '\n');
+            }
+            else {
+                process.stderr.write(getErrorMessage(error) + '\n');
+            }
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/workspace/helpers.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared helpers for `peaks workspace <sub-command>` implementations.
+ *
+ * Extracted from `src/cli/commands/workspace-commands.ts` (slice
+ * 2026-06-16-workspace-commands-split) so multiple sub-command files can
+ * reuse the same hooks-decision marker + prompt logic. Pure helpers
+ * only — no commander / no service calls. Keeping these here means the
+ * per-subcommand files stay focused on their command wiring and option
+ * parsing.
+ */
+/** Sticky decision marker for the first-time "install hooks" prompt. */
+export declare const HOOKS_DECISION_REL_PATH = ".peaks/.peaks-init-hooks-decision.json";
+export type HooksDecision = 'installed' | 'skipped';
+export type HooksDecisionMarker = {
+    version: 1;
+    decision: HooksDecision;
+    decidedAt: string;
+    scope: 'project' | 'global';
+};
+export declare function readDecisionMarker(projectRoot: string): HooksDecisionMarker | null;
+export declare function writeDecisionMarker(projectRoot: string, decision: HooksDecision): void;
+/**
+ * Read a yes/no answer from stdin. Returns `true` for empty / Y / y,
+ * `false` for N / n, or `null` when stdin is not a TTY (the caller falls
+ * back to the no-prompt path). Times out after 30s so a piped-but-blocked
+ * stdin never hangs the CLI.
+ */
+export declare function promptYesNo(question: string): Promise<boolean | null>;

package/dist/cli/commands/workspace/helpers.js

@@ -0,0 +1,87 @@
+/**
+ * Shared helpers for `peaks workspace <sub-command>` implementations.
+ *
+ * Extracted from `src/cli/commands/workspace-commands.ts` (slice
+ * 2026-06-16-workspace-commands-split) so multiple sub-command files can
+ * reuse the same hooks-decision marker + prompt logic. Pure helpers
+ * only — no commander / no service calls. Keeping these here means the
+ * per-subcommand files stay focused on their command wiring and option
+ * parsing.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+/** Sticky decision marker for the first-time "install hooks" prompt. */
+export const HOOKS_DECISION_REL_PATH = '.peaks/.peaks-init-hooks-decision.json';
+export function readDecisionMarker(projectRoot) {
+    const path = join(projectRoot, HOOKS_DECISION_REL_PATH);
+    if (!existsSync(path))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(path, 'utf8'));
+        if (data.version !== 1)
+            return null;
+        if (data.decision !== 'installed' && data.decision !== 'skipped')
+            return null;
+        if (typeof data.decidedAt !== 'string')
+            return null;
+        if (data.scope !== 'project' && data.scope !== 'global')
+            return null;
+        return {
+            version: 1,
+            decision: data.decision,
+            decidedAt: data.decidedAt,
+            scope: data.scope
+        };
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+export function writeDecisionMarker(projectRoot, decision) {
+    const path = join(projectRoot, HOOKS_DECISION_REL_PATH);
+    const dir = join(projectRoot, '.peaks');
+    mkdirSync(dir, { recursive: true });
+    const marker = {
+        version: 1,
+        decision,
+        decidedAt: new Date().toISOString(),
+        scope: 'project'
+    };
+    writeFileSync(path, JSON.stringify(marker, null, 2) + '\n', 'utf8');
+}
+/**
+ * Read a yes/no answer from stdin. Returns `true` for empty / Y / y,
+ * `false` for N / n, or `null` when stdin is not a TTY (the caller falls
+ * back to the no-prompt path). Times out after 30s so a piped-but-blocked
+ * stdin never hangs the CLI.
+ */
+export function promptYesNo(question) {
+    return new Promise((resolve) => {
+        if (process.stdin.isTTY !== true) {
+            resolve(null);
+            return;
+        }
+        const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+        const timer = setTimeout(() => {
+            rl.close();
+            resolve(null);
+        }, 30_000);
+        rl.question(question, (answer) => {
+            clearTimeout(timer);
+            rl.close();
+            const trimmed = answer.trim().toLowerCase();
+            if (trimmed === '' || trimmed === 'y' || trimmed === 'yes') {
+                resolve(true);
+                return;
+            }
+            if (trimmed === 'n' || trimmed === 'no') {
+                resolve(false);
+                return;
+            }
+            // Treat anything else as "no" — the user can re-run with --install-hooks
+            // if they want a different answer. We never throw from this prompt.
+            resolve(false);
+        });
+    });
+}

package/dist/cli/commands/workspace/init-command.d.ts

@@ -0,0 +1,139 @@
+/**
+ * `peaks workspace init` — slice 006 + 007 + 014 + 018 + 2026-06-16-peaks-code-auto-scaffold.
+ *
+ * Extracted from `src/cli/commands/workspace-commands.ts` (slice
+ * 2026-06-16-workspace-commands-split) to keep that entry file under the
+ * 800-line Karpathy cap. Owns:
+ *   - commander option wiring (`--project`, `--session-id`, `--change-id`, etc.)
+ *   - canonical project-root resolution
+ *   - session id resolution (with slice-018 rotation)
+ *   - first-time hooks install prompt + sticky marker
+ *   - missing-standards diagnostic surface (AC1-AC7) and `--init-standards` apply
+ *
+ * Imports the shared hooks-decision marker helpers from `./helpers.ts`.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../../cli-helpers.js';
+import { type HooksDecision } from './helpers.js';
+export type WorkspaceInitOptions = {
+    project: string;
+    sessionId?: string;
+    json?: boolean;
+    allowSessionRebind?: boolean;
+    /**
+     * Slice 018 opt-out, commander-convention form. The user-facing
+     * flag is `--no-rotate-on-outer-mismatch`; commander strips the
+     * `--no-` prefix and assigns the boolean to this property (default
+     * `true`, set to `false` when the flag is passed). The wrapper
+     * reads this as `=== false` to opt out. The presence file still
+     * records `outerSessionMismatch` regardless of the flag's value.
+     */
+    rotateOnOuterMismatch?: boolean;
+    /**
+     * How to handle the first-time "install peaks hooks" prompt.
+     *   - ask  (default in TTY): prompt the user once, sticky-marker the answer
+     *   - auto (default in --json / non-TTY): install silently, sticky-marker installed
+     *   - skip: write sticky-marker skipped, do not install
+     * After the first decision the sticky marker wins, regardless of --install-hooks
+     * (re-runs respect the recorded decision; only re-install when the marker says
+     * installed but the hooks have been removed out from under us).
+     */
+    installHooks?: 'ask' | 'auto' | 'skip';
+    /**
+     * Slice 2.0.1-bug3-fact-forcing-bypass: opt out of writing the
+     * consumer-project `.claude/settings.local.json` file. Default
+     * (commander `--no-` prefix) is `true`; pass `--no-claude-hooks` to
+     * set this to `false`. The wrapper reads this as `=== false` to
+     * skip the materialization. The bypass is documented in
+     * `peaks-code/references/anchoring-and-session-info.md`.
+     */
+    claudeHooks?: boolean;
+    /**
+     * Slice 2026-06-16-peaks-code-auto-scaffold (RD#7): opt-in flag to
+     * auto-scaffold `.claude/rules/{common,<language>}/` when missing.
+     * Default `false` — the diagnostic fires but no write happens.
+     * Set to `true` (via `--init-standards`) to also run
+     * `executeProjectStandardsInit({ projectRoot, apply: true })`.
+     */
+    initStandards?: boolean;
+    /**
+     * Slice 2026-07-15-project-scan-bootstrap (G2 / G4b / AC9 / AC10):
+     * commander-style `--no-project-scan-bootstrap` opt-out. Default
+     * (no flag) leaves this `undefined` (treated as `true`). Pass the
+     * flag to set `options.projectScanBootstrap === false`, which the
+     * caller reads as `=== false` to skip the bootstrap call.
+     */
+    projectScanBootstrap?: boolean;
+    /**
+     * Slice 2026-07-15-project-scan-bootstrap (G2 / G4b / AC10):
+     * `--force-project-scan-templates` flag. Default (no flag)
+     * leaves this `undefined`. Pass the flag to set
+     * `options.forceProjectScanTemplates === true`, which forces the
+     * bootstrap service to overwrite the 4 bundled audit/business
+     * templates even when they already exist (sediment is preserved
+     * otherwise).
+     */
+    forceProjectScanTemplates?: boolean;
+};
+/**
+ * Outcome of the first-time "install peaks hooks" decision attached to
+ * `peaks workspace init`. Reported in the response data so the LLM and
+ * the human both see what happened.
+ */
+export type FirstTimeHooksInstallOutcome = {
+    /** The decision recorded (or already on file) in the sticky marker. */
+    decision: HooksDecision;
+    /**
+     * What the install path actually did this call.
+     *   - first-decision: we recorded a brand-new sticky marker (and may have installed)
+     *   - reinstalled:    the marker said installed but the hooks were missing — we re-applied
+     *   - marker-honored: the marker already existed; we did not touch the hooks
+     *   - already-installed: the hooks were already present and the marker does not exist yet
+     *                          (we write a fresh marker to lock in the answer for next time)
+     */
+    action: 'first-decision' | 'reinstalled' | 'marker-honored' | 'already-installed';
+    scope: 'project' | 'global';
+    /**
+     * Why the action was the way it was (e.g. "stdin-not-tty", "user-answered-no",
+     * "marker-installed-hooks-missing"). Surfaced for forensics.
+     */
+    reason?: string;
+};
+export type ResolveFirstTimeHooksInstallOptions = {
+    projectRoot: string;
+    /**
+     * Explicit mode from the --install-hooks flag. When omitted, the default
+     * is "ask" in TTY mode and "auto" otherwise (see `defaultMode` logic).
+     */
+    explicitMode?: 'ask' | 'auto' | 'skip' | undefined;
+    /**
+     * Whether the caller is in --json mode. In --json mode we never prompt
+     * (the LLM cannot answer an interactive question) — we silently treat
+     * "ask" as "auto" and proceed.
+     */
+    jsonMode: boolean;
+};
+export declare function registerWorkspaceInitCommand(workspace: Command, io: ProgramIO): void;
+/**
+ * Resolve the first-time "install peaks hooks" decision for this project.
+ * Decision tree:
+ *
+ *   1. Read the sticky marker.
+ *      - Marker present:
+ *        - marker.decision === 'installed' AND hooks are present → action: marker-honored, no side effects
+ *        - marker.decision === 'installed' AND hooks are MISSING   → re-install, action: reinstalled
+ *        - marker.decision === 'skipped'                            → action: marker-honored, no install
+ *      - Marker absent:
+ *        - hooks already present → write a fresh 'installed' marker, action: already-installed
+ *        - otherwise:
+ *          - explicit --install-hooks=auto  → install + marker, action: first-decision
+ *          - explicit --install-hooks=skip  → marker only, action: first-decision
+ *          - explicit --install-hooks=ask OR default in TTY:
+ *              - jsonMode → silently auto-install (LLM cannot answer), action: first-decision
+ *              - TTY      → prompt; on yes install + marker, on no marker-only
+ *          - default in non-TTY → auto-install, action: first-decision
+ *
+ * Project scope is the only supported scope here; global scope is reserved
+ * for explicit `peaks hooks install --global` invocations.
+ */
+export declare function resolveFirstTimeHooksInstall(options: ResolveFirstTimeHooksInstallOptions): Promise<FirstTimeHooksInstallOutcome>;