opencode-plugin-flow 4.4.0 → 5.1.0

package/dist/domain/session.d.ts

@@ -0,0 +1,355 @@
+import type { ValidationCommandClass } from "./validation-command.js";
+export type FeatureStatus = "pending" | "in_progress" | "completed" | "blocked";
+export type SessionStatus = "planning" | "ready" | "running" | "blocked" | "completed";
+export type FeatureReviewDepth = "quick" | "standard" | "detailed";
+export type FinalReviewPolicy = "broad" | "detailed";
+export type ValidationScope = "targeted" | "broad";
+export type SnapshotId = string;
+export type EvidenceId = string;
+export type EvidenceArtifactRef = {
+    kind: "restricted_evidence_v1";
+    digest: `sha256:${string}`;
+    byteLength: number;
+};
+export type CausalGuard = {
+    operationId: string;
+    expectedRevision: number;
+    expectedSnapshotId: SnapshotId;
+};
+declare const featureIdBrand: unique symbol;
+declare const sessionIdBrand: unique symbol;
+export type FeatureId = string & {
+    readonly [featureIdBrand]: "FeatureId";
+};
+export type SessionId = string & {
+    readonly [sessionIdBrand]: "SessionId";
+};
+export declare function toFeatureId(value: string): FeatureId;
+export declare function toSessionId(value: string): SessionId;
+export type OrchestrationPassRecord = {
+    id: string;
+    kind: "discovery" | "audit" | "review" | "validation" | "verification" | "candidate" | "implementation-decision";
+    decision?: "serial" | "parallel" | "candidate-exact-path" | "candidate-worktree" | "tournament" | "skipped" | undefined;
+    decisionReason?: string | undefined;
+    candidateEligibility: "eligible" | "not_eligible" | "unknown";
+    candidateDecision?: "used" | "skipped" | "serial_required" | undefined;
+    decisionFactors: Array<"shared_state" | "overlapping_files" | "small_slice" | "needs_manager_judgment" | "independent_surface" | "validation_available">;
+    modes: Array<"evidence" | "review" | "validation" | "audit" | "verifier" | "candidate-implementation">;
+    workerCount: number;
+    candidateWorkerCount: number;
+    verifierWorkerCount: number;
+    sliceIds: string[];
+    dependsOn: string[];
+    writeScope: "none" | "manager-serial" | "exact-path" | "isolated-worktree" | "mixed";
+    handoffRefs: string[];
+    verificationStatus: "not-needed" | "pending" | "passed" | "failed" | "mixed" | "downgraded";
+    outcome: "accepted" | "modified" | "rejected" | "partial" | "not-covered" | "superseded";
+    synthesisRef?: string | undefined;
+};
+export type OrchestrationTelemetry = {
+    passCount: number;
+    workerCount: number;
+    candidatePassCount: number;
+    verifierPassCount: number;
+    candidateEligibleCount: number;
+    candidateUsedDecisionCount: number;
+    candidateSerialRequiredDecisionCount: number;
+    skippedCandidateDecisionCount: number;
+    latestPasses: OrchestrationPassRecord[];
+};
+export type ReviewFinding = {
+    summary: string;
+    severity: "blocking" | "advisory";
+};
+export type ReviewFindingTaxonomy = "implementation_defect" | "regression_coverage_gap" | "evidence_gap" | "advisory";
+export type ReviewExecutionFindingInput = {
+    taxonomy: ReviewFindingTaxonomy;
+    subject: string;
+    requirementOrRisk: string;
+    evidenceLocator: string;
+    summary: string;
+    severity: "blocking" | "advisory";
+};
+export type ReviewExecutionFinding = ReviewExecutionFindingInput & {
+    fingerprint: string;
+};
+export type ReviewExecutionInput = {
+    attemptId: string;
+    logicalPassId: string;
+    featureId: FeatureId;
+    reviewKind: "feature" | "final";
+    reviewSnapshotId: string;
+    verdict: "passed" | "failed";
+    findings: ReviewExecutionFindingInput[];
+    startedAt: string;
+    completedAt: string;
+    terminalDisposition: "submitted" | "observed_unsubmitted";
+};
+export type ReviewExecution = Omit<ReviewExecutionInput, "findings"> & {
+    findings: ReviewExecutionFinding[];
+};
+export type ReviewLifecycleTelemetry = {
+    featureAttemptCount: number;
+    finalAttemptCount: number;
+    passedVerdictCount: number;
+    failedVerdictCount: number;
+    retryConsumedCount: number;
+};
+export type ObservedReviewWorkerLedger = {
+    source: "unavailable";
+    reconciliationStatus: "unreconciled";
+    observedExecutionCount: null;
+} | {
+    source: "host_observed";
+    reconciliationStatus: "reconciled";
+    observedExecutionCount: number;
+};
+export type Review = {
+    status: "passed" | "failed";
+    summary: string;
+    blockingFindings: ReviewFinding[];
+};
+export type FinalReview = Review & {
+    reviewDepth: FinalReviewPolicy;
+};
+export type ValidationRun = {
+    command: string;
+    status: "passed" | "failed";
+    summary: string;
+};
+export type ValidationEvidence = {
+    kind: "validation";
+    evidenceId: EvidenceId;
+    snapshotId: SnapshotId;
+    sourceDigest: string;
+    commandClass: ValidationCommandClass;
+    startedAt: string;
+    completedAt: string;
+    exitCode: number;
+    outputDigest: string;
+    artifactRef?: EvidenceArtifactRef | undefined;
+    environmentKeys: string[];
+};
+export type ReviewEvidence = {
+    kind: "review";
+    evidenceId: EvidenceId;
+    snapshotId: SnapshotId;
+    sourceDigest: string;
+    attemptId: string;
+    packetDigest: string;
+    startedAt: string;
+    completedAt: string;
+};
+export type EvidenceRecord = ValidationEvidence | ReviewEvidence;
+export type CausalMutationRecord = {
+    operationId: string;
+    operationKind: "plan_save" | "plan_approve" | "run_start" | "review_record" | "evidence_record" | "feature_complete" | "feature_reset" | "session_close";
+    requestDigest: string;
+    priorMutationDigest: string | null;
+    mutationDigest: string;
+    priorRevision: number;
+    revision: number;
+    priorSnapshotId: SnapshotId;
+    currentSnapshotId: SnapshotId;
+    changedEntity: {
+        kind: "session" | "plan" | "feature" | "review" | "evidence" | "closure";
+        id: string;
+    };
+    changedFields: string[];
+    blockerDelta: {
+        added: string[];
+        removed: string[];
+    };
+    evidenceRefs: EvidenceId[];
+    recordedAt: string;
+};
+export type CausalState = {
+    revision: number;
+    genesisSnapshotId: SnapshotId;
+    snapshotId: SnapshotId;
+    mutations: CausalMutationRecord[];
+    evidence: EvidenceRecord[];
+};
+type ReviewerProjectionRequestBase = {
+    featureId: FeatureId;
+    packetHash: string;
+    evidenceRefs: string[];
+    expectedRevision?: number | undefined;
+    expectedSnapshotId?: SnapshotId | undefined;
+};
+export type ReviewerProjectionRequest = (ReviewerProjectionRequestBase & {
+    reviewKind: "feature";
+}) | (ReviewerProjectionRequestBase & {
+    reviewKind: "final";
+});
+type ReviewerProjectionBase = {
+    view: "reviewer";
+    featureId: FeatureId;
+    assignedScope: string[];
+    packetHash: string;
+    evidenceRefs: string[];
+    expectedRevision: number;
+    expectedSnapshotId: SnapshotId;
+};
+export type ReviewerProjection = (ReviewerProjectionBase & {
+    reviewKind: "feature";
+    requiredDepth: FeatureReviewDepth;
+}) | (ReviewerProjectionBase & {
+    reviewKind: "final";
+    requiredDepth: FinalReviewPolicy;
+    requirements: string[];
+    decisions: string[];
+});
+export type Artifact = {
+    path: string;
+};
+export type Feature = {
+    id: FeatureId;
+    title: string;
+    summary: string;
+    status: FeatureStatus;
+    reviewDepth: FeatureReviewDepth;
+    targets: string[];
+    validation: string[];
+    dependsOn: FeatureId[];
+};
+export type Plan = {
+    summary: string;
+    overview: string;
+    requirements: string[];
+    decisions: string[];
+    finalReviewPolicy: FinalReviewPolicy;
+    features: Feature[];
+};
+export type ExecutionProjection = {
+    view: "execution";
+    goal: string;
+    plan: {
+        summary: string;
+        overview: string;
+        requirements: string[];
+        decisions: string[];
+        finalReviewPolicy: FinalReviewPolicy;
+    };
+    feature: {
+        id: FeatureId;
+        title: string;
+        summary: string;
+        targets: string[];
+        validation: string[];
+        dependsOn: FeatureId[];
+        reviewDepth: FeatureReviewDepth;
+    };
+    isFinalFeature: boolean;
+    requiredValidationScope: ValidationScope;
+    expectedRevision: number;
+    expectedSnapshotId: SnapshotId;
+};
+export type PlanInput = {
+    summary: string;
+    overview: string;
+    requirements?: string[] | undefined;
+    decisions?: string[] | undefined;
+    finalReviewPolicy?: FinalReviewPolicy | undefined;
+    features: Array<{
+        id: FeatureId;
+        title: string;
+        summary: string;
+        status?: FeatureStatus | undefined;
+        reviewDepth?: FeatureReviewDepth | undefined;
+        targets?: string[] | undefined;
+        validation?: string[] | undefined;
+        dependsOn?: FeatureId[] | undefined;
+    }>;
+};
+export type CompletedWorkerOutcome = {
+    kind: "completed";
+    summary?: string | undefined;
+    resolutionHint?: string | undefined;
+};
+export type NeedsInputOutcome = {
+    kind: "blocked" | "needs_input" | "replan_required";
+    summary: string;
+    resolutionHint?: string | undefined;
+};
+export type WorkerOutcome = CompletedWorkerOutcome | NeedsInputOutcome;
+type WorkerResultBase = {
+    operationId?: string | undefined;
+    expectedRevision?: number | undefined;
+    expectedSnapshotId?: SnapshotId | undefined;
+    /** Trusted application-boundary digest of the normalized public request. */
+    requestDigest?: string | undefined;
+    featureId: FeatureId;
+    summary: string;
+    artifactsChanged: Artifact[];
+    validationRun: ValidationRun[];
+    validationScope?: ValidationScope | undefined;
+    featureReviewDepth?: FeatureReviewDepth | undefined;
+    featureReview?: Review | undefined;
+    finalReview?: FinalReview | undefined;
+    reviewExecutions?: ReviewExecutionInput[] | undefined;
+    evidence?: EvidenceRecord[] | undefined;
+    orchestrationPasses: OrchestrationPassRecord[];
+};
+export type WorkerResult = (WorkerResultBase & {
+    status: "ok";
+    validationScope: ValidationScope;
+    featureReviewDepth: FeatureReviewDepth;
+    featureReview: Review;
+    outcome?: CompletedWorkerOutcome | undefined;
+}) | (WorkerResultBase & {
+    status: "needs_input";
+    outcome: NeedsInputOutcome;
+});
+export type ExecutionHistoryEntry = {
+    featureId: FeatureId;
+    status: "completed" | "blocked" | "needs_input";
+    summary: string;
+    recordedAt: string;
+    artifactsChanged: Artifact[];
+    validationRun: ValidationRun[];
+    validationScope?: ValidationScope | undefined;
+    featureReviewDepth?: FeatureReviewDepth | undefined;
+    featureReview?: Review | undefined;
+    finalReview?: FinalReview | undefined;
+    outcome?: WorkerOutcome | undefined;
+    orchestrationPasses: OrchestrationPassRecord[];
+};
+export type BudgetTelemetry = {
+    reviewCount: number;
+    failedReviewCount: number;
+    failedReviewAttemptsByFeature: Record<string, number>;
+    reviewExecutions: ReviewExecution[];
+    reviewLifecycle: ReviewLifecycleTelemetry;
+    observedReviewWorkers: ObservedReviewWorkerLedger;
+    orchestration: OrchestrationTelemetry;
+};
+export type Session = {
+    version: 3;
+    id: SessionId;
+    goal: string;
+    status: SessionStatus;
+    approval: "pending" | "approved";
+    plan: Plan | null;
+    activeFeatureId: FeatureId | null;
+    history: ExecutionHistoryEntry[];
+    budget: BudgetTelemetry;
+    causal: CausalState;
+    closure: {
+        kind: "completed" | "deferred" | "abandoned";
+        summary: string;
+        recordedAt: string;
+    } | null;
+    lastError: {
+        tool: string;
+        summary: string;
+        recovery?: string | undefined;
+        recordedAt: string;
+    } | null;
+    timestamps: {
+        createdAt: string;
+        updatedAt: string;
+        completedAt: string | null;
+    };
+};
+export {};

