peaks-loop 4.1.2 → 4.1.4

package/dist/cli/commands/project-context-command.js

@@ -0,0 +1,44 @@
+// src/cli/commands/project-context-command.ts
+//
+// `peaks project context` — generate or read the persistent project context.
+// Split out of `project-commands.ts`; the verb name, its options, the
+// `exists` / `content` envelope keys and the read-vs-generate branch are
+// unchanged.
+import { generateProjectContext, readProjectContext } from '../../services/memory/project-context-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+/** The read branch's envelope data, present or absent. */
+function readContextData(project) {
+    const content = readProjectContext(project);
+    const path = `${project}/.peaks/PROJECT.md`;
+    return content === null ? { exists: false, path } : { exists: true, path, content };
+}
+async function runProjectContext(io, options) {
+    try {
+        if (options.read) {
+            printResult(io, ok('project.context', readContextData(options.project)), options.json);
+            return;
+        }
+        const result = await generateProjectContext(options.project);
+        printResult(io, ok('project.context', {
+            path: result.path,
+            sessionCount: result.sessionCount,
+            content: result.content,
+            // context command also bootstraps the project-scan tree.
+            // The envelope surfaces write counts + duration so the LLM
+            // (and the user) see what landed.
+            projectScan: result.projectScan
+        }), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('project.context', 'PROJECT_CONTEXT_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks directory']), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerProjectContextCommand(project, io) {
+    addJsonOption(project
+        .command('context')
+        .description('Generate or read persistent project context for cross-session Peaks understanding. Generates BOTH `.peaks/PROJECT.md` (session history) AND `.peaks/project-scan/project-scan.md` (tech stack + archetypes) — see `peaks workspace init` for the full 5-template boot (G4b/AC9).')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--read', 'read existing PROJECT.md without regenerating')).action((options) => runProjectContext(io, options));
+}

package/dist/cli/commands/project-dashboard-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerProjectDashboardCommand(project: Command, io: ProgramIO): void;

package/dist/cli/commands/project-dashboard-command.js

@@ -0,0 +1,74 @@
+// src/cli/commands/project-dashboard-command.ts
+//
+// `peaks project dashboard` — one-call snapshot of doctor / MCP / OpenSpec /
+// requests / capabilities for a project. Split out of `project-commands.ts`;
+// the verb name, its options, the gate order and the envelope shape are
+// unchanged.
+import { loadProjectDashboard } from '../../services/dashboard/project-dashboard-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+/** The runbook repairs the envelope names — only the ones that apply. */
+function runbookSuggestions(health) {
+    return [
+        health.missingRunbook.length > 0
+            ? `Add a ## Default runbook section to: ${health.missingRunbook.join(', ')}`
+            : null,
+        health.applyNoteFailed.length > 0
+            ? `Add authorization/--dry-run notes next to destructive --apply lines in: ${health.applyNoteFailed.join(', ')}`
+            : null
+    ].filter((line) => line !== null);
+}
+/** Runbook health — the first gate. */
+function runbookRefusal(dashboard) {
+    const health = dashboard.runbookHealth;
+    if (health.ok)
+        return null;
+    return fail('project.dashboard', 'PROJECT_DASHBOARD_RUNBOOK_UNHEALTHY', `Skill runbook health failing: ${health.healthy}/${health.required} healthy`, dashboard, runbookSuggestions(health));
+}
+/** A stale active skill presence — the second gate. */
+function skillPresenceRefusal(dashboard) {
+    const presence = dashboard.skillPresence;
+    if (!presence.active || presence.fresh)
+        return null;
+    return fail('project.dashboard', 'PROJECT_DASHBOARD_STALE_SKILL_PRESENCE', `Active Peaks skill presence ${presence.skill ?? '<unknown>'} is stale (set ${presence.setAt ?? '<unknown>'})`, dashboard, [
+        'Run `peaks skill presence:clear` if the role has ended, or `peaks skill presence:set <skill>` to refresh it'
+    ]);
+}
+/** The doctor aggregate under `--strict` — the third gate. */
+function doctorRefusal(dashboard, strict) {
+    if (dashboard.doctor.ok || !strict)
+        return null;
+    return fail('project.dashboard', 'PROJECT_DASHBOARD_DOCTOR_STRICT_FAIL', `Doctor reports ${dashboard.doctor.failed} failed check(s) (${dashboard.doctor.passed} passed) — --strict mode requires the doctor aggregate to pass`, dashboard, [
+        'Run `peaks doctor --json` and resolve the failing checks, or drop --strict to use the workspace-only policy'
+    ]);
+}
+/** The first gate that refuses, in the declared order: runbook → presence → doctor. */
+function dashboardRefusal(dashboard, strict) {
+    return (runbookRefusal(dashboard) ?? skillPresenceRefusal(dashboard) ?? doctorRefusal(dashboard, strict));
+}
+async function runProjectDashboard(io, options) {
+    try {
+        const dashboard = await loadProjectDashboard({
+            projectRoot: options.project,
+            okPolicy: options.strict === true ? 'strict' : 'workspace-only'
+        });
+        const refusal = dashboardRefusal(dashboard, options.strict === true);
+        if (refusal !== null) {
+            printResult(io, refusal, options.json);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok('project.dashboard', dashboard), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('project.dashboard', 'PROJECT_DASHBOARD_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path before retrying']), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerProjectDashboardCommand(project, io) {
+    addJsonOption(project
+        .command('dashboard')
+        .description('One-call snapshot of doctor / MCP / OpenSpec / requests / capabilities for a project')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--strict', 'ok follows the doctor aggregate (legacy semantics). Default: workspace-only (ok tracks the runbook health)', false)).action((options) => runProjectDashboard(io, options));
+}

package/dist/cli/commands/project-knowledge-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerProjectKnowledgeCommand(project: Command, io: ProgramIO): void;

package/dist/cli/commands/project-knowledge-command.js

@@ -0,0 +1,48 @@
+// src/cli/commands/project-knowledge-command.ts
+//
+// `peaks project knowledge` — read the schema-sedimented business-knowledge
+// concept table. Split out of `project-commands.ts`; the verb name, its
+// options, the `--filter` substring semantics and every envelope key are
+// unchanged.
+import { readBusinessKnowledge } from '../../services/prd/project-scan-reader.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+/** The `exists: true` payload, with the case-insensitive concept filter applied. */
+function knowledgeData(knowledge, filter) {
+    const concepts = filter
+        ? knowledge.concepts.filter((c) => c.concept.toLowerCase().includes(filter.toLowerCase()))
+        : knowledge.concepts;
+    return {
+        exists: true,
+        schemaVersion: knowledge.schemaVersion,
+        total: knowledge.concepts.length,
+        matched: concepts.length,
+        filter: filter ?? null,
+        concepts
+    };
+}
+async function runProjectKnowledge(io, options) {
+    try {
+        const knowledge = await readBusinessKnowledge(options.project);
+        if (knowledge === null) {
+            printResult(io, ok('project.knowledge', {
+                exists: false,
+                projectRoot: options.project,
+                path: `${options.project}/.peaks/project-scan/business-knowledge.md`
+            }), options.json);
+            return;
+        }
+        printResult(io, ok('project.knowledge', knowledgeData(knowledge, options.filter)), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('project.knowledge', 'PROJECT_KNOWLEDGE_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks/project-scan directory']), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerProjectKnowledgeCommand(project, io) {
+    addJsonOption(project
+        .command('knowledge')
+        .description('Read .peaks/project-scan/business-knowledge.md (the schema-sedimented concept table). LLM-consumable; use --filter for a concept substring.')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--filter <glob>', 'substring filter on the concept name (case-insensitive)')).action((options) => runProjectKnowledge(io, options));
+}

package/dist/cli/commands/project-memories-show-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerProjectMemoriesShowCommand(project: Command, io: ProgramIO): void;

package/dist/cli/commands/project-memories-show-command.js

@@ -0,0 +1,87 @@
+// src/cli/commands/project-memories-show-command.ts
+//
+// `peaks project memories:show <name>` — one memory body, compact by default.
+// Split out of `project-commands.ts`; the verb name, its options, the stale
+// threshold rules (R3/R4) and every envelope key are unchanged.
+import { readProjectMemoryBody } from '../../services/memory/project-memory-service.js';
+import { applyStalePolicy, DEFAULT_STALE_DAYS } from '../../shared/stale-policy.js';
+import { formatMdCompact } from '../../shared/format-md-compact.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+/** R4: the stale decision is computed at CLI load time only; the `.md` is never modified. */
+function memoryStalePolicy(memory, thresholdDays, includeStale) {
+    return applyStalePolicy([{ name: memory.name, updatedAt: memory.updatedAt }], {
+        thresholdDays,
+        includeStale
+    });
+}
+/** `--stale-days <n>` must be a finite positive number; anything else keeps the 30-day default. */
+function staleThresholdDays(options) {
+    const days = options.staleDays;
+    return days !== undefined && Number.isFinite(days) && days > 0 ? days : DEFAULT_STALE_DAYS;
+}
+/**
+ * The age the `MEMORY_STALE` refusal reports. The first policy call dropped the
+ * entry, so it cannot report the age — this second one keeps it (`includeStale`)
+ * purely to read `ageDays` back out.
+ */
+function staleRefusalAgeDays(memory, thresholdDays, droppedCount) {
+    return droppedCount > 0
+        ? (memoryStalePolicy(memory, thresholdDays, true).entries[0]?.ageDays ?? 0)
+        : 0;
+}
+/** The `ok` payload: the default `compact` body unless `--pretty` overrides it. */
+function memoriesShowData(memory, entry, options) {
+    const format = options.pretty === true ? 'pretty' : 'compact';
+    const body = format === 'pretty' ? memory.body : formatMdCompact(memory.body);
+    return {
+        name: memory.name,
+        title: memory.title,
+        kind: memory.kind,
+        sourcePath: memory.filePath,
+        updatedAt: memory.updatedAt,
+        ageDays: entry?.ageDays ?? 0,
+        stale: entry?.stale ?? false,
+        body,
+        format,
+        bodyBytes: Buffer.byteLength(body, 'utf8')
+    };
+}
+function memoryNotFound(name, project) {
+    return fail('project.memories:show', 'MEMORY_NOT_FOUND', `memory ${name} not found in .peaks/memory`, { name, projectRoot: project }, ['Run `peaks project memories --json` to see available names']);
+}
+function staleMemoryRefusal(name, project, ageDays, thresholdDays) {
+    return fail('project.memories:show', 'MEMORY_STALE', `memory ${name} is stale (age ${ageDays} days > ${thresholdDays} day threshold); pass --include-stale to override`, { name, ageDays, thresholdDays }, ['Pass --include-stale to load stale memories; pass --stale-days <N> to override the threshold']);
+}
+function runProjectMemoriesShow(io, name, options) {
+    try {
+        const memory = readProjectMemoryBody(options.project, name);
+        if (memory === null) {
+            printResult(io, memoryNotFound(name, options.project), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const thresholdDays = staleThresholdDays(options);
+        const policy = memoryStalePolicy(memory, thresholdDays, options.includeStale === true);
+        if (policy.entries.length === 0) {
+            const ageDays = staleRefusalAgeDays(memory, thresholdDays, policy.droppedCount);
+            printResult(io, staleMemoryRefusal(name, options.project, ageDays, thresholdDays), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok('project.memories:show', memoriesShowData(memory, policy.entries[0], options)), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('project.memories:show', 'PROJECT_MEMORY_SHOW_FAILED', getErrorMessage(error), { name, projectRoot: options.project }, ['Check the project path and .peaks/memory directory']), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerProjectMemoriesShowCommand(project, io) {
+    addJsonOption(project
+        .command('memories:show <name>')
+        .description('Show one project memory body by name. Default format is `compact` (LLM-primary); pass --pretty for the disk verbatim. Stale entries (default ≥30 days) are excluded; pass --include-stale or --stale-days <N> to override.')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--pretty', 'return the on-disk body verbatim; overrides the compact default')
+        .option('--include-stale', 'include stale entries (the default excludes them)')
+        .option('--stale-days <n>', 'override the 30-day stale threshold (must be > 0)', (value) => Number(value))).action((name, options) => runProjectMemoriesShow(io, name, options));
+}

package/dist/cli/commands/project-memory-index-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerProjectMemoryIndexCommand(project: Command, io: ProgramIO): void;

package/dist/cli/commands/project-memory-index-command.js

@@ -0,0 +1,31 @@
+// src/cli/commands/project-memory-index-command.ts
+//
+// `peaks project memory-index` — the lightweight hot/warm memory index read.
+// Split out of `project-commands.ts`; the verb name, its options and the
+// `exists` / `index` envelope shape are unchanged.
+import { readMemoryIndex } from '../../services/memory/project-memory-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+function runProjectMemoryIndex(io, options) {
+    try {
+        const index = readMemoryIndex(options.project);
+        if (!index) {
+            printResult(io, ok('project.memory-index', {
+                exists: false,
+                message: 'No memory index found. Run `peaks project memories:extract` first.'
+            }), options.json);
+            return;
+        }
+        printResult(io, ok('project.memory-index', { exists: true, index }), options.json);
+    }
+    catch (error) {
+        printResult(io, fail('project.memory-index', 'MEMORY_INDEX_FAILED', getErrorMessage(error), { projectRoot: options.project }, ['Check the project path and .peaks/memory directory']), options.json);
+        process.exitCode = 1;
+    }
+}
+export function registerProjectMemoryIndexCommand(project, io) {
+    addJsonOption(project
+        .command('memory-index')
+        .description('Read the memory index — lightweight hot/warm分层 view of all project memories')
+        .requiredOption('--project <path>', 'target project root')).action((options) => runProjectMemoryIndex(io, options));
+}

package/dist/cli/commands/qa-archive-screenshots-command.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerQaArchiveScreenshotsCommand(qa: Command, io: ProgramIO): void;

package/dist/cli/commands/qa-archive-screenshots-command.js

@@ -0,0 +1,53 @@
+// src/cli/commands/qa-archive-screenshots-command.ts
+//
+// `peaks qa archive-screenshots` — the remediation for peaks-qa SKILL.md
+// "Hard contracts for browser validation" Contract 1: every Playwright
+// `browser_take_screenshot` MUST land under
+// `.peaks/_runtime/<sessionId>/qa/screenshots/`, not at the project root. When
+// the LLM forgets to pass `filename`, Playwright MCP scatters `.png` files at
+// the repo top level; this verb scans `--source` (default: project root) and
+// moves strays into the session directory. Extracted from `qa-commands.ts`; the
+// registered name, options, envelope and exit codes are unchanged.
+import { join, resolve } from 'node:path';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { archiveScreenshots } from '../../services/qa/screenshot-archive-service.js';
+import { getSessionId } from '../../services/session/session-manager.js';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerQaArchiveScreenshotsCommand(qa, io) {
+    addJsonOption(qa
+        .command('archive-screenshots')
+        .description('Move stray Playwright screenshots (.png/.jpg/.jpeg) from the ' +
+        'project root into .peaks/_runtime/<session-id>/qa/screenshots/. ' +
+        'Enforces peaks-qa SKILL.md Contract 1.')
+        .option('--source <dir>', 'directory to scan for stray screenshots (default: project root)', '.')
+        .option('--project <path>', 'project root (default: cwd)', '.')
+        .option('--session-id <sid>', 'target session id; defaults to the active session', '')).action((options) => {
+        try {
+            const projectRoot = resolve(options.project);
+            const sid = options.sessionId?.trim() || getSessionId(projectRoot) || 'ad-hoc';
+            // Sid axis. Guarded after resolution so the flag value and the session
+            // binding are both covered. `archiveScreenshots` cannot do this itself:
+            // it only ever sees a fully-resolved `targetDir`.
+            if (isUnsafePathInput(sid)) {
+                throw new Error(`Invalid session id: ${sid} (must be a single path segment)`);
+            }
+            const targetDir = join(projectRoot, '.peaks', '_runtime', sid, 'qa', 'screenshots');
+            const envelope = archiveScreenshots({ sourceDir: options.source, targetDir });
+            printResult(io, ok('qa.archive-screenshots', envelope, [], archiveNextActions(envelope)), options.json);
+        }
+        catch (error) {
+            process.exitCode = 1;
+            printResult(io, fail('qa.archive-screenshots', 'ARCHIVE_FAILED', error instanceof Error ? error.message : 'Unknown error', { project: options.project, source: options.source }, ['Verify the source dir exists and is readable']), options.json);
+        }
+    });
+}
+/** The move notice, or the all-clear — never both. */
+function archiveNextActions(envelope) {
+    return envelope.moved.length === 0
+        ? ['No stray screenshots found in ' + envelope.scannedSource]
+        : [
+            `Moved ${envelope.moved.length} file(s) to ${envelope.targetDir}`,
+            'Re-run peaks qa run to verify the gate passes'
+        ];
+}

package/dist/cli/commands/qa-commands.d.ts

@@ -1,93 +1,20 @@
 /**
+ * `peaks qa run` — the peaks-qa slice surface, and `peaks qa archive-screenshots`
+ * — the Contract 1 remediation. The verbs live beside this file:
  *
- * `peaks qa run` — runs a peaks-qa slice for the active project.
+ *   `qa-run-command.ts`                 the slice action (I/O + envelope)
+ *   `qa-run-slice.ts`                   the pure gate list it drives
+ *   `qa-run-options.ts`                 the `--no-X` flag contract
+ *   `qa-context-prestep.ts`              Plan 1 / Task 9 context build
+ *   `qa-archive-screenshots-command.ts` the stray-screenshot sweep
  *
- * The slice is the user-facing surface for the QA gate family
- * (functional / security / browser E2E). The browser-E2E gate
- * specifically is what the restart-loop detector guards. The
- * detector is wired into the slice here:
- *
- *   1. We construct a `BrowserRestartDetector` (configurable via
- *      `--max-browser-restarts` / `--no-restart-detector`).
- *   2. We construct a `BrowserEventLogger` that writes the
- *      per-slice JSONL log to
- *      `.peaks/_runtime/<session-id>/qa/browser-events.jsonl`.
- *   3. The slice entry exposes `runQaSlice` so tests can
- *      feed a synthetic event log and assert the diagnostic.
- *
- * CLI surface (PRD G5 + AC4/AC5/AC6):
- *   peaks qa run --project <X> [--no-browser] [--max-browser-restarts N]
- *                       [--no-restart-detector] [--session-id <sid>] [--json]
- *
- * `--no-browser` (G5) skips the browser E2E gate entirely. The
- * resulting gate list marks the browser gate as `status: skipped`
- * with reason `--no-browser`. This is a slice-level opt-out for
- * backend-only or already-covered-by-unit-tests work.
+ * This module owns only the `qa` parent (hidden) and the registrar order, and
+ * re-exports every symbol it used to define so existing importers need no edit.
  */
 import type { Command } from 'commander';
-import { type ProgramIO } from '../cli-helpers.js';
-import { type BrowserEvent } from '../../services/qa/browser-restart-detector.js';
-import { type MutReportJson } from 'peaks-loop-mut';
-export type QaRunOptions = {
-    project: string;
-    browser?: boolean;
-    restartDetector?: boolean;
-    maxBrowserRestarts?: string;
-    sessionId?: string;
-    json?: boolean;
-    mutation?: boolean;
-};
-export type QaGateStatus = {
-    readonly name: string;
-    readonly status: 'passed' | 'skipped' | 'failed';
-    readonly reason?: string;
-    /**
-     * Plan 2 / Task 8 — when the gate consumes an artifact with a
-     * deterministic signature, this field carries that signature for
-     * downstream audit-trail consumers. Currently set only on the
-     * `mutation` gate to MUT.sig (the `sha256` of mut-report.json).
-     */
-    readonly mutSig?: string;
-};
-export type QaRunResult = {
-    readonly sessionId: string;
-    readonly project: string;
-    readonly browserEnabled: boolean;
-    readonly gates: readonly QaGateStatus[];
-    readonly detectorTriggered: boolean;
-    readonly diagnostic?: string;
-    readonly subAgentPromptHint: string;
-    /**
-     * Plan 2 / Task 8 — MUT.sig when peaks-mut ran in this session.
-     * Undefined when peaks-mut was not run (no mut-report.json) or
-     * the user passed --no-mutation.
-     */
-    readonly mutSig?: string;
-};
-export declare const DEFAULT_MAX_BROWSER_RESTARTS = 3;
-export type RunQaSliceInput = {
-    readonly project: string;
-    readonly sessionId: string;
-    readonly browserEnabled: boolean;
-    readonly maxRestarts: number;
-    readonly detectorEnabled: boolean;
-    readonly events: readonly BrowserEvent[];
-    readonly mutationReport: MutReportJson | null;
-    readonly mutationEnabled: boolean;
-};
-export declare function runQaSlice(input: RunQaSliceInput): QaRunResult;
-/**
- * Commander 12.x sets `options.X = false` for `--no-X` (POSITIVE form),
- * not `options.noX = true`. Reads use the positive form; the default is
- * `true` and the boolean form is `false` only when the user passes `--no-X`.
- *
- * Exported for unit testing the parser contract in isolation from
- * the rest of the action handler.
- */
-export declare function readQaRunOptions(options: QaRunOptions): {
-    readonly browserEnabled: boolean;
-    readonly detectorEnabled: boolean;
-    readonly maxRestarts: number;
-    readonly mutationEnabled: boolean;
-};
+import type { ProgramIO } from '../cli-helpers.js';
 export declare function registerQaCommands(program: Command, io: ProgramIO): void;
+export { readQaRunOptions } from './qa-run-options.js';
+export type { QaRunOptions } from './qa-run-options.js';
+export { DEFAULT_MAX_BROWSER_RESTARTS, runQaSlice } from './qa-run-slice.js';
+export type { QaGateStatus, QaRunResult, RunQaSliceInput } from './qa-run-slice.js';