@sayknow-cli/coding-agent 0.3.6 → 0.3.7

package/dist/types/skc-runtime/ultragoal-runtime.d.ts

@@ -0,0 +1,303 @@
+import type { WorkflowHudSummary } from "../skill-state/active-state";
+export type UltragoalSkcGoalMode = "aggregate" | "per-story";
+export type UltragoalGoalStatus = "pending" | "active" | "complete" | "failed" | "blocked" | "review_blocked" | "superseded";
+export interface UltragoalGoal {
+    id: string;
+    title: string;
+    objective: string;
+    status: UltragoalGoalStatus;
+    createdAt: string;
+    updatedAt: string;
+    startedAt?: string;
+    completedAt?: string;
+    evidence?: string;
+    steering?: Record<string, unknown>;
+    completionVerification?: UltragoalCompletionVerification;
+}
+export interface UltragoalPlan {
+    version: 1;
+    brief: string;
+    skcGoalMode: UltragoalSkcGoalMode;
+    skcObjective: string;
+    skcObjectiveAliases?: string[];
+    goals: UltragoalGoal[];
+    createdAt: string;
+    updatedAt: string;
+    [key: string]: unknown;
+}
+export type UltragoalReceiptKind = "per-goal" | "final-aggregate";
+export interface UltragoalCompletionVerification {
+    schemaVersion: 1;
+    receiptId: string;
+    verifiedAt: string;
+    goalId: string;
+    receiptKind: UltragoalReceiptKind;
+    goalStatusBeforeCheckpoint: UltragoalGoalStatus;
+    skcGoalMode: UltragoalSkcGoalMode;
+    skcObjective: string;
+    qualityGateHash: string;
+    planGeneration: string;
+    basis: {
+        planHashBeforeCheckpoint: string;
+        latestRelevantLedgerEventIdBeforeCheckpoint: string | null;
+        goalUpdatedAtBeforeCheckpoint: string;
+        relevantGoalIdsBeforeCheckpoint: string[];
+        requiredGoalSetHashBeforeCheckpoint: string;
+    };
+    checkpointLedgerEventId: string;
+}
+export interface UltragoalLedgerEvent extends JsonObject {
+    eventId?: string;
+    event?: string;
+    goalId?: string;
+    timestamp?: string;
+}
+export type UltragoalNudgeSurface = "pause" | "drop" | "ask" | "premature_complete";
+export type UltragoalNudgeTargetKind = "story" | "final_aggregate_receipt";
+export interface UltragoalNudgeLedgerEvent extends UltragoalLedgerEvent {
+    event: "nudge";
+    goalId: string;
+    targetKind: UltragoalNudgeTargetKind;
+    surface: UltragoalNudgeSurface;
+    attempt: number;
+    budget: number;
+    reason: string;
+    currentGoalObjective?: string;
+}
+export interface UltragoalNudgeTarget {
+    goalId: string;
+    targetKind: UltragoalNudgeTargetKind;
+}
+export type UltragoalNudgeOutcome = {
+    nudged: true;
+    attempt: number;
+    budget: number;
+    goalId: string;
+    targetKind: UltragoalNudgeTargetKind;
+    event: UltragoalNudgeLedgerEvent;
+} | {
+    nudged: false;
+    exhausted: true;
+    count: number;
+    budget: number;
+    goalId: string;
+    targetKind: UltragoalNudgeTargetKind;
+} | {
+    nudged: false;
+    inactive: true;
+    reason: string;
+};
+export interface UltragoalPaths {
+    dir: string;
+    briefPath: string;
+    goalsPath: string;
+    ledgerPath: string;
+}
+export interface UltragoalStatusSummary {
+    exists: boolean;
+    status: "missing" | "pending" | "active" | "complete" | "blocked" | "failed";
+    paths: UltragoalPaths;
+    skcObjective?: string;
+    currentGoal?: UltragoalGoal;
+    counts: Record<UltragoalGoalStatus, number>;
+    goals: UltragoalGoal[];
+    nudgeBudget?: number;
+    nudgeCount?: number;
+    nudgeRemaining?: number;
+    nudgeGoalId?: string;
+    nudgeTargetKind?: UltragoalNudgeTargetKind;
+}
+export interface UltragoalCommandResult {
+    reviewBlockerGoalIds?: string[];
+    createdReviewPlan?: boolean;
+    status: number;
+    stdout?: string;
+    stderr?: string;
+    createdPlan?: boolean;
+}
+interface JsonObject {
+    [key: string]: unknown;
+}
+export declare function hashStructuredValue(value: unknown): string;
+export declare function getUltragoalPaths(cwd: string, sessionId?: string | null): UltragoalPaths;
+export declare function readUltragoalLedger(cwd: string, sessionId?: string | null): Promise<UltragoalLedgerEvent[]>;
+export declare const DEFAULT_ULTRAGOAL_NUDGE_BUDGET = 10;
+/** Pure: count ledger `nudge` rows for an exact goalId. */
+export declare function countUltragoalNudges(ledger: readonly UltragoalLedgerEvent[], goalId: string): number;
+/**
+ * Resolve the per-story nudge budget. Project `./.skc/settings.json` overrides the
+ * user settings (`$SKC_CONFIG_DIR/settings.json` or `~/.skc/settings.json`), else the
+ * default. Mirrors the `skc.deepInterview.ambiguityThreshold` user+project precedence.
+ */
+export declare function resolveUltragoalNudgeBudget(cwd: string): Promise<{
+    budget: number;
+    source: string;
+}>;
+/**
+ * Pure canonical selector shared by guards and status so `nudgeGoalId` can never
+ * diverge between what a guard consumes and what status displays. Prefers the active
+ * current-goal objective, then active > pending > failed (matching `chooseNextGoal`),
+ * then the aggregate final-receipt target when all stories are complete but the
+ * aggregate run still needs a final receipt. Returns null for verified-complete or
+ * absent/unrelated plans.
+ */
+export declare function selectUltragoalNudgeTarget(plan: UltragoalPlan, options?: {
+    currentGoalObjective?: string;
+    retryFailed?: boolean;
+}): UltragoalNudgeTarget | null;
+/**
+ * Atomic consuming writer. Locks the ledger path, rereads + counts nudge rows for the
+ * target story, and appends exactly one `nudge` row inside the same critical section
+ * only while budget remains. Reuses the lockless `appendLedger` inside the lock (it
+ * does not acquire a conflicting lock), so concurrent guarded attempts cannot both
+ * observe `count = budget - 1` and overshoot the budget.
+ */
+export declare function recordUltragoalNudgeIfBudgetRemaining(input: {
+    cwd: string;
+    sessionId?: string | null;
+    target: UltragoalNudgeTarget;
+    surface: UltragoalNudgeSurface;
+    budget: number;
+    reason: string;
+    currentGoalObjective?: string;
+}): Promise<UltragoalNudgeOutcome>;
+export declare function computeUltragoalPlanGeneration(input: {
+    plan: UltragoalPlan;
+    ledger: readonly UltragoalLedgerEvent[];
+    goal: UltragoalGoal;
+    receiptKind: UltragoalReceiptKind;
+    beforeStatus: UltragoalGoalStatus;
+    excludeEventId?: string;
+    targetGoalUpdatedAt?: string;
+}): {
+    planGeneration: string;
+    basis: UltragoalCompletionVerification["basis"];
+};
+export declare function readUltragoalPlan(cwd: string, sessionId?: string | null): Promise<UltragoalPlan | null>;
+export declare function getUltragoalStatus(cwd: string, sessionId?: string | null): Promise<UltragoalStatusSummary>;
+export declare function buildUltragoalHudSummary(summary: UltragoalStatusSummary, latestLedger?: UltragoalLedgerEvent): WorkflowHudSummary;
+export declare function createUltragoalPlan(input: {
+    cwd: string;
+    brief: string;
+    skcGoalMode?: UltragoalSkcGoalMode;
+    sessionId?: string | null;
+}): Promise<UltragoalPlan>;
+export interface UltragoalRunCompletionState {
+    requiredGoals: UltragoalGoal[];
+    incompleteGoals: UltragoalGoal[];
+    nextGoal?: UltragoalGoal;
+    allComplete: boolean;
+    hasBlockers: boolean;
+    needsFinalAggregateReceipt: boolean;
+}
+export declare function getUltragoalRunCompletionState(plan: UltragoalPlan, options?: {
+    retryFailed?: boolean;
+}): UltragoalRunCompletionState;
+export declare function startNextUltragoalGoal(input: {
+    cwd: string;
+    retryFailed?: boolean;
+    sessionId?: string | null;
+}): Promise<{
+    plan: UltragoalPlan;
+    goal?: UltragoalGoal;
+    allComplete: boolean;
+}>;
+type SurfaceFamily = "web" | "cli" | "native" | "api-package" | "algorithm-math" | "unknown";
+type UltragoalChangeStatus = "added" | "modified" | "deleted" | "renamed" | "copied" | "unknown";
+type UltragoalChangeCategory = "code" | "generated-binding" | "tool" | "settings-registry" | "prompt-doc-behavior" | "docs-static" | "other";
+interface UltragoalChangeSetPath extends JsonObject {
+    path: string;
+    status: UltragoalChangeStatus;
+    oldPath?: string;
+    category?: UltragoalChangeCategory;
+}
+interface UltragoalChangeSet extends JsonObject {
+    source: "checkpoint-git" | "review-pr" | "review-branch" | "review-worktree" | "review-spec";
+    baseRef?: string;
+    headRef?: string;
+    mergeBase?: string;
+    paths: UltragoalChangeSetPath[];
+    rawDiffStat?: string;
+    trusted: true;
+}
+export declare function normalizeSurfaceToken(value: string): string;
+export declare function surfaceFamily(value: string): SurfaceFamily;
+export interface ReplayProcessHandle {
+    readonly exited: Promise<number>;
+    kill(signal?: number | NodeJS.Signals): void;
+}
+export declare function waitForReplayProcessWithTimeout(process: ReplayProcessHandle, timeoutMs: number, graceMs?: number): Promise<number>;
+export declare function validateExecutorQaRedTeamEvidenceForReview(cwd: string, executorQa: Record<string, unknown>, options?: {
+    mode?: "review";
+    changeSet?: UltragoalChangeSet;
+}): Promise<void>;
+export declare function checkpointUltragoalGoal(input: {
+    cwd: string;
+    goalId: string;
+    status: UltragoalGoalStatus;
+    evidence: string;
+    qualityGateJson?: string;
+}): Promise<UltragoalPlan>;
+export interface UltragoalCheckpointContinuation {
+    plan: UltragoalPlan;
+    checkpointedGoal: UltragoalGoal;
+    nextGoal?: UltragoalGoal;
+    startedNext: boolean;
+    allComplete: boolean;
+    incompleteGoals: UltragoalGoal[];
+}
+export declare function checkpointAndContinueUltragoalGoal(input: {
+    cwd: string;
+    goalId: string;
+    status: UltragoalGoalStatus;
+    evidence: string;
+    qualityGateJson?: string;
+    advanceNext?: boolean;
+    retryFailed?: boolean;
+}): Promise<UltragoalCheckpointContinuation>;
+export declare function addUltragoalSubgoal(input: {
+    cwd: string;
+    title: string;
+    objective: string;
+    evidence: string;
+    rationale: string;
+}): Promise<UltragoalPlan>;
+export declare function recordUltragoalReviewBlockers(input: {
+    cwd: string;
+    goalId: string;
+    title: string;
+    objective: string;
+    evidence: string;
+}): Promise<UltragoalPlan>;
+export type UltragoalBlockerClassification = "human_blocked" | "resolvable";
+/**
+ * Record an audited blocker triage classification in the durable ledger. A
+ * `human_blocked` classification is the only thing that authorizes
+ * `goal({"op":"pause"})` while an Ultragoal run is active; `resolvable` is an
+ * audit note and never unblocks pause.
+ */
+export declare function recordUltragoalBlockerClassification(input: {
+    cwd: string;
+    classification: UltragoalBlockerClassification;
+    evidence: string;
+    goalId?: string;
+}): Promise<UltragoalLedgerEvent>;
+type UltragoalReviewContractStrength = "strong" | "thin-derived";
+interface UltragoalReviewFinding extends JsonObject {
+    severity: "blocker";
+    message: string;
+}
+interface UltragoalReviewResult extends JsonObject {
+    verdict: "pass" | "fail" | "inconclusive: weak-contract";
+    contractStrength: UltragoalReviewContractStrength;
+    cleanPassEligible: boolean;
+    source: JsonObject;
+    findings: UltragoalReviewFinding[];
+    artifactValidationSummary: JsonObject;
+    weakContractCapApplied: boolean;
+    blockerGoalIds?: string[];
+}
+export declare function resolveGitBase(cwd: string, branch?: string): Promise<string>;
+export declare function runUltragoalReview(cwd: string, args: readonly string[]): Promise<UltragoalReviewResult>;
+export declare function runNativeUltragoalCommand(args: string[], cwd?: string): Promise<UltragoalCommandResult>;
+export {};

