@kontourai/flow-agents 0.1.1

package/docs/workflow-artifact-lifecycle.md

@@ -0,0 +1,141 @@
+---
+title: Workflow Artifact Lifecycle
+---
+
+# Workflow Artifact Lifecycle
+
+Flow Agents treats task artifacts as useful working memory, not permanent product documentation. Feature branches should promote durable planning, decisions, evidence pointers, and acceptance notes into normal project docs, source, schemas, or provider records instead of carrying `.flow-agents/` runtime files.
+
+The local artifact root is a current-state dashboard first and a short-lived recovery cache second. It should answer "what needs attention now?" without forcing agents to sift through old successful deliveries.
+
+## Audit Command
+
+Use the read-only cleanup audit before making any local retention decision:
+
+```bash
+npm run workflow-artifact-cleanup-audit -- --artifact-root .flow-agents
+npm run workflow-artifact-cleanup-audit -- --artifact-root .flow-agents --json
+```
+
+The command scans immediate workflow directories, skips non-workflow lanes such as `archive/`, and reports active WIP separately from cleanup candidates, terminal done records, active learning follow-ups, and invalid sidecars. This first slice is dry-run classification only: it does not delete, archive, move, or rewrite runtime artifacts by default, and it has no apply mode.
+
+Use the Current-State Semantics and Local Retention Policy sections below to interpret each bucket. In particular, learning records with `learning.status: followup_required` or any `routing[].status: open` remain active learning follow-ups until every route is completed, opened elsewhere, deferred with a trigger, accepted, or rejected.
+
+## Artifact Lanes
+
+Use one local lane under `.flow-agents/`:
+
+| Lane | Path | Commit Policy | Purpose |
+| --- | --- | --- | --- |
+| Runtime workspace | `.flow-agents/<slug>/` | Do not commit | Local session state, sidecars, delegate events, scratch evidence, and recovery notes. |
+
+The runtime workspace stays local because it may contain stale session state, machine-specific paths, or noisy intermediate artifacts. When a branch needs cross-session or cross-person traceability, promote the durable summary, decisions, evidence pointers, and acceptance notes into docs, source, schemas, or provider records instead of committing runtime artifacts.
+
+## Current-State Semantics
+
+Treat `state.json` as the active-work signal for local users and `pull-work`.
+
+| State shape | Meaning | Queue treatment |
+| --- | --- | --- |
+| `planning`, `planned`, `in_progress`, `verifying`, `blocked`, `failed`, `not_verified`, or `needs_decision` | Work still needs agent or user attention. | Active WIP or shepherding candidate. |
+| `verified` with `next_action.status: continue` | Local evidence passed, but release, final acceptance, or learning is not closed. | Active shepherding candidate. |
+| `verified` with `next_action.status: done` | Evidence passed and the next phase was completed outside the state machine or by a provider record. | Cleanup candidate; should be advanced to a terminal state during final acceptance. |
+| `accepted` with `phase: learning` and `learning.status: followup_required` | Learning was captured but at least one routed follow-up is still open or undecided. | Active learning follow-up until routed to backlog, docs, evals, skills, knowledge, or an explicit deferred trigger. |
+| `delivered`, `accepted`, or `archived` with `phase: done`, or `accepted`/`archived` with closed learning routing | Completed local workflow. | Not active WIP; retain only while useful for recovery or audit. |
+
+`verified` is not a terminal state. It means the verifier supplied evidence. Final acceptance must still record the provider change, CI/release result, docs promotion decision, and any learning route before the workflow stops being active.
+
+## Learning Closeout
+
+Learning records are a routing surface, not a permanent parking lot.
+
+Use `learning.status: followup_required` only while at least one learning route still needs action. Each route should end in one of these outcomes:
+
+- `completed`: the doc, eval, skill, backlog item, code change, or knowledge update was made.
+- `open`: a provider-backed issue, backlog artifact, or named owner now tracks the follow-up.
+- `deferred`: the follow-up has a concrete revisit trigger, such as a later milestone, repeated failure pattern, provider capability, or date.
+- `rejected`: the follow-up was considered and intentionally not pursued, with a reason in the learning record.
+
+Once every route is completed, open elsewhere, deferred with a trigger, or rejected with a reason, record `learning.status: learned` and advance the workflow out of active WIP. Do not leave local runtime state as `needs_decision` only because a durable follow-up issue exists.
+
+Terminal learning review also records correction state in `learning.json`. Before closeout, compare intended behavior to observed behavior:
+
+- Clean runs use `correction.needed: false`, brief `correction.evidence`, and closed/no-follow-up routing such as `target: "none"` with `status: "completed"`.
+- Mismatches use `correction.needed: true` with typed `correction.type`, stable `correction.recurrence_key`, intended behavior, observed behavior, gap, and a prevention route or explicit `no_change_rationale`.
+
+Correction records stay in local `learning.json` for this slice. They do not create a new sidecar, do not upload to Source/Sink storage, do not build Console/dashboard UI, and do not automatically open provider issues. Future consumers can derive correction rate, resolved corrections, repeated recurrence keys, stale unresolved corrections, and clean-run rate from the same fields.
+
+Durable learning should be promoted by target:
+
+- workflow rule changes go to `context/contracts/`, `skills/`, or workflow docs
+- regression expectations go to `evals/`
+- product or architecture decisions go to `docs/` or `docs/adr/`
+- executable work goes to GitHub issues or the configured backlog provider
+- durable user/team memory goes to the configured knowledge store
+
+## Local Retention Policy
+
+For local-only users, keep enough local state to recover recent work, but do not use `.flow-agents/<slug>/` as the long-term system of record.
+
+Recommended defaults:
+
+| Artifact class | Retain locally | Durable destination |
+| --- | --- | --- |
+| Active WIP, blockers, and unresolved decisions | Until resolved | Current `.flow-agents/<slug>/` state and handoff. |
+| Recently merged or accepted deliveries | 14-30 days, or until the next queue audit | PR body, issue comments, release records, promoted docs, or archived evidence refs. |
+| Security, migration, release, or provider-governance evidence | 30-90 days when useful for audit | Provider record, release note, durable doc, or external evidence store. |
+| Routine successful local runtime artifacts | Delete or archive after durable promotion and recovery window | Usually none beyond provider record and docs. |
+| Learning records with routed follow-ups | Until all routes are completed, opened elsewhere, deferred with trigger, or rejected | Backlog issue, docs/evals/skills change, or knowledge note. |
+
+When a future Source/Sink service is available, the same lifecycle should apply: local runtime artifacts become a cache and upload source; the service becomes the searchable history. Local-only users should still be able to run cleanup from provider records and durable docs without losing active work.
+
+## Prevention Rules
+
+To prevent historical entries from polluting current-state scans:
+
+1. After a PR is merged or a no-provider-change path is accepted, final acceptance must advance `state.json` out of `verified` unless there is a real blocker.
+2. If learning is required, route every learning item before marking the workflow inactive. Open durable issues are valid routes; they should not keep the local workflow active forever.
+3. `pull-work` should classify old `verified` records with `next_action.status: done` as cleanup candidates, not active implementation work.
+4. Queue audits should flag `needs_decision` or `followup_required` records older than the local recovery window.
+5. Cleanup should preserve links to PRs, issues, durable docs, and evidence summaries before deleting or archiving local runtime folders.
+
+## Durable Closeout Shape
+
+Durable closeout content is the handoff from working memory to project knowledge. Put it in the provider record, PR body, issue comments, release note, ADR, README section, schema docs, or runbook that owns the shipped behavior. It should record:
+
+- shipped behavior or explicit non-shipped result
+- provider change records such as PRs or issues
+- verification evidence and residual gaps
+- durable docs targets updated or intentionally skipped
+- ADRs, README sections, schema docs, runbooks, or release notes created
+- follow-up issues or learning-review records
+- confirmation that `.flow-agents/` runtime artifacts remain untracked
+
+## Completion Rule
+
+Before merge to `main`:
+
+1. Promote durable behavior, contracts, decisions, operations notes, and usage guidance into long-lived docs such as `README.md`, `docs/`, `docs/adr/`, schema docs, runbooks, changelogs, or provider records.
+2. Make sure the durable record names the promotion targets and any accepted gaps.
+3. Confirm `.flow-agents/` runtime artifacts remain untracked.
+4. Keep links to provider records, durable docs, or archived external evidence instead of relying on temporary local files.
+
+`main` must not contain tracked files under `.flow-agents/`. If runtime artifacts still seem necessary after merge, their durable content has not been promoted yet.
+
+## Promotion Targets
+
+Promote by ownership:
+
+- user-facing behavior: `README.md`, product docs, or workflow usage docs
+- architecture and policy decisions: `docs/adr/` or focused design docs
+- workflow rules and gates: `context/contracts/`, `skills/`, `agents/`, and workflow docs
+- schemas and API contracts: `schemas/` and contract docs
+- operational behavior: runbooks, release notes, or deployment docs
+- evidence and release state: PR body, provider checks, release records, or durable evidence docs
+- follow-up work: provider-backed issues or backlog artifacts
+
+Do not promote raw intermediate thinking wholesale. Promote the resulting decisions, requirements, evidence, and user-facing instructions.
+
+## Enforcement
+
+Runtime state remains ignored under `.flow-agents/`. Static package validation fails if runtime artifacts are tracked. Reviewers should reject PRs that omit durable docs, source, schema, provider, or evidence updates needed to understand shipped behavior.

