@kontourai/flow-agents 0.1.1

package/context/contracts/review-contract.md

@@ -0,0 +1,104 @@
+# Review Contract
+
+Review is report-only critique. It asks whether the changed code is maintainable, secure, consistent with project standards, and structurally sound before verification proves behavior.
+
+## Purpose
+
+Review and verification are separate gates:
+
+- Review answers: should this implementation be changed before we trust it?
+- Verification answers: what evidence proves the accepted behavior works?
+
+Keep review findings in the configured critique artifact/sink; in the local sidecar workflow this is materialized as `critique.json`. Keep behavior evidence in `evidence.json`.
+
+Review is not a canonical `state.phase` value. Machine-readable workflow state must use the canonical lifecycle phase vocabulary from the artifact contract, while review-work records its verdicts and findings through the critique artifact/sink.
+
+## Required Inputs
+
+- session artifact path when available
+- plan artifact path or implementation summary
+- modified files
+- relevant project standards, including `context/code-review-standards.md` when present
+- risk triggers such as auth, user input, database queries, filesystem operations, API endpoints, cryptography, payments, migrations, CI, deployment, or public contracts
+
+## Review Lanes And Trigger Rules
+
+Run each required lane as report-only critique. A lane is required when modified
+files, the plan, or the implementation behavior match its triggers. When trigger
+detection is uncertain for a substantial change, run the relevant lane or record
+that lane as `not_verified` with the reason.
+
+| Lane | Triggers | Expected reviewer or delegate |
+| --- | --- | --- |
+| Code | Source code, tests, scripts, generated-code inputs, public contracts, or implementation logic changed. | `tool-code-reviewer` |
+| Security | Authentication, authorization, user input, query params, headers, templates, serialization, database queries, filesystem paths, uploads, downloads, archives, generated files, API endpoints, webhooks, external API calls, network operations, cryptography, tokens, secrets, payments, billing, CI, deployment, or feature flags changed. | `tool-security-reviewer` |
+| Dependency | Package manifests, dependency manifests, lockfiles, dependency tooling, package manager config, container base-image dependency declarations, or dependency update policy changed. Examples include `package.json`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `requirements.txt`, `pyproject.toml`, `poetry.lock`, `Pipfile.lock`, `Cargo.toml`, `Cargo.lock`, `go.mod`, `go.sum`, `pom.xml`, `build.gradle`, `Gemfile.lock`, `composer.lock`, and NuGet lock files. | `tool-dependencies-updater` or configured repo dependency reviewer |
+| Architecture/standards | Module boundaries, ownership boundaries, shared abstractions, schemas, API compatibility, data flow, migrations, platform conventions, documented decisions, project standards, or cross-cutting behavior changed. | `tool-code-reviewer` plus configured architecture/domain reviewer when present |
+| IaC/policy | Infrastructure as code, policy as code, cloud/deployment config, Terraform, OpenTofu, CloudFormation, Kubernetes manifests, Helm charts, Dockerfiles, Compose files, GitHub Actions, CI/CD permissions, IAM, OPA/Rego, Sentinel, or environment provisioning changed. | `tool-security-reviewer`, configured IaC/policy reviewer, or repo-local read-only scanner |
+
+IaC/policy scanner guidance is vendor-neutral. Acceptable scanner classes include
+Checkov, tfsec, Trivy, Semgrep, and project-configured policy scanners, but no
+single vendor is required by this contract. Reviewers may reference native
+scanner output or SARIF when available, but missing scanner tooling must be
+recorded as `not_verified`; do not install new scanners or silently pass the
+lane during review.
+
+## Reviewers
+
+Run the relevant report-only reviewers:
+
+- `tool-code-reviewer` for code quality, maintainability, correctness, project standards, and architecture/standards fit
+- `tool-security-reviewer` when security or IaC/policy triggers are present
+- `tool-dependencies-updater` when dependency manifests, package manifests, package manager configuration, or lockfiles change
+- an architecture, domain, IaC/policy, dependency, or standards reviewer when configured by the project or requested by the user
+
+All reviewers are read-only reporters. They may inspect files, run read-only analysis commands, and write review artifacts under the workflow artifact directory. They must not modify source files, apply patches, or run autofixes.
+
+## Review Scope
+
+Attempt relevant perspectives and record findings:
+
+- Code quality: readability, naming, function/file size, error handling, duplication, maintainability
+- Correctness risks: edge cases, unintended behavior, unsafe assumptions, missing tests
+- Standards fit: project conventions, local architecture, public contracts, documented decisions
+- Security: secrets, injection, XSS, path traversal, auth/authz, unsafe external calls, vulnerable dependencies
+- Architecture: ownership boundaries, coupling, data flow, schema or API compatibility, migration risk
+
+If a perspective is required but cannot be reviewed, record it as `not_verified` with the reason.
+
+## Verdicts
+
+- `pass`: no open findings that block delivery
+- `comment`: non-blocking findings or suggestions only
+- `fail`: at least one open critical/high finding, or a medium finding that requires code changes before delivery
+- `not_verified`: required review evidence could not be collected
+
+## Structured Critique Sidecar
+
+When review runs as part of a workflow, write or update the configured critique artifact/sink. For the current local sidecar materialization, write or update `critique.json` beside the workflow artifacts using `schemas/workflow-critique.schema.json`.
+
+Prefer the sidecar writer when available:
+
+```bash
+npm run workflow:sidecar -- record-critique .flow-agents/<slug> \
+  --id code-review \
+  --reviewer tool-code-reviewer \
+  --verdict pass \
+  --summary "Code review passed."
+```
+
+For Markdown reviewer reports, import them when possible:
+
+```bash
+npm run workflow:sidecar -- import-critique .flow-agents/<slug> \
+  .flow-agents/<slug>/<slug>--code-review.md \
+  --reviewer tool-code-reviewer
+```
+
+## Gate Rules
+
+- Critical or high findings block delivery until fixed, accepted by the user, deferred with explicit rationale, or marked false positive.
+- Security critical/high findings block delivery unless the user explicitly accepts the risk.
+- Medium findings that require code changes route through an execution fix pass.
+- Any code change after review requires another clean review and verification pass.
+- Do not mark critique `pass` while open findings remain.

