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

package/dist/services/workflow/pipeline-verify-service.js

@@ -0,0 +1,449 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { isRequestType } from '../artifacts/artifact-prerequisites.js';
+import { showRequestArtifact } from '../artifacts/request-artifact-service.js';
+import { resolveSecurityFindingsPath, resolvePerformanceFindingsPath } from './artifact-paths.js';
+import { readSkipState } from './workflow-state-store.js';
+import { getSessionIdCanonical } from '../session/session-manager.js';
+import { listUnpromotedFeedback } from '../feedback/feedback-promotion-service.js';
+function extractState(markdown) {
+    for (const rawLine of markdown.split(/\r?\n/)) {
+        const match = /^-\s*state:\s*(.+?)\s*$/.exec(rawLine.trim());
+        if (match?.[1])
+            return match[1];
+    }
+    return 'unknown';
+}
+/**
+ * As of slice 2026-06-05-change-id-as-unit-of-work, the file's durable
+ * scope is the change-id (the `.peaks/_runtime/<sessionId>/` dir the file lives
+ * in), NOT the session-id. We resolve the on-disk location via
+ * `showRequestArtifact` (which scans all top-level dirs and returns the
+ * actual dir the file was found in) instead of assuming
+ * `.peaks/_runtime/<sessionId>/<role>/requests/`.
+ */
+async function findRequestFile(projectRoot, role, rid) {
+    const artifact = await showRequestArtifact({ projectRoot, role: role, requestId: rid });
+    if (artifact === null)
+        return null;
+    // Slice 2026-06-28-code-mode-bypass-fix (defect #3): the legacy
+    // `showRequestArtifact` returns the FULL SCOPE (`_runtime/<sid>`)
+    // as `sessionId`, not just the trailing id segment. The canonical
+    // evidence lookup needs only the bare id (`.peaks/_runtime/change/<id>/`).
+    // When the scope starts with `_runtime/`, strip that prefix so the
+    // path resolver builds the right canonical location.
+    let sessionId = artifact.sessionId;
+    if (sessionId.startsWith('_runtime/') || sessionId.startsWith('_runtime\\')) {
+        sessionId = sessionId.replace(/^_runtime[\\/]/, '');
+    }
+    return { path: artifact.path, content: artifact.content, sessionId };
+}
+function rdGatesForType(requestType) {
+    const gates = [
+        { name: 'rd-request-exists', description: 'RD request artifact created', passed: false, detail: '' }
+    ];
+    if (requestType === 'feature' || requestType === 'refactor') {
+        gates.push({ name: 'tech-doc', description: 'Technical design doc', passed: false, detail: '' });
+    }
+    if (requestType === 'bugfix') {
+        gates.push({ name: 'bug-analysis', description: 'Bug root-cause analysis', passed: false, detail: '' });
+    }
+    if (requestType !== 'docs' && requestType !== 'chore' && requestType !== 'config') {
+        gates.push({ name: 'code-review', description: 'Code review evidence', passed: false, detail: '' });
+    }
+    if (requestType === 'feature' || requestType === 'refactor' || requestType === 'bugfix' || requestType === 'config') {
+        gates.push({ name: 'security-review', description: 'Security review evidence', passed: false, detail: '' });
+    }
+    return gates;
+}
+function qaGatesForType(requestType) {
+    const gates = [
+        { name: 'qa-request-exists', description: 'QA request artifact created', passed: false, detail: '' }
+    ];
+    if (requestType === 'feature' || requestType === 'refactor' || requestType === 'bugfix') {
+        gates.push({ name: 'test-cases', description: 'QA test cases', passed: false, detail: '' });
+        gates.push({ name: 'test-report', description: 'QA test report with execution results', passed: false, detail: '' });
+    }
+    if (requestType === 'feature' || requestType === 'refactor' || requestType === 'bugfix' || requestType === 'config') {
+        gates.push({ name: 'security-findings', description: 'QA security findings', passed: false, detail: '' });
+    }
+    if (requestType === 'feature' || requestType === 'refactor') {
+        gates.push({ name: 'performance-findings', description: 'QA performance findings', passed: false, detail: '' });
+    }
+    return gates;
+}
+const RD_QA_HANDOFF_STATES = new Set(['qa-handoff', 'handed-off', 'implemented']);
+const QA_COMPLETE_STATES = new Set(['verdict-issued']);
+export async function verifyPipeline(options) {
+    const requestType = isRequestType(options.requestType ?? '') ? options.requestType : 'feature';
+    const violations = [];
+    const nextActions = [];
+    const rdGates = rdGatesForType(requestType);
+    const qaGates = qaGatesForType(requestType);
+    // Slice 2026-06-13-peaks-workflow-skip: read the skip-state (if any)
+    // and pre-mark matching gates as `status: 'skipped'`. We do this
+    // BEFORE evaluating evidence files, so a skipped gate never
+    // emits a "missing evidence" violation. The boolean `passed` is
+    // set to `true` so legacy consumers (which only check `passed`)
+    // treat skipped gates as satisfied; the new `status` field
+    // distinguishes the bypass from an actual pass.
+    const skippedGateNames = new Set();
+    if (options.sessionId !== undefined) {
+        const skipState = readSkipState(options.projectRoot, options.sessionId, options.rid);
+        if (skipState !== null) {
+            for (const gateName of skipState.skippedGates) {
+                if (gateName === 'QA' || gateName === 'qa-phase' || gateName === 'qa') {
+                    for (const g of qaGates)
+                        skippedGateNames.add(g.name);
+                }
+                else if (gateName === 'RD' || gateName === 'rd-phase' || gateName === 'rd') {
+                    for (const g of rdGates)
+                        skippedGateNames.add(g.name);
+                }
+                else {
+                    skippedGateNames.add(gateName);
+                }
+            }
+            nextActions.push(`Skipped gates (via peaks workflow skip): [${skipState.skippedGates.join(', ')}] — reason: ${skipState.skipReason}`);
+        }
+    }
+    function markIfSkipped(gate) {
+        if (skippedGateNames.has(gate.name)) {
+            gate.status = 'skipped';
+            gate.passed = true;
+            gate.detail = 'skipped via peaks workflow skip';
+        }
+    }
+    // Resolve RD + QA on-disk locations via showRequestArtifact (the change-id
+    // is whatever dir the file actually lives in, not the caller's session-id).
+    const rdFile = await findRequestFile(options.projectRoot, 'rd', options.rid);
+    let rdInvoked = false;
+    let rdState = 'missing';
+    // The resolved change-id is the on-disk location the file actually
+    // lives in. The caller's `options.sessionId` is a hint used for
+    // path construction (nextActions strings), NOT for the resolved
+    // sessionId field — the on-disk location is the source of truth.
+    let resolvedChangeId = '';
+    if (rdFile) {
+        rdInvoked = true;
+        rdState = extractState(rdFile.content);
+        rdGates[0].passed = true;
+        rdGates[0].detail = `found at ${rdFile.path}`;
+        resolvedChangeId = rdFile.sessionId;
+    }
+    else {
+        violations.push('RD phase skipped: peaks-rd was never invoked for this request (no RD request artifact found)');
+        nextActions.push('Invoke Skill(skill="peaks-rd") with the request-id, then run unit tests + code review + security review');
+        rdGates[0].detail = 'not found';
+    }
+    // Check RD evidence files (under the change-id dir the RD request lives in)
+    const RD_EVIDENCE_FILE = {
+        'tech-doc': 'tech-doc.md',
+        'bug-analysis': 'bug-analysis.md',
+        'code-review': 'code-review.md',
+        'security-review': 'security-review.md'
+    };
+    // Slice v2.17.0 hard-kill — change-id axis removed as filesystem
+    // scope. The canonical evidence location is now the session axis
+    // `.peaks/_runtime/<sessionId>/<role>/...` (where `<sessionId>` is
+    // the on-disk dir the request artifact lives in; for back-compat
+    // with the legacy `_runtime/<sessionId>/` and `.peaks/<sessionId>/`
+    // layouts we also probe those). When the legacy fallback fires, the
+    // gate detail / nextActions surface the `DEPRECATION_LEGACY_PATH_USED`
+    // warning so QA / TXT can nudge users to migrate via
+    // `peaks workspace migrate-change-scope --apply`.
+    // v2.18.1 bug #5 fix: same session-axis fallback as the QA resolver
+    // below. When `resolvedChangeId` is empty (no RD/QA artifact on disk
+    // yet), the canonical session id from the binding-store is the
+    // preferred filesystem scope; falling through to `options.rid` would
+    // make every missing-evidence path look like a per-rid scope dir.
+    const rdEvidenceDir = resolvedChangeId || options.sessionId || getSessionIdCanonical(options.projectRoot) || options.rid;
+    // Slice 2026-06-28-code-mode-bypass-fix (defect #3): track whether
+    // every resolved evidence file landed on the canonical path. Drives
+    // the `usedCanonicalPath` envelope field. The flag stays `true` if
+    // no evidence file was resolved at all (nothing to be non-canonical
+    // about); it flips to `false` if any file resolves via legacy.
+    let anyEvidenceResolved = false;
+    let allResolvedPathsCanonical = true;
+    for (const gate of rdGates.slice(1)) {
+        const fileName = RD_EVIDENCE_FILE[gate.name];
+        // v2.17.0 canonical: session axis — `<sessionId>` is the on-disk
+        // dir the request artifact was found in (matches the layout used
+        // by `request-artifact-service.ts` for new artifacts).
+        const canonicalPath = join(options.projectRoot, '.peaks', '_runtime', rdEvidenceDir, 'rd', fileName);
+        const legacyMisplacedPath = join(options.projectRoot, '.peaks', rdEvidenceDir, 'rd', fileName);
+        // Pre-v2.17.0 change-axis form: `.peaks/_runtime/change/<id>/rd/<file>`
+        // — the v2.16.0 / v2.17.0-era canonical that v2.17.0 hard-killed.
+        // Kept as a back-compat fallback for un-migrated workspaces.
+        const legacyChangeAxisPath = join(options.projectRoot, '.peaks', '_runtime', 'change', rdEvidenceDir, 'rd', fileName);
+        let resolvedPath = null;
+        let usedLegacy = false;
+        for (const candidate of [canonicalPath, legacyMisplacedPath, legacyChangeAxisPath]) {
+            if (existsSync(candidate)) {
+                resolvedPath = candidate;
+                usedLegacy = candidate !== canonicalPath;
+                break;
+            }
+        }
+        if (resolvedPath !== null) {
+            anyEvidenceResolved = true;
+            if (usedLegacy)
+                allResolvedPathsCanonical = false;
+            gate.passed = true;
+            gate.detail = resolvedPath + (usedLegacy ? ' [DEPRECATION_LEGACY_PATH_USED]' : '');
+            if (usedLegacy) {
+                violations.push(`DEPRECATION_LEGACY_PATH_USED: ${resolvedPath} — move the file into .peaks/_runtime/${rdEvidenceDir}/rd/ (the canonical location) so subsequent runs resolve on the canonical path. The legacy \`peaks workspace migrate-change-scope\` helper was removed in v2.19.0; use \`peaks workspace migrate\` to relocate misplaced content.`);
+            }
+        }
+        else {
+            gate.detail = `missing: ${canonicalPath}`;
+            violations.push(`RD evidence missing: ${gate.description} (${fileName})`);
+            nextActions.push(`Create .peaks/_runtime/${rdEvidenceDir}/rd/${fileName}`);
+        }
+    }
+    // Check if RD reached qa-handoff
+    if (rdInvoked && !RD_QA_HANDOFF_STATES.has(rdState)) {
+        violations.push(`RD not ready for QA: state is "${rdState}" — must reach "qa-handoff" (unit tests, karpathy-guidelines §1 Think / §2 Simplicity / §3 Surgical / §4 Goal-Driven, code review, security review complete)`);
+        nextActions.push(`Complete RD gates → peaks request transition ${options.rid} --role rd --state qa-handoff`);
+    }
+    // Check QA phase
+    const qaFile = await findRequestFile(options.projectRoot, 'qa', options.rid);
+    let qaInvoked = false;
+    let qaState = 'missing';
+    if (qaFile) {
+        qaInvoked = true;
+        qaState = extractState(qaFile.content);
+        qaGates[0].passed = true;
+        qaGates[0].detail = `found at ${qaFile.path}`;
+        resolvedChangeId = qaFile.sessionId || resolvedChangeId;
+    }
+    else {
+        violations.push('QA phase skipped: peaks-qa was never invoked for this request (no QA request artifact found)');
+        nextActions.push('Invoke Skill(skill="peaks-qa") with the request-id for functional/performance/security testing');
+        qaGates[0].detail = 'not found';
+    }
+    // Check QA evidence files. For the security/performance findings
+    // gates, the canonical form post-slice-025 is the per-rid suffixed
+    // path; the legacy non-suffixed form is still accepted during the
+    // 1-minor-release back-compat window. The path resolver
+    // (artifact-paths.ts) decides which form to consume; we pass the
+    // resolved change-id and the rid.
+    // v2.18.1 bug #5 fix: when no RD/QA artifact is on disk yet (resolvedChangeId
+    // is empty), fall back to the current session id from the binding-store
+    // instead of `rdEvidenceDir` (= the rid). The session axis
+    // `.peaks/_runtime/<sessionId>/qa/...` is the canonical v2.17.0 home; the
+    // legacy `_runtime/change/<sessionId>/qa/...` probe should only fire for
+    // pre-v2.17.0 workspaces, not as a default for new requests. The slug in
+    // the `sessionId` envelope field is preserved below for traceability.
+    const changeIdForResolver = resolvedChangeId || getSessionIdCanonical(options.projectRoot) || rdEvidenceDir;
+    const QA_EVIDENCE_FILE = {
+        'test-cases': `test-cases/${options.rid}.md`,
+        'test-report': `test-reports/${options.rid}.md`,
+        'security-findings': '',
+        'performance-findings': ''
+    };
+    for (const gate of qaGates.slice(1)) {
+        if (gate.name === 'security-findings' || gate.name === 'performance-findings') {
+            const resolver = gate.name === 'security-findings' ? resolveSecurityFindingsPath : resolvePerformanceFindingsPath;
+            const resolved = resolver({ projectRoot: options.projectRoot, sessionId: changeIdForResolver, rid: options.rid });
+            if (existsSync(resolved.path)) {
+                anyEvidenceResolved = true;
+                if (resolved.form === 'legacy')
+                    allResolvedPathsCanonical = false;
+                gate.passed = true;
+                gate.detail = resolved.path;
+                if (resolved.form === 'legacy') {
+                    // 1-minor-release back-compat window. Surface the warning so
+                    // users know to migrate. Per PRD §Migration the form will be
+                    // rejected after the next minor bump.
+                    violations.push(`QA evidence accepted in legacy form (will be rejected after next minor release): ${resolved.path} — re-run peaks workflow plan refresh to migrate`);
+                }
+            }
+            else {
+                gate.detail = `missing: ${resolved.path}`;
+                violations.push(`QA evidence missing: ${gate.description} (${resolved.path})`);
+                nextActions.push(`Create ${resolved.path} (or use the legacy non-suffixed form during the 1-minor-release back-compat window)`);
+            }
+            continue;
+        }
+        const fileName = QA_EVIDENCE_FILE[gate.name];
+        // v2.17.0 canonical: session axis — `<sessionId>/qa/<file>`.
+        const canonicalQaPath = join(options.projectRoot, '.peaks', '_runtime', rdEvidenceDir, 'qa', fileName);
+        const legacyMisplacedQaPath = join(options.projectRoot, '.peaks', rdEvidenceDir, 'qa', fileName);
+        // Pre-v2.17.0 change-axis form: kept as back-compat fallback.
+        const legacyChangeAxisQaPath = join(options.projectRoot, '.peaks', '_runtime', 'change', rdEvidenceDir, 'qa', fileName);
+        let resolvedQaPath = null;
+        let usedLegacyQa = false;
+        for (const candidate of [canonicalQaPath, legacyMisplacedQaPath, legacyChangeAxisQaPath]) {
+            if (existsSync(candidate)) {
+                resolvedQaPath = candidate;
+                usedLegacyQa = candidate !== canonicalQaPath;
+                break;
+            }
+        }
+        if (resolvedQaPath !== null) {
+            anyEvidenceResolved = true;
+            if (usedLegacyQa)
+                allResolvedPathsCanonical = false;
+            gate.passed = true;
+            gate.detail = resolvedQaPath + (usedLegacyQa ? ' [DEPRECATION_LEGACY_PATH_USED]' : '');
+            if (usedLegacyQa) {
+                violations.push(`DEPRECATION_LEGACY_PATH_USED: ${resolvedQaPath} — move the file into .peaks/_runtime/${rdEvidenceDir}/qa/ (the canonical location) so subsequent runs resolve on the canonical path. The legacy \`peaks workspace migrate-change-scope\` helper was removed in v2.19.0; use \`peaks workspace migrate\` to relocate misplaced content.`);
+            }
+        }
+        else {
+            gate.detail = `missing: ${canonicalQaPath}`;
+            violations.push(`QA evidence missing: ${gate.description} (${fileName})`);
+            nextActions.push(`Create .peaks/_runtime/${rdEvidenceDir}/qa/${fileName}`);
+        }
+    }
+    // Check if QA reached verdict-issued
+    if (qaInvoked && !QA_COMPLETE_STATES.has(qaState)) {
+        violations.push(`QA not complete: state is "${qaState}" — must reach "verdict-issued" (functional + performance + security checks done)`);
+        nextActions.push(`Complete QA gates → peaks request transition ${options.rid} --role qa --state verdict-issued`);
+    }
+    // RD invoked without QA — check is moved to AFTER markIfSkipped
+    // (slice 2026-06-13-peaks-workflow-skip) because the gate.status
+    // values are only final after the post-process pass. We track the
+    // decision with a placeholder here and resolve it below.
+    const rdInvokedWithoutQaRaw = rdInvoked && !qaInvoked;
+    // Slice 2026-06-13-peaks-workflow-skip: post-process. For any gate
+    // the user marked as skipped, override the evaluation result. The
+    // boolean `passed` is set to true so the gate counts as satisfied;
+    // the new `status: 'skipped'` field signals the bypass to
+    // downstream consumers. Violations and nextActions pushed for
+    // skipped gates are filtered out (the user explicitly chose to
+    // skip — the missing-evidence message is no longer actionable).
+    for (const gate of [...rdGates, ...qaGates]) {
+        if (skippedGateNames.has(gate.name)) {
+            markIfSkipped(gate);
+        }
+    }
+    if (skippedGateNames.size > 0) {
+        const skippedViolations = new Set();
+        for (const gate of [...rdGates, ...qaGates]) {
+            if (gate.status === 'skipped') {
+                skippedViolations.add(`RD evidence missing: ${gate.description}`);
+                skippedViolations.add(`QA evidence missing: ${gate.description}`);
+            }
+        }
+        for (let i = violations.length - 1; i >= 0; i -= 1) {
+            const v = violations[i];
+            for (const sv of skippedViolations) {
+                if (v.startsWith(sv)) {
+                    violations.splice(i, 1);
+                    break;
+                }
+            }
+        }
+    }
+    // Resolve the "RD invoked without QA" check now that markIfSkipped
+    // has run. The check is suppressed when every QA gate is skipped
+    // (slice 2026-06-13-peaks-workflow-skip: the user explicitly chose
+    // to skip the QA phase).
+    if (rdInvokedWithoutQaRaw) {
+        const allQaSkipped = qaGates.every((g) => g.status === 'skipped');
+        if (!allQaSkipped) {
+            violations.push('CRITICAL: peaks-rd was invoked but peaks-qa was NOT — QA functional/performance/security testing is mandatory after all RD work');
+            nextActions.push('MUST invoke Skill(skill="peaks-qa") before declaring workflow complete');
+        }
+    }
+    // Slice 002 (v2.15.0) AC-3 — Gate H "feedback-promotion". Scans
+    // `.peaks/memory/*.md` for `metadata.type === 'feedback'` entries
+    // without a promotion marker (HTML comment or `.promotion.json`
+    // sidecar). When any unpromoted feedback is found, the gate fails
+    // and the pipeline does not complete until the user promotes via
+    // `peaks feedback promote <memory-file> --layer <A|B|C>`.
+    //
+    // The scan is intentionally non-throwing — a missing or unreadable
+    // memory dir is treated as "no feedback found, gate passes" so
+    // empty projects / pre-feedback-epoch projects don't false-positive.
+    const feedbackGates = [
+        {
+            name: 'feedback-promotion',
+            description: 'Every feedback memory is promoted to at least one enforcement layer (sop / hooks / hard-floor)',
+            passed: false,
+            detail: ''
+        }
+    ];
+    let unpromotedFeedbackCount = 0;
+    try {
+        const unpromoted = listUnpromotedFeedback({ projectRoot: options.projectRoot });
+        unpromotedFeedbackCount = unpromoted.length;
+        if (unpromoted.length === 0) {
+            feedbackGates[0].passed = true;
+            feedbackGates[0].detail = `0 unpromoted feedback memories in .peaks/memory/`;
+        }
+        else {
+            feedbackGates[0].detail = `${unpromoted.length} unpromoted feedback memor${unpromoted.length === 1 ? 'y' : 'ies'}: ${unpromoted.map((u) => u.name).join(', ')}`;
+            violations.push(`Gate H feedback-promotion FAILED: ${unpromoted.length} feedback memor${unpromoted.length === 1 ? 'y is' : 'ies are'} not yet promoted to an enforcement layer (${unpromoted.map((u) => u.name).join(', ')}). Run \`peaks feedback promote <memory-file> --layer <A|B|C>\` for each. See sops/feedback-promotion-sop.md.`);
+            nextActions.push(`Run \`peaks feedback promote <memory-file> --layer <A|B|C>\` for each unpromoted feedback memory to satisfy Gate H.`);
+        }
+    }
+    catch {
+        // listUnpromotedFeedback swallows IO errors internally; the
+        // outer catch is a belt-and-braces guard for unexpected
+        // failures (e.g. permission denied). Treat as "no feedback" —
+        // fail-open on gate infrastructure rather than blocking ship.
+        feedbackGates[0].passed = true;
+        feedbackGates[0].detail = 'feedback-promotion scan skipped (memory dir unreadable; treating as no feedback)';
+    }
+    const allFeedbackGatesPassed = feedbackGates.every((g) => g.passed);
+    const allRdGatesPassed = rdGates.every((g) => g.passed);
+    const allQaGatesPassed = qaGates.every((g) => g.passed);
+    const complete = rdInvoked && qaInvoked && allRdGatesPassed && allQaGatesPassed && allFeedbackGatesPassed
+        && RD_QA_HANDOFF_STATES.has(rdState) && QA_COMPLETE_STATES.has(qaState);
+    // Slice 025 — derive the `acceptedForm` and `gateC` verdict. The form is
+    // 'suffixed' if both the security + perf gates passed via the new
+    // per-rid path; 'legacy' if either was consumed via the legacy fallback;
+    // 'none' if neither passed.
+    const secGate = qaGates.find((g) => g.name === 'security-findings');
+    const perfGate = qaGates.find((g) => g.name === 'performance-findings');
+    const secForm = secGate?.detail?.includes(`-${options.rid}.md`) ? 'suffixed' : 'legacy';
+    const perfForm = perfGate?.detail?.includes(`-${options.rid}.md`) ? 'suffixed' : 'legacy';
+    const acceptedForm = !secGate?.passed && !perfGate?.passed
+        ? 'none'
+        : (secForm === 'suffixed' && perfForm === 'suffixed')
+            ? 'suffixed'
+            : (secForm === 'legacy' || perfForm === 'legacy')
+                ? 'legacy'
+                : 'suffixed';
+    const gateC = allQaGatesPassed ? 'pass' : 'fail';
+    const gateH = allFeedbackGatesPassed ? 'pass' : 'fail';
+    // Slice 2026-06-28-code-mode-bypass-fix (defect #3): `true` when
+    // every gate resolved on the canonical path; `false` when at least
+    // one fell back to a legacy form. QA / TXT surface the value so the
+    // user knows the legacy content must be moved into the canonical
+    // location (the legacy `peaks workspace migrate-change-scope` helper
+    // was removed in v2.19.0; use `peaks workspace migrate` to relocate
+    // misplaced content).
+    //
+    // Implementation note: use the in-loop flag `allResolvedPathsCanonical`
+    // (correctly updated by both the inline evidence loop AND the
+    // artifact-paths resolver for security/performance findings), not a
+    // string-scan over `gate.detail`. The string-scan approach misses the
+    // artifact-paths legacy branch (it does NOT inject the
+    // `DEPRECATION_LEGACY_PATH_USED` suffix into gate.detail).
+    //
+    // If NO evidence file resolved (e.g. all gates missing), the field is
+    // `true` — there is nothing non-canonical to worry about. If every
+    // resolved gate was skipped via `peaks workflow skip`, the field is
+    // `true` — the user opted out of the canonical/legacy decision.
+    const allGatesSkipped = [...rdGates, ...qaGates].every((g) => g.status === 'skipped');
+    const usedCanonicalPath = !anyEvidenceResolved || allGatesSkipped || allResolvedPathsCanonical;
+    return {
+        rid: options.rid,
+        sessionId: resolvedChangeId,
+        requestType,
+        complete,
+        rdPhase: { invoked: rdInvoked, state: rdState, gates: rdGates },
+        qaPhase: { invoked: qaInvoked, state: qaState, gates: qaGates },
+        feedbackPhase: { gates: feedbackGates },
+        violations,
+        nextActions,
+        acceptedForm,
+        gateC,
+        gateH,
+        usedCanonicalPath
+    };
+}

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

@@ -0,0 +1,29 @@
+import { type ResultEnvelope } from '../../shared/result.js';
+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 '../../shared/result.js';
+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'
+    });
+}