@harness-engineering/types 0.9.0 → 0.9.2

package/dist/index.d.ts

@@ -1,814 +1,945 @@
 /**
- * Represents a ticket created in an external tracking service.
+ * Result type for consistent error handling across the toolkit.
  */
-interface ExternalTicket {
-    /** External identifier, e.g., "github:owner/repo#42" */
-    externalId: string;
-    /** URL to the ticket in the external service */
-    url: string;
-}
+type Result<T, E = Error> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
 /**
- * Current state of a ticket in the external service.
- * Pulled during syncFromExternal.
+ * Creates a successful Result.
  */
-interface ExternalTicketState {
-    /** External identifier */
-    externalId: string;
-    /** Ticket title in the external service */
-    title: string;
-    /** External status (e.g., "open", "closed") */
-    status: string;
-    /** External labels (used for status disambiguation on GitHub) */
-    labels: string[];
-    /** Current assignee in the external service, or null */
-    assignee: string | null;
-}
+declare function Ok<T>(value: T): Result<T, never>;
 /**
- * Result of a sync operation. Collects successes and errors per-feature.
+ * Creates a failed Result.
  */
-interface SyncResult {
-    /** Tickets created during this sync */
-    created: ExternalTicket[];
-    /** External IDs of tickets that were updated */
-    updated: string[];
-    /** Assignment changes detected during pull */
-    assignmentChanges: Array<{
-        feature: string;
-        from: string | null;
-        to: string | null;
-    }>;
-    /** Per-feature errors (sync never throws) */
-    errors: Array<{
-        featureOrId: string;
-        error: Error;
-    }>;
-}
+declare function Err<E>(error: E): Result<never, E>;
 /**
- * Configuration for external tracker sync.
+ * Type guard to check if a Result is successful.
  */
-interface TrackerSyncConfig {
-    /** Adapter kind -- narrowed to GitHub-only for now */
-    kind: 'github';
-    /** Repository in "owner/repo" format (for GitHub) */
-    repo?: string;
-    /** Labels auto-applied to created tickets for filtering + identification */
-    labels?: string[];
-    /** Maps roadmap status -> external status string */
-    statusMap: Record<FeatureStatus, string>;
-    /**
-     * Maps external status (+ optional label) -> roadmap status.
-     * Compound keys like "open:in-progress" express state + label.
-     * Optional — when absent, syncFromExternal preserves current roadmap status.
-     */
-    reverseStatusMap?: Record<string, FeatureStatus>;
-}
-
+declare function isOk<T, E>(result: Result<T, E>): result is {
+    ok: true;
+    value: T;
+};
 /**
- * Token usage statistics for an agent turn or session.
+ * Type guard to check if a Result is failed.
  */
-interface TokenUsage {
-    /** Number of tokens used in the input (prompt) */
-    inputTokens: number;
-    /** Number of tokens generated in the output (response) */
-    outputTokens: number;
-    /** Combined total tokens used */
-    totalTokens: number;
-}
+declare function isErr<T, E>(result: Result<T, E>): result is {
+    ok: false;
+    error: E;
+};
+
 /**
- * Reference to a blocking issue.
+ * A single step in a multi-skill workflow.
  */
