peaks-loop 4.0.0-beta.2 → 4.0.0-beta.21

package/dist/services/workflow/autonomous-resume-writer.js

@@ -0,0 +1,170 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { getSessionDir } from '../session/getSessionDir.js';
+import { pathExists } from 'peaks-loop-shared/fs';
+import { isUnsafePathInput } from '../../shared/path-safety.js';
+function defaultClock() {
+    return new Date().toISOString();
+}
+function normalizeGoal(goal) {
+    const trimmed = goal.trim();
+    if (!trimmed) {
+        throw new Error('Goal must be non-empty');
+    }
+    return trimmed;
+}
+function renderGoalPackage(sessionId, goal) {
+    return `${JSON.stringify({
+        sessionId,
+        artifactType: 'goal-package',
+        status: 'ready',
+        goal,
+        doneCondition: `Autonomous plan for ${sessionId} is complete when all acceptance criteria pass, the worker queue is empty or blocked with next actions, and validation evidence is recorded.`,
+        resumeCondition: `Resume ${sessionId} only after checkpoint artifacts, worker queue state, and validation evidence requirements have been verified.`,
+        acceptanceCriteria: [
+            'A resumable autonomous RD plan exists with checkpoints, worker queue, and validation evidence requirements.',
+            'Curated capabilities from docs/accessRepo.md and docs/mcpServer.md are considered before custom implementation.',
+            'Resume after compact verifies checkpoints and evidence before continuing.',
+            'All execution remains dry-run until explicitly approved.'
+        ]
+    }, null, 2)}\n`;
+}
+function renderRdPlan(sessionId) {
+    return `${JSON.stringify({
+        sessionId,
+        artifactType: 'rd-plan',
+        status: 'ready',
+        workerQueueStatus: 'ready',
+        taskCount: 1,
+        reducerRequired: true
+    }, null, 2)}\n`;
+}
+function renderCheckpoint(sessionId, createdAt) {
+    return `${JSON.stringify({
+        sessionId,
+        artifactType: 'checkpoint',
+        status: 'ready',
+        checkpointId: 'checkpoint-1',
+        createdAt,
+        workerQueueState: {},
+        validationRefs: ['unit-tests.md']
+    }, null, 2)}\n`;
+}
+function renderValidationReport(sessionId) {
+    return `---
+sessionId: ${sessionId}
+artifactType: validation-report
+status: passed
+---
+
+Validation summary:
+
+- Resume artifact scaffold generated for ${sessionId}.
+
+Checks:
+
+- unit-tests
+
+Result: passed
+
+Evidence refs:
+
+- unit-tests.md
+`;
+}
+function renderUnitTestsEvidence(sessionId) {
+    return `# unit-tests evidence for ${sessionId}
+
+Replace this stub with the real test command, output, and coverage delta. The autonomous resume validator only requires this file to exist and be a safe markdown name listed in checkpoint-1.json validationRefs.
+`;
+}
+function renderResumeInstructions(sessionId) {
+    return `---
+sessionId: ${sessionId}
+artifactType: resume-instructions
+status: passed
+---
+
+Resume steps:
+
+- Read autonomous-goal-package.json and confirm acceptance criteria.
+- Read autonomous-rd-plan.json and reconcile worker queue with current diff.
+- Read checkpoint-1.json and verify worker queue state matches what is on disk.
+- Read evidence/*.md referenced by checkpoint validationRefs and confirm Result: passed.
+
+Preconditions:
+
+- Artifact workspace is local and matches sessionId ${sessionId}.
+- No destructive --apply has run without explicit authorization.
+
+Blocked actions:
+
+- Resume cannot proceed if checkpoint validationRefs or evidence files are missing or invalid.
+
+Next actions:
+
+- Run peaks workflow autonomous --change-id ${sessionId} --goal "<goal>" --json to recompute the plan.
+- Compare blockedReasons; resolve before reattempting resume.
+`;
+}
+function buildFiles(sessionId, goal, createdAt, artifactWorkspacePath) {
+    // Slice 2026-06-29-change-id-root-removal: route every reviewable
+    // artifact under the session-axis dir at `.peaks/_runtime/<sid>/...`
+    // via `getSessionDir`. The change-id identifier is reused as the
+    // session-dir name (per-execution scope). The gitignore rule on
+    // `.peaks/_runtime/` covers the path; the reviewable-vs-ephemeral
+    // split is preserved.
+    const scopeRoot = getSessionDir(artifactWorkspacePath, sessionId);
+    return [
+        {
+            path: join(scopeRoot, 'prd', 'autonomous-goal-package.json'),
+            content: renderGoalPackage(sessionId, goal)
+        },
+        {
+            path: join(scopeRoot, 'rd', 'swarm', 'autonomous-rd-plan.json'),
+            content: renderRdPlan(sessionId)
+        },
+        {
+            path: join(scopeRoot, 'rd', 'swarm', 'checkpoints', 'checkpoint-1.json'),
+            content: renderCheckpoint(sessionId, createdAt)
+        },
+        {
+            path: join(scopeRoot, 'rd', 'swarm', 'evidence', 'unit-tests.md'),
+            content: renderUnitTestsEvidence(sessionId)
+        },
+        {
+            path: join(scopeRoot, 'rd', 'swarm', 'evidence', 'validation-report.md'),
+            content: renderValidationReport(sessionId)
+        },
+        {
+            path: join(scopeRoot, 'rd', 'swarm', 'resume-instructions.md'),
+            content: renderResumeInstructions(sessionId)
+        }
+    ];
+}
+export async function writeAutonomousResumeArtifacts(request) {
+    // Slice 2026-06-29-change-id-root-removal: change-id is metadata-only;
+    // structural validation for the session id is a path-safety check
+    // (no path-traversal / no absolute path) so unsafe ids never escape
+    // the canonical `.peaks/_runtime/<sid>/` scope.
+    if (isUnsafePathInput(request.sessionId)) {
+        throw new Error(`Refusing to write: session id '${request.sessionId}' is unsafe (path-traversal, absolute, or otherwise malformed).`);
+    }
+    const goal = normalizeGoal(request.goal);
+    const clock = request.clock ?? defaultClock;
+    const createdAt = clock();
+    const files = buildFiles(request.sessionId, goal, createdAt, request.artifactWorkspacePath);
+    if (request.apply !== true) {
+        return { applied: false, files };
+    }
+    for (const file of files) {
+        if (await pathExists(file.path)) {
+            throw new Error(`Refusing to write: ${file.path} already exists. Remove it before re-running peaks autonomous resume init --apply.`);
+        }
+    }
+    for (const file of files) {
+        await mkdir(dirname(file.path), { recursive: true });
+        await writeFile(file.path, file.content, 'utf8');
+    }
+    return { applied: true, files };
+}