package/context/contracts/sandbox-policy.md

@@ -0,0 +1,52 @@
+# Sandbox Policy Contract
+
+Workflow artifacts must name the execution boundary required for the work. The sandbox mode is a planning and delegation contract, not a substitute for the runtime permission model.
+
+## Canonical Modes
+
+Use exactly one of these values when recording `sandbox_mode`:
+
+- `local-read-only`: inspect files, configs, logs, docs, and command output without mutating files or external systems.
+- `local-edit`: edit files in the active workspace and run local validation with low conflict and rollback risk.
+- `worktree`: use an isolated branch/worktree for parallel work, broad refactors, generated artifacts, or work likely to outlive the current session.
+- `container`: use a disposable local environment for untrusted dependencies, destructive tools, or build steps that may pollute host state.
+- `cloud-sandbox`: use scoped cloud accounts, projects, stacks, or preview environments with explicit owner, budget risk, and teardown.
+- `privileged-integration`: access sensitive data, mutate external systems, send messages, deploy, approve releases, or use elevated local permissions.
+
+## Required Artifact Fields
+
+Plans, execution summaries, and handoffs should record:
+
+- `sandbox_mode`
+- `scope`
+- `owner`
+- `approval`
+- `rollback`
+- `evidence`
+
+The Markdown form may use a Definition Of Done bullet. Structured sidecars should use the same vocabulary when a schema supports the field.
+
+## Selection Rules
+
+- Start discovery, planning, and code review at `local-read-only`.
+- Use `local-edit` only when the active workspace is the intended edit surface.
+- Prefer `worktree` for parallel agents, overlapping ownership, broad shared-file edits, or long-running work.
+- Prefer `container` for risky dependency installation, generated-code experiments, or destructive commands.
+- Use `cloud-sandbox` for cloud experimentation before touching shared or production-like resources.
+- Use `privileged-integration` only with explicit approval, target, expected effect, rollback, and post-action verification.
+
+## Escalation Rules
+
+- Upgrade the mode when the work becomes riskier than planned.
+- Stop for approval when the required mode is `privileged-integration` or when cloud, destructive, or externally mutating behavior was not already authorized.
+- Downgrade only when the artifact records why the stronger boundary is no longer required.
+- Do not hide sandbox blockers in a final summary. Record the blocker and route back to planning or user approval.
+
+## Evidence Expectations
+
+- `local-read-only`: sources read and checks attempted.
+- `local-edit`: modified files and validation commands.
+- `worktree`: worktree path, branch, owner, merge plan, and cleanup plan.
+- `container`: image/context, mounted paths, command evidence, and copied outputs.
+- `cloud-sandbox`: account/project, region, permissions, cost risk, teardown evidence.
+- `privileged-integration`: approval reason, target, action result, rollback status, and post-action verification.

