@kontourai/flow-agents 3.12.1 → 4.1.0

package/docs/adr/0023-kit-provisioning.md

@@ -0,0 +1,47 @@
+---
+title: "ADR 0023: Declarative Kit Provisioning"
+---
+
+# ADR 0023: Declarative Kit Provisioning
+
+**Date:** 2026-07-16
+**Status:** Accepted (owner-ratified Option A in flow-agents#647)
+
+---
+
+## Context
+
+Kits sometimes need to supply repository-owned configuration or policy files in addition to runtime projections. The motivating `veritas-governance` follow-up needs this capability, but embedding kit-specific copy logic in Flow Agents would violate the kit boundary. Runtime activation is also the wrong mechanism: its projection directory is regenerable adapter state, while these files must become normal files in the consumer repository.
+
+## Decision
+
+A kit may declare a `provisions` list in `kit.json`. Each entry is inert data naming an id, a source file inside the kit, and a consumer-repository-relative target. Provision declarations are never executed.
+
+The Flow Agents engine performs agent-blind file copying through an explicit `kit provision` operation. It validates source and target containment, preflights every destination, and creates files only when no declared destination already exists. An explicit `--force` option may replace declared destination files; the default never silently overwrites an anchor-owned or consumer-owned file. `--dry-run` reports the plan without writing.
+
+`flow-agents init --activate-kit` invokes the same engine after activation with create-only semantics. Existing destinations are reported as skipped warnings so init remains safe to rerun. Provisioning remains separate from runtime activation and its projection directory.
+
+The engine records successful copies under `.kontourai/flow-agents/provisions/<kit-id>.json`. This manifest is bookkeeping and may be replaced on a later successful provisioning operation. Enforcement policy and ownership of protected paths remain anchor-side; a kit declaration does not grant permission to overwrite them.
+
+## Consequences
+
+- Kits can ship repository files without executable installers or kit-specific engine behavior.
+- Create-only defaults preserve consumer and anchor ownership; replacement requires an explicit user operation.
+- Provisioned files belong to the consumer repository once written. Uninstalling or deactivating a kit never removes or reverts them.
+- Runtime adapters continue to activate only their supported projection assets and report provisions as explicitly skipped.
+- Consumers that need stronger protected-path policy enforce it at their anchor; the generic engine remains deliberately dumb and kit-neutral.
+
+## Accepted residuals
+
+- **Copy is best-effort against concurrent interposition (both ends).** The checks and the copy
+  are separate steps (check-then-act): a file created into a declared destination between the
+  conflict preflight and the write can still be overwritten, and a source re-pointed to a link
+  between its containment check and its read could resolve elsewhere. Provisioning targets a
+  developer/CI working tree, not a hostile multi-writer path, so both TOCTOU windows are accepted
+  rather than closed with exclusive-create / open-then-fstat plumbing. The static guarantees are
+  enforced up front: reserved-directory (`.git`, the provision manifest namespace), source and
+  destination containment (link-resolved), and case-fold collision rejection; concurrent
+  interposition on either end is out of scope.
+- **Target case-folding assumes the common single-case-family repo.** Collision and reserved-path
+  checks case-fold targets so case-insensitive filesystems are safe; a genuinely case-sensitive
+  repo that intends two targets differing only in case is rejected as a portability hazard.

package/docs/adr/index.md

@@ -32,3 +32,4 @@ Numbered ADRs below are FROZEN immutable history (see the banner on each file).
 | 0020 | Trust-Reconcile Manifest, Claim Classification, and Waivers | unknown | [0020-trust-reconcile-manifest-and-claim-classification.md](./0020-trust-reconcile-manifest-and-claim-classification.md) |
 | 0021 | Assignment Leases and Stale-Claim Takeover | 2026-07-02 | [0021-assignment-leases-and-stale-claim-takeover.md](./0021-assignment-leases-and-stale-claim-takeover.md) |
 | 0022 | Fail-Closed Delivery Reconciliation with Governed Exemptions | 2026-07-02 | [0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md](./0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md) |
+| 0023 | Declarative Kit Provisioning | 2026-07-16 | [0023-kit-provisioning.md](./0023-kit-provisioning.md) |

package/docs/architecture-engine-and-kits.md

@@ -102,9 +102,26 @@ Kit trust is orthogonal to engine privilege. A marketplace may call a kit offici
 
 The answer is determined by validation, activation, and gate evidence, not by a privileged kit list.
 
+## The Portfolio Layer Doctrine
+
+The engine/kits split here is Flow Agents' instance of the portfolio-wide **Layer Doctrine**
+([surface/docs/architecture/portfolio-layer-doctrine.md](https://github.com/kontourai/surface/blob/main/docs/architecture/portfolio-layer-doctrine.md)):
+dependency direction is one-way up the stack (open trust format → building-block tools → Surface →
+products), and no layer reaches sideways into a peer. A product engine (e.g. `@kontourai/veritas`)
+never depends on the platform, and a **kit consumes an engine only through its CLI + recorded
+artifacts, never as an npm library import** — the whole point of the manifest/catalog model above.
+Both edges are now enforced executably: veritas-side by `check-no-flow-agents-dep.mjs` (the engine
+declares no flow-agents dependency) and here by [`scripts/check-layer-boundary.mjs`](../scripts/check-layer-boundary.mjs)
+(no kit imports the veritas engine as a library). See veritas's
+[Engine / Surface Seam](https://github.com/kontourai/veritas/blob/main/docs/architecture/engine-surface-seam.md)
+for the canonical engine-vs-kit capability inventory that the Veritas Governance Kit row above
+builds on.
+
 ## Related docs
 
 - [Flow Kit Authoring Guide](kit-authoring-guide.md)
 - [Flow Kit Repository Contract](flow-kit-repository-contract.md)
 - [Runtime Hook Surface spec](spec/runtime-hook-surface.md)
 - [Verifiable Trust](verifiable-trust.md)
+- [Veritas Engine / Surface Seam](https://github.com/kontourai/veritas/blob/main/docs/architecture/engine-surface-seam.md) — how `@kontourai/veritas` splits into an engine library + the kit-owned product surface
+- [Portfolio Layer Doctrine](https://github.com/kontourai/surface/blob/main/docs/architecture/portfolio-layer-doctrine.md)

package/docs/context-map.md

@@ -59,7 +59,11 @@ Machine-readable workflow state lives beside Markdown artifacts in `.kontourai/f
 | builder-lifecycle-authorization.schema.json | Builder Lifecycle Authorization | https://kontourai.dev/schemas/builder-lifecycle-authorization.schema.json |
 | decision-record.schema.json | Flow Agents Decision Record | https://flow-agents.dev/schemas/decision-record.schema.json |
 | flow-agents-settings.schema.json | Flow Agents Settings | https://flow-agents.dev/schemas/flow-agents-settings.schema.json |
+| grounded-execution-narrative.schema.json | Flow Agents Grounded Execution Narrative | https://flow-agents.dev/schemas/grounded-execution-narrative.schema.json |
 | lifecycle-authority-keys.schema.json | Lifecycle Authority Key Registry | https://kontourai.dev/schemas/lifecycle-authority-keys.schema.json |
+| narrative-eval-result.schema.json | Flow Agents Narrative Eval Result | https://flow-agents.dev/schemas/narrative-eval-result.schema.json |
+| narrative-runtime-projection.schema.json | Flow Agents Grounded Runtime Projection | https://flow-agents.dev/schemas/narrative-runtime-projection.schema.json |
+| narrative-source-manifest.schema.json | Flow Agents Narrative Source Manifest | https://flow-agents.dev/schemas/narrative-source-manifest.schema.json |
 | workflow-acceptance.schema.json | Flow Agents Workflow Acceptance | https://flow-agents.dev/schemas/workflow-acceptance.schema.json |
 | workflow-critique.schema.json | Flow Agents Workflow Critique | https://flow-agents.dev/schemas/workflow-critique.schema.json |
 | workflow-evidence.schema.json | Flow Agents Workflow Evidence | https://flow-agents.dev/schemas/workflow-evidence.schema.json |
@@ -67,6 +71,7 @@ Machine-readable workflow state lives beside Markdown artifacts in `.kontourai/f
 | workflow-learning.schema.json | Flow Agents Workflow Learning | https://flow-agents.dev/schemas/workflow-learning.schema.json |
 | workflow-release.schema.json | Flow Agents Workflow Release Readiness | https://flow-agents.dev/schemas/workflow-release.schema.json |
 | workflow-state.schema.json | Flow Agents Workflow State | https://flow-agents.dev/schemas/workflow-state.schema.json |
+| workflow-waves.schema.json | Flow Agents Workflow Waves | https://flow-agents.dev/schemas/workflow-waves.schema.json |
 
 Primary tools: public `flow-agents workflow`, `trust.bundle`, artifact validation, `scripts/hooks/stop-goal-fit.js`, and `scripts/hooks/workflow-steering.js`. The package-internal writer is not an agent or consumer interface.
 
@@ -96,6 +101,7 @@ Primary tools: public `flow-agents workflow`, `trust.bundle`, artifact validatio
 | agentic-engineering | skills/agentic-engineering/SKILL.md | Eval-first execution, task decomposition, and cost-aware model routing for AI-driven development workflows. |
 | browser-test | skills/browser-test/SKILL.md | Headless browser automation via Playwright — screenshots, accessibility checks, form filling, UI testing, DOM inspection. |
 | builder-shape | kits/builder/skills/builder-shape/SKILL.md | Builder Kit shaping entrypoint. Turns a raw idea into a provider-neutral, reviewable backlog proposal and stops before build selection unless the user explicitly continues. |
+| consult-standards | kits/veritas-governance/skills/consult-standards/SKILL.md | Get just-in-time Veritas governance guidance for a file or work area before editing it: run `veritas explain --file <path>` (or `--work-area <id>`) to see the governance excerpt, the Repo Standards rules that apply, their do/don't/exampl... |
 | dependency-update | skills/dependency-update/SKILL.md | Analyze and upgrade project dependencies — latest versions, security vulnerabilities, actionable update plan across all package managers. |
 | design-probe | kits/builder/skills/design-probe/SKILL.md | Generic one-question-at-a-time design probe for turning unclear goals, designs, and handoffs into shared understanding. |
 | eval-rebuild | skills/eval-rebuild/SKILL.md | Project-specific build and install commands for the eval feedback loop. Injected into eval-builder agent. Replace this skill for different build systems. |
@@ -104,6 +110,7 @@ Primary tools: public `flow-agents workflow`, `trust.bundle`, artifact validatio
 | knowledge-capture | kits/knowledge/skills/knowledge-capture/SKILL.md | Save durable knowledge, lightweight pointers, user corrections, decisions, lessons, relationship context, or source references into the knowledge base. Use when the user says save, remember, capture, file this, bookmark context, or when... |
 | pickup-probe | kits/builder/skills/pickup-probe/SKILL.md | Provider-grounded pickup probe used at the Builder design-probe step before planning. |
 | search-first | skills/search-first/SKILL.md | Research-before-coding workflow. Search for existing tools, libraries, and patterns before writing custom code. |
+| standards-authoring | kits/veritas-governance/skills/standards-authoring/SKILL.md | Author or update a repo's Veritas Repo Standards through the kit's standards-authoring flow: run `veritas init --explore`/`--guided` to derive a proposed starter set (project name, repo-shape-adaptive Repo Map nodes, evidence-check infer... |
 
 ## Agents
 

package/docs/decisions/backlog-readiness-source.md

@@ -0,0 +1,89 @@
+---
+status: current
+subject: Backlog Readiness Source
+decided: 2026-07-16
+evidence:
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/441
+  - kind: pr
+    ref: https://github.com/kontourai/flow-agents/pull/449
+  - kind: commit
+    ref: c19c3e64a214be7d5b2585004fd3c4f2597781e5
+  - kind: url
+    ref: https://claude.ai/code/session_01SmQYjiUo1aDSXgEKyiye7M
+---
+
+# Backlog Readiness Source
+
+Which signal marks a Work Item intentionally ready for pickup, and what
+`pull-work` is allowed to do when that signal yields nothing.
+
+## Decision
+
+- **The org project board is the readiness source.** The configured
+  BoardProvider — org GitHub Project `kontourai/1` ("Flow Agents Builder
+  Platform") — carries readiness as board Status. `ready_statuses=["ready"]`
+  is the pickup filter; the board's `Priority` field ranks the cross-repo
+  ready queue.
+- **Triage is the automated intake status.** Every new `kontourai/*` issue is
+  added to the board with Status=Triage by the shared reusable workflow
+  (`kontourai/.github` `add-issue-to-project.yml`, called per-repo from
+  `.github/workflows/add-to-project.yml`); closing an issue moves it to Done.
+  Nothing reaches Ready automatically.
+- **The Triage → Ready move is the intentionality act.** Moving an item to
+  Ready (and setting Priority) is the triage responsibility that makes work
+  eligible for agent pickup. This is a deliberate human/triage-pass decision,
+  not automation.
+- **A configured readiness source that yields nothing is a surfaced warning,
+  never a silent fallback.** The board reader emits `zero_ready_items` when
+  the configured board produces an empty ready queue (landed with PR #449),
+  and the issue-listing path emits `board_provider_bypassed` whenever a
+  BoardProvider is configured but issue-level listing is used instead.
+  `pull-work` must carry these warnings into its artifact and route to
+  triage/intake rather than silently substituting unranked issue listing.
+- The settings contract declares the real board taxonomy: the schema's
+  `exclude_statuses` vocabulary includes `triage`, and this repo's settings
+  exclude `triage` explicitly. `verification` remains in the schema vocabulary
+  for provider-neutral shapes even though this board has no such column.
+
+## Evidence basis (re-verified live, 2026-07-16)
+
+Issue #441 was shaped on 2026-07-06 evidence that the board was dead (15
+items, all Done, no automation). That premise is now false:
+
+- The kontourai org has exactly **one** ProjectV2: `kontourai/1`, open, **468
+  items** (306 Triage / 14 Ready / 148 Done) spanning 13 repos; 169 of 171
+  open flow-agents issues are on it.
+- The auto-add workflow targets exactly this project
+  (`PVT_kwDOEJYCKs4BYzgP`), Status field options: Triage, Ready, In Progress,
+  Blocked, Review, Done.
+- A live board-driven `pull-work` read returns a **14-item priority-ranked
+  cross-repo ready queue** with zero warnings and zero intake gaps.
+- The agent-path `gh` token carries the `project` scope, so the read:project
+  friction recorded in #441 no longer holds.
+
+## Rejected alternative
+
+**Label-based readiness (per-repo `ready`/`blocked`/`in-progress` labels).**
+Recommended by #441 when the board was dead, because it needed no board
+maintenance and no extra token scope. Both advantages evaporated once the
+auto-add automation went live org-wide and the agent token gained `project`
+scope — and labels cannot express cross-repo priority ranking without
+inventing a parallel convention per repo. Revisit trigger: if the auto-add
+workflow or `project` token scope regresses for agent environments, reopen
+this subject rather than quietly re-deriving readiness from labels.
+
+## Follow-ups (owned elsewhere, not absorbed here)
+
+- **One-time triage sweep** of the ~306 Triage items (and any open issues
+  missing from the board) to assign Ready/Priority intentionally — owned by
+  the triage pass in #443 item 2. Not executed with this decision: the Ready
+  set was already non-empty (14 items), and bulk-moving 300+ items without
+  the accepted mechanism would manufacture fake intentionality.
+- **Board maintenance as flow responsibility** (intake adds, claim → In
+  Progress, completion Done assertion): #443.
+- **Doctor board-health checks** (configured-but-unfed board, dead readiness
+  source, missing token scope): #443 item 5 / #321. Until that surface
+  exists, the warnings live in `pull-work` provider output and the
+  `pull-work` skill contract only.
+- **Workspace-scoped pull-work** across multiple repos: #444.

package/docs/decisions/index.md

@@ -12,6 +12,7 @@ Numbered ADRs under `docs/adr/` are frozen history and are not listed here.
 | --- | --- | --- |
 | [agent-coordination](./agent-coordination.md) | current | Agent coordination |
 | [anti-gaming-trust-security](./anti-gaming-trust-security.md) | needs-decision | Anti-gaming trust security |
+| [backlog-readiness-source](./backlog-readiness-source.md) | current | Backlog Readiness Source |
 | [context-lifecycle](./context-lifecycle.md) | needs-decision | Context lifecycle |
 | [core-domain-kit-boundary](./core-domain-kit-boundary.md) | needs-decision | Core vs domain kit boundary |
 | [decision-records](./decision-records.md) | current | Decision records |
@@ -36,3 +37,4 @@ Numbered ADRs under `docs/adr/` are frozen history and are not listed here.
 | [typescript-source-policy](./typescript-source-policy.md) | current | TypeScript-first source policy |
 | [workflow-enforcement](./workflow-enforcement.md) | current | Workflow Enforcement |
 | [workflow-trust-state](./workflow-trust-state.md) | needs-decision | Workflow trust state |
+| [writer-observed-execution](./writer-observed-execution.md) | current | Writer-observed execution |

package/docs/decisions/writer-observed-execution.md

@@ -0,0 +1,51 @@
+---
+status: current
+subject: Writer-observed execution
+decided: 2026-07-14
+evidence:
+  - kind: issue
+    ref: "634"
+  - kind: adr
+    ref: docs/adr/0017-anti-gaming-trust-security-model.md
+  - kind: adr
+    ref: docs/adr/0020-trust-reconcile-manifest-and-claim-classification.md
+---
+# Writer-observed execution
+
+**Decision.** When `record-gate-claim` executes a declared evidence command itself
+(`runObservedCommand` — a real process it spawned, with a real exit code, output hash, and,
+for tests, a `local-process-exit` execution proof), it appends that observation to the same
+hash-chained `command-log.jsonl` the PostToolUse capture hook writes, under the same
+lockfile protocol, visibly attributed via `source: "canonical-writer-execution"`. The
+capture fold's precedence is **outcome-ranked, source-blind**: observed fail > observed
+pass > ambiguous, with the exit code always traveling with the winning status. The
+properties that matter follow: a writer pass can lift ambiguity but can never bury an
+independently captured failure (fail is sticky from either source), and a writer-observed
+failure likewise defeats any pass. Passes from the two sources rank equally — the
+distinction between them lives in the permanent `source` attribution, not in the fold. The chain
+fork classifier tolerates shared-parent siblings only when every sibling's source is
+`postToolUse-capture` or `canonical-writer-execution`; any other source on a shared parent
+remains tamper.
+
+**Context.** ADR 0017/0020 make the independent capture log the truth source for command
+outcomes, and #470 hardened capture to never record `pass` without positive evidence. On
+hosts whose runtime hook payloads carry no exit code (Claude Code's PostToolUse
+`tool_response` today), every captured entry is honestly `ambiguous` — and #634 showed the
+consequence: `builder.verify.*` claims can never derive `verified`, while the sanctioned
+accepted-gap waiver produces `assumed`, which no gate's `accepted_statuses` admits. The
+verify gate was structurally unclosable on such hosts regardless of evidence quality.
+
+**Why this preserves the anti-gaming posture.** A writer observation is not an inference or
+a self-report of intent — it is the exit code of a process the canonical writer itself
+spawned and waited on. It enters the record distinguishable forever (the `source` field),
+tamper-evident (chain-hashed), serialized against the hook (shared lock), and subordinate
+on conflict (an observed fail from either source wins). The waiver path is untouched:
+accepted gaps remain disclosure that derives `assumed`, never gate satisfaction.
+
+**Residual risk, accepted.** A compromised writer process could self-attest a pass the hook
+never saw. Mitigations: the attribution is permanent and auditable; the chain makes
+retroactive editing detectable; a hook-observed failure always prevails; and PR CI Trust
+Reconcile re-executes manifest commands independently of any local observation. Follow-up
+(#634 option c): when runtime harnesses surface exit codes in hook payloads, hook capture
+naturally resumes confirming passes first-hand; writer observations then serve as
+corroboration rather than the sole deterministic signal.

package/docs/developer-architecture.md

@@ -22,7 +22,7 @@ Use these local references when you need more detail:
 - [ADR 0005](adr/0005-kubernetes-inspired-resource-contracts.md) records the Kontour Resource Contract direction.
 - [Kontour Resource Contract](kontour-resource-contract.md) documents the shared durable record shape.
 - [Flow Kit Repository Contract](flow-kit-repository-contract.md) documents local kit validation and activation boundaries.
-- [Veritas Integration Boundary](veritas-integration.md) documents optional governance evidence.
+- [Veritas Integration Boundary](veritas-integration.md) records the early integration rationale; the shipped path is the **Veritas Governance Kit** (`kits/veritas-governance`) — see its [README](../kits/veritas-governance/docs/README.md) and [Engine and kits](architecture-engine-and-kits.md).
 
 ## Coordination Map
 
@@ -63,10 +63,10 @@ flowchart LR
 | Flow Agents | Agent-facing workflow bundles, skills, sidecars, artifact contracts, evals, runtime export, provider wiring, and local-first docs. | Does not become the core workflow engine for all Kontour products and should not copy product-native rule models into this repo. |
 | Flow | Generic workflow semantics, Flow Definitions, gate transitions, attempts, route-back behavior, Flow Runs, and Flow Reports. | Flow Agents may consume or project Flow concepts, but Flow owns enforcement semantics once the Flow surface is available. |
 | Builder Kit | The first Kontour-authored Flow Kit for build work: shaping, pickup probes, planning, execution, review, verification, publication, release readiness, and learning workflows. | Flow Agents validates, installs, activates, and routes Builder Kit assets; it does not make every Builder Kit specialization a core Flow Agents concept. |
-| Veritas | Repo-local standards, authority settings, policy/rule checks, and native governance reports. | Flow Agents records compact Veritas evidence references when configured; Veritas is optional and not a mandatory dependency for every workflow. |
+| Veritas | The repo-local governance **evaluation engine** (`@kontourai/veritas`): repo standards, authority settings, policy/rule checks, merge-readiness, and native governance reports. | Flow Agents ships the **Veritas Governance Kit** (`kits/veritas-governance`), which owns the repo-installed governance surface (standards scaffold, hooks, authoring, agent guidance) and gates a real `veritas readiness` verdict as a `software-readiness-verdict` trust.bundle claim — wrapping the engine's CLI, never importing or reimplementing it. The kit is optional; the engine it wraps is a standalone library. |
 | Surface | Portable trust state, claims, TrustReports, Trust Snapshots, and user-facing trust surfaces. | Flow Agents can reference Surface-shaped claims for gates, but Surface owns claim models and trust presentation. |
 
-**Current state:** Builder Kit is the first proof point for extracting out-of-the-box behavior into normal Flow Kits. Veritas integration is documented as optional and adapter-driven. Surface references appear as a trust-state boundary in local Veritas and Builder Kit evidence docs.
+**Current state:** Builder Kit is the first proof point for extracting out-of-the-box behavior into normal Flow Kits. Veritas is consumed through the **Veritas Governance Kit** (`kits/veritas-governance`) — an agentless kit that wraps the `veritas` CLI and projects its recorded readiness verdict into a trust.bundle gate; it owns the repo-installed governance surface, while veritas stays the standalone evaluation engine. Surface references appear as a trust-state boundary in local Veritas and Builder Kit evidence docs.
 
 **Future direction:** Flow Agents should support more runtime adapters, provider adapters, and Flow Kits without forcing all users to install Builder Kit, Veritas, Surface, or a specific hosted provider.
 

package/docs/fixture-ownership.md

@@ -23,11 +23,15 @@ run `npm run validate:source --` and `npm run fixture:retirement-audit --`.
 | `evals/fixtures/kit-conformance-levels` | K-level conformance and consumer-target derivation fixtures | `evals/integration/test_kit_conformance_levels.sh` | Keep while K-level derivation, degradation invariant, and consumer-target badge rules are tested. |
 | `evals/fixtures/hook-influence` | hook influence behavioral cases | `evals/integration/test_hook_influence_cases.sh`, `evals/static/test_workflow_skills.sh`, `scripts/validate-hook-influence-cases.js` | Keep while hook influence cases define agent guidance behavior. |
 | `evals/fixtures/learning-review-proposals` | learning-review kit/gate tuning proposal fixtures (#352): pattern-present (engineered cost-inflation + gate false-block-rate pattern, with sessions/ trust.bundle + gate-review.inquiries.json joins and a hand-computed expected-aggregates.json), balanced (proportional cost/findings movement -> zero proposals), under-threshold (below LR_MIN_WINDOW_SAMPLE), repeat-window (idempotency), and effect-follow-up (later-window effect-fill pass for a ratified proposal) | `evals/integration/test_learning_review_proposals.sh` | Keep while `scripts/telemetry/learning-review-proposals.sh`/`learning-review-decide.sh` (docs/specs/learning-review-proposals-contract.md) are enforced: hand-computed aggregates, evidence-cited proposals, zero-mutation, idempotency, and the ratify -> effect-fill trail. |
+| `evals/fixtures/narrative-sources` | narrative source snapshot, offline resolution, integrity, completeness, fail-closed redaction, grounded runtime projection, grounded execution narrative, and trust-isolation fixtures (#613, #617, #618, #619) | `evals/integration/test_narrative_source_contract.sh`, `evals/integration/test_narrative_runtime_projection.sh`, `evals/integration/test_narrative_grounded_envelope.sh`, `evals/integration/test_narrative_redaction_failclosed.sh`, `evals/integration/test_narrative_trust_isolation.sh` | Keep while the narrative source manifest, content-addressed offline resolver, integrity verification, grounded runtime projection, grounded execution narrative composition, capture-completeness disclosure, lifecycle locality, fail-closed redaction, and narrative trust-isolation contracts are supported. |
+| `evals/fixtures/narrative-grounding-validator` | narrative grounding validator adversarial fixtures (#623) | `evals/integration/test_narrative_grounding_validator.sh` | Keep while deterministic citation integrity, material-event coverage, epistemic-label integrity, and fail-closed narrative publication are enforced. |
+| `evals/fixtures/narrative-prose-renderer` | model-assisted prose renderer adversarial fixtures (#614): provenance-subset (unsupported-summary), no-op-loop lack-of-progress wording, and prompt-injection fixtures reused from evals/fixtures/narrative-grounding-validator | `evals/integration/test_narrative_prose_renderer.sh` | Keep while the fail-closed prose renderer (D3 provenance-subset citation check, provider gating, economics-always, zero-prose-artifact-on-failure) is enforced. |
+| `evals/fixtures/narrative-evals` | grounded narrative faithfulness eval corpus + result-schema package (#612): ten R1 case-class fixtures with frozen-manifest answer keys plus five R3 corruption fixtures whose named eval-check anchors are the scorer-teeth mutation targets | `evals/integration/test_narrative_evals.sh` | Keep while the versioned adversarial corpus, its frozen-manifest answer keys, the schema-valid narrative-eval-result output, the declared cross-runtime capability parity, and the R3 scorer-teeth mutation battery are enforced. |
 | `evals/fixtures/pull-work-provider` | work item provider normalization fixtures | `evals/integration/test_pull_work_provider.sh` | Keep while provider normalization preserves blockers, artifact refs, board membership, and freshness metadata. |
 | `evals/fixtures/pull-work-wip-shepherding` | WIP shepherding state fixtures | `evals/static/test_workflow_skills.sh` | Keep while pull-work documents personal versus global WIP behavior. |
 | `evals/fixtures/reconcile-preflight` | #356 reconcile-preflight shape fixtures not already covered by trust-reconcile-exploits (un-superseded disputed critique, standalone disputed session-local claim) | `evals/integration/test_reconcile_preflight.sh` | Keep while the local `reconcile-preflight` subcommand (#356) is proven against the two shapes trust-reconcile-exploits does not already fixture (un-superseded disputed critique, standalone disputed session-local claim); the other four shapes reuse trust-reconcile-exploits/trust-reconcile-mixed-bundle directly rather than forking near-duplicates. |
 | `evals/fixtures/surface-trust` | Surface trust evidence fixtures | `evals/integration/test_workflow_sidecar_writer.sh` | Keep while sidecar writer maps Surface trust evidence into workflow records. |
-| `evals/fixtures/telemetry` | hermetic Stop-hook usage transcript fixture (#defect-2026-07 telemetry-usage-cost-extraction): a multi-model JSONL transcript with .message.model + .message.usage token blocks proving real token/cost/model extraction end-to-end; also reused by the #568 slice 1 per-tool-call usage-enrichment eval (test_telemetry_tool_usage.sh), which adds usage-transcript-oversized-prefix.jsonl to prove the bounded tail-read | `evals/integration/test_usage_cost.sh`, `evals/integration/test_telemetry_usage_pipeline.sh`, `evals/integration/test_telemetry_tool_usage.sh` | Keep while telemetry.sh's Stop-hook usage pipeline (usage_parse_transcript / usage_model_from_transcript_usage / usage_last_turn_usage) is proven against hermetic multi-model and oversized-prefix transcripts rather than relying on live runtime data. |
+| `evals/fixtures/telemetry` | hermetic Stop-hook usage transcript fixture (#defect-2026-07 telemetry-usage-cost-extraction): a multi-model JSONL transcript with .message.model + .message.usage token blocks proving real token/cost/model extraction end-to-end; also reused by the #568 slice 1 per-tool-call usage-enrichment eval (test_telemetry_tool_usage.sh), which adds usage-transcript-oversized-prefix.jsonl to prove the bounded tail-read | `evals/integration/test_usage_cost.sh`, `evals/integration/test_telemetry_usage_pipeline.sh`, `evals/integration/test_telemetry_tool_usage.sh`, `evals/integration/test_telemetry_tool_outcome.sh` | Keep while telemetry.sh's Stop-hook usage pipeline (usage_parse_transcript / usage_model_from_transcript_usage / usage_last_turn_usage) is proven against hermetic multi-model and oversized-prefix transcripts rather than relying on live runtime data. |
 | `evals/fixtures/trust-reconcile-exploits` | WS8 trust-reconcile anti-gaming exploit fixtures (frozen negative regressions); also reused by the #356 local reconcile-preflight eval (same shapes, no forked copies) | `evals/integration/test_trust_reconcile_negatives.sh`, `evals/integration/test_reconcile_preflight.sh` | Keep while trust-reconcile.js enforces the WS8 iteration-2 soundness properties (no-label test_output, unwaived-assumed, status-misassertion, waiver-on-command); each fixture is a permanent negative regression. |
 | `evals/fixtures/trust-reconcile-mixed-bundle` | WS8 trust-reconcile mixed-evidence end-to-end proof fixture; also reused by the #356 reconcile-preflight eval as its CLEAN-BUNDLE (AC4) case | `evals/integration/test_trust_reconcile_mixed_bundle.sh`, `evals/integration/test_reconcile_preflight.sh` | Keep while the trust-reconcile manifest/classification/waiver contract (ADR 0020) is enforced; proves a mixed test_output + session-local + waived bundle passes the CI anchor. |
 | `evals/fixtures/trust-reconcile-ws3` | WS8 AC6 backward-compat fixture: real ws3-kit-dependencies-namespacing old-style bundle | `evals/integration/test_trust_reconcile_negatives.sh` | Keep while backward compatibility with pre-classification (all-test_output) bundles is asserted; proves an old-style bundle still FAILS the same way (no silent pass). |

package/docs/flow-kit-repository-contract.md

@@ -72,7 +72,7 @@ codex-local
 
 Unknown adapter ids fail with JSON diagnostics that include the available adapters. No Claude, Kiro, framework, API, npm module extraction, or remote install adapters are implemented by this activation surface.
 
-The `codex-local` adapter supports only Flow Definition assets declared in `flows`. It activates the built-in Builder Kit Flow Definitions, including `builder.shape` and `builder.build`, plus Flow Definitions from locally installed kit copies under:
+The `codex-local` adapter supports assets declared in `flows`, `skills`, and `docs`. It activates the built-in Builder Kit Flow Definitions, including `builder.shape` and `builder.build`, plus supported assets from locally installed kit copies under:
 
 ```text
 <dest>/kits/local/repositories/<kit-id>/
@@ -91,13 +91,13 @@ Flow Definition copies are placed under `flows/<kit-id>/<flow-id>.flow.json`, an
 The stable activation diagnostics include:
 
 - `selected_adapter`: selected adapter id, currently `codex-local`.
-- `supported_asset_classes`: asset classes the selected adapter activates, currently `["flows"]`.
+- `supported_asset_classes`: asset classes the selected adapter activates, currently `["flows", "skills", "docs"]`.
 - `generated_runtime_files`: generated runtime-local files with asset class, path, kit id, asset id, and source path.
 - `skipped_assets`: unsupported declared assets with asset class, path, kit id, asset id when present, and reason.
 - `warnings`: recoverable catalog, registry, or asset discovery problems.
 - `errors`: blocking discovery or activation problems.
 
-Declared `skills`, `docs`, `adapters`, `evals`, and generic `assets` are diagnostic-only for this adapter. They are skipped with explicit `skipped_assets` entries; they are not copied, installed, invoked, or treated as active runtime behavior.
+Declared `skills` and `docs` are copied into the runtime projection alongside flows. Declared `adapters`, `evals`, generic `assets`, and `provisions` are diagnostic-only for this adapter. They are skipped with explicit `skipped_assets` entries; they are not copied, installed, invoked, or treated as active runtime behavior.
 
 ## Root Manifest
 
@@ -122,6 +122,14 @@ Declared `skills`, `docs`, `adapters`, `evals`, and generic `assets` are diagnos
       "id": "example.readme",
       "path": "docs/README.md"
     }
+  ],
+  "provisions": [
+    {
+      "id": "example-kit.editor-policy",
+      "path": "provisions/editor-policy.json",
+      "target": ".editor/policy.json",
+      "description": "Initial repository policy."
+    }
   ]
 }
 ```
@@ -138,6 +146,29 @@ Optional fields:
 - `product_name`: non-empty display name when the product name differs from `name`.
 - `description`: non-empty summary.
 - `skills`, `docs`, `adapters`, `evals`, `assets`: lists of relative asset paths or objects with `id`, `path`, and optional `description`.
+- `provisions`: a list of objects with kit-id-prefixed `id`, source `path`, consumer-repository-relative `target`, and optional `description`.
+
+## Repository Provisioning
+
+Provision entries declare inert files; kits do not execute installer code. Source paths follow the other extension-asset rules: they must be relative, stay inside the kit directory, and name an existing regular file. Targets must be non-empty relative paths, must not contain traversal segments or resolve outside the consumer repository, must not be inside `.git`, and must be unique after normalization.
+
+Provision a catalog kit, an installed-registry kit, or a kit at a direct local path with:
+
+```bash
+flow-agents kit provision <kit-id-or-path> [--target <consumer-repo>] [--force] [--dry-run]
+```
+
+`--target` defaults to the current working directory and must already be a directory. The engine resolves the real path of the deepest existing destination ancestor before writing, so a symlink cannot redirect a provision outside the target repository. It preflights the whole declaration: by default, any existing destination reports every conflict, exits nonzero, and writes none of the provisioned files. `--force` replaces declared destination files. `--dry-run` prints every source-to-target mapping and writes nothing.
+
+After a successful non-dry-run copy, Flow Agents writes or replaces this bookkeeping manifest:
+
+```text
+<target>/.kontourai/flow-agents/provisions/<kit-id>.json
+```
+
+The schema is `{ schema_version: "1.0", kit_id, kit_hash, provisioned_at, files: [{ id, target }] }`. Provisioned files become consumer-repository content; uninstalling or deactivating the kit does not remove them.
+
+When `flow-agents init --activate-kit <id>` successfully activates a selected kit, init invokes the same provisioning engine against its destination with create-only semantics. Existing destinations are reported as skipped warnings and do not fail an init rerun. Provisions never enter the runtime projection directory.
 
 ## Path Rules
 

package/docs/kit-authoring-guide.md

@@ -54,7 +54,7 @@ Required fields:
 | `name` | Non-empty display name |
 | `flows` | Non-empty list; each entry must have `id` and `path` |
 
-Optional fields: `product_name`, `description`, `skills`, `docs`, `adapters`, `evals`, `assets`, `dependencies` (cross-kit dependency declarations; see [Cross-kit dependencies](#cross-kit-dependencies)), `workflow_triggers` (structured workflow steering keyed by engine trigger names such as `implementation-work-detected`), `hook_influence_expectations` (kit-owned required hook-influence fixture expectations), and `first_party` (legacy catalog/marketplace metadata; no runtime privilege). Optional asset fields list relative asset paths or objects with `id`, `path`, and optional `description`. `skills` and `docs` assets are activated by both adapters alongside flows. `adapters`, `evals`, and `assets` appear in diagnostics as `skipped_assets` (see the Activate section for the full per-adapter table).
+Optional fields: `product_name`, `description`, `skills`, `docs`, `adapters`, `evals`, `assets`, `dependencies` (cross-kit dependency declarations; see [Cross-kit dependencies](#cross-kit-dependencies)), `workflow_triggers` (structured workflow steering keyed by engine trigger names such as `implementation-work-detected`), `hook_influence_expectations` (kit-owned required hook-influence fixture expectations), `agent_spawn_triggers` (perimeter trigger surfaces that spawn agent runs plus their dedup/cooldown/cap/concurrency guard config; validation warns when a spawning surface lacks complete guards — see `context/contracts/trigger-guards.md`), and `first_party` (legacy catalog/marketplace metadata; no runtime privilege). Optional asset fields list relative asset paths or objects with `id`, `path`, and optional `description`. `skills` and `docs` assets are activated by both adapters alongside flows. `adapters`, `evals`, and `assets` appear in diagnostics as `skipped_assets` (see the Activate section for the full per-adapter table).
 
 ## Minimal flow file
 

package/docs/migrations.md

@@ -6,11 +6,26 @@ title: Migrations
 
 ## Unreleased
 
-- Gate-action envelopes now use `schema_version: "2.0"`. Each entry in
-  `gate.requirements` includes its originating `gate_id`, allowing consumers to
+- Gate-action envelopes now use `schema_version: "3.0"`. `action.declared_artifacts`
+  and `stop_condition.required.artifact_refs` contain typed targets instead of
+  strings. A `file` target names its project-relative `path` and whether it is
+  directly writable or must be produced through a declared operation; a
+  `trust_slice` target is explicitly non-writable and names the public interface
+  that records it. `action.artifact_bindings` maps each typed target to the
+  gate expectation ids it satisfies, so consumers can derive the exact required
+  target set from unresolved required expectations without private kit metadata.
+  The bindings are product-owned gate semantics, not grader hints or
+  consumer-authored guidance. Empty expectation ownership on a file represents
+  a declared optional artifact that is never gate-required; trust slices must
+  own an expectation so their recording interface can be derived.
+  Structured evidence parameters reference the canonical
+  `public_interfaces.schemas.evidence_ref_json` JSON Schema. There is no legacy
+  envelope fallback; adapters must require version 3.0 and stop treating
+  `trust.bundle#<slice>` as a filesystem path.
+- Gate-action envelope version 2.0 added the originating `gate_id` to each
+  `gate.requirements` entry, allowing consumers to
   verify accepted exceptions without private Flow-definition knowledge. There
-  is no legacy envelope fallback; adapters that validate or project the public
-  envelope must require version 2.0 and the new binding.
+  was no legacy version 1.0 fallback.
 - Workflow runtime artifacts now live under `.kontourai/flow-agents/` instead
   of earlier runtime roots such as `.flow-agents/` or `.agents/flow-agents/`.
   Move any local session directories, sidecars, or `current.json` pointers you

package/docs/public-workflow-cli.md

@@ -165,12 +165,21 @@ consume another turn when `workflow drive` is invoked again:
 flow_agents workflow drive \
   --session-dir .kontourai/flow-agents/example \
   --adapter-command-file .kontourai/flow-agents/runtime-adapter.json \
+  --context-policy fresh \
   --max-turns 6 \
   --turn-timeout-ms 900000 \
   --barrier-wait-ms 300000 \
   --json
 ```
 
+`--context-policy warm` remains the default and requests one new adapter context for the mission,
+then resumes it. `--context-policy fresh` requests a new context for every bounded Flow action. Both
+policies pass the same canonical gate-action handoff and preserve the same Flow gates, evidence rules,
+mission budget, and adapter authority. The selected policy is persisted with the mission and cannot be
+changed on resume. Adapters must honor the request's `context_strategy.thread` value and must not infer
+context routing from model names. This is a context-management capability, not permission to drop gates,
+invent evidence, or replay a prior transcript into a nominally fresh context.
+
 Driver state and its append-only event stream live under
 `.kontourai/flow-agents/<slug>/continuation-driver/`. The mission turn count survives reinvocation;
 subsequent invocations must use the same `--max-turns` value. The request contains the

package/docs/spec/builder-flow-runtime.md

@@ -157,7 +157,7 @@ authority for pointer navigation.
 ### Gate-Action Envelope
 
 Every active Builder continuation request includes a bounded
-`gate_action_envelope` with schema version `1.0`. Flow Agents derives it from
+`gate_action_envelope` with schema version `3.0`. Flow Agents derives it from
 the persisted canonical Flow run and effective Flow Definition, then joins it
 to the installed Builder Kit's validated `flow_step_actions` record. It is an
 execution context, not a second gate evaluator: Flow remains the only authority
@@ -179,12 +179,30 @@ Declared operations, artifacts, and evidence expectation ids come from product
 metadata. `implementation_allowed` is also product metadata; the shipped Builder
 Kit declares it true only for `builder.build/execute`.
 
-The read-only status interface is an exact version-pinned command. Mutation
+Declared artifact targets are typed. A `file` target includes its resolved
+project-relative path under the active session, its direct-write policy, and
+the skill or external operation that produces it. Operation result files are
+not model-writable. A `trust_slice` target names a
+logical `trust.bundle#<slice>` projection, sets `direct_write_allowed` to false,
+and identifies the public evidence or critique interface that records it. A
+trust slice is never a filename and adapters must not edit `trust.bundle`
+directly.
+
+The read-only status interface identifies the exact package version, binary,
+and argv without requiring an adapter to parse a shell command. Mutation
 interfaces are typed per expectation: `workflow.evidence`, `workflow.critique`,
 or a named product operation such as `publish-change`. Evidence and critique
 interfaces expose fixed argv plus typed required parameters and allowed values;
-they do not publish shell strings with substitution placeholders. Consumers add
-parameter values as distinct argv entries.
+they do not publish shell strings with substitution placeholders. Structured
+evidence parameters reference `public_interfaces.schemas.evidence_ref_json`, a
+bounded JSON Schema with required fields for source, command, artifact,
+provider, and external evidence. Consumers add parameter values as distinct
+argv entries.
+
+Adapters that perform an allowed direct file write remain responsible for
+opening the target without following symlinks and for confirming that the final
+path remains inside the active session. The envelope declares authority and
+identity; it does not make an arbitrary adapter filesystem write atomic.
 
 `publish-change` is a provider-capability protocol, not a claim that the local
 `flow-agents publish-change` helper opens a pull request. Its envelope binds the
@@ -204,7 +222,14 @@ checks; it is not the provider action executor.
 empty lists for terminal actions. Expectation ids must exactly equal the resolved
 Flow expectation set. Artifact bindings map each artifact to its owning
 expectations, allowing optional artifacts to remain declared without appearing
-under `stop_condition.required`. Operation bindings must resolve through the
+under `stop_condition.required`. The same ownership is projected publicly as
+typed `action.artifact_bindings`; consumers derive required targets by selecting
+bindings that own an unresolved required expectation. These bindings are
+product-owned gate semantics, not grader hints or consumer-authored guidance.
+For file artifacts, an empty `expectation_ids` list keeps the artifact declared
+and observable but never gate-required. Trust slices must own at least one
+expectation because ownership determines their recording interface.
+Operation bindings must resolve through the
 canonical public operation catalog, not merely a self-declared string. Artifact
 refs are either lexically safe session-relative paths or validated
 `trust.bundle#<safe-id>` virtual refs; absolute paths, traversal, and arbitrary
@@ -265,11 +290,16 @@ exception applies, or every effective expectation is optional. This advances
 those gates without prematurely evaluating ordinary missing-required gates, and
 once the run advances no obsolete action skill remains required.
 
-The envelope and its prior-turn delta are additive fields of
+The envelope, its prior-turn delta, and `context_strategy` are additive fields of
 `ContinuationTurnRequest` schema `1.0`; adapters that only consume the existing
-request fields remain compatible. When `workflow drive` produces its optional
+request fields remain compatible. `context_strategy` tells a capable adapter to
+start a `new` context or `resume` the mission context and identifies the handoff
+as canonical. The mission-bound policy defaults to warm continuation; selecting
+fresh context changes only transcript routing, never the Flow contract, gate
+requirements, or evidence authority. When `workflow drive` produces its optional
 signed request/result attestation, the exact request object (including the
-envelope) is included in the signed payload without transformation.
+envelope and context strategy) is included in the signed payload without
+transformation.
 # Builder Lifecycle Authority
 
 The canonical Flow run owns pause, resume, and cancellation. The current assignment actor may
@@ -295,6 +325,7 @@ Flow issue #118.
 ```text
 flow-agents builder-run pause --session-dir <dir> --reason <text>
 flow-agents builder-run resume --session-dir <dir> --reason <text>
+flow-agents builder-run cancel-request --session-dir <dir> [--out <file>] [--reason <text>] [--actor <name>] [--expires-in-hours <n>]
 flow-agents builder-run cancel --session-dir <dir> --authorization-file <record.json>
 flow-agents builder-run release-assignment --session-dir <dir> --reason <text>
 flow-agents builder-run archive --session-dir <dir> --authorization-file <record.json>
@@ -307,3 +338,13 @@ assignment while holding the same lock; a successfully consumed cancellation non
 replayed. Archive accepts only completed or canceled runs, moves the session under
 `.kontourai/flow-agents/archive/<slug>/`, and retains the canonical Flow run. None of these
 operations deletes a branch or worktree; cleanup requires a separate provider-aware action.
+
+`cancel-request` is a **read-only convenience** that removes the friction of hand-assembling a
+cancellation record: it mints the *unsigned* authorization for the run (correct `run_id`,
+`subject`, active `assignment_actor`, a fresh `nonce` and expiry) and prints the exact
+`signing_payload` bytes to sign. It does not sign, cancel, or mutate anything — the operator signs
+the payload with their Ed25519 lifecycle-authority key, adds the `signature` block to the emitted
+file, and runs `cancel --authorization-file` as above. The signing payload is produced through the
+same actor/request normalization the verifier applies, so a signature over it verifies by
+construction. Like `cancel`, it requires an active assignment holder; an active run whose
+assignment has already been released cannot be authorized this way without re-claiming it first.