package/dist/services/workflow/plan-reader.d.ts

@@ -0,0 +1,29 @@
+import { type ResultEnvelope } from 'peaks-loop-shared/result';
+export type PlanType = 'security' | 'perf';
+/** Back-compat env-var. When set to "1", fall back to legacy paths. */
+export declare const BACK_COMPAT_FLAG = "PEAKS_PLAN_LEGACY_FALLBACK";
+/** F-1 (slice 025 security): canonical session-id shape. */
+export declare const SESSION_ID_PATTERN: RegExp;
+export interface ReadPlanArgs {
+    readonly type: PlanType;
+    readonly project: string;
+    readonly sessionId: string;
+}
+export interface ReadPlanData {
+    readonly type: PlanType;
+    readonly exists: boolean;
+    readonly path: string;
+    readonly hash: string | null;
+    readonly refreshedAt: string | null;
+    /** `'canonical' | 'legacy' | 'missing'` — surfaced to the slice workflow
+     * so it can warn the user about a back-compat fallback. */
+    readonly source: 'canonical' | 'legacy' | 'missing';
+}
+/**
+ * Normalize a markdown body for hashing. Sections sorted, blank lines
+ * collapsed, leading/trailing whitespace stripped. Hash is sha256[0:12].
+ */
+export declare function normalizePlanBody(body: string): string;
+/** Compute the deterministic plan hash on a normalized body. */
+export declare function hashNormalizedBody(body: string): string;
+export declare function readPlan(args: ReadPlanArgs): ResultEnvelope<ReadPlanData>;

package/dist/services/workflow/plan-reader.js

