peaks-loop 4.0.0-beta → 4.0.0-beta.10

package/dist/services/artifacts/repair-cycle-service.js

@@ -0,0 +1,52 @@
+import { showRequestArtifact } from './request-artifact-service.js';
+const DEFAULT_MAX_CYCLES = 3;
+// Matches transition notes Code writes during repair routing.
+// Format example:
+//   - transition note (2026-05-25T08:00:00.000Z): QA return-to-rd cycle 1: failing acceptance items A, B
+//   - transition note (2026-05-25T09:00:00.000Z): QA cycle 2: regression in module X
+const REPAIR_NOTE_PATTERN = /-\s*transition note\s*\(([^)]+)\)\s*:\s*(?:QA(?:\s+return-to-rd)?\s+cycle\s+(\d+))\s*:?\s*(.*?)$/i;
+export async function getRepairCycleStatus(options) {
+    const showOptions = {
+        projectRoot: options.projectRoot,
+        role: 'rd',
+        requestId: options.requestId
+    };
+    if (options.sessionId !== undefined) {
+        showOptions.sessionId = options.sessionId;
+    }
+    const artifact = await showRequestArtifact(showOptions);
+    if (artifact === null) {
+        return null;
+    }
+    const maxCycles = options.maxCycles ?? DEFAULT_MAX_CYCLES;
+    const lines = artifact.content.split(/\r?\n/);
+    const entries = [];
+    for (const rawLine of lines) {
+        const match = REPAIR_NOTE_PATTERN.exec(rawLine);
+        if (match === null)
+            continue;
+        const [, timestamp, cycleStr, reason] = match;
+        if (timestamp === undefined || cycleStr === undefined)
+            continue;
+        const cycle = Number(cycleStr);
+        if (!Number.isFinite(cycle) || cycle < 1)
+            continue;
+        entries.push({ cycle, timestamp, reason: (reason ?? '').trim() });
+    }
+    // Distinct cycle numbers — repair loop may write the same cycle note multiple times.
+    const distinct = new Set(entries.map((entry) => entry.cycle));
+    const cycleCount = distinct.size;
+    const remaining = Math.max(0, maxCycles - cycleCount);
+    const atCap = cycleCount >= maxCycles;
+    return {
+        requestId: options.requestId,
+        sessionId: artifact.sessionId,
+        path: artifact.path,
+        cycleCount,
+        maxCycles,
+        remaining,
+        atCap,
+        blocked: atCap,
+        entries
+    };
+}

package/dist/services/audit/enforcers/active-skill-resolver.d.ts

@@ -0,0 +1,29 @@
+/**
+ * active-skill-resolver — utility for hook enforcers.
+ *
+ * Resolves the active peak skill name for the current session, so hook
+ * enforcers (e.g. code-ban) can decide whether to fire.
+ *
+ * Per `src/services/session/caller-id-types.ts`: the active-skill file is
+ * at `.peaks/_runtime/<peakSessionId>/active-skill-<callerId>.json`.
+ *
+ * Resolution order (graceful degradation — never throws):
+ *   1. PEAKS_ACTIVE_SKILL env var (explicit override, used by tests)
+ *   2. .peaks/_runtime/<sid>/active-skill-<callerId>.json for each caller
+ *      bound to the current peak session
+ *   3. null (caller did not set a skill; enforcers can decide to skip)
+ */
+export interface ActiveSkillResolution {
+    readonly skill: string | null;
+    readonly callerId: string | null;
+    readonly sessionId: string | null;
+    readonly source: 'env' | 'file' | 'none';
+}
+/**
+ * Resolve the active peak skill for the current hook invocation.
+ *
+ * Reads PEAKS_ACTIVE_SKILL first (test override), then walks
+ * `.peaks/_runtime/<sid>/` for any `active-skill-*.json` file. Returns
+ * the first match.
+ */
+export declare function resolveActiveSkillForCaller(projectRoot: string): ActiveSkillResolution;

