Harden Flow runtime boundaries to reduce contract drift and cleanup overhead

This cutover consolidates tool/runtime boundary handling, removes obsolete adapter/helper layers, and centralizes completion/time logic so summary, rendering, and transition behavior stay aligned under one domain model.

Constraint: OpenCode tool arg surfaces must remain SDK-compatible while runtime validation remains authoritative
Rejected: Keep adapter shim layer | duplicated boundary logic and slower cleanup convergence
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep transitions return-value based; avoid introducing throw-driven control flow in domain transitions
Tested: bun run check (typecheck + deadcode + tests + build)
Not-tested: External OpenCode host integration with tool calls outside repository tests

Author: vriesdcrv

bun.lock

@@ -16,6 +16,7 @@ bun run check
 Useful scripts:
 
 - `bun run build`
+- `bun run deadcode`
 - `bun run test`
 - `bun run typecheck`
 - `bun run check`
@@ -27,10 +28,12 @@ Useful scripts:
 - `src/index.ts` — plugin entrypoint
 - `src/installer.ts` — local OpenCode plugin installer
 - `src/config.ts` — command and agent injection
-- `src/tools.ts` — runtime tool surface
+- `src/tools.ts` — OpenCode runtime tool surface
 - `src/runtime/schema.ts` — session and contract schemas
-- `src/runtime/transitions/` — state transition rules split by lifecycle phase
-- `src/runtime/session.ts` — load and save helpers
+- `src/runtime/transitions/` — domain state transition rules split by lifecycle phase
+- `src/runtime/domain/completion.ts` — shared completion-policy calculations
+- `src/runtime/application/tool-runtime.ts` — application-level tool orchestration helpers
+- `src/runtime/session.ts` — persistence and lifecycle exports
 - `src/runtime/render.ts` — derived markdown rendering
 - `src/prompts/agents.ts` — agent instructions
 - `src/prompts/commands.ts` — slash-command templates
@@ -40,10 +43,11 @@ Useful scripts:
 Flow is built around a small set of responsibilities:
 
 1. A plugin `config` hook injects commands and agents.
-2. Runtime tools own all state transitions.
+2. Runtime tools are adapter entrypoints and delegate to application/domain runtime helpers.
 3. Session state is stored under `.flow/sessions/<session-id>/session.json` with `.flow/active` pointing at the current run.
-4. Prompted agents call runtime tools instead of mutating state directly.
-5. Readable markdown docs are rendered beside each saved session under `.flow/sessions/<session-id>/docs/`.
+4. Domain transitions remain authoritative for workflow state changes.
+5. Prompted agents call runtime tools instead of mutating state directly.
+6. Readable markdown docs are rendered beside each saved session under `.flow/sessions/<session-id>/docs/`.
 
 ## Current Agent Roles
 

docs/development.md

@@ -9,9 +9,10 @@
   ],
   "scripts": {
     "build": "bun build ./src/index.ts --outfile ./dist/index.js --target node",
+    "deadcode": "knip --include files,dependencies",
     "test": "bun test",
     "typecheck": "tsc --noEmit",
-    "check": "bun run typecheck && bun run test && bun run build",
+    "check": "bun run typecheck && bun run deadcode && bun run test && bun run build",
     "install:opencode": "bun run ./src/install-opencode.ts",
     "uninstall:opencode": "bun run ./src/uninstall-opencode.ts"
   },
@@ -33,6 +34,7 @@
   "devDependencies": {
     "@opencode-ai/plugin": "^1.3.10",
     "bun-types": "latest",
+    "knip": "^5.63.1",
     "typescript": "^6.0.2"
   }
 }

package.json

@@ -64,7 +64,7 @@ Execution flow:
 4. Run targeted validation.
 5. Review the changed files.
 6. If review finds blocking issues, fix them, rerun targeted validation, and review again. Repeat until review passes or a real blocker remains.
-7. On the final completion path, run broad validation, ask flow-reviewer for a final review, and persist that approval with flow_review_record_final.
+7. On the final completion path, run broad validation, ask flow-reviewer for a final review, and persist that approval with flow_review_record_final. Treat the active feature as the final completion path whenever completing it would satisfy the session completion policy, including completionPolicy.minCompletedFeatures even if other plan features remain pending.
 8. Otherwise ask flow-reviewer to review the feature and persist the decision with flow_review_record_feature.
 9. Return one worker result matching:
 
@@ -106,7 +106,7 @@ Autonomous loop:
 7. If the reviewer returns needs_fix, or the runtime marks the outcome retryable or auto-resolvable, keep the same feature active, coordinate the smallest credible fix/review/reset step, and continue.
 8. Persist an approved feature result with flow_run_complete_feature. If flow_run_complete_feature fails, inspect the runtime error and any structured recovery metadata, satisfy the stated prerequisite, and perform the indicated runtime action when one is provided.
 9. If the runtime routes back into planning because the feature needs decomposition, refresh the plan and continue.
-10. On the final completion path, have flow-worker run broad validation, use flow-reviewer for the final cross-feature review, persist it with flow_review_record_final, and keep fixing/revalidating until the final review passes.
+10. On the final completion path, have flow-worker run broad validation, use flow-reviewer for the final cross-feature review, persist it with flow_review_record_final, and keep fixing/revalidating until the final review passes. Treat the active feature as the final completion path whenever completing it would satisfy the session completion policy, including completionPolicy.minCompletedFeatures even if other plan features remain pending.
 11. Only then allow final completion.
 12. Repeat until the session is complete or blocked.