opencode-plugin-flow 4.4.0 → 5.0.0

package/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 One short entry per release, written for users deciding whether to upgrade.
 
+## [5.0.0] - 2026-07-18
+
+TypeScript 7 hard-cutover lore makes Flow 5 smaller, stricter, and easier to
+recover without carrying a v4 compatibility layer:
+
+- The compiler is TypeScript 7.0.2; the pinned toolchain is Bun 1.3.14,
+  Biome 2.5.4, OpenCode plugin 1.18.3, and Zod 4.4.3. Published code now
+  requires Node.js 24 or newer and CI covers Node 24 and 26.
+- Source code now follows `domain -> application -> infrastructure ->
+  platform`: pure transitions use injected time and IDs, application use cases
+  depend on repository ports, filesystem state is an outer implementation,
+  and OpenCode owns only host transport and rendering.
+- OpenCode's embedded validator is private to the host adapter. Flow's core
+  schemas use its direct Zod dependency, shared fixtures keep both wire
+  contracts aligned, and declaration emit no longer leaks package-manager or
+  nested-validator paths.
+- Persisted sessions use schema version 3. Version 2 sessions are not migrated;
+  they are reported as unsupported and preserved in quarantine so a new v5
+  session can start safely.
+- Public use-case results have an explicit typed operation status. Repository-
+  and caller-controlled prose is confined to `workflowData`; top-level
+  summaries, next actions, and recovery fields remain plugin-authored. Feature
+  and session IDs are branded, feature IDs are consistently lowercase
+  kebab-case at every input boundary, and all superseded `src/runtime` and
+  `src/adapters` entrypoints are removed.
+- Source and declaration imports follow NodeNext ESM rules with explicit `.js`
+  specifiers, and the packed-package smoke test compiles a strict NodeNext
+  consumer without skipping library checks before importing the plugin in Node.
+- Workspace roots are canonicalized and every Flow-managed directory and file
+  rejects symbolic links before read or mutation. Archive publication is
+  no-clobber and retry-safe, while lock contention and malformed owner metadata
+  fail closed for manual inspection instead of using age or liveness to steal a
+  lock. Completion outcomes require an explicit discriminator, and domain
+  transitions copy caller-owned plan and evidence collections before recording
+  them.
+- Flow no longer synchronizes Markdown into OpenCode's global skill registry.
+  Core command guidance and optional helpers are embedded in the plugin;
+  `flow_guidance` returns exact package-versioned documents by stable id, plugin
+  startup performs no global skill filesystem work, and `flow_status` no longer
+  carries setup/restart health.
+- Plugin configuration only registers commands and agents; it performs no
+  workspace filesystem I/O and maintains no ambient instruction projection.
+  `/flow-review` validates OpenCode's native subtask identity and agent before
+  rewriting only its prompt, so malformed dispatch fails closed.
+- Orchestration telemetry retains at most 50 recent pass records and accepts at
+  most 50 per completion. Deduplication is scoped to that retained telemetry
+  window, and failed completion mutations now update `timestamps.updatedAt`
+  from the same instant recorded in `lastError`.
+- The experimental compaction hook, token telemetry, phase boundaries, resume
+  packets, and acknowledgement protocol are gone. Review retry exhaustion uses
+  the ordinary blocked-feature/reset path, while a recorded closure makes the
+  session archive-only until retry-safe publication succeeds.
+- The old doctor/sync/uninstall CLI is replaced by explicit
+  `legacy-cleanup --dry-run|--apply`. Apply never deletes: it moves only
+  marker-proven pristine v4 folders to a recovery archive and refuses
+  foreign, edited, extra, malformed, or symlinked content.
+
 ## [4.4.0] - 2026-07-17
 
 Prompt economy lore makes Flow's instructions smaller, more role-specific, and

package/README.md

@@ -6,10 +6,10 @@ then implement one feature at a time with enforced validation and review
 evidence. State lives in `.flow/session.json`, so a session survives restarts,
 model switches, and context loss.
 