package/dist/services/audit/enforcers/active-skill-resolver.js

@@ -0,0 +1,71 @@
+/**
+ * active-skill-resolver — utility for hook enforcers.
+ *
+ * Resolves the active peak skill name for the current session, so hook
+ * enforcers (e.g. code-ban) can decide whether to fire.
+ *
+ * Per `src/services/session/caller-id-types.ts`: the active-skill file is
+ * at `.peaks/_runtime/<peakSessionId>/active-skill-<callerId>.json`.
+ *
+ * Resolution order (graceful degradation — never throws):
+ *   1. PEAKS_ACTIVE_SKILL env var (explicit override, used by tests)
+ *   2. .peaks/_runtime/<sid>/active-skill-<callerId>.json for each caller
+ *      bound to the current peak session
+ *   3. null (caller did not set a skill; enforcers can decide to skip)
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getSessionIdCanonical } from '../../session/session-manager.js';
+import { getSessionDir } from '../../session/getSessionDir.js';
+const ACTIVE_SKILL_PREFIX = 'active-skill-';
+/**
+ * Resolve the active peak skill for the current hook invocation.
+ *
+ * Reads PEAKS_ACTIVE_SKILL first (test override), then walks
+ * `.peaks/_runtime/<sid>/` for any `active-skill-*.json` file. Returns
+ * the first match.
+ */
+export function resolveActiveSkillForCaller(projectRoot) {
+    const envOverride = process.env.PEAKS_ACTIVE_SKILL;
+    if (typeof envOverride === 'string' && envOverride.length > 0) {
+        return { skill: envOverride, callerId: null, sessionId: null, source: 'env' };
+    }
+    let sessionId = null;
+    try {
+        sessionId = getSessionIdCanonical(projectRoot);
+    }
+    catch {
+        return { skill: null, callerId: null, sessionId: null, source: 'none' };
+    }
+    if (sessionId === null) {
+        return { skill: null, callerId: null, sessionId: null, source: 'none' };
+    }
+    const sessionDir = getSessionDir(projectRoot, sessionId);
+    if (!existsSync(sessionDir)) {
+        return { skill: null, callerId: null, sessionId: sessionId, source: 'none' };
+    }
+    let entries;
+    try {
+        entries = readdirSync(sessionDir);
+    }
+    catch {
+        return { skill: null, callerId: null, sessionId: sessionId, source: 'none' };
+    }
+    for (const entry of entries) {
+        if (!entry.startsWith(ACTIVE_SKILL_PREFIX) || !entry.endsWith('.json'))
+            continue;
+        const callerId = entry.slice(ACTIVE_SKILL_PREFIX.length, -'.json'.length);
+        const filePath = join(sessionDir, entry);
+        try {
+            const raw = readFileSync(filePath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.skill === 'string' && parsed.skill.length > 0) {
+                return { skill: parsed.skill, callerId, sessionId, source: 'file' };
+            }
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            // skip malformed file
+        }
+    }
+    return { skill: null, callerId: null, sessionId, source: 'none' };
+}

package/dist/services/audit/enforcers/code-ban.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Code-commit-ban enforcer — PreToolUse Bash guard.
+ *
+ * Per L2 redesign §5.4. Deny `git commit` or `git apply` invocations from
+ * a peaks-* skill. The Code Commit Ban Red Line says peaks-code / peaks-rd
+ * are orchestrators, not implementers; the actual `git commit` step must
+ * go through `peaks request transition`, which itself enforces spec-locked
+ * + tech-doc-presence.
+ *
+ * Trust red line (per `gate-enforcement-hook.md`): if the registry or
+ * manifest read fails, the hook must fail-OPEN (warn + allow). The LLM is
+ * never bricked by a peaks bug.
+ */
+export interface CodeBanInput {
+    readonly skill: string;
+    readonly command: string;
+}
+export interface CodeBanResult {
+    readonly denied: boolean;
+    readonly reason: string;
+}
+export declare function isCodeCommit(skill: string, command: string): boolean;
+export declare function evaluateCodeBan(input: CodeBanInput): CodeBanResult;