package/context/contracts/verification-contract.md

@@ -0,0 +1,134 @@
+# Verification Contract
+
+Verification is report-only. It proves whether the implementation satisfies the plan, the Definition Of Done, and the original user outcome.
+
+## Required Inputs
+
+- session artifact path when available
+- plan artifact path or acceptance criteria
+- Definition Of Done and stop-short risks
+- modified files
+- build, test, lint, browser, or runtime commands from the plan, AGENTS.md, or project conventions
+
+## Report-Only Rule
+
+Verifiers and reviewers do not modify source code. They may run commands, inspect files, take screenshots, and write verification artifacts. They must not apply fixes, formatting, lint autofixes, or patches.
+
+## Verification Phases
+
+Attempt relevant phases and record evidence:
+
+- Build: compile or bundle the project
+- Types: run detected static type checks
+- Lint: run detected lint or quality checks
+- Tests: run affected or full tests, with coverage when available
+- Security: scan for secrets, debug artifacts, and dependency issues when relevant
+- Diff review: inspect changed files against acceptance criteria
+- Browser or visual checks: use screenshots, accessibility checks, and interaction tests for UI changes
+- Provider checks: collect CI, status, review, mergeability, deployment, policy, or equivalent ChangeProvider evidence after publish-change when release confidence depends on the provider
+
+If a tool or environment is unavailable, mark that phase `NOT_VERIFIED` with the reason. Do not skip silently.
+
+Provider-check gaps are risk-based:
+
+- Docs-only changes may use `SKIP` / `skip` for missing provider checks only when the report names the skipped check, explains why local docs evidence is enough, and the repository does not require the missing check.
+- Runtime, schema, package, hook, security, migration, release, infrastructure, or deployment changes require provider check evidence or equivalent proof. If that proof is missing, mark the provider check and any affected acceptance/release item `NOT_VERIFIED`; release-readiness must hold rather than treating the gap as pass.
+- Provider API failure, unknown mergeability, missing required review, or absent CI is not a clean pass for risky changes.
+
+## Verdicts
+
+- `PASS`: all required criteria are satisfied with evidence, and no required phase failed or remains unaccepted.
+- `FAIL`: at least one acceptance criterion, required check, or Goal Fit item failed.
+- `NOT_VERIFIED`: required evidence could not be collected.
+- `PARTIAL`: only for legacy reports where some criteria pass and some fail or remain unverified; route it like a non-pass.
+
+## Required Report Shape
+
+```markdown
+## Verification Report
+
+Build:     [PASS/FAIL/NOT_VERIFIED/SKIP] <command, exit code, or reason>
+Types:     [PASS/FAIL/NOT_VERIFIED/SKIP] <command, result, or reason>
+Lint:      [PASS/FAIL/NOT_VERIFIED/SKIP] <command, result, or reason>
+Tests:     [PASS/FAIL/NOT_VERIFIED/SKIP] <command, result, coverage, or reason>
+Security:  [PASS/FAIL/NOT_VERIFIED/SKIP] <findings or reason>
+Provider:  [PASS/FAIL/NOT_VERIFIED/SKIP] <provider checks, change ref, or risk-based skip reason>
+Diff:      [PASS/FAIL/NOT_VERIFIED] <changed files reviewed>
+
+### Acceptance Criteria
+- [PASS/FAIL/NOT_VERIFIED] <criterion> - <evidence or gap>
+
+### Goal Fit
+- [PASS/FAIL/NOT_VERIFIED] User outcome - <evidence or gap>
+- [PASS/FAIL/NOT_VERIFIED] User-facing workflow - <docs, commands, UI, screenshots, or gap>
+- [PASS/FAIL/NOT_VERIFIED] Durable docs target - <updated, deferred, not needed, or gap>
+- [PASS/FAIL/NOT_VERIFIED] Stop-short risks - <resolved, accepted, or still open>
+
+### Verdict: PASS | PARTIAL | FAIL | NOT_VERIFIED
+<summary>
+```
+
+## Structured Evidence Sidecar
+
+When verification runs as part of a workflow, write or update `evidence.json` beside the workflow artifacts using `schemas/workflow-evidence.schema.json`.
+
+Use the sidecar writer when available:
+
+```bash
+npm run workflow:sidecar -- record-evidence .flow-agents/<slug> \
+  --verdict pass \
+  --check-json '{"id":"tests","kind":"test","status":"pass","summary":"Relevant checks passed."}'
+```
+
+Map phases to check kinds:
+
+- Build -> `build`
+- Types -> `types`
+- Lint -> `lint`
+- Tests -> `test`
+- Security -> `security`
+- Diff -> `diff`
+- Browser or visual checks -> `browser`
+- Runtime checks -> `runtime`
+- External policy or governance checks -> `policy` or `external`
+- Provider checks from publish-change or release surfaces -> `external`
+
+Use lowercase statuses: `pass`, `fail`, `not_verified`, or `skip`. Set the top-level `verdict` to `pass`, `partial`, `fail`, or `not_verified`. Include `not_verified_gaps` for any missing required evidence.
+
+Modified files are part of verification scope. If changed-file scope is unavailable, mark diff/scope integrity `NOT_VERIFIED` instead of inferring from memory. Optional governance providers such as Veritas may use the same modified-file scope as input or as an integrity reference, but their native reports should remain external evidence referenced from `evidence.json`.
+
+When evidence has a native standard artifact, include `standard_refs` on the relevant check instead of flattening that artifact into prose:
+
+- SARIF for static analysis, code review, security, and policy findings
+- OpenTelemetry logs or traces for runtime, tool, model, workflow, and production-like event evidence
+- JUnit or TAP for test runner output
+- Veritas for optional policy/proof-lane evidence owned by Veritas
+
+Use `external_evidence` for evidence stored outside the artifact directory, with `system`, `ref`, optional `summary`, and optional `standard`.
+
+External governance evidence follows `context/contracts/governance-adapter-contract.md`. Veritas is optional: when present, reference its native artifact with `standard: "veritas"`; when absent, do not invent a pass.
+
+Published change evidence follows `context/contracts/work-item-contract.md`. Record ChangeProvider evidence as provider-neutral refs: `work_item_ref`, `board_ref`, `change_ref`, provider checks, closing-reference checks, and evidence refs. GitHub pull requests are the first adapter example, not required core terminology.
+
+Update `acceptance.json` when acceptance criteria move from `pending` to `pass`, `fail`, `not_verified`, or `accepted_gap`.
+
+## Final-State Reconciliation
+
+Verifier-local mismatch notes are pre-orchestration observations. They are useful for catching stale Markdown or sidecars, but they are not the terminal source of truth after the orchestrator updates final sidecars.
+
+Before a clean terminal verdict:
+
+- read the final `acceptance.json`, `evidence.json`, and `release.json` when present
+- ensure Markdown summaries and sidecars no longer silently contradict each other
+- record final sidecar validation evidence or mark the mismatch `NOT_VERIFIED`
+- supersede earlier mismatch notes only by naming the final reconciled sidecars and evidence
+
+If final sidecars still disagree with the Markdown artifact, return `NOT_VERIFIED` or `FAIL` according to the affected acceptance criteria.
+
+## Verdict Rules
+
+- Every acceptance criterion gets a status.
+- Evidence is mandatory for PASS.
+- `NOT_VERIFIED` is honest uncertainty, not failure disguised as success.
+- A technically green build is not enough for PASS when the user still cannot run, inspect, understand, or act on the result.
+- The orchestrator routes FAIL, PARTIAL, and unaccepted NOT_VERIFIED back through execution or to an explicit user decision.

