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

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/classify/classify-service.d.ts

@@ -0,0 +1,42 @@
+/**
+ * L1a task classification service.
+ *
+ * Spec: docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §4
+ *
+ * Hybrid mechanism: signal-based heuristic + user override + audit log.
+ *
+ * Signal rules (per the spec, conservative defaults):
+ *   - filesChanged >= feature_threshold_files OR linesChanged >= feature_threshold_lines
+ *     AND touchesDependencies → 'migration'
+ *   - touchesMigrationScripts → 'migration'
+ *   - isPureRefactor AND linesChanged > 50 → 'refactor'
+ *   - filesChanged >= feature_threshold_files OR linesChanged >= feature_threshold_lines
+ *     → 'feature'
+ *   - keywords contains 'fix' / 'bug' / 'broken' → 'bug'
+ *   - filesChanged <= 3 AND linesChanged <= 5 → 'typo'
+ *   - default → 'bug' (mid-low)
+ *
+ * Conservatism:
+ *   - 'strict' promotes the result by one level
+ *   - 'lax' demotes the result by one level
+ *   - 'default' leaves it as-is
+ *
+ * Override (the user can force a level):
+ *   - `peaks classify override --level <level> --reason "<text>"` writes
+ *     to the audit log; cannot be downgraded (per spec: downgrade
+ *     is always refused)
+ */
+import { type ClassifyResult, type ClassifySignals, type TaskLevel } from './classify-types.js';
+import type { ClassifyConservatism } from '../preferences/preferences-types.js';
+export interface ClassifyInput {
+    readonly signals: ClassifySignals;
+    readonly conservatism: ClassifyConservatism;
+    /** When set, force the level (bypasses the heuristic). */
+    readonly override?: {
+        level: TaskLevel;
+        reason: string;
+    };
+    /** Optional clock for testability. */
+    readonly clock?: () => string;
+}
+export declare function classifyTask(input: ClassifyInput, featureThresholdFiles?: number, featureThresholdLines?: number): ClassifyResult;

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

@@ -0,0 +1,122 @@
+/**
+ * L1a task classification service.
+ *
+ * Spec: docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §4
+ *
+ * Hybrid mechanism: signal-based heuristic + user override + audit log.
+ *
+ * Signal rules (per the spec, conservative defaults):
+ *   - filesChanged >= feature_threshold_files OR linesChanged >= feature_threshold_lines
+ *     AND touchesDependencies → 'migration'
+ *   - touchesMigrationScripts → 'migration'
+ *   - isPureRefactor AND linesChanged > 50 → 'refactor'
+ *   - filesChanged >= feature_threshold_files OR linesChanged >= feature_threshold_lines
+ *     → 'feature'
+ *   - keywords contains 'fix' / 'bug' / 'broken' → 'bug'
+ *   - filesChanged <= 3 AND linesChanged <= 5 → 'typo'
+ *   - default → 'bug' (mid-low)
+ *
+ * Conservatism:
+ *   - 'strict' promotes the result by one level
+ *   - 'lax' demotes the result by one level
+ *   - 'default' leaves it as-is
+ *
+ * Override (the user can force a level):
+ *   - `peaks classify override --level <level> --reason "<text>"` writes
+ *     to the audit log; cannot be downgraded (per spec: downgrade
+ *     is always refused)
+ */
+import { TASK_LEVELS, TASK_LEVEL_GATE_SETS, TASK_LEVEL_ORDER, } from './classify-types.js';
+const FEATURE_KEYWORDS = ['fix', 'bug', 'broken', 'crash', 'regression'];
+const MIGRATION_KEYWORDS = ['migrate', 'migration', 'codemod', 'backfill', 'schema', 'bump'];
+const REFACTOR_KEYWORDS = ['refactor', 'rename', 'extract', 'inline', 'cleanup'];
+function detectLevel(signals, featureThresholdFiles, featureThresholdLines) {
+    // 1. Migration takes priority.
+    if (signals.touchesMigrationScripts)
+        return 'migration';
+    const lower = signals.keywords.map((k) => k.toLowerCase());
+    if (signals.touchesDependencies && lower.some((k) => MIGRATION_KEYWORDS.includes(k))) {
+        return 'migration';
+    }
+    if (signals.touchesDependencies)
+        return 'migration';
+    if (signals.touchesDependencies === false && signals.isPureRefactor && signals.linesChanged > 50) {
+        return 'refactor';
+    }
+    if (lower.some((k) => REFACTOR_KEYWORDS.includes(k)) && signals.isPureRefactor) {
+        return 'refactor';
+    }
+    // 2. Feature threshold.
+    if (signals.filesChanged >= featureThresholdFiles || signals.linesChanged >= featureThresholdLines) {
+        return 'feature';
+    }
+    // 3. Bug-fix keywords.
+    if (lower.some((k) => FEATURE_KEYWORDS.includes(k))) {
+        return 'bug';
+    }
+    // 4. Small diff: typo.
+    if (signals.filesChanged <= 3 && signals.linesChanged <= 5) {
+        return 'typo';
+    }
+    // 5. Default: bug (mid-low).
+    return 'bug';
+}
+function applyConservatism(level, conservatism) {
+    if (conservatism === 'default')
+        return level;
+    const order = TASK_LEVEL_ORDER[level];
+    const index = TASK_LEVELS.indexOf(level);
+    if (conservatism === 'strict') {
+        const next = Math.min(index + 1, TASK_LEVELS.length - 1);
+        return TASK_LEVELS[next] ?? level;
+    }
+    // 'lax'
+    const prev = Math.max(index - 1, 0);
+    return TASK_LEVELS[prev] ?? level;
+}
+function buildRationale(signals, level, overrideApplied) {
+    if (overrideApplied)
+        return `level forced via override`;
+    const parts = [];
+    parts.push(`${signals.filesChanged} file(s), ${signals.linesChanged} line(s)`);
+    if (signals.touchesMigrationScripts)
+        parts.push('touches migration scripts');
+    if (signals.touchesDependencies)
+        parts.push('touches dependencies');
+    if (signals.isPureRefactor)
+        parts.push('pure refactor (no behavior change)');
+    if (signals.keywords.length > 0)
+        parts.push(`keywords: ${signals.keywords.join(', ')}`);
+    parts.push(`→ ${level}`);
+    return parts.join('; ');
+}
+export function classifyTask(input, featureThresholdFiles = 10, featureThresholdLines = 100) {
+    const heuristicLevel = detectLevel(input.signals, featureThresholdFiles, featureThresholdLines);
+    let finalLevel;
+    let overrideApplied = false;
+    if (input.override !== undefined) {
+        finalLevel = input.override.level;
+        overrideApplied = true;
+    }
+    else {
+        finalLevel = applyConservatism(heuristicLevel, input.conservatism);
+    }
+    const gateSet = TASK_LEVEL_GATE_SETS[finalLevel];
+    const rationale = buildRationale(input.signals, finalLevel, overrideApplied);
+    const timestamp = (input.clock ?? (() => new Date().toISOString()))();
+    const audit = {
+        timestamp,
+        inputs: input.signals,
+        output: finalLevel,
+        conservatism: input.conservatism,
+        overrideApplied,
+        reason: input.override?.reason ?? rationale,
+    };
+    return {
+        level: finalLevel,
+        signals: input.signals,
+        rationale,
+        gateSet,
+        audit,
+    };
+}