package/dist/services/audit/enforcers/code-ban.js

@@ -0,0 +1,27 @@
+/**
+ * Code-commit-ban enforcer — PreToolUse Bash guard.
+ *
+ * Per L2 redesign §5.4. Deny `git commit` or `git apply` invocations from
+ * a peaks-* skill. The Code Commit Ban Red Line says peaks-code / peaks-rd
+ * are orchestrators, not implementers; the actual `git commit` step must
+ * go through `peaks request transition`, which itself enforces spec-locked
+ * + tech-doc-presence.
+ *
+ * Trust red line (per `gate-enforcement-hook.md`): if the registry or
+ * manifest read fails, the hook must fail-OPEN (warn + allow). The LLM is
+ * never bricked by a peaks bug.
+ */
+const COMMIT_APPLY_PATTERN = /^\s*git\s+(commit|apply)\b/;
+const DENY_REASON = 'Code Commit Ban Red Line: peaks-* skills must go through peaks-code / peaks-rd. ' +
+    'Use `peaks request transition` instead of `git commit` / `git apply` directly.';
+export function isCodeCommit(skill, command) {
+    if (!skill.startsWith('peaks-'))
+        return false;
+    return COMMIT_APPLY_PATTERN.test(command);
+}
+export function evaluateCodeBan(input) {
+    if (isCodeCommit(input.skill, input.command)) {
+        return { denied: true, reason: DENY_REASON };
+    }
+    return { denied: false, reason: '' };
+}

package/dist/services/audit/red-line-catalog.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Red-line catalog — the 5 P0 red lines shipped in L2.1, plus the marker
+ * patterns that the classifier uses to discover them in markdown.
+ *
+ * The catalog is hand-maintained. New enforcers (L2.2/2.3/2.4) add entries
+ * here and the backing-detector picks them up automatically.
+ */
+import type { RedLineMarker } from './types.js';
+export interface RedLineCatalogEntry {
+    /** Stable id, e.g. "rl-code-ban-001". */
+    readonly id: string;
+    readonly rule: string;
+    /** Markers that, if found near the rule's text, identify this red line. */
+    readonly markers: readonly RedLineMarker[];
+    /** Substring(s) that must appear in the surrounding ±2 lines. */
+    readonly phrases: readonly string[];
+    /** Relative path to the enforcement file (or null when prose-only). */
+    readonly enforcerRef: string | null;
+}
+export declare const RED_LINE_CATALOG: readonly RedLineCatalogEntry[];
+/**
+ * Catalog entries for enforcers whose source code is shipped in this slice
+ * but whose integration is deferred to subsequent slices (L2.1.1 or later).
+ *
+ * The backing-detector downgrades these to `prose-only` at runtime because
+ * the integration seam is missing. When the integration lands, the entry
+ * is removed from this set in a single-line follow-up commit.
+ *
+ * L2.1 final state: Tasks 5 (code-ban) + 6 (no-root-pollution) are
+ * wired into peaks hook handle (Tasks 1-4: framework + 3 enforcers also
+ * integrated). Tasks 3 (tech-doc-presence) and 4 (mock-placement) are
+ * deferred — their request-transition / slice-check integrations are
+ * tracked separately.
+ */
+export declare const DEFERRED_ENFORCERS: ReadonlySet<string>;
+/**
+ * A red line's catalog id is the join key. If a discovered red line in a
+ * markdown file matches no catalog entry, it stays as `prose-only`.
+ *
+ * Match policy: phrase-only for identity. Markers (MANDATORY / BLOCKING /
+ * MUST NOT / RED LINE) are too generic to disambiguate — every catalog
+ * entry shares the same marker set, so a marker-only match would always
+ * return the first catalog entry regardless of the rule.
+ *
+ * Deferred enforcers (Tasks 4-6 integration pending) are matched by
+ * phrase but tagged with enforcerRef=null so the backing-detector
+ * downgrades them to prose-only at runtime. They are NOT removed from
+ * the catalog so future integration commits can re-tag them with a
+ * single source-of-truth change.
+ */
+export declare function findCatalogEntry(rule: string, _markers: readonly RedLineMarker[]): RedLineCatalogEntry | null;