package/context/contracts/work-item-contract.md

@@ -0,0 +1,215 @@
+# Work Item Contract
+
+This contract defines the provider-neutral vocabulary for selecting, planning, and handing off backlog work. It is the source shape for provider-backed workflows such as `pull-work`; provider-specific adapters map into this model without making GitHub, Jira, Linear, or any other provider the generic language.
+
+## Provider Roles
+
+- `WorkItemProvider`: supplies issue-like records that represent requested work, defects, chores, or decisions.
+- `BoardProvider`: supplies project, board, milestone, sprint, or queue membership and the fields used to order or route work.
+- `ChangeProvider`: supplies branch, review, merge request, pull request, changeset, release, or deploy records that represent a published implementation.
+
+A single external system can implement both roles. For example, GitHub Issues is a `WorkItemProvider`, while GitHub Projects is a `BoardProvider`.
+
+## Work Item Shape
+
+Every provider-backed work item should preserve the stable fields below when the provider can supply them.
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `id` | yes | Stable provider identifier, such as an issue number, opaque item id, or provider-qualified id. |
+| `title` | yes | Human-readable summary. |
+| `body` | optional | Main description, problem statement, or request body. |
+| `status` | optional | Provider-neutral lifecycle state or mapped board status, such as `todo`, `ready`, `in_progress`, `blocked`, `review`, `verification`, or `done`. |
+| `labels` / `tags` | optional | Provider labels, tags, components, or categories used for filtering and triage. |
+| `priority` | optional | Provider priority value mapped without changing meaning, such as `P0`, `P1`, or `high`. |
+| `size` | optional | Estimated implementation size, complexity, or effort. |
+| `risk` | optional | Delivery, technical, product, security, migration, or coordination risk. |
+| `blockers` | optional | Blocking work items, decisions, external dependencies, or explicit blocked reasons. |
+| `related_links` | optional | URLs or provider references for related issues, discussions, docs, designs, incidents, and decisions. |
+| `source_provider` | yes | Provider identity and source location, including provider kind, owner or workspace, repository or project, and canonical URL when available. |
+| `project_membership` / `board_membership` | optional | Board, project, milestone, sprint, queue, column, or status-field membership supplied by a `BoardProvider`. |
+| `pr_links` | optional | Pull requests, merge requests, or changesets associated with the work item. |
+| `artifact_refs` | optional | Workflow artifacts, sidecars, evidence, plans, reviews, handoffs, or durable docs that trace the work. |
+
+Provider-specific fields may be carried as adapter metadata, but generic workflow skills should make selection and handoff decisions from the neutral shape above.
+
+## Planning Base And Drift
+
+Executable work items should record the source revision that shaped their scope. This lets pickup Probe compare the current repository against the assumptions used when the work entered the backlog.
+
+Recommended fields:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `planned_base_ref` | recommended | Branch or ref used when shaping the work item, usually `main`. |
+| `planned_base_sha` | recommended | Exact commit SHA of `planned_base_ref` at shaping time. |
+| `planned_at` | recommended | Timestamp when the work item was shaped or last materially re-shaped. |
+| `planning_artifact_ref` | recommended | Idea-to-backlog, design, ADR, or plan artifact that produced the work item. |
+| `planning_scope_refs` | optional | Key docs, contracts, schemas, files, or packages considered during shaping. |
+| `dependency_refs` | optional | Issues, changes, releases, or commits assumed complete, pending, or blocking during shaping. |
+
+`pull-work` and pickup Probe should compare `planned_base_sha` with the current target ref before planning implementation. At minimum, record:
+
+- current target ref and SHA
+- files, docs, contracts, or schemas changed since `planned_base_sha` when they overlap `planning_scope_refs` or likely execution scope
+- dependency issue/change state that has moved since shaping
+- whether drift is material to scope, acceptance criteria, dependencies, or risk
+
+Pickup Probe drift outcomes:
+
+| Outcome | Meaning |
+| --- | --- |
+| `no_material_drift` | The work item is still aligned with current main and dependencies. |
+| `scope_drift` | Current code/docs changed the intended scope or acceptance criteria; ask for alignment or route back to shaping. |
+| `dependency_drift` | Assumed blockers, prerequisites, or related changes moved; refresh dependency assumptions before planning. |
+| `contract_drift` | Relevant docs, contracts, schemas, or provider policies changed; re-check the work item against the current contract. |
+| `conflict_risk` | Changed files or active work overlap likely execution scope; require worktree, rebase, sequencing, or coordination before planning. |
+
+If a legacy work item lacks `planned_base_sha`, pickup Probe should record the gap and use current main plus provider history as the best available baseline instead of inventing certainty.
+
+## Publish Change Shape
+
+`publish-change` is the provider-neutral step between clean local evidence and release readiness. It publishes the verified diff to a `ChangeProvider`, records the provider result, and collects provider checks without making any one provider's terms core workflow vocabulary.
+
+### References
+
+Use typed references instead of provider-specific nouns in core artifacts:
+
+| Ref | Description |
+| --- | --- |
+| `work_item_ref` | Provider-backed work request, defect, task, or decision selected for the workflow. |
+| `board_ref` | Project, board, queue, milestone, sprint, or planning surface that contextualizes the work item. |
+| `change_ref` | Published implementation record such as a pull request, merge request, changeset, review request, release proposal, or deploy request. |
+| `evidence_ref` | Workflow evidence, CI/check run, test report, review artifact, governance report, or provider-native proof linked to the change. |
+
+### PublishChangeResult
+
+A publish-change result should preserve:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `provider` | yes | Stable provider id and adapter version when known. |
+| `status` | yes | `published`, `updated`, `skipped`, `failed`, or `not_verified`. |
+| `work_item_refs` | optional | Work items the change intends to address. |
+| `board_refs` | optional | Board or project records affected by the change. |
+| `change_ref` | optional | Provider change identity, canonical URL, branch, target, and state. Required unless status is `skipped`, `failed`, or `not_verified`. |
+| `closing_reference_check` | optional | Whether the provider recognized references that will close or resolve work items. |
+| `provider_checks` | optional | Provider-native checks such as CI, required review, policy, mergeability, status, or deployment gates. |
+| `evidence_refs` | optional | Local sidecars, standard evidence artifacts, provider checks, and external evidence records used for release readiness. |
+| `summary` | yes | Human-readable outcome and next action. |
+
+### ClosingReferenceCheck
+
+Closing-reference recognition is provider behavior. Core workflow artifacts should record the neutral result:
+
+| Field | Required | Description |
+| --- | --- | --- |
+| `expected_work_item_refs` | yes | Work items the change is expected to close, resolve, or complete. |
+| `recognized_work_item_refs` | yes | Work items the provider reports as recognized by the change record. |
+| `missing_work_item_refs` | yes | Expected refs not recognized by the provider. |
+| `status` | yes | `pass`, `fail`, `not_verified`, or `skip`. |
+| `evidence_refs` | optional | Provider API response, rendered body, check output, or dry-run fixture supporting the result. |
+
+If closing behavior matters and expected refs are missing, publish-change must return `fail` or `not_verified`; do not hide it as a successful publish.
+
+### Provider Checks
+
+Provider checks are external facts used by evidence-gate and release-readiness. Examples include CI checks, required status checks, branch protection, mergeability, required review, deployment checks, and external policy checks. Record them as provider-neutral check records with status `pass`, `fail`, `not_verified`, or `skip`, plus evidence refs.
+
+Missing provider checks are risk-sensitive:
+
+- Docs-only changes may pass with an explicit `skip` when the skipped provider check is not required by the repository and the artifact records why local review is enough.
+- Runtime, schema, package, hook, security, migration, release, or infrastructure changes require provider check evidence or an explicit `not_verified` / release `hold`.
+- A provider being unavailable is not a pass. Record `not_verified` unless the workflow explicitly chooses a low-risk no-provider path.
+
+## Capability Flags
+
+Adapters must describe provider capabilities explicitly so workflows can avoid assuming unavailable fields.
+
+| Capability | Meaning |
+| --- | --- |
+| `issues` | Provider can list or read issue-like work items. |
+| `projects_boards` | Provider can list or read project, board, queue, sprint, or milestone membership. |
+| `status_fields` | Provider exposes lifecycle, column, state, or status field values. |
+| `custom_fields` | Provider exposes typed project or work item fields beyond the base shape. |
+| `dependencies` | Provider exposes blocked-by, blocks, parent-child, or linked-dependency relationships. |
+| `labels` | Provider exposes labels, tags, components, or categories. |
+| `milestones` | Provider exposes milestones, releases, iterations, or equivalent delivery targets. |
+| `assignees` | Provider exposes owner or assignee information. |
+| `pr_links` | Provider exposes pull request, merge request, changeset, or branch links. |
+| `comments` | Provider exposes discussion comments or activity entries. |
+| `change_records` | Provider exposes branch, pull request, merge request, changeset, release, deploy, or review records. |
+| `closing_references` | Provider reports whether change text or metadata will close, resolve, or complete linked work items. |
+| `checks` | Provider exposes CI, status, review, mergeability, policy, deployment, or equivalent checks. |
+
+Capabilities are descriptive, not discovery settings. Provider settings and configured-provider discovery are separate implementation concerns.
+
+## Status Guidance
+
+Adapters may keep the provider's original status in metadata, but workflow-facing status should be mapped to a small neutral category when possible:
+
+- `todo`: known work that is not ready or started.
+- `ready`: scoped work that can be selected.
+- `in_progress`: work currently owned or being implemented.
+- `blocked`: work waiting on another item, decision, access, or external event.
+- `review`: work waiting for human or automated critique.
+- `verification`: work waiting for validation, evidence, or CI.
+- `done`: accepted, closed, merged, released, or otherwise complete according to the provider.
+
+When a provider has more detail than these categories, carry it in `project_membership`, `board_membership`, or adapter metadata rather than expanding the generic status vocabulary.
+
+## GitHub Mapping
+
+GitHub is the first concrete mapping for this contract, not the generic vocabulary.
+
+### GitHub Issues as `WorkItemProvider`
+
+| Work item field | GitHub Issues source |
+| --- | --- |
+| `id` | Repository-qualified issue number or node id. |
+| `title` | Issue title. |
+| `body` | Issue body. |
+| `status` | Issue state plus mapped project status when available. |
+| `labels` / `tags` | Issue labels. |
+| `priority`, `size`, `risk` | Labels or GitHub Projects custom fields when present. |
+| `blockers` | Linked issues, task lists, project fields, or issue body references marked as blocked/blocking. |
+| `related_links` | Issue links, closing references, discussions, docs, and cross-references. |
+| `source_provider` | `github`, repository owner/name, issue number, node id, and issue URL. |
+| `pr_links` | Linked pull requests, closing PRs, branches, or manually referenced PR URLs. |
+| `artifact_refs` | `.flow-agents/<slug>/` artifacts, plan/review/evidence links, and promoted docs referenced from the issue or workflow. |
+
+### GitHub Projects as `BoardProvider`
+
+| Board field | GitHub Projects source |
+| --- | --- |
+| `project_membership` / `board_membership` | Organization or repository project, project item id, view or board name when known, status field, milestone, iteration, and custom fields. |
+| `status` | Mapped project status field when it is more workflow-relevant than issue open/closed state. |
+| `priority`, `size`, `risk` | Project custom fields or labels when those fields are configured. |
+| `blockers` | Project dependency fields, linked issues, or custom blocked fields when configured. |
+| `related_links` | Project item URL, project URL, milestone URL, and linked provider references. |
+
+GitHub capability flags should reflect what the current token and project configuration can actually read. Do not treat unavailable project fields as empty truth; record them as not available or `NOT_VERIFIED` in workflow evidence when they affect selection.
+
+### GitHub Pull Requests as `ChangeProvider`
+
+| Publish/change field | GitHub source |
+| --- | --- |
+| `change_ref` | Pull request number, node id, head branch, base branch, URL, merge state, and review state. |
+| `work_item_refs` | Issues linked in the pull request body, branch, commits, manually supplied metadata, or GraphQL closing issue references. |
+| `closing_reference_check` | Provider-recognized closing issues from GitHub, compared with expected issue refs. |
+| `provider_checks` | Check runs, status checks, required reviews, branch protection, mergeability, and deployment checks visible to the token. |
+| `evidence_refs` | Workflow sidecars, verification summaries, CI URLs, check run URLs, review artifacts, and release-readiness records linked from the pull request. |
+
+GitHub is the first adapter/example for publish-change. Core workflow text should still say `change_ref`, `provider_checks`, and `closing_reference_check` unless it is inside a GitHub mapping or example.
+
+## Artifact References
+
+Workflow artifacts should be linked by stable path or URL and should preserve traceability to source work items:
+
+- pull-work artifacts that capture board snapshots and selection rationale
+- plan artifacts and `acceptance.json`
+- execution handoffs and modified-file evidence
+- review, verification, evidence, release, and learning sidecars
+- promoted durable docs or release notes
+
+`artifact_refs` should not replace provider state. They connect agent workflow evidence back to the provider-backed work item.