-The design is skills-first: the skills carry planning, execution, validation,
-review, and orchestration judgment, while the plugin runtime stays deliberately
-small — it keeps the session ledger and enforces the hard gates prompts should
-not be trusted to remember.
+The design is guidance-first: package-owned Markdown carries planning,
+execution, validation, review, and orchestration judgment, while the plugin
+runtime stays deliberately small — it keeps the session ledger and enforces the
+hard gates prompts should not be trusted to remember.
 
 Full project documentation is available in the
 [Flow OpenCode wiki](https://github.com/ddv1982/flow-opencode/wiki).
@@ -17,11 +17,10 @@ Full project documentation is available in the
 ## Quick start
 
 ```bash
-opencode plugin opencode-plugin-flow@4.4.0 --global --force
-npx -y opencode-plugin-flow@4.4.0 sync
+opencode plugin opencode-plugin-flow@5.0.0 --global --force
 ```
 
-Restart OpenCode, then give Flow a goal:
+Start or restart OpenCode, then give Flow a goal:
 
 ```text
 /flow-auto add rate limiting to the public API
@@ -52,8 +51,9 @@ restart.
   ...
 
 > /flow-status
-  status: running, 1/3 features completed
-  nextAction: complete feature "per-route-config"
+  status: ok
+  workflowData.session.status: running, 1/3 features completed
+  nextAction: complete the feature under workflowData.session.activeFeature
 ```
 
 Interrupt at any point; `/flow-run` resumes the next approved feature. On the
@@ -65,7 +65,7 @@ completed.
 
 | Command | Purpose |
 | --- | --- |
-| `/flow-auto <goal>` | Drive the full skill-guided loop. |
+| `/flow-auto <goal>` | Drive the full guidance-driven loop. |
 | `/flow-plan <goal>` | Create or approve a plan. |
 | `/flow-run` | Execute one approved feature. |
 | `/flow-review` | Run a read-only review. |
@@ -73,20 +73,22 @@ completed.
 
 Commands are compiled entrypoints: manager commands carry only their applicable
 core instructions, while `/flow-review` runs against the reserved reviewer's
-role-specific agent contract. They keep working even when OpenCode's native
-skill discovery lags behind a fresh install (see
-[docs/troubleshooting.md](docs/troubleshooting.md)).
+role-specific agent contract. Flow does not install files into OpenCode's
+global skill registry and does not depend on native skill discovery.
 
-`flow-test`, `flow-deslop`, `flow-ui-quality`, and `flow-commit` are managed
-helper skills, not public commands.
-`flow-commit` is user-triggered only and stays outside the autonomous loop.
+`flow-test`, `flow-deslop`, `flow-ui-quality`, and `flow-commit` are optional
+package-owned guides loaded on demand through `flow_guidance`, not public
+commands. `flow-commit` is user-triggered only and stays outside the autonomous
+loop.
 
 ## Tools
 
-The runtime exposes seven tools:
+The plugin exposes eight tools. `flow_guidance` is read-only and returns embedded
+Markdown; the other seven form the stateful runtime surface:
 
 | Tool | Purpose |
 | --- | --- |
+| `flow_guidance` | Load exact package-owned guidance by stable id. |
 | `flow_status` | Read the active session and next action. |
 | `flow_plan_save` | Create a session and/or save a draft plan. |
 | `flow_plan_approve` | Approve the draft plan. |
@@ -101,7 +103,7 @@ final feature also needs a passing `finalReview`.
 
 ## What the runtime enforces
 
-The runtime owns only safety; judgment lives in the skills:
+The runtime owns only safety; judgment lives in package-owned guidance:
 
 - `.flow/session.json` is the single source of truth; writes are locked and
   atomic, and closed sessions are archived under `.flow/history/`.
@@ -114,19 +116,18 @@ The runtime owns only safety; judgment lives in the skills:
   that is shallower than the approved feature requires.
 - Failed reviews are bounded: a failed review pauses by default, and autonomous
   repair is limited to one repair plus one retry before the feature blocks.
-- Completed feature counts are telemetry only; Flow does not stop an approved
-  plan just because several features have completed. Review retry boundaries
-  still return a bounded resume packet and require explicit `phaseBoundaryAck`
-  before starting the next feature.
-- Skills do not estimate context pressure or request host compaction. Only a
-  runtime-issued phase boundary stops the current loop for a fresh invocation.
+- Review exhaustion uses the ordinary blocked-feature state; continuing requires
+  an explicit `flow_feature_reset`, not a second checkpoint protocol.
+- Once a closure is recorded, the session is archive-only. If publication fails,
+  retry `flow_session_close`; no run, reset, approval, or replan can reopen it.
 - A session can close as `completed` only after final completion has passed.
-- Crash recovery is built in: stale session locks expire automatically and
-  unreadable session files are quarantined with recovery guidance, never
-  silently deleted.
+- Session locks fail closed: Flow never guesses that an old lock is abandoned,
+  and only the unique owner may release it. Unreadable session files are
+  quarantined with recovery guidance, never silently deleted.
 - Flow writes `.flow/.gitignore` so session state stays out of Git by default.
-- `.flow/opencode-instructions.md` is a generated projection of the active
-  session that keeps ambient context accurate; do not edit it.
+- `.flow/session.json` is the only active-state representation. Canonical Flow
+  commands call `flow_status` before acting; plugin configuration does not read,
+  refresh, or project workspace state.
 
 ## Hidden workers
 
@@ -154,26 +155,28 @@ used exact-path candidate workers, used isolated worktrees, ran a tournament, or
 skipped eligible candidates. Feature completion can carry bounded
 `orchestrationPasses` with candidate eligibility, decision, and structured
 factors; `flow_status` reports the aggregate under
-`session.budget.orchestration`.
+`workflowData.session.budget.orchestration`.
 
-## Install details, doctor, repair, uninstall
+## Install details and legacy cleanup
 
-See [docs/troubleshooting.md](docs/troubleshooting.md) for skill sync
-mechanics, the `doctor`/`sync` CLI, older-OpenCode install fallback, stuck
-session recovery, and uninstall (`uninstall --dry-run` previews removals).
+See [docs/troubleshooting.md](docs/troubleshooting.md) for updates,
+older-OpenCode install fallback, stuck session recovery, and removal of global
+Flow skill folders left by v4.
 
-To update a pinned Flow version, rerun the install command with the new
-version. To inspect skill health:
+To update a pinned Flow version, rerun the install command with the new version.
+Flow starts with the new package-owned guidance immediately; no second restart
+or sync command is required. To preview recoverable migration of pristine v4
+global skill folders:
 
 ```bash
-npx -y opencode-plugin-flow@4.4.0 doctor
+npx -y opencode-plugin-flow@5.0.0 legacy-cleanup --dry-run
 ```
 
 ## Development
 
 ```bash
 bun install
-bun run check        # typecheck + lint + build + tests
+bun run check        # typecheck + lint + prompt quality + build + tests
 bun run smoke:live   # boots a real OpenCode server against the packed tarball
 ```
 
@@ -185,7 +188,8 @@ import flowPlugin from "opencode-plugin-flow";
 
 See [docs/development.md](docs/development.md) and
 [docs/maintainer-contract.md](docs/maintainer-contract.md) for the
-runtime/skills split and release process.
+v5 domain/application/infrastructure/platform boundaries, guidance split, and
+release process.
 
 ## Credits
 
@@ -195,5 +199,5 @@ work on parallel agent workflows. Flow also draws conceptual inspiration from
 emphasis on codebase orientation, context engineering, agent orchestration,
 and reviewable handoffs.
 
-The Flow version is its own OpenCode-native design: skills-first,
+The Flow version is its own OpenCode-native design: package-owned guidance,
 manager-owned state, hidden workers, and no extra runtime ledger.

package/dist/application/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class UnreadableFlowSessionError extends Error {
+    readonly code = "UNREADABLE_FLOW_SESSION";
+    readonly reason: string;
+    constructor(message: string, reason: string);
+}

package/dist/{runtime/api.d.ts → application/flow-service.d.ts}

@@ -1,5 +1,48 @@
 import { z } from "zod";
-export type RuntimeResponse = Record<string, unknown>;
+import type { Feature, Session, SessionId } from "../domain/session.js";
+import { summarizeSession, type TransitionEnvironment } from "../domain/transitions.js";
+import type { SessionRepository } from "./ports/session-repository.js";
+type StatusResponse = ReturnType<typeof summarizeSession>;
+type ActiveStatusResponse = Extract<StatusResponse, {
+    workflowData: unknown;
+}>;
+type SessionWorkflowData = ActiveStatusResponse["workflowData"]["session"];
+type WorkflowData = {
+    session?: SessionWorkflowData;
+    failure?: {
+        summary: string;
+        recovery?: string;
+    };
+    startedFeature?: Feature;
+    archive?: {
+        sessionId: SessionId;
+        closure: Session["closure"];
+    };
+    quarantine?: {
+        reason: string;
+        preservedAt?: string;
+    };
+};
+type ResponseContext = {
+    statusSummary?: string;
+    nextAction?: string;
+    dataNote?: string;
+    workflowData?: WorkflowData;
+    recovery?: string;
+};
+export type FlowResponse = ResponseContext & {
+    status: "ok" | "error" | "missing_goal" | "missing_session";
+    summary: string;
+};
+export type FlowService = {
+    status(): Promise<FlowResponse>;
+    planSave(input: unknown): Promise<FlowResponse>;
+    planApprove(): Promise<FlowResponse>;
+    runStart(input: unknown): Promise<FlowResponse>;
+    featureComplete(input: unknown): Promise<FlowResponse>;
+    featureReset(input: unknown): Promise<FlowResponse>;
+    sessionClose(input: unknown): Promise<FlowResponse>;
+};
 export declare const FlowPlanSaveSchema: z.ZodObject<{
     goal: z.ZodOptional<z.ZodString>;
     plan: z.ZodOptional<z.ZodObject<{
@@ -12,47 +55,46 @@ export declare const FlowPlanSaveSchema: z.ZodObject<{
             detailed: "detailed";
         }>>;
         features: z.ZodArray<z.ZodObject<{
-            summary: z.ZodString;
-            id: z.ZodString;
+            id: z.ZodPipe<z.ZodString, z.ZodTransform<import("../domain/session.js").FeatureId, string>>;
             title: z.ZodString;
+            summary: z.ZodString;
             status: z.ZodOptional<z.ZodEnum<{
-                pending: "pending";
-                in_progress: "in_progress";
-                completed: "completed";
                 blocked: "blocked";
+                completed: "completed";
+                in_progress: "in_progress";
+                pending: "pending";
             }>>;
             reviewDepth: z.ZodOptional<z.ZodEnum<{
+                detailed: "detailed";
                 quick: "quick";
                 standard: "standard";
-                detailed: "detailed";
             }>>;
             targets: z.ZodOptional<z.ZodArray<z.ZodString>>;
             validation: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            dependsOn: z.ZodOptional<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<import("../domain/session.js").FeatureId, string>>>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const FlowRunStartSchema: z.ZodObject<{
-    featureId: z.ZodOptional<z.ZodString>;
-    phaseBoundaryAck: z.ZodOptional<z.ZodBoolean>;
+    featureId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("../domain/session.js").FeatureId, string>>>;
 }, z.core.$strict>;
 export declare const FlowFeatureResetSchema: z.ZodObject<{
-    featureId: z.ZodString;
+    featureId: z.ZodPipe<z.ZodString, z.ZodTransform<import("../domain/session.js").FeatureId, string>>;
 }, z.core.$strict>;
 export declare const FlowSessionCloseSchema: z.ZodObject<{
     kind: z.ZodEnum<{
+        abandoned: "abandoned";
         completed: "completed";
         deferred: "deferred";
-        abandoned: "abandoned";
     }>;
     summary: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export declare const FlowFeatureCompleteToolSchema: z.ZodObject<{
     status: z.ZodEnum<{
-        ok: "ok";
         needs_input: "needs_input";
+        ok: "ok";
     }>;
-    featureId: z.ZodString;
+    featureId: z.ZodPipe<z.ZodString, z.ZodTransform<import("../domain/session.js").FeatureId, string>>;
     summary: z.ZodString;
     artifactsChanged: z.ZodOptional<z.ZodArray<z.ZodObject<{
         path: z.ZodString;
@@ -60,45 +102,45 @@ export declare const FlowFeatureCompleteToolSchema: z.ZodObject<{
     validationRun: z.ZodOptional<z.ZodArray<z.ZodObject<{
         command: z.ZodString;
         status: z.ZodEnum<{
-            passed: "passed";
             failed: "failed";
+            passed: "passed";
         }>;
         summary: z.ZodString;
     }, z.core.$strict>>>;
     validationScope: z.ZodOptional<z.ZodEnum<{
-        targeted: "targeted";
         broad: "broad";
+        targeted: "targeted";
     }>>;
     featureReviewDepth: z.ZodOptional<z.ZodEnum<{
+        detailed: "detailed";
         quick: "quick";
         standard: "standard";
-        detailed: "detailed";
     }>>;
     featureReview: z.ZodOptional<z.ZodObject<{
         status: z.ZodEnum<{
-            passed: "passed";
             failed: "failed";
+            passed: "passed";
         }>;
         summary: z.ZodString;
         blockingFindings: z.ZodDefault<z.ZodArray<z.ZodObject<{
             summary: z.ZodString;
             severity: z.ZodDefault<z.ZodEnum<{
-                blocking: "blocking";
                 advisory: "advisory";
+                blocking: "blocking";
             }>>;
         }, z.core.$strict>>>;
     }, z.core.$strict>>;
     finalReview: z.ZodOptional<z.ZodObject<{
         status: z.ZodEnum<{
-            passed: "passed";
             failed: "failed";
+            passed: "passed";
         }>;
         summary: z.ZodString;
         blockingFindings: z.ZodDefault<z.ZodArray<z.ZodObject<{
             summary: z.ZodString;
             severity: z.ZodDefault<z.ZodEnum<{
-                blocking: "blocking";
                 advisory: "advisory";
+                blocking: "blocking";
             }>>;
         }, z.core.$strict>>>;
         reviewDepth: z.ZodEnum<{
@@ -106,42 +148,37 @@ export declare const FlowFeatureCompleteToolSchema: z.ZodObject<{
             detailed: "detailed";
         }>;
     }, z.core.$strict>>;
-    outcome: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
-        kind: z.ZodDefault<z.ZodEnum<{
-            completed: "completed";
-            blocked: "blocked";
-            needs_input: "needs_input";
-            replan_required: "replan_required";
-        }>>;
+    outcome: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"completed">;
         summary: z.ZodOptional<z.ZodString>;
         resolutionHint: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>, z.ZodObject<{
-        kind: z.ZodDefault<z.ZodEnum<{
+        kind: z.ZodEnum<{
             blocked: "blocked";
             needs_input: "needs_input";
             replan_required: "replan_required";
-        }>>;
+        }>;
         summary: z.ZodString;
         resolutionHint: z.ZodOptional<z.ZodString>;
-    }, z.core.$strict>]>>;
+    }, z.core.$strict>], "kind">>;
     orchestrationPasses: z.ZodOptional<z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         kind: z.ZodEnum<{
-            validation: "validation";
             audit: "audit";
             candidate: "candidate";
             discovery: "discovery";
+            "implementation-decision": "implementation-decision";
             review: "review";
+            validation: "validation";
             verification: "verification";
-            "implementation-decision": "implementation-decision";
         }>;
         decision: z.ZodOptional<z.ZodEnum<{
-            parallel: "parallel";
-            serial: "serial";
             "candidate-exact-path": "candidate-exact-path";
             "candidate-worktree": "candidate-worktree";
-            tournament: "tournament";
+            parallel: "parallel";
+            serial: "serial";
             skipped: "skipped";
+            tournament: "tournament";
         }>>;
         decisionReason: z.ZodOptional<z.ZodString>;
         candidateEligibility: z.ZodDefault<z.ZodEnum<{
@@ -150,25 +187,25 @@ export declare const FlowFeatureCompleteToolSchema: z.ZodObject<{
             unknown: "unknown";
         }>>;
         candidateDecision: z.ZodOptional<z.ZodEnum<{
+            serial_required: "serial_required";
             skipped: "skipped";
             used: "used";
-            serial_required: "serial_required";
         }>>;
         decisionFactors: z.ZodDefault<z.ZodArray<z.ZodEnum<{
-            shared_state: "shared_state";
+            independent_surface: "independent_surface";
+            needs_manager_judgment: "needs_manager_judgment";
             overlapping_files: "overlapping_files";
+            shared_state: "shared_state";
             small_slice: "small_slice";
-            needs_manager_judgment: "needs_manager_judgment";
-            independent_surface: "independent_surface";
             validation_available: "validation_available";
         }>>>;
         modes: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            audit: "audit";
+            "candidate-implementation": "candidate-implementation";
             evidence: "evidence";
+            review: "review";
             validation: "validation";
-            audit: "audit";
             verifier: "verifier";
-            review: "review";
-            "candidate-implementation": "candidate-implementation";
         }>>>;
         workerCount: z.ZodDefault<z.ZodNumber>;
         candidateWorkerCount: z.ZodDefault<z.ZodNumber>;
@@ -176,36 +213,31 @@ export declare const FlowFeatureCompleteToolSchema: z.ZodObject<{
         sliceIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
         dependsOn: z.ZodDefault<z.ZodArray<z.ZodString>>;
         writeScope: z.ZodDefault<z.ZodEnum<{
-            none: "none";
-            "manager-serial": "manager-serial";
             "exact-path": "exact-path";
             "isolated-worktree": "isolated-worktree";
+            "manager-serial": "manager-serial";
             mixed: "mixed";
+            none: "none";
         }>>;
         handoffRefs: z.ZodDefault<z.ZodArray<z.ZodString>>;
         verificationStatus: z.ZodDefault<z.ZodEnum<{
-            pending: "pending";
-            passed: "passed";
+            downgraded: "downgraded";
             failed: "failed";
             mixed: "mixed";
             "not-needed": "not-needed";
-            downgraded: "downgraded";
+            passed: "passed";
+            pending: "pending";
         }>>;
         outcome: z.ZodDefault<z.ZodEnum<{
             accepted: "accepted";
             modified: "modified";
-            rejected: "rejected";
-            partial: "partial";
             "not-covered": "not-covered";
+            partial: "partial";
+            rejected: "rejected";
             superseded: "superseded";
         }>>;
         synthesisRef: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
-export declare function flowStatus(worktree: string): Promise<RuntimeResponse>;
-export declare function flowPlanSave(worktree: string, input: unknown): Promise<RuntimeResponse>;
-export declare function flowPlanApprove(worktree: string): Promise<RuntimeResponse>;
-export declare function flowRunStart(worktree: string, input: unknown): Promise<RuntimeResponse>;
-export declare function flowFeatureComplete(worktree: string, input: unknown): Promise<RuntimeResponse>;
-export declare function flowFeatureReset(worktree: string, input: unknown): Promise<RuntimeResponse>;
-export declare function flowSessionClose(worktree: string, input: unknown): Promise<RuntimeResponse>;
+export declare function createFlowService(repository: SessionRepository, environment: TransitionEnvironment): FlowService;
+export {};

package/dist/application/ports/session-repository.d.ts

@@ -0,0 +1,11 @@
+import type { Session } from "../../domain/session.js";
+export type SessionTransaction = {
+    load(): Promise<Session | null>;
+    save(session: Session): Promise<Session>;
+    archiveAndClear(session: Session): Promise<void>;
+    quarantineUnreadable(): Promise<string | null>;
+};
+export interface SessionRepository {
+    read(): Promise<Session | null>;
+    transact<T>(task: (transaction: SessionTransaction) => Promise<T>): Promise<T>;
+}