cc-codeconductor 0.5.0 → 1.0.0

package/README.md

@@ -13,93 +13,55 @@ contracts, task cards, and risk-based routing.
 >
 > ## Current Scope
 >
-> What works today:
+> Canonical matrix: [docs/current-status.md](docs/current-status.md).
+> Published package is **0.5.0**. The next documented release is **v1.0.0**
+> (Product OS). This repository: `bun run dev …` (not `npx`) while iterating.
+>
+> Published in 0.5.0:
 >
 > - `npx cc-codeconductor init` — detects project stack, writes
 >   `.codeconductor/config.yml`, copies `council.yml` and `policy.yml` into
 >   `.codeconductor/presets/`
-> - `npx cc-codeconductor install council --target <opencode|claude|codex|agy|all>` —
->   generates and writes preset files; supports `--global` to install to
->   `~/.opencode/`, `~/.claude/`, `~/.codex/`, `~/.agents/`
-> - `npx cc-codeconductor install lsp --target <opencode|claude|codex|gemini|cursor|agy|all>` —
->   installs LSP servers and configures AI coding tools; auto-detects project
->   languages or use `--lang` to override
-> - `npx cc-codeconductor detect` — detects project stack and recommends presets
-> - `npx cc-codeconductor doctor` — validates configuration and installed runner
->   directories
-> - `npx cc-codeconductor update` — re-applies the council preset for the configured
->   target
-> - `npx cc-codeconductor seo audit --url <url>` — runs a comprehensive SEO audit
->   on a single page (meta tags, schema.org, GEO readiness) and generates a
->   markdown report
-> - `npx cc-codeconductor seo audit --sitemap <url>` — batch audits all URLs from
->   a sitemap.xml with rate limiting and SSRF prevention
-> - `npx cc-codeconductor seo llms --sitemap <url>` — generates a `llms.txt` file
->   for AI-search readiness from sitemap content
-> - `npx cc-codeconductor help` (alias: `cc-help`) — shows preset inventory
->   (skills, subagents, commands) for the active or specified target
-> - `npx cc-codeconductor debt-harvest` (alias: `harvest`) — scans source files
->   for `// defer` comments and writes `.codeconductor/debt-ledger.md`
-> - `npx cc-codeconductor goal "<objective>"` (alias: `cc-goal`) — decomposes an
->   objective into a dependency-ordered task graph, writes
->   `.codeconductor/current-goal.yml`
-> - `/cc-pagespeed --url <url>` — audits web performance using the PageSpeed
->   Insights API; applies the 80/20 principle to produce a prioritized report of
->   Core Web Vitals (LCP, TBT, CLS, FCP, TTFB) with framework-specific fixes;
->   requires `PAGESPEED_API_KEY` env var for full CrUX field data (optional but
->   recommended)
-> - `npx cc-codeconductor install preset --target <opencode|claude|codex|agy|all>` —
->   installs the full preset (agents, prompts, skills, commands, settings) for the
->   chosen runner; use `--locale=es` to inject Spanish-aware instructions into
->   agent files, or rely on the locale saved during `init`
-> - **Stack-specific presets (v0.4.0)**: `ts-next-drizzle`, `spring-kotlin-jpa`,
->   `laravel-tall`, `python-data-api` — bundle `architect` + `implementer`
->   contracts tuned to a single framework so `install preset` drops in the right
->   defaults for that stack.
-> - **9 specialized skills (v0.4.0)**: `drizzle-schema-architect`,
->   `tailwind-responsive-auditor`, `seo-analytics-injector`,
->   `jpa-nplusone-detector`, `spring-auth-auditor`, `livewire-alpine-bridge`,
->   `fastapi-pydantic-strict`, `tdd-mutation-tester`, `auth-token-inspector` —
->   loaded automatically by the matching preset.
-> - **Workflow Loop Core (v0.4.0)** — 8-phase pipeline
->   (`intake → structure → design → test → implement → validate → council →
->   compact`) with operational guardrails (wall-clock timeout, max files
->   modified, max lines changed) and human-in-the-loop STOP gates after Design
->   and Council Verdict.
-> - **Council consensus v0.4.0** — agent confidence thresholds
->   (`< 0.6` per-agent or `< 0.7` average escalates) and a `complianceVeto`
->   channel that overrides majority the same way `securityVeto` does.
-> - **Goal orchestration (v0.4.0)** — `goal` planner writes
->   `.codeconductor/current-goal.yml`; the orchestrator delegates tasks in
->   dependency order and blocks dependents when a prerequisite is `blocked`.
-> - **Memory compression + escalation emitter (v0.4.0)** — Phase 5 memory index
->   + token budget hook keeps inter-agent context below the configured budget;
->   the loop controller emits escalation reports when guardrails fire.
-> - **Parallel subagents (v0.4.0)** — risk-based routing policy v0.4.0 enables
->   parallel execution for eligible agent sequences (architect + implementer
->   pattern, council verdict fan-out).
-> - Manual presets for OpenCode, Claude Code, and Codex
-> - Versioned Agent Contracts
-> - Routing Policy documentation
-> - Task Card, Scorecard, and workflow templates
-> - Spring Boot/Kotlin and Python/Django workflow guidance
+> - `npx cc-codeconductor install council --target <opencode|claude|codex|agy|all>`
+> - `npx cc-codeconductor install preset --target <opencode|claude|codex|gemini|cursor|agy|all>`
+> - `npx cc-codeconductor install lsp --target <…>`
+> - `npx cc-codeconductor detect` / `doctor` / `update`
+> - `npx cc-codeconductor seo audit` / `seo llms` (SSRF-guarded fetch)
+> - `npx cc-codeconductor help` / `cc-help`
+> - `npx cc-codeconductor debt-harvest` (alias: `harvest`)
+> - `npx cc-codeconductor ccep …` — CCEP is the canonical consumer workflow loop
+> - `npx cc-codeconductor openspec …` — OpenSpec is a **delivery loop** and the
+>   backlog tool (`validate` / `scan` / `plan` / `status` / `next`)
+> - `npx cc-codeconductor scorecard …`
+> - Slash commands after `install preset` — prefer `/cc-iterative`, `/cc-triage`,
+>   `/cc-handoff`; `/cc-openspec` runs the OpenSpec loop
+> - `/cc-pagespeed --url <url>` — PageSpeed Insights / Core Web Vitals after
+>   `install preset`; `PAGESPEED_API_KEY` is optional but recommended for CrUX
+>   field data (see [docs/pagespeed-usage.md](docs/pagespeed-usage.md))
+> - Stack-specific skill selection (`ts-next-drizzle`, `spring-kotlin-jpa`,
+>   `laravel-tall`, `python-data-api`)
+> - Council consensus: confidence thresholds + `securityVeto` / `complianceVeto`
 >