package/dist/services/audit/red-line-catalog.js

@@ -0,0 +1,195 @@
+/**
+ * Red-line catalog — the 5 P0 red lines shipped in L2.1, plus the marker
+ * patterns that the classifier uses to discover them in markdown.
+ *
+ * The catalog is hand-maintained. New enforcers (L2.2/2.3/2.4) add entries
+ * here and the backing-detector picks them up automatically.
+ */
+import { RED_LINE_CATALOG_P2_A } from './red-line-catalog-p2-a.js';
+import { RED_LINE_CATALOG_P2_B } from './red-line-catalog-p2-b.js';
+export const RED_LINE_CATALOG = [
+    {
+        id: 'rl-code-ban-001',
+        rule: 'Code Commit Ban',
+        markers: ['BLOCKING', 'MANDATORY'],
+        phrases: [
+            'peaks-code',
+            'orchestrator, NOT an implementer',
+            'code',
+        ],
+        enforcerRef: 'src/services/audit/enforcers/code-ban.ts',
+    },
+    {
+        id: 'rl-no-root-pollution-001',
+        rule: 'No Root Pollution',
+        markers: ['MANDATORY', 'MUST NOT', 'RED LINE'],
+        phrases: [
+            'root pollution',
+            'must not write to the project root',
+            'no root',
+        ],
+        enforcerRef: 'src/services/audit/enforcers/no-root-pollution.ts',
+    },
+    {
+        id: 'rl-sub-agent-sid-001',
+        rule: 'Sub-Agent SID Isolation',
+        markers: ['MANDATORY', 'BLOCKING'],
+        phrases: [
+            'sub-agent',
+            'session id',
+            'sub-agent session sharing',
+            'one conversation = one sid',
+        ],
+        enforcerRef: 'src/services/audit/enforcers/sub-agent-sid.ts',
+    },
+    {
+        id: 'rl-mock-placement-001',
+        rule: 'Mock Data Placement',
+        markers: ['MUST NOT', 'MANDATORY'],
+        phrases: [
+            'mock data',
+            'mock placement',
+            'inline mock',
+            'fixture placement',
+        ],
+        enforcerRef: 'src/services/audit/enforcers/mock-placement.ts',
+    },
+    // === Slice L2.2 P1 — 10 P1 red lines across 5 categories ===
+    // Each catalog entry has a phrase that distinguishes it from P0; the
+    // backing-detector + DEFERRED_ENFORCERS mechanism handles the rest.
+    {
+        id: 'rl-resume-detection-001',
+        rule: 'Resume Detection: Session Binding',
+        markers: ['MANDATORY', 'BLOCKING'],
+        phrases: ['resume detection', 'session binding', 'resume session', 'resume from'],
+        enforcerRef: 'src/services/audit/enforcers/resume-detection.ts',
+    },
+    {
+        id: 'rl-resume-detection-002',
+        rule: 'Resume Detection: Request State',
+        markers: ['MANDATORY', 'BLOCKING'],
+        phrases: ['request state', 'resumable state', 'spec-locked', 'implemented', 'qa-handoff'],
+        enforcerRef: 'src/services/audit/enforcers/resume-detection.ts',
+    },
+    {
+        id: 'rl-prototype-fidelity-001',
+        rule: 'Prototype Fidelity: No Stub Markers',
+        markers: ['MUST NOT', 'MANDATORY'],
+        phrases: ['prototype fidelity', 'no stub', 'no TODO', 'no FIXME', 'no placeholder'],
+        enforcerRef: 'src/services/audit/enforcers/prototype-fidelity.ts',
+    },
+    {
+        id: 'rl-prototype-fidelity-002',
+        rule: 'Prototype Fidelity: Test Coverage',
+        markers: ['MANDATORY', 'RED LINE'],
+        phrases: ['prototype test', 'must have tests', 'test coverage', 'fidelity test'],
+        enforcerRef: 'src/services/audit/enforcers/prototype-fidelity.ts',
+    },
+    {
+        id: 'rl-design-draft-confirm-001',
+        rule: 'Design-Draft Confirm: Existence',
+        markers: ['MANDATORY', 'BLOCKING'],
+        phrases: ['design-draft', 'design draft', 'design-draft.md', 'design draft exists'],
+        enforcerRef: 'src/services/audit/enforcers/design-draft-confirm.ts',
+    },
+    {
+        id: 'rl-design-draft-confirm-002',
+        rule: 'Design-Draft Confirm: Confirmed State',
+        markers: ['MANDATORY', 'BLOCKING'],
+        phrases: ['design confirmed', 'design-draft confirmed', 'confirmed-by-user', 'user confirmed'],
+        enforcerRef: 'src/services/audit/enforcers/design-draft-confirm.ts',
+    },
+    {
+        id: 'rl-pre-rd-scan-001',
+        rule: 'Pre-RD Scan: Archetype Detected',
+        markers: ['MANDATORY', 'BLOCKING'],
+        phrases: ['pre-rd scan', 'project-scan', 'archetype detected', 'scan archetype'],
+        enforcerRef: 'src/services/audit/enforcers/pre-rd-scan.ts',
+    },
+    {
+        id: 'rl-pre-rd-scan-002',
+        rule: 'Pre-RD Scan: Standards Preflight',
+        markers: ['MANDATORY', 'BLOCKING'],
+        phrases: ['standards preflight', 'pre-rd standards', 'standards init', 'standards update'],
+        enforcerRef: 'src/services/audit/enforcers/pre-rd-scan.ts',
+    },
+    {
+        id: 'rl-login-gate-001',
+        rule: 'Login Gate: Destructive Path Confirmation',
+        markers: ['MANDATORY', 'BLOCKING', 'RED LINE'],
+        phrases: ['login gate', 'destructive path', 'uninstall', 'force-push', 'user confirmation required'],
+        enforcerRef: 'src/services/audit/enforcers/login-gate.ts',
+    },
+    {
+        id: 'rl-login-gate-002',
+        rule: 'Login Gate: Protected Path Auth',
+        markers: ['MANDATORY', 'BLOCKING'],
+        phrases: ['protected path', 'auth required', 'auth header', 'login required', 'session check'],
+        enforcerRef: 'src/services/audit/enforcers/login-gate.ts',
+    },
+    // Slice #6 L2.3 P2-a: 24 lint-style red-lines (Theme A: section
+    // structure, B: frontmatter shape, C: output style, D: CLI-back
+    // gaps, E: reference integrity, F: workflow-bound shape, G: catalog
+    // governance). Spread from the P2-a module so future P2-a edits
+    // are localized.
+    ...RED_LINE_CATALOG_P2_A,
+    // Slice #7 L2.4 P2-b: 25 lint-style red-lines for references/*.md
+    // (Themes H-P) + 4 audit-regression enforcers (Theme L). Spread
+    // from the P2-b module so future P2-b edits are localized.
+    ...RED_LINE_CATALOG_P2_B,
+];
+/**
+ * Catalog entries for enforcers whose source code is shipped in this slice
+ * but whose integration is deferred to subsequent slices (L2.1.1 or later).
+ *
+ * The backing-detector downgrades these to `prose-only` at runtime because
+ * the integration seam is missing. When the integration lands, the entry
+ * is removed from this set in a single-line follow-up commit.
+ *
+ * L2.1 final state: Tasks 5 (code-ban) + 6 (no-root-pollution) are
+ * wired into peaks hook handle (Tasks 1-4: framework + 3 enforcers also
+ * integrated). Tasks 3 (tech-doc-presence) and 4 (mock-placement) are
+ * deferred — their request-transition / slice-check integrations are
+ * tracked separately.
+ */
+// v2.14.0 Slice C Group G3: prose-only catalog governance reform.
+// All 8 previously-deferred enforcers are now integrated into the
+// red-lines audit pipeline (see red-lines-service.ts §3-7). The
+// backing-detector re-classifies these entries as cli-backed because
+// their enforcerRef file exists on disk. Rationale per id lives in
+// `.peaks/standards/catalog-governance/v2-14-classifications.md`.
+//
+// The 80 discovered-prose-only entries (`rl-discovered-...` ids) remain
+// in the catalog with `informational: true` and stay outside the
+// prose-only ratio (see prose-ratio-calculator.ts).
+export const DEFERRED_ENFORCERS = new Set([]);
+/**
+ * A red line's catalog id is the join key. If a discovered red line in a
+ * markdown file matches no catalog entry, it stays as `prose-only`.
+ *
+ * Match policy: phrase-only for identity. Markers (MANDATORY / BLOCKING /
+ * MUST NOT / RED LINE) are too generic to disambiguate — every catalog
+ * entry shares the same marker set, so a marker-only match would always
+ * return the first catalog entry regardless of the rule.
+ *
+ * Deferred enforcers (Tasks 4-6 integration pending) are matched by
+ * phrase but tagged with enforcerRef=null so the backing-detector
+ * downgrades them to prose-only at runtime. They are NOT removed from
+ * the catalog so future integration commits can re-tag them with a
+ * single source-of-truth change.
+ */
+export function findCatalogEntry(rule, _markers) {
+    const lower = rule.toLowerCase();
+    for (const entry of RED_LINE_CATALOG) {
+        const phraseHit = entry.phrases.some((p) => lower.includes(p.toLowerCase()));
+        if (phraseHit) {
+            if (DEFERRED_ENFORCERS.has(entry.id)) {
+                // Return a copy with enforcerRef nulled out, so backing-detector
+                // treats it as prose-only until the integration lands.
+                return { ...entry, enforcerRef: null };
+            }
+            return entry;
+        }
+    }
+    return null;
+}

