Skip to content

Latest commit

 

History

History
360 lines (306 loc) · 20.7 KB

maintainer-contract.md

File metadata and controls

360 lines (306 loc) · 20.7 KB

Maintainer Contract

This document defines Flow's invariants.

Product boundary

Flow is in preview. Positioning defines its audience and limits. What Flow guarantees classifies claims by enforcement and labels claims without tests or scheduled evals as unmeasured.

Tools, commands, guides, agents, and Session v5 stay frozen while those guarantees are measured. Optional fields may be added. Removal or rename requires a major announced one release ahead. A new required-at-save plan declaration is a major. evidence entries own scope, platform, and assertions; named commands bind .flow/results.xml. scope: "gate-observe" records inspect-only audit outcomes; gate still requires pass. Release qualification owns the thresholds and cadence.

Flow owns a serial durable lifecycle with planning, one active run, observed validation, one independent review, reset, and closure. Implementation may use a bounded, ephemeral host-native worker wave. Flow exposes eleven tools, five commands, four guides, and three hidden subagents. flow-planner is disabled unless selected. Active work uses the manager and reserved planner, worker, and reviewer roles.

An active Flow session is authoritative for its goal until an explicit close records completed, deferred, or abandoned disposition. The manager must not silently continue that goal through an ordinary non-Flow workflow. Runtime nextAction is durable default workflow direction, not a new permission grant. Environment-sensitive transition guards remain authoritative when a mutation is attempted.

Prerequisite repairs have no amendment count limit. Each needs a current, complete failed canonical gate and reversible same-goal targets before review. Later amendments need a canonical failure recorded after the preceding amendment. The plan, gate, tests, and review stay fixed. Repair handoffs occur once per accepted amendment boundary, not per capture.

Before manager mutations, compare the compact goal with the request. Exact recovery of an accepted close runs first and grants no new authority. The manager judges alignment: continuation or compatible narrowing proceeds; new or expanded work makes no mutation and offers continue, defer, or abandon. Close completed work before a new request. Same-goal approved plan-only requests report plan and progress without mutation.

Within existing implementation authority, /flow-auto continues through runnable features and closure. An accepted non-replayed manager mutation must establish progress in the same Flow session before idle can enqueue another prompt. An unchanged ready baseline, replacement session, unknown attribution, or stale source fails closed. A dispatched reviewer may contribute only the expected state-constrained successor revision after flow_review_start.

Planning awaiting approval and await-user-direction remain checkpoints. Shadow advice grants no mutation. A reply resumes only after its accepted manager mutation advances the same session into a mechanical state. An unchanged recognized checkpoint returns to waiting. Native assistant and call identities must match the frozen inputs consumed by that model request. Later input cannot relabel an older assistant or supply authority from another host.

Automatic compaction retains the epoch through its checked native control. Its user-role checkpoint grants no approval. Steer or consumed input, manual compaction of automatic work, user interruption, or event-stream loss revokes the interval. Consumer cancellation ends only its captured HTTP request. Queued prompts preserve the running request. Stale callbacks cannot revoke a fresh source. Summary-only ordinary history grants no checkpoint execution. These checks add no Session v5 field. See ADR 0018.

/flow-auto stop and /flow-auto cancel revoke only the process-local lease in that OpenCode session. They do not mutate or close the durable Flow session.

Initial auto/run prompts, compaction context, and synthetic continuations share a manager kernel covering mutation ownership, reviewer-owned submission, reserved roles, the failedReviewCount === 1 retry gate, and current-source and relevant base-diff evidence. The kernel adds no role registry or durable policy.

Retry selection follows the Session v5 convergence rules. The session remains authoritative while waiting. Other pauses require a material product or scope choice, missing external Git or release authority, a hard operational failure, or user-chosen deferred or abandoned closure. Only the user may select those non-completed dispositions.

Flow does not own plugin installation, automatic activation, cache cleanup, configuration repair, optional worker admission, audit schemas, benchmark promotion, replay reporting, narrow correction protocols, durable wave state, worker recovery, concurrent active features, or cross-version active-state migration. It also owns no persisted request-intent classifier, retry counter, or delivery document.