-> See [docs/v0.4.0-release-notes.md](docs/v0.4.0-release-notes.md) for the
-> full v0.4.0 feature breakdown.
+> Documented as **v1.0.0** (in this repo, not in published 0.5.0):
 >
-> What does not exist yet:
+> - `goal` / `ingest` / `product` / `orchestrate` / `impact` / `verify`
+> - Product graph in `.codeconductor/product-graph.json`
+> - See [docs/v1.0.0-release-notes.md](docs/v1.0.0-release-notes.md)
+>
+> Experimental (library only, not a CLI runtime):
 >
-> - Runtime sandbox enforcement
-> - Policy compiler
-> - Automated agent evaluation
-> - Safe Merger
+> - `runWorkflowPipeline()` — 8-phase loop in `src/core/pipeline/workflow-loop.ts`
+>
+> What does not exist yet:
 >
-> Security note:
+> - Runtime sandbox / OS-level isolation
+> - Policy compiler / uniform target enforcement
+> - Full stack-specific asset pruning
 >
-> CodeConductor currently provides declarative policies and documented
-> guardrails. It does not yet enforce OS-level isolation, shell sandboxing, or
-> runtime permission boundaries by itself. Treat all agent execution as
-> dependent on the capabilities and limitations of the target tool.
+> Security note: policies are declarative. Agent execution depends on the
+> target runner. `install preset --target cursor` overwrites runner command
+> dirs; maintainer-only stubs (`cc-self-review`, `cc-update-preset-models`)
+> are skipped so this repo can dogfood `install preset`.
 
 ---
 