package/dist/services/audit/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Red-line audit framework — types.
+ *
+ * Spec: docs/superpowers/specs/2026-06-11-peaks-loop-l1-l2-l3-redesign.md §5
+ * PRD:  .peaks/_runtime/2026-06-11-session-f0312d/prd/requests/001-001-l2-1-redlines-audit.md
+ * OpenSpec: openspec/changes/2026-06-11-l2-1-redlines-audit/
+ *
+ * The audit framework classifies MANDATORY / BLOCKING / MUST NOT / RED LINE
+ * markers across skills/, .claude/rules/, and openspec/changes/. Each
+ * discovered red line is tagged with its backing (cli-backed / partial /
+ * prose-only) so the L2 redesign can track the prose-only ratio over time.
+ */
+export type RedLineMarker = 'MANDATORY' | 'BLOCKING' | 'MUST NOT' | 'RED LINE';
+export type RedLineBacking = 'cli-backed' | 'partial' | 'prose-only';
+export interface RedLineSource {
+    /** Path relative to project root, posix-style (forward slashes). */
+    readonly file: string;
+    readonly line: number;
+    readonly marker: RedLineMarker;
+    /** ±2 lines of surrounding context for human review. */
+    readonly context: string;
+}
+export interface RedLineEntry {
+    /** Stable id, e.g. "rl-code-ban-001". */
+    readonly id: string;
+    /** Human-readable rule name, e.g. "Code Commit Ban". */
+    readonly rule: string;
+    readonly source: RedLineSource;
+    readonly backing: RedLineBacking;
+    /** Relative path to the enforcement file, or null when prose-only. */
+    readonly enforcerRef: string | null;
+    /**
+     * v2.12.1 catalog governance: `true` for entries that are
+     * advisory / educational / "discovered-but-not-yet-enforced" and
+     * therefore should NOT count toward the prose-only ratio (per spec
+     * §10.2 L2 acceptance ≤ 5%). Defaults to `false`; the classifier
+     * sets it to `true` for auto-discovered prose-only entries (those
+     * without a catalog match, since they have no enforcer template
+     * to promote to). Callers that want strict accounting can still
+     * read `backing === 'prose-only'` and filter manually.
+     *
+     * Why: the pre-v2.12.1 catalog treated every MANDATORY/BLOCKING
+     * phrase in SKILL.md as a "red line", which produced a 60.1%
+     * prose-only ratio (89/148) for what is mostly LLM behavior
+     * guidance, not machine-enforceable rules. See
+     * `.peaks/memory/2026-06-27-prose-only-catalog-followup.md`.
+     */
+    readonly informational?: boolean;
+}
+export interface RedLineAudit {
+    readonly totalRedLines: number;
+    readonly cliBacked: number;
+    readonly partial: number;
+    readonly proseOnly: number;
+    readonly audit: readonly RedLineEntry[];
+    /** Findings from running the 7 file-system enforcers during the scan (L2.4 P2-b). */
+    readonly enforcerFindings: readonly EnforcerFinding[];
+}
+/**
+ * Enforcer finding — emitted by an enforcer function that runs as part
+ * of the audit scan. Distinct from `RedLineEntry` (which is catalog-matched
+ * markdown text). L2.4 P2-b ships this dimension: the audit framework
+ * actually invokes the 7 file-system enforcers during a scan, not just
+ * catalogs them.
+ */
+export type EnforcerFindingSeverity = 'pass' | 'warn' | 'fail';
+export interface EnforcerFinding {
+    readonly enforcerId: string;
+    readonly rule: string;
+    readonly severity: EnforcerFindingSeverity;
+    readonly file: string;
+    readonly detail: string;
+}
+/**
+ * A single markdown line discovered by a tree scanner. The classifier turns
+ * these into RedLineEntry by matching against the red-line catalog.
+ */
+export interface MarkdownLine {
+    readonly file: string;
+    readonly line: number;
+    readonly text: string;
+}
+export interface ScanWarning {
+    readonly file: string;
+    readonly message: string;
+}