Session v5

  • Session v5 is the only active schema. Older documents never hydrate as active state and old archives never authorize work.
  • Session v5 compatibility runs from older writer to newer reader. Older builds cannot read values beyond historical bounds, including more than three amendments or 64 planned gates plus a separate broad observation. Finish or close before downgrade; Flow adds no rollback layer.
  • Approval locks a bounded DAG and optional per-feature pass or observe checks. New plans declare one evidence gate, or gate-observe for all-inspect work. Older documents hydrate without evidence or checks; retired gate and externalEvidence fields stay unread.
  • Stable finding, issue, and requirement IDs supplied by the source request remain verbatim in saved feature summary or validation prose so each ID is traceable to an immutable outcome and its evidence.
  • If implementation would require material scope outside an approved plan, stop editing. Finish the approved plan or explicitly close it before creating a different plan; never replan the active approved session in place.
  • A feature run aggregates validation, review, result, and artifacts. Optional baseline and packet references point to managed hashed sidecars.
  • Runs remain in strictly increasing durable start-revision order, so derived latest-attempt delivery cannot disagree with canonical progress.
  • At most one run is active. Dependencies must be complete before a run starts.
  • New failed reviews block either run kind. Inspection repairs cover approved report/evidence targets, not product defects. Legacy completed inspections with failed reviews retain unsupported assurance. Reset supersedes the selected feature and its dependent runs. An optional exact nextFeatureId starts the chosen runnable feature in the same transaction, and its new run starts empty. A failed feature is excluded from implicit selection while its latest relevant reviewed outcome remains failed; untouched dependency-independent features remain eligible. Automatic convergence is bounded by recorded failed review results: only failedReviewCount === 1 without a scopeBlocker finding permits one fresh full automatic retry. Every scope blocker or count of two or greater projects await-user-direction before a directed or qualified host-authorized attempt. When all runnable candidates require an explicit retry, status is ready and projects await-user-direction. This includes a blocked run superseded by reset to independent work once that work finishes. Detail identifies the failed feature from durable runs. Explicit flow_run_start(featureId) begins that retry without reset. Pre-review resets and rejected stale-source submissions do not increment the derived count.
  • Completed close is allowed only after every feature has a completed current run. Inspections may complete with negative findings. Full completion assurance still requires passing current reviews and the declared evidence. Deferred and abandoned close explicitly supersede active work.

Terminal capacity

New nonterminal mutations reserve one operation, 197,632 compact JSON bytes, and the last safe revision for close. Exact replays bypass admission. Legacy open v5 limits remain 4,096 operations and 4 MiB. A final matching close at the session revision may reach 4,097 operations and 4,391,936 bytes. Removing terminal material must leave at most 4,096 operations and 4 MiB plus four bytes for run supersession. Closure digests and all session invariants still apply. No operation is pruned. Open files retain their physical 4 MiB limit. Extended archives require a newer reader, including after downgrade. Legacy MAX_SAFE_INTEGER revisions stay readable but have no successor. See terminal recovery.

Causality and idempotency

Every accepted mutation advances one nonnegative revision. Mutation requests carry the expected revision and a stable operation ID. An exact previously accepted request resolves to the same durable entity at its current projection without another mutation. Reusing the ID for another kind or payload fails. Rejected work does not consume the operation ID.

Revision and durable record order are authoritative. Session correctness must not depend on UTC time, model-provided time, elapsed duration, or timestamp repair.

flow_status adds process-local host capability, activity, and detail timing. Automatic continuation defines these fields and source-bound progress. They add no Session v5 state or authority.

Every successful status read also derives statusReport from its typed projection. The report owns human lifecycle and recovery text and is not stored. At await-user-direction, the manager renders the complete detail report, including defer/abandon choices and retry authority. A matching failed required gate may supply its declared command and environment as historical facts; this does not establish a current failure or convert an observed gate into a repair.

Validation and review

Validation and review defines check and closure rules. Optional feature checks freeze pass or observe intent at approval. Flow stores a bounded source-bound packet before assignment. Reviewers page through it in flow_status without shell access. Missing or stale packets consume no failed review.

