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

package/dist/services/artifacts/artifact-prerequisites.js

@@ -0,0 +1,491 @@
+import { join, dirname, basename } from 'node:path';
+import { readFile, readdir } from 'node:fs/promises';
+import { pathExists } from '../../shared/fs.js';
+import { emitObservabilityEvent } from '../observability/observability-service.js';
+export const VALID_REQUEST_TYPES = [
+    'feature',
+    'bugfix',
+    'refactor',
+    'docs',
+    'config',
+    'chore'
+];
+export const DEFAULT_REQUEST_TYPE = 'feature';
+export function isRequestType(value) {
+    return VALID_REQUEST_TYPES.includes(value);
+}
+// Shared prerequisite fragments
+// (Removed in v2.11.0 Group A: TECH_DOC prerequisite. The per-session
+// rd/tech-doc.md is replaced by the immutable peaks-prd handoff at
+// prd/handoff.md. Group B will introduce a PRD_HANDOFF prerequisite
+// once the handoff service lands. For Group A scope, `rd:implemented`
+// and `rd:qa-handoff` rely on the evidence files (code-review,
+// security-review, perf-baseline, karpathy-review, unit tests) only.)
+const BUG_ANALYSIS = {
+    relativePath: 'rd/bug-analysis.md',
+    description: 'Bug root-cause analysis (reproduction, affected paths, fix approach, regression test plan)',
+    mustContain: ['## Root cause', '## Fix approach']
+};
+const CODE_REVIEW = {
+    relativePath: 'rd/code-review.md',
+    description: 'Code review evidence (CRITICAL/HIGH must be fixed before handoff)',
+    mustContain: ['## Findings', 'CRITICAL']
+};
+const SECURITY_REVIEW = { relativePath: 'rd/security-review.md', description: 'Security review evidence for the changed surface' };
+// Gate B9 — RD-side perf baseline (peaks-rd SKILL "Parallel review fan-out").
+// The file must exist; the body must either carry a Results table marker
+// (per peaks-rd SKILL "Mandatory perf-baseline output") or the explicit
+// "N/A — no perf surface" escape hatch. A slice without a perf surface
+// still has to write the stub; an RD that omits perf-baseline entirely is
+// blocked here, matching peaks-rd's BLOCKING Gate B9 claim.
+const PERF_BASELINE = {
+    relativePath: 'rd/perf-baseline.md',
+    description: 'RD-side perf baseline (peaks-rd Gate B9) — must include a Results table with measurements OR the literal "N/A — no perf surface" escape hatch in the Notes section. QA Gate A4 diffs against this file.',
+    // Either a real Results table is present, OR the explicit no-perf-surface
+    // stub marker. Both paths satisfy Gate B9; absence of both is BLOCKED.
+    mustContainAny: ['## Results', 'N/A — no perf surface']
+};
+// v2.12.0 Group B Tier 5 — audit outputs from the new independent
+// skills (`peaks-security-audit` / `peaks-perf-audit`). These replace
+// the v2.11.x rd/{security-review,perf-baseline}.md slots for the
+// fanout-trigger types (feat / bugfix / refactor). The audit skills
+// are dispatched as pre-RD audit runs that consume the public PRD
+// handoff (`prd/handoff.md`) — see `AUDIT_REQUIRES_HANDOFF` below.
+//
+// Back-compat: the canonical location is `audit/security.md` (and
+// `audit/perf.md`); the legacy `rd/security-review.md` (and
+// `rd/perf-baseline.md`) path is also accepted via `legacyRelativePath`
+// for the 1-minor-release window. v2.13.0 hard-deletes the legacy paths.
+const AUDIT_SECURITY = {
+    relativePath: 'audit/security.md',
+    legacyRelativePath: 'rd/security-review.md',
+    description: 'Independent security audit output (peaks-security-audit skill, v2.12.0+). Replaces the v2.11.x rd/security-review.md slot for fanout-trigger request types. The legacy path is accepted during the 1-minor-release back-compat window via legacyRelativePath.',
+    // New canonical path writes a "## Verdict" header on the audit
+    // envelope. The legacy rd/security-review.md writes a "## Findings"
+    // header. Both pass the gate.
+    mustContainAny: ['## Verdict', '## Findings']
+};
+const AUDIT_PERF = {
+    relativePath: 'audit/perf.md',
+    legacyRelativePath: 'rd/perf-baseline.md',
+    description: 'Independent perf audit output (peaks-perf-audit skill, v2.12.0+). Replaces the v2.11.x rd/perf-baseline.md slot for fanout-trigger request types. The legacy path is accepted during the 1-minor-release back-compat window via legacyRelativePath.',
+    // New schema writes "## Baseline" header; the legacy schema writes
+    // "## Results". Both pass the gate, as does the explicit
+    // no-perf-surface stub (slices whose surface is purely logic /
+    // config / docs).
+    mustContainAny: ['## Baseline', '## Results', 'N/A — no perf surface']
+};
+// v2.13.1 Group A — MUT prereq (Plan 2 ships `mut-report.json` to
+// `.peaks/_runtime/<sid>/mut/mut-report.json`; v2.13.1 wires it into
+// the rd:qa-handoff gate for fanout-trigger types). The body must carry
+// the `"passed": true` marker so the gate rejects failed mutation
+// runs. We pin on the substring `"passed":` so that both JSON and
+// pretty-printed JSON (with whitespace variations) are caught — the
+// downstream stricter check happens in `verdict-aggregator.ts`. The
+// PRD's preserved-behavior clause says `loadMutReport() === null`
+// stays `skipped` on the qa side, which means this prereq is the
+// rd-side CLI hard gate (blocks `rd → qa-handoff`), while qa-side
+// consumption remains soft.
+//
+// v2.13.2 AC-5 — 1-minor-release back-compat window. When
+// `backCompat: true` is set, a MISSING file downgrades to a warning
+// (`mut-report-missing-deprecated-in-v2.14.0`) instead of a hard
+// failure. The hard-fail behavior for `passed: false` is preserved
+// (the body still has to carry `"passed": true` when present).
+// v2.14.0 will remove `backCompat` and re-elevate missing → throw.
+const MUT_REPORT = {
+    relativePath: 'mut/mut-report.json',
+    description: 'peaks-mut mutation + weak-assertion report (Plan 2, v2.12.0+). v2.13.1: required at rd:qa-handoff for feature / bugfix / refactor slices. v2.13.2: back-compat window — missing file downgrades to a warning (1-minor-release); passed:false still throws. The body must carry `"passed": true` when present; failed runs are blocked at this gate. CONFIG / DOCS / CHORE slices retain the legacy "no acceptance surface" exemption.',
+    // Substring check on the JSON property name only — strictness (kill
+    // rate ≥ 0.8 etc.) is enforced downstream by verdict-aggregator +
+    // peaks-mut's evaluateThresholds. We require both the property name
+    // and a literal `true` value to keep the gate as tight as possible
+    // without depending on JSON parsing in the prereq resolver.
+    mustContainAny: ['"passed": true', '"passed":true'],
+    backCompat: true
+};
+// v2.12.0 Group B Tier 5 — gate that the peaks-prd handoff (the
+// immutable handoff capsule at `prd/handoff.md`) exists before any
+// audit skill is allowed to consume it. The peaks-security-audit
+// and peaks-perf-audit CLI commands read frontmatter from
+// `prd/handoff.md` (AC-2.4 / AC-3.4); if the handoff is missing the
+// audit skill aborts — and so should the prereq gate when those
+// audits are required at rd:qa-handoff.
+//
+// This gate is co-listed with AUDIT_SECURITY / AUDIT_PERF at
+// `rd:qa-handoff` for FEATURE / BUGFIX / REFACTOR. CONFIG retains
+// the old form (no PRD handoff chain — config slices may run before
+// PRD handoff exists for small CONFIG-only commits).
+const AUDIT_REQUIRES_HANDOFF = {
+    relativePath: 'prd/handoff.md',
+    description: 'PRD handoff capsule (v2.12.0+) — peaks-security-audit / peaks-perf-audit both read frontmatter from this file. Must exist before audit prereqs are evaluated at rd:qa-handoff.',
+    // Empty `mustContain` is fine — file existence is the contract.
+    // The peaks-prd handoff service writes frontmatter with
+    // `schemaVersion: 2` and a sha256 fingerprint; we pin a
+    // substring check on `schemaVersion: 2` to fail loudly if a
+    // legacy handoff (schemaVersion: 1) slips in. This protects
+    // the audit skills from reading an envelope they cannot parse.
+    mustContain: ['schemaVersion: 2', 'sha256:']
+};
+// Karpathy-Gate (Slice 5/6 — karpathy-enforcement 5-way fanout).
+// Hard gate: rd/karpathy-review.md MUST exist with the 4 guideline section
+// markers (think-before-coding / simplicity-first / surgical-changes /
+// goal-driven-execution) as actual headings before rd:qa-handoff transitions
+// to qa. Slice 2.6.1.F hardening: the 4 guideline markers are now enforced
+// as `headingMustContain` (line-anchored `#`–`###` prefix), not as substring
+// matches. This prevents a malicious or careless file from passing the gate
+// by simply mentioning the guideline names as prose. The `## Karpathy-Gate`
+// header remains a substring match (it is the file's own gate header, not
+// a structural section anchor).
+const KARPATHY_REVIEW = {
+    relativePath: 'rd/karpathy-review.md',
+    description: 'RD-side karpathy review (peaks-rd 5-way fanout) — must contain a "## Karpathy-Gate" header AND the 4 guideline section markers (Think Before Coding / Simplicity First / Surgical Changes / Goal-Driven Execution) as actual markdown headings. Per karpathy §1 / §3.',
+    mustContain: ['## Karpathy-Gate'],
+    headingMustContain: [
+        'Think Before Coding',
+        'Simplicity First',
+        'Surgical Changes',
+        'Goal-Driven Execution'
+    ]
+};
+// v2.14.0 G4 — third-party reviewer (peaks-reviewer skill). Parallel
+// to KARPATHY_REVIEW. The body MUST carry the literal substring
+// `third-party-review` so a stub file with an empty envelope cannot
+// pass the gate. The full envelope lives at the JSON sibling path
+// (`rd/third-party-review.json`); this MD file is the human-readable
+// companion. The body is also expected to declare a `modelFamily`
+// distinct from the karpathy-reviewer's modelFamily (AC-4.4 — the CI
+// gate diffs `rd/third-party-review.json.modelFamily` against
+// `rd/karpathy-review.md` parsed `modelFamily`); equality fails the
+// build. When `~/.peaks/config.json` lacks a `reviewer.providers`
+// section, the prereq is auto-marked `skipped: no-reviewer-config`
+// and the transition still passes (A4.3 fallbackOnError=skip).
+const THIRD_PARTY_REVIEW = {
+    relativePath: 'rd/third-party-review.md',
+    description: 'v2.14.0 G4 third-party reviewer (peaks-reviewer skill) — must declare a `modelFamily` distinct from the karpathy-reviewer modelFamily (AC-4.4). Skipped when `~/.peaks/config.json` lacks `reviewer.providers` (>=2 entries); the prereq then resolves to a soft warning (`no-reviewer-config`) rather than a hard failure. The JSON sibling at `rd/third-party-review.json` carries the schema-validated ReviewerEnvelope (no free-form LLM JSON). v2.14.0 ships as a soft-warning prereq (1-minor-release back-compat window); v2.15.0 will hard-fail when the file is absent AND `reviewer.providers` is configured.',
+    mustContain: ['third-party-review', 'modelFamily'],
+    backCompat: true
+};
+const TEST_CASES = {
+    relativePath: 'qa/test-cases/<rid>.md',
+    description: 'Generated test cases (unit / integration / UI regression)',
+    mustContain: ['## Test cases']
+};
+const TEST_REPORT = {
+    relativePath: 'qa/test-reports/<rid>.md',
+    description: 'Test execution report with actual pass/fail/coverage results',
+    mustContain: ['## Test execution']
+};
+const SECURITY_FINDINGS = {
+    relativePath: 'qa/security-findings.md',
+    description: 'Security test findings (record "no findings" inside if truly clean)',
+    mustContain: ['## Findings']
+};
+const PERFORMANCE_FINDINGS = {
+    relativePath: 'qa/performance-findings.md',
+    description: 'Performance test findings (record baseline/after numbers or explicit "not applicable" rationale)',
+    mustContain: ['## Baseline']
+};
+// PRD content prereq: ensures the PRD artifact has actual scope/acceptance content
+// before handoff to RD/UI/QA. The SKILL says "Handoff to RD/UI/QA is blocked while
+// the artifact is missing or in `draft` state" — this gives that claim a CLI gate.
+const PRD_CONTENT = {
+    relativePath: 'prd/requests/<rid>.md',
+    description: 'PRD artifact must contain Goal and Acceptance criteria sections before handoff',
+    mustContain: ['## Goals', '## Acceptance']
+};
+const UNIT_TESTS = {
+    relativePath: 'qa/test-cases/<rid>.md',
+    description: 'Unit test files for the implemented changes (enforces peaks-rd Gate B2)',
+    mustContain: ['## Test cases', 'test(']
+};
+const QA_INITIATED = {
+    relativePath: 'qa/.initiated',
+    description: 'QA skill must be invoked before RD handoff (run peaks request init --role qa)'
+};
+// v2.11.0 D1/D4 trim (Group C Tier 6): peaks-qa no longer requires
+// qa/security-findings.md or qa/performance-findings.md at qa:verdict-issued.
+// Those are owned by peaks-rd's audit fan-out (rd/security-review.md and
+// rd/perf-baseline.md). QA references them by path from the test-report body
+// (see qa-transition-gates.md Gates A3/A4). SECURITY_FINDINGS /
+// PERFORMANCE_FINDINGS constants are kept for back-compat and a 1-minor-
+// release deprecation window but are NOT in any qa:verdict-issued table.
+//
+// v2.12.0 Group B Tier 5: at rd:qa-handoff, the v2.11.x security-review +
+// perf-baseline slots are replaced by `AUDIT_SECURITY` + `AUDIT_PERF` (the
+// new audit-skill outputs). The legacy `AUDIT_SECURITY_LEGACY` /
+// `AUDIT_PERF_LEGACY` shims are kept in the same list so the 1-minor-
+// release back-compat window still accepts the v2.11.x on-disk layout;
+// both the new path (`audit/security.md`) and the legacy path
+// (`rd/security-review.md`) satisfy the gate. The audit skills require
+// `prd/handoff.md` (`AUDIT_REQUIRES_HANDOFF`).
+//
+// v2.13.1 Group A: add `MUT_REPORT` (peaks-mut Plan 2 output). The
+// gate is the rd-side CLI hard block; CONFIG / DOCS / CHORE retain the
+// legacy "no acceptance surface" exemption via MINIMAL_TABLE /
+// CONFIG_TABLE.
+const FEATURE_TABLE = {
+    'prd:handed-off': [PRD_CONTENT],
+    'rd:implemented': [],
+    'rd:qa-handoff': [
+        CODE_REVIEW,
+        AUDIT_REQUIRES_HANDOFF,
+        AUDIT_SECURITY,
+        AUDIT_PERF,
+        KARPATHY_REVIEW,
+        THIRD_PARTY_REVIEW,
+        MUT_REPORT,
+        UNIT_TESTS,
+        QA_INITIATED
+    ],
+    'qa:running': [TEST_CASES],
+    'qa:verdict-issued': [TEST_CASES, TEST_REPORT]
+};
+// Bugfix: lighter planning artifact (bug-analysis instead of tech-doc), still requires code review + security review + regression test.
+// Performance baseline: required for perf-shaped bugfixes (where the bug IS a
+// perf regression). For non-perf bugfixes, RD writes the perf-baseline stub
+// with "N/A — no perf surface" — Gate B9 still passes (mustContainAny hit),
+// and the stub tells QA Gate A4 to skip the perf diff.
+// v2.11.0 D1/D4: SECURITY_FINDINGS dropped from qa:verdict-issued (peaks-rd owns it).
+// v2.12.0 Group B Tier 5: security-review + perf-baseline → AUDIT_SECURITY +
+// AUDIT_PERF (with legacy shims for 1-minor-release back-compat).
+// v2.13.1 Group A: add MUT_REPORT (same rd-side hard block rationale as
+// FEATURE_TABLE).
+const BUGFIX_TABLE = {
+    'prd:handed-off': [PRD_CONTENT],
+    'rd:implemented': [BUG_ANALYSIS],
+    'rd:qa-handoff': [
+        BUG_ANALYSIS,
+        CODE_REVIEW,
+        AUDIT_REQUIRES_HANDOFF,
+        AUDIT_SECURITY,
+        AUDIT_PERF,
+        KARPATHY_REVIEW,
+        THIRD_PARTY_REVIEW,
+        MUT_REPORT,
+        UNIT_TESTS,
+        QA_INITIATED
+    ],
+    'qa:running': [TEST_CASES],
+    'qa:verdict-issued': [TEST_CASES, TEST_REPORT]
+};
+// Refactor: same as feature; refactor hard gates (coverage ≥ 95%) are enforced separately in peaks-rd SKILL.
+const REFACTOR_TABLE = FEATURE_TABLE;
+// Docs / chore: minimal gate — require PRD content before proceeding.
+// Prevents jumping to implementation without planning.
+const MINIMAL_TABLE = {
+    'prd:handed-off': [PRD_CONTENT]
+};
+// Config: security review is the only mandatory check (config changes can break auth, CORS, CSP, secrets handling).
+// v2.11.0 D1/D4: SECURITY_FINDINGS dropped from qa:verdict-issued (peaks-rd owns security evidence).
+const CONFIG_TABLE = {
+    'prd:handed-off': [PRD_CONTENT],
+    'rd:qa-handoff': [SECURITY_REVIEW],
+    'qa:verdict-issued': [TEST_REPORT]
+};
+const PREREQUISITES_BY_TYPE = {
+    feature: FEATURE_TABLE,
+    bugfix: BUGFIX_TABLE,
+    refactor: REFACTOR_TABLE,
+    docs: MINIMAL_TABLE,
+    config: CONFIG_TABLE,
+    chore: MINIMAL_TABLE
+};
+export function getPrerequisitesFor(role, newState, requestType = DEFAULT_REQUEST_TYPE) {
+    const table = PREREQUISITES_BY_TYPE[requestType];
+    return table[`${role}:${newState}`] ?? [];
+}
+function resolvePrerequisitePath(prerequisite, requestId) {
+    return prerequisite.relativePath.replace('<rid>', requestId);
+}
+/**
+ * Resolve a prerequisite to an on-disk path, tolerating the numbered filename
+ * prefix that `request init` writes (e.g. `001-<rid>.md`). When the prerequisite
+ * path contains `<rid>`, we accept either the legacy bare `<rid>.md` form or any
+ * `NNN-<rid>.md` numbered form — mirroring the matcher in request-artifact-service.
+ * Returns the matched absolute path, or null when nothing matches.
+ */
+async function resolvePrerequisiteAbsolutePath(sessionRoot, prerequisite, requestId) {
+    const relative = resolvePrerequisitePath(prerequisite, requestId);
+    const exact = join(sessionRoot, relative);
+    if (await pathExists(exact)) {
+        return exact;
+    }
+    // Only `<rid>`-templated prerequisites can carry a numbered prefix; fixed paths
+    // (e.g. rd/tech-doc.md) are matched exactly above.
+    if (!prerequisite.relativePath.includes('<rid>')) {
+        return null;
+    }
+    const dir = dirname(exact);
+    const targetSuffix = `-${basename(exact)}`;
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+    const match = entries.find((name) => /^\d+-/.test(name) && name.endsWith(targetSuffix));
+    return match ? join(dir, match) : null;
+}
+export async function checkPrerequisites(options) {
+    const requirements = getPrerequisitesFor(options.role, options.newState, options.requestType);
+    if (requirements.length === 0) {
+        return { ok: true, missing: [], warnings: [] };
+    }
+    // Slice 006 simplifies the resolution to a 2-tier fallback. The
+    // per-change-id scope (`.peaks/_runtime/<sessionId>/<role>/`) is gone — new
+    // artifacts go to the session dir directly. The 2 tiers are:
+    //   1. `.peaks/_runtime/<sid>/<role>/...` (post-F3 canonical
+    //      session home; primary).
+    //   2. `.peaks/_runtime/<sid>/<role>/...` (pre-F3 legacy session home;
+    //      back-compat).
+    // The sessionId is preserved in the artifact body's frontmatter for
+    // human navigation; it is no longer a filesystem path key.
+    const canonicalSessionRoot = options.sessionId !== undefined
+        ? join(options.projectRoot, '.peaks', '_runtime', options.sessionId)
+        : null;
+    const legacySessionRoot = options.sessionId !== undefined
+        ? join(options.projectRoot, '.peaks', options.sessionId)
+        : null;
+    const missing = [];
+    const warnings = [];
+    for (const prerequisite of requirements) {
+        const relative = resolvePrerequisitePath(prerequisite, options.requestId);
+        const absolute = await resolvePrerequisiteAbsolutePathWithFallback(canonicalSessionRoot, legacySessionRoot, prerequisite, options.requestId);
+        if (absolute === null) {
+            // v2.13.2 AC-5: back-compat window for MUT_REPORT — missing
+            // file downgrades to a warning, NOT a hard failure. v2.14.0
+            // will remove this branch and re-elevate missing → throw.
+            const backCompat = prerequisite.backCompat === true;
+            if (backCompat) {
+                warnings.push({
+                    path: relative,
+                    code: 'mut-report-missing-deprecated-in-v2.14.0',
+                    message: `${prerequisite.description} — file missing; soft-blocked under v2.13.2 1-minor back-compat window. v2.14.0 hard-fail.`
+                });
+                continue;
+            }
+            missing.push({ path: relative, description: prerequisite.description });
+            continue;
+        }
+        if (prerequisite.mustContain && prerequisite.mustContain.length > 0) {
+            const body = await readFile(absolute, 'utf8');
+            const lowered = body.toLowerCase();
+            const missingMarkers = prerequisite.mustContain.filter((marker) => !lowered.includes(marker.toLowerCase()));
+            if (missingMarkers.length > 0) {
+                missing.push({
+                    path: relative,
+                    description: `${prerequisite.description} — missing section(s): ${missingMarkers.join(', ')}`
+                });
+            }
+        }
+        if (prerequisite.headingMustContain && prerequisite.headingMustContain.length > 0) {
+            const body = await readFile(absolute, 'utf8');
+            // Slice 2.6.1.F: a line beginning with `#`, `##`, or `###` followed by
+            // the marker (case-insensitive). Fenced code blocks are NOT excluded
+            // here — a "heading" inside a code fence is rare and, when present,
+            // should still be reported as missing to keep the contract strict.
+            const headingLines = body
+                .split('\n')
+                .map((line) => line.trim())
+                .filter((line) => /^#{1,3}\s+/.test(line));
+            const loweredHeadings = headingLines.map((h) => h.toLowerCase());
+            const missingHeadings = prerequisite.headingMustContain.filter((marker) => !loweredHeadings.some((h) => h.includes(marker.toLowerCase())));
+            if (missingHeadings.length > 0) {
+                missing.push({
+                    path: relative,
+                    description: `${prerequisite.description} — missing heading(s): ${missingHeadings.join(', ')}`
+                });
+            }
+        }
+        if (prerequisite.mustContainAny && prerequisite.mustContainAny.length > 0) {
+            const body = await readFile(absolute, 'utf8');
+            const lowered = body.toLowerCase();
+            const hitAny = prerequisite.mustContainAny.some((marker) => lowered.includes(marker.toLowerCase()));
+            if (!hitAny) {
+                missing.push({
+                    path: relative,
+                    description: `${prerequisite.description} — none of the escape-hatch markers present: ${prerequisite.mustContainAny.join(', ')}`
+                });
+            }
+        }
+    }
+    const result = { ok: missing.length === 0, missing, warnings };
+    emitPrereqTransitionEvent({
+        projectRoot: options.projectRoot,
+        sessionId: options.sessionId ?? '',
+        role: options.role,
+        newState: options.newState,
+        requestId: options.requestId,
+        result
+    });
+    return result;
+}
+// Slice C of v2.11.1 — observability hook #7/7. Fire-and-forget per
+// PRD Q4. The synchronous emit never throws and never blocks the
+// prereq check return value.
+function emitPrereqTransitionEvent(opts) {
+    if (opts.sessionId === undefined)
+        return;
+    emitObservabilityEvent({
+        schemaVersion: 1,
+        ts: new Date().toISOString(),
+        sessionId: opts.sessionId,
+        category: 'slice-transition',
+        sliceRid: opts.requestId,
+        detail: {
+            artifactRole: opts.role,
+            to: opts.newState,
+            prereqOk: opts.result.ok,
+            missingCount: opts.result.missing.length
+        }
+    }, { projectRoot: opts.projectRoot });
+}
+/**
+ * Resolve a prerequisite to an on-disk path, with a 2-tier fallback
+ * (slice 006 — the per-change-id tier was dropped because per-change-id
+ * dirs are no longer created):
+ *   1. `<canonicalSessionRoot>/<relative>` (post-F3 canonical session
+ *      home, when `canonicalSessionRoot` is provided).
+ *   2. `<legacySessionRoot>/<relative>` (pre-F3 legacy session home,
+ *      when `legacySessionRoot` is provided).
+ * Tolerates the numbered filename prefix that `request init` writes
+ * (e.g. `001-<rid>.md`) at every tier. Returns the matched absolute
+ * path, or null when nothing matches.
+ *
+ * v2.12.0 Group B Tier 5: if `prerequisite.legacyRelativePath` is set
+ * and neither primary session-root tier resolved, the resolver tries
+ * the legacy relative path at BOTH session roots before declaring the
+ * prereq missing. This is the 1-minor-release back-compat mechanism
+ * for artifacts that moved location (e.g. `rd/security-review.md` →
+ * `audit/security.md`).
+ */
+async function resolvePrerequisiteAbsolutePathWithFallback(canonicalSessionRoot, legacySessionRoot, prerequisite, requestId) {
+    const roots = [canonicalSessionRoot, legacySessionRoot];
+    // First pass: try the primary relativePath at every root.
+    for (const root of roots) {
+        if (root === null)
+            continue;
+        const found = await resolvePrerequisiteAbsolutePath(root, prerequisite, requestId);
+        if (found !== null)
+            return found;
+    }
+    // Second pass: if a legacyRelativePath is declared, try it at every
+    // root. Only the relativePath is swapped — the same numbered-prefix
+    // tolerance applies via the shared resolver.
+    if (prerequisite.legacyRelativePath !== undefined) {
+        const legacyPrereq = {
+            ...prerequisite,
+            relativePath: prerequisite.legacyRelativePath
+        };
+        for (const root of roots) {
+            if (root === null)
+                continue;
+            const found = await resolvePrerequisiteAbsolutePath(root, legacyPrereq, requestId);
+            if (found !== null)
+                return found;
+        }
+    }
+    return null;
+}

package/dist/services/artifacts/artifact-service.d.ts

@@ -0,0 +1,43 @@
+export type ArtifactProvider = 'github' | 'gitlab';
+export type ArtifactInitPlan = {
+    provider: ArtifactProvider;
+    name: string;
+    visibility: 'private';
+    localPath: string;
+    remoteFirst: boolean;
+    dryRun: boolean;
+    plannedActions: string[];
+    tokenPolicy: string;
+};
+export type GuidedArtifactSetup = {
+    step: 'detect' | 'configure' | 'validate' | 'complete';
+    workspaceId: string | null;
+    workspacePath: string | null;
+    provider: ArtifactProvider | null;
+    repoOwner: string | null;
+    repoName: string | null;
+    localPath: string;
+    remoteUrl: string | null;
+    validationResult: {
+        workspaceExists: boolean;
+        gitAvailable: boolean;
+        ghTokenAvailable: boolean;
+        sshKeyAvailable: boolean;
+    };
+    nextStep: string;
+    guidance: string[];
+};
+export declare function createArtifactInitPlan(options: {
+    provider: ArtifactProvider;
+    name: string;
+    localPath?: string;
+    dryRun?: boolean;
+}): ArtifactInitPlan;
+export declare function createGuidedArtifactSetup(): GuidedArtifactSetup;
+export declare function getArtifactStatus(): {
+    mode: string;
+    supportedProviders: ArtifactProvider[];
+    localPath: string;
+    configured: boolean;
+    nextActions: string[];
+};

package/dist/services/artifacts/artifact-service.js

@@ -0,0 +1,98 @@
+import { existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+import { getWorkspaceConfigForPath } from '../config/config-service.js';
+import { getArtifactRemoteRepo, getLocalArtifactPath } from './workspace-service.js';
+function getRemoteUrl(artifactRepo) {
+    if (!artifactRepo)
+        return null;
+    if (artifactRepo.provider === 'github') {
+        return `https://github.com/${artifactRepo.owner}/${artifactRepo.name}.git`;
+    }
+    return `https://gitlab.com/${artifactRepo.owner}/${artifactRepo.name}.git`;
+}
+function hasGit() {
+    try {
+        execFileSync('git', ['--version']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function hasSshKey() {
+    const sshDir = resolve(process.env.HOME ?? homedir(), '.ssh');
+    const keyNames = ['id_ed25519', 'id_rsa', 'id_ecdsa', 'id_dsa'];
+    return keyNames.some((keyName) => existsSync(resolve(sshDir, keyName)));
+}
+export function createArtifactInitPlan(options) {
+    return {
+        provider: options.provider,
+        name: options.name,
+        visibility: 'private',
+        localPath: options.localPath ?? '.peaks-artifacts',
+        remoteFirst: true,
+        dryRun: options.dryRun ?? true,
+        plannedActions: [
+            `confirm creation of private ${options.provider} artifact repository`,
+            'verify authentication without storing tokens',
+            `create or link remote artifact repository ${options.name}`,
+            `prepare local working copy at ${options.localPath ?? '.peaks-artifacts'}`,
+            'write artifact repository creation report'
+        ],
+        tokenPolicy: 'Use provider auth/CLI or environment tokens only; never write tokens to skills, artifacts, config, or reports.'
+    };
+}
+export function createGuidedArtifactSetup() {
+    const workspace = getWorkspaceConfigForPath(process.cwd());
+    const artifactRepo = workspace ? getArtifactRemoteRepo(workspace) : null;
+    const validationResult = {
+        workspaceExists: workspace !== null,
+        gitAvailable: hasGit(),
+        ghTokenAvailable: Boolean(process.env.GH_TOKEN?.trim()),
+        sshKeyAvailable: hasSshKey()
+    };
+    const localPath = workspace ? getLocalArtifactPath(workspace) : '.peaks-artifacts';
+    const remoteUrl = getRemoteUrl(artifactRepo ?? undefined);
+    return {
+        step: 'detect',
+        workspaceId: workspace?.workspaceId ?? null,
+        workspacePath: workspace?.rootPath ?? null,
+        provider: artifactRepo?.provider ?? null,
+        repoOwner: artifactRepo?.owner ?? null,
+        repoName: artifactRepo?.name ?? null,
+        localPath,
+        remoteUrl,
+        validationResult,
+        nextStep: workspace ? (artifactRepo ? 'validate' : 'complete') : 'configure',
+        guidance: [
+            'Step 1: Detect current workspace and environment',
+            `  - Workspace: ${workspace?.workspaceId ?? 'not configured'}`,
+            `  - Git available: ${validationResult.gitAvailable ? 'yes' : 'no'}`,
+            `  - GH_TOKEN environment variable: ${validationResult.ghTokenAvailable ? 'available' : 'not set'}`,
+            `  - SSH key for code push: ${validationResult.sshKeyAvailable ? 'available' : 'not found'}`,
+            '',
+            'Step 2: Configure artifact repository',
+            '  - Optional for local-only storage',
+            '  - Run: peaks artifacts init --provider github --name <repo> --dry-run',
+            '  - Or add to workspace: peaks config workspace add --id <id> --provider github --repo-owner <owner> --repo-name <name>',
+            '',
+            'Step 3: Validate setup',
+            '  - Run: peaks sc status',
+            '  - Run: peaks artifacts workspace',
+            '',
+            'Step 4: Complete',
+            artifactRepo ? '  - Artifact sync is ready when workspace has remote artifact storage configured' : '  - Local artifact storage is ready'
+        ]
+    };
+}
+export function getArtifactStatus() {
+    return {
+        mode: 'remote-first',
+        supportedProviders: ['github', 'gitlab'],
+        localPath: '.peaks-artifacts',
+        configured: false,
+        nextActions: ['Run peaks artifacts init --provider gitlab --name <repo> --dry-run']
+    };
+}

package/dist/services/artifacts/artifact-templates.d.ts

@@ -0,0 +1,30 @@
+import type { RequestType } from './artifact-prerequisites.js';
+/**
+ * Role discriminator for the five request-artifact templates. Lives here
+ * (rather than in `request-artifact-service.ts`) so this pure-function
+ * module has no dependency on the service. The service re-exports it for
+ * back-compat with external callers.
+ */
+export type RequestArtifactRole = 'prd' | 'ui' | 'rd' | 'qa' | 'sc';
+/**
+ * Handoff path helpers.
+ *
+ * Slice 2026-06-29-change-id-root-removal: all handoff paths now key
+ * on the session-id axis (`.peaks/_runtime/<sessionId>/<role>/...`)
+ * instead of the deleted change-id axis
+ * (`.peaks/_runtime/change/<sessionId>/<role>/...`). The session
+ * dir is gitignored; the hard ban on `.peaks/_runtime/<id>/`
+ * siblings remains in force.
+ *
+ * The render functions below emit markdown bodies that quote these
+ * paths verbatim as write instructions — if the body contains a
+ * banned top-level path, the sub-agent prompt will recreate the
+ * forbidden dir on its next write.
+ */
+/** Canonical handoff path for a downstream role's request artifact. */
+export declare function formatHandoffPath(sessionId: string, role: string, requestId: string): string;
+/** Canonical path for the SC commit-boundary handoff artifact. */
+export declare function formatCommitBoundaryPath(sessionId: string, requestId: string): string;
+/** Canonical path for the txt skill-usage lessons log under a session scope. */
+export declare function formatSkillUsageLessonsPath(sessionId: string): string;
+export declare function renderTemplate(role: RequestArtifactRole, requestId: string, sessionId: string, changeSlug: string, timestamp: string, requestType: RequestType): string;