@@ -168,7 +130,7 @@ Task Card → Risk Classification → Routing Policy → Conductor Agent → Del
 - Provider-agnostic `AgentContract` abstraction with target renderers for Claude, OpenCode, Codex, and Agy
 - Council consensus engine (`councilConsensus()`) for multi-agent governance with majority/unanimous algorithms, security veto, **compliance veto**, and **agent confidence thresholds** (v0.4.0)
 - Phase 5 runtime modules — scoped context injection, TDD history compaction, concise inter-agent messaging, and token budget enforcement in the compile-fix loop
-- **Workflow Loop Core (v0.4.0)** — 8-phase pipeline (`runWorkflowPipeline`) with wall-clock / files-modified / lines-changed guardrails and STOP gates at Design and Council Verdict
+- **Workflow Loop Core (v0.4.0, experimental)** — 8-phase pipeline (`runWorkflowPipeline`) with wall-clock / files-modified / lines-changed guardrails and STOP gates at Design and Council Verdict (library-only; not a shipped CLI runtime)
 - **Stack-specific presets (v0.4.0)** — `ts-next-drizzle`, `spring-kotlin-jpa`, `laravel-tall`, `python-data-api`
 - **9 specialized skills (v0.4.0)** — drizzle-schema-architect, tailwind-responsive-auditor, seo-analytics-injector, jpa-nplusone-detector, spring-auth-auditor, livewire-alpine-bridge, fastapi-pydantic-strict, tdd-mutation-tester, auth-token-inspector
 - **Goal orchestration (v0.4.0)** — `goal` planner + `goal-state` writer feed the orchestrator's dependency-order delegation loop
@@ -176,6 +138,41 @@ Task Card → Risk Classification → Routing Policy → Conductor Agent → Del
 
 ---
 
+## Programmatic API
+
+`cc-codeconductor` ships a library entry in addition to the CLI. The `bin`
+commands still resolve to `dist/index.js`. Application code should import the
+package root:
+
+```ts
+import {
+  LoopEngine,
+  runLoop,
+  runVerification,
+  getNextTask,
+  startTask,
+  completeTask,
+  loopStateMachine,
+  createInitialState,
+} from 'cc-codeconductor';
+```
+
+Exported surface (stable for this minor):
+
+- Orchestrator: `getReadyTasks`, `getNextTask`, `startTask`, `completeTask`, `goalTaskToCanonicalCard`, `buildTaskEnvelope`, `formatGoalStatus`
+- Loop engine (TC3): `LoopEngine`, `runLoop`, `runLoopForProject`, `shouldRunAgentLoop`, `formatFeedback`
+- Verification: `runVerification`, `gateTaskCompletion`, `validateEvidenceIds`
+- Zod contracts: everything from `src/validation/schemas.ts`
+- Domain loop: `createInitialState`, `loopStateMachine` and their types
+
+`infrastructure/` and `*-internal` modules are not part of the public API.
+
+```bash
+bun run build   # CLI → dist/index.js, library → dist/library.js + .d.ts
+```
+
+---
+
 ## CLI Usage
 
 ### Install
@@ -292,7 +289,12 @@ const next = getPreset('ts-next-drizzle');
 ```
 
 `init` / `detect` identifies the stack from the project and wires the
-matching specialized skills automatically when you run `install preset`.
+matching specialized skills onto the **generic** target workflow when you run
+`install preset`. Full stack-specific asset pruning/replacement (swapping the
+entire agent/command tree for a stack pack) is **not implemented yet** — the
+registry and skill wiring are real; treat claims of a full stack install swap
+as aspirational until that lands.
+
 The full set of assets for a stack-specific preset is in
 `presets/<preset-name>/agents/` — copy them manually if you need to apply a
 preset by name.
@@ -347,17 +349,19 @@ npx cc-codeconductor update --global
 
 Smart updates all currently installed target presets, council configurations, and skills (from `skills-lock.json`), preserving user edits outside managed blocks. Also validates that `AGENTS.md` and `CLAUDE.md` do not exceed the 40KB size limit.
 
-#### `help` — show preset inventory
+#### `help` / `cc-help` — distinct help contracts
 
 ```bash