Bounded worker waves

Serial means one durable active feature run and one authoritative combined validation/review chain. The manager works serially by default, but may delegate two or three exact, non-overlapping slices to one initial flow-worker cohort when parallel work has clear benefit, and at most one targeted follow-up cohort. Existing implementation authority covers a qualifying wave; workers need no separate user approval.

Workers contribute only inside their assigned boundary. The manager owns shared files, integration, evidence acceptance, the combined diff, authoritative validation, and review dispatch. Ordinary worker edits are allowed so a cohort can run without approval interruptions; Shell, .flow and .git metadata paths, nested delegation, and Flow-state tools are denied. Exact per-assignment paths remain a prompt contract because one static reusable agent cannot express a dynamic file ACL; the manager audits assigned versus changed paths after every cohort. Every assignment includes the manager's preflighted adversarial acceptance and risk checklist. Generic agents may not substitute for a flow-worker or the reserved reviewer. No wave state is persisted; after interruption, ordinary status and worktree inspection remain authoritative. ADR 0006 records the rationale and rejected heavier designs; the package's flow-run guidance is the executable manager contract.

Persistence

  • Workspace resolution is canonical and project-scoped.
  • .flow and managed files are not followed through symbolic links.
  • One cross-process project lock protects transactions.
  • Session writes validate the complete schema and use atomic replacement with durability sync where supported.
  • Unreadable active state is quarantined instead of overwritten.
  • Close first records the terminal state durably, then publishes a no-overwrite archive and clears active state; compact status projects the exact retry request needed to converge after interruption.
  • Exact active close replay confirms that the canonical active bytes still match, synchronizes the file and .flow durability boundary, and does not rewrite the Session. Exact archived replay re-synchronizes no-overwrite publication and active cleanup, including when cleanup is already absent. A delayed replay must not clear a different active session.
  • An archive or active-state collision preserves both documents and returns manualRecoveryRequired with no archiveRetry; callers stop automatic retry rather than overwrite or delete either side. Closed status re-derives an archive collision from the existing history document, so interruption cannot restore automatic retry. This behavior adds no persisted recovery state.
  • Every durably accepted close returns identical derived workflowData.delivery on success, archive-pending recovery, exact retry, and delayed history replay. handoff declares formatVersion: 1 and externalActionAuthority: "not-granted". Delivery contains goal, closure, progress, each feature's attempts, outcome, terminal findings, reported artifact groups, and tiered assurance limits. Copy summary.lines unchanged. Closure kind, exact unmet commands and declared platforms infer no availability. closure.summary, report and blocked statusReport stay unchanged.
  • Delivery derives from the closed Session or archive. Session v5 and archive JSON store neither projection nor report. A report artifact needs a user request.
  • Source identity hashes sorted effective workspace path/type/content tuples; .git and .flow are excluded. It is a content fingerprint, not a Git audit chain.
  • Source identity requires a readable Git worktree and rejects tracked submodules explicitly.
  • Lock timeout fails closed. Reclamation requires an absent local PID, an exclusive claim, and a matching owner token. Live or unreadable owners are untouched; age grants no ownership. Shared-host or cross-PID-namespace workspaces are unsupported.

OpenCode surface

Compact flow_status includes the goal and derived findingsDigest, empty as []. Blocked state adds featureId, attempt and failedReviewCount. No intent, hold or retry budget is persisted. At blocked or ready await-user-direction, read detail once and report findings. Reset-only compatibility never restores implicit selection. See Session v5.

options.typesafeApiKeyEnv names the server variable (default TYPESAFE_API_KEY). Names match [A-Za-z_][A-Za-z0-9_]*; invalid names warn and disable the source. Custom names never fall back. Missing/blank values disable defaults; others are trimmed at runtime. The key goes only in auth headers, never options, logs or telemetry. Restart after environment changes. A key enables shadow defaults (six attempts, $0.02); plugin recovery: { "mode": "off" } disables the source. --recovery=off disables advice, not retry limits. First retry stays automatic; fresh direction permits one retry/start. Shadow grants nothing; release delegation is disabled. recoveryStatus.last adds process-local assessment duration, transport attempts, reservation deltas, scores, and threshold checks. reservedUsd is an upper-bound reservation, not billed cost. responseUsage counts only the final validated response, excluding failed attempts. Without validated usage it is null. Custom providers may leave transport facts null. See ADR 0016.