package/dist/services/classify/classify-types.d.ts

@@ -0,0 +1,79 @@
+/**
+ * L1a task classification — types and per-level gate sets.
+ *
+ * Spec: docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §4
+ *
+ * Five task levels: typo / bug / feature / refactor / migration. Each
+ * level has a gate set (the "配套 gate set" — L1b) that the slice
+ * checker runs. Higher levels = more gates = slower but safer.
+ *
+ * The classification is a HYBRID mechanism:
+ *   1. Heuristic signal (file count, line count, keyword presence)
+ *   2. User override (`peaks classify override --level <level> --reason "<>"`)
+ *   3. Audit log of every classification (forensics)
+ *
+ * Conservatism modifier (per .peaks/preferences.json:classifyConservatism):
+ *   - 'default' — use the signal thresholds as-is
+ *   - 'strict'  — always upgrade to next level
+ *   - 'lax'     — always downgrade to previous level
+ */
+export type TaskLevel = 'typo' | 'bug' | 'feature' | 'refactor' | 'migration';
+export declare const TASK_LEVELS: readonly TaskLevel[];
+/** Numeric ordering for "next level" / "previous level" promotion. */
+export declare const TASK_LEVEL_ORDER: Readonly<Record<TaskLevel, number>>;
+export interface ClassifySignals {
+    /** Number of files changed in the diff. */
+    readonly filesChanged: number;
+    /** Number of lines added + removed in the diff. */
+    readonly linesChanged: number;
+    /** Whether the diff includes dependency files (package.json, etc.). */
+    readonly touchesDependencies: boolean;
+    /** Whether the diff includes migration scripts / codemods. */
+    readonly touchesMigrationScripts: boolean;
+    /** Whether the diff is mostly renames / formatting / comment changes. */
+    readonly isPureRefactor: boolean;
+    /** Keywords found in the change description or commit message. */
+    readonly keywords: readonly string[];
+}
+/** The gate set that runs for a given task level (L1b). */
+export interface TaskLevelGateSet {
+    readonly level: TaskLevel;
+    /** Human-readable description. */
+    readonly description: string;
+    /** Which slice-check stages run at this level. */
+    readonly stages: readonly string[];
+    /** Whether PRD is required at this level. */
+    readonly requiresPrd: boolean;
+    /** Whether a tech-doc is required at this level. */
+    readonly requiresTechDoc: boolean;
+    /** Whether a code review is required at this level. */
+    readonly requiresCodeReview: boolean;
+    /** Whether a security review is required at this level. */
+    readonly requiresSecurityReview: boolean;
+    /** Whether a perf baseline is required at this level. */
+    readonly requiresPerfBaseline: boolean;
+    /** Whether the slice must transition through QA handoff. */
+    readonly requiresQaHandoff: boolean;
+    /** Whether the user must explicitly confirm destructive paths. */
+    readonly requiresDestructiveConfirmation: boolean;
+}
+export declare const TASK_LEVEL_GATE_SETS: Readonly<Record<TaskLevel, TaskLevelGateSet>>;
+/** Result of a classification (deterministic given signals + conservatism). */
+export interface ClassifyResult {
+    readonly level: TaskLevel;
+    readonly signals: ClassifySignals;
+    /** Why this level was chosen (1-2 sentence explanation). */
+    readonly rationale: string;
+    /** The gate set that will run for this level. */
+    readonly gateSet: TaskLevelGateSet;
+    /** The audit log entry (every classification is logged). */
+    readonly audit: ClassifyAuditEntry;
+}
+export interface ClassifyAuditEntry {
+    readonly timestamp: string;
+    readonly inputs: ClassifySignals;
+    readonly output: TaskLevel;
+    readonly conservatism: 'default' | 'strict' | 'lax';
+    readonly overrideApplied: boolean;
+    readonly reason: string;
+}

