@sayknow-cli/coding-agent 0.4.1 → 0.4.3

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

@@ -0,0 +1,433 @@
+import type { WorkflowHudSummary } from "../skill-state/active-state";
+export { computeUltragoalPlanGeneration, receiptRelevantGoals } from "./ultragoal-receipt-freshness";
+export { captureUltragoalRecoverySnapshot, parseStrictTerminalTranscript, persistUltragoalRecoveryDecision, planUltragoalOwnerLossRecovery, type UltragoalOwnerLossReceipt, type UltragoalRecoveryBinding, type UltragoalRecoveryDecision, type UltragoalRecoverySnapshot, validateOwnerLossBinding, validateRawUltragoalEvidence, validateRecoveryAdmission, validateRecoveryPath, } from "./ultragoal-owner-loss-recovery";
+export type UltragoalSkcGoalMode = "aggregate" | "per-story";
+export type UltragoalGoalStatus = "pending" | "active" | "complete" | "failed" | "blocked" | "review_blocked" | "superseded";
+export type UltragoalPipelineMetadataSource = "original_plan_graph" | "legacy_brief_only" | "steering";
+export type UltragoalPipelineOverlapState = "none" | "open" | "joined_clean" | "blocked_disjoint_continue" | "quarantine_required" | "rebaseline_complete";
+export interface UltragoalPipelineTargets extends JsonObject {
+    files: string[];
+    surfaces: string[];
+}
+export interface UltragoalPipelineMetadata extends JsonObject {
+    schemaVersion: 1;
+    goalId: string;
+    source: UltragoalPipelineMetadataSource;
+    eligible: boolean;
+    dependsOn: string[];
+    independentOf: string[];
+    targets: UltragoalPipelineTargets;
+    metadataHash: string;
+    overlap: UltragoalPipelineOverlapState;
+    overlapId?: string;
+    priorGoalId?: string;
+    nextGoalId?: string;
+    blockerFootprints?: UltragoalPipelineTargets[];
+    invalidationReason?: string;
+    invalidatedAt?: string;
+}
+export interface UltragoalGoalMetadataInput {
+    schemaVersion: 1;
+    goalId: string;
+    source: UltragoalPipelineMetadataSource;
+    dependsOn?: string[];
+    independentOf?: string[];
+    targets?: Partial<UltragoalPipelineTargets>;
+}
+export interface UltragoalValidationBatchMetadata extends JsonObject {
+    schemaVersion: 1;
+    batchId: string;
+    memberIds: string[];
+    finalGoalId: string;
+    mode: "aggregate-only";
+    metadataHash: string;
+}
+export interface UltragoalValidationBatchInput {
+    schemaVersion: 1;
+    batchId: string;
+    memberIds: string[];
+    finalGoalId: string;
+}
+export interface UltragoalPipelineOverlapHandles extends JsonObject {
+    review: JsonObject;
+    qa: JsonObject;
+    implementation: JsonObject;
+}
+export interface UltragoalPipelineOverlapReceipt extends JsonObject {
+    ok: true;
+    event: string;
+    overlap_id: string;
+    prior_goal_id: string;
+    next_goal_id?: string;
+    goal_id?: string;
+    status?: UltragoalPipelineOverlapState;
+    next_goal_status?: UltragoalGoalStatus;
+    goals_path: string;
+    ledger_path: string;
+}
+export type UltragoalPipelineLedgerEventName = "pipeline_overlap_started" | "pipeline_overlap_joined" | "pipeline_overlap_blocked" | "pipeline_overlap_quarantined" | "pipeline_overlap_rebaselined";
+export interface UltragoalPipelineLedgerEvent extends UltragoalLedgerEvent {
+    event: UltragoalPipelineLedgerEventName;
+    schemaVersion: 1;
+    overlapId: string;
+    priorGoalId: string;
+    nextGoalId: string;
+}
+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;
+    pipelineMetadata?: UltragoalPipelineMetadata;
+    validationBatch?: UltragoalValidationBatchMetadata;
+}
+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;
+    validationBatch?: {
+        schemaVersion: 1;
+        role: "deferred-member";
+        batchId: string;
+        memberIds: string[];
+        finalGoalId: string;
+        metadataHash: string;
+        changeSetHash: string;
+    } | {
+        schemaVersion: 1;
+        role: "batch-close";
+        batchId: string;
+        memberIds: string[];
+        finalGoalId: string;
+        memberMetadataHashes: Record<string, string>;
+        memberReceiptIds: Record<string, string>;
+        memberCheckpointLedgerEventIds: Record<string, string>;
+        memberChangeSetHashes: Record<string, string>;
+        unionHash: 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;
+    pipelineOverlap?: JsonObject;
+}
+export interface UltragoalCommandResult {
+    reviewBlockerGoalIds?: string[];
+    createdReviewPlan?: boolean;
+    status: number;
+    stdout?: string;
+    stderr?: string;
+    createdPlan?: boolean;
+}
+export interface JsonObject {
+    [key: string]: unknown;
+}
+export declare function currentUltragoalSessionId(cwd: string): string;
+export declare const PASSED_STATUS = "passed";
+export declare function hashStructuredValue(value: unknown): string;
+export declare function getUltragoalPaths(cwd: string, sessionId?: string | null): UltragoalPaths;
+export declare function isEnoent(error: unknown): boolean;
+export declare function appendLedger(cwd: string, event: JsonObject, sessionId?: string | null): Promise<UltragoalLedgerEvent>;
+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 writePlan(cwd: string, plan: UltragoalPlan, sessionId?: string | null): Promise<void>;
+export declare function nonEmptyString(value: unknown): string | null;
+export declare function stringArray(value: unknown): string[] | null;
+export declare function hashPipelineMetadata(metadata: Omit<UltragoalPipelineMetadata, "metadataHash">): string;
+export declare function validateValidationBatchPipelineExclusion(goal: UltragoalGoal): void;
+export declare function targetsAreDisjoint(left: UltragoalPipelineTargets, right: UltragoalPipelineTargets): boolean;
+export declare function targetsOverlap(left: UltragoalPipelineTargets, right: UltragoalPipelineTargets): boolean;
+export declare function requireNonEmptyPipelineTargets(value: unknown, fieldName: string): UltragoalPipelineTargets;
+export declare function collectPipelineBlockerFootprints(result: JsonObject, fieldName: string): UltragoalPipelineTargets[];
+export declare function pipelinePeer(plan: UltragoalPlan, metadata: UltragoalPipelineMetadata): UltragoalGoal | undefined;
+export declare function handleIdsFromValue(value: JsonObject | JsonObject[], fieldName: string): string[];
+export declare function resultHandleIds(value: JsonObject, fieldName: string): string[];
+export declare function requireCoveredHandles(expected: readonly string[], actual: readonly string[], fieldName: string): void;
+export declare function requireFreshPipelineMetadata(goal: UltragoalGoal): UltragoalPipelineMetadata;
+export declare function openPipelineOverlap(plan: UltragoalPlan): {
+    prior: UltragoalGoal;
+    next: UltragoalGoal;
+    overlapId: string;
+} | null;
+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;
+    goalMetadata?: UltragoalGoalMetadataInput[];
+    goalMetadataJson?: string;
+    validationBatches?: UltragoalValidationBatchInput[];
+    validationBatchJson?: string;
+}): Promise<UltragoalPlan>;
+export interface UltragoalRunCompletionState {
+    requiredGoals: UltragoalGoal[];
+    incompleteGoals: UltragoalGoal[];
+    nextGoal?: UltragoalGoal;
+    allComplete: boolean;
+    hasBlockers: boolean;
+    needsFinalAggregateReceipt: boolean;
+}
+export declare function requireJsonObjectValue(value: unknown, fieldName: string): JsonObject;
+export declare function requireJsonObjectOrArrayValue(value: unknown, fieldName: string): JsonObject | JsonObject[];
+import { joinUltragoalPipelineOverlap, rebaselineUltragoalPipelineOverlap, startUltragoalPipelineOverlap } from "./ultragoal-pipeline";
+export { joinUltragoalPipelineOverlap, rebaselineUltragoalPipelineOverlap, startUltragoalPipelineOverlap };
+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;
+}>;
+export declare function qualityGateObject(value: unknown): JsonObject | null;
+export declare function nonEmptyStringArray(value: unknown): string[] | null;
+export declare function requireQualityGateObject(value: unknown, fieldName: string): JsonObject;
+export declare function requireObjectArray(value: unknown, fieldName: string): JsonObject[];
+export declare function requiredStringField(row: JsonObject, key: string, fieldName: string): string;
+export declare function requireStringLinks(value: unknown, fieldName: string): string[];
+export declare function requireResolvedLinks(ids: string[], map: Map<string, JsonObject>, fieldName: string): void;
+export declare function normalizedEvidenceKind(row: JsonObject): string;
+export declare function evidenceKindMatches(kind: string, words: string[]): boolean;
+export type SurfaceFamily = "web" | "cli" | "native" | "api-package" | "algorithm-math" | "unknown";
+export type UltragoalChangeStatus = "added" | "modified" | "deleted" | "renamed" | "copied" | "unknown";
+export type UltragoalChangeCategory = "code" | "generated-binding" | "tool" | "settings-registry" | "prompt-doc-behavior" | "docs-static" | "other";
+export interface UltragoalChangeSetPath extends JsonObject {
+    path: string;
+    status: UltragoalChangeStatus;
+    oldPath?: string;
+    category?: UltragoalChangeCategory;
+}
+export 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;
+    rawDiff?: string;
+    trusted: true;
+}
+export declare function normalizeRepoPath(value: string): string;
+export declare function categorizeComputerChangePath(value: string): UltragoalChangeCategory;
+export declare function isSettingsSchemaPath(value: string): boolean;
+export declare function normalizeSurfaceToken(value: string): string;
+export declare function surfaceFamily(value: string): SurfaceFamily;
+export declare function isLiveSurfaceFamily(family: SurfaceFamily): boolean;
+export declare function isSubstantiveEvidence(value: unknown): boolean;
+export declare function hasTypedVerifiedReceipt(value: unknown): boolean;
+export declare function hasExistingNonEmptyArtifact(cwd: string, value: unknown): Promise<boolean>;
+export declare function readArtifactBytes(cwd: string, row: JsonObject, fieldName: string): Promise<Buffer | null>;
+import { validateArtifactProof, validateCliReplay, validateLiveSurfaceProofPresence, validateReplayExemptFallback, validateStructuralArtifact, validateSurfaceStructuralRequirement, waitForReplayProcessWithTimeout } from "./ultragoal-evidence";
+export type { ReplayProcessHandle } from "./ultragoal-evidence";
+export { validateArtifactProof, validateCliReplay, validateLiveSurfaceProofPresence, validateReplayExemptFallback, validateStructuralArtifact, validateSurfaceStructuralRequirement, waitForReplayProcessWithTimeout, };
+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[];
+}
+import { computeCheckpointChangeSet, parseGitNameStatus, parseUnifiedDiffPaths, resolveGitBase, spawnText } from "./ultragoal-change-set";
+export { computeCheckpointChangeSet, parseGitNameStatus, parseUnifiedDiffPaths, resolveGitBase, spawnText };
+export declare function runUltragoalReview(cwd: string, args: readonly string[]): Promise<UltragoalReviewResult>;
+export declare function runNativeUltragoalCommand(args: string[], cwd?: string): Promise<UltragoalCommandResult>;