package/dist/types/skc-runtime/workflow-command-ref.d.ts

@@ -0,0 +1,43 @@
+import { type CanonicalSkcWorkflowSkill } from "../skill-state/canonical-skills";
+export type CommandRefVisibility = "public" | "hidden" | "planned";
+export type CommandRefIncludeWhen = "implemented-only" | "planned";
+export interface CommandRefCommand {
+    tokens: string[];
+    rendered: string;
+    visibility: CommandRefVisibility;
+    includeWhen: CommandRefIncludeWhen;
+    note?: string;
+}
+export interface CommandRefExample {
+    label?: string;
+    bytes: string;
+}
+export interface CommandRefBridge {
+    from: string;
+    to: string;
+    rendered: string;
+}
+export interface CommandRefBlock {
+    skill: CanonicalSkcWorkflowSkill;
+    blockId: string;
+    sourcePath: string;
+    renderOrder: number;
+    markers: {
+        start: string;
+        end: string;
+    };
+    commands: CommandRefCommand[];
+    examples: CommandRefExample[];
+    aliasesAndBridges: CommandRefBridge[];
+    notes: string[];
+}
+export interface RenderedCommandRefBlock {
+    skill: CanonicalSkcWorkflowSkill;
+    blockId: string;
+    markers: CommandRefBlock["markers"];
+    bytes: string;
+}
+export declare const WORKFLOW_COMMAND_REF_BLOCKS: readonly CommandRefBlock[];
+export declare function listCommandRefBlocks(skill?: CanonicalSkcWorkflowSkill): CommandRefBlock[];
+export declare function renderCommandRefBlock(skill: CanonicalSkcWorkflowSkill, blockId?: string): RenderedCommandRefBlock;
+export declare function isCanonicalSkcWorkflowSkill(value: string): value is CanonicalSkcWorkflowSkill;