-npx cc-codeconductor help                    # show inventory for active target
-npx cc-codeconductor help --target claude    # show inventory for specific target
-npx cc-codeconductor cc-help                 # alias
-npx cc-codeconductor help --output json      # machine-readable output
+npx cc-codeconductor help                    # general CLI usage
+npx cc-codeconductor --help                  # same general usage text
+npx cc-codeconductor cc-help                 # preset inventory for active target
+npx cc-codeconductor cc-help --target claude # inventory for a specific target
+npx cc-codeconductor cc-help --output json   # machine-readable inventory
 ```
 
-Lists the skills, subagents, commands, and workflows available in the active
-preset. Reads from `presets/<target>/` in the project root.
+`help` prints the CLI command list. `cc-help` lists skills, subagents,
+commands, and workflows for the active preset (or a specified `--target`).
+Reads inventory from `presets/<target>/` in the project root.
 
 #### `debt-harvest` — collect deferred debt items
 
@@ -531,15 +535,11 @@ codeconductor/
 
 ## Roadmap
 
-| Version    | Focus                                                       |
-| ---------- | ----------------------------------------------------------- |
-| **v0.2.0** | **CLI: init, detect, install, doctor, update — shipped** ✅ |
-| v0.3.0     | Next.js, FastAPI, generic presets, monorepo support         |
-| **v0.4.0** | **Workflow Loop Core, stack-specific presets, 9 specialized skills, confidence thresholds + compliance veto in council consensus, goal orchestration, memory compression — shipped** ✅ |
-| v0.5.0     | Scorecard CLI, prompt contracts v0.5.0 (Evaluation gate, 3 new agents, Grok fallback) — shipped ✅ |
-| v1.0.0     | Stable contracts, stable routing, documented evaluation     |
+Published package: **0.5.0**. The next documented release is **v1.0.0**
+(Product OS). Details: [docs/current-status.md](docs/current-status.md) and
+[docs/v1.0.0-release-notes.md](docs/v1.0.0-release-notes.md).
 
-See [ROADMAP.md](ROADMAP.md) for details.
+See [ROADMAP.md](ROADMAP.md) for historical notes.
 
 ---
 

package/dist/cli/errors.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Exit codes as per CLI contract
+ */
+export declare const ExitCode: {
+    readonly SUCCESS: 0;
+    readonly VALIDATION_ERROR: 1;
+    readonly UNSAFE_OPERATION: 2;
+    readonly UNSUPPORTED_PROJECT: 3;
+    readonly CONFIG_CONFLICT: 4;
+    readonly CREDENTIAL_LEAK: 5;
+};
+export type ExitCodeType = (typeof ExitCode)[keyof typeof ExitCode];
+/**
+ * Base error class for CLI errors
+ */
+export declare class CliError extends Error {
+    readonly code: ExitCodeType;
+    readonly details?: unknown | undefined;
+    constructor(message: string, code: ExitCodeType, details?: unknown | undefined);
+}
+/**
+ * Validation error - invalid arguments, malformed config, Zod validation failure
+ */
+export declare class ValidationError extends CliError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * Unsafe operation - destructive operation without --force, protected path conflict
+ */
+export declare class UnsafeOperationError extends CliError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * Unsupported project - project stack not detected or not supported
+ */
+export declare class UnsupportedProjectError extends CliError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * Config conflict - existing config conflicts with requested operation
+ */
+export declare class ConfigConflictError extends CliError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * Credential leak - content contains secrets or API keys
+ */
+export declare class CredentialGuardError extends CliError {
+    readonly matches: ReadonlyArray<{
+        filePath: string;
+        line: number;
+        pattern: string;
+        matched: string;
+    }>;
+    constructor(message: string, matches: ReadonlyArray<{
+        filePath: string;
+        line: number;
+        pattern: string;
+        matched: string;
+    }>, details?: unknown);
+}
+/**
+ * Map error to exit code
+ */
+export declare function getExitCode(error: unknown): ExitCodeType;

package/dist/core/compilation/compile-checker.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Compile Check — runs a build command via Bun.spawn, captures output,
+ * parses errors, and returns structured results for re-injection.
+ */
+export interface CompileError {
+    file: string;
+    line?: number;
+    column?: number;
+    code: string;
+    message: string;
+    raw: string;
+}
+export interface CompileResult {
+    success: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    errors: CompileError[];
+    durationMs: number;
+    timedOut: boolean;
+}
+export interface CompileCheckOptions {
+    /**
+     * Shell command to run (string or pre-split args). Default: `tsc --noEmit`.
+     * Must be a project-trusted compile command from config, never unsanitized CLI input.
+     */
+    command?: string | string[];
+    /** Working directory. Default: process.cwd() */
+    cwd?: string;
+    /** Timeout in milliseconds. Default: 120 000 (2 min) */
+    timeoutMs?: number;
+}
+/**
+ * Tokenize a shell command string, respecting single and double quotes.
+ *
+ * Exported so other modules that must spawn configured commands (e.g. the
+ * regression checklist) can avoid invoking a shell entirely.
+ */
+export declare function tokenizeCommand(cmd: string): string[];
+export declare function isAllowlistedCompileCommand(command: string | string[]): boolean;
+/** Allowlisted commands that actually run a test suite (`bun test`, `npm test`, …). */
+export declare function isAllowlistedTestCommand(command: string | string[]): boolean;
+/**
+ * Parse compile stderr output into structured CompileError[].
+ * Tries TypeScript format first, then ESLint, then generic.
+ */
+export declare function parseCompileErrors(stderr: string): CompileError[];
+/**
+ * Run a compile check via Bun.spawn with configurable timeout.
+ */
+export declare function runCompileCheck(options?: CompileCheckOptions): Promise<CompileResult>;

package/dist/core/config/codeconductor-config.d.ts

@@ -0,0 +1,42 @@
+/**
+ * CodeConductor configuration interface
+ */
+export interface CodeConductorConfig {
+    version: string;
+    project: {
+        name: string;
+        profile?: string;
+    };
+    defaults: {
+        target: 'opencode' | 'claude' | 'codex' | 'gemini' | 'cursor' | 'agy';
+        overwrite: boolean;
+        locale: 'en' | 'es';
+    };
+    presets: {
+        council: {
+            enabled: boolean;
+            version: string;
+        };
+    };
+    safety: {
+        destructiveCommands: string[];
+        secretPatterns: string[];
+        compileCheck?: {
+            enabled: boolean;
+            command?: string;
+            timeoutMs?: number;
+        };
+    };
+    loop?: {
+        enabled?: boolean;
+        maxIterations?: number;
+        maxTokenBudget?: number;
+    };
+}
+/**
+ * Default configuration.
+ * `safety.secretPatterns` references `DEFAULT_SECRET_PATTERNS` from
+ * credential-guard.ts so there is a single source of truth for default
+ * credential patterns.
+ */
+export declare const DEFAULT_CONFIG: CodeConductorConfig;

package/dist/core/config/config-loader.d.ts

@@ -0,0 +1,11 @@
+import { ValidationError } from '../../cli/errors';
+import { type Result } from '../../utils/result';
+import type { CodeConductorConfig } from './codeconductor-config';
+/**
+ * Load configuration from project root
+ */
+export declare function loadConfig(projectRoot: string): Promise<Result<CodeConductorConfig, ValidationError>>;
+/**
+ * Check if config exists
+ */
+export declare function configExists(projectRoot: string): Promise<boolean>;

package/dist/core/filesystem/credential-guard.d.ts

@@ -0,0 +1,18 @@
+import type { CodeConductorConfig } from '../config/codeconductor-config';
+/**
+ * Default keyword patterns. Empty by design: built-in detection is handled by
+ * the high-confidence signatures in `safety.ts`, which match provider-specific
+ * credential shapes instead of generic keyword assignments. Keyword matching
+ * remains available as an opt-in via project `secretPatterns`.
+ */
+export declare const DEFAULT_SECRET_PATTERNS: string[];
+/**
+ * Load opt-in keyword patterns by merging sources in priority order:
+ * 1. CodeConductorConfig.safety.secretPatterns (highest — user/project overrides)
+ * 2. policy.yml secretPatterns (declarative policy)
+ * 3. DEFAULT_SECRET_PATTERNS (empty — see above)
+ *
+ * These are additive to the always-on high-confidence signatures.
+ * Note: policy.yml loading is async, so this function is async.
+ */
+export declare function loadCredentialPatterns(config?: CodeConductorConfig): Promise<ReadonlyArray<string>>;

package/dist/core/goal/goal-planner.d.ts

@@ -0,0 +1,8 @@
+import type { GoalGraphInput } from '../../validation/schemas';
+/**
+ * Pure function: objective string → GoalGraph
+ *
+ * Matches the objective against built-in templates (auth, crud, search,
+ * notification, migration) or falls back to a generic 4-task chain.
+ */
+export declare function planGoal(objective: string): GoalGraphInput;

package/dist/core/goal/goal-state.d.ts

@@ -0,0 +1,15 @@
+import { type GoalGraphInput } from '../../validation/schemas';
+import { type Result } from '../../utils/result';
+/**
+ * Write a goal graph to .codeconductor/current-goal.yml
+ */
+export declare function writeGoal(projectRoot: string, graph: GoalGraphInput): Promise<Result<void, Error>>;
+/**
+ * Load and validate a goal graph from .codeconductor/current-goal.yml
+ */
+export declare function loadGoal(projectRoot: string): Promise<Result<GoalGraphInput, Error>>;
+/**
+ * Mark a task as blocked in the goal graph.
+ * Loads the graph, finds the task by ID, sets status to 'blocked', and writes back.
+ */
+export declare function markTaskBlocked(projectRoot: string, taskId: string, reason: string): Promise<Result<void, Error>>;

package/dist/core/loop/git-stats.d.ts

@@ -0,0 +1,13 @@
+/** Shared TTL so loop iterations do not spawn git on every tick. */
+export declare const GIT_STATS_CACHE_TTL_MS = 3000;
+export interface GitChangeStats {
+    readonly filesModified: number;
+    readonly linesChanged: number;
+}
+export type GitStatsReader = (cwd: string) => Promise<GitChangeStats>;
+export declare function resetGitStatsCache(): void;
+export declare function fetchGitChangeStats(cwd: string): Promise<GitChangeStats>;
+export declare function readGitChangeStats(cwd: string, options?: {
+    readonly now?: number;
+    readonly fetch?: GitStatsReader;
+}): Promise<GitChangeStats>;

package/dist/core/loop/loop-engine.d.ts

@@ -0,0 +1,79 @@
+import { type CompileError, type CompileResult } from '../compilation/compile-checker';
+import { type LoopState, type TddState } from '../../domain/loop/loop-state';
+import { type GitStatsReader } from './git-stats';
+import { type Result } from '../../utils/result';
+export interface LoopConfig {
+    maxIterations?: number;
+    maxTokenBudget?: number;
+    buildCommand?: string;
+    cwd?: string;
+    maxWallClockSeconds?: number;
+    maxFilesModified?: number;
+    maxLinesChanged?: number;
+    gitStats?: GitStatsReader;
+}
+export interface EscalationReport {
+    readonly taskTitle: string;
+    readonly iterationsAttempted: number;
+    readonly errorHistory: readonly (readonly CompileError[])[];
+    readonly attemptedFixes: readonly string[];
+    readonly originalContext: string;
+    readonly recommendedAction: string;
+}
+export interface LoopResult {
+    readonly success: boolean;
+    readonly iterations: number;
+    readonly totalErrors: number;
+    readonly finalPhase: LoopState['phase'];
+    readonly escalationReport?: EscalationReport;
+    readonly errorHistory: readonly (readonly CompileError[])[];
+}
+export type GuardrailHit = {
+    readonly kind: 'timeout';
+    readonly elapsedSeconds: number;
+    readonly limit: number;
+} | {
+    readonly kind: 'files';
+    readonly count: number;
+    readonly limit: number;
+} | {
+    readonly kind: 'lines';
+    readonly count: number;
+    readonly limit: number;
+};
+/**
+ * Shared wall-clock / git-diff budget checks for compile-fix and the 8-phase pipeline.
+ */
+export declare class LoopEngine {
+    private readonly limits;
+    readonly startedAt: number;
+    constructor(limits: {
+        readonly maxWallClockSeconds?: number;
+        readonly maxFilesModified?: number;
+        readonly maxLinesChanged?: number;
+        readonly cwd?: string;
+    }, gitStats?: GitStatsReader, startedAt?: number);
+    private readonly gitStats;
+    evaluate(scope?: 'time' | 'all'): Promise<GuardrailHit | null>;
+}
+export declare function formatFeedback(errors: readonly CompileError[]): string;
+export type GenerateFn = (feedback?: string) => Promise<{
+    tokenUsage: number;
+} | void>;
+export type CompileCheckFn = () => Promise<CompileResult>;
+export declare function runLoop(generateFn: GenerateFn, compileCheckFn: CompileCheckFn, config?: LoopConfig, taskTitle?: string, originalTask?: string): Promise<LoopResult>;
+/** implement / test agent phases that must run the compile-fix engine. */
+export declare function shouldRunAgentLoop(type?: string, agentType?: string, phase?: string): boolean;
+/**
+ * Apply runner-captured TDD suite evidence to the domain TDD machine.
+ * Hand-written evidence files fail closed via `loadTddSuiteEvidence`.
+ */
+export declare function advanceTddPhase(projectRoot: string, taskId: string, state: TddState, evidenceId: string): Promise<Result<{
+    state: TddState;
+    result: 'CONTINUE' | 'TERMINATE';
+}, Error>>;
+export declare function runLoopForProject(projectRoot: string, options: {
+    readonly taskTitle: string;
+    readonly allowCompileCheck?: boolean;
+    readonly originalTask?: string;
+}): Promise<LoopResult>;

package/dist/core/memory/episodic-store.d.ts

@@ -0,0 +1,6 @@
+import { type ProductEventInput } from '../../validation/schemas';
+import { type Result } from '../../utils/result';
+export declare function appendEvent(projectRoot: string, event: Omit<ProductEventInput, 'id'> & {
+    id?: string;
+}): Promise<Result<ProductEventInput, Error>>;
+export declare function listEvents(projectRoot: string, since?: string, type?: ProductEventInput['type']): Promise<Result<ProductEventInput[], Error>>;

package/dist/core/memory/operational-state.d.ts

@@ -0,0 +1,6 @@
+import { type OperationalStateInput } from '../../validation/schemas';
+import { type Result } from '../../utils/result';
+export declare function loadOperationalState(projectRoot: string): Promise<Result<OperationalStateInput, Error>>;
+export declare function saveOperationalState(projectRoot: string, state: OperationalStateInput): Promise<Result<void, Error>>;
+export declare function setActiveTask(projectRoot: string, taskId: string, agent?: string): Promise<Result<void, Error>>;
+export declare function clearActiveTask(projectRoot: string, taskId: string): Promise<Result<void, Error>>;

package/dist/core/orchestrator/runtime-orchestrator.d.ts

@@ -0,0 +1,25 @@
+import type { CanonicalTaskCardInput, GoalGraphInput, GoalTaskInput, OperationalStateInput } from '../../validation/schemas';
+import { type Result } from '../../utils/result';
+import type { CommandEnvelopeInput } from '../../validation/schemas';
+/**
+ * Undo a task status change and restore the operational state captured before
+ * it. Used when a later step fails, so a task is never left half-transitioned.
+ * The original failure is returned, annotated when the undo itself fails.
+ */
+export declare function rollbackTaskStatus(projectRoot: string, graph: GoalGraphInput, task: GoalTaskInput, previousStatus: GoalTaskInput['status'], previousState: OperationalStateInput, cause: Error): Promise<Result<never, Error>>;
+export declare function getReadyTasks(graph: GoalGraphInput): GoalTaskInput[];
+export declare function goalTaskToCanonicalCard(task: GoalTaskInput & {
+    targetFiles?: string[];
+    agentType?: string;
+    evidenceRequired?: string[];
+}, objective: string): CanonicalTaskCardInput;
+export declare function buildTaskEnvelope(card: CanonicalTaskCardInput, projectRoot: string, projectName: string): CommandEnvelopeInput;
+export interface OrchestratorNextResult {
+    task: CanonicalTaskCardInput;
+    envelope: CommandEnvelopeInput;
+    readyCount: number;
+}
+export declare function getNextTask(projectRoot: string, projectName: string): Promise<Result<OrchestratorNextResult, Error>>;
+export declare function startTask(projectRoot: string, taskId: string, agent?: string): Promise<Result<void, Error>>;
+export declare function completeTask(projectRoot: string, taskId: string, evidenceIds?: string[]): Promise<Result<void, Error>>;
+export declare function formatGoalStatus(graph: GoalGraphInput): string;

package/dist/core/planner/product-planner.d.ts

@@ -0,0 +1,18 @@
+import type { GoalGraphInput, GoalTaskInput, ProductGraphInput } from '../../validation/schemas';
+export declare function inferEvidenceRequired(task: GoalTaskInput): string[];
+export interface ProductGoalGraph extends GoalGraphInput {
+    productEnriched: boolean;
+    impactPreview?: {
+        components: string[];
+        requirements: string[];
+    };
+}
+export declare function planProductGoal(objective: string, graph?: ProductGraphInput): ProductGoalGraph;
+export declare function enrichGoalWithProduct(graph: GoalGraphInput, productGraph?: ProductGraphInput): GoalGraphInput & {
+    enrichedTasks: Array<GoalTaskInput & {
+        targetFiles: string[];
+        agentType: string;
+        evidenceRequired: string[];
+    }>;
+};
+export declare function scoreTaskPriority(task: GoalTaskInput, graph?: ProductGraphInput): number;

package/dist/core/presets/package-paths.d.ts

@@ -0,0 +1,4 @@
+export declare const PACKAGE_ROOT: string;
+export declare const SRC_PRESETS_DIR: string;
+export declare const ROOT_PRESETS_DIR: string;
+export declare const POLICY_PATH: string;

package/dist/core/product-graph/graph-store.d.ts

@@ -0,0 +1,11 @@
+import type { ProductNodeType } from '../../domain/product/entities';
+import { type ProductGraphInput, type ProductGraphNodeInput, type ProductGraphEdgeInput } from '../../validation/schemas';
+import { type Result } from '../../utils/result';
+export declare function loadGraph(projectRoot: string): Promise<Result<ProductGraphInput, Error>>;
+export declare function saveGraph(projectRoot: string, graph: ProductGraphInput): Promise<Result<void, Error>>;
+export declare function upsertNode(graph: ProductGraphInput, node: ProductGraphNodeInput): ProductGraphInput;
+export declare function linkNodes(graph: ProductGraphInput, edge: ProductGraphEdgeInput): ProductGraphInput;
+export declare function queryNodes(graph: ProductGraphInput, type?: ProductNodeType, textFilter?: string): ProductGraphNodeInput[];
+export declare function findPath(graph: ProductGraphInput, fromId: string, toId: string): string[] | null;
+export declare function countByType(graph: ProductGraphInput): Record<string, number>;
+export declare function getNeighbors(graph: ProductGraphInput, nodeId: string, relation?: ProductGraphEdgeInput['relation']): ProductGraphNodeInput[];