package/context/deferred/demo-mode.md

@@ -0,0 +1,33 @@
+# Demo Mode
+
+Speed over polish. For customer demos, workshops, and prototypes.
+
+## When to Activate
+- User says "demo", "prototype", "workshop", "spike", "proof of concept", or "POC"
+- Explicitly requested: "use demo mode"
+
+## Relaxed Quality Gates
+- Skip TDD — write tests only for critical paths if time allows
+- Skip code review — no tool-verifier pass required
+- Minimal validation — "it runs and looks right" is sufficient
+- Skip linting/formatting enforcement
+
+## Quick-Start Patterns
+
+| Language | Stack | Command |
+|----------|-------|---------|
+| TypeScript | Vite + React | `npm create vite@latest -- --template react-ts` |
+| Python | FastAPI | `pip install fastapi uvicorn && uvicorn main:app --reload` |
+| Go | net/http | Standard library, no framework needed |
+| Java | Spring Boot | `spring init --dependencies=web,devtools` |
+
+## Guidelines
+- **Visual-first validation** — use Playwright screenshots over unit tests for UI work
+- **Framework scaffolding** — prefer `create-*` CLIs and official templates over manual setup
+- **Hardcoded config is fine** — no need for env vars or config files in demos
+- **Skip abstractions** — inline logic, skip interfaces/factories, keep it flat
+- **Copy-paste is acceptable** — DRY doesn't apply to throwaway code
+
+## ⚠️ Boundary
+
+Demo-mode artifacts MUST NOT be committed to production branches. Use a `demo/` or `spike/` branch prefix. If demo code needs to become production code, run the full development workflow from step 0.