package/dist/services/code/auto-compact-orchestrator.d.ts

@@ -0,0 +1,98 @@
+import { type CompactTrigger, type ConvergencePlan, type InFlightBatchProbe, type AutoCompactResult } from '../context/auto-compact-types.js';
+import type { CompactTarget } from '../context/auto-compact-dispatcher.js';
+export interface AutoCompactInput {
+    /** Project root for context (default cwd). */
+    readonly projectRoot: string;
+    /** Caller-provided in-flight batch probe (default false). */
+    readonly inFlightBatch?: InFlightBatchProbe | undefined;
+    /**
+     * Force execute even when ratio < threshold (test seam). In
+     * production this is always `false` — peaks-loop drives compact
+     * autonomously at 0.85+ with zero human / zero LLM intervention.
+     */
+    readonly force?: boolean | undefined;
+    /** Skip the 95% red-line gate (test seam — never true in production). */
+    readonly bypassRedLine?: boolean | undefined;
+    /** Current session id (default = resolve via session-id-service). */
+    readonly sessionId?: string | undefined;
+    /** Injectable env for IDE detection (test seam). */
+    readonly env?: NodeJS.ProcessEnv | undefined;
+    /** Injectable clock for mtime checks (test seam). */
+    readonly now?: Date | undefined;
+    /**
+     * Slice 2026-06-28-code-mode-bypass-fix (defect #4): which session
+     * the compact should target. Default `'main'` — the orchestrator
+     * (peaks-code body) runs in the main-session Claude Code window and
+     * wants to compress *its* context. Sub-agent shells pass
+     * `'sub-agent'` to preserve the legacy shell-spawn behaviour.
+     */
+    readonly target?: CompactTarget | undefined;
+}
+/**
+ * Map a context ratio to a `CompactTrigger` action. Pure; the side
+ * effects (checkpoint + IDE dispatch) live in `runAutoCompact`. Two
+ * tiers:
+ *
+ *   - ratio < 0.85 → 'none' or 'soft-warn'
+ *   - ratio ≥ 0.85 → 'pre-compact' (async-friendly path)
+ *   - ratio ≥ 0.95 → 'red-line' (synchronous gate)
+ */
+export declare function evaluateCompactTrigger(ratio: number): CompactTrigger;
+/**
+ * Decide whether to run the auto-compact flow. Pure function for the
+ * decision; side effects (checkpoint + IDE dispatch) live in
+ * `runAutoCompact` below. Zero human / zero LLM intervention:
+ *
+ *   - ratio < 0.85           → skip (LLM keeps working; no action)
+ *   - 0.85 ≤ ratio < 0.95    → pre-compact; if in-flight batch
+ *                                present, defer (D6.e); else dispatch
+ *                                IDE compact asynchronously.
+ *   - ratio ≥ 0.95           → red-line; ALWAYS dispatch synchronously
+ *                                regardless of in-flight batch.
+ */
+export declare function evaluateAutoCompactDecision(input: {
+    ratio: number;
+    inFlightBatch?: InFlightBatchProbe | undefined;
+    force?: boolean | undefined;
+    bypassRedLine?: boolean | undefined;
+}): {
+    shouldCompact: boolean;
+    reason: 'below-threshold' | 'in-flight-batch' | 'pre-compact' | 'red-line';
+    trigger: CompactTrigger;
+};
+/**
+ * Build the convergence plan that D7's post-compact-detect will read
+ * back. Includes the current plan, open questions, recent decisions,
+ * todo state, and recent artifact paths — strictly more than what a
+ * raw `/compact` would preserve.
+ */
+export declare function buildConvergencePlan(input: {
+    readonly sessionId: string;
+    readonly projectRoot: string;
+    readonly ratio: number;
+    readonly checkpointPath: string;
+    readonly nextActions: readonly string[];
+    readonly redLine?: boolean;
+}): ConvergencePlan;
+/**
+ * Execute the auto-compact flow.
+ *
+ * Steps (orchestration):
+ *   1. Resolve session id.
+ *   2. Read current ratio via AC-1 (`readContextPercent`).
+ *   3. Evaluate trigger via `evaluateCompactTrigger`.
+ *   4. If trigger.kind === 'none' / 'soft-warn' → return skip.
+ *   5. If trigger.kind === 'pre-compact' AND in-flight batch → wait.
+ *   6. If trigger.kind === 'pre-compact' → async dispatch (write
+ *      checkpoint + IDE compact; orchestrator returns immediately).
+ *   7. If trigger.kind === 'red-line' → synchronous gate: refuse
+ *      sub-agent dispatch, dispatch IDE compact, mark `redLineGated`.
+ *
+ * The caller (CLI or skill body) handles the actual return — D7's
+ * post-compact-detect will pick up the checkpoint on the next turn.
+ * For red-line, the caller MUST block further tool calls until the
+ * post-compact probe confirms ratio < 0.85.
+ */
+export declare function runAutoCompact(input: AutoCompactInput): Promise<AutoCompactResult>;
+/** Re-export for callers that need to surface the trigger shape. */
+export type { CompactTrigger, ConvergencePlan, InFlightBatchProbe, AutoCompactResult };