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

package/dist/services/workflow/artifact-paths.js

@@ -0,0 +1,166 @@
+/**
+ * Cross-slice artifact path resolvers (slice 025 — Security + Perf
+ * Plan/Result split).
+ *
+ * The plan/result split introduces per-request `<rid>`-suffixed QA
+ * artifacts (`security-findings-<rid>.md`, `performance-findings-<rid>.md`)
+ * in addition to the legacy non-suffixed form. This module is the single
+ * source of truth for the canonical and legacy paths and the lazy
+ * migration that bridges the 1-minor-release back-compat window.
+ *
+ * v2.17.0 hard-kill: the canonical QA artifact dir is the SESSION
+ * axis `.peaks/_runtime/<sessionId>/qa/`. The pre-v2.17.0 change axis
+ * `.peaks/_runtime/change/<sessionId>/qa/` is kept as a back-compat
+ * fallback for un-migrated workspaces — when consumed, the resolver
+ * tags the form `'legacy'` so Gate C can surface the deprecation
+ * warning. Same for the legacy misplaced `.peaks/<sessionId>/qa/` form.
+ */
+import { existsSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+const QA_DIR = 'qa';
+/** File name (with `<rid>` suffix) for the per-request security findings delta. */
+export const SECURITY_FINDINGS_SUFFIXED = (rid) => `security-findings-${rid}.md`;
+/** File name (legacy, no `<rid>` suffix) for the security findings artifact. */
+export const SECURITY_FINDINGS_LEGACY = 'security-findings.md';
+/** File name (with `<rid>` suffix) for the per-request performance findings delta. */
+export const PERFORMANCE_FINDINGS_SUFFIXED = (rid) => `performance-findings-${rid}.md`;
+/** File name (legacy, no `<rid>` suffix) for the performance findings artifact. */
+export const PERFORMANCE_FINDINGS_LEGACY = 'performance-findings.md';
+/** Base name (no extension) shared by both the suffixed and legacy forms. */
+const SECURITY_FINDINGS_BASE = 'security-findings';
+const PERFORMANCE_FINDINGS_BASE = 'performance-findings';
+/**
+ * v2.17.0 — canonical QA dir is the session axis
+ * `.peaks/_runtime/<sessionId>/qa/`. The pre-v2.17.0 change axis
+ * `.peaks/_runtime/change/<sessionId>/qa/` is kept as a back-compat
+ * fallback for un-migrated workspaces. The legacy misplaced
+ * `.peaks/<sessionId>/qa/` form was a pre-1.3.0 write-path bug.
+ *
+ * Slice 2026-06-29-change-id-root-removal: the legacy
+ * `peaks workspace migrate-change-scope` migration tool is gone;
+ * operators must move misplaced dirs into the canonical location
+ * by hand (or via `peaks workspace migrate`).
+ *
+ * During a 1-minor-release deprecation window the resolver falls back
+ * to the legacy paths so un-migrated workspaces still resolve. When
+ * a fallback fires, the result is tagged `'legacy'`.
+ */
+function canonicalQaDir(projectRoot, sessionId) {
+    // v2.17.0 canonical: session axis. The `<sessionId>` arg is treated
+    // as the on-disk session dir name (it equals the sessionId under
+    // the session-axis layout). Under v2.16.0 layouts the same string
+    // was the change-id dir name.
+    return join(projectRoot, '.peaks', '_runtime', sessionId, QA_DIR);
+}
+function legacyChangeAxisQaDir(projectRoot, sessionId) {
+    return join(projectRoot, '.peaks', '_runtime', 'change', sessionId, QA_DIR);
+}
+function legacyMisplacedQaDir(projectRoot, sessionId) {
+    return join(projectRoot, '.peaks', sessionId, QA_DIR);
+}
+/**
+ * Try the most-specific read first: the suffixed form. On miss, fall back
+ * to the legacy form. On legacy hit, run a one-shot lazy migration that
+ * renames the legacy file to `<base>-<rid>.md` (when the legacy body
+ * contains a recognizable rid), or leaves a 3-line redirect stub.
+ *
+ * Pure path resolver: does NOT write any new content. The lazy migration
+ * only renames an existing file; it does not invent data.
+ */
+function resolveFindingsPath(args) {
+    const qaDir = canonicalQaDir(args.projectRoot, args.sessionId);
+    if (args.rid !== undefined) {
+        const suffixedPath = join(qaDir, args.suffixedFile(args.rid));
+        if (existsSync(suffixedPath)) {
+            return { path: suffixedPath, form: 'suffixed', redirectedFrom: null, rid: args.rid };
+        }
+        // Try the v2.16.0 change-axis dir, the pre-1.3.0 misplaced
+        // `.peaks/<id>/qa/` form, and the sibling-of-`_runtime/` form.
+        // All three are migration targets handled in v2.19.0+ by
+        // manual relocation into the canonical location (the legacy
+        // `peaks workspace migrate-change-scope` CLI was removed).
+        const legacyCandidates = [
+            join(legacyChangeAxisQaDir(args.projectRoot, args.sessionId), args.suffixedFile(args.rid)),
+            join(legacyMisplacedQaDir(args.projectRoot, args.sessionId), args.suffixedFile(args.rid)),
+            join(legacyChangeAxisQaDir(args.projectRoot, args.sessionId), args.legacyFile),
+            join(legacyMisplacedQaDir(args.projectRoot, args.sessionId), args.legacyFile)
+        ];
+        for (const candidate of legacyCandidates) {
+            if (existsSync(candidate)) {
+                return {
+                    path: candidate,
+                    form: 'legacy',
+                    redirectedFrom: null,
+                    rid: args.rid
+                };
+            }
+        }
+        // No file present; report the would-be suffixed path so the caller can
+        // surface it in error messages.
+        return { path: suffixedPath, form: 'suffixed', redirectedFrom: null, rid: args.rid };
+    }
+    // rid is undefined — caller wants the legacy single-file form.
+    const legacyPath = join(qaDir, args.legacyFile);
+    if (existsSync(legacyPath)) {
+        return { path: legacyPath, form: 'legacy', redirectedFrom: null, rid: null };
+    }
+    return { path: legacyPath, form: 'legacy', redirectedFrom: null, rid: null };
+}
+/**
+ * Resolve the security-findings artifact path. Preferred form is the
+ * `<rid>`-suffixed path; legacy non-suffixed path is accepted as a
+ * 1-minor-release back-compat fallback.
+ *
+ * When `rid` is provided and the suffixed form is missing, the legacy
+ * form is reported (NOT the suffixed path) so the caller can decide to
+ * log a warning. When `rid` is undefined, the legacy form is the
+ * canonical target.
+ */
+export function resolveSecurityFindingsPath(args) {
+    return resolveFindingsPath({
+        projectRoot: args.projectRoot,
+        sessionId: args.sessionId,
+        ...(args.rid !== undefined ? { rid: args.rid } : {}),
+        base: SECURITY_FINDINGS_BASE,
+        legacyFile: SECURITY_FINDINGS_LEGACY,
+        suffixedFile: SECURITY_FINDINGS_SUFFIXED
+    });
+}
+/** Resolve the performance-findings artifact path (mirror of `resolveSecurityFindingsPath`). */
+export function resolvePerformanceFindingsPath(args) {
+    return resolveFindingsPath({
+        projectRoot: args.projectRoot,
+        sessionId: args.sessionId,
+        ...(args.rid !== undefined ? { rid: args.rid } : {}),
+        base: PERFORMANCE_FINDINGS_BASE,
+        legacyFile: PERFORMANCE_FINDINGS_LEGACY,
+        suffixedFile: PERFORMANCE_FINDINGS_SUFFIXED
+    });
+}
+/**
+ * Lazy migration: rename a legacy non-suffixed QA artifact to the
+ * suffixed form for the given rid. Idempotent — re-running is a no-op
+ * once the suffixed form exists.
+ *
+ * Returns the resulting path. Callers (Gate C in `pipeline-verify-service.ts`)
+ * log a warning when the legacy form is the one consumed.
+ */
+export function lazyMigrateLegacyFindings(args) {
+    // Slice 2026-06-28: lazy migration operates on the canonical QA dir.
+    const qaDir = canonicalQaDir(args.projectRoot, args.sessionId);
+    const legacyPath = join(qaDir, args.legacyFile);
+    const suffixedPath = join(qaDir, args.suffixedFile(args.rid));
+    if (!existsSync(legacyPath)) {
+        return { renamed: false, path: suffixedPath };
+    }
+    if (existsSync(suffixedPath)) {
+        return { renamed: false, path: suffixedPath };
+    }
+    try {
+        renameSync(legacyPath, suffixedPath);
+        return { renamed: true, path: suffixedPath };
+    }
+    catch {
+        return { renamed: false, path: legacyPath };
+    }
+}

package/dist/services/workflow/autonomous-resume-writer.d.ts

@@ -0,0 +1,16 @@
+export type AutonomousResumeWriteRequest = {
+    readonly sessionId: string;
+    readonly goal: string;
+    readonly artifactWorkspacePath: string;
+    readonly apply?: boolean;
+    readonly clock?: () => string;
+};
+export type AutonomousResumeArtifactFile = {
+    readonly path: string;
+    readonly content: string;
+};
+export type AutonomousResumeWriteResult = {
+    readonly applied: boolean;
+    readonly files: readonly AutonomousResumeArtifactFile[];
+};
+export declare function writeAutonomousResumeArtifacts(request: AutonomousResumeWriteRequest): Promise<AutonomousResumeWriteResult>;

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 '../../shared/fs.js';
+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/pipeline-verify-service.d.ts

@@ -0,0 +1,90 @@
+import type { RequestType } from '../artifacts/artifact-prerequisites.js';
+export type PipelineGate = {
+    name: string;
+    description: string;
+    passed: boolean;
+    detail: string;
+    /**
+     * Slice 2026-06-13-peaks-workflow-skip: optional status that
+     * distinguishes a gate that was BYPASSED via `peaks workflow skip`
+     * from one that actually passed evaluation. When set, the gate
+     * was NOT evaluated by `evaluateGate` — the user/CLI explicitly
+     * marked it as skipped. The boolean `passed` is set to `true` so
+     * existing consumers (which only check `passed`) treat a skipped
+     * gate as "satisfied", but downstream consumers that need
+     * audit-grade distinction (e.g. CI badges, dashboards) can read
+     * `status` to tell pass / fail / skipped apart.
+     *
+     *   - omitted (default): not set, gate was evaluated; treat as legacy.
+     *   - 'pass':          gate evaluated and passed.
+     *   - 'fail':          gate evaluated and failed.
+     *   - 'skipped':       gate was bypassed; never evaluated.
+     */
+    status?: 'pass' | 'fail' | 'skipped';
+};
+export type PipelineVerification = {
+    rid: string;
+    sessionId: string;
+    requestType: RequestType;
+    complete: boolean;
+    rdPhase: {
+        invoked: boolean;
+        state: string;
+        gates: PipelineGate[];
+    };
+    qaPhase: {
+        invoked: boolean;
+        state: string;
+        gates: PipelineGate[];
+    };
+    /**
+     * Slice 002 (v2.15.0) AC-3: Gate H "feedback-promotion". Always
+     * present (single-element array). Evaluates whether every
+     * `metadata.type === 'feedback'` memory in `.peaks/memory/`
+     * carries a promotion marker (comment OR sidecar). Failures
+     * block the `complete` verdict via the `gateH` field below; the
+     * pipeline only completes when every gate in this array passes.
+     */
+    feedbackPhase?: {
+        gates: PipelineGate[];
+    };
+    violations: string[];
+    nextActions: string[];
+    /** Form of the security/performance findings artifacts Gate C accepted
+     * (slice 025). `'suffixed'` for the new per-rid form, `'legacy'` for the
+     * pre-slice-025 non-suffixed form, `'none'` when neither was found. */
+    acceptedForm?: 'suffixed' | 'legacy' | 'none';
+    /** `gateC` is the pre-computed verdict string (AC7 dogfood shape). */
+    gateC?: 'pass' | 'fail';
+    /**
+     * Slice 002 (v2.15.0) AC-3: Gate H verdict string. `'pass'` when
+     * all feedback memories are promoted; `'fail'` when at least one
+     * unpromoted feedback memory was found.
+     */
+    gateH?: 'pass' | 'fail';
+    /**
+     * Slice 2026-06-28-code-mode-bypass-fix (defect #3): `true` when
+     * every evidence file resolved on the canonical path
+     * (`.peaks/_runtime/change/<sessionId>/...`). `false` when at least
+     * one evidence file resolved via a legacy fallback (`.peaks/<sessionId>/...`
+     * or `.peaks/_runtime/<sessionId>/...`). QA / TXT surface the value
+     * so users know to move misplaced evidence into the canonical
+     * location.
+     *
+     * Slice 2026-06-29-change-id-root-removal: the legacy
+     * `peaks workspace migrate-change-scope` migration tool is gone;
+     * users must now move misplaced content into the canonical
+     * `.peaks/_runtime/change/<sessionId>/<role>/` dir manually (or via
+     * `peaks workspace migrate`).
+     */
+    usedCanonicalPath?: boolean;
+};
+export declare function verifyPipeline(options: {
+    projectRoot: string;
+    rid: string;
+    /** Optional explicit session-id; when omitted, the RD/QA on-disk location
+     * is resolved via showRequestArtifact (which scans all top-level dirs and
+     * returns the actual session-id the file lives in). */
+    sessionId?: string;
+    requestType?: string;
+}): Promise<PipelineVerification>;