@kontourai/flow-agents 0.1.1

package/docs/skills-map.md

@@ -0,0 +1,203 @@
+---
+title: Flow Agents Skills Map
+---
+
+# Flow Agents Skills Map
+
+This map groups the current skills by the user journey they support. The Builder Kit workflow system is centered on concrete workflow skills, while Flow Agents coordinates Flow Kit installation, runtime adapters, and local control.
+
+For practical operator instructions and copy/paste prompts, see https://github.com/kontourai/flow-agents/blob/main/docs/workflow-usage-guide.md. For the shared cross-distribution contracts behind the workflow artifacts and gates, see https://github.com/kontourai/flow-agents/blob/main/docs/workflow-shared-contracts.md.
+
+- `builder-shape`: product-level Builder Kit shape invocation that guides `idea-to-backlog` without requiring the user to name the primitive, links `kits/builder/flows/shape.flow.json`, and stops at the backlog gate unless issue sync is explicit.
+- `idea-to-backlog`: discovery, idea separation, thinnest meaningful slice, shaping, prioritization, and executable GitHub issue creation.
+- `pull-work`: dynamic backlog selection, grouping/dependency checks, WIP awareness, worktree decision, and execution handoff; in Builder Kit build, every selected item or justified group needs fresh pickup Probe evidence before planning.
+- `design-probe`: generic one-question-at-a-time probing interview; Builder Kit uses this step before planning when the build flow needs shared understanding or a pickup decision.
+- `pickup-probe`: Builder Kit specialization of `design-probe` for selected work items; records scope, provider state, WIP/conflict scans, risks, decisions, unresolved questions, accepted gaps, and planning readiness.
+- `plan-work` / `execute-plan` / `deliver`: Definition Of Done, execution orchestration, and local delivery closure.
+- `review-work`: report-only critique for quality, security triggers, architecture fit, and standards findings.
+- `verify-work`: behavior evidence mapped to acceptance criteria and Goal Fit.
+- `evidence-gate`: trust assessment for completed work: acceptance evidence, integrity checks, CI confidence, and next step.
+- `release-readiness`: operational decisioning for a published change: merge/release/deploy/hold, rollback, observability, final acceptance docs, and post-deploy planning.
+- `learning-review`: post-merge/post-deploy learning, follow-up routing, docs promotion checks, and durable knowledge capture.
+
+```mermaid
+flowchart LR
+  Idea[Raw idea or goal]
+  Shape[Builder Kit shape / idea-to-backlog<br/>shape executable work]
+  Pickup[pull-work<br/>select ready work]
+  Probe[design-probe / pickup-probe<br/>pickup Probe before planning]
+  Build[plan-work + execute-plan<br/>build the slice]
+  Review[review-work<br/>critique code and risk]
+  Verify[verify-work<br/>prove behavior]
+  GoalFit[goal-fit<br/>check user outcome]
+  Trust[evidence-gate<br/>map criteria to evidence]
+  Publish[publish-change<br/>commit / push / PR / CI]
+  Release[release-readiness<br/>merge / release / deploy / docs decision]
+  Learn[learning-review<br/>route follow-ups]
+  Backlog[(GitHub issues)]
+
+  Idea --> Shape --> Backlog --> Pickup --> Probe --> Build --> Review --> Verify --> GoalFit --> Trust --> Publish --> Release --> Learn
+  Probe -->|not needed| Build
+  Pickup -->|too vague or stale| Shape
+  Review -->|findings| Build
+  GoalFit -->|incomplete| Build
+  Trust -->|FAIL / NOT_VERIFIED| Build
+  Learn -->|new work| Shape
+```
+
+## Current Shape
+
+The operating model now has first-class coverage from idea intake through trusted delivery:
+
+- Upstream product work is exposed through `builder-shape` and owned by `idea-to-backlog`.
+- Backlog selection and execution handoff are owned by `pull-work`.
+- Design probing is a generic skill named `design-probe`; in the Builder Kit build flow the step is still named `design-probe`, and the `pickup-probe` specialization records selected-work readiness before planning. `decision_gap` route-backs return there for missing pickup/planning decisions.
+- Product-level Builder Kit build may guide `pull-work -> design-probe / pickup-probe -> plan-work`; direct primitives still stop at their own gates and report the expected next step.
+- Broad continuation language does not carry across newly selected work after merge. Queue inspection is allowed, but planning the next item requires a fresh pickup Probe record.
+- Critique is owned by `review-work` and persisted in `critique.json`.
+- Verification is owned by `verify-work` and persisted in `evidence.json`.
+- Trust evidence is assessed by `evidence-gate`; it decides whether completed work has enough proof and integrity to publish or continue fixing.
+- Publishing verified changes is the bridge between evidence and release readiness: commit the verified diff, push the branch, open or update the PR, and collect PR/CI evidence.
+- Merge/release/deploy decisioning is owned by `release-readiness` after the publish-change gate.
+- Retrospective learning and follow-up routing are owned by `learning-review`.
+- Implementation still flows through `plan-work`, `execute-plan`, `review-work`, and `verify-work`, with `Definition Of Done` and `Goal Fit Gate` preventing task-complete-but-user-incomplete delivery.
+- Real browser/runtime checks remain delegated to `feedback-loop` and `browser-test`.
+
+The upstream guardrail is intentionally strict: multiple ideas are inventoried separately first, the thinnest meaningful slice is identified for each buildable idea, and bundled work must have an explicit dependency or shared-outcome justification. The pickup workflow repeats this check before planning so unrelated backlog items do not silently become one implementation stream.
+
+The intentionally deferred primitives such as `intake-idea`, `shape-work`, `test-map`, and `scope-and-integrity-check` are nested workflow sections for now. They should become separate skills only if their behavior grows enough to need independent contracts, artifacts, or eval suites.
+
+## Phase Composition
+
+This view shows how each phase is composed. The left rail is the durable phase sequence; each phase row names its primary owner, supporting skills, nested sections that may later become primitives, and the gate/artifact that lets the next phase begin.
+
+<section class="phase-map" aria-label="Workflow phase composition">
+  <article class="phase-row">
+    <div class="phase-step"><span>01</span><strong>Discovery & shaping</strong></div>
+    <div class="phase-lanes">
+      <section class="phase-lane phase-lane--primary"><h3>Primary</h3><p><code>builder-shape</code> <code>idea-to-backlog</code></p></section>
+      <section class="phase-lane"><h3>Support</h3><p><code>knowledge-search</code> <code>search-first</code> <code>explore</code> <code>crowdsource</code> <code>frontend-design</code> <code>github-cli</code> <code>knowledge-capture</code></p></section>
+      <section class="phase-lane"><h3>Nested sections / future primitives</h3><p>intake/dedupe, separate ideas, thinnest meaningful slice, opportunity review, explore options, <code>shape-work</code>, prioritize work, sync executable backlog</p></section>
+      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Idea, slice, shape, and backlog gates. Writes shaped briefs and GitHub issue links in <code>.flow-agents/&lt;slug&gt;/</code>.</p></section>
+    </div>
+  </article>
+  <article class="phase-row">
+    <div class="phase-step"><span>02</span><strong>Backlog pickup</strong></div>
+    <div class="phase-lanes">
+      <section class="phase-lane phase-lane--primary"><h3>Primary</h3><p><code>pull-work</code></p></section>
+      <section class="phase-lane"><h3>Support</h3><p><code>github-cli</code></p></section>
+      <section class="phase-lane"><h3>Nested sections / future primitives</h3><p>board snapshot, WIP check, grouping/dependency check, pickup Probe decision, worktree decision, <code>plan-work</code> handoff</p></section>
+      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Pickup gate and pickup Probe handoff. Writes selected issues, blockers, bundle justification, provider state, accepted gaps, worktree policy, expected modified files, conflict risks, and handoff notes.</p></section>
+    </div>
+  </article>
+  <article class="phase-row">
+    <div class="phase-step"><span>03</span><strong>Planning & build</strong></div>
+    <div class="phase-lanes">
+      <section class="phase-lane phase-lane--primary"><h3>Primary</h3><p><code>plan-work</code> <code>execute-plan</code> <code>review-work</code> <code>verify-work</code></p></section>
+      <section class="phase-lane"><h3>Support</h3><p><code>feedback-loop</code> <code>browser-test</code> <code>deliver</code> <code>fix-bug</code> <code>tdd-workflow</code></p></section>
+      <section class="phase-lane"><h3>Nested sections / future primitives</h3><p>Definition Of Done, execution plan, parallel waves, implementation session state, critique report, verification report, runtime/browser validation, Goal Fit Gate</p></section>
+      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Review, verification, and Goal Fit gates. Produces critique findings plus test, build, lint, browser, or runtime evidence tied to acceptance criteria and the user-facing outcome.</p></section>
+    </div>
+  </article>
+  <article class="phase-row">
+    <div class="phase-step"><span>04</span><strong>Evidence & release</strong></div>
+    <div class="phase-lanes">
+      <section class="phase-lane phase-lane--primary"><h3>Primary</h3><p><code>evidence-gate</code> <code>release-readiness</code></p></section>
+      <section class="phase-lane"><h3>Support</h3><p><code>github-cli</code> <code>eval-rebuild</code></p></section>
+      <section class="phase-lane"><h3>Nested sections / future primitives</h3><p>criteria-to-evidence map, CI confidence, <code>scope-and-integrity-check</code>, publish-change, rollback review, observability review, post-deploy plan, final acceptance docs, remediate-ci</p></section>
+      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Evidence, publish-change, release, and docs gates. Writes confidence, integrity, commit/branch/PR/CI links, release scope, risk, rollback, deploy-readiness decisions, and durable documentation links.</p></section>
+    </div>
+  </article>
+  <article class="phase-row">
+    <div class="phase-step"><span>05</span><strong>Learning & improvement</strong></div>
+    <div class="phase-lanes">
+      <section class="phase-lane phase-lane--primary"><h3>Primary</h3><p><code>learning-review</code></p></section>
+      <section class="phase-lane"><h3>Support</h3><p><code>knowledge-capture</code> <code>observe</code> <code>idea-to-backlog</code> <code>eval-rebuild</code></p></section>
+      <section class="phase-lane"><h3>Nested sections / future primitives</h3><p>facts vs interpretation, follow-up routing, docs promotion review, knowledge updates, eval updates, skill/backlog improvements</p></section>
+      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Learning gate. Writes outcomes, gaps, docs promotion state, follow-ups, knowledge updates, and verdict.</p></section>
+    </div>
+  </article>
+</section>
+
+| Phase | Primary workflow skill | Supporting skills | Nested sections / future primitive candidates |
+| --- | --- | --- | --- |
+| Idea discovery and shaping | `builder-shape`, `idea-to-backlog` | `knowledge-search`, `search-first`, `explore`, `crowdsource`, `frontend-design`, `github-cli`, `knowledge-capture` | intake/dedupe, separate ideas, thinnest meaningful slice, opportunity review, explore options, shape work, prioritize work, sync executable backlog |
+| Backlog pickup | `pull-work` | `github-cli` | board snapshot, WIP check, grouping/dependency check, Probe decision, worktree decision, handoff |
+| Execution planning and build | `design-probe`, `pickup-probe`, `plan-work`, `execute-plan`, `review-work`, `verify-work` | `feedback-loop`, `browser-test`, `deliver`, `fix-bug`, `tdd-workflow` | Probe notes, Builder Kit Probe record, Definition Of Done, execution plan, parallel waves, implementation session state, critique report, verification report, Goal Fit Gate |
+| Evidence and release confidence | `evidence-gate`, `release-readiness` | `github-cli`, `eval-rebuild` | criteria-to-evidence map, CI confidence, scope/integrity check, publish-change, rollback review, observability review, final acceptance docs, post-deploy plan |
+| Learning and improvement | `learning-review` | `knowledge-capture`, `observe`, `idea-to-backlog`, `eval-rebuild` | facts vs interpretation, docs promotion review, follow-up routing, knowledge updates, eval/skill/backlog improvements |
+
+The highest-leverage future extractions are likely `shape-work`, `test-map`, `scope-and-integrity-check`, and `remediate-ci`. They are still nested because their behavior is present, but not yet large enough to need separate activation contracts.
+
+## Gates And Artifacts
+
+Each workflow phase ends with an explicit gate and durable artifact:
+
+- `builder-shape` invokes Builder Kit shape, delegates to `idea-to-backlog`, links `kits/builder/flows/shape.flow.json`, and writes the standard `.flow-agents/<slug>/<slug>--idea-to-backlog.md` artifact.
+- `idea-to-backlog` writes `.flow-agents/<slug>/<slug>--idea-to-backlog.md` and produces shaped briefs plus GitHub issue links.
+- `pull-work` writes `.flow-agents/<slug>/<slug>--pull-work.md` with selected issues, WIP notes, blockers, pickup Probe decisions or accepted gaps, worktree decision, expected modified files, conflict risks, and a `plan-work` handoff.
+- `plan-work` and `deliver` write `.flow-agents/<slug>/<slug>--*.md` artifacts with `Definition Of Done`, `Goal Fit Gate`, and `Final Acceptance` sections.
+- `review-work` writes reviewer artifacts when available and updates `critique.json` with quality, security, architecture, standards, and resolution state.
+- `verify-work` writes verification artifacts and updates `evidence.json` with behavior evidence mapped to acceptance criteria.
+- `evidence-gate` writes `.flow-agents/<slug>/<slug>--evidence-gate.md` with acceptance evidence, CI summary, integrity report, verdict, and next step.
+- `release-readiness` writes `.flow-agents/<slug>/<slug>--release-readiness.md` with release scope, evidence reference, risk review, operational plan, rollback plan, observability plan, post-deploy checks, and decision.
+- `learning-review` writes `.flow-agents/<slug>/<slug>--learning-review.md` with outcomes, evidence, decisions, gaps, follow-ups, knowledge updates, and verdict.
+
+Core gates:
+
+- Idea Gate: raw input is deduped, classified, and routed.
+- Slice Gate: each candidate has one outcome, one thinnest meaningful slice, and explicit split/bundle/dependency reasoning.
+- Shape Gate: scope, non-goals, risk, rollout notes, and acceptance criteria are stable enough.
+- Backlog Gate: GitHub issues represent executable or near-executable work.
+- Pickup Gate: selected work is ready, WIP is acceptable, and worktree policy is recorded.
+- Review Gate: report-only reviewers have no open blocking findings, or findings are explicitly accepted/deferred/false positive.
+- Verification Gate: implementation evidence exists from local, automated, browser, or runtime checks.
+- Goal Fit Gate: the original user outcome is satisfied, gaps are explicit, and local/project/global scope is clear.
+- Evidence Gate: acceptance criteria are mapped to falsifiable evidence and scope integrity is checked.
+- Publish Change Gate: verified changes are committed, pushed, represented by a PR or explicit no-PR decision, and PR checks/CI are linked.
+- Release Gate: CI, docs, rollout, rollback, observability, and owner concerns are addressed for the risk class.
+- Docs Gate: accepted planning artifacts are archived and promoted into durable docs when useful.
+- Learning Gate: failures and recurring patterns are routed to tests, evals, skills, backlog, or knowledge capture.
+
+## End-To-End Flow
+
+```mermaid
+flowchart LR
+  Idea[Idea / vague goal]
+  BacklogSkill[idea-to-backlog]
+  Issue[Executable GitHub issue]
+  Pull[pull-work]
+  Probe[design-probe]
+  Worktree[worktree decision]
+  Plan[plan-work]
+  Execute[execute-plan]
+  Review[review-work]
+  Verify[verify-work]
+  GoalFit[goal-fit]
+  Evidence[evidence-gate]
+  Publish[publish-change]
+  Release[release-readiness]
+  Docs[final acceptance docs]
+  Learning[learning-review]
+  Done[merged / shipped]
+
+  Idea --> BacklogSkill --> Issue --> Pull --> Probe --> Worktree --> Plan --> Execute --> Review --> Verify --> GoalFit --> Evidence
+  Evidence -->|PASS| Publish --> Release --> Done --> Docs --> Learning
+  Review -->|findings| Execute
+  GoalFit -->|incomplete| Plan
+  Evidence -->|FAIL / NOT_VERIFIED| Plan
+  Pull -->|too vague / stale| BacklogSkill
+  Learning -->|systemic change| Eval[eval-rebuild / backlog / skill update]
+```
+
+## Eval Coverage
+
+Workflow evals are layered to match this map:
+
+- Static contract evals guard non-negotiable skill boundaries.
+- Behavioral activation evals check that agents choose the right workflow and stop at gates.
+- Artifact quality evals inspect durable session artifacts and GitHub issue drafts.
+- Adversarial evals exercise premature coding, vague issues, missing CI, weakened tests, and prototype promotion risks.
+- End-to-end evals cover `idea-to-backlog -> pull-work -> design-probe -> plan-work -> execute-plan -> review-work -> verify-work -> goal-fit -> evidence-gate` selectively.
+
+This keeps one conversation capable of carrying the full operating loop while making each phase produce an artifact that the next phase can verify.