package/context/deferred/languages/go.md

@@ -0,0 +1,31 @@
+# Go Rules
+
+Loaded on-demand when working in Go projects.
+
+## Error Handling
+- Check every error — no `_` for error returns unless explicitly justified
+- Wrap errors with context: `fmt.Errorf("doing X: %w", err)`
+- Use `errors.Is` / `errors.As` for comparison — never string matching
+- Sentinel errors as package-level `var` for expected conditions
+- Return errors, don't panic — reserve `panic` for truly unrecoverable states
+
+## Testing
+- Table-driven tests as the default pattern
+- Use `testify/assert` or `testify/require` for readable assertions
+- `t.Helper()` in test helper functions
+- `t.Parallel()` for independent tests
+- Benchmarks (`Benchmark*`) for performance-sensitive code
+
+## Tooling
+- `go vet` + `golangci-lint` with default linters enabled
+- `gofmt` / `goimports` for formatting (non-negotiable)
+- `go mod tidy` before every commit
+
+## Patterns
+- Accept interfaces, return structs
+- `context.Context` as first parameter for cancellation and deadlines
+- Prefer small interfaces (1-3 methods) for testability
+- Use `sync.Once` for lazy initialization, not `init()`
+- Channel direction in function signatures: `chan<-` or `<-chan`
+- Prefer `slog` (Go 1.21+) for structured logging
+- Embed structs for composition, not inheritance

