@kontourai/flow-agents 0.1.1

package/context/contracts/builder-kit-workflow-state-contract.md

@@ -0,0 +1,319 @@
+# Builder Kit Workflow State Contract
+
+This contract defines the durable routing state for Builder Kit build-flow pickup and resume. It keeps `state.json` limited to canonical Flow Agents workflow routing and stores rich pickup decisions in a documented Probe record sidecar referenced by `state.json`, `handoff.json`, and the session artifact.
+
+Builder Kit owns product-level build-flow coordination. Flow Agents owns the workflow harness, artifact conventions, primitive execution, and evidence gates. Flow remains the owner of Flow gate semantics. Builder Kit contracts may route to Flow Agents primitives, but must not redefine pass, fail, approval, or release authority semantics.
+
+## State Surfaces
+
+Builder Kit routing uses these surfaces together:
+
+| Surface | Owner | Purpose |
+| --- | --- | --- |
+| `state.json` | Flow Agents workflow state | Durable current phase, status, next action, and routing target. |
+| `handoff.json` | Flow Agents handoff | Human and machine-readable pause, resume, delegation, or blocker summary. |
+| Builder Kit Probe record | Builder Kit contract sidecar | Rich pickup/design decisions used to choose the next build-flow step. |
+| session artifact | active orchestrator or worker | Human-readable execution progress, modified files, evidence, and links. |
+| plan, acceptance, evidence, critique, release, learning sidecars | phase owners | Phase-specific gates and proof. |
+
+`state.json` must not be overloaded with detailed Probe decisions. It should reference the Probe record path in `artifact_paths` or `next_action.target_artifact` when the Probe record is the target for resuming or deciding the next step. `handoff.json` should also reference the Probe record whenever a paused Builder Kit build-flow cannot be resumed correctly from `state.json` alone.
+
+## Required Routing Fields
+
+Every Builder Kit build-flow pause, resume, or step transition must make the following fields recoverable from artifacts alone.
+
+| Field | Durable location | Required meaning |
+| --- | --- | --- |
+| current step | `state.phase`, `state.status`, and Probe record `current_step` | The current Builder Kit step or direct Flow Agents primitive. |
+| next step | `state.next_action` and Probe record `next_step` | The next step to run after resume or after the current primitive exits. |
+| route reason | Probe record `route_reason`; summarized in `state.next_action.summary` | Why this route was selected, including missing state, evidence, decisions, or blockers. |
+| selected work item refs | Probe record `selected_work_items`; optionally linked in `handoff.json` | Neutral work item references from the work-item contract. |
+| missing evidence | Probe record `missing_evidence`; evidence sidecar for verification gaps | Evidence needed before planning, execution, verification, or release can proceed. |
+| unresolved questions | Probe record `unresolved_questions`; handoff summary when user input is needed | Open decisions that block or shape the next step. |
+| accepted gaps | Probe record `accepted_gaps`; acceptance sidecar when tied to criteria | Known gaps explicitly accepted for this iteration. |
+| resume prompt | Probe record `resume_prompt`; handoff summary for future sessions | The concise instruction needed to resume without chat memory. |
+| artifact references | `state.artifact_paths`, `state.next_action.target_artifact`, handoff refs, and Probe record `artifact_refs` | Paths to sidecars, plans, evidence, source refs, and docs needed for pickup. |
+| automation mode | Probe record `automation_mode` and route reason | The active Builder Kit automation boundary: `manual`, `guided`, `strict`, or `autonomous-bounded`. |
+| recovery mode | Probe record `recovery_mode` | Whether the workflow came from a direct primitive invocation or Builder Kit build-flow recovery. |
+| probe status | Probe record `probe_status` and handoff summary | Machine-checkable pickup Probe outcome: `missing`, `required`, `in_progress`, `passed`, `accepted_gap`, or `blocked`. |
+| probe artifact ref | Probe record `probe_artifact_ref` | The artifact or sidecar path that contains the current pickup Probe evidence. |
+| grouping decision | Probe record `grouping_decision` | Whether selected work is a single item, independent multi-item set, justified bundle, unsafe group, or empty board. |
+| WIP/shepherding decision | pull-work artifact `wip_assessment`, `my_active_work`, `shepherding_candidates`, `stale_worktrees`, `open_prs_by_me`, `global_conflicts`, `dependency_impacts`, and `start_new_work_decision` | Whether starting new work is appropriate or whether existing personal work should be shepherded first. |
+| worktree lifecycle | pull-work artifact `worktree_lifecycle`; handoff summary when cleanup is pending | How long an isolated worktree should be retained, who owns cleanup, and which command removes it after merge/abandonment. |
+| Flow boundary | Probe record `flow_boundary` | Explicit preservation of Flow gate authority and Flow Agents harness ownership. |
+
+## Probe Record
+
+A Builder Kit Probe record is a JSON sidecar beside the other workflow artifacts, for example `.flow-agents/<slug>/builder-kit-probe.json`. It is the durable location for pickup/design context that would otherwise make `state.json` too broad.
+
+Required shape:
+
+```json
+{
+  "schema_version": "1.0",
+  "task_slug": "example-task",
+  "current_step": "design-probe",
+  "next_step": "plan-work",
+  "route_reason": "selected work item has enough evidence and no unresolved blocking questions",
+  "automation_mode": "guided",
+  "recovery_mode": "builder-kit-build-flow",
+  "probe_status": "passed",
+  "probe_artifact_ref": ".flow-agents/example-task/builder-kit-probe.json",
+  "grouping_decision": {
+    "status": "single-item",
+    "justification": "one selected work item"
+  },
+  "selected_work_items": [
+    {
+      "provider": "github",
+      "ref": "#68",
+      "title": "Builder Kit workflow state contract"
+    }
+  ],
+  "missing_evidence": [],
+  "unresolved_questions": [],
+  "accepted_gaps": [],
+  "resolution_hints": [],
+  "resume_prompt": "Resume Builder Kit build-flow by running plan-work from the selected work item and Probe record.",
+  "artifact_refs": [
+    ".flow-agents/example-task/state.json",
+    ".flow-agents/example-task/handoff.json"
+  ],
+  "flow_boundary": {
+    "builder_kit_owns": "product-level build-flow coordination and next-step selection",
+    "flow_agents_owns": "workflow artifacts, primitive execution, and evidence harness",
+    "flow_owns": "gate authority semantics"
+  }
+}
+```
+
+Allowed `current_step` and `next_step` values are Builder Kit step names or direct Flow Agents primitive names. Use `pull-work`, `design-probe`, `pickup-probe`, `plan-work`, `execute-plan`, `verify-work`, `evidence-gate`, `release-readiness`, `learning-review`, `blocked`, or `done` unless a downstream contract defines a narrower Builder Kit flow. The Builder Kit flow step remains `design-probe`; `pickup-probe` is the Builder Kit specialization record or skill used to prepare a selected work item for planning.
+
+`selected_work_items` should use the neutral fields from `context/contracts/work-item-contract.md` where available. Provider-specific IDs may be included, but routing must not depend on a provider-specific shape when the neutral reference is present.
+
+## Resolution Hints
+
+Builder Kit Probe records may include optional `resolution_hints` for missing evidence, `NOT_VERIFIED`, or accepted-gap readiness states. Use them when Builder Kit can name the blocked readiness claim, deterministic blocked references, required evidence, and the step that should resolve the gap. Omit them when the Probe record has no actionable readiness gap or when a direct Flow Agents primitive has all inputs needed without Builder Kit build-flow context.
+
+The canonical machine storage for `resolution_hints` is the Builder Kit Probe JSON record. Markdown pull-work, pickup, plan, or session artifacts may summarize the hints or link to the Probe record for humans, but they are not a second machine contract and must not introduce divergent machine-readable hint shapes.
+
+Stable hint fields:
+
+| Field | Meaning |
+| --- | --- |
+| `gap_id` | Stable identifier for the gap class Builder Kit is describing, such as `revision_freshness_not_verified`. |
+| `claim_id` | Builder Kit-owned readiness claim affected by the gap, such as `planning.baseline.current`. This is not a Flow gate schema or Veritas claim requirement. |
+| `reason_code` | Stable reason the claim is missing, inconclusive, `NOT_VERIFIED`, or accepted as a gap. |
+| `blocked_refs[]` | Deterministic references blocked by the gap. Entries should be objects with stable `kind` and `id` values, for example `acceptance_criterion` / `AC2`, `workflow_gate` / `plan-work.readiness`, and `flow_step` / `builder.build.plan`. |
+| `resolve_at` | The Builder Kit or Flow Agents step expected to resolve or explicitly accept the gap. Use an object with at least `step`; include `owner` or `artifact` when useful. |
+| `required_evidence[]` | Evidence records needed to resolve the claim. Entries should have stable ids, a short description, and expected source or artifact refs when known. |
+| `fallback_policy_id` | Stable policy id for an explicitly accepted fallback path when fresh evidence cannot be recovered for this iteration. The fallback is an accepted gap, not proof that the missing evidence is fresh. |
+| `summary` | Human-readable summary of what is blocked and how to resolve it. |
+
+Baseline freshness example for missing historical `planned_base_sha`:
+
+```json
+{
+  "probe_status": "accepted_gap",
+  "accepted_gaps": [
+    {
+      "gap_id": "revision_freshness_not_verified",
+      "claim_id": "planning.baseline.current",
+      "reason_code": "missing_planned_base_sha",
+      "summary": "Historical planned_base_sha was not recorded; current main and provider history are accepted as the fallback baseline for this iteration."
+    }
+  ],
+  "resolution_hints": [
+    {
+      "gap_id": "revision_freshness_not_verified",
+      "claim_id": "planning.baseline.current",
+      "reason_code": "missing_planned_base_sha",
+      "blocked_refs": [
+        {
+          "kind": "acceptance_criterion",
+          "id": "AC2"
+        },
+        {
+          "kind": "workflow_gate",
+          "id": "plan-work.readiness"
+        },
+        {
+          "kind": "flow_step",
+          "id": "builder.build.plan"
+        }
+      ],
+      "resolve_at": {
+        "step": "pickup-probe",
+        "owner": "builder-kit"
+      },
+      "required_evidence": [
+        {
+          "id": "current_target_ref",
+          "description": "Current target branch or ref recorded during pickup.",
+          "source": "pull-work provider scan or local git baseline",
+          "example_value": "main"
+        },
+        {
+          "id": "current_target_sha",
+          "description": "Current target commit SHA recorded during pickup.",
+          "source": "pull-work provider scan or local git baseline",
+          "example_value": "73f050b275290838a5b8f3a5a1e9eb8715830c46"
+        },
+        {
+          "id": "provider_history",
+          "description": "Provider issue/project history or equivalent source proving the selected work context inspected during pickup.",
+          "source": "provider adapter output",
+          "example_value": ".flow-agents/builder-kit-not-verified-resolution-hints/builder-kit-not-verified-resolution-hints--pull-work.md"
+        },
+        {
+          "id": "source_artifact",
+          "description": "Source shaped artifact or pickup artifact used to accept the fallback baseline.",
+          "source": ".flow-agents/<slug>/<slug>--idea-to-backlog.md",
+          "example_value": ".flow-agents/builder-kit-not-verified-resolution-hints/builder-kit-not-verified-resolution-hints--idea-to-backlog.md"
+        }
+      ],
+      "fallback_policy_id": "accepted_fallback_baseline.current_target_plus_provider_history",
+      "summary": "Resolve missing planned_base_sha at pickup-probe by recording the current target ref and SHA, provider history/source artifact evidence, and the accepted fallback baseline policy before planning."
+    }
+  ]
+}
+```
+
+This example is intentionally limited to baseline freshness for missing or inconclusive `planned_base_sha`. It does not make the fallback baseline fresh planned evidence; it records an accepted Builder Kit readiness gap with deterministic repair guidance.
+
+Boundary and non-goal rules:
+
+- Builder Kit owns readiness guidance, including optional `resolution_hints`, Builder Kit `claim_id` names, and product-flow next-step selection.
+- Flow Agents owns workflow artifacts, sidecars, primitive execution, modified-file recording, and evidence harness behavior.
+- Flow owns gate semantics. `resolution_hints` must not redefine Flow pass, fail, approval, release, or route-back authority.
+- Veritas remains optional evidence. A hint may reference Veritas output when present, but Builder Kit Probe records must not require Veritas schemas or duplicate Veritas policy contracts.
+- Generic Flow Agents sidecar schemas, including `schemas/workflow-evidence.schema.json`, are not extended by this Builder Kit field.
+- Direct primitive workflows remain valid without Builder Kit-specific `resolution_hints`.
+
+## Product Flow Chaining And Primitive Stopping
+
+Product-level Builder Kit flows may guide the next step; direct primitives must not surprise the user by auto-continuing.
+
+- `builder-shape` is the product-level shape entry point. It delegates to `idea-to-backlog` without requiring the user to name that primitive, then stops at the backlog gate unless issue sync or continuation was explicitly requested.
+- Builder Kit `build` is the product-level build entry point. It may guide `pull-work -> design-probe / pickup-probe -> plan-work` when the user asked for the Builder Kit build flow.
+- Direct `idea-to-backlog`, direct `pull-work`, and direct `plan-work` remain standalone primitives. They record state and report the expected next step, but they do not auto-continue merely because a product flow exists.
+- If a direct primitive is invoked with missing upstream Builder Kit state, it must explain the missing pre-step and offer the product-level entry point or the correct previous primitive instead of fabricating state.
+- If the user declines guided continuation, record `automation_mode: "manual"` and the expected `next_step` in the Probe record or handoff.
+
+## Pull Work WIP And Worktree Lifecycle
+
+Builder Kit build pickup must not treat all active work equally. `pull-work` records two separate views before selecting new work:
+
+- Personal WIP controls whether new work should start. This includes the current user's dirty worktrees, local branches, open PRs, active sidecars, review/verification/release decisions, and stale worktrees.
+- Global work informs safety and priority. Work by others blocks only when it creates file-scope conflict, dependency, sequencing, release-lane, provider-state, or artifact-contract risk.
+
+The pull-work artifact must record:
+
+- `my_active_work`
+- `shepherding_candidates`
+- `stale_worktrees`
+- `open_prs_by_me`
+- `global_conflicts`
+- `dependency_impacts`
+- `start_new_work_decision`
+
+`start_new_work_decision` is the durable gate for pickup. Use `proceed` only when personal WIP is within policy and global risks are recorded or accepted. Use `shepherd_existing`, `cleanup_required`, `blocked`, or `needs_user` when existing work, stale worktrees, unresolved PRs, or decisions should be handled first.
+
+When a worktree is selected, the artifact must also record `worktree_lifecycle`:
+
+- path
+- branch
+- retain-until condition: PR merged, branch abandoned, or user override
+- cleanup owner
+- cleanup command
+- cleanup blockers such as open PR, pending review, pending CI, dirty files, unpublished commits, or user decision
+
+Publish-change retains the worktree so review, CI, and follow-up fixes can happen in the same isolated checkout. Final acceptance, release cleanup, or explicit abandonment owns `git worktree remove <path>` and any branch deletion when safe. Files should not be copied back to a main checkout by hand.
+
+## Automation Modes
+
+Builder Kit routing must record one automation mode:
+
+| Mode | Boundary |
+| --- | --- |
+| `manual` | Surface state, recommendations, and resume prompt only. Do not advance to the next primitive without explicit user instruction. |
+| `guided` | Recommend and prepare the next step. Ask before crossing from Probe/design into planning or execution when unresolved questions or missing evidence remain. |
+| `strict` | Advance only when all required artifacts, evidence, conflict checks, and acceptance inputs are present. Missing upstream state routes to `decision_gap` through `design-probe`. |
+| `autonomous-bounded` | Advance within the approved work item, file ownership, sandbox, and Definition of Done boundaries. Stop for scope expansion, missing gate evidence, destructive actions, or Flow authority decisions. |
+
+Mode changes must be explicit in the Probe record route reason or handoff. A stricter mode may stop earlier than the table permits. A looser mode must not bypass Flow Agents evidence gates or Flow authority.
+
+## Direct Primitive Recovery
+
+Direct primitive invocation remains valid. A user or orchestrator may call `pull-work`, `plan-work`, `execute-plan`, `verify-work`, or another primitive without Builder Kit build-flow state.
+
+When a direct primitive has sufficient required inputs, it should proceed according to that primitive's own contract and update the standard Flow Agents artifacts. It may create a Probe record only if Builder Kit resume will need richer pickup context.
+
+When Builder Kit build-flow recovery detects missing upstream state, selected work item evidence, or unresolved route decisions, it must distinguish that from direct primitive use:
+
+| Scenario | Required route |
+| --- | --- |
+| Direct primitive has complete primitive inputs | Continue the primitive and record standard state/handoff. |
+| Direct primitive lacks required primitive inputs | Mark `state.next_action.status` as `needs_user` or `blocked` and summarize the missing input. |
+| Builder Kit build-flow lacks selected work item or design context | Route `decision_gap` to `design-probe` in the Probe record and summarize that in `state.next_action`. |
+| Builder Kit build-flow has selected work item but incomplete pickup evidence | Route to `pickup-probe` or `design-probe` with `missing_evidence` populated. |
+| Builder Kit build-flow has complete pickup context | Route to `plan-work` with the Probe record and selected work item refs linked. |
+
+`decision_gap` is a route reason, not a new `state.phase`. Use the existing `pickup` or `planning` phase as appropriate and put the detailed reason in the Probe record.
+
+Primitive recovery prompts should name the next intended step. Examples:
+
+- Missing backlog item: "This needs Builder Kit shape / idea-to-backlog before pull-work can select executable work."
+- Missing pickup Probe: "This Builder Kit build-flow plan request lacks pickup Probe evidence; route `decision_gap -> design-probe` and complete `pickup-probe` before planning."
+- Manual mode: "Direct primitive mode selected; next expected step is `plan-work` after you approve the recorded handoff."
+
+## Guided Next-Step Behavior
+
+The default Builder Kit build-flow route is:
+
+```text
+pull-work -> design-probe / pickup-probe -> plan-work -> execute-plan -> verify-work -> evidence-gate
+```
+
+Routing rules:
+
+- After `pull-work`, if no work item is selected, route to `design-probe` with route reason `decision_gap`.
+- After `pull-work`, if one or more work items are selected but evidence is incomplete, route to `pickup-probe` with `missing_evidence` populated.
+- After `pickup-probe`, if unresolved questions remain and are not accepted gaps, route to `design-probe` or user input according to the automation mode.
+- After `design-probe` or `pickup-probe`, if the selected work item, acceptance criteria, evidence, conflict scan, and ownership boundaries are sufficient, route to `plan-work`.
+- After `plan-work`, route to `execute-plan` only when the plan is approved by the active workflow mode and ownership boundaries remain valid.
+- Mid-work resume must choose the next action from artifacts, not chat memory.
+
+## Per-Item Pickup Probe Enforcement
+
+Every selected work item or explicitly bundled work group in Builder Kit `build` needs a fresh pickup Probe before planning.
+
+- One item is the default selection after `pull-work`.
+- Multiple items are allowed only when the Probe record includes `grouping_decision.status: "independent-items"` or `"justified-bundle"` and records the bundle or independence justification plus conflict risks.
+- A broad prior instruction such as "continue through all waves" or "pick up the next tasks" must not authorize planning for a newly selected item after a merge. The workflow may inspect the queue, but must create a fresh Probe record before planning or execution.
+- Unsafe grouped work must route back to `pull-work` with `grouping_decision.status: "unsafe-group"` and a split recommendation.
+- Empty board state must route to Builder Kit shape / `idea-to-backlog`; do not improvise implementation work.
+
+Planning may proceed only when `probe_status` is `passed` or `accepted_gap` and `probe_artifact_ref`, selected work refs, grouping decision, accepted gaps, expected modified files, conflict risks, and resume prompt are present.
+
+## Resume Requirements
+
+A future session must be able to resume Builder Kit build-flow from these artifacts alone:
+
+- `state.json` identifies current phase/status and the next action target.
+- `handoff.json` summarizes the pause, blocker, delegation, or resume target.
+- The Probe record explains the current step, next step, route reason, selected work item refs, missing evidence, unresolved questions, accepted gaps, automation mode, and recovery mode.
+- The session artifact records modified files and progress.
+- Phase sidecars record acceptance criteria, evidence, critique, release, or learning state when those gates have started.
+
+If any required resume field is absent, Builder Kit build-flow must route through `design-probe` or `pickup-probe` before planning or execution. Direct primitive recovery may instead ask for the missing primitive input.
+
+## Downstream Contract Target
+
+Issues #64, #51, and #62 are downstream consumers of this contract. They may add implementation, hooks, provider behavior, or fixtures, but they must preserve:
+
+- `state.json` as the routing-focused Flow Agents state sidecar.
+- Builder Kit Probe records as the rich pickup/design decision surface.
+- Direct primitive invocation as valid outside Builder Kit build-flow.
+- Builder Kit build-flow recovery through `decision_gap` to `design-probe` when upstream state is missing.
+- Flow boundary preservation: Builder Kit coordinates product flow, Flow Agents coordinates harness artifacts and primitives, and Flow owns gate authority semantics.