package/dist/types/skc-runtime/workflow-manifest.d.ts

@@ -0,0 +1,54 @@
+/**
+ * TypeScript is the authoritative source of truth for SKC workflow manifests.
+ * Any JSON manifest projection is derived from this module and must never be
+ * hand-edited.
+ */
+import { type CanonicalSkcWorkflowSkill } from "../skill-state/canonical-skills";
+export interface WorkflowState {
+    id: string;
+    initial?: boolean;
+    terminal?: boolean;
+}
+export interface WorkflowTransition {
+    from: string;
+    to: string;
+    verb: string;
+}
+export interface WorkflowVerb {
+    name: string;
+    planned?: boolean;
+    /** Invocation surface that exposes this verb in the real CLI parser. */
+    surface?: "state-action" | "command-positional" | "command-flag";
+}
+export interface TypedArgSpec {
+    name: string;
+    type: "string" | "number" | "boolean" | "enum" | "object";
+    enumValues?: string[];
+    required?: boolean;
+    appliesToVerbs?: string[];
+    planned?: boolean;
+}
+export interface RetentionPolicy {
+    category: string;
+    keep?: number;
+    maxAgeDays?: number;
+}
+export interface SkillManifest {
+    skill: CanonicalSkcWorkflowSkill;
+    states: WorkflowState[];
+    initialState: string;
+    terminalStates: string[];
+    transitions: WorkflowTransition[];
+    verbs: WorkflowVerb[];
+    typedArgs: TypedArgSpec[];
+    retention: RetentionPolicy[];
+    hudFields: string[];
+    graphLabel: string;
+}
+export declare const WORKFLOW_MANIFEST: Record<CanonicalSkcWorkflowSkill, SkillManifest>;
+export declare function getSkillManifest(skill: CanonicalSkcWorkflowSkill): SkillManifest;
+export declare function isKnownWorkflowState(skill: CanonicalSkcWorkflowSkill, state: string): boolean;
+export declare function isValidTransition(skill: CanonicalSkcWorkflowSkill, from: string, to: string): boolean;
+export declare function listVerbs(skill: CanonicalSkcWorkflowSkill): string[];
+export declare function typedArgsFor(skill: CanonicalSkcWorkflowSkill, verb: string): TypedArgSpec[];
+export declare function serializeManifestProjection(): string;

