cclaw-cli 7.7.0 → 8.1.0

package/dist/delegation.d.ts

@@ -1,649 +0,0 @@
-import { type SubagentFallback } from "./harness-adapters.js";
-import { type MandatoryDelegationTaskClass } from "./content/stage-schema.js";
-import type { FlowStage } from "./types.js";
-import { type FlowState } from "./flow-state.js";
-import { type ParseImplementationUnitParallelOptions, type ParsedParallelWave } from "./internal/plan-split-waves.js";
-export type DelegationMode = "mandatory" | "proactive";
-export type DelegationStatus = "scheduled" | "launched" | "acknowledged" | "completed" | "failed" | "waived" | "stale";
-export declare const DELEGATION_DISPATCH_SURFACES: readonly ["claude-task", "cursor-task", "opencode-agent", "codex-agent", "generic-task", "role-switch", "manual"];
-export type DelegationDispatchSurface = typeof DELEGATION_DISPATCH_SURFACES[number];
-/** Agents that declare `claimedPaths` for parallel/disjoint scheduling and fan-out caps. */
-export declare function isParallelTddSliceWorker(agent: string | undefined): boolean;
-/**
- * Per-surface allowed agent-definition path prefixes. Used by the generated
- * `.cclaw/hooks/delegation-record.mjs` helper to reject mismatched
- * `--agent-definition-path` values without inspecting any harness state.
- *
- * The list is intentionally structural: each surface maps to one or more
- * repo-relative path prefixes that must be a parent of the supplied path.
- * `role-switch` and `manual` accept any path because the agent-definition
- * is intentionally not a generated artifact for those surfaces.
- */
-export declare const DELEGATION_DISPATCH_SURFACE_PATH_PREFIXES: Record<DelegationDispatchSurface, string[]>;
-export type DelegationEventType = DelegationStatus;
-/**
- * How a delegation was actually fulfilled. Advisory — mirrors the harness
- * `subagentFallback` that was in effect when the entry was recorded.
- *
- * - `isolated`         — native isolated subagent worker (Claude/OpenCode/Codex).
- * - `generic-dispatch` — generic Task/Subagent dispatch mapped to a named role.
- * - `role-switch`      — performed in-session with explicit role announce.
- * - `harness-waiver`   — auto-waived due to missing dispatch capability.
- * - `legacy-inferred`  — pre-v3 entry: completed status without dispatch
- *   surface/proof. Read-only; stage-complete reports it as a warning until
- *   the entry is re-recorded via `delegation-record.mjs --rerecord`.
- */
-export type DelegationFulfillmentMode = "isolated" | "generic-dispatch" | "role-switch" | "harness-waiver" | "legacy-inferred";
-export interface DelegationTokenUsage {
-    input: number;
-    output: number;
-    model: string;
-}
-export type DelegationWaiverAcceptedBy = "user-flag";
-export type DelegationEntry = {
-    stage: string;
-    agent: string;
-    mode: DelegationMode;
-    status: DelegationStatus;
-    /**
-     * Span identifier for this delegation unit. Multiple status transitions for
-     * the same delegated unit should reuse the same spanId.
-     */
-    spanId?: string;
-    /** Parent span id when this delegation was spawned from another span. */
-    parentSpanId?: string;
-    /** ISO timestamp when the delegation span started. */
-    startTs?: string;
-    /** ISO timestamp when the delegation span ended (for terminal statuses). */
-    endTs?: string;
-    /**
-     * Legacy timestamp used by historical ledgers. New writers set both `ts` and
-     * `startTs` for backward compatibility.
-     */
-    taskId?: string;
-    waiverReason?: string;
-    acceptedBy?: DelegationWaiverAcceptedBy;
-    /**
-     * Waiver approval token captured from `cclaw-cli internal waiver-grant`.
-     * Present on waiver rows that went through `cclaw-cli internal
-     * waiver-grant`. Legacy rows that lack provenance are surfaced as the
-     * advisory linter finding `waiver_legacy_provenance`.
-     */
-    approvalToken?: string;
-    approvalReason?: string;
-    approvalIssuedAt?: string;
-    ts?: string;
-    /**
-     * Run id the entry belongs to. Older ledgers written before 0.5.17 may omit this;
-     * consumers treat missing runId as unscoped (conservatively excluded from current-run checks).
-     */
-    runId?: string;
-    /** Legacy field kept for backward compatibility with historical ledgers. */
-    conditionTrigger?: string;
-    /** Optional token usage captured from the delegated run. */
-    tokens?: DelegationTokenUsage;
-    /** Number of retries attempted for this span. */
-    retryCount?: number;
-    /** Optional references to evidence anchors in artifacts. */
-    evidenceRefs?: string[];
-    /** Dispatch proof id from the parent/controller side. */
-    dispatchId?: string;
-    /** Worker-reported run id or task id returned by the harness. */
-    workerRunId?: string;
-    /** Concrete runtime surface used to launch the worker. */
-    dispatchSurface?: DelegationDispatchSurface;
-    /** Path to the generated or canonical agent definition used for dispatch. */
-    agentDefinitionPath?: string;
-    /** ISO timestamp when the worker was acknowledged by the harness/worker. */
-    ackTs?: string;
-    /** ISO timestamp when the worker was launched. */
-    launchedTs?: string;
-    /** ISO timestamp when the worker completed. */
-    completedTs?: string;
-    /** Optional skill marker used for role-specific mandatory checks. */
-    skill?: string;
-    /**
-     * Fulfillment mode this entry was executed under. Omitted on legacy rows
-     * (treated as `"isolated"` for Claude, otherwise inferred from the active
-     * harness).
-     */
-    fulfillmentMode?: DelegationFulfillmentMode;
-    /**
-     * Schema version marker for span-compatible delegation rows.
-     *
-     * - `1` — legacy rows that predate the dispatch-surface lock
-     * - `2` — historical interim format that introduced ack/launched
-     *   timestamps but did not require dispatch-surface or ack-ts on
-     *   completed isolated/generic
-     * - `3` — current format: completed isolated/generic must carry
-     *   `dispatchSurface`, `agentDefinitionPath`, and ACK timestamp
-     */
-    schemaVersion?: 1 | 2 | 3;
-    /**
-     * When set, the operator explicitly opted into running this
-     * scheduled span concurrently with another active span on the same
-     * `(stage, agent)` pair. Bypasses the dispatch-dedup check.
-     */
-    allowParallel?: boolean;
-    /**
-     * Set on synthetic terminal `stale` rows written via
-     * `--supersede=<prevSpanId>`. References the new spanId that
-     * superseded this span. Helps `/cc tree` and the linter report a
-     * coherent successor chain.
-     */
-    supersededBy?: string;
-    /**
-     * Repo-relative paths the delegated slice-builder will edit. Used by the
-     * file-overlap scheduler to either auto-allow parallel dispatch (disjoint
-     * paths) or block the row with `DispatchOverlapError` (overlapping paths).
-     * For agents other than `slice-builder` the field is advisory.
-     *
-     * keep in sync with the inline copy in
-     * `src/content/hooks.ts::delegationRecordScript`.
-     */
-    claimedPaths?: string[];
-    /**
-     * Absolute path of the isolated git worktree assigned to this span when
-     * `tdd.isolationMode=worktree|auto`.
-     */
-    worktreePath?: string;
-    /**
-     * TDD slice identifier, e.g. `"S-1"`. Recorded by the controller when
-     * dispatching `slice-builder` so the artifact linter can auto-derive the
-     * Watched-RED Proof + Vertical Slice Cycle tables from
-     * `delegation-events.jsonl` instead of requiring agents to maintain the
-     * markdown by hand. Optional on non-TDD rows.
-     *
-     * keep in sync with the inline copy in
-     * `src/content/hooks.ts::delegationRecordScript`.
-     */
-    sliceId?: string;
-    /**
-     * Explicit phase tag for TDD slice events. Combined with `sliceId`, the
-     * linter validates RED → GREEN → REFACTOR → DOC monotonicity per slice.
-     * `refactor-deferred` requires a rationale either via
-     * `--refactor-rationale` (recorded into `evidenceRefs[0]`) or an
-     * `evidenceRefs` entry that contains the rationale text.
-     *
-     * keep in sync with the inline copy in
-     * `src/content/hooks.ts::delegationRecordScript`.
-     */
-    phase?: "red" | "green" | "refactor" | "refactor-deferred" | "doc" | "resolve-conflict";
-    /**
-     * Refactor outcome folded into `phase=green` events so a single row can
-     * close RED → GREEN → REFACTOR for the slice without a separate
-     * `phase=refactor` / `phase=refactor-deferred` lifecycle pass.
-     *
-     * - `mode: "inline"` — refactor pass ran inline as part of the GREEN
-     *   delegation (rationale optional but recommended for traceability).
-     * - `mode: "deferred"` — refactor was intentionally deferred; rationale
-     *   is required (carried in `rationale` and mirrored into
-     *   `evidenceRefs[0]` so evidence-pointer linters keep matching).
-     *
-     * `phase=refactor` and `phase=refactor-deferred` events remain valid;
-     * the linter accepts either form for REFACTOR coverage.
-     *
-     * keep in sync with the inline copy in
-     * `src/content/hooks.ts::delegationRecordScript`.
-     */
-    refactorOutcome?: {
-        mode: "inline" | "deferred";
-        rationale?: string;
-    };
-    /**
-     * Risk tier hint copied from the plan slice. Used by
-     * `integrationCheckRequired()` to decide whether the integration-overseer
-     * must run. `low` and `medium` are advisory; `high` always triggers the
-     * overseer. Optional on every row.
-     */
-    riskTier?: "low" | "medium" | "high";
-};
-export declare const DELEGATION_PHASES: readonly ["red", "green", "refactor", "refactor-deferred", "doc", "resolve-conflict"];
-export type DelegationPhase = (typeof DELEGATION_PHASES)[number];
-export declare const DELEGATION_LEDGER_SCHEMA_VERSION: 3;
-export type DelegationLedger = {
-    runId: string;
-    entries: DelegationEntry[];
-    /** Schema version of the ledger envelope. Current: `3`. */
-    schemaVersion?: 1 | 2 | 3;
-};
-export type DelegationEvent = DelegationEntry & {
-    event: DelegationEventType;
-    eventTs: string;
-    schemaVersion: 1 | 2 | 3;
-};
-/**
- * Heuristic: does a changed file path strongly imply a trust-boundary
- * surface? Used by tests and prompt guidance for risk-triggered review.
- *
- * Matches authN/Z, credentials, crypto, policy, or explicit sanitization
- * or injection handling. Intentionally excludes broad terms like `input`
- * and `validation` because they match innocuous paths such as
- * `form-input.ts` or `number-validation.ts` and produce false positives.
- */
-export declare function isTrustBoundaryPath(filePath: string): boolean;
-export declare function readDelegationLedger(projectRoot: string): Promise<DelegationLedger>;
-export declare function readDelegationEvents(projectRoot: string): Promise<{
-    events: DelegationEvent[];
-    corruptLines: number[];
-}>;
-/**
- * Fold ledger entries to the latest row per `spanId` and keep only spans
- * whose latest status is still active (`scheduled | launched |
- * acknowledged`). Used by the `state/subagents.json` writer so the
- * tracker never reports a span that already has a terminal row.
- *
- * Output is ordered by ascending `startTs ?? ts` so existing UI
- * consumers see a stable presentation order.
- *
- * Rows without a `spanId` are skipped — they are not addressable by
- * the tracker contract and would collide on the empty key.
- *
- * Callers are expected to pass entries already filtered to the active
- * `runId`; cross-run rows are therefore not re-filtered here.
- *
- * keep in sync with the inline copy in
- * `src/content/hooks.ts::delegationRecordScript`.
- */
-export declare function computeActiveSubagents(entries: DelegationEntry[]): DelegationEntry[];
-/**
- * Thrown by `validateMonotonicTimestamps` when an incoming row
- * would push a span's timeline backwards. Carries enough context that
- * the CLI / hook surface can format a `delegation_timestamp_non_monotonic`
- * JSON payload without re-deriving the offending field.
- *
- * keep in sync with the inline copy in
- * `src/content/hooks.ts::delegationRecordScript`.
- */
-export declare class DelegationTimestampError extends Error {
-    readonly field: string;
-    readonly actual: string;
-    readonly priorBound: string;
-    constructor(field: string, actual: string, priorBound: string);
-}
-/**
- * Enforce that lifecycle timestamps on a delegation span move
- * forward (or stay equal). Validates both per-row invariants
- * (`startTs ≤ launchedTs ≤ ackTs ≤ completedTs`) and a cross-row
- * invariant: the union of prior rows for this `spanId` plus the
- * incoming row must have non-decreasing `ts`.
- *
- * Equality is allowed because fast-completing dispatches legitimately
- * collapse multiple lifecycle markers onto the same instant.
- *
- * keep in sync with the inline copy in
- * `src/content/hooks.ts::delegationRecordScript`.
- */
-export declare function validateMonotonicTimestamps(stamped: DelegationEntry, prior: DelegationEntry[]): void;
-/**
- * Thrown by `appendDelegation` when the operator opens a
- * second `scheduled` span on the same `(stage, agent)` pair while an
- * earlier span on the same pair is still active. Callers can catch and
- * either pass the existing span id via `--supersede=<id>` (which
- * pre-writes a synthetic `stale` row) or `--allow-parallel` to record
- * concurrent spans intentionally.
- */
-export declare class DispatchDuplicateError extends Error {
-    readonly existingSpanId: string;
-    readonly existingStatus: DelegationStatus;
-    readonly newSpanId: string;
-    readonly pair: {
-        stage: string;
-        agent: string;
-    };
-    constructor(params: {
-        existingSpanId: string;
-        existingStatus: DelegationStatus;
-        newSpanId: string;
-        pair: {
-            stage: string;
-            agent: string;
-        };
-    });
-}
-/**
- * Thrown by `validateFileOverlap` when a new `slice-builder` is scheduled
- * on a TDD stage with at least one `claimedPaths` entry that overlaps an
- * active span. The scheduler auto-allows parallel dispatch when paths are
- * disjoint, so an explicit overlap is treated as a serialization signal:
- * the operator must wait for the existing span to terminate or pass
- * `--allow-parallel` deliberately to acknowledge the conflict.
- */
-export declare class DispatchOverlapError extends Error {
-    readonly existingSpanId: string;
-    readonly newSpanId: string;
-    readonly pair: {
-        stage: string;
-        agent: string;
-    };
-    readonly conflictingPaths: string[];
-    constructor(params: {
-        existingSpanId: string;
-        newSpanId: string;
-        pair: {
-            stage: string;
-            agent: string;
-        };
-        conflictingPaths: string[];
-    });
-}
-/**
- * Thrown when the count of active `slice-builder` spans reaches
- * `MAX_PARALLEL_SLICE_BUILDERS` and a new scheduled row would push it past
- * the cap. Cap can be configured via `.cclaw/config.yaml::execution.maxBuilders`,
- * overridden once via `--override-cap=N` on the hook flag, or globally via
- * `CCLAW_MAX_PARALLEL_SLICE_BUILDERS=<N>` env.
- */
-export declare class DispatchCapError extends Error {
-    readonly cap: number;
-    readonly active: number;
-    readonly pair: {
-        stage: string;
-        agent: string;
-    };
-    constructor(params: {
-        cap: number;
-        active: number;
-        pair: {
-            stage: string;
-            agent: string;
-        };
-    });
-}
-/**
- * Return `true` when `path` is a repo-relative path owned by the cclaw
- * managed runtime under `.cclaw/`. Used by `validateClaimedPathsNotProtected`
- * during `appendDelegation` to reject `slice-builder` (or any worker)
- * spans that try to claim ownership of cclaw-managed files. Does not
- * normalise the input — callers pass the path exactly as the worker wrote
- * it into `claimedPaths` so the error message points at the real string.
- */
-export declare function isManagedRuntimePath(path: string): boolean;
-/**
- * Thrown by `appendDelegation` when a scheduled span declares a
- * `claimedPaths` entry that lives under the cclaw managed runtime
- * (see `isManagedRuntimePath`). Workers must never edit those paths
- * directly — they are owned by the managed sync surface. The error
- * lists the offending paths so the operator can drop or rewrite them.
- */
-export declare class DispatchClaimedPathProtectedError extends Error {
-    readonly protectedPaths: string[];
-    readonly spanId: string;
-    constructor(params: {
-        protectedPaths: string[];
-        spanId: string;
-    });
-}
-/**
- * Reject any worker span that declares `claimedPaths` entries owned by
- * the cclaw managed runtime. Called from `appendDelegation` for
- * `status === "scheduled"` rows alongside the overlap and fan-out
- * checks. Throws `DispatchClaimedPathProtectedError` listing every
- * offending path so the operator can fix the dispatch in one pass.
- */
-export declare function validateClaimedPathsNotProtected(stamped: DelegationEntry): void;
-/**
- * Thrown by `appendDelegation` (and the inline `delegation-record.mjs`
- * helper) when an event with a non-null `phase` is recorded with
- * `status="acknowledged"`. Phase-level granularity only makes sense on
- * terminal outcomes (`completed` or `failed`); the dispatch-level ACK
- * (no phase) is the controller saying "I see the dispatch surface back".
- *
- * Motivated by hox W-08/S-41: the slice-builder agent recorded all four
- * phase events with `--status=acknowledged`, which the helper silently
- * accepted but `slice-commit.mjs` only fires on `phase=doc status=completed`.
- * `wave-status` then saw the slice as phantom-open even though the
- * worker had finished. Recovery required raw backfill commands.
- *
- * 7.6.0 makes the constraint explicit: pair `--phase=<phase>` with
- * `--status=completed` (or `--status=failed`) and use
- * `--status=acknowledged` only for the dispatch-level ack (no phase).
- */
-export declare class PhaseEventRequiresTerminalStatusError extends Error {
-    readonly phase: string;
-    readonly status: DelegationStatus;
-    readonly spanId: string;
-    readonly correctedCommandHint: string;
-    constructor(params: {
-        phase: string;
-        status: DelegationStatus;
-        spanId: string;
-        correctedCommandHint: string;
-    });
-}
-/**
- * Reject delegation rows where `phase` is set but `status` is not
- * `completed` or `failed`. Acknowledged/launched/scheduled/waived/stale
- * rows must NOT carry a phase — the phase-level lifecycle exists only
- * to record terminal outcomes per phase (RED/GREEN/REFACTOR/DOC).
- *
- * Throws `PhaseEventRequiresTerminalStatusError`; the message includes
- * an actionable corrected-command hint that the controller can paste.
- */
-export declare function validatePhaseEventStatus(stamped: DelegationEntry): void;
-/**
- * Thrown by `appendDelegation` when a new `scheduled` span would open a
- * second TDD cycle for a slice that already has at least one closed span
- * (a span with completed phase rows for `red`, `green`, at least one of
- * `refactor`/`refactor-deferred`, and `doc`) in the same run. Re-running
- * a slice under a fresh span is almost always controller drift —
- * legitimate replay reuses the original spanId and is absorbed by the
- * existing dedup. Motivated by the hox-session 7.0.5 finding where
- * `S-36` had two scheduled spans (`span-w07-S-36-final` and `span-w07-S-36`)
- * that the linter then misread as out-of-order phases.
- */
-export declare class SliceAlreadyClosedError extends Error {
-    readonly sliceId: string;
-    readonly runId: string;
-    readonly closedSpanId: string;
-    readonly newSpanId: string;
-    constructor(params: {
-        sliceId: string;
-        runId: string;
-        closedSpanId: string;
-        newSpanId: string;
-    });
-}
-/**
- * Default cap on active `slice-builder` spans in a single TDD run. Override
- * via `CCLAW_MAX_PARALLEL_SLICE_BUILDERS=<int>` (validated `>=1`).
- */
-export declare const MAX_PARALLEL_SLICE_BUILDERS: 5;
-export interface ReadySliceUnit {
-    unitId: string;
-    sliceId: string;
-    dependsOn: string[];
-    claimedPaths: string[];
-    parallelizable: boolean;
-}
-export interface SelectReadySlicesOptions {
-    cap: number;
-    completedUnitIds: ReadonlySet<string>;
-    activePathHolders: ReadonlyArray<{
-        paths: string[];
-    }>;
-}
-/**
- * Return up to `cap` slice units whose dependsOn are satisfied, avoiding
- * `claimedPaths` intersections with already-selected units and active holders.
- */
-export declare function selectReadySlices(units: ReadySliceUnit[], opts: SelectReadySlicesOptions): ReadySliceUnit[];
-/**
- * Build scheduler rows from merged parallel wave definitions + plan units.
- */
-export declare function readySliceUnitsFromMergedWaves(mergedWaves: ParsedParallelWave[], planMarkdown: string, options?: ParseImplementationUnitParallelOptions): ReadySliceUnit[];
-/**
- * Verdict from `integrationCheckRequired()`.
- *
- * `required: true` means the controller MUST dispatch
- * `integration-overseer` before stage-complete; `reasons[]` lists the
- * triggers that fired so the controller can quote them in artifacts.
- *
- * `required: false` means the integration check can be safely skipped
- * (disjoint paths and no high-risk slices). Callers
- * that skip dispatch should append a `cclaw_integration_overseer_skipped`
- * audit row to `delegation-events.jsonl` so the run log stays honest
- * about the decision.
- */
-export interface IntegrationCheckVerdict {
-    required: boolean;
-    reasons: string[];
-}
-/**
- * Heuristic helper deciding whether a multi-slice wave needs
- * the `integration-overseer` dispatch.
- *
- * Triggers (any one):
- *   - **two or more closed slices share import boundaries** (heuristic:
- *     two slices declare a `claimedPaths` whose first 2 path segments
- *     match — same package/module directory);
- *   - any slice has `riskTier === "high"`.
- *
- * When none fire, the verdict is `{ required: false, reasons: ["disjoint-paths"] }`
- * and the caller should record a `cclaw_integration_overseer_skipped`
- * audit before bypassing the dispatch.
- *
- * Note on inputs: this function reads from the supplied delegation
- * events list directly so callers can inject synthetic data in tests.
- * Use `readDelegationEvents(projectRoot)` in production paths.
- */
-export declare function integrationCheckRequired(events: DelegationEvent[]): IntegrationCheckVerdict;
-/**
- * Append a non-delegation audit event recording that the
- * integration-overseer dispatch was skipped because
- * `integrationCheckRequired()` returned `required: false`. Best-effort;
- * never throws.
- */
-export declare function recordIntegrationOverseerSkipped(projectRoot: string, params: {
-    runId: string;
-    reasons: string[];
-    sliceIds: string[];
-}): Promise<void>;
-/**
- * Load merged wave plan (Parallel Execution Plan block + wave-plans/) and map to `ReadySliceUnit[]`.
- */
-export declare function loadTddReadySlicePool(planMarkdown: string, artifactsDir: string, options?: ParseImplementationUnitParallelOptions): Promise<ReadySliceUnit[]>;
-/**
- * When scheduling a `slice-builder` on a TDD stage, compare `claimedPaths`
- * against every currently active span on the same `(stage, agent)` pair.
- * Overlap → throw `DispatchOverlapError`; disjoint paths → return
- * `{ autoParallel: true }` so the caller can mark the new entry
- * `allowParallel = true` without explicit operator intent. When the agent
- * is not a slice-builder or no `claimedPaths` are supplied, the function
- * returns `{ autoParallel: false }` and the standard dedup path takes over.
- */
-export declare function validateFileOverlap(stamped: DelegationEntry, activeEntries: DelegationEntry[]): {
-    autoParallel: boolean;
-};
-/**
- * Enforce the slice-builder fan-out cap. The new scheduled row pushes the
- * active count from N to N+1; if that would exceed the cap (default/config 5,
- * env-overridable via `CCLAW_MAX_PARALLEL_SLICE_BUILDERS`), throw
- * `DispatchCapError`.
- *
- * Caller passes the already-folded list of active entries (latest row per
- * spanId, ACTIVE statuses only). The function counts entries that match
- * the agent on the same `stage`. The new row's own spanId is excluded so
- * re-recording a `scheduled` doesn't trip the cap on a span that's already
- * counted.
- */
-export declare function validateFanOutCap(stamped: DelegationEntry, activeEntries: DelegationEntry[], override?: number | null): void;
-/**
- * Find the latest active span for a given `(stage, agent)`
- * pair in the supplied ledger entries. Returns the row whose latest
- * status (after the latest-by-spanId fold) is still in the active set
- * (`scheduled | launched | acknowledged`).
- *
- * Run-scope is **strict**: only entries whose `runId` matches the
- * supplied `runId` are folded. Entries with empty/missing `runId`
- * (older ledgers without explicit run scoping) are treated as NOT belonging
- * to the current run, so they cannot keep an old span "active" across
- * a fresh dispatch and trip a spurious `dispatch_duplicate`. This
- * Ensures a slice-builder that ran in run-1 does not block a
- * slice-builder scheduled in run-2.
- *
- * keep in sync with the inline copy in
- * `src/content/hooks.ts::delegationRecordScript`.
- */
-export declare function findActiveSpanForPair(stage: string, agent: string, runId: string, ledger: DelegationLedger): DelegationEntry | null;
-export declare function appendDelegation(projectRoot: string, entry: DelegationEntry): Promise<void>;
-/**
- * Aggregate the fulfillment mode cclaw expects for the active harness set.
- * Priority native > generic-dispatch > role-switch > waiver — the best
- * available mode wins so mixed installs (e.g. claude + codex) inherit the
- * strongest guarantee.
- */
-export declare function expectedFulfillmentMode(fallbacks: SubagentFallback[]): DelegationFulfillmentMode;
-export declare function checkMandatoryDelegations(projectRoot: string, stage: FlowStage, options?: {
-    repairFeatureSystem?: boolean;
-    /**
-     * Optional task class for the active run. When set to
-     * `"software-bugfix"`, the mandatory delegation gate is skipped
-     * entirely. Callers that don't classify the run leave
-     * this undefined; the function then falls back to
-     * `flowState.taskClass` (persisted in `flow-state.json`) so the
-     * Bugfix-skip remains active across the `cclaw advance-stage`
-     * code path even when no caller forwards an explicit override.
-     */
-    taskClass?: MandatoryDelegationTaskClass | null;
-}): Promise<{
-    satisfied: boolean;
-    missing: string[];
-    waived: string[];
-    staleIgnored: string[];
-    /** Delegation rows missing required evidence under a role-switch fallback. */
-    missingEvidence: string[];
-    /** Native isolated completion rows that lack dispatch proof. */
-    missingDispatchProof: string[];
-    /** Legacy inferred isolated completions accepted only as migration warnings. */
-    legacyInferredCompletions: string[];
-    /** Current-run event log lines that could not be parsed. */
-    corruptEventLines: number[];
-    /** Current-run scheduled rows with no terminal row sharing the same spanId. */
-    staleWorkers: string[];
-    /** Expected fulfillment mode for the active harness set. */
-    expectedMode: DelegationFulfillmentMode;
-    /**
-     * `true` when `mandatoryAgentsFor` returned [] for
-     * this (track, taskClass) combination — i.e. the gate was skipped
-     * entirely on quick track or software-bugfix runs. The skip is also
-     * recorded as a `mandatory_delegations_skipped_by_track` event in
-     * `delegation-events.jsonl` for audit traceability.
-     */
-    skippedByTrack: boolean;
-}>;
-/**
- * Append a non-delegation audit event recording
- * that one or more required artifact-validation findings were
- * demoted from blocking to advisory because the active run is on a
- * small-fix lane (`track === "quick"` or `taskClass === "software-bugfix"`).
- *
- * The event mirrors `mandatory_delegations_skipped_by_track`
- * audit pattern: best-effort write to `delegation-events.jsonl`, no
- * agent payload, recognized by `readDelegationEvents` so it does not
- * corrupt downstream parsers. Failures are swallowed.
- */
-export declare function recordArtifactValidationDemotedByTrack(projectRoot: string, params: {
-    stage: FlowStage;
-    track: FlowState["track"];
-    taskClass: MandatoryDelegationTaskClass | null;
-    runId: string;
-    sections: string[];
-}): Promise<void>;
-/**
- * Append a non-delegation audit event recording
- * that the scope-stage Expansion Strategist (`product-discovery`)
- * delegation requirement was skipped because the active run is on a
- * small-fix lane (`track === "quick"` or `taskClass === "software-bugfix"`).
- *
- * Mirrors the `mandatory_delegations_skipped_by_track`
- * audit pattern: best-effort write to `delegation-events.jsonl`, no
- * agent payload, recognized by `readDelegationEvents` so it does not
- * corrupt downstream parsers. Failures are swallowed.
- */
-export declare function recordExpansionStrategistSkippedByTrack(projectRoot: string, params: {
-    track: FlowState["track"];
-    taskClass: MandatoryDelegationTaskClass | null;
-    runId: string;
-    selectedScopeMode: string;
-}): Promise<void>;