package/context/contracts/delivery-contract.md

@@ -0,0 +1,69 @@
+# Delivery Contract
+
+Delivery chains planning, execution, review, verification, Goal Fit, and final acceptance until the user-facing goal is genuinely handled.
+
+## Workflow
+
+1. Create or resume a session artifact that follows `context/contracts/artifact-contract.md`.
+2. Plan with `context/contracts/planning-contract.md`.
+3. Execute with `context/contracts/execution-contract.md`.
+4. Review code quality and security where relevant. Reviews are report-only.
+5. Verify with `context/contracts/verification-contract.md`.
+6. Route failures, findings, and `NOT_VERIFIED` gaps back through execution or to an explicit user decision.
+7. Complete the Goal Fit Gate before final response.
+8. Publish verified changes before release readiness: commit the verified diff, push the branch, open or update the provider change record or record an explicit no-provider-change reason, and collect provider check evidence.
+9. Run release readiness against the provider change/branch/check state, not only local verification.
+10. Complete Final Acceptance and docs promotion after CI, merge, release, or explicit acceptance.
+
+## Delegation Gates
+
+Delivery orchestrators must invoke the primitive delegates for the planning and verification gates:
+
+- `plan-work` delegates planning to `tool-planner`.
+- `review-work` delegates critique to `tool-code-reviewer` and conditionally to `tool-security-reviewer`.
+- `verify-work` delegates verification to `tool-verifier`.
+- UI or browser-facing verification also delegates to `tool-playwright`.
+
+These gates still apply when the environment is read-only, the repository is not writable, or a prerequisite is missing. In blocked environments, attempt the required delegation first when the tool is available, then report the blocked result as `NOT_VERIFIED` or `FAIL` with evidence. Do not replace the delegate gate with a local summary.
+
+When reporting gate progress or final delivery evidence, name the exact delegate ids (`tool-planner`, `tool-worker`, `tool-code-reviewer`, `tool-security-reviewer`, `tool-verifier`, `tool-playwright`) rather than generic labels like planner, worker, reviewer, verifier, or browser verifier. Exact names make telemetry gaps and text-only evals auditable.
+
+## Goal Fit Gate
+
+Before claiming delivery, the session artifact must answer:
+
+- [ ] Original user goal restated
+- [ ] Every acceptance criterion has evidence
+- [ ] User-facing workflow was exercised or documented
+- [ ] Local/project and global scope are handled when relevant
+- [ ] Unknown, NOT_VERIFIED, and TODO gaps are resolved or explicitly accepted
+- [ ] Dashboard/UI changes have visual evidence when relevant
+- [ ] Durable docs target is updated, scheduled for final acceptance, or marked not needed with reason
+
+## Loop Rules
+
+- Reviewers and verifiers are report-only.
+- Any code change after review or verification requires another clean review and verification pass.
+- CRITICAL or HIGH review findings route through re-planning unless the fix is explicitly narrow and safe.
+- MEDIUM findings and verification FAIL items route through an execution fix pass.
+- The loop exits only when review and verification are clean in the same iteration and Goal Fit is complete or explicitly accepted.
+
+## Final Acceptance
+
+After CI passes and the work is merged, released, or otherwise accepted:
+
+- [ ] CI/relevant checks passed
+- [ ] verified diff committed and pushed
+- [ ] provider change record created or updated, or explicit no-provider-change reason recorded
+- [ ] merge, release, or hold decision recorded
+- [ ] working artifacts archived or linked
+- [ ] long-lived docs updated with why and how the feature was built
+- [ ] durable docs link back to the provider record, archived plan, or session artifact when useful
+- [ ] local `.flow-agents/` runtime artifacts remain untracked, and durable outcomes are promoted before merge to `main`
+- [ ] follow-up issues or learning-review items created for deferred work
+
+## Distribution Rule
+
+This contract is shared across Codex, Kiro, Claude Code, and future distributions. Distribution-specific files may adapt paths, tool names, and hook wiring, but they should not redefine the workflow rules independently.
+
+GitHub PRs are the first `ChangeProvider` adapter example: in GitHub-backed projects, the provider change record is normally a PR and provider checks are normally PR checks.