package/dist/types/skill-state/active-state.d.ts

@@ -0,0 +1,109 @@
+import { CANONICAL_SKC_WORKFLOW_SKILLS, type CanonicalSkcWorkflowSkill } from "./canonical-skills";
+import type { WorkflowStateReceipt } from "./workflow-state-contract";
+export declare const SKILL_ACTIVE_STATE_FILE = "skill-active-state.json";
+export { CANONICAL_SKC_WORKFLOW_SKILLS, type CanonicalSkcWorkflowSkill };
+export type WorkflowHudSeverity = "info" | "warning" | "blocked" | "error" | "success";
+export interface WorkflowHudChip {
+    label: string;
+    value?: string;
+    priority?: number;
+    severity?: WorkflowHudSeverity;
+}
+export interface WorkflowHudSummary {
+    version: 1;
+    summary?: string;
+    chips?: WorkflowHudChip[];
+    details?: WorkflowHudChip[];
+    severity?: WorkflowHudSeverity;
+    updated_at?: string;
+}
+export type { WorkflowStateReceipt } from "./workflow-state-contract";
+export interface ActiveSubskillEntry {
+    plugin: string;
+    subskillName: string;
+    parent: string;
+    bindsTo: string;
+    phase: string;
+    activationArg: string;
+    filePath: string;
+    toolPaths: string[];
+}
+export interface SkillActiveEntry {
+    skill: string;
+    phase?: string;
+    active?: boolean;
+    activated_at?: string;
+    updated_at?: string;
+    session_id?: string;
+    thread_id?: string;
+    turn_id?: string;
+    hud?: WorkflowHudSummary;
+    stale?: boolean;
+    receipt?: WorkflowStateReceipt;
+    handoff_from?: string;
+    handoff_to?: string;
+    handoff_at?: string;
+    active_subskills?: ActiveSubskillEntry[];
+    source_state_revision?: number;
+}
+export interface SkillActiveState {
+    version?: number;
+    active?: boolean;
+    skill?: string;
+    keyword?: string;
+    phase?: string;
+    activated_at?: string;
+    updated_at?: string;
+    source?: string;
+    session_id?: string;
+    thread_id?: string;
+    turn_id?: string;
+    initialized_mode?: CanonicalSkcWorkflowSkill;
+    initialized_state_path?: string;
+    active_skills?: SkillActiveEntry[];
+    active_subskills?: ActiveSubskillEntry[];
+    [key: string]: unknown;
+}
+export interface SkillActiveStatePaths {
+    rootPath: string;
+    sessionPath: string;
+}
+export interface SyncSkillActiveStateOptions {
+    cwd: string;
+    skill: string;
+    active: boolean;
+    phase?: string;
+    sessionId?: string;
+    threadId?: string;
+    turnId?: string;
+    nowIso?: string;
+    source?: string;
+    hud?: WorkflowHudSummary;
+    receipt?: WorkflowStateReceipt;
+    handoff_from?: string;
+    handoff_to?: string;
+    handoff_at?: string;
+    active_subskills?: ActiveSubskillEntry[];
+    sourceRevision?: number;
+}
+export declare function normalizeWorkflowHudSummary(raw: unknown): WorkflowHudSummary | undefined;
+export declare function isCanonicalSkcWorkflowSkill(skill: string): skill is CanonicalSkcWorkflowSkill;
+export declare function listActiveSkills(raw: unknown): SkillActiveEntry[];
+export declare function normalizeSkillActiveState(raw: unknown): SkillActiveState | null;
+export declare function getSkillActiveStatePaths(cwd: string, sessionId?: string): SkillActiveStatePaths;
+export declare function collapsePlanningPipeline(entries: readonly SkillActiveEntry[]): SkillActiveEntry[];
+export declare function readVisibleSkillActiveState(cwd: string, sessionId?: string): Promise<SkillActiveState | null>;
+export declare function syncSkillActiveState(options: SyncSkillActiveStateOptions): Promise<void>;
+export interface ApplyHandoffOptions {
+    cwd: string;
+    caller: SyncSkillActiveStateOptions;
+    callee: SyncSkillActiveStateOptions;
+    /** Shared timestamp; falls back to new Date().toISOString(). */
+    nowIso?: string;
+    /** When true, read errors other than ENOENT propagate. */
+    strict?: boolean;
+}
+/**
+ * Atomically apply a workflow-skill handoff to the session-scoped active state.
+ */
+export declare function applyHandoffToActiveState(options: ApplyHandoffOptions): Promise<void>;

