peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/audit-independent/security-audit-service.js

@@ -0,0 +1,316 @@
+/**
+ * peaks-security-audit service — independent security audit skill driver.
+ *
+ * Slice v2.12.0 (Group A, Tier 2). The skill is decoupled from the
+ * peaks-rd 5-way fan-out (per PRD AC-2.x) and lives as a standalone
+ * CLI surface: `peaks security-audit run --rid <id> ...`.
+ *
+ * The service owns:
+ *   - 5-state detection of the security-audit runtime
+ *     (handoff-missing / template-missing / dispatch-failed / template-malformed / ready)
+ *   - Loading + sha256 verification of the prd/handoff.md
+ *   - Loading the project-level security-template.md
+ *   - Producing the audit envelope (verdict + violations) to write
+ *     to `.peaks/_runtime/<sid>/audit/security-<rid>.md`
+ *
+ * The actual LLM-in-loop audit step is NOT in this service — the
+ * parent LLM (peaks-security-audit skill prompt) reads the template,
+ * runs the audit, and returns a structured envelope. This service
+ * is the pure I/O + validation core; the LLM is the judgement core.
+ *
+ * Why a service (not inlined in the CLI):
+ *   - Unit-testable in isolation (6 case per PRD AC-2.8)
+ *   - The 5-state detector mirrors the ecc-bridge detectEcc pattern
+ *     (slice 7 Group D), keeping the surface uniform
+ *   - Future migration to peaks sub-agent dispatch (peaks-rd main
+ *     loop can opt to call this service directly without re-implementing
+ *     the handoff verification)
+ *
+ * Cross-references:
+ *   - PRD: `.peaks/_runtime/<sid>/prd/handoff.md` (sha256-locked, schemaVersion: 2)
+ *   - Template: `.peaks/project-scan/security-template.md`
+ *   - Output: `.peaks/_runtime/<sid>/audit/security-<rid>.md`
+ *   - Schema: `.peaks/project-scan/audit-output-schema.md` (schemaVersion: 1)
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, resolve, isAbsolute } from 'node:path';
+import { createHash } from 'node:crypto';
+/**
+ * Validate a raw value as a SecurityAuditEnvelope. Mirrors the
+ * `isEccEnvelope` strict-shape pattern.
+ */
+export function isSecurityAuditEnvelope(value) {
+    if (value === null || typeof value !== 'object')
+        return false;
+    const obj = value;
+    if (typeof obj.verdict !== 'string')
+        return false;
+    if (obj.verdict !== 'pass' && obj.verdict !== 'warn' && obj.verdict !== 'block') {
+        return false;
+    }
+    if (!Array.isArray(obj.violations))
+        return false;
+    if (typeof obj.summary !== 'string')
+        return false;
+    for (const v of obj.violations) {
+        if (v === null || typeof v !== 'object')
+            return false;
+        const vo = v;
+        if (typeof vo.dimension !== 'string')
+            return false;
+        if (typeof vo.severity !== 'string')
+            return false;
+        if (vo.severity !== 'CRITICAL' && vo.severity !== 'HIGH' && vo.severity !== 'MED' && vo.severity !== 'LOW') {
+            return false;
+        }
+        if (typeof vo.file !== 'string')
+            return false;
+        if (typeof vo.line !== 'number' || !Number.isFinite(vo.line))
+            return false;
+        if (typeof vo.hint !== 'string')
+            return false;
+    }
+    return true;
+}
+/**
+ * Read the peaks-prd handoff frontmatter + body, verify sha256 matches
+ * the body. Returns null on missing file or sha256 mismatch; otherwise
+ * returns the parsed frontmatter + body string.
+ *
+ * Defensive: we read frontmatter via a 1-line regex match, not via
+ * a YAML parser. The handoff service (`src/services/prd/handoff-service.ts`)
+ * is the canonical writer; we only consume its output here.
+ */
+export function readAndVerifyHandoff(handoffPath, projectRoot) {
+    if (!handoffPath || !isAbsolute(handoffPath)) {
+        const absolutePath = resolve(projectRoot, handoffPath);
+        if (!existsSync(absolutePath))
+            return null;
+        return readAndVerifyHandoff(absolutePath, projectRoot);
+    }
+    if (!existsSync(handoffPath))
+        return null;
+    let raw;
+    try {
+        raw = readFileSync(handoffPath, 'utf8');
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+    // Frontmatter pattern: `---` line, then key: value pairs, then `---` line.
+    const match = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (match === null)
+        return null;
+    const frontmatterRaw = match[1];
+    const body = match[2];
+    const sha256Match = frontmatterRaw.match(/^sha256:\s*([a-f0-9]{64})\s*$/m);
+    const schemaVersionMatch = frontmatterRaw.match(/^schemaVersion:\s*(\d+)\s*$/m);
+    if (sha256Match === null || schemaVersionMatch === null)
+        return null;
+    const sha256Expected = sha256Match[1];
+    const schemaVersion = parseInt(schemaVersionMatch[1], 10);
+    const sha256Actual = createHash('sha256').update(body, 'utf8').digest('hex');
+    if (sha256Expected !== sha256Actual)
+        return null;
+    return {
+        frontmatter: { sha256: sha256Expected, schemaVersion },
+        body,
+    };
+}
+/**
+ * Read the project-level security-template.md. Returns the body
+ * string (with frontmatter stripped) or null if the file is absent.
+ * Does NOT validate the template content; the parent LLM validates
+ * by reading.
+ */
+export function readSecurityTemplate(projectRoot) {
+    const templatePath = join(projectRoot, '.peaks', 'project-scan', 'security-template.md');
+    if (!existsSync(templatePath))
+        return null;
+    try {
+        return readFileSync(templatePath, 'utf8');
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+/**
+ * 5-state detector. The parent skill inspects the state and either
+ * proceeds (when `ready`) or records a degradation note and falls
+ * back (when any other state).
+ *
+ * Soft-fail policy mirrors `detectEcc` (slice 7 Group D): the CLI
+ * never throws; it returns a typed detect result.
+ */
+export function detectSecurityAudit(input) {
+    const warnings = [];
+    const nextActions = [];
+    const handoffPath = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'prd', 'handoff.md');
+    const handoffPresent = existsSync(handoffPath);
+    const templatePath = join(input.projectRoot, '.peaks', 'project-scan', 'security-template.md');
+    const templatePresent = existsSync(templatePath);
+    if (!handoffPresent) {
+        return {
+            state: 'handoff-missing',
+            handoffPresent: false,
+            templatePresent,
+            warnings: [`peaks-prd handoff not found at ${handoffPath}`],
+            nextActions: [
+                'Run peaks-prd handoff init to produce a sha256-locked handoff before running peaks security-audit.',
+                'Until the handoff exists, peaks-security-audit cannot start (gate fail).'
+            ]
+        };
+    }
+    if (!templatePresent) {
+        return {
+            state: 'template-missing',
+            handoffPresent: true,
+            templatePresent: false,
+            warnings: [`security-template.md not found at ${templatePath}`],
+            nextActions: [
+                'Run peaks project template init to bootstrap the 3 audit templates (security-template, perf-template, audit-output-schema).',
+                'Until the template exists, peaks-security-audit cannot start (gate fail).'
+            ]
+        };
+    }
+    if (input.dispatchError !== undefined) {
+        return {
+            state: 'dispatch-failed',
+            handoffPresent: true,
+            templatePresent: true,
+            warnings: [
+                `Audit dispatch failed: ${input.dispatchError instanceof Error ? input.dispatchError.message : String(input.dispatchError)}`
+            ],
+            nextActions: [
+                'Inspect the audit prompt template for the failure cause.',
+                'peaks-security-audit falls back to inline LLM review (degradation note: security-audit-dispatch-failed).'
+            ]
+        };
+    }
+    if (input.envelope !== undefined && !isSecurityAuditEnvelope(input.envelope)) {
+        return {
+            state: 'envelope-malformed',
+            handoffPresent: true,
+            templatePresent: true,
+            warnings: [
+                'Security-audit returned a value that failed envelope validation (expected { verdict, violations, summary }).'
+            ],
+            nextActions: [
+                'Verify the security-audit skill prompt matches PRD AC-2.x output shape.',
+                'If the envelope shape is intentionally different, file a bug at the peaks-loop repo.'
+            ]
+        };
+    }
+    return {
+        state: 'ready',
+        handoffPresent: true,
+        templatePresent: true,
+        warnings,
+        nextActions
+    };
+}
+/**
+ * Render a SecurityAuditEnvelope to the canonical audit artifact body
+ * (markdown). Mirrors `adaptEccEnvelopeToRdCodeReview` in ecc-bridge.ts:
+ * produce a markdown body with all required sections, ready to write
+ * to `.peaks/_runtime/<sid>/audit/security-<rid>.md`.
+ */
+export function renderSecurityAuditArtifact(env, opts) {
+    const counts = {};
+    for (const v of env.violations) {
+        counts[v.severity] = (counts[v.severity] ?? 0) + 1;
+    }
+    const criticalCount = counts['CRITICAL'] ?? 0;
+    const findingsBullets = env.violations.length === 0
+        ? '- (none)'
+        : env.violations.map((v) => `- [${v.severity}] ${v.dimension} @ ${v.file}:${v.line} — ${v.hint}`).join('\n');
+    const requiredFixes = env.violations.length === 0
+        ? ''
+        : [
+            '## Required fixes',
+            '',
+            ...env.violations.map((v) => `- [${v.severity}] ${v.file}:${v.line} — ${v.hint}`),
+            ''
+        ].join('\n');
+    const body = [
+        '## Summary',
+        '',
+        env.summary,
+        '',
+        '## Threat model coverage',
+        '',
+        `audited at: ${opts.generatedAt}`,
+        `verdict: ${env.verdict}`,
+        `handoffHash: ${opts.handoffHash}`,
+        '',
+        '## Findings',
+        '',
+        findingsBullets,
+        '',
+        requiredFixes,
+        '## Verdict',
+        '',
+        `verdict: ${env.verdict}`,
+        `CRITICAL: ${criticalCount}`,
+        ''
+    ].filter((s) => s.length > 0).join('\n');
+    return {
+        body,
+        violationsCount: env.violations.length,
+        verdict: env.verdict,
+    };
+}
+/**
+ * Write the rendered audit artifact to
+ * `.peaks/_runtime/<sid>/audit/security-<rid>.md`.
+ *
+ * Atomic write (tmp + rename) to avoid partial writes on crash.
+ * Returns the absolute path on success.
+ */
+export function writeSecurityAuditArtifact(projectRoot, sessionId, rid, body) {
+    const targetDir = join(projectRoot, '.peaks', '_runtime', sessionId, 'audit');
+    mkdirSync(targetDir, { recursive: true });
+    const targetPath = join(targetDir, `security-${rid}.md`);
+    // tmp + rename for atomicity
+    const tmpPath = `${targetPath}.tmp`;
+    writeFileSync(tmpPath, body, 'utf8');
+    // Sync rename: on Windows, fs.renameSync overwrites if target exists (Node 22+)
+    const { renameSync } = require('node:fs');
+    renameSync(tmpPath, targetPath);
+    return targetPath;
+}
+/**
+ * Convenience: run `detectSecurityAudit` + `renderSecurityAuditArtifact`
+ * + `writeSecurityAuditArtifact` in one call.
+ *
+ * Returns `{ detect, artifactPath, violationsCount, verdict }` or
+ * `{ detect, artifactPath: null, ... }` when not ready.
+ */
+export function runSecurityAudit(input) {
+    const detect = detectSecurityAudit({
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId,
+        ...(input.dispatchError !== undefined ? { dispatchError: input.dispatchError } : {}),
+        ...(input.envelope !== undefined ? { envelope: input.envelope } : {})
+    });
+    if (detect.state !== 'ready' || input.envelope === undefined) {
+        return { detect, artifactPath: null, violationsCount: 0, verdict: null };
+    }
+    // detect.state === 'ready' implies input.envelope passed isSecurityAuditEnvelope.
+    const env = input.envelope;
+    const handoffPath = join(input.projectRoot, '.peaks', '_runtime', input.sessionId, 'prd', 'handoff.md');
+    const verified = readAndVerifyHandoff(handoffPath, input.projectRoot);
+    const handoffHash = verified?.frontmatter.sha256 ?? 'unknown';
+    const rendered = renderSecurityAuditArtifact(env, {
+        rid: input.rid,
+        handoffHash,
+        generatedAt: input.generatedAt
+    });
+    const artifactPath = writeSecurityAuditArtifact(input.projectRoot, input.sessionId, input.rid, rendered.body);
+    return {
+        detect,
+        artifactPath,
+        violationsCount: rendered.violationsCount,
+        verdict: rendered.verdict
+    };
+}

package/dist/services/autonomous-swarm/autonomous-swarm-service.d.ts

@@ -0,0 +1,127 @@
+/**
+ * autonomous-swarm-service — slice rid-014.
+ *
+ * Purpose:
+ *   Build a dry-run-only autonomous RD swarm planner that turns a
+ *   user-supplied goal + change-id + mode into a *resumable* plan:
+ *   goal package (done / resume conditions), capability reuse list,
+ *   checkpoint queue, worker-queue placeholders (no spawn), evidence
+ *   requirements, and resume instructions.
+ *
+ * Reuse (per rid-014 plan §1):
+ *   - `validateChangeId` + `planArtifactPath` + `buildWorkspaceUnavailable`
+ *     from `src/services/openspec/artifact-boundary.ts` (rid-009).
+ *   - `getTechStatus` from `src/services/tech/tech-service.ts` (rid-012).
+ *   - `planRdSwarmGraph` shape from `src/services/rd-swarm/rd-swarm-service.ts`
+ *     (rid-013) — composed as the workerQueue feed.
+ *
+ * Style:
+ *   - Named function exports — matches `rd-swarm-service.ts` + `artifact-boundary.ts`.
+ *   - Hand-rolled `Result<T, E>` unions — no `neverthrow` dep.
+ *   - Pure path math + intentional capability fs reads (no side effects).
+ *   - No real workers, no MCP install, no settings mutation, no target-repo edit.
+ *
+ * Hard ban:
+ *   - MUST NOT install / invoke / import any external skill or MCP server.
+ *   - MUST NOT launch workers or mutate the target repo.
+ *   - MUST NOT touch `src/services/openspec/artifact-boundary.ts`,
+ *     `src/services/tech/`, or `src/services/rd-swarm/`.
+ */
+import { buildWorkspaceUnavailable, type Result, type BoundaryError } from '../openspec/artifact-boundary.js';
+export type AutonomousMode = 'code' | 'team';
+export type GoalCommandMarker = {
+    marker: '/goal';
+    nonDurable: true;
+    notes: string;
+};
+export type AutonomousGoalPackage = {
+    changeId: string;
+    goal: string;
+    mode: AutonomousMode;
+    autonomyMode: 'dry-run';
+    nonGoals: string[];
+    doneCondition: string;
+    resumeCondition: string;
+    riskNotes: string[];
+    goalCommand?: GoalCommandMarker;
+};
+export type CheckpointStatus = 'pending' | 'verified' | 'failed';
+export type Checkpoint = {
+    id: string;
+    name: string;
+    evidencePath: string;
+    status: CheckpointStatus;
+};
+export type WorkerQueueEntry = {
+    taskId: string;
+    wave: string;
+    status: 'planned' | 'running' | 'done' | 'blocked';
+    briefPath: string;
+    dependsOn: string[];
+};
+export type EvidenceRequirement = {
+    id: string;
+    kind: 'validation-report' | 'coverage-report' | 'reducer-report';
+    path: string;
+    required: boolean;
+};
+export type CapabilityEntry = {
+    source: string;
+    purpose: string;
+    trustLevel: 'internal' | 'external' | 'unknown';
+    activation: string;
+    risk: string;
+};
+export type CapabilityReuseResult = {
+    entries: CapabilityEntry[];
+    truncated: boolean;
+    warnings: string[];
+};
+export type ResumeInstructions = {
+    summary: string;
+    steps: string[];
+    checkpointStates: Array<{
+        id: string;
+        status: CheckpointStatus;
+    }>;
+};
+export type AutonomousRdPlan = {
+    changeId: string;
+    goal: string;
+    mode: AutonomousMode;
+    autonomyMode: 'dry-run';
+    available: boolean;
+    goalPackage: AutonomousGoalPackage;
+    capabilityReuse: CapabilityReuseResult;
+    checkpoints: Checkpoint[];
+    workerQueue: WorkerQueueEntry[];
+    evidence: EvidenceRequirement[];
+    artifactRoot: string;
+    gateStatus: {
+        techApprovalRequired: boolean;
+        techStatus: string;
+        skipReason?: string;
+    };
+    blockedReasons: string[];
+    nextActions: string[];
+    resumeInstructions: ResumeInstructions;
+};
+export type BuildAutonomousGoalPackageInput = {
+    changeId: string;
+    goal: string;
+    mode: AutonomousMode;
+    maxWorkers: number;
+    dryRun: true;
+    workspaceRoot: string;
+};
+export type PlanAutonomousRdSwarmInput = BuildAutonomousGoalPackageInput & {
+    requiresTechApproval?: boolean;
+};
+export declare function buildAutonomousGoalPackage(input: BuildAutonomousGoalPackageInput): AutonomousGoalPackage;
+export declare function planCapabilityReuse(input: {
+    workspaceRoot: string;
+}): CapabilityReuseResult;
+export declare function buildResumeInstructions(plan: AutonomousRdPlan): ResumeInstructions;
+export declare function planAutonomousRdSwarm(input: PlanAutonomousRdSwarmInput): AutonomousRdPlan;
+export type { Result, BoundaryError };
+export { buildWorkspaceUnavailable };