package/dist/domain/transitions.d.ts

@@ -0,0 +1,163 @@
+import type { CausalGuard, CausalMutationRecord, EvidenceRecord, ExecutionProjection, Feature, FeatureId, FeatureReviewDepth, PlanInput, ReviewExecution, ReviewExecutionFindingInput, ReviewExecutionInput, ReviewerProjection, ReviewerProjectionRequest, Session, SessionId, SnapshotId, WorkerResult } from "./session.js";
+export declare const MAX_EXECUTION_PROJECTION_BYTES: number;
+export type TransitionEnvironment = {
+    now(): string;
+    newSessionId(): SessionId;
+    newOperationId?(revision: number): string;
+};
+export type TransitionResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    message: string;
+    recovery?: string;
+    session?: Session;
+};
+export declare function canonicalOperationRequestDigest(kind: CausalMutationRecord["operationKind"], input: unknown): string;
+export declare function canonicalSessionSnapshotId(session: Session): SnapshotId;
+export declare function canonicalEvidenceId(evidence: EvidenceRecord): string;
+export declare function validateCausalChain(session: Session): string | null;
+export declare function stableReviewFindingFingerprint(finding: ReviewExecutionFindingInput): string;
+export type LogicalReviewPassProjection = {
+    logicalPassId: string;
+    featureId: FeatureId;
+    reviewKind: ReviewExecution["reviewKind"];
+    reviewSnapshotId: string;
+    latestAttemptId: string;
+    verdict: ReviewExecution["verdict"];
+    attemptCount: number;
+};
+export declare function projectLogicalReviewPasses(executions: readonly ReviewExecution[]): LogicalReviewPassProjection[];
+export declare function recordReviewExecutions(session: Session, executions: readonly ReviewExecutionInput[], environment: TransitionEnvironment, operationId?: string, guard?: Pick<CausalGuard, "expectedRevision" | "expectedSnapshotId">): TransitionResult<Session>;
+export declare function mergeReviewExecutionsForCompletion(session: Session, executions: readonly ReviewExecutionInput[]): TransitionResult<Session>;
+export declare function mergeEvidenceForCompletion(session: Session, evidenceRecords: readonly EvidenceRecord[]): TransitionResult<Session>;
+export declare function recordEvidence(session: Session, evidenceRecords: readonly EvidenceRecord[], environment: TransitionEnvironment, operationId?: string): TransitionResult<Session>;
+export declare function createSession(goal: string, environment: TransitionEnvironment): Session;
+export declare function applyPlan(session: Session, planInput: PlanInput, environment: TransitionEnvironment): TransitionResult<Session>;
+export declare function approvePlan(session: Session, environment: TransitionEnvironment): TransitionResult<Session>;
+export declare function startRun(session: Session, environment: TransitionEnvironment, featureId?: FeatureId): TransitionResult<{
+    session: Session;
+    feature: Feature;
+}>;
+export declare function completeFeature(session: Session, worker: WorkerResult, environment: TransitionEnvironment): TransitionResult<Session>;
+export declare function resetFeature(session: Session, featureId: FeatureId, environment: TransitionEnvironment, guard?: CausalGuard): TransitionResult<Session>;
+export declare function closeSession(session: Session, kind: "completed" | "deferred" | "abandoned", environment: TransitionEnvironment, summary?: string, guard?: CausalGuard): TransitionResult<Session>;
+export declare function serializedUtf8JsonBytes(value: unknown): number;
+export declare function compactSessionProjection(session: Session): {
+    view: "compact";
+    sessionId: SessionId;
+    status: import("./session.js").SessionStatus;
+    approval: "approved" | "pending";
+    revision: number;
+    snapshotId: string;
+    feature: {
+        id: FeatureId;
+        status: import("./session.js").FeatureStatus;
+    } | null;
+    progress: {
+        completed: number;
+        total: number;
+        remaining: number;
+    };
+    blockers: {
+        featureIds: string[];
+        summary: string | null;
+    };
+    closure: {
+        kind: "abandoned" | "completed" | "deferred";
+    } | null;
+    nextAction: string;
+};
+export declare function executionSessionProjection(session: Session): TransitionResult<ExecutionProjection>;
+export declare function detailSessionProjection(session: Session): {
+    view: "detail";
+    compact: {
+        view: "compact";
+        sessionId: SessionId;
+        status: import("./session.js").SessionStatus;
+        approval: "approved" | "pending";
+        revision: number;
+        snapshotId: string;
+        feature: {
+            id: FeatureId;
+            status: import("./session.js").FeatureStatus;
+        } | null;
+        progress: {
+            completed: number;
+            total: number;
+            remaining: number;
+        };
+        blockers: {
+            featureIds: string[];
+            summary: string | null;
+        };
+        closure: {
+            kind: "abandoned" | "completed" | "deferred";
+        } | null;
+        nextAction: string;
+    };
+    plan: {
+        summary: string;
+        overview: string;
+        requirements: string[];
+        decisions: string[];
+        finalReviewPolicy: import("./session.js").FinalReviewPolicy;
+        features: {
+            id: FeatureId;
+            title: string;
+            summary: string;
+            status: import("./session.js").FeatureStatus;
+            reviewDepth: FeatureReviewDepth;
+            targets: string[];
+            dependsOn: FeatureId[];
+        }[];
+    } | null;
+    history: {
+        featureId: FeatureId;
+        status: "blocked" | "completed" | "needs_input";
+        summary: string;
+        recordedAt: string;
+        validation: {
+            status: "failed" | "passed";
+            summary: string;
+        }[];
+    }[];
+    causal: {
+        revision: number;
+        snapshotId: string;
+        mutations: CausalMutationRecord[];
+        evidence: EvidenceRecord[];
+    };
+};
+export declare function reviewerSessionProjection(session: Session, request: ReviewerProjectionRequest): TransitionResult<ReviewerProjection>;
+export declare function mutationReceiptProjection(session: Session, warnings?: readonly string[], operationId?: string): {
+    view: "mutation_receipt";
+    status: import("./session.js").SessionStatus;
+    operationId: string | null;
+    revision: number;
+    snapshotId: string;
+    changedEntity: {
+        kind: "session" | "plan" | "feature" | "review" | "evidence" | "closure";
+        id: string;
+    } | null;
+    changedFields: string[];
+    blockerDelta: {
+        added: string[];
+        removed: string[];
+    };
+    evidenceRefs: string[];
+    warnings: string[];
+    nextAction: string;
+};
+export declare function causalDeltaProjection(session: Session, sinceRevision: number): TransitionResult<{
+    view: "delta";
+    changed: boolean;
+    fromRevision: number;
+    throughRevision: number;
+    currentRevision: number;
+    snapshotId: SnapshotId;
+    mutations: CausalMutationRecord[];
+    hasMore: boolean;
+    nextSinceRevision: number | null;
+}>;