package/docs/standards-register.md

@@ -0,0 +1,96 @@
+---
+title: Standards Register
+---
+
+# Standards Register
+
+Flow Agents should reuse durable standards and common conventions before inventing local formats. This register records the standards Flow Agents intends to align with and where Flow Agents-owned schemas may still be needed.
+
+## Adoption Policy
+
+Use an existing standard when it covers the job well enough.
+
+Invent a Flow Agents format only when:
+
+- no durable standard fits the artifact
+- the format is small and purpose-specific
+- the format has a JSON Schema or equivalent contract
+- the artifact is human-inspectable or has a readable companion summary
+- the artifact can be exported to a common format when practical
+
+Avoid private formats for skills, repo instructions, contacts, calendars, API descriptions, security findings, dependency provenance, or telemetry when a widely used standard exists.
+
+## Standards
+
+| Area | Standard / Convention | Flow Agents Use |
+| --- | --- | --- |
+| Repo guidance | `AGENTS.md` | Project-level instructions and durable agent guidance. |
+| Source language | TypeScript-first source policy | Product/runtime source should default to TypeScript across Kontour repositories, with narrow JS/MJS exceptions. See `docs/adr/0006-typescript-first-source-policy.md`. |
+| Skills | Agent Skills / `SKILL.md` | Reusable capability packages with progressive disclosure. |
+| Tools | MCP | Tool, resource, prompt, and integration exposure. |
+| API contracts | OpenAPI | HTTP/service integration descriptions. |
+| Auth | OAuth/OIDC | Delegated access and identity boundaries for integrations. |
+| Resource contracts | Kontour Resource Contract | Kubernetes-inspired, runtime-neutral durable records for Flow Agents scope, workflow state, evidence pointers, provider output, and interchange. See `docs/kontour-resource-contract.md`. |
+| Workflow state | JSON Schema | Flow Agents-owned state, criteria, handoff, evidence, critique, release, and learning sidecars. |
+| Telemetry | OpenTelemetry logs/traces and GenAI conventions | Runtime, workflow, tool, model, and eval event alignment. Evidence sidecars reference native OpenTelemetry records instead of copying them. |
+| Findings | SARIF | Code review, security, static analysis, and policy finding interchange where applicable. Evidence sidecars reference native SARIF runs/results. |
+| Supply chain | CycloneDX, SLSA | Dependency, SBOM, provenance, and release-trust workflows. |
+| Contacts | JSContact, vCard where needed | Person and relationship records. |
+| Calendar | iCalendar, CalDAV | Meetings, events, reminders, and schedule references. |
+| Mail/data sync | JMAP | Future-facing mail, contacts, and calendar sync model. |
+| Transcripts | WebVTT/SRT | Meeting and video transcript import/export. |
+| Notes | CommonMark, Markdown frontmatter | Durable human-readable knowledge artifacts. |
+| Structured knowledge | JSON-LD, schema.org | Portable people, organization, event, action, and relationship metadata when useful. |
+| Agent-to-agent | A2A | Watch and integrate only where it helps cross-runtime delegation. |
+| Documentation discovery | `llms.txt` | Track as emerging; use for docs discovery when it becomes stable enough. |
+
+## Flow Agents-Owned Formats
+
+Flow Agents may need local schemas for reliability glue that existing standards do not define cleanly.
+
+| Format | Purpose | Target Location | Status |
+| --- | --- | --- | --- |
+| Workflow state | Current phase, owner, next action, status, and resumability data | `.flow-agents/<slug>/state.json` | Draft schema: `schemas/workflow-state.schema.json` |
+| Acceptance criteria | Criteria, source request, evidence requirements, and goal-fit status | `.flow-agents/<slug>/acceptance.json` | Draft schema: `schemas/workflow-acceptance.schema.json` |
+| Evidence summary | Proof commands, standard refs, skipped checks, not-verified gaps, and external evidence links | `.flow-agents/<slug>/evidence.json` | Draft schema: `schemas/workflow-evidence.schema.json` |
+| Handoff | What another agent or future session needs to continue safely | `.flow-agents/<slug>/handoff.json` | Draft schema: `schemas/workflow-handoff.schema.json` |
+| Critique record | Reviewer passes, findings, severity, and resolution state for critique loops | `.flow-agents/<slug>/critique.json` | Draft schema: `schemas/workflow-critique.schema.json` |
+| Release readiness | Merge, release, deploy, hold, rollback, docs, and operational readiness decisions | `.flow-agents/<slug>/release.json` | Draft schema: `schemas/workflow-release.schema.json` |
+| Learning record | Repeated failure, correction, pattern, and recommended system update | `.flow-agents/<slug>/learning.json` or `.telemetry/outcomes.jsonl` | Draft schema: `schemas/workflow-learning.schema.json` |
+| Context map | Compact project map: structure, commands, conventions, test strategy, packs, and recent state | Generated under `.flow-agents/` or configurable cache | Planned |
+| Pack manifest | Core and optional pack composition for a target install | `packaging/packs.json` plus generated export catalog metadata | Draft manifest: `packaging/packs.json` |
+| Governance adapter | Optional bridge from Flow Agents evidence gates to tools such as Veritas | `context/contracts/governance-adapter-contract.md` | Draft contract |
+
+These formats should be treated as contracts once introduced. Breaking changes require schema version bumps and migration notes.
+
+## Integration Boundaries
+
+Flow Agents should integrate with external systems through narrow adapters.
+
+For example, Veritas can own repo-local standards, authority settings, evidence checks, JIT `explain`, and evidence records. Flow Agents can invoke Veritas and ingest its output without taking ownership of Veritas policy semantics.
+
+The adapter contract is `context/contracts/governance-adapter-contract.md`.
+
+Evidence adapters should preserve native proof when possible:
+
+- Static analysis, review, security, and policy findings should point to SARIF artifacts when the source can produce them.
+- Runtime and workflow events should point to OpenTelemetry logs or traces when available.
+- Test runner output should point to JUnit, TAP, or the runner's native artifact when available.
+- Veritas output should be recorded as an optional `standard_refs` or `external_evidence` entry with `standard: "veritas"`.
+
+That pattern should apply broadly:
+
+- Let specialized tools own their native model.
+- Map their output into Flow Agents evidence or knowledge records.
+- Keep adapters optional unless the capability is required for the core experience.
+
+## Review Questions
+
+Before merging a new schema, file format, or artifact:
+
+- Which standard did we check first?
+- Why was it insufficient?
+- Is the new format schema-described?
+- Is there a human-readable representation?
+- Can another tool consume or export it?
+- Does this belong in core or an optional pack?