package/context/contracts/execution-contract.md

@@ -0,0 +1,53 @@
+# Execution Contract
+
+Execution turns an approved plan artifact into code and local evidence while preserving parallel safety.
+
+## Required Inputs
+
+- plan artifact path
+- session artifact path
+- task description, files, acceptance criteria, and Definition Of Done items relevant to the task
+- prior wave results when executing a later wave
+- sandbox mode and escalation policy from `context/contracts/sandbox-policy.md`
+
+## Worker Rules
+
+- Validate scope before writing code.
+- Confirm the planned `sandbox_mode` still fits the task before mutating files or systems.
+- Check existing task artifacts for overlapping modified files.
+- Work with existing user or agent changes; do not revert unrelated work.
+- Follow local project patterns and use the smallest implementation that satisfies the plan.
+- Update the session or worker task artifact with modified files and progress. Modified files are required execution evidence for conflict detection, verification scope, and optional governance providers.
+- Prefer `npm run workflow:sidecar -- advance-state` when available to update `state.json` and `handoff.json` at phase boundaries.
+- Run relevant validation for the files changed.
+- If instructions are insufficient, another in-progress task blocks the work, the required sandbox mode is stronger than planned, or approval is missing, stop and report the blocker rather than guessing.
+
+## Sandbox Modes
+
+Use the vocabulary in `context/contracts/sandbox-policy.md`:
+
+- `local-read-only`
+- `local-edit`
+- `worktree`
+- `container`
+- `cloud-sandbox`
+- `privileged-integration`
+
+Execution may upgrade to a stronger mode when risk increases. Downgrades require a recorded reason.
+
+## Parallel Wave Rules
+
+- Independent tasks with no shared files can run in the same wave.
+- Shared files, generated artifacts, migrations, and cross-cutting contracts should be serialized unless the plan gives explicit file ownership.
+- Worker delegation must name the exact worker role (`tool-worker`) rather than spawning an unnamed/default implementation agent.
+- After each wave, collect results, check conflicts, and update the session artifact before starting the next wave.
+
+## Completion Rules
+
+Execution is complete only when:
+- all planned waves are complete or explicitly blocked
+- modified files are recorded in the session/deliver artifact or an evidence sidecar that the verifier can read; do not store them in `state.json` unless the workflow state schema supports that field
+- sandbox mode and approval/rollback assumptions are recorded when relevant
+- local validation attempted for changed areas
+- failures caused by the execution are fixed or reported as blockers
+- remaining gaps are ready for verification rather than hidden in the final summary