package/dist/types/skill-state/canonical-skills.d.ts

@@ -0,0 +1,3 @@
+/** Native-free canonical SKC workflow skill identifiers. */
+export declare const CANONICAL_SKC_WORKFLOW_SKILLS: readonly ["deep-interview", "ralplan", "ultragoal", "team"];
+export type CanonicalSkcWorkflowSkill = (typeof CANONICAL_SKC_WORKFLOW_SKILLS)[number];

package/dist/types/skill-state/deep-interview-mutation-guard.d.ts

@@ -0,0 +1,38 @@
+import type { AgentTool } from "@sayknow-cli/agent-core";
+export declare const DEEP_INTERVIEW_MUTATION_BLOCK_MESSAGE = "Deep-interview phase boundary: continue gathering context/questions/risks and emit a handoff/spec before code edits. Mutation tools and patch execution are blocked while deep-interview is active; finalize specs through `skc deep-interview --write --stage final` or hand off to an execution phase.";
+export declare const WORKFLOW_STATE_MUTATION_BLOCK_MESSAGE = ".skc workflow state and artifacts are runtime-owned. Agent mutation tools cannot edit `.skc/**`; use the sanctioned `skc` CLI instead.";
+export declare const RALPLAN_MUTATION_BLOCK_MESSAGE = "Ralplan planning phase boundary: keep refining the consensus plan and persist plan artifacts through `skc ralplan --write` (stage scratch files under a temp dir if needed). Product-code mutation tools and patch execution are blocked while ralplan is active; mutate only after the plan is approved and execution begins.";
+export declare const ULTRAGOAL_GOAL_PLANNING_MUTATION_BLOCK_MESSAGE = "Ultragoal goal-planning phase boundary: finish goal planning and record goals through `skc ultragoal` before editing code. Product-code mutation tools and patch execution are blocked until goal planning completes and execution begins.";
+type ToolWithEditMode = AgentTool & {
+    mode?: unknown;
+    customWireName?: unknown;
+};
+export interface DeepInterviewMutationGuardInput {
+    cwd: string;
+    sessionId?: string;
+    threadId?: string;
+    tool: ToolWithEditMode;
+    args: unknown;
+    forceOverride?: boolean;
+    enforceWorkflowState?: boolean;
+}
+export interface DeepInterviewMutationDecision {
+    blocked: boolean;
+    message?: string;
+    targets: string[];
+    reason?: string;
+    command?: string;
+}
+export declare function assertDeepInterviewMutationRawPathsAllowed(input: {
+    cwd: string;
+    sessionId?: string;
+    threadId?: string;
+    rawPaths: string[];
+    forceOverride?: boolean;
+}): Promise<void>;
+export declare function getDeepInterviewMutationDecision(input: DeepInterviewMutationGuardInput): Promise<DeepInterviewMutationDecision>;
+export declare function assertDeepInterviewMutationAllowed(input: DeepInterviewMutationGuardInput): Promise<void>;
+export declare const getWorkflowMutationDecision: typeof getDeepInterviewMutationDecision;
+export declare const assertWorkflowMutationAllowed: typeof assertDeepInterviewMutationAllowed;
+export declare const assertWorkflowMutationRawPathsAllowed: typeof assertDeepInterviewMutationRawPathsAllowed;
+export {};