package/docs/veritas-integration.md

@@ -0,0 +1,165 @@
+---
+title: Veritas Integration Boundary
+---
+
+# Veritas Integration Boundary
+
+Veritas is a strong fit for Flow Agents' development evidence and governance layer, but it should stay optional and adapter-driven.
+
+The guiding rule is simple: Flow owns generic process enforcement, Flow Agents projects Flow-backed workflows into agent harnesses, and Veritas owns repo-local standards, authority, and evidence-check semantics.
+
+## User-Facing Story
+
+The user should not need to know which tool produced a policy check.
+
+```text
+User: Keep going until the change is ready.
+
+Flow Agents:
+1. Plans the work.
+2. Executes or delegates scoped changes.
+3. Runs normal verification.
+4. If Veritas is configured, asks Veritas for repo-local readiness evidence.
+5. Records the Veritas artifact as gate evidence in the Flow-backed workflow state.
+6. Continues, blocks, or asks for a decision based on the Flow gate outcome.
+```
+
+The user sees a clear result: pass, fail, hold, or not verified. The implementation detail is that one evidence source may be Veritas.
+
+## Ownership Split
+
+| Area | Flow Agents Owns | Veritas Owns |
+| --- | --- | --- |
+| Workflow | Agent-facing workflow packs, harness hooks, sidecars, release decisions, learning loops | None |
+| Flow | Process steps, gates, transitions, Flow Runs, exceptions, and Flow Reports | None |
+| Governance | When to ask for governance evidence | Repo standards, authority settings, evidence checks |
+| Evidence | `evidence.json`, `standard_refs`, `external_evidence`, acceptance mapping | Native Veritas reports and rule results |
+| UX | Plain-language next action and user decision points | Explain output for policy/rule details |
+| Packaging | Optional power/adapter wiring | Veritas installation and configuration |
+
+Flow Agents may use Flow terminology internally as Flow is extracted, but Veritas evidence should remain a compact provider result. Do not copy Veritas requirements into Flow or Flow Agents workflow definitions.
+
+## Adapter Contract
+
+Flow Agents should integrate through the governance adapter contract:
+https://github.com/kontourai/flow-agents/blob/main/context/contracts/governance-adapter-contract.md
+
+The optional TypeScript adapter is available through:
+
+```bash
+npm run veritas-governance -- evidence \
+  --artifact-dir .flow-agents/<task-slug> \
+  --repo-root . \
+  --veritas-bin veritas \
+  --veritas-artifact .veritas/readiness/evidence.json \
+  --max-age-seconds 3600
+```
+
+By default the adapter invokes:
+
+```bash
+veritas readiness --check evidence --working-tree
+```
+
+Use `--veritas-bin <path-or-command>` to point at a local Veritas checkout, wrapper, or fixture. Use `--repo-root <path>` to choose the working directory for the Veritas process. Use `--veritas-root <path>` to append `--root <path>` to the Veritas command. Use `--evidence-path <path>` when the caller wants to write a sidecar somewhere other than `<artifact-dir>/evidence.json`. Use `--max-age-seconds <n>` to mark a configured native artifact stale after a caller-selected threshold.
+
+When Veritas runs, Flow Agents records a normal evidence check with a standard ref and top-level external evidence reference:
+
+```json
+{
+  "schema_version": "1.0",
+  "task_slug": "example-task",
+  "verdict": "pass",
+  "checks": [
+    {
+      "id": "veritas-governance-evidence",
+      "kind": "policy",
+      "status": "pass",
+      "summary": "Veritas readiness evidence completed without blocking findings.",
+      "standard_refs": [
+        {
+          "standard": "veritas",
+          "ref": "/repo/.veritas/readiness/evidence.json",
+          "role": "native",
+          "summary": "Native Veritas readiness evidence artifact."
+        }
+      ]
+    }
+  ],
+  "external_evidence": [
+    {
+      "system": "veritas",
+      "standard": "veritas",
+      "ref": {
+        "kind": "external",
+        "url": "file:///repo/.veritas/readiness/evidence.json"
+      },
+      "summary": "Native Veritas readiness evidence artifact."
+    }
+  ]
+}
+```
+
+The adapter maps native Veritas artifacts only by reference. It writes `kind: "policy"`, `standard_refs[].standard: "veritas"`, and top-level `external_evidence` entries with `standard: "veritas"`. It does not add Veritas-specific fields to Flow Agents schemas or copy native rule details into Flow Agents sidecars.
+
+If Veritas is unavailable and the workflow expected it, record `not_verified` instead of inventing a pass. The adapter records `not_verified` when the executable is missing, Veritas exits nonzero, the configured native artifact is missing or unreadable, or the artifact is older than the freshness threshold. `--not-configured` records `not_verified` without invoking Veritas. `--skip` records an explicit skipped policy check when the caller intentionally opts out.
+
+## Builder Kit Trust Evidence
+
+Builder Kit gates stay provider-neutral. The Builder Kit Flow Definition names gate expectations as `kind: "surface.claim"` and declares the claim type, subject, accepted statuses, and blocking behavior. It does not name Veritas or any other trust producer.
+
+When a trust-backed path is configured, Flow Agents may attach a compact Surface-shaped reference to the Builder Kit evidence gate. The reference points at a TrustReport or Trust Snapshot, carries the related gate id, Surface claim type, claim status, artifact ref, integrity summary, authority or trusted-producer summary, subject, and freshness state, and then maps to the normal Flow gate result. Flow owns the gate authority decision, route reason, trusted producer mapping, and accepted gap behavior. Surface owns the portable trust state represented by the Surface claim and the TrustReport / Trust Snapshot. A Probe can request or clarify the evidence needed before planning or before a later Builder Kit gate retries.
+
+Veritas is only one optional producer of those artifacts. A local Veritas readiness run can emit native Veritas evidence and, when configured, point Flow Agents at a Surface-shaped TrustReport or Trust Snapshot. Flow Agents records the reference; it does not copy Veritas rule models, readiness semantics, or provider-native fields into Builder Kit gates.
+
+Provider and artifact absence are explicit:
+
+- If no trust provider is configured, ordinary Builder Kit activation, planning, verification, and evidence gates continue to work through the existing Flow Kit path.
+- If a trust-backed path was requested but no provider is configured, the trust check records `not_verified` with a clear gap instead of blocking unrelated Builder Kit usage.
+- If a provider is configured but the expected TrustReport or Trust Snapshot is absent or unreadable, only the requested trust-backed evidence check records `not_verified`; it does not silently pass and it does not make Veritas mandatory.
+- If a TrustReport or Trust Snapshot is present but has a rejected, stale, expired, missing-authority, or integrity-mismatched Surface claim, the Builder Kit evidence gate routes through the normal `fail` or `not_verified` path.
+
+## Adoption Gate
+
+Before making Veritas a first-class Flow Agents power, prove:
+
+- Veritas can run in advisory readiness mode without becoming a hard dependency.
+- Veritas output maps cleanly into `evidence.json`.
+- Veritas rule failures produce actionable Flow Agents next actions.
+- Non-development and knowledge workflows do not pay a context or install penalty.
+- The integration improves reliability faster than a smaller Flow Agents-only checker.
+
+## Current Integration Shape
+
+Flow Agents should not introduce a repo-specific Python wrapper as the Veritas integration surface. Until the integration is worth productizing, run Veritas directly from the Veritas checkout or published package and record only compact evidence references in Flow Agents sidecars.
+
+The forward path is a small TypeScript adapter or package command that:
+
+- invokes Veritas readiness without copying Veritas rule schemas into Flow Agents
+- stores native Veritas output under `.veritas/` or a caller-selected external evidence directory
+- records a compact `evidence.json` reference through the Flow Agents sidecar writer
+- fails honestly with `NOT_VERIFIED` when Veritas was expected but unavailable or unreadable
+
+That adapter exists now as `flow-agents veritas-governance evidence`. It is intentionally optional and fixture-tested; ordinary Flow Agents validation and delivery workflows do not require a live Veritas installation.
+
+Veritas source and CLI details live in the Veritas repository:
+https://github.com/kontourai/veritas
+
+Current local configuration in this repo is limited to:
+
+1. Flow Agents adapter metadata under `integrations/veritas/`.
+2. Repo standards that Veritas may evaluate:
+   - instruction governance files stay intact
+   - workflow contract changes require eval updates
+   - hook/script changes require validation evidence
+3. A provider-neutral evidence contract for recording the result back into Flow Agents workflow state.
+
+## Non-Goals
+
+- Do not vendor Veritas source into Flow Agents.
+- Do not make Veritas mandatory for the core pack.
+- Do not duplicate Veritas policy schemas inside Flow Agents.
+- Do not make knowledge, meeting, or sales workflows depend on development governance tooling.
+- Do not bootstrap `.veritas/repo-map.json` from Flow Agents in this slice. Native Veritas repository setup remains future Veritas-owned or adapter-owned work.
+
+This keeps Veritas aligned with the north star without letting one optional governance provider define the whole Flow Agents architecture.