package/dist/domain/validation-command.d.ts

@@ -0,0 +1,8 @@
+export type ValidationCommandClass = "test" | "typecheck" | "lint" | "build" | "format" | "smoke" | "other";
+/**
+ * Classify a validation command for evidence matching.
+ *
+ * Precedence is intentional and preserves the classifier contract previously
+ * exposed at the application boundary.
+ */
+export declare function validationCommandClass(command: string): ValidationCommandClass;

package/dist/guidance/catalog.d.ts

@@ -0,0 +1,18 @@
+import { type FlowGuidanceId, type FlowGuidanceTopic } from "./ids.js";
+export { FLOW_GUIDANCE_IDS, FLOW_GUIDANCE_TOPICS, type FlowGuidanceId, type FlowGuidanceTopic, } from "./ids.js";
+export type FlowGuidanceFile = {
+    relativePath: string;
+    content: string;
+};
+export type FlowGuidanceDefinition = {
+    name: FlowGuidanceTopic;
+    files: FlowGuidanceFile[];
+};
+export declare const FLOW_GUIDANCE_DEFINITIONS: readonly FlowGuidanceDefinition[];
+export type FlowGuidanceDocument = FlowGuidanceFile & {
+    id: FlowGuidanceId;
+    topic: FlowGuidanceTopic;
+};
+export declare const FLOW_GUIDANCE_DOCUMENTS: readonly FlowGuidanceDocument[];
+export declare function getFlowGuidance(id: FlowGuidanceId): FlowGuidanceDocument;
+export declare function findFlowGuidance(topic: string, relativePath: string): FlowGuidanceDocument | undefined;