package/docs/workflow-eval-strategy.md

@@ -0,0 +1,295 @@
+---
+title: Workflow Eval Strategy
+---
+
+# Workflow Eval Strategy
+
+The Builder Kit workflow system now has concrete skill contracts for `idea-to-backlog`, `pull-work`, `plan-work`, `review-work`, `deliver`, `evidence-gate`, `release-readiness`, and `learning-review`, plus shared workflow contracts in `context/contracts/`. Evals should prove both the written contracts and the agent behavior around gates, artifacts, worktrees, Goal Fit, release readiness, final acceptance docs, and learning feedback.
+
+Flow Agents evals prove coordination, install, runtime adapter behavior, and artifact discipline. They should not redefine Flow gate authority: Flow Definitions use typed `expects` entries, Surface claim gates use `kind: "surface.claim"`, and Flow project config owns trusted producer mappings plus gate overrides.
+
+## Goals
+
+Prove that workflow skills are operational, not just descriptive:
+
+- Agents activate the right workflow for the right user intent.
+- Upstream shaping does not collapse into implementation.
+- Provider-backed work items are treated as executable backlog, not the whole reasoning store; GitHub issues are the first adapter example.
+- Provider-neutral work item, board, change, check, and evidence terms remain the core vocabulary; GitHub stays an adapter/example.
+- Work selection considers readiness, WIP, blockers, Probe needs, and worktree isolation.
+- Review is report-only critique and records findings separately from verification evidence.
+- Evidence review is report-only and maps claims to falsifiable proof.
+- Goal Fit catches task-complete-but-user-incomplete delivery before final response.
+- Release readiness, final acceptance docs, and learning review are covered before work is treated as done.
+- Failures produce actionable feedback into skills, evals, tests, backlog, or knowledge.
+
+## Eval Layers
+
+### 1. Static Contract Evals
+
+Run on every static pass.
+
+File: `evals/static/test_workflow_skills.sh`
+
+These check that skill contracts preserve non-negotiable guardrails:
+
+- `idea-to-backlog` forbids production implementation and keeps upstream work separate from `plan-work`, `execute-plan`, `review-work`, and `verify-work`.
+- `pull-work` forbids implementation, enforces WIP awareness, records worktree decisions, returns vague work to shaping, and hands off to `plan-work`.
+- `plan-work` requires `Definition Of Done`, stop-short risks, and durable docs target.
+- `deliver` requires `Goal Fit Gate` and `Final Acceptance` before local delivery is treated as complete.
+- workflow skills and tool agents reference shared `context/contracts/` files instead of redefining artifact, planning, execution, review, verification, and delivery protocols independently.
+- `review-work` separates critique from verification, delegates to `tool-code-reviewer`, conditionally delegates to `tool-security-reviewer`, and records findings in `critique.json`.
+- `evidence-gate` is report-only, treats `NOT_VERIFIED` as first-class, includes scope/integrity checks, evidence tiers, and CI health, and remains separate from release readiness.
+- `publish-change` is required between clean evidence and release readiness: verified diff committed, branch pushed, provider change opened or updated, and provider checks linked.
+- `publish-change` records provider-neutral `PublishChangeResult` evidence: work item refs, board refs, change refs, closing-reference recognition, provider checks, and evidence refs.
+- missing provider checks are risk-based: docs-only changes may pass with explicit skip, while runtime/schema/package/hook/security changes become `NOT_VERIFIED` or release `HOLD` without CI or equivalent provider evidence.
+- `release-readiness` separates merge/release/deploy gates, rollback, observability, ownership, final acceptance docs, and post-deploy verification planning.
+- final terminal delivery reconciles temporary verifier-local sidecar mismatch notes against authoritative final sidecars and orchestrator evidence.
+- `learning-review` records observed facts, decisions, docs promotion state, gaps, follow-ups, knowledge updates, and avoids automatic policy mutation. Terminal learning evals must cover intended-vs-observed correction decisions: clean runs with `correction.needed: false` and no open route, and mismatches with `correction.needed: true`, typed correction type, stable recurrence key, gap, and prevention route or no-change rationale.
+
+Static evals prove documented contracts did not drift. They do not prove the agent follows them in conversation.
+
+Activation-only behavioral evals may assert no write tools when the goal is trigger and boundary testing. Artifact-quality evals must allow controlled writes to `.flow-agents/<slug>/*.md` and inspect the resulting artifact contracts.
+
+### 2. Behavioral Activation Evals
+
+Run when evaluating workflow behavior for Codex/Kiro changes.
+
+File: `evals/cases/dev/promptfooconfig.yaml`
+
+Core cases:
+
+- `idea-to-backlog`: user asks to turn an idea into backlog but not code.
+- `pull-work`: user asks to pick the next provider-backed work item without implementing.
+- `evidence-gate`: user asks whether locally verified work is trustworthy enough to merge.
+- Review work: user asks for quality/security/architecture critique after implementation.
+- Release readiness: user asks whether a published change is ready to merge, release, deploy, hold, or roll back after evidence is clean.
+- Learning review: user asks what should be captured after failures or prototype work.
+
+These should verify:
+
+- correct skill activation
+- no premature implementation
+- correct phase boundaries
+- durable artifact intent
+- appropriate use of `gh` / CLI where relevant
+- explicit stop at gates
+- clear `PASS`, `FAIL`, or `NOT_VERIFIED` outcomes where evidence is being assessed
+- contract persistence after long, noisy, or stale context
+
+### 3. Artifact Quality Evals
+
+Inspect generated `.flow-agents/<slug>/*.md` files and provider-backed work item drafts for required structure.
+
+The local artifact-quality gate is:
+
+```bash
+bash evals/integration/test_workflow_artifacts.sh
+```
+
+It exercises a realistic plan -> review -> delivery artifact chain and negative fixtures for missing Goal Fit, green-build-only delivery, and hidden `NOT_VERIFIED`.
+
+Candidate assertions:
+
+- `idea-to-backlog` artifact includes source ideas, current phase, triage decision, shaped work brief, readable story/outcome, stable `R*` requirement ids, stable `AC*` acceptance ids, priority rationale, milestone/delivery outcome, backlog gate, and work item links.
+- `pull-work` artifact includes selected work item, readiness classification, WIP notes, blockers, Probe/design notes when needed, worktree decision, allowed scope, done criteria, and `plan-work` handoff.
+- `pull-work` / pickup Probe artifacts include planned base ref/SHA when available, current target SHA, drift classification, and alignment routing for material scope, dependency, contract, or conflict drift.
+- `plan-work` / `deliver` artifacts include Definition Of Done, requirement-to-acceptance trace, task-to-acceptance mapping, acceptance evidence expectations, stop-short risks, Goal Fit Gate, Final Acceptance, and durable docs target.
+- `review-work` artifacts and `critique.json` include reviewer ids, verdicts, severity-tagged findings, artifact refs, and resolution state.
+- `evidence-gate` artifact includes acceptance criteria map, evidence manifest, CI summary, scope/integrity report, `PASS` / `FAIL` / `NOT_VERIFIED`, and next step.
+- `publish-change` artifact includes provider, work item refs, board refs, change ref, closing-reference check, provider checks, evidence refs, and next action.
+- `release-readiness` artifact includes release scope, evidence reference, risk review, operational plan, rollback plan, observability plan, final acceptance docs, post-deploy checks, and decision.
+- `learning-review` artifact includes outcomes, evidence, decisions, docs promotion state, gaps, follow-ups, knowledge updates, and verdict.
+- Work item drafts include story/outcome, problem, scope, non-goals, stable `R*` requirement ids, stable `AC*` acceptance ids, source artifact links, priority rationale, milestone/delivery outcome, dependencies, and verification expectation.
+
+### 4. Adversarial Workflow Evals
+
+These cases check that the gates resist pressure and ambiguity:
+
+- User asks to "just start coding" during `idea-to-backlog`; agent should hold the gate or require explicit continuation into delivery.
+- Work item is vague; `pull-work` should return it to shaping instead of planning execution.
+- Work item was planned against an older main SHA and relevant contracts changed; pickup Probe should classify `contract_drift` and route to alignment before planning.
+- WIP is congested in review/verification; `pull-work` should prefer finishing active work before starting new implementation.
+- Verification passed locally but CI is missing; `evidence-gate` should return `NOT_VERIFIED` or degraded confidence depending on risk.
+- Docs-only change with missing provider checks and explicit skip rationale may pass when local docs evidence satisfies the risk.
+- Runtime/schema/package/hook/security change with missing provider checks should return `NOT_VERIFIED` in evidence-gate or `HOLD` in release-readiness unless equivalent evidence is recorded.
+- Tests were deleted or weakened; `evidence-gate` should flag integrity risk.
+- CI passes only after unexplained reruns; `evidence-gate` should degrade confidence.
+- Prototype code exists; workflow should require learning review before production promotion.
+- Release notes, rollback, or observability are missing for production-impacting work; `release-readiness` should return `HOLD`, optionally routing missing evidence back to `evidence-gate`.
+- Agent tries to stop with an active `.flow-agents/<slug>/` delivery artifact; `stop-goal-fit` should warn and strict mode should block.
+- CI/merge acceptance happens but docs are not promoted; release readiness or learning review should record a docs follow-up or explain why durable docs are not needed.
+- Temporary verifier-local sidecar mismatch notes remain in the history; terminal artifacts must show final sidecar reconciliation before reporting clean delivery.
+- Deep-context delivery contains stale shortcuts; agent should ignore stale context and still preserve Definition Of Done, explicit `NOT_VERIFIED`, Goal Fit, and Final Acceptance.
+
+### 5. End-To-End Loop Evals
+
+Run selectively for workflow release candidates.
+
+```text
+idea-to-backlog -> pull-work -> design-probe -> plan-work -> execute-plan -> review-work -> verify-work -> goal-fit -> evidence-gate -> publish-change -> release-readiness -> final-acceptance-docs -> learning-review
+```
+
+The end-to-end eval should assert that:
+
+- each phase consumes the prior artifact instead of reinterpreting the goal from scratch
+- worktree decisions are recorded before implementation planning
+- acceptance criteria survive through planning, implementation, review, verification, and evidence review
+- requirement and acceptance ids survive from backlog work item through planning, implementation, review, verification, and evidence review
+- Goal Fit checks the original user outcome before delivery
+- shared contracts remain the source of truth even after context gets long
+- failed or missing evidence loops back to the right phase
+- release readiness, docs promotion, and learning feedback are produced before final completion
+
+This layer is intentionally expensive and should not run on every edit.
+
+The deterministic local smoke layer is cheaper than a full LLM end-to-end eval. It validates the persisted artifact chain with `npm run workflow:validate-artifacts --` and runs as part of `bash evals/run.sh integration`. Full LLM end-to-end evals should still be run for release candidates and model/profile changes.
+
+The default Flow Agents CI baseline is the provider-check lane for ordinary pull requests and `main` pushes:
+
+```bash
+bash evals/ci/run-baseline.sh
+```
+
+It runs deterministic credential-free checks: source tree validation, context-map drift, static evals, workflow artifact checks, publish-change helper coverage, sidecar writer coverage, Goal Fit and workflow steering hooks, hook-influence contract checks, Flow Kit repository checks, runtime adapter activation, and bundle install smoke tests. It writes logs plus Markdown provider evidence summaries under `evals/results/ci-baseline/`. GitHub Actions uploads separate per-lane artifacts: `flow-agents-ci-source-and-static`, `flow-agents-ci-workflow-contracts`, and `flow-agents-ci-runtime-and-kit`.
+
+Default CI intentionally skips live GitHub mutation checks, LLM behavioral/acceptance evals, and Veritas/governance provider evidence unless a maintainer opts into those lanes. The CI summary must name those skips so evidence-gate and release-readiness can classify them as accepted skips or `NOT_VERIFIED` according to change risk.
+
+Surface trust artifact attachment is covered by deterministic schema, runtime, and report checks, not by live provider authority. The targeted local command is:
+
+```bash
+bash evals/integration/test_workflow_sidecar_writer.sh
+```
+
+That eval exercises Builder Kit `surface.claim` evidence using provider-neutral TrustReport / Trust Snapshot fixtures for accepted, rejected, stale, missing-authority, integrity-mismatch, provider-absent, and artifact-absent cases. It proves Flow Agents can record compact Surface claim evidence in `evidence.json` and report pass, fail, or `NOT_VERIFIED` gaps without requiring provider-specific fields.
+
+This coverage does not redefine Flow gate authority. Flow Definitions continue to express expectations, Flow project config owns trusted producer mappings and gate overrides, and Flow gate authority remains outside the local report writer. Runtime/provider gaps should be recorded as `NOT_VERIFIED` when a configured Surface claim path cannot be checked; ordinary Builder Kit workflows remain valid when no trust provider or trust artifact is configured.
+
+The same sidecar writer eval covers runtime transition enforcement without making Flow Agents the owner of transition semantics. It verifies that `record-evidence`, `advance-state`, `record-release`, `record-learning`, and `dogfood-pass` use the sidecar transition guard for `state.json` and `handoff.json` writes; verifier/evidence helpers cannot jump directly to terminal workflow state while release or learning gates remain; rejected transitions append `transition-diagnostics.jsonl` without mutating authoritative state or handoff sidecars; Builder Kit `builder.build` route-backs require declared reasons and respect deterministic max-attempt accounting; and legacy direct primitive workflows remain compatible when no Builder Kit Flow Definition context is present.
+
+Learning sidecar evals also protect the correction contract. Positive fixtures validate a no-correction clean run and a correction-needed mismatch. Negative fixtures reject correction-needed records that omit `correction.recurrence_key` or omit both prevention route and `no_change_rationale`. These fields are local `learning.json` data for future metrics such as correction rate, resolved corrections, repeated recurrence keys, stale unresolved corrections, and clean-run rate; the evals must not require Console/dashboard UI, Source/Sink storage, provider issue automation, or a reconciliation CLI.
+
+## Feedback Loop
+
+Every failed behavioral or artifact eval should be classified:
+
+- bad skill trigger description
+- unclear workflow instructions
+- missing artifact schema
+- missing tool/subagent support
+- bad eval prompt
+- bad assertion/rubric
+- model limitation
+- real product ambiguity
+- workflow design drift
+
+Then update one of:
+
+- skill frontmatter
+- skill body
+- static contract eval
+- behavioral prompt/rubric
+- artifact schema
+- source workflow document
+- backlog issue for missing tool support
+- knowledge note for durable learning
+
+Do not fix eval failures by weakening the goal. If the goal is wrong, update the design artifact first, then the eval.
+
+Post-run usage feedback should be recorded through the normalized feedback-loop schema described in https://github.com/kontourai/flow-agents/blob/main/docs/agent-usage-feedback-loop.md. Behavioral evals that compare runtimes, repositories, profiles, prompts, judges, or skills should record outcome rows with stable `runtime`, `repo`, `profile_id`, `prompt_id`, `prompt_variant`, `skill_ids`, and `skill_variant` identifiers. This lets reports compare success rate, partial/failure/not-verified rate, duration, tool invocations, delegations, permission requests, rework rate, quality score, and human minutes saved across setups.
+
+Quality outcomes are manual or eval-recorded evidence. Telemetry can count runtime behavior, but it should not automatically infer `quality_score`, `result`, rework, or saved time.
+
+Example cross-repo comparison:
+
+```bash
+npm run usage-feedback -- report \
+  --telemetry-dir ../repo-a/.telemetry \
+  --telemetry-dir ../repo-b/.telemetry \
+  --group-by repo
+```
+
+Example runtime and judge comparison:
+
+```bash
+bash evals/run.sh llm dev --runtime claude --judge-runtime codex --suite regression
+bash evals/run.sh llm dev --runtime claude --judge-runtime claude --suite regression
+bash evals/run.sh llm dev --runtime codex --judge-runtime claude --suite regression
+```
+
+Claude Code acceptance is cheap by default and should stay that way for routine checks. Use explicit opt-in flags only when spending Claude usage is intentional:
+
+```bash
+FLOW_AGENTS_ACCEPTANCE_CLAUDE_LLM=1 bash evals/run.sh acceptance claude
+FLOW_AGENTS_ACCEPTANCE_CLAUDE_LLM=1 FLOW_AGENTS_ACCEPTANCE_REQUIRE_CLAUDE_TELEMETRY=1 bash evals/run.sh acceptance claude
+```
+
+Runtime hook behavior is intentionally tested at different levels. Keep these lanes separate when citing evidence for the Builder Kit `plan -> execute -> review -> verify` loop:
+
+- Adapter evals prove runtime-specific adapters can transform hook output into the protocol shape expected by Codex, Claude Code, or Kiro. They prove delivery shape, not live model influence.
+- Installed-command evals execute Claude Code, Codex, and Kiro hook commands from installed bundle paths against the same workflow state fixture. They prove the exported bundle can run and emit guidance from installed commands, not that a live model used that guidance.
+- Claude Code live acceptance proves prompt-submit workflow-steering context reaches the model and changes the final response.
+- Kiro live acceptance proves strict Goal Fit Stop gates surface as hook failures in the CLI. Kiro does not currently inject prompt-submit workflow-steering output back into model context in the live harness.
+- Codex `exec` live acceptance proves exported agents and skill routing from a full installed bundle. Codex hook adapters and installed-command evals prove hook protocol output, but the current `codex exec` harness does not observe project hook guidance as model context. Record Codex live hook influence as `NOT_VERIFIED` / `documented-runtime-gap` unless a future live harness demonstrates that project hook guidance reached model context and changed the response.
+
+Hook-influence behavioral cases live in `evals/fixtures/hook-influence/cases.json` and are validated by `npm run validate:hook-influence --`. These cases make the expected behavior explicit: what hook guidance must contain, what the agent must do after seeing it, and which evidence tier proves it. For `kontourai/flow-agents#62`, the required cases cover missing pickup Probe before planning, review-before-verify after execution, verification failure route-back with preserved FAIL evidence, and Goal Fit stop behavior. Review remains report-only critique recorded in `critique.json`; verification remains evidence recorded in `evidence.json`. Open critique findings or verification failure route back through execution before the loop can be delivered.
+
+Evidence tiers:
+
+| Tier | Meaning |
+| --- | --- |
+| `adapter` | Runtime adapter transforms hook output into the target runtime protocol; proves protocol delivery shape, not live model influence. |
+| `installed-command` | The exported hook command runs from installed Codex, Claude Code, and Kiro bundle paths and emits the expected guidance. |
+| `live-acceptance` | A live runtime session shows the agent responding differently because hook guidance reached the model or runtime stop gate. |
+| `documented-runtime-gap` | The runtime is covered by adapter or installed-command evidence, but a live harness cannot yet prove model-context influence. |
+| `design-target` | Expected behavior is captured as an executable fixture contract, but implementation or live harness evidence is intentionally deferred. |
+
+Use the Flow Agents CI baseline as the provider evidence lane for this deterministic coverage:
+
+```bash
+bash evals/ci/run-baseline.sh
+```
+
+For GitHub provider evidence, cite the relevant uploaded lane artifact/check: `flow-agents-ci-source-and-static`, `flow-agents-ci-workflow-contracts`, or `flow-agents-ci-runtime-and-kit`. Those artifacts are provider evidence for deterministic local contracts and installed-command behavior. They intentionally skip live LLM influence checks unless separately configured, so they must not be cited as proof that Codex live model context was changed by project hooks.
+
+Run the non-LLM hook-influence contract with:
+
+```bash
+bash evals/integration/test_hook_influence_cases.sh
+```
+
+Example Codex profile comparison:
+
+```bash
+npm run usage-feedback -- report \
+  --telemetry-dir .telemetry/codex-default \
+  --telemetry-dir .telemetry/codex-bedrock \
+  --runtime codex \
+  --group-by profile_id
+```
+
+Telemetry import is runtime-neutral. Use `import-telemetry --runtime <runtime>` for Kiro, Codex, Claude Code, or future runtimes that emit the shared event envelope; `import-codex` remains a compatibility alias for Codex full logs.
+
+```bash
+npm run usage-feedback -- import-telemetry \
+  --runtime claude-code \
+  --input-telemetry-dir /path/to/project/.telemetry \
+  --telemetry-dir .telemetry/claude
+```
+
+## Release Criteria
+
+Workflow changes are ready to release when:
+
+- static contract evals pass
+- relevant behavioral cases pass or have documented runtime blockers
+- hook-influence behavioral cases validate and any runtime gaps are explicitly marked
+- artifact quality checks cover changed artifact contracts
+- adversarial cases exist for any newly added gate behavior
+- end-to-end evals pass for workflow release candidates
+- `bash evals/integration/test_workflow_artifacts.sh` passes for shared-contract artifact changes
+- generated bundle docs and skill maps agree on owners, gates, artifacts, and deferred primitives
+
+## Runtime Notes
+
+Behavioral results must record which runtime is being evaluated: Codex or Kiro. A pass in one runtime does not automatically prove the other unless the prompt path, tools, and skill-loading behavior are equivalent.