package/docs/work-item-adapters.md

@@ -0,0 +1,72 @@
+---
+title: Work Item And Change Adapters
+---
+
+# Work Item And Change Adapters
+
+Flow Agents uses provider-neutral workflow vocabulary and maps it to concrete tools through adapters. GitHub is the first adapter and the most common example, but core workflow gates should talk about work items, boards, changes, checks, and evidence instead of assuming GitHub-specific records.
+
+The source contract is `context/contracts/work-item-contract.md`.
+
+## Provider Roles
+
+Use these roles in artifacts and docs:
+
+- `WorkItemProvider`: issue-like requested work, defects, chores, or decisions.
+- `BoardProvider`: project, board, queue, sprint, milestone, or planning state.
+- `ChangeProvider`: published implementation records such as pull requests, merge requests, changesets, release proposals, or deploy requests.
+
+A provider can implement more than one role. GitHub Issues maps to `WorkItemProvider`, GitHub Projects maps to `BoardProvider`, and GitHub Pull Requests maps to `ChangeProvider`.
+
+## Publish Change
+
+`publish-change` runs after local evidence is clean enough to share and before release readiness. It should produce a `PublishChangeResult` with:
+
+- `work_item_refs`: the selected work items the change intends to satisfy.
+- `board_refs`: any board/project/queue records that contextualize the work.
+- `change_ref`: the published provider change record.
+- `closing_reference_check`: whether the provider recognized expected close/resolve references.
+- `provider_checks`: CI, status, review, mergeability, deployment, policy, or equivalent checks.
+- `evidence_refs`: local sidecars, verification reports, standard evidence artifacts, and provider-native proof.
+
+If a provider is unavailable, record `not_verified` unless the workflow explicitly selected a low-risk no-provider path.
+
+## Planning Base Drift
+
+When a work item is shaped for the backlog, record the target ref and commit SHA that informed the plan, usually current `main`. Provider adapters should preserve that as `planned_base_ref`, `planned_base_sha`, `planned_at`, and `planning_artifact_ref` when possible.
+
+At pickup time, compare the current target SHA with the planned base SHA before planning implementation. If relevant files, docs, contracts, schemas, or dependency states changed, pickup Probe should classify the drift as `no_material_drift`, `scope_drift`, `dependency_drift`, `contract_drift`, or `conflict_risk` and ask for alignment when the drift changes scope or risk.
+
+GitHub can store this in the issue body, a managed comment, a source artifact, or adapter metadata. Core workflow logic should still treat it as provider-neutral work item metadata.
+
+## GitHub Adapter Example
+
+For GitHub, `publish-change` usually means:
+
+- commit the verified diff
+- push the branch
+- open or update a pull request
+- render the pull request body from a file or structured template
+- include issue closing references, workflow evidence, verification summary, and artifact links
+- ask GitHub which issue references it recognizes
+- collect pull request checks, required reviews, mergeability, and status checks
+
+GitHub-specific words belong in adapter sections and examples. The shared workflow result should still be expressed as `change_ref`, `closing_reference_check`, `provider_checks`, and `evidence_refs`.
+
+## Risk-Based Missing Checks
+
+Provider checks are not equally important for every change.
+
+Docs-only changes can pass with an explicit `skip` when:
+
+- the repository does not require a provider check for the change
+- local diff review or docs validation is enough for the stated risk
+- the evidence names the skipped check and the reason
+
+Runtime, schema, package, hook, security, migration, release, infrastructure, or deployment changes require stronger evidence. Missing provider checks for those changes must become `not_verified` in evidence-gate or `hold` in release-readiness until CI or equivalent proof is available.
+
+Do not treat missing CI, missing required review, missing branch protection data, or provider API failure as a clean pass for risky changes.
+
+## Artifact Lifecycle
+
+Local workflow artifacts under `.flow-agents/<slug>/` or a distribution-specific artifact root are runtime/session state by default. Provider records may link to those artifacts, but long-lived decisions should be promoted into durable docs, release notes, changelogs, ADRs, or provider comments/descriptions that are intended to persist.