-interface BlockerRef {
-    /** Unique ID of the blocker */
-    id: string | null;
-    /** Human-readable identifier (e.g., "CORE-123") */
-    identifier: string | null;
-    /** Current state of the blocker */
-    state: string | null;
+interface WorkflowStep {
+    /** The skill to execute (e.g., "detect-doc-drift") */
+    skill: string;
+    /** Name of the artifact this step produces */
+    produces: string;
+    /** Name of the artifact this step expects as input */
+    expects?: string;
+    /** Whether failure of this step stops the workflow */
+    gate?: 'pass-required' | 'advisory';
 }
 /**
- * Representation of a work item (issue/feature) in a tracker.
+ * Definition of a sequence of steps to achieve a goal.
  */
-interface Issue {
-    /** Unique ID in the tracking system */
-    id: string;
-    /** Human-readable identifier (e.g., "CORE-123") */
-    identifier: string;
-    /** Title or headline of the issue */
-    title: string;
-    /** Detailed description, if available */
-    description: string | null;
-    /** Numerical priority (lower is typically higher priority) */
-    priority: number | null;
-    /** Current lifecycle state */
-    state: string;
-    /** Name of the git branch associated with this issue */
-    branchName: string | null;
-    /** Direct URL to the issue in the tracker */
-    url: string | null;
-    /** List of labels or tags */
-    labels: string[];
-    /** References to issues that block this one */
-    blockedBy: BlockerRef[];
-    /** ISO timestamp of creation */
-    createdAt: string | null;
-    /** ISO timestamp of last update */
-    updatedAt: string | null;
+interface Workflow {
+    /** Descriptive name of the workflow */
+    name: string;
+    /** Ordered list of steps */
+    steps: WorkflowStep[];
 }
 /**
- * Categories of errors that can occur during agent execution.
+ * Possible outcomes for a single workflow step.
  */
-type AgentErrorCategory = 'agent_not_found' | 'invalid_workspace_cwd' | 'response_timeout' | 'turn_timeout' | 'process_exit' | 'response_error' | 'turn_failed' | 'turn_cancelled' | 'turn_input_required';
+type StepOutcome = 'pass' | 'fail' | 'skipped';
 /**
- * Error returned by an agent backend.
+ * Detailed result of a workflow step execution.
  */
-interface AgentError {
-    /** Machine-readable category */
-    category: AgentErrorCategory;
-    /** Human-readable message */
-    message: string;
-    /** Optional additional context */
-    details?: unknown;
+interface WorkflowStepResult {
+    /** The step that was executed */
+    step: WorkflowStep;
+    /** The outcome of the execution */
+    outcome: StepOutcome;
+    /** Path to the produced artifact, if any */
+    artifact?: string;
+    /** Error message if outcome is 'fail' */
+    error?: string;
+    /** Execution time in milliseconds */
+    durationMs: number;
 }
 /**
- * Parameters for starting a new agent session.
+ * Final result of a complete workflow execution.
  */
-interface SessionStartParams {
-    /** Absolute path to the workspace directory */
-    workspacePath: string;
-    /** Permission level for the agent (e.g., "readonly", "full") */
-    permissionMode: string;
-    /** List of tool names the agent is allowed to use */
-    allowedTools?: string[];
-    /** Custom system instructions for the agent */
-    systemPrompt?: string;
+interface WorkflowResult {
+    /** The workflow that was executed */
+    workflow: Workflow;
+    /** Results for each step in the workflow */
+    stepResults: WorkflowStepResult[];
+    /** Whether the overall workflow passed (all required gates passed) */
+    pass: boolean;
+    /** Total execution time in milliseconds */
+    totalDurationMs: number;
 }
+
 /**
- * Represents an active session with an agent backend.
+ * Stability classification for prompt caching.
+ *
+ * - `static`    -- changes only on deploy/update (skills index, tool definitions, SKILL.md)
+ * - `session`   -- stable within a session, varies between sessions (graph context, project state)
+ * - `ephemeral` -- changes per call (tool responses, diff content, file reads)
  */
-interface AgentSession {
-    /** Unique ID for the session */
-    sessionId: string;
-    /** Workspace associated with this session */
-    workspacePath: string;
-    /** Name of the backend provider */
-    backendName: string;
-    /** ISO timestamp when the session started */
-    startedAt: string;
-}
+type StabilityTier = 'static' | 'session' | 'ephemeral';
 /**
- * Parameters for a single interaction (turn) with an agent.
+ * Metadata describing a content block's caching stability.
  */
-interface TurnParams {
-    /** ID of the active session */
-    sessionId: string;
-    /** User or system prompt for this turn */
-    prompt: string;
-    /** Whether this is a continuation of a previous turn */
-    isContinuation: boolean;
+interface StabilityMetadata {
+    /** The stability classification of this content */
+    stability: StabilityTier;
+    /** Advisory TTL hint (e.g., '1h', '5m') -- provider adapters decide actual TTL */
+    ttlHint?: string;
 }
+
 /**
- * Event emitted by an agent during a turn.
+ * Predefined cognitive modes for skills.
  */
-interface AgentEvent {
-    /** Event type (e.g., "thought", "tool_call", "output") */
-    type: string;
-    /** ISO timestamp */
-    timestamp: string;
-    /** Optional subtype for finer-grained classification */
-    subtype?: string;
-    /** Token usage snapshot if available */
-    usage?: TokenUsage;
-    /** Event payload */
-    content?: unknown;
-    /** Session ID if not implicit */
-    sessionId?: string;
-}
+declare const STANDARD_COGNITIVE_MODES: readonly ["adversarial-reviewer", "constructive-architect", "meticulous-implementer", "diagnostic-investigator", "advisory-guide", "meticulous-verifier"];
 /**
- * Result of a completed agent turn.
+ * Cognitive mode of a skill, determining its behavior and persona.
  */
-interface TurnResult {
-    /** Whether the turn completed successfully */
-    success: boolean;
-    /** ID of the session */
-    sessionId: string;
-    /** Cumulative usage for this turn */
-    usage: TokenUsage;
-    /** Error message if success is false */
-    error?: string;
+type CognitiveMode = (typeof STANDARD_COGNITIVE_MODES)[number] | (string & {});
+/**
+ * Static metadata for a skill.
+ */
+interface SkillMetadata {
+    /** Unique name of the skill */
+    name: string;
+    /** Semantic version string */
+    version: string;
+    /** Brief description of what the skill does */
+    description: string;
+    /** The cognitive mode this skill operates in */
+    cognitive_mode?: CognitiveMode;
+    /** Caching stability tier -- defaults to inferred from content type if omitted */
+    stability?: StabilityTier;
 }
 /**
- * Interface for agent backend implementations (Claude, Mock, etc.)
+ * Contextual information for a skill execution.
  */
-interface AgentBackend {
-    /** Unique name of the backend */
-    readonly name: string;
-    /** Starts a new session */
-    startSession(params: SessionStartParams): Promise<Result<AgentSession, AgentError>>;
-    /** Runs a turn and streams events */
-    runTurn(session: AgentSession, params: TurnParams): AsyncGenerator<AgentEvent, TurnResult, void>;
-    /** Stops and cleans up a session */
-    stopSession(session: AgentSession): Promise<Result<void, AgentError>>;
-    /** Verifies connectivity and health */
-    healthCheck(): Promise<Result<void, AgentError>>;
+interface SkillContext {
+    /** Name of the executing skill */
+    skillName: string;
+    /** Current pipeline phase */
+    phase: string;
+    /** Files relevant to the current execution */
+    files: string[];
+    /** Optional token budget — uses a plain record to avoid cross-package deps. */
+    tokenBudget?: Record<string, number>;
+    /** Additional metadata */
+    metadata: Record<string, unknown>;
 }
 /**
- * Interface for issue tracking systems (Roadmap, Linear, GitHub, etc.)
+ * Context for a single turn in a multi-turn skill interaction.
  */
-interface IssueTrackerClient {
-    /** Fetches issues eligible for agent assignment */
-    fetchCandidateIssues(): Promise<Result<Issue[], Error>>;
-    /** Fetches issues in specific lifecycle states */
-    fetchIssuesByStates(stateNames: string[]): Promise<Result<Issue[], Error>>;
-    /** Fetches current state for a set of issue IDs */
-    fetchIssueStatesByIds(issueIds: string[]): Promise<Result<Map<string, Issue>, Error>>;
+interface TurnContext extends SkillContext {
+    /** Current turn number (1-indexed) */
+    turnNumber: number;
+    /** Results from previous turns in the same session */
+    previousResults: unknown[];
 }
 /**
- * Configuration for an issue tracker adapter.
+ * Error reported by a skill.
  */
-interface TrackerConfig {
-    /** Adapter kind (e.g., "roadmap", "linear") */
-    kind: string;
-    /** API endpoint if applicable */
-    endpoint?: string;
-    /** API key or token */
-    apiKey?: string;
-    /** Project slug or identifier */
-    projectSlug?: string;
-    /** Local file path for file-based trackers */
-    filePath?: string;
-    /** States considered "ready for work" */
-    activeStates: string[];
-    /** States considered "finished" */
-    terminalStates: string[];
-}
+type SkillError = {
+    /** Machine-readable error code */
+    code: string;
+    /** Human-readable error message */
+    message: string;
+    /** Phase in which the error occurred */
+    phase: string;
+};
 /**
- * Polling interval configuration.
+ * Result of a skill execution.
  */
-interface PollingConfig {
-    /** Interval in milliseconds */
-    intervalMs: number;
-}
+type SkillResult = {
+    /** Whether the skill achieved its goal */
+    success: boolean;
+    /** List of artifact paths produced */
+    artifacts: string[];
+    /** One-line summary of the outcome */
+    summary: string;
+};
 /**
- * Workspace management configuration.
+ * Lifecycle hooks for skills.
  */
-interface WorkspaceConfig {
-    /** Root directory where agent workspaces are created */
-    root: string;
+interface SkillLifecycleHooks {
+    /** Called before the skill starts execution */
+    preExecution?: (context: SkillContext) => SkillContext | null;
+    /** Called before each turn in a multi-turn interaction */
+    perTurn?: (context: TurnContext) => TurnContext | null;
+    /** Called after the skill completes execution */
+    postExecution?: (context: SkillContext, result: SkillResult) => void;
 }
+
 /**
- * Lifecycle hooks configuration.
+ * Names of standard CI checks.
  */
-interface HooksConfig {
-    /** Script to run after creating a workspace */
-    afterCreate: string | null;
-    /** Script to run before starting an agent */
-    beforeRun: string | null;
-    /** Script to run after an agent completes */
-    afterRun: string | null;
-    /** Script to run before removing a workspace */
-    beforeRemove: string | null;
-    /** Maximum time allowed for hook execution */
-    timeoutMs: number;
-}
+type CICheckName = 'validate' | 'deps' | 'docs' | 'entropy' | 'security' | 'perf' | 'phase-gate' | 'arch' | 'traceability';
 /**
- * Configuration for the agent runner.
+ * Status of a CI check.
  */
-interface AgentConfig {
-    /** Backend type to use */
-    backend: string;
-    /** Command to launch the agent if applicable */
-    command?: string;
-    /** Model name/identifier */
-    model?: string;
-    /** API key for the agent provider */
-    apiKey?: string;
-    /** Global limit on concurrent agents */
-    maxConcurrentAgents: number;
-    /** Maximum turns allowed per session */
-    maxTurns: number;
-    /** Maximum backoff for retries */
-    maxRetryBackoffMs: number;
-    /** Concurrency limits partitioned by issue state */
-    maxConcurrentAgentsByState: Record<string, number>;
-    /** Policy for approving tool calls */
-    approvalPolicy?: string;
-    /** Policy for execution environment isolation */
-    sandboxPolicy?: string;
-    /** Timeout for a single turn */
-    turnTimeoutMs: number;
-    /** Timeout for reading from the agent */
-    readTimeoutMs: number;
-    /** Timeout for agent inactivity */
-    stallTimeoutMs: number;
-}
+type CICheckStatus = 'pass' | 'fail' | 'warn' | 'skip';
 /**
- * Internal server configuration.
+ * A specific issue found during a CI check.
  */
-interface ServerConfig {
-    /** Port to listen on (null to disable) */
-    port: number | null;
+interface CICheckIssue {
+    /** Severity level */
+    severity: 'error' | 'warning';
+    /** Descriptive message */
+    message: string;
+    /** Path to the affected file */
+    file?: string;
+    /** Line number in the affected file */
+    line?: number;
 }
 /**
- * Root workflow configuration object.
+ * Result of a single CI check execution.
  */
-interface WorkflowConfig {
-    /** Issue tracker settings */
-    tracker: TrackerConfig;
-    /** Polling loop settings */
-    polling: PollingConfig;
-    /** Workspace settings */
-    workspace: WorkspaceConfig;
-    /** Lifecycle hook settings */
-    hooks: HooksConfig;
-    /** Agent execution settings */
-    agent: AgentConfig;
-    /** Server settings */
-    server: ServerConfig;
+interface CICheckResult {
+    /** Name of the check */
+    name: CICheckName;
+    /** Final status of the check */
+    status: CICheckStatus;
+    /** List of issues discovered */
+    issues: CICheckIssue[];
+    /** Execution time in milliseconds */
+    durationMs: number;
 }
 /**
- * Complete workflow definition including config and prompts.
+ * Summary counts for a set of CI checks.
  */
-interface WorkflowDefinition {
-    /** Orchestrator configuration */
-    config: WorkflowConfig;
-    /** Template used to generate agent prompts */
-    promptTemplate: string;
+interface CICheckSummary {
+    /** Total number of checks run */
+    total: number;
+    /** Number of passing checks */
+    passed: number;
+    /** Number of failing checks */
+    failed: number;
+    /** Number of checks with warnings */
+    warnings: number;
+    /** Number of skipped checks */
+    skipped: number;
 }
-
 /**
- * Extended entry for cost tracking storage and display.
- * Composes TokenUsage — does not extend it.
+ * Final report for a CI run.
  */
-interface UsageRecord {
-    /** Harness session identifier */
-    sessionId: string;
-    /** ISO 8601 timestamp of the usage event */
+interface CICheckReport {
+    /** Schema version */
+    version: 1;
+    /** Name of the project */
+    project: string;
+    /** ISO timestamp of the run */
     timestamp: string;
-    /** Token counts for this event */
-    tokens: TokenUsage;
-    /** Tokens used to create prompt cache entries */
-    cacheCreationTokens?: number;
-    /** Tokens read from prompt cache */
-    cacheReadTokens?: number;
-    /** Model identifier (e.g., "claude-sonnet-4-20250514") */
-    model?: string;
-    /** Cost in integer microdollars (USD * 1,000,000), calculated at read time */
-    costMicroUSD?: number;
+    /** Detailed results for each check */
+    checks: CICheckResult[];
+    /** Aggregated summary */
+    summary: CICheckSummary;
+    /** Process exit code suggested for the CI runner */
+    exitCode: 0 | 1 | 2;
 }
 /**
- * Per-model pricing rates, all in USD per 1 million tokens.
+ * Severity level that should trigger a CI failure.
  */
-interface ModelPricing {
-    /** Input token cost per 1M tokens */
-    inputPer1M: number;
-    /** Output token cost per 1M tokens */
-    outputPer1M: number;
-    /** Cache read cost per 1M tokens (not all models support caching) */
-    cacheReadPer1M?: number;
-    /** Cache write/creation cost per 1M tokens */
-    cacheWritePer1M?: number;
-}
+type CIFailOnSeverity = 'error' | 'warning';
 /**
- * Aggregated usage for a single calendar day.
+ * Configuration options for the CI command.
  */
-interface DailyUsage {
-    /** ISO 8601 date string (YYYY-MM-DD) */
-    date: string;
-    /** Number of distinct sessions that had activity on this day */
-    sessionCount: number;
-    /** Summed token counts across all sessions */
-    tokens: TokenUsage;
-    /** Summed cache creation tokens (omitted if no cache data) */
-    cacheCreationTokens?: number;
-    /** Summed cache read tokens (omitted if no cache data) */
-    cacheReadTokens?: number;
-    /** Total cost in integer microdollars, null if any session has unknown pricing */
-    costMicroUSD: number | null;
-    /** Distinct model identifiers seen on this day */
-    models: string[];
+interface CICheckOptions {
+    /** Checks to skip */
+    skip?: CICheckName[];
+    /** Severity level that causes failure */
+    failOn?: CIFailOnSeverity;
+    /** Custom config file path */
+    configPath?: string;
 }
 /**
- * Aggregated usage for a single session across all its turns.
+ * Supported CI platforms.
  */
-interface SessionUsage {
-    /** Harness session identifier */
-    sessionId: string;
-    /** ISO 8601 timestamp of the first event in this session */
-    firstTimestamp: string;
-    /** ISO 8601 timestamp of the last event in this session */
-    lastTimestamp: string;
-    /** Summed token counts across all turns */
-    tokens: TokenUsage;
-    /** Summed cache creation tokens (omitted if no cache data) */
-    cacheCreationTokens?: number;
-    /** Summed cache read tokens (omitted if no cache data) */
-    cacheReadTokens?: number;
-    /** Model identifier (may be populated from CC data) */
-    model?: string;
-    /** Total cost in integer microdollars, null if pricing unavailable */
-    costMicroUSD: number | null;
-    /** Data source: 'harness', 'claude-code', or 'merged' */
-    source: 'harness' | 'claude-code' | 'merged';
+type CIPlatform = 'github' | 'gitlab' | 'generic';
+/**
+ * Options for initializing CI configuration.
+ */
+interface CIInitOptions {
+    /** Target CI platform */
+    platform?: CIPlatform;
+    /** Checks to enable */
+    checks?: CICheckName[];
 }
 
 /**
- * Session-scoped accumulative state types.
- *
- * Session memory allows skills to append to shared sections (terminology,
- * decisions, constraints, risks, openQuestions, evidence) rather than
- * overwriting. Each entry is timestamped and tagged with the authoring skill.
- *
- * @see docs/changes/ai-foundations-integration/proposal.md
+ * Valid statuses for a roadmap feature.
  */
+type FeatureStatus = 'backlog' | 'planned' | 'in-progress' | 'done' | 'blocked';
 /**
- * Names of accumulative session sections.
- * Runtime array used for iteration and validation.
+ * Priority override levels for roadmap features.
+ * When present, priority replaces positional ordering as the primary sort key.
  */
-declare const SESSION_SECTION_NAMES: readonly ["terminology", "decisions", "constraints", "risks", "openQuestions", "evidence"];
+type Priority = 'P0' | 'P1' | 'P2' | 'P3';
 /**
- * Union type of valid session section names.
+ * A feature entry in the project roadmap.
  */
-type SessionSectionName = (typeof SESSION_SECTION_NAMES)[number];
+interface RoadmapFeature {
+    /** Feature name (from the H3 heading, without "Feature:" prefix) */
+    name: string;
+    /** Current status */
+    status: FeatureStatus;
+    /** Relative path to the spec file, or null if none */
+    spec: string | null;
+    /** Relative paths to plan files */
+    plans: string[];
+    /** Names of blocking features (textual references) */
+    blockedBy: string[];
+    /** One-line summary */
+    summary: string;
+    /** GitHub username, email, or display name — null if unassigned */
+    assignee: string | null;
+    /** Optional priority override — null uses positional ordering */
+    priority: Priority | null;
+    /** External tracker ID (e.g., "github:owner/repo#42") — null if not synced */
+    externalId: string | null;
+}
 /**
- * Lifecycle status of a session entry.
- * - `active` — current and relevant
- * - `resolved` — addressed or answered (e.g., an open question that was resolved)
- * - `superseded` — replaced by a newer entry
+ * A milestone grouping in the roadmap. The special "Backlog" milestone
+ * has `isBacklog: true` and appears as `## Backlog` instead of `## Milestone: <name>`.
  */
-type SessionEntryStatus = 'active' | 'resolved' | 'superseded';
+interface RoadmapMilestone {
+    /** Milestone name (e.g., "MVP Release") or "Backlog" */
+    name: string;
+    /** True for the special Backlog section */
+    isBacklog: boolean;
+    /** Features in this milestone, in document order */
+    features: RoadmapFeature[];
+}
 /**
- * A single entry in a session section.
- * Entries are append-only; skills mark them as `resolved` or `superseded`
- * rather than deleting.
+ * A single record in the assignment history log.
+ * Reassignment produces two records: 'unassigned' for previous, 'assigned' for new.
  */
-interface SessionEntry {
-    /** Auto-generated unique identifier */
-    id: string;
-    /** ISO 8601 timestamp of when the entry was created */
-    timestamp: string;
-    /** Name of the skill that authored this entry */
-    authorSkill: string;
-    /** The entry content (free-form text) */
-    content: string;
-    /** Lifecycle status of the entry */
-    status: SessionEntryStatus;
+interface AssignmentRecord {
+    /** Feature name */
+    feature: string;
+    /** Assignee identifier (username, email, or display name) */
+    assignee: string;
+    /** What happened */
+    action: 'assigned' | 'completed' | 'unassigned';
+    /** ISO date string (YYYY-MM-DD) */
+    date: string;
 }
 /**
- * Container mapping each section name to its array of entries.
- * Used as the shape of session-scoped state in `state.json`.
+ * YAML frontmatter of the roadmap file.
  */
-type SessionSections = {
-    [K in SessionSectionName]: SessionEntry[];
-};
+interface RoadmapFrontmatter {
+    /** Project name */
+    project: string;
+    /** Schema version (currently 1) */
+    version: number;
+    /** ISO date when roadmap was created */
+    created?: string;
+    /** ISO date when roadmap was last updated */
+    updated?: string;
+    /** ISO timestamp of last automated sync */
+    lastSynced: string;
+    /** ISO timestamp of last manual edit */
+    lastManualEdit: string;
+}
+/**
+ * Parsed roadmap document.
+ */
+interface Roadmap {
+    /** Parsed frontmatter */
+    frontmatter: RoadmapFrontmatter;
+    /** Milestones in document order (including Backlog) */
+    milestones: RoadmapMilestone[];
+    /** Assignment history records, in document order */
+    assignmentHistory: AssignmentRecord[];
+}
 
 /**
- * @harness-engineering/types
- *
- * Core types and interfaces for Harness Engineering toolkit
+ * Represents a ticket created in an external tracking service.
  */
+interface ExternalTicket {
+    /** External identifier, e.g., "github:owner/repo#42" */
+    externalId: string;
+    /** URL to the ticket in the external service */
+    url: string;
+}
 /**
- * Result type for consistent error handling across the toolkit.
+ * Current state of a ticket in the external service.
+ * Pulled during syncFromExternal.
  */
-type Result<T, E = Error> = {
-    ok: true;
-    value: T;
-} | {
-    ok: false;
-    error: E;
-};
+interface ExternalTicketState {
+    /** External identifier */
+    externalId: string;
+    /** Ticket title in the external service */
+    title: string;
+    /** External status (e.g., "open", "closed") */
+    status: string;
+    /** External labels (used for status disambiguation on GitHub) */
+    labels: string[];
+    /** Current assignee in the external service, or null */
+    assignee: string | null;
+}
 /**
- * Creates a successful Result.
+ * Result of a sync operation. Collects successes and errors per-feature.
  */
-declare function Ok<T>(value: T): Result<T, never>;
+interface SyncResult {
+    /** Tickets created during this sync */
+    created: ExternalTicket[];
+    /** External IDs of tickets that were updated */
+    updated: string[];
+    /** Assignment changes detected during pull */
+    assignmentChanges: Array<{
+        feature: string;
+        from: string | null;
+        to: string | null;
+    }>;
+    /** Per-feature errors (sync never throws) */
+    errors: Array<{
+        featureOrId: string;
+        error: Error;
+    }>;
+}
 /**
- * Creates a failed Result.
+ * Configuration for external tracker sync.
  */
-declare function Err<E>(error: E): Result<never, E>;
+interface TrackerSyncConfig {
+    /** Adapter kind -- narrowed to GitHub-only for now */
+    kind: 'github';
+    /** Repository in "owner/repo" format (for GitHub) */
+    repo?: string;
+    /** Labels auto-applied to created tickets for filtering + identification */
+    labels?: string[];
+    /** Maps roadmap status -> external status string */
+    statusMap: Record<FeatureStatus, string>;
+    /**
+     * Maps external status (+ optional label) -> roadmap status.
+     * Compound keys like "open:in-progress" express state + label.
+     * Optional — when absent, syncFromExternal preserves current roadmap status.
+     */
+    reverseStatusMap?: Record<string, FeatureStatus>;
+}
+
 /**
- * Type guard to check if a Result is successful.
+ * Token usage statistics for an agent turn or session.
  */
-declare function isOk<T, E>(result: Result<T, E>): result is {
-    ok: true;
-    value: T;
-};
+interface TokenUsage {
+    /** Number of tokens used in the input (prompt) */
+    inputTokens: number;
+    /** Number of tokens generated in the output (response) */
+    outputTokens: number;
+    /** Combined total tokens used */
+    totalTokens: number;
+    /** Tokens used to create a new cache entry (provider-specific) */
+    cacheCreationTokens?: number;
+    /** Tokens read from an existing cache entry (provider-specific) */
+    cacheReadTokens?: number;
+}
 /**
- * Type guard to check if a Result is failed.
+ * Reference to a blocking issue.
  */
-declare function isErr<T, E>(result: Result<T, E>): result is {
-    ok: false;
-    error: E;
-};
+interface BlockerRef {
+    /** Unique ID of the blocker */
+    id: string | null;
+    /** Human-readable identifier (e.g., "CORE-123") */
+    identifier: string | null;
+    /** Current state of the blocker */
+    state: string | null;
+}
 /**
- * A single step in a multi-skill workflow.
+ * Representation of a work item (issue/feature) in a tracker.
  */
-interface WorkflowStep {
-    /** The skill to execute (e.g., "detect-doc-drift") */
-    skill: string;
-    /** Name of the artifact this step produces */
-    produces: string;
-    /** Name of the artifact this step expects as input */
-    expects?: string;
-    /** Whether failure of this step stops the workflow */
-    gate?: 'pass-required' | 'advisory';
+interface Issue {
+    /** Unique ID in the tracking system */
+    id: string;
+    /** Human-readable identifier (e.g., "CORE-123") */
+    identifier: string;
+    /** Title or headline of the issue */
+    title: string;
+    /** Detailed description, if available */
+    description: string | null;
+    /** Numerical priority (lower is typically higher priority) */
+    priority: number | null;
+    /** Current lifecycle state */
+    state: string;
+    /** Name of the git branch associated with this issue */
+    branchName: string | null;
+    /** Direct URL to the issue in the tracker */
+    url: string | null;
+    /** List of labels or tags */
+    labels: string[];
+    /** References to issues that block this one */
+    blockedBy: BlockerRef[];
+    /** ISO timestamp of creation */
+    createdAt: string | null;
+    /** ISO timestamp of last update */
+    updatedAt: string | null;
+}
+/**
+ * Categories of errors that can occur during agent execution.
+ */
+type AgentErrorCategory = 'agent_not_found' | 'invalid_workspace_cwd' | 'response_timeout' | 'turn_timeout' | 'process_exit' | 'response_error' | 'turn_failed' | 'turn_cancelled' | 'turn_input_required';
+/**
+ * Error returned by an agent backend.
+ */
+interface AgentError {
+    /** Machine-readable category */
+    category: AgentErrorCategory;
+    /** Human-readable message */
+    message: string;
+    /** Optional additional context */
+    details?: unknown;
 }
 /**
- * Definition of a sequence of steps to achieve a goal.
+ * Parameters for starting a new agent session.
  */
-interface Workflow {
-    /** Descriptive name of the workflow */
-    name: string;
-    /** Ordered list of steps */
-    steps: WorkflowStep[];
+interface SessionStartParams {
+    /** Absolute path to the workspace directory */
+    workspacePath: string;
+    /** Permission level for the agent (e.g., "readonly", "full") */
+    permissionMode: string;
+    /** List of tool names the agent is allowed to use */
+    allowedTools?: string[];
+    /** Custom system instructions for the agent */
+    systemPrompt?: string;
 }
 /**
- * Possible outcomes for a single workflow step.
+ * Represents an active session with an agent backend.
  */
-type StepOutcome = 'pass' | 'fail' | 'skipped';
+interface AgentSession {
+    /** Unique ID for the session */
+    sessionId: string;
+    /** Workspace associated with this session */
+    workspacePath: string;
+    /** Name of the backend provider */
+    backendName: string;
+    /** ISO timestamp when the session started */
+    startedAt: string;
+}
 /**
- * Detailed result of a workflow step execution.
+ * Parameters for a single interaction (turn) with an agent.
  */
-interface WorkflowStepResult {
-    /** The step that was executed */
-    step: WorkflowStep;
-    /** The outcome of the execution */
-    outcome: StepOutcome;
-    /** Path to the produced artifact, if any */
-    artifact?: string;
-    /** Error message if outcome is 'fail' */
-    error?: string;
-    /** Execution time in milliseconds */
-    durationMs: number;
+interface TurnParams {
+    /** ID of the active session */
+    sessionId: string;
+    /** User or system prompt for this turn */
+    prompt: string;
+    /** Whether this is a continuation of a previous turn */
+    isContinuation: boolean;
 }
 /**
- * Final result of a complete workflow execution.
+ * Event emitted by an agent during a turn.
  */
-interface WorkflowResult {
-    /** The workflow that was executed */
-    workflow: Workflow;
-    /** Results for each step in the workflow */
-    stepResults: WorkflowStepResult[];
-    /** Whether the overall workflow passed (all required gates passed) */
-    pass: boolean;
-    /** Total execution time in milliseconds */
-    totalDurationMs: number;
+interface AgentEvent {
+    /** Event type (e.g., "thought", "tool_call", "output") */
+    type: string;
+    /** ISO timestamp */
+    timestamp: string;
+    /** Optional subtype for finer-grained classification */
+    subtype?: string;
+    /** Token usage snapshot if available */
+    usage?: TokenUsage;
+    /** Event payload */
+    content?: unknown;
+    /** Session ID if not implicit */
+    sessionId?: string;
 }
 /**
- * Predefined cognitive modes for skills.
+ * Result of a completed agent turn.
  */
-declare const STANDARD_COGNITIVE_MODES: readonly ["adversarial-reviewer", "constructive-architect", "meticulous-implementer", "diagnostic-investigator", "advisory-guide", "meticulous-verifier"];
+interface TurnResult {
+    /** Whether the turn completed successfully */
+    success: boolean;
+    /** ID of the session */
+    sessionId: string;
+    /** Cumulative usage for this turn */
+    usage: TokenUsage;
+    /** Error message if success is false */
+    error?: string;
+}
 /**
- * Cognitive mode of a skill, determining its behavior and persona.
+ * Interface for agent backend implementations (Claude, Mock, etc.)
  */
-type CognitiveMode = (typeof STANDARD_COGNITIVE_MODES)[number] | (string & {});
+interface AgentBackend {
+    /** Unique name of the backend */
+    readonly name: string;
+    /** Starts a new session */
+    startSession(params: SessionStartParams): Promise<Result<AgentSession, AgentError>>;
+    /** Runs a turn and streams events */
+    runTurn(session: AgentSession, params: TurnParams): AsyncGenerator<AgentEvent, TurnResult, void>;
+    /** Stops and cleans up a session */
+    stopSession(session: AgentSession): Promise<Result<void, AgentError>>;
+    /** Verifies connectivity and health */
+    healthCheck(): Promise<Result<void, AgentError>>;
+}
 /**
- * Static metadata for a skill.
+ * Interface for issue tracking systems (Roadmap, Linear, GitHub, etc.)
  */
-interface SkillMetadata {
-    /** Unique name of the skill */
-    name: string;
-    /** Semantic version string */
-    version: string;
-    /** Brief description of what the skill does */
-    description: string;
-    /** The cognitive mode this skill operates in */
-    cognitive_mode?: CognitiveMode;
+interface IssueTrackerClient {
+    /** Fetches issues eligible for agent assignment */
+    fetchCandidateIssues(): Promise<Result<Issue[], Error>>;
+    /** Fetches issues in specific lifecycle states */
+    fetchIssuesByStates(stateNames: string[]): Promise<Result<Issue[], Error>>;
+    /** Fetches current state for a set of issue IDs */
+    fetchIssueStatesByIds(issueIds: string[]): Promise<Result<Map<string, Issue>, Error>>;
 }
 /**
- * Contextual information for a skill execution.
+ * Configuration for an issue tracker adapter.
  */
-interface SkillContext {
-    /** Name of the executing skill */
-    skillName: string;
-    /** Current pipeline phase */
-    phase: string;
-    /** Files relevant to the current execution */
-    files: string[];
-    /** Optional token budget — uses a plain record to avoid cross-package deps. */
-    tokenBudget?: Record<string, number>;
-    /** Additional metadata */
-    metadata: Record<string, unknown>;
+interface TrackerConfig {
+    /** Adapter kind (e.g., "roadmap", "linear") */
+    kind: string;
+    /** API endpoint if applicable */
+    endpoint?: string;
+    /** API key or token */
+    apiKey?: string;
+    /** Project slug or identifier */
+    projectSlug?: string;
+    /** Local file path for file-based trackers */
+    filePath?: string;
+    /** States considered "ready for work" */
+    activeStates: string[];
+    /** States considered "finished" */
+    terminalStates: string[];
 }
 /**
- * Context for a single turn in a multi-turn skill interaction.
+ * Polling interval configuration.
  */
-interface TurnContext extends SkillContext {
-    /** Current turn number (1-indexed) */
-    turnNumber: number;
-    /** Results from previous turns in the same session */
-    previousResults: unknown[];
+interface PollingConfig {
+    /** Interval in milliseconds */
+    intervalMs: number;
 }
 /**
- * Error reported by a skill.
+ * Workspace management configuration.
  */
-type SkillError = {
-    /** Machine-readable error code */
-    code: string;
-    /** Human-readable error message */
-    message: string;
-    /** Phase in which the error occurred */
-    phase: string;
-};
+interface WorkspaceConfig {
+    /** Root directory where agent workspaces are created */
+    root: string;
+}
 /**
- * Names of standard CI checks.
+ * Lifecycle hooks configuration.
  */
-type CICheckName = 'validate' | 'deps' | 'docs' | 'entropy' | 'security' | 'perf' | 'phase-gate' | 'arch' | 'traceability';
+interface HooksConfig {
+    /** Script to run after creating a workspace */
+    afterCreate: string | null;
+    /** Script to run before starting an agent */
+    beforeRun: string | null;
+    /** Script to run after an agent completes */
+    afterRun: string | null;
+    /** Script to run before removing a workspace */
+    beforeRemove: string | null;
+    /** Maximum time allowed for hook execution */
+    timeoutMs: number;
+}
 /**
- * Status of a CI check.
+ * Configuration for the agent runner.
  */
-type CICheckStatus = 'pass' | 'fail' | 'warn' | 'skip';
+interface AgentConfig {
+    /** Backend type to use */
+    backend: string;
+    /** Command to launch the agent if applicable */
+    command?: string;
+    /** Model name/identifier */
+    model?: string;
+    /** API key for the agent provider */
+    apiKey?: string;
+    /** Global limit on concurrent agents */
+    maxConcurrentAgents: number;
+    /** Maximum turns allowed per session */
+    maxTurns: number;
+    /** Maximum backoff for retries */
+    maxRetryBackoffMs: number;
+    /** Concurrency limits partitioned by issue state */
+    maxConcurrentAgentsByState: Record<string, number>;
+    /** Policy for approving tool calls */
+    approvalPolicy?: string;
+    /** Policy for execution environment isolation */
+    sandboxPolicy?: string;
+    /** Timeout for a single turn */
+    turnTimeoutMs: number;
+    /** Timeout for reading from the agent */
+    readTimeoutMs: number;
+    /** Timeout for agent inactivity */
+    stallTimeoutMs: number;
+}
 /**
- * A specific issue found during a CI check.
+ * Internal server configuration.
  */
-interface CICheckIssue {
-    /** Severity level */
-    severity: 'error' | 'warning';
-    /** Descriptive message */
-    message: string;
-    /** Path to the affected file */
-    file?: string;
-    /** Line number in the affected file */
-    line?: number;
+interface ServerConfig {
+    /** Port to listen on (null to disable) */
+    port: number | null;
 }
 /**
- * Result of a single CI check execution.
+ * Root workflow configuration object.
  */
-interface CICheckResult {
-    /** Name of the check */
-    name: CICheckName;
-    /** Final status of the check */
-    status: CICheckStatus;
-    /** List of issues discovered */
-    issues: CICheckIssue[];
-    /** Execution time in milliseconds */
-    durationMs: number;
+interface WorkflowConfig {
+    /** Issue tracker settings */
+    tracker: TrackerConfig;
+    /** Polling loop settings */
+    polling: PollingConfig;
+    /** Workspace settings */
+    workspace: WorkspaceConfig;
+    /** Lifecycle hook settings */
+    hooks: HooksConfig;
+    /** Agent execution settings */
+    agent: AgentConfig;
+    /** Server settings */
+    server: ServerConfig;
 }
 /**
- * Summary counts for a set of CI checks.
+ * Complete workflow definition including config and prompts.
  */
-interface CICheckSummary {
-    /** Total number of checks run */
-    total: number;
-    /** Number of passing checks */
-    passed: number;
-    /** Number of failing checks */
-    failed: number;
-    /** Number of checks with warnings */
-    warnings: number;
-    /** Number of skipped checks */
-    skipped: number;
+interface WorkflowDefinition {
+    /** Orchestrator configuration */
+    config: WorkflowConfig;
+    /** Template used to generate agent prompts */
+    promptTemplate: string;
 }
+
 /**
- * Final report for a CI run.
+ * Extended entry for cost tracking storage and display.
+ * Composes TokenUsage — does not extend it.
  */
-interface CICheckReport {
-    /** Schema version */
-    version: 1;
-    /** Name of the project */
-    project: string;
-    /** ISO timestamp of the run */
+interface UsageRecord {
+    /** Harness session identifier */
+    sessionId: string;
+    /** ISO 8601 timestamp of the usage event */
     timestamp: string;
-    /** Detailed results for each check */
-    checks: CICheckResult[];
-    /** Aggregated summary */
-    summary: CICheckSummary;
-    /** Process exit code suggested for the CI runner */
-    exitCode: 0 | 1 | 2;
+    /** Token counts for this event */
+    tokens: TokenUsage;
+    /** Tokens used to create prompt cache entries */
+    cacheCreationTokens?: number;
+    /** Tokens read from prompt cache */
+    cacheReadTokens?: number;
+    /** Model identifier (e.g., "claude-sonnet-4-20250514") */
+    model?: string;
+    /** Cost in integer microdollars (USD * 1,000,000), calculated at read time */
+    costMicroUSD?: number;
 }
 /**
- * Severity level that should trigger a CI failure.
+ * Per-model pricing rates, all in USD per 1 million tokens.
  */
-type CIFailOnSeverity = 'error' | 'warning';
+interface ModelPricing {
+    /** Input token cost per 1M tokens */
+    inputPer1M: number;
+    /** Output token cost per 1M tokens */
+    outputPer1M: number;
+    /** Cache read cost per 1M tokens (not all models support caching) */
+    cacheReadPer1M?: number;
+    /** Cache write/creation cost per 1M tokens */
+    cacheWritePer1M?: number;
+}
 /**
- * Configuration options for the CI command.
+ * Aggregated usage for a single calendar day.
  */
-interface CICheckOptions {
-    /** Checks to skip */
-    skip?: CICheckName[];
-    /** Severity level that causes failure */
-    failOn?: CIFailOnSeverity;
-    /** Custom config file path */
-    configPath?: string;
+interface DailyUsage {
+    /** ISO 8601 date string (YYYY-MM-DD) */
+    date: string;
+    /** Number of distinct sessions that had activity on this day */
+    sessionCount: number;
+    /** Summed token counts across all sessions */
+    tokens: TokenUsage;
+    /** Summed cache creation tokens (omitted if no cache data) */
+    cacheCreationTokens?: number;
+    /** Summed cache read tokens (omitted if no cache data) */
+    cacheReadTokens?: number;
+    /** Total cost in integer microdollars, null if any session has unknown pricing */
+    costMicroUSD: number | null;
+    /** Distinct model identifiers seen on this day */
+    models: string[];
 }
 /**
- * Supported CI platforms.
+ * Aggregated usage for a single session across all its turns.
  */
-type CIPlatform = 'github' | 'gitlab' | 'generic';
+interface SessionUsage {
+    /** Harness session identifier */
+    sessionId: string;
+    /** ISO 8601 timestamp of the first event in this session */
+    firstTimestamp: string;
+    /** ISO 8601 timestamp of the last event in this session */
+    lastTimestamp: string;
+    /** Summed token counts across all turns */
+    tokens: TokenUsage;
+    /** Summed cache creation tokens (omitted if no cache data) */
+    cacheCreationTokens?: number;
+    /** Summed cache read tokens (omitted if no cache data) */
+    cacheReadTokens?: number;
+    /** Model identifier (may be populated from CC data) */
+    model?: string;
+    /** Total cost in integer microdollars, null if pricing unavailable */
+    costMicroUSD: number | null;
+    /** Data source: 'harness', 'claude-code', or 'merged' */
+    source: 'harness' | 'claude-code' | 'merged';
+}
+
 /**
- * Options for initializing CI configuration.
+ * A single skill invocation record stored in adoption.jsonl.
+ * One line per invocation, appended by the adoption-tracker hook.
  */
-interface CIInitOptions {
-    /** Target CI platform */
-    platform?: CIPlatform;
-    /** Checks to enable */
-    checks?: CICheckName[];
+interface SkillInvocationRecord {
+    /** Skill name (e.g., "harness-brainstorming") */
+    skill: string;
+    /** Session identifier */
+    session: string;
+    /** ISO 8601 timestamp when the skill started */
+    startedAt: string;
+    /** Duration in milliseconds */
+    duration: number;
+    /** Invocation outcome */
+    outcome: 'completed' | 'failed' | 'abandoned';
+    /** Phase names reached during the invocation */
+    phasesReached: string[];
+    /** Skill tier (1, 2, or 3). Absent when not derivable from events. */
+    tier?: number;
+    /** How the skill was triggered. Absent when not derivable from events. */
+    trigger?: string;
+}
+/**
+ * Aggregated summary for a single skill across multiple invocations.
+ */
+interface SkillAdoptionSummary {
+    /** Skill name */
+    skill: string;
+    /** Total invocation count */
+    invocations: number;
+    /** Fraction of invocations with outcome 'completed' (0-1) */
+    successRate: number;
+    /** Mean duration in milliseconds */
+    avgDuration: number;
+    /** ISO 8601 timestamp of the most recent invocation */
+    lastUsed: string;
+    /** Skill tier (absent when unknown) */
+    tier?: number;
+}
+/**
+ * Point-in-time snapshot of adoption metrics.
+ * Used by CLI commands and dashboard API.
+ */
+interface AdoptionSnapshot {
+    /** Time period: "daily", "weekly", or "all-time" */
+    period: string;
+    /** Total invocations in the period */
+    totalInvocations: number;
+    /** Count of distinct skills invoked */
+    uniqueSkills: number;
+    /** Top skills by invocation count */
+    topSkills: SkillAdoptionSummary[];
+    /** ISO 8601 timestamp when this snapshot was generated */
+    generatedAt: string;
 }
+
 /**
- * Result of a skill execution.
+ * Session-scoped accumulative state types.
+ *
+ * Session memory allows skills to append to shared sections (terminology,
+ * decisions, constraints, risks, openQuestions, evidence) rather than
+ * overwriting. Each entry is timestamped and tagged with the authoring skill.
+ *
+ * @see docs/changes/ai-foundations-integration/proposal.md
  */
-type SkillResult = {
-    /** Whether the skill achieved its goal */
-    success: boolean;
-    /** List of artifact paths produced */
-    artifacts: string[];
-    /** One-line summary of the outcome */
-    summary: string;
-};
 /**
- * Lifecycle hooks for skills.
+ * Names of accumulative session sections.
+ * Runtime array used for iteration and validation.
  */
-interface SkillLifecycleHooks {
-    /** Called before the skill starts execution */
-    preExecution?: (context: SkillContext) => SkillContext | null;
-    /** Called before each turn in a multi-turn interaction */
-    perTurn?: (context: TurnContext) => TurnContext | null;
-    /** Called after the skill completes execution */
-    postExecution?: (context: SkillContext, result: SkillResult) => void;
-}
+declare const SESSION_SECTION_NAMES: readonly ["terminology", "decisions", "constraints", "risks", "openQuestions", "evidence"];
 /**
- * Valid statuses for a roadmap feature.
+ * Union type of valid session section names.
  */
-type FeatureStatus = 'backlog' | 'planned' | 'in-progress' | 'done' | 'blocked';
+type SessionSectionName = (typeof SESSION_SECTION_NAMES)[number];
 /**
- * Priority override levels for roadmap features.
- * When present, priority replaces positional ordering as the primary sort key.
+ * Lifecycle status of a session entry.
+ * - `active` — current and relevant
+ * - `resolved` — addressed or answered (e.g., an open question that was resolved)
+ * - `superseded` — replaced by a newer entry
  */
-type Priority = 'P0' | 'P1' | 'P2' | 'P3';
+type SessionEntryStatus = 'active' | 'resolved' | 'superseded';
 /**
- * A feature entry in the project roadmap.
+ * A single entry in a session section.
+ * Entries are append-only; skills mark them as `resolved` or `superseded`
+ * rather than deleting.
  */
-interface RoadmapFeature {
-    /** Feature name (from the H3 heading, without "Feature:" prefix) */
-    name: string;
-    /** Current status */
-    status: FeatureStatus;
-    /** Relative path to the spec file, or null if none */
-    spec: string | null;
-    /** Relative paths to plan files */
-    plans: string[];
-    /** Names of blocking features (textual references) */
-    blockedBy: string[];
-    /** One-line summary */
-    summary: string;
-    /** GitHub username, email, or display name — null if unassigned */
-    assignee: string | null;
-    /** Optional priority override — null uses positional ordering */
-    priority: Priority | null;
-    /** External tracker ID (e.g., "github:owner/repo#42") — null if not synced */
-    externalId: string | null;
+interface SessionEntry {
+    /** Auto-generated unique identifier */
+    id: string;
+    /** ISO 8601 timestamp of when the entry was created */
+    timestamp: string;
+    /** Name of the skill that authored this entry */
+    authorSkill: string;
+    /** The entry content (free-form text) */
+    content: string;
+    /** Lifecycle status of the entry */
+    status: SessionEntryStatus;
 }
 /**
- * A milestone grouping in the roadmap. The special "Backlog" milestone
- * has `isBacklog: true` and appears as `## Backlog` instead of `## Milestone: <name>`.
+ * Container mapping each section name to its array of entries.
+ * Used as the shape of session-scoped state in `state.json`.
  */
-interface RoadmapMilestone {
-    /** Milestone name (e.g., "MVP Release") or "Backlog" */
-    name: string;
-    /** True for the special Backlog section */
-    isBacklog: boolean;
-    /** Features in this milestone, in document order */
-    features: RoadmapFeature[];
-}
+type SessionSections = {
+    [K in SessionSectionName]: SessionEntry[];
+};
+
 /**
- * A single record in the assignment history log.
- * Reassignment produces two records: 'unassigned' for previous, 'assigned' for new.
+ * Project-level telemetry configuration stored in harness.config.json.
+ * Only the on/off toggle lives here -- identity is in .harness/telemetry.json.
  */
-interface AssignmentRecord {
-    /** Feature name */
-    feature: string;
-    /** Assignee identifier (username, email, or display name) */
-    assignee: string;
-    /** What happened */
-    action: 'assigned' | 'completed' | 'unassigned';
-    /** ISO date string (YYYY-MM-DD) */
-    date: string;
+interface TelemetryConfig {
+    /** Whether telemetry collection is enabled. Default: true. */
+    enabled: boolean;
 }
 /**
- * YAML frontmatter of the roadmap file.
+ * Optional identity fields stored in .harness/telemetry.json (gitignored).
+ * Each field is independently opt-in.
  */
-interface RoadmapFrontmatter {
-    /** Project name */
-    project: string;
-    /** Schema version (currently 1) */
-    version: number;
-    /** ISO date when roadmap was created */
-    created?: string;
-    /** ISO date when roadmap was last updated */
-    updated?: string;
-    /** ISO timestamp of last automated sync */
-    lastSynced: string;
-    /** ISO timestamp of last manual edit */
-    lastManualEdit: string;
+interface TelemetryIdentity {
+    project?: string;
+    team?: string;
+    alias?: string;
 }
 /**
- * Parsed roadmap document.
+ * Resolved consent state after merging env vars, config, and identity file.
+ * Discriminated union: when allowed is false, no identity or installId fields exist.
  */
-interface Roadmap {
-    /** Parsed frontmatter */
-    frontmatter: RoadmapFrontmatter;
-    /** Milestones in document order (including Backlog) */
-    milestones: RoadmapMilestone[];
-    /** Assignment history records, in document order */
-    assignmentHistory: AssignmentRecord[];
+type ConsentState = {
+    allowed: true;
+    identity: TelemetryIdentity;
+    installId: string;
+} | {
+    allowed: false;
+};
+/**
+ * A single telemetry event payload for PostHog HTTP batch API.
+ */
+interface TelemetryEvent {
+    /** Event name, e.g. "skill_invocation", "session_end" */
+    event: string;
+    /** installId (anonymous) or alias (identified) */
+    distinctId: string;
+    properties: {
+        installId: string;
+        os: string;
+        nodeVersion: string;
+        harnessVersion: string;
+        skillName?: string;
+        duration?: number;
+        outcome?: 'success' | 'failure';
+        phasesReached?: string[];
+        project?: string;
+        team?: string;
+    };
+    /** ISO 8601 timestamp */
+    timestamp: string;
 }
 
-export { type AgentBackend, type AgentConfig, type AgentError, type AgentErrorCategory, type AgentEvent, type AgentSession, type AssignmentRecord, type BlockerRef, type CICheckIssue, type CICheckName, type CICheckOptions, type CICheckReport, type CICheckResult, type CICheckStatus, type CICheckSummary, type CIFailOnSeverity, type CIInitOptions, type CIPlatform, type CognitiveMode, type DailyUsage, Err, type ExternalTicket, type ExternalTicketState, type FeatureStatus, type HooksConfig, type Issue, type IssueTrackerClient, type ModelPricing, Ok, type PollingConfig, type Priority, type Result, type Roadmap, type RoadmapFeature, type RoadmapFrontmatter, type RoadmapMilestone, SESSION_SECTION_NAMES, STANDARD_COGNITIVE_MODES, type ServerConfig, type SessionEntry, type SessionEntryStatus, type SessionSectionName, type SessionSections, type SessionStartParams, type SessionUsage, type SkillContext, type SkillError, type SkillLifecycleHooks, type SkillMetadata, type SkillResult, type StepOutcome, type SyncResult, type TokenUsage, type TrackerConfig, type TrackerSyncConfig, type TurnContext, type TurnParams, type TurnResult, type UsageRecord, type Workflow, type WorkflowConfig, type WorkflowDefinition, type WorkflowResult, type WorkflowStep, type WorkflowStepResult, type WorkspaceConfig, isErr, isOk };
+export { type AdoptionSnapshot, type AgentBackend, type AgentConfig, type AgentError, type AgentErrorCategory, type AgentEvent, type AgentSession, type AssignmentRecord, type BlockerRef, type CICheckIssue, type CICheckName, type CICheckOptions, type CICheckReport, type CICheckResult, type CICheckStatus, type CICheckSummary, type CIFailOnSeverity, type CIInitOptions, type CIPlatform, type CognitiveMode, type ConsentState, type DailyUsage, Err, type ExternalTicket, type ExternalTicketState, type FeatureStatus, type HooksConfig, type Issue, type IssueTrackerClient, type ModelPricing, Ok, type PollingConfig, type Priority, type Result, type Roadmap, type RoadmapFeature, type RoadmapFrontmatter, type RoadmapMilestone, SESSION_SECTION_NAMES, STANDARD_COGNITIVE_MODES, type ServerConfig, type SessionEntry, type SessionEntryStatus, type SessionSectionName, type SessionSections, type SessionStartParams, type SessionUsage, type SkillAdoptionSummary, type SkillContext, type SkillError, type SkillInvocationRecord, type SkillLifecycleHooks, type SkillMetadata, type SkillResult, type StabilityMetadata, type StabilityTier, type StepOutcome, type SyncResult, type TelemetryConfig, type TelemetryEvent, type TelemetryIdentity, type TokenUsage, type TrackerConfig, type TrackerSyncConfig, type TurnContext, type TurnParams, type TurnResult, type UsageRecord, type Workflow, type WorkflowConfig, type WorkflowDefinition, type WorkflowResult, type WorkflowStep, type WorkflowStepResult, type WorkspaceConfig, isErr, isOk };