@@ -0,0 +1,174 @@
+/**
+ * `peaks workflow plan read` — slice 025 (Security + Perf Plan/Result split).
+ *
+ * Returns the envelope `{ exists, path, hash, refreshedAt }` for the
+ * session-scoped security-test-plan or perf-baseline plan. The hash is
+ * computed on the **normalized** body (sections sorted, blank lines
+ * collapsed) so it is independent of cosmetic re-ordering; mtime is
+ * surfaced as ISO-8601.
+ *
+ * Back-compat: when the BACK_COMPAT_FLAG env var is "1" and the
+ * legacy path (`.peaks/_runtime/<planFile>` at the project root) exists but
+ * the canonical session path does not, the reader falls back to the
+ * legacy path and reports `source: "legacy"`.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { getSessionDir } from '../session/getSessionDir.js';
+/** Back-compat env-var. When set to "1", fall back to legacy paths. */
+export const BACK_COMPAT_FLAG = 'PEAKS_PLAN_LEGACY_FALLBACK';
+/** F-1 (slice 025 security): canonical session-id shape. */
+export const SESSION_ID_PATTERN = /^\d{4}-\d{2}-\d{2}-[a-z][a-z0-9-]*[a-z0-9]$/;
+const PLAN_FILE = {
+    security: 'security-test-plan.md',
+    perf: 'perf-baseline.md'
+};
+/**
+ * Normalize a markdown body for hashing. Sections sorted, blank lines
+ * collapsed, leading/trailing whitespace stripped. Hash is sha256[0:12].
+ */
+export function normalizePlanBody(body) {
+    const lines = body
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+    return lines.sort().join('\n');
+}
+/** Compute the deterministic plan hash on a normalized body. */
+export function hashNormalizedBody(body) {
+    const normalized = normalizePlanBody(body);
+    return createHash('sha256').update(normalized, 'utf8').digest('hex').slice(0, 12);
+}
+function canonicalPath(args) {
+    return join(getSessionDir(args.projectRoot, args.sessionId), 'qa', PLAN_FILE[args.type]);
+}
+function legacyPath(args) {
+    return join(args.projectRoot, '.peaks', PLAN_FILE[args.type]);
+}
+/** Build the data envelope for a path that exists. */
+function buildData(args) {
+    const stats = statSync(args.path);
+    return {
+        type: args.type,
+        exists: true,
+        path: args.path,
+        hash: hashNormalizedBody(readFileSync(args.path, 'utf8')),
+        refreshedAt: stats.mtime.toISOString(),
+        source: args.source
+    };
+}
+/**
+ * F-2 (slice 025 security): resolve symlinks and confirm the real path
+ * still lives under the expected base directory. A canonical path
+ * may itself be a symlink (or a directory in the path chain may be),
+ * which would let a malicious or accidental symlink escape the
+ * `.peaks/_runtime/<sessionId>/` containment. We reject anything
+ * whose real path falls outside the expected base.
+ *
+ * The caller passes the expected base:
+ *   - session dir for canonical reads (`.peaks/_runtime/<sid>/qa/...`)
+ *   - project root for legacy back-compat reads (`.peaks/_runtime/<planFile>`)
+ */
+function assertContained(args) {
+    let real;
+    try {
+        real = realpathSync(args.path);
+    }
+    catch {
+        // If realpath fails (e.g. broken symlink), treat as escape — never
+        // return "ok" without a verified real path.
+        return {
+            ok: false,
+            code: 'SYMLINK_ESCAPE',
+            message: `resolved path escapes base directory: cannot resolve ${args.path}`
+        };
+    }
+    // Slice 2026-06-13-repair-pre-existing-test-failures: realpath the
+    // expectedBase too. On macOS the OS exposes /tmp and
+    // /var/folders/... as symlinks to /private/tmp and
+    // /private/var/folders/.... `mkdtempSync` returns the unresolved
+    // form; the file inside resolves through the symlink. Without
+    // symmetric realpath on both sides, the prefix check incorrectly
+    // rejects a file that is genuinely inside the base directory.
+    // Falls back to the raw expectedBase when the base itself does
+    // not yet exist (e.g. the canonical session dir before first
+    // write), preserving the pre-fix behavior for that case.
+    let expectedPrefix;
+    try {
+        expectedPrefix = join(realpathSync(args.expectedBase), sep);
+    }
+    catch {
+        expectedPrefix = join(args.expectedBase, sep);
+    }
+    if (!real.startsWith(expectedPrefix)) {
+        return {
+            ok: false,
+            code: 'SYMLINK_ESCAPE',
+            message: `resolved path escapes base directory: ${real} is not under ${expectedPrefix}`
+        };
+    }
+    return { ok: true, real };
+}
+export function readPlan(args) {
+    // F-1 (slice 025 security): reject path-traversal payloads before any
+    // filesystem call. The CLI also validates, but the service is the
+    // authoritative gate — every caller (CLI, skill, integration test)
+    // benefits from the same rejection shape.
+    if (!SESSION_ID_PATTERN.test(args.sessionId)) {
+        return fail('workflow.plan.read', 'INVALID_SESSION_ID', 'session id must match YYYY-MM-DD-slug pattern', {
+            type: args.type,
+            exists: false,
+            path: '',
+            hash: null,
+            refreshedAt: null,
+            source: 'missing'
+        });
+    }
+    const canonical = canonicalPath({ projectRoot: args.project, sessionId: args.sessionId, type: args.type });
+    if (existsSync(canonical)) {
+        const guard = assertContained({
+            expectedBase: getSessionDir(args.project, args.sessionId),
+            path: canonical
+        });
+        if (!guard.ok) {
+            return fail('workflow.plan.read', guard.code, guard.message, {
+                type: args.type,
+                exists: false,
+                path: canonical,
+                hash: null,
+                refreshedAt: null,
+                source: 'missing'
+            });
+        }
+        return ok('workflow.plan.read', buildData({ type: args.type, path: canonical, source: 'canonical' }));
+    }
+    const legacy = legacyPath({ projectRoot: args.project, type: args.type });
+    const backCompatEnabled = process.env[BACK_COMPAT_FLAG] === '1';
+    if (backCompatEnabled && existsSync(legacy)) {
+        const guard = assertContained({
+            expectedBase: args.project,
+            path: legacy
+        });
+        if (!guard.ok) {
+            return fail('workflow.plan.read', guard.code, guard.message, {
+                type: args.type,
+                exists: false,
+                path: legacy,
+                hash: null,
+                refreshedAt: null,
+                source: 'missing'
+            });
+        }
+        return ok('workflow.plan.read', buildData({ type: args.type, path: legacy, source: 'legacy' }));
+    }
+    return ok('workflow.plan.read', {
+        type: args.type,
+        exists: false,
+        path: canonical,
+        hash: null,
+        refreshedAt: null,
+        source: 'missing'
+    });
+}