package/dist/types/skc-runtime/windows-powershell-command.d.ts

@@ -0,0 +1,9 @@
+export declare const SKC_TMUX_LAUNCHED_ENV = "SKC_TMUX_LAUNCHED";
+export interface WindowsPowerShellInnerCommandOptions {
+    command: readonly string[];
+    args?: readonly string[];
+    environment?: Record<string, string>;
+    tmuxExitMarkerPath?: string;
+}
+/** Builds the shared BOM-free UTF-16LE command for native Windows tmux-compatible panes. */
+export declare function buildWindowsPowerShellInnerCommand({ command, args, environment, tmuxExitMarkerPath, }: WindowsPowerShellInnerCommandOptions): string;

package/dist/types/skc-runtime/workflow-cli-common.d.ts

@@ -0,0 +1,8 @@
+export declare class CommandError extends Error {
+    readonly exitStatus: number;
+    constructor(exitStatus: number, message: string);
+}
+export declare function flagValue(args: readonly string[], flag: string): string | undefined;
+export declare function hasFlag(args: readonly string[], flag: string): boolean;
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+export declare function assertSafePathComponent(value: string, label: string): void;

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,57 @@
+/**
+ * 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;
+    stopReleasingPhases: readonly string[];
+    phaseLock: readonly string[];
+    canonicalOverrides: readonly 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,126 @@
+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 type VisibleSkillActiveStateCacheTier = "security" | "hud";
+export interface ReadVisibleSkillActiveStateOptions {
+    tier?: VisibleSkillActiveStateCacheTier;
+}
+interface ActiveStateStatSignature {
+    path: string;
+    mtimeMs: number;
+    size: number;
+}
+interface ActiveStateSignature {
+    sessionPath: ActiveStateStatSignature | null;
+    activeDir: ActiveStateStatSignature | null;
+    activeEntries: ActiveStateStatSignature[];
+    ralplanModeState: ActiveStateStatSignature | null;
+}
+export declare function computeActiveStateSignature(cwd: string, sessionId: string): Promise<ActiveStateSignature>;
+export declare function invalidateVisibleSkillActiveStateCache(cwd?: string, sessionId?: string): void;
+export declare function readVisibleSkillActiveState(cwd: string, sessionId?: string, opts?: ReadVisibleSkillActiveStateOptions): 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];