package/dist/services/classify/classify-types.js

@@ -0,0 +1,90 @@
+/**
+ * L1a task classification — types and per-level gate sets.
+ *
+ * Spec: docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §4
+ *
+ * Five task levels: typo / bug / feature / refactor / migration. Each
+ * level has a gate set (the "配套 gate set" — L1b) that the slice
+ * checker runs. Higher levels = more gates = slower but safer.
+ *
+ * The classification is a HYBRID mechanism:
+ *   1. Heuristic signal (file count, line count, keyword presence)
+ *   2. User override (`peaks classify override --level <level> --reason "<>"`)
+ *   3. Audit log of every classification (forensics)
+ *
+ * Conservatism modifier (per .peaks/preferences.json:classifyConservatism):
+ *   - 'default' — use the signal thresholds as-is
+ *   - 'strict'  — always upgrade to next level
+ *   - 'lax'     — always downgrade to previous level
+ */
+export const TASK_LEVELS = ['typo', 'bug', 'feature', 'refactor', 'migration'];
+/** Numeric ordering for "next level" / "previous level" promotion. */
+export const TASK_LEVEL_ORDER = {
+    typo: 0,
+    bug: 1,
+    feature: 2,
+    refactor: 3,
+    migration: 4,
+};
+export const TASK_LEVEL_GATE_SETS = {
+    typo: {
+        level: 'typo',
+        description: 'Single-line fix: typo, comment, formatting. No new logic.',
+        stages: ['typecheck', 'lint'],
+        requiresPrd: false,
+        requiresTechDoc: false,
+        requiresCodeReview: false,
+        requiresSecurityReview: false,
+        requiresPerfBaseline: false,
+        requiresQaHandoff: false,
+        requiresDestructiveConfirmation: false,
+    },
+    bug: {
+        level: 'bug',
+        description: 'Bug fix: existing behavior wrong, patched in 1-3 files.',
+        stages: ['typecheck', 'unit-tests', 'lint'],
+        requiresPrd: false,
+        requiresTechDoc: false,
+        requiresCodeReview: true,
+        requiresSecurityReview: false,
+        requiresPerfBaseline: false,
+        requiresQaHandoff: false,
+        requiresDestructiveConfirmation: false,
+    },
+    feature: {
+        level: 'feature',
+        description: 'New feature: new behavior, new files, new tests.',
+        stages: ['typecheck', 'unit-tests', 'lint', 'review-fanout', 'gate-verify-pipeline'],
+        requiresPrd: true,
+        requiresTechDoc: true,
+        requiresCodeReview: true,
+        requiresSecurityReview: true,
+        requiresPerfBaseline: true,
+        requiresQaHandoff: true,
+        requiresDestructiveConfirmation: true,
+    },
+    refactor: {
+        level: 'refactor',
+        description: 'Refactor: behavior-preserving structural change.',
+        stages: ['typecheck', 'unit-tests', 'lint', 'review-fanout'],
+        requiresPrd: false,
+        requiresTechDoc: true,
+        requiresCodeReview: true,
+        requiresSecurityReview: true,
+        requiresPerfBaseline: false,
+        requiresQaHandoff: true,
+        requiresDestructiveConfirmation: false,
+    },
+    migration: {
+        level: 'migration',
+        description: 'Migration: codemod, schema change, data backfill, dependency upgrade.',
+        stages: ['typecheck', 'unit-tests', 'lint', 'review-fanout', 'gate-verify-pipeline', 'backward-compat'],
+        requiresPrd: true,
+        requiresTechDoc: true,
+        requiresCodeReview: true,
+        requiresSecurityReview: true,
+        requiresPerfBaseline: true,
+        requiresQaHandoff: true,
+        requiresDestructiveConfirmation: true,
+    },
+};