package/dist/services/workflow/plan-refresher.d.ts

@@ -0,0 +1,32 @@
+import { type ResultEnvelope } from 'peaks-loop-shared/result';
+import { normalizePlanBody, type PlanType } from './plan-reader.js';
+export interface RefreshPlanArgs {
+    readonly type: PlanType;
+    readonly project: string;
+    readonly sessionId: string;
+    /** When true, write the plan to disk. When false, return the would-be body + hash only. */
+    readonly apply: boolean;
+}
+export interface RefreshPlanData {
+    readonly type: PlanType;
+    readonly writtenFiles: string[];
+    /** When `apply=false`, the would-be write targets. */
+    readonly wouldWrite: string[];
+    readonly hash: string;
+    readonly refreshedAt: string;
+    readonly dryRun: boolean;
+    /** The deterministic body (post-normalization). Always surfaced so tests
+     * can assert byte-equality across runs. */
+    readonly bodyPreview: string;
+}
+/** Build the security-test-plan body deterministically. */
+export declare function buildSecurityPlanBody(projectRoot: string): string;
+/** Build the perf-baseline body deterministically. */
+export declare function buildPerfPlanBody(projectRoot: string): string;
+export declare function refreshPlan(args: RefreshPlanArgs): ResultEnvelope<RefreshPlanData>;
+export { normalizePlanBody };
+export declare function renderPlanBody(args: {
+    type: PlanType;
+    project: string;
+}): string;
+export declare function hashBody(body: string): string;