package/context/contracts/governance-adapter-contract.md

@@ -0,0 +1,67 @@
+# Governance Adapter Contract
+
+Governance adapters let Flow Agents ask an external tool for policy, proof, or trust evidence without baking repo-specific policy into Flow Agents core.
+
+## Boundary
+
+Flow Agents owns:
+
+- workflow phase routing
+- acceptance criteria and goal-fit checks
+- `evidence.json` references to external proof
+- release, learning, and handoff decisions
+
+The adapter owns:
+
+- repo-local policy semantics
+- evidence check selection and execution
+- native evidence artifact shape
+- rule explanations and just-in-time guidance
+- policy promotion or retirement logic
+
+Flow Agents must not copy an adapter's rule model into core skills. It should invoke the adapter when configured, record the artifact reference, and route the resulting pass/fail/not-verified status through normal evidence gates.
+
+## Minimum Adapter Shape
+
+An adapter integration should define:
+
+- `id`: stable adapter id, such as `veritas`
+- `availability_check`: command or file probe that proves the adapter is installed/configured
+- `readiness_command`: optional command that explains required proof or verification budget
+- `evidence_command`: command that produces a native evidence artifact or machine-readable result
+- `feedback_command`: optional command that emits concise agent-facing guidance
+- `artifact_pattern`: where native evidence artifacts are written
+- `standard`: evidence standard used in Flow Agents sidecars, such as `veritas`, `sarif`, or `opentelemetry-log`
+- `sandbox_mode`: minimum mode required by `context/contracts/sandbox-policy.md`
+- `failure_routing`: whether failures return to planning, execution, verification, release readiness, or human decision
+
+## Veritas Boundary
+
+Veritas is the first known fit for this contract.
+
+Use Veritas when a repo has Veritas configuration and the work needs repo-local standards, authority, evidence checks, readiness, or JIT rule guidance.
+
+Do not require Veritas for the Flow Agents core surface or Builder Kit. Treat it as an optional development/governance provider:
+
+- `veritas readiness --check evidence --working-tree`: readiness evidence, native report, and feedback draft
+- `veritas readiness --check boundaries --working-tree`: protected-area and ownership signal
+- `veritas readiness --check coverage --working-tree`: evidence coverage signal
+- `veritas explain <rule|file|surface>`: just-in-time guidance
+
+When a Veritas artifact is used, write a Flow Agents evidence check with `standard_refs[].standard: "veritas"` and `standard_refs[].ref` pointing at the Veritas artifact. If the artifact is outside the workflow directory, also add `external_evidence`.
+
+## Stop Conditions
+
+Stop and route to the user or plan when:
+
+- the adapter is not installed or configured and the plan requires it
+- the adapter needs a stronger sandbox mode than the plan recorded
+- the adapter reports blocking policy failures
+- the adapter output cannot be tied to changed files, acceptance criteria, or release risk
+- the native evidence artifact is missing or unreadable
+
+## Non-Goals
+
+- Do not turn adapter-specific rules into Flow Agents universal rules.
+- Do not make Veritas or any governance adapter mandatory for ordinary Flow Agents usage.
+- Do not flatten native evidence artifacts into long Markdown summaries when a stable artifact reference is available.