package/dist/guidance/ids.d.ts

@@ -0,0 +1,4 @@
+export declare const FLOW_GUIDANCE_TOPICS: readonly ["flow", "flow-plan", "flow-run", "flow-test", "flow-review", "flow-deslop", "flow-ui-quality", "flow-commit"];
+export type FlowGuidanceTopic = (typeof FLOW_GUIDANCE_TOPICS)[number];
+export declare const FLOW_GUIDANCE_IDS: readonly ["flow", "flow/references/recovery-playbook.md", "flow/references/parallel-orchestration.md", "flow/references/parallel-decision.md", "flow/references/parallel-manifest.md", "flow/references/parallel-execution.md", "flow/references/parallel-synthesis.md", "flow/references/parallel-pass-example.md", "flow/references/handoff-format.md", "flow-plan", "flow-plan/references/planning-examples.md", "flow-plan/references/plan-quality-checklist.md", "flow-plan/references/parallel-discovery.md", "flow-run", "flow-run/references/validation-rubric.md", "flow-run/references/audit-rubric.md", "flow-test", "flow-review", "flow-review/references/hidden-reviewer-contract.md", "flow-review/references/review-rubric.md", "flow-deslop", "flow-deslop/references/smell-rubric.md", "flow-deslop/references/refactor-workflow.md", "flow-ui-quality", "flow-ui-quality/references/ui-rubric.md", "flow-ui-quality/references/visual-verification.md", "flow-commit"];
+export type FlowGuidanceId = (typeof FLOW_GUIDANCE_IDS)[number];

package/dist/index.d.ts

@@ -1 +1 @@
-export { default } from "./adapters/opencode/plugin";
+export { default } from "./platform/opencode/plugin.js";