peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/sc/sc-service.js

@@ -0,0 +1,552 @@
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import { isInsidePath } from '../../shared/path-utils.js';
+import { getWorkspaceConfigForPath } from '../config/config-service.js';
+import { getArtifactRemoteRepo, getArtifactWorkspaceStatus, getLocalArtifactPath } from '../artifacts/workspace-service.js';
+import { getSessionId } from '../session/session-manager.js';
+const REQUIRED_ARTIFACTS = [
+    { name: 'retention-boundary.md', path: ['sc', 'retention-boundary.md'] },
+    { name: 'change-impact.json', path: ['sc', 'change-impact.json'] },
+    { name: 'coverage-report.md', path: ['rd', 'coverage-report.md'] }
+];
+const RETENTION_REQUIREMENTS = [
+    ['prd', 'refactor-goal.md'],
+    ['rd', 'slice-spec.md'],
+    ['rd', 'coverage-report.md'],
+    ['rd', 'code-review-report.md'],
+    ['rd', 'security-review-report.md'],
+    ['rd', 'post-check-dry-run.md'],
+    ['qa', 'validation-report.md'],
+    ['sc', 'change-impact.json'],
+    ['sc', 'retention-boundary.md'],
+    ['txt', 'context-capsule.md']
+];
+/**
+ * "Modern" retention requirements for the current peaks-loop artifact
+ * naming convention. The legacy `RETENTION_REQUIREMENTS` above assume
+ * older `refactor-goal.md` / `slice-spec.md` / `coverage-report.md` /
+ * `validation-report.md` / `change-impact.json` / `retention-boundary.md`
+ * / `context-capsule.md` filenames that predate the W4 session resolver.
+ *
+ * When the resolver finds a session that owns the slice, validate
+ * against the modern set: the actual files the current workflow emits
+ * (per-slice `prd/requests/<rid>.md`, per-slice `rd/requests/<rid>.md`,
+ * per-session `rd/tech-doc.md`, per-slice `qa/test-cases/<rid>.md`,
+ * per-slice `qa/test-reports/<rid>.md`, per-session `txt/handoff.md`).
+ * The legacy set is preserved for the workspace-artifact path so
+ * existing repos on the old convention keep working.
+ */
+const MODERN_RETENTION_REQUIREMENTS = [
+    'rd/tech-doc.md',
+    'qa/test-cases/{sliceId}.md',
+    'qa/test-reports/{sliceId}.md',
+    'txt/handoff.md'
+];
+const SLICE_ID_PATTERN = /^(?!\.{1,2}$)[A-Za-z0-9._-]+$/;
+function getPeaksPath(workspaceRoot) {
+    return resolve(workspaceRoot, '.peaks');
+}
+function getArtifactRepoUrl(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 getCurrentCommitHash(workspaceRoot) {
+    if (!workspaceRoot)
+        return null;
+    try {
+        return execFileSync('git', ['rev-parse', 'HEAD'], { cwd: workspaceRoot, encoding: 'utf-8' }).trim();
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+function mapSyncState(syncStatus) {
+    if (syncStatus === 'synced')
+        return 'synced';
+    if (syncStatus === 'pending')
+        return 'pending';
+    return 'failed';
+}
+function getCurrentArtifactDir(artifactWorkspacePath) {
+    const peaksPath = getPeaksPath(artifactWorkspacePath);
+    // Slice 2026-06-29-change-id-root-removal: the `.peaks/_runtime/current-change`
+    // binding file is gone. Resolve the active change-id from the workspace
+    // session binding instead. When no session is bound, fall back to
+    // `unknown-session` (matches the previous behaviour for an unbound workspace).
+    // The on-disk change dir lives under the canonical
+    // `.peaks/_runtime/<sid>/` layer (single-axis layout).
+    const sessionId = getSessionId(artifactWorkspacePath);
+    const effectiveChangeId = sessionId ?? 'unknown-session';
+    return {
+        peaksPath,
+        sessionId,
+        changeDir: resolve(peaksPath, '_runtime', effectiveChangeId)
+    };
+}
+function getRetentionChangeDir(artifactWorkspacePath, sliceId) {
+    // Slice 2026-06-29-change-id-root-removal: retention slice dirs
+    // remain under the legacy `.peaks/<sliceId>/` shape (they're shipped
+    // / frozen artifacts, not session-scoped workspace state). Only the
+    // ACTIVE session-dir resolution uses `_runtime/` — retention slices
+    // are a different lifecycle.
+    const peaksPath = getPeaksPath(artifactWorkspacePath);
+    return {
+        peaksPath,
+        sessionId: sliceId,
+        changeDir: resolve(peaksPath, sliceId)
+    };
+}
+function isRetainedArtifactFile(filePath, artifactWorkspacePath, changesRoot, changeDir) {
+    if (!existsSync(filePath))
+        return false;
+    try {
+        const artifactWorkspaceRealPath = realpathSync(artifactWorkspacePath);
+        const changesRootRealPath = realpathSync(changesRoot);
+        const changeDirRealPath = realpathSync(changeDir);
+        const fileRealPath = realpathSync(filePath);
+        return !lstatSync(changesRoot).isSymbolicLink()
+            && !lstatSync(changeDir).isSymbolicLink()
+            && isInsidePath(changesRootRealPath, artifactWorkspaceRealPath)
+            && isInsidePath(changeDirRealPath, changesRootRealPath)
+            && isInsidePath(fileRealPath, changeDirRealPath);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read the orchestrator's active-skill marker and return its
+ * `sessionId`, or null when the file is missing / malformed.
+ *
+ * As of slice 2026-06-05-peaks-runtime-layer the canonical home is
+ * `<projectRoot>/.peaks/_runtime/active-skill.json`. The legacy
+ * `<projectRoot>/.peaks/.active-skill.json` is consulted as a
+ * one-minor-release back-compat fallback: if the new path is
+ * absent but the legacy path is present and valid, we use the
+ * legacy value. The new path always wins when both exist.
+ */
+function readActiveSkillSessionId(projectRoot) {
+    const newPath = join(projectRoot, '.peaks', '_runtime', 'active-skill.json');
+    const legacyPath = join(projectRoot, '.peaks', '.active-skill.json');
+    const pathToRead = existsSync(newPath) ? newPath : legacyPath;
+    if (!existsSync(pathToRead))
+        return null;
+    try {
+        const raw = readFileSync(pathToRead, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.sessionId === 'string' && parsed.sessionId.length > 0) {
+            return parsed.sessionId;
+        }
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+    return null;
+}
+/**
+ * Read the workspace session binding and return its `sessionId`,
+ * or null when the file is missing / malformed.
+ *
+ * As of slice 2026-06-05-peaks-runtime-layer the canonical home is
+ * `<projectRoot>/.peaks/_runtime/session.json`. The legacy
+ * `<projectRoot>/.peaks/.session.json` is consulted as a
+ * one-minor-release back-compat fallback: if the new path is
+ * absent but the legacy path is present and valid, we use the
+ * legacy value. The new path always wins when both exist.
+ */
+function readSessionJsonBinding(projectRoot) {
+    const newPath = join(projectRoot, '.peaks', '_runtime', 'session.json');
+    const legacyPath = join(projectRoot, '.peaks', '.session.json');
+    const pathToRead = existsSync(newPath) ? newPath : legacyPath;
+    if (!existsSync(pathToRead))
+        return null;
+    try {
+        const raw = readFileSync(pathToRead, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.sessionId === 'string' && parsed.sessionId.length > 0) {
+            return parsed.sessionId;
+        }
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+    return null;
+}
+/**
+ * The "marker" artifact whose existence under a session dir is the signal
+ * that the session owns the slice. We look for `qa/test-cases/<sliceId>.md`
+ * first (a present test plan is the most decisive signal of session
+ * ownership for a slice id). If the test plan is absent we also accept
+ * `qa/test-reports/<sliceId>.md` (a finished QA report is also a decisive
+ * ownership signal). When neither exists for a candidate session, that
+ * session does not own the slice.
+ */
+function sessionOwnsSlice(projectRoot, sessionId, sliceId) {
+    // As of slice 2026-06-05-change-id-as-unit-of-work, the same
+    // session id can live at multiple umbrella locations:
+    //   - `.peaks/_runtime/<sessionId>/` (legacy or top-level active)
+    //   - `.peaks/retrospective/<sessionId>/` (shipped slice)
+    //   - `.peaks/_dogfood/<sessionId>/` (dogfood evidence)
+    // Try each in turn; the first match wins.
+    const candidateDirs = [
+        join(projectRoot, '.peaks', sessionId),
+        join(projectRoot, '.peaks', 'retrospective', sessionId),
+        join(projectRoot, '.peaks', '_dogfood', sessionId)
+    ];
+    for (const sessionDir of candidateDirs) {
+        if (!existsSync(sessionDir))
+            continue;
+        for (const marker of [`qa/test-cases/${sliceId}.md`, `qa/test-reports/${sliceId}.md`]) {
+            if (existsSync(join(sessionDir, marker)))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Find a session dir under `<projectRoot>/.peaks/` that owns the slice
+ * (see `sessionOwnsSlice`). Returns the first match in lexicographic
+ * order, or null when no session owns the slice.
+ */
+function findSessionOwningSlice(projectRoot, sliceId) {
+    const peaksRoot = join(projectRoot, '.peaks');
+    if (!existsSync(peaksRoot))
+        return null;
+    let topLevel;
+    try {
+        topLevel = readdirSync(peaksRoot);
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+    topLevel.sort();
+    // As of slice 2026-06-05-change-id-as-unit-of-work, shipped slices
+    // are archived under `.peaks/retrospective/<dir>/` and dogfood
+    // evidence lives under `.peaks/_dogfood/<dir>/`. Both umbrellas host
+    // scopes at one level deeper than the top-level `.peaks/_runtime/<dir>/`
+    // shape. Expand the candidate list so the find-fallback tier can
+    // locate these. Accept both legacy session-id format
+    // (`YYYY-MM-DD-session-<6hex>`) and new change-id format
+    // (`YYYY-MM-DD-<slug>`) as valid scope dir names.
+    const candidateSessionIds = [];
+    for (const entry of topLevel) {
+        if (entry === 'retrospective' || entry === '_dogfood') {
+            const nested = readdirSyncSafe(join(peaksRoot, entry));
+            for (const n of nested) {
+                candidateSessionIds.push(n);
+            }
+        }
+        else {
+            candidateSessionIds.push(entry);
+        }
+    }
+    candidateSessionIds.sort();
+    for (const id of candidateSessionIds) {
+        // Legacy session-id format OR new change-id format. Reject files
+        // and other non-scope entries (e.g. .peaks-init-hooks-decision.json,
+        // PROJECT.md, _runtime, memory, sops, perf-baseline, etc.)
+        if (!isScopeDirName(id))
+            continue;
+        if (sessionOwnsSlice(projectRoot, id, sliceId)) {
+            return id;
+        }
+    }
+    return null;
+}
+/** Is this a valid legacy session-id OR new change-id dir name? */
+function isScopeDirName(name) {
+    // Legacy: 2026-MM-DD-session-<6hex>
+    if (/^\d{4}-\d{2}-\d{2}-session-[a-f0-9]+$/.test(name))
+        return true;
+    // New: 2026-MM-DD-<slug> where slug is letters / digits / hyphens / dots
+    // (the slice-migration kept the 4-digit year prefix, so 3-digit
+    // numbered filenames from request artifacts stay out of this path —
+    // they live in retrospective/ nested with the year-prefixed change-id
+    // as the dir, not at top level).
+    if (/^\d{4}-\d{2}-\d{2}-[\w.\-]+$/.test(name))
+        return true;
+    return false;
+}
+function readdirSyncSafe(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Resolve the session id that owns the slice's artifacts using a 3-tier
+ * precedence:
+ *
+ *   1. `.peaks/_runtime/active-skill.json` `sessionId` (with back-compat
+ *      fallback to `.peaks/.active-skill.json`) if it points to a real
+ *      session that owns the slice.
+ *   2. `.peaks/_runtime/session.json` `sessionId` (with back-compat
+ *      fallback to `.peaks/.session.json`) if it points to a real
+ *      session that owns the slice.
+ *   3. `find .peaks/ -name '<marker>'` — the first session dir under
+ *      `.peaks/` that owns the slice.
+ *   4. else `{ resolvedSessionId: null, candidateSources: [] }`.
+ *
+ * The back-compat fallbacks are tolerated for one minor release so
+ * users with pre-migration trees (or running an older CLI version)
+ * still get a clean resolution. After the migration (or after v1.3.0
+ * is installed and `peaks workspace reconcile` has been run), only
+ * the new paths exist and the fallbacks never fire.
+ *
+ * `candidateSources` reports which sources were checked before the
+ * resolver found (or did not find) a winner; the list is in the order
+ * the resolver consulted them. This makes the precedence observable in
+ * the JSON envelope so a human reviewer can see "active-skill was empty
+ * AND session-json was empty, so find-fallback won".
+ */
+export function resolveArtifactSession(projectRoot, sliceId) {
+    const activeSkill = readActiveSkillSessionId(projectRoot);
+    if (activeSkill !== null && sessionOwnsSlice(projectRoot, activeSkill, sliceId)) {
+        return { resolvedSessionId: activeSkill, candidateSources: ['active-skill'] };
+    }
+    const sessionJson = readSessionJsonBinding(projectRoot);
+    if (sessionJson !== null && sessionOwnsSlice(projectRoot, sessionJson, sliceId)) {
+        return { resolvedSessionId: sessionJson, candidateSources: ['active-skill', 'session-json'] };
+    }
+    const findHit = findSessionOwningSlice(projectRoot, sliceId);
+    if (findHit !== null) {
+        return { resolvedSessionId: findHit, candidateSources: ['active-skill', 'session-json', 'find-fallback'] };
+    }
+    return { resolvedSessionId: null, candidateSources: [] };
+}
+export function getChangeTraceabilityStatus() {
+    const workspace = getWorkspaceConfigForPath(process.cwd());
+    const artifactStatus = getArtifactWorkspaceStatus(workspace?.workspaceId);
+    if (!workspace) {
+        return {
+            sessionId: null,
+            hasArtifactRepo: false,
+            artifactSyncStatus: 'unknown',
+            localArtifactPath: '.peaks-artifacts',
+            requiredArtifacts: REQUIRED_ARTIFACTS.map((artifact) => ({
+                name: artifact.name,
+                path: resolve('.peaks', '<session-id>', ...artifact.path),
+                exists: false
+            })),
+            nextActions: ['Add a workspace: peaks config workspace add --id <id> --name <name> --path <path>']
+        };
+    }
+    const artifactWorkspacePath = getLocalArtifactPath(workspace);
+    const { peaksPath, sessionId, changeDir } = getCurrentArtifactDir(artifactWorkspacePath);
+    const artifactRepo = getArtifactRemoteRepo(workspace);
+    const hasArtifactRepo = Boolean(artifactRepo);
+    const changesRoot = peaksPath;
+    const requiredArtifacts = REQUIRED_ARTIFACTS.map((artifact) => {
+        const artifactPath = resolve(changeDir, ...artifact.path);
+        return {
+            name: artifact.name,
+            // Slice 2026-06-29-change-id-root-removal: the reported path
+            // matches the canonical single-axis layout
+            // `.peaks/_runtime/<sid>/...`.
+            path: resolve(peaksPath, '_runtime', sessionId ?? '<session-id>', ...artifact.path),
+            exists: isRetainedArtifactFile(artifactPath, artifactWorkspacePath, changesRoot, changeDir)
+        };
+    });
+    const nextActions = [];
+    if (!sessionId) {
+        nextActions.push('Run `peaks workspace init` to bind a session for this workspace');
+    }
+    if (hasArtifactRepo && artifactStatus.syncStatus === 'pending') {
+        nextActions.push(`Run peaks artifacts sync --workspace ${workspace.workspaceId} --dry-run`);
+    }
+    return {
+        sessionId,
+        hasArtifactRepo,
+        artifactSyncStatus: artifactStatus.syncStatus,
+        localArtifactPath: getLocalArtifactPath(workspace),
+        requiredArtifacts,
+        nextActions
+    };
+}
+export function createChangeImpact(options) {
+    const workspace = getWorkspaceConfigForPath(process.cwd());
+    const artifactRepo = workspace ? getArtifactRemoteRepo(workspace) : null;
+    return {
+        sessionId: options.sessionId,
+        sourceArtifacts: options.sourceArtifacts ?? [],
+        affectedModules: options.affectedModules ?? [],
+        affectedFiles: options.affectedFiles ?? [],
+        qaImpact: {
+            coverageDelta: null,
+            testCount: 0,
+            status: 'unknown'
+        },
+        riskImpact: {
+            level: 'medium',
+            factors: ['Manual review required', 'No automated gates detected']
+        },
+        syncPointers: {
+            artifactRepo: getArtifactRepoUrl(artifactRepo ?? undefined),
+            lastSync: null,
+            localPath: workspace ? getLocalArtifactPath(workspace) : '.peaks-artifacts'
+        }
+    };
+}
+export function createArtifactRetentionReport(options) {
+    return {
+        sliceId: options.sliceId,
+        prdArtifacts: options.prdArtifacts ?? [],
+        rdArtifacts: options.rdArtifacts ?? [],
+        qaArtifacts: options.qaArtifacts ?? [],
+        coverageArtifacts: options.coverageArtifacts ?? [],
+        reviewArtifacts: options.reviewArtifacts ?? [],
+        codeChanges: options.codeChanges ?? [],
+        retentionStatus: 'pending',
+        commitHash: null,
+        rollbackPoint: null
+    };
+}
+export function recordCommitBoundary(options) {
+    const workspace = getWorkspaceConfigForPath(process.cwd());
+    const artifactStatus = getArtifactWorkspaceStatus(workspace?.workspaceId);
+    const commitHash = getCurrentCommitHash(workspace?.rootPath);
+    const projectRoot = workspace?.rootPath ?? process.cwd();
+    const resolution = resolveArtifactSession(projectRoot, options.sliceId);
+    return {
+        sliceId: options.sliceId,
+        commitHash,
+        timestamp: new Date().toISOString(),
+        artifacts: options.artifacts ?? [],
+        codeFiles: options.codeFiles ?? [],
+        syncState: mapSyncState(artifactStatus.syncStatus),
+        rollbackPoint: commitHash,
+        resolvedSessionId: resolution.resolvedSessionId,
+        candidateSources: resolution.candidateSources
+    };
+}
+export function validateArtifactRetention(sliceId) {
+    const workspace = getWorkspaceConfigForPath(process.cwd());
+    // Resolve from `process.cwd()` even when no workspace is configured, so
+    // the W4 session resolver can still find the slice's owning session.
+    // The legacy "no workspace" check still surfaces as a missing artifact,
+    // but the resolution happens first so the JSON envelope's additive
+    // `resolvedSessionId` is populated regardless of workspace state.
+    const projectRoot = workspace?.rootPath ?? process.cwd();
+    if (!SLICE_ID_PATTERN.test(sliceId)) {
+        return {
+            valid: false,
+            missingArtifacts: ['Invalid slice id'],
+            warnings: ['Slice id must stay inside .peaks/_runtime/<session-id> and only contain letters, numbers, dots, underscores, or hyphens'],
+            resolvedSessionId: null,
+            candidateSources: []
+        };
+    }
+    const resolution = resolveArtifactSession(projectRoot, sliceId);
+    const effectiveSliceId = resolution.resolvedSessionId ?? sliceId;
+    // W4: if the resolver found a session, ALSO accept artifacts under
+    // `<projectRoot>/.peaks/_runtime/<resolvedSessionId>/` (the canonical per-slice
+    // dir). The project-root peaks is where the orchestrator's skills
+    // actually write (see `initWorkspace` in `workspace-service.ts`), so
+    // when the resolution chain lands on a real session the artifacts are
+    // usually there. We accept either location — workspace artifact path
+    // OR project-root peaks — so the additive behavior does not regress
+    // existing workspaces.
+    const resolvedPeaksSessionDir = resolution.resolvedSessionId !== null
+        ? join(projectRoot, '.peaks', resolution.resolvedSessionId)
+        : null;
+    // Collect present files: legacy workspace-artifact-path check, OR the
+    // resolved session's project-root peaks dir.
+    const legacyPresent = (folder, file) => {
+        if (!workspace)
+            return false;
+        const artifactWorkspacePath = getLocalArtifactPath(workspace);
+        const { peaksPath, changeDir } = getRetentionChangeDir(artifactWorkspacePath, effectiveSliceId);
+        const filePath = resolve(changeDir, folder, file);
+        return isRetainedArtifactFile(filePath, artifactWorkspacePath, peaksPath, changeDir);
+    };
+    const resolvedPresent = (folder, file) => {
+        if (resolvedPeaksSessionDir === null)
+            return false;
+        return existsSync(join(resolvedPeaksSessionDir, folder, file));
+    };
+    if (!workspace) {
+        // No workspace: validate against the resolved session dir directly
+        // (this is the common peaks-code / peaks-rd invocation: the slice
+        // lives under the project-root `.peaks/_runtime/<sessionId>/`, and the
+        // workspace artifact path is irrelevant). When the resolution also
+        // fails, fall back to the legacy "No workspace configured" failure
+        // mode so the existing CLI contract is preserved.
+        if (resolvedPeaksSessionDir === null) {
+            return {
+                valid: false,
+                missingArtifacts: ['No workspace configured'],
+                warnings: ['Cannot validate without a configured workspace'],
+                resolvedSessionId: resolution.resolvedSessionId,
+                candidateSources: resolution.candidateSources
+            };
+        }
+        const missingArtifacts = modernRequirementRelativePaths(sliceId).filter((rel) => !existsSync(join(resolvedPeaksSessionDir, rel)));
+        return {
+            valid: missingArtifacts.length === 0,
+            missingArtifacts,
+            warnings: missingArtifacts.length === 0 ? [] : ['Some required artifact files are missing'],
+            resolvedSessionId: resolution.resolvedSessionId,
+            candidateSources: resolution.candidateSources
+        };
+    }
+    const missingArtifacts = RETENTION_REQUIREMENTS
+        .map(([folder, file]) => `${folder}/${file}`)
+        .filter((rel) => !legacyPresent(...rel.split('/')) && !resolvedPresent(...rel.split('/')));
+    // If the legacy check is short (i.e. we're missing a lot of legacy-named
+    // files) but the resolver landed on a real session, ALSO accept the
+    // modern set. The legacy set was designed for an older workflow naming
+    // and a freshly-minted session in the current peaks-loop flow will not
+    // have the legacy names. This keeps `peaks sc validate --slice-id <rid>`
+    // returning `valid: true` for slices that completed under the current
+    // peaks-loop convention.
+    if (missingArtifacts.length > 0 && resolvedPeaksSessionDir !== null) {
+        const modernMissing = modernRequirementRelativePaths(sliceId).filter((rel) => !resolvedPresent(...rel.split('/')));
+        if (modernMissing.length === 0) {
+            return {
+                valid: true,
+                missingArtifacts: [],
+                warnings: [],
+                resolvedSessionId: resolution.resolvedSessionId,
+                candidateSources: resolution.candidateSources
+            };
+        }
+    }
+    return {
+        valid: missingArtifacts.length === 0,
+        missingArtifacts,
+        warnings: missingArtifacts.length === 0 ? [] : ['Some required artifact files are missing'],
+        resolvedSessionId: resolution.resolvedSessionId,
+        candidateSources: resolution.candidateSources
+    };
+}
+/**
+ * Render the modern retention requirements as relative paths keyed
+ * against the slice id. The `{sliceId}` placeholder in the template
+ * is replaced with the actual slice id; per-session files (no
+ * placeholder) keep their literal name.
+ */
+function modernRequirementRelativePaths(sliceId) {
+    return MODERN_RETENTION_REQUIREMENTS.map((template) => template.replace('{sliceId}', sliceId));
+}
+export function getScHelpText() {
+    return [
+        'peaks sc status                          Show change traceability status',
+        'peaks sc impact --change-id <id>         Generate change impact artifact',
+        'peaks sc retention --slice-id <id>        Create artifact retention report',
+        'peaks sc validate --slice-id <id>         Validate artifact retention',
+        'peaks sc boundary --slice-id <id>         Record retention boundary for slice',
+        '',
+        'Change traceability workflow integration:',
+        '  1. Run peaks sc status to check current state',
+        '  2. After slice completion, run peaks sc retention --slice-id <id>',
+        '  3. Keep artifacts local in .peaks/_runtime/<session-id>/ by default',
+        '  4. Commit or sync artifacts only after explicit authorization'
+    ];
+}

package/dist/services/scan/acceptance-coverage-service.d.ts

@@ -0,0 +1,42 @@
+export type AcceptanceItem = {
+    id: string;
+    text: string;
+    line: number;
+};
+export type TestCase = {
+    title: string;
+    acceptanceIds: string[];
+    line: number;
+};
+export type CoverageEntry = {
+    acceptanceId: string;
+    acceptanceText: string;
+    testCases: string[];
+};
+export type AcceptanceCoverageReport = {
+    ok: boolean;
+    prdPath: string;
+    testCasesPath: string;
+    acceptanceItems: AcceptanceItem[];
+    testCases: TestCase[];
+    coverage: CoverageEntry[];
+    uncovered: AcceptanceItem[];
+    unlinkedTestCases: TestCase[];
+    invalidReferences: Array<{
+        testCaseTitle: string;
+        reference: string;
+    }>;
+};
+export type AcceptanceCoverageOptions = {
+    projectRoot: string;
+    requestId: string;
+    sessionId?: string;
+};
+export type AcceptanceCoverageError = {
+    kind: 'prd-not-found';
+} | {
+    kind: 'test-cases-not-found';
+    expectedPath: string;
+};
+export declare function getAcceptanceCoverage(options: AcceptanceCoverageOptions): Promise<AcceptanceCoverageReport | AcceptanceCoverageError>;
+export declare function isAcceptanceCoverageError(value: AcceptanceCoverageReport | AcceptanceCoverageError): value is AcceptanceCoverageError;