package/context/deferred/languages/python.md

@@ -0,0 +1,31 @@
+# Python Rules
+
+Loaded on-demand when working in Python projects.
+
+## Types
+- Type hints on all function signatures — no untyped public APIs
+- Use `from __future__ import annotations` for forward references
+- `typing.Protocol` for structural subtyping over ABC where possible
+
+## Validation
+- Pydantic for runtime validation of external inputs (API payloads, config, env vars)
+- Dataclasses or attrs for internal data structures (no plain dicts for structured data)
+
+## Testing
+- pytest as the test framework — no unittest
+- Co-locate tests in `tests/` mirroring `src/` structure
+- Use fixtures over setup/teardown methods
+- `pytest-cov` for coverage reporting
+
+## Tooling
+- Ruff for linting and formatting (replaces flake8 + black + isort)
+- `pyproject.toml` as the single config file
+- Type checking with mypy or pyright in strict mode
+
+## Patterns
+- Use `async/await` where I/O bound (httpx, database, file ops)
+- Prefer `pathlib.Path` over `os.path`
+- Use context managers (`with`) for resource cleanup
+- Prefer `enum.Enum` over string constants
+- Use `logging` module with structured output — no `print()` in library code
+- Virtual environments always — never install to system Python

package/context/deferred/languages/typescript.md

@@ -0,0 +1,34 @@
+# TypeScript Rules
+
+Loaded on-demand when working in TypeScript projects.
+
+## Compiler
+- `strict: true` always — no exceptions
+- Target ES2022+ unless browser compat requires lower
+
+## Types
+- Prefer `type` over `interface` for unions and intersections
+- `interface` for object shapes that may be extended
+- No `any` without a `// eslint-disable` comment explaining why
+- Use `unknown` for untyped external data, narrow with type guards
+- Prefer `const` and `readonly` — mutability must be intentional
+
+## Validation
+- Use Zod for runtime validation of external inputs (API payloads, env vars, config)
+- Infer types from Zod schemas (`z.infer<typeof schema>`) — single source of truth
+
+## Testing
+- Jest or Vitest (prefer Vitest for new projects)
+- Co-locate test files: `foo.ts` → `foo.test.ts`
+- Mock external dependencies, not internal modules
+
+## Tooling
+- ESLint + Prettier (or Biome as a single tool)
+- `@typescript-eslint/strict` ruleset as baseline
+- Format on save, lint on commit
+
+## Patterns
+- Prefer `async/await` over raw Promises
+- Use discriminated unions for state machines
+- Barrel exports (`index.ts`) only at package boundaries, not within modules
+- Prefer named exports over default exports