package/dist/types/skill-state/initial-phase.d.ts

@@ -0,0 +1,12 @@
+import type { CanonicalSkcWorkflowSkill } from "./active-state";
+/**
+ * Canonical initial phase for each SKC workflow skill. Used by both
+ * `recordSkillActivation` (UserPromptSubmit hook seeding initial mode-state)
+ * and the `skc state <caller> handoff --to <callee>` runtime when promoting
+ * the callee.
+ *
+ * Keeping this mapping in a neutral skill-state module avoids cycles between
+ * `skc-runtime/state-runtime.ts` and `hooks/skill-state.ts` (which pulls in
+ * session-manager and ultragoal verification code).
+ */
+export declare function initialPhaseForSkill(skill: CanonicalSkcWorkflowSkill | string): string;

package/dist/types/skill-state/workflow-hud.d.ts

@@ -0,0 +1,83 @@
+import type { WorkflowHudSummary } from "./active-state";
+interface WorkflowGateHudState {
+    approvalStatus?: string;
+    blockedReason?: string;
+    nextAction?: string;
+}
+interface DeepInterviewHudState extends WorkflowGateHudState {
+    phase?: string;
+    ambiguity?: number;
+    threshold?: number;
+    roundCount?: number;
+    targetComponent?: string;
+    weakestDimension?: string;
+    specStatus?: string;
+    updatedAt?: string;
+}
+interface RalplanHudState extends WorkflowGateHudState {
+    stage?: string;
+    waiting?: string;
+    iteration?: number;
+    iterationFromIndex?: number;
+    stages?: string;
+    verdict?: string;
+    latestSummary?: string;
+    pendingApproval?: boolean;
+    updatedAt?: string;
+}
+interface UltragoalLikeGoal {
+    id: string;
+    title: string;
+    status: string;
+}
+interface UltragoalHudState extends WorkflowGateHudState {
+    status: string;
+    currentGoal?: UltragoalLikeGoal;
+    counts: Record<string, number>;
+    goals: UltragoalLikeGoal[];
+    latestLedgerEvent?: {
+        event?: string;
+        goalId?: string;
+        timestamp?: string;
+        kind?: string;
+        evidence?: string;
+    };
+    updatedAt?: string;
+}
+interface TeamHudWorker {
+    id: string;
+    status?: string;
+}
+interface TeamHudState extends WorkflowGateHudState {
+    phase: string;
+    task_total: number;
+    task_counts: Record<string, number>;
+    workers: TeamHudWorker[];
+    updated_at?: string;
+    latestEvent?: {
+        type?: string;
+        worker?: string;
+        message?: string;
+    };
+    latestMessage?: {
+        from_worker?: string;
+        body?: string;
+    };
+}
+export declare function buildDeepInterviewHudSummary(state: DeepInterviewHudState): WorkflowHudSummary;
+export interface DeepInterviewHudDeriveOptions {
+    phase?: string;
+    specStatus?: string;
+    updatedAt?: string;
+}
+/**
+ * Single source of deep-interview HUD derivation. Reads a complete (normalized)
+ * mode-state envelope so recorder, `skc state write`, reconcile, seed, and handoff
+ * all produce identical chips. Topology-aware `target`/`weakest` come from
+ * `state.topology`; `legacy_missing` topology omits those chips (no synthetic values).
+ */
+export declare function deriveDeepInterviewHud(payload: Record<string, unknown>, options?: DeepInterviewHudDeriveOptions): WorkflowHudSummary;
+export declare function buildRalplanHudSummary(state: RalplanHudState): WorkflowHudSummary;
+export declare function buildUltragoalHudSummary(state: UltragoalHudState): WorkflowHudSummary;
+export declare function buildTeamHudSummary(state: TeamHudState): WorkflowHudSummary;
+export {};