Commands

Command Contract
flow-auto Normal end-to-end driver for the authorized lifecycle.
flow-plan Plan-only/advanced creation, revision, and approval; same-goal approved plans are reported without mutation.
flow-run Advanced/recovery execution of one approved feature after request alignment.
flow-review Internal/recovery dispatch for a runtime-created reviewer assignment.
flow-status Advanced/recovery projection of compact durable state and the next action.

flow-review stays in the public inventory because OpenCode dispatches the reserved reviewer through it and recovery may need it. It is not an ordinary user starting point.

Tools

Tool Contract
flow_guidance Load one package-owned guide.
flow_status Read compact, execution, detail, reviewer, or paged reviewer-evidence state.
flow_plan_save Create or replace the active draft plan.
flow_plan_amend Record a bounded prerequisite repair after a failed canonical gate.
flow_plan_approve Approve and lock the draft plan.
flow_run_start Start one runnable approved feature.
flow_validation_start Arm observation of the exact next Shell command.
flow_review_start Create the run's independent review assignment.
flow_feature_complete Reviewer-only result submission; exact accepted requests replay read-only.
flow_feature_reset Supersede a failed attempt and optionally atomically start the exact authorized retry or dependency-independent feature through nextFeatureId.
flow_session_close Close and archive the session, returning the same concise derived delivery and tiered assurance on every durably accepted close path.

Tools accept nested request and return state under workflowData; mutations require a current revision and stable operation ID. Closure adds derived delivery. flow_guidance instead takes an ID and returns Markdown; see authoring.

Guides

Guide Contract
flow Manager orientation and authority boundary.
flow-plan Planning and conversational approval.
flow-run Serial execution and optional bounded waves.
flow-review Independent review of one runtime assignment.

Hidden agents

Agent Boundary
flow-planner Draft advice using read, glob, and grep. The manager saves and approves.
flow-worker Bounded implementation contribution; ordinary edits are allowed, while Shell, .flow and .git metadata paths, external-directory access, skills, delegation, and Flow tools are denied.
flow-reviewer Independent workspace-read-only inspection; only flow_status and its exact flow_feature_complete lifecycle submission are allowed among Flow tools.

Project modelPreferences options take precedence over global picker choices. Global choices override reviewer options and environment defaults. A role reset restores its base configuration. Explicit picker selections clear that role's reasoning variant. Status reports requested roles and the latest observed coding model. These are process-local observations. Manager variants survive continuation. Configuration does not confirm provider execution.

Duplicate plugin instances for the same canonical project fail closed through a small process-global guard. Instances for different projects do not conflict. The guard does not elect a winning version or modify configuration.

Distribution and release

The public package is loaded through OpenCode's ordinary npm plugin configuration and native plugin command. Flow ships no installer CLI and performs no startup activation, cache cleanup, inventory, version election, or automatic repair.

The deterministic local gate is bun run check. CI keeps a normal Linux check, targeted platform persistence coverage, dependency and workflow checks, a real OpenCode live smoke, package smoke, and release publication. Removed lifecycle soaks, harness promotion, replay, and cross-version active session gates must not return without a new ADR that removes an equal or larger amount of product machinery.

Model evals are the one exception, admitted by ADR 0010 against the prompt prose the declared gate replaced. They run weekly and on demand in one workflow, never in a gate a contributor waits on, and skip themselves without a configured matrix or credentials. bun run qualify seals a complete campaign and exact canary. A scenario without a threshold, or a required scenario the report omitted, fails.

Bounded-wave coverage should test the real agent permissions, manager guidance, and host-visible configuration without adding a scheduler or tests-of-tests.

See Model-driven wave evidence for the manual canary policy.

The optional ./tui export provides /flow-models. It saves role preferences after confirmation and adds no lifecycle tool.