package/context/contracts/planning-contract.md

@@ -0,0 +1,85 @@
+# Planning Contract
+
+Planning turns a user goal into an executable implementation plan without writing production code.
+
+## Required Inputs
+
+- original user goal
+- working directory
+- relevant constraints from conversation, AGENTS.md, and active skills
+- session artifact path when part of a larger workflow
+- research findings when the work depends on unfamiliar external APIs, libraries, or current behavior
+
+## Required Output
+
+Produce a plan artifact that follows `context/contracts/artifact-contract.md`.
+
+Also create or update structured sidecars beside the Markdown artifacts:
+
+- `state.json`: phase `planning`, then `planned` status once the plan is ready.
+- `acceptance.json`: each acceptance criterion from the Definition Of Done, with `pending` status and expected evidence references when known.
+- `handoff.json`: summary and next steps when the plan is ready for execution or user approval.
+
+Use the sidecar writer when available:
+
+```bash
+npm run workflow:sidecar -- init-plan .flow-agents/<slug>/<slug>--deliver.md \
+  --source-request "<original request>" \
+  --summary "<planning summary>" \
+  --next-action "<next execution step>"
+```
+
+The plan body must include:
+
+```markdown
+## Plan
+
+<one-paragraph approach and key decisions>
+
+## Definition Of Done
+
+- **User outcome:** <what the user can understand, run, decide, or operate after delivery>
+- **Scope:** <included work and explicitly excluded work>
+- **Acceptance criteria:**
+  - [ ] AC1 `<stable-id>`: <criterion> - Evidence: <test, command, screenshot, dashboard, doc, CI, or manual check>; Source evidence: <expected file/line refs or provider permalink expectation when implementation behavior is claimed>
+- **Usefulness checks:**
+  - [ ] User-facing workflow is documented or discoverable
+  - [ ] Local and global/project scope are separated when relevant
+  - [ ] Dashboard/UI changes have visual evidence when relevant
+  - [ ] Unknown, NOT_VERIFIED, and TODO gaps are resolved or explicitly accepted
+- **Stop-short risks:** <ways this could technically pass while still not meeting the user's goal>
+- **Durable docs target:** <docs path to update after CI/merge, or "not needed" with reason>
+- **Sandbox mode:** <one of `local-read-only`, `local-edit`, `worktree`, `container`, `cloud-sandbox`, or `privileged-integration`; see `context/contracts/sandbox-policy.md`>
+
+## Baseline and AC revalidation
+
+- **Current target:** <latest target ref/SHA used for planning, or `not applicable` for direct local planning>
+- **Freshness source:** <pull-work or pickup Probe artifact ref, `revision_freshness`, and planned base ref/SHA when present>
+- **Accepted gap baseline:** <explicit accepted gap such as missing historical `planned_base_sha` with fallback baseline, or `none`; missing `planned_base_sha` is not fresh>
+- **AC revalidation against drift:** <each upstream AC id revalidated against current target, changed scope intersections, dependency/provider state, and provider history>
+- **Stale assumptions:** <assumptions invalidated by target movement, changed files, contracts, dependencies, provider state, or `none`>
+- **Route-back decision:** <`none`, route back to pickup Probe for unresolved pickup/planning gaps, or route stale shaped work back to idea-to-backlog>
+
+### Wave 1 (parallel)
+
+#### Task: <name>
+- **Files:** <create/modify/delete list>
+- **Changes:** <specific behavior changes>
+- **Acceptance:** <criterion-level evidence expected>
+- **Supports:** <AC ids and requirement ids supported by this task>
+- **Context:** <patterns, constraints, or references>
+```
+
+## Planning Rules
+
+- Explore enough codebase context to make the plan executable.
+- Reuse existing patterns before inventing new ones.
+- Separate independent tasks into parallel waves and dependent tasks into later waves.
+- Every task must have concrete acceptance criteria.
+- Preserve stable requirement and acceptance ids from upstream backlog issues when they exist; otherwise create stable ids in the plan before execution.
+- Every implementation task must map back to the acceptance criteria it supports.
+- Acceptance criteria for implementation behavior must name expected command/test evidence and expected source evidence. Source evidence means structured refs with `kind`, `url`, `file`, `line_start`, `line_end`, and `excerpt` where applicable; use immutable GitHub blob permalinks pinned to a commit SHA when provider URLs are available, and local file/line refs only as pre-publish fallback.
+- Plans should state that provider, PR, issue, closure, and final acceptance comments need an `Acceptance Evidence` table with columns `AC id`, `Status`, `Command/Test Evidence`, `Source Evidence / Permalinks`, and `Gaps`.
+- The Definition Of Done is the stop condition, not a decorative section.
+- If the goal is exploratory or uncertain, define what the user should be able to take away from the work.
+- Call out stop-short risks during planning, especially when a technical implementation could pass while the user still cannot run, inspect, understand, or act on the result.