package/docs/workflow-shared-contracts.md

@@ -0,0 +1,51 @@
+---
+title: Shared Workflow Contracts
+---
+
+# Shared Workflow Contracts
+
+The workflow system now separates durable process contracts from role-specific instructions.
+
+## Source Of Truth
+
+Shared contracts live in `context/contracts/`:
+
+- `artifact-contract.md`
+- `planning-contract.md`
+- `execution-contract.md`
+- `review-contract.md`
+- `verification-contract.md`
+- `delivery-contract.md`
+
+These files define the stable rules for artifacts, planning, execution, review, verification, delivery loops, Goal Fit, and final acceptance.
+
+The durable resource shape for selected scope, workflow runs, run plans, status conditions, provider-backed Work Items, and sidecar compatibility direction is documented in the Kontour Resource Contract:
+https://github.com/kontourai/flow-agents/blob/main/docs/kontour-resource-contract.md
+
+That reference is docs-only guidance for new resource-shaped contracts and does not migrate current sidecars or require Kubernetes at runtime.
+
+The lifecycle for in-progress and completed workflow artifacts is documented in the Workflow Artifact Lifecycle:
+https://github.com/kontourai/flow-agents/blob/main/docs/workflow-artifact-lifecycle.md
+
+Runtime workflow artifacts under `.flow-agents/` remain local and ignored. Completed work must promote durable behavior, decisions, contracts, and evidence into long-lived docs, source, schemas, or provider records before merge to `main`.
+
+## How Skills And Agents Use Them
+
+Skills should explain when to run a workflow and how to orchestrate it. They should reference the relevant contract instead of restating the full protocol.
+
+Agents should explain their role-specific behavior. They should follow the relevant contract instead of carrying a second copy of the artifact or verdict format.
+
+This keeps the system portable across Codex, Kiro, Claude Code, and future distributions. Exporters can adapt tool names, paths, and hook syntax, but the workflow rules stay canonical.
+
+## Eval Direction
+
+Static evals check that the contract files exist, that workflow skills and tool agents reference them, and that deep-context behavioral eval cases exist.
+
+Behavioral evals should test whether the agent still preserves the contract after a long prompt or long session history:
+
+- planning still includes Definition Of Done, stop-short risks, and evidence-bearing acceptance criteria
+- execution still updates artifacts between waves
+- review still records report-only critique in `critique.json`
+- verification still reports PASS, FAIL, or NOT_VERIFIED with evidence per criterion
+- delivery still completes Goal Fit before final response
+- final acceptance still promotes durable docs after CI or merge