@kontourai/flow-agents 3.3.0 → 3.4.0

package/docs/decisions/embeddable-engine.md

@@ -0,0 +1,152 @@
+---
+status: needs-decision
+subject: Embeddable engine and adapter model
+decided: 2026-07-07
+evidence:
+  - kind: doc
+    ref: docs/spec/runtime-hook-surface.md
+  - kind: doc
+    ref: docs/decisions/flow-flow-agents-boundary.md
+  - kind: doc
+    ref: docs/decisions/trust-ledger-retention.md
+  - kind: pr
+    ref: https://github.com/kontourai/flow-agents/pull/497
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/410
+---
+
+# Embeddable engine and adapter model
+
+> Status: **proposed** direction (shaped with Brian Anderson, 2026-07-07). Not yet
+> fully built. Ratify + carry forward as the runtime is factored. This record is
+> the north star the adapter/port refactors implement against; the linked backlog
+> issues are the work.
+
+**Decision.** Flow Agents is one **runtime-agnostic engine** with **thin
+adapters** on the edges. A development harness (Claude Code, Codex, opencode, pi,
+Kiro) and a customer agent built on a framework/SDK (AWS Strands, VoltAgent,
+LangGraph, OpenAI Agents SDK) are the **same shape**: both are adapters that feed
+canonical Flow events into the one engine and honor the same contracts. A Flow or
+Flow-Agent-Kit implementation should behave **consistently** across development
+workflows and customer agent implementations, with **explicit callouts** wherever
+a runtime genuinely cannot offer a Flow feature — never silent divergence.
+
+Five rules follow.
+
+1. **One core, adapters at the edge (DRY by construction).** The engine owns
+   everything runtime-independent: the canonical event vocabulary, the redaction
+   contract, project/session/actor attribution, dual-channel transport, trust
+   bundles, gate/claim semantics, and state projection. An adapter's only job is
+   to translate a runtime's native surface into canonical events and to invoke
+   engine decisions — it holds **no policy of its own**. Today the harness
+   adapters already prove this: one shared shell core
+   (`scripts/telemetry/telemetry.sh` + `lib/*.sh`) with thin per-runtime JS
+   adapters (~130 lines each) that normalize hook input and shell into the core.
+   Duplicated logic across adapters is a bug against this record.
+
+2. **Harness adapters and framework adapters are the same category.** A CLI
+   harness emits events from shell hooks; an in-process framework emits the same
+   canonical events from a language-native package — no shelling out, honoring the
+   same redaction contract in-process. The difference is the **transport into the
+   core**, not the **contract or the semantics**. `context.project`,
+   `context.cwd` redaction, actor identity, and dual-channel routing are derived
+   the same way everywhere (see `docs/spec/runtime-hook-surface.md`, which is now
+   the canonical adapter surface, and PR #497 which made `context.project` a
+   canonical field). Where the shell core cannot be reused verbatim in-process,
+   the engine's runtime-agnostic logic is extracted to a language port the
+   framework adapter calls; the shell adapter becomes one caller of that port, not
+   the definition of it.
+
+3. **Flow Agents is an "SDK" engine layer, and Console is its remote backend.**
+   The same engine that instruments a dev session is the layer a customer embeds
+   in their own agent to get Flow's trust/state/economics for free. When embedded,
+   the **Console is the remote trust and state backend** for those SDK-embedded
+   agents — the same projection surface described in
+   `docs/decisions/trust-ledger-retention.md` (git/CI authoritative, console a
+   rebuildable projection), now fed by customer agents as well as dev harnesses.
+   The engine does not care whether the events came from a terminal or from a
+   long-running service.
+
+4. **Cooperative in-process, authoritative at the boundary ("agent proposes, CI
+   disposes").** A framework/SDK adapter runs inside the customer's process, which
+   the engine does not control, so in-process enforcement is **cooperative**: the
+   embedded engine emits claims and honors gates as a good citizen. Authority
+   lives at the trust boundary the customer does not own — the **Console ingest
+   and CI trust-reconcile** re-verify what the agent claimed against independent
+   results (the fail-closed reconciliation from
+   `docs/adr/0022`). An adapter can be sloppy or hostile and the boundary still
+   holds the line. This is the same posture that already governs harness delivery;
+   it generalizes unchanged to embedded agents.
+
+5. **Consistency is guaranteed by a conformance suite, not by hope
+   (OpenTelemetry model).** Every adapter — shell harness or language framework —
+   must pass a shared **conformance suite** that asserts the canonical contracts:
+   event shape, redaction defaults (full local path never leaves the machine),
+   attribution precedence, dual-channel routing, and gate/claim behavior. A new
+   adapter is "done" when it passes the suite, exactly as an OpenTelemetry SDK is
+   conformant when it passes the spec's tests. Feature gaps a runtime cannot close
+   are declared **explicitly** in the adapter's conformance report, not left for a
+   user to discover.
+
+## Consequences / required refactors
+
+The backlog issues that carry this direction:
+
+- **Extract a runtime-agnostic core** (#500). The engine logic currently expressed
+  in shell (`scripts/telemetry/lib/*`) must be factored so its policy — event
+  canonicalization, redaction, attribution precedence, transport routing — is a
+  reusable port with at least a shell binding (today) and a language binding
+  (first framework adapter). No new policy may be added to an adapter that isn't
+  in the core.
+- **The artifact/state store becomes a pluggable port** (#501). Trust bundles,
+  delivery records, and state projection are written today against a filesystem +
+  git + Console assumption. For embedded agents that seam must be an interface
+  (local-fs, git, Console-remote, customer-supplied) so the engine backend is
+  swappable without touching adapters. This is the storage-port dependency of the
+  Console-as-backend rule (3).
+- **An adapter conformance suite** (#502) makes rule 5 checkable — one shared spec
+  every adapter (harness or framework) must pass, with explicit gap declarations.
+- **A first framework adapter proves the model** (#503). AWS Strands (the
+  non-terminal runtime that motivated this) is the reference in-process adapter:
+  it must emit canonical events in-process, honor redaction without a shell, and
+  pass the conformance suite. Its explicit callouts define the template for "what
+  a framework cannot do that a harness can."
+- **`runtime-hook-surface.md` is promoted from a harness spec to the adapter
+  contract** every adapter category conforms to.
+
+## Rationale
+
+The owner's model — "harness adapters and framework adapters would work in a very
+similar if not exactly the same way, such that a Flow or Flow-Agent-Kit
+implementation is consistent across development workflows and customer agent
+implementations" — only holds if there is a single engine and the runtimes are
+adapters over it. The alternative (per-runtime reimplementations that happen to
+agree) drifts the moment two runtimes are maintained by different hands, which is
+precisely the failure the numbered-ADR redesign already diagnosed elsewhere in
+this portfolio. DRY here is not a style preference; it is what makes "Flow behaves
+the same everywhere" a checkable property (rule 5) instead of a marketing claim.
+
+Making Console the remote backend for embedded agents (rule 3) is the same
+git-authoritative / console-projection split already ratified for trust retention;
+it costs nothing new conceptually and turns the dogfood console into the customer
+product surface. The cooperative-vs-authoritative split (rule 4) is the only
+honest enforcement story for code running in a process we do not own, and it is
+already how delivery reconciliation works — so embedding does not weaken the trust
+model, it inherits it.
+
+The explicit-callout requirement is the guard against the seductive failure mode:
+quietly letting a framework adapter skip a Flow feature because it was hard,
+leaving customers with an inconsistent product and no signal. A conformance report
+that names the gap keeps the promise of consistency honest.
+
+## Open questions
+
+- **Language of the first extracted core port** (TypeScript is the source-policy
+  default; the shell core stays as a binding). Tracked in the extract-core issue.
+- **Conformance-suite substrate** — reuse the existing `evals/integration`
+  harness vs a new adapter-conformance package.
+- **Storage-port interface shape** and whether the Console-remote binding reuses
+  the existing telemetry ingest or a dedicated port.
+
+These are implementation decisions for the linked backlog; the direction above is
+the fixed part.

package/docs/decisions/index.md

@@ -15,6 +15,7 @@ Numbered ADRs under `docs/adr/` are frozen history and are not listed here.
 | [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 |
+| [embeddable-engine](./embeddable-engine.md) | needs-decision | Embeddable engine and adapter model |
 | [flow-flow-agents-boundary](./flow-flow-agents-boundary.md) | needs-decision | Flow / Flow Agents boundary |
 | [flow-kit](./flow-kit.md) | needs-decision | Flow Kit |
 | [flow-skill-kit-tool-boundary](./flow-skill-kit-tool-boundary.md) | needs-decision | Flow / Skill / Kit / Tool boundary |
@@ -30,7 +31,8 @@ Numbered ADRs under `docs/adr/` are frozen history and are not listed here.
 | [promotion-gate](./promotion-gate.md) | current | Promotion gate |
 | [standing-directives](./standing-directives.md) | current | Standing directives |
 | [three-hard-boundary-model](./three-hard-boundary-model.md) | needs-decision | Three-hard-boundary model |
+| [trust-ledger-retention](./trust-ledger-retention.md) | needs-decision | Trust-ledger retention and console-as-projection |
 | [trust-reconcile](./trust-reconcile.md) | current | Trust-reconcile and delivery reconciliation |
 | [typescript-source-policy](./typescript-source-policy.md) | current | TypeScript-first source policy |
-| [workflow-enforcement](./workflow-enforcement.md) | needs-decision | Workflow Enforcement |
+| [workflow-enforcement](./workflow-enforcement.md) | current | Workflow Enforcement |
 | [workflow-trust-state](./workflow-trust-state.md) | needs-decision | Workflow trust state |

package/docs/decisions/trust-ledger-retention.md

@@ -0,0 +1,88 @@
+---
+status: needs-decision
+subject: Trust-ledger retention and console-as-projection
+decided: 2026-07-07
+evidence:
+  - 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
+  - kind: adr
+    ref: docs/adr/0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md
+  - kind: doc
+    ref: docs/implementing-trust-reconciliation.md
+  - kind: issue
+    ref: kontourai/console#118
+  - kind: issue
+    ref: kontourai/console#125
+  - kind: issue
+    ref: kontourai/flow-agents#463
+  - kind: issue
+    ref: kontourai/flow-agents#73
+---
+# Trust-ledger retention and console-as-projection
+
+> Status: **needs-decision** (proposed direction (shaped with Brian Anderson, 2026-07-07). Not yet
+> fully built. Ratify + carry forward as ADR on implementation.
+
+**Decision.** Git is the **authoritative store** for trust bundles and delivery
+records; the Console (and any hosted DB projection) is a **rebuildable, queryable
+projection** over them, never the source of truth. Three rules follow:
+
+1. **Two stores, two retention tiers.** The authoritative bundle is committed
+   (`delivery/<slug>/trust.bundle` + checkpoint) and pinned to the merge commit —
+   permanent, distributed, surviving any console outage. The console DB keeps a
+   projection: **coarse audit records** (bundles, decisions, gate/claim outcomes)
+   retained long; the **fine-grained raw telemetry firehose** kept for a short
+   window and rolled up into aggregates. Retention in the projection is a **cost**
+   decision, not a **correctness** one.
+
+2. **"Needs attention" is a view-filter, never a delete-sweep.** An item leaves
+   the operational attention set when it reaches a terminal state or ages past a
+   recency cutoff — the underlying record is retained, it just stops surfacing as
+   actionable. Deleting audit history to quiet a dashboard is a category error.
+
+3. **The gate fires at PR time; post-merge the bundle is an audit record.** A
+   bundle seals to the work-commit and tolerates lag (the ancestor check + fresh
+   CI re-run absorb later commits); it is not regenerated per push. After a
+   (squash) merge it rides into the merge commit as a committed file and becomes
+   provenance, not enforcement. See `docs/implementing-trust-reconciliation.md`.
+
+**Rationale.** "Console isn't the source of truth" is the *enabling* property, not
+a caveat: because git holds the authority, the projection is free to be pruned,
+tiered, or rebuilt for cost/perf without losing anything. This dissolves the
+tension between "keep an auditable delivery history" and "don't let a dashboard
+fill with days-old noise" — they are different concerns (retention vs. attention)
+that were previously conflated in one store. Observed data motivates the tiering:
+in one live snapshot the coarse audit table held ~38 rows while the raw
+telemetry-event table held ~30,000 — bundles are not what grows; the event stream
+is.
+
+**A "stale" bundle is a presentation problem, not a data problem.** A bundle is an
+immutable dated receipt ("verified this way at commit X"); it never becomes
+*wrong*, only misleading if surfaced as *current* truth. The query layer answers
+"true now?" from latest-state-per-subject and "true at commit X?" from the bundle.
+
+**Consequences / what to build.**
+
+- **Reframe the console "janitor" ([console#125]) from reaper to attention
+  view-filter**: terminal-state + recency cutoff over the operating-state
+  projection, with no deletion of underlying events. (Today the gap is
+  structural: there is no terminal-close/expiry event type, so nothing ever
+  leaves the active set — a process that stops emitting without a terminal status
+  flags as "long-running / needs attention" forever.)
+- **Make the projection genuinely rebuildable** ([flow-agents#463],
+  [flow-agents#73]): add a backfill/import that re-hydrates the console from the
+  committed `delivery/*/trust.bundle` files across repos. Until this exists, "the
+  DB is just a cache of git" is false in practice — a wipe/restart loses
+  queryability until producers re-push (observed 2026-07-07: a hosted-DB wipe
+  required a manual service restart and had no re-hydration path).
+- **Add retention + rollup for raw telemetry** (relates to the console noise
+  cleanup, [flow-agents#7-equivalent]): keep raw events N days, keep aggregates
+  long.
+- **Trust-bundle registry** ([console#118]) is the research home for org-scoped
+  retention, sharing, and third-party verification of the ledger.
+
+**Non-goals.** This decision does not change the layered-defense posture of ADR
+0017/0020/0022, the PR-time gate semantics, or claim classification. It adds the
+retention/projection design layer on top.

package/docs/decisions/workflow-enforcement.md

@@ -1,18 +1,40 @@
 ---
-status: needs-decision
+status: current
 subject: Workflow Enforcement
-decided: 2026-07-03
+decided: 2026-07-10
 evidence:
   - kind: adr
     ref: docs/adr/0001-flow-agents-consumes-flow.md
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/438
+  - kind: session-archive
+    ref: .kontourai/flow-agents/builder-enforcement-remediation/builder-enforcement-remediation--pull-work.md
 ---
 # Workflow Enforcement
 
-This subject has provenance in frozen ADR history ([0001-flow-agents-consumes-flow.md](../adr/0001-flow-agents-consumes-flow.md)) but no living
-decision has been ratified yet under the topic-keyed decision registry
-(`context/contracts/decision-registry-contract.md`). This stub records that the
-subject is open and links the frozen ADR(s) as provenance; it is not a decision.
+**Decision.** A new Workflow Run always starts at the first step declared by its canonical
+Flow Definition. A caller cannot choose a later starting step, and metadata such as an ad-hoc
+reason cannot grant that authority. Flow-native accepted exceptions may satisfy a named gate in
+an existing run; they do not authorize skipping the prefix that precedes that gate.
 
-When a living decision is ratified for workflow enforcement, update this
-file's `status` to `current`, add rationale, and keep the `adr` evidence
-links as provenance for the history that led here.
+Recovery resumes persisted run state rather than creating a replacement run at an arbitrary
+step. The recovered state must validate against the canonical definition identity and preserve
+its transitions, gate outcomes, attached evidence, and accepted exceptions. An import surface,
+when provided, must validate the same complete durable record before making it active; it is not
+a step-selection escape hatch.
+
+Direct primitives remain valid outside a product Workflow Run. For example, standalone
+`plan-work` may execute with its own primitive contract, but it must not stamp or report itself
+as a completed `builder.build` prefix. A request that intends the Builder Kit product flow must
+enter through `pull-work`, then `design-probe`, before planning.
+
+**Rationale.** The Flow Definition is the executable ordering authority. Allowing callers to
+self-declare a later step makes every upstream gate advisory and lets the artifact being created
+justify its own creation. Separating standalone primitives from product-flow runs preserves
+useful composability without weakening ordered workflows.
+
+**Consequences.** `ensure-session --flow-id builder.build --step-id plan` is invalid for a new
+run, even with `--ad-hoc-reason`. Existing run recovery is identified by durable run identity,
+not by a reason string. Refusal must happen before session files, assignment claims, or other
+side effects. Builder skills must route productized work through the declared prefix and describe
+direct primitive use as standalone.

package/docs/fixture-ownership.md

@@ -17,13 +17,16 @@ run `npm run validate:source --` and `npm run fixture:retirement-audit --`.
 | `evals/fixtures/backlog-provider-settings` | settings precedence fixtures | `evals/integration/test_effective_backlog_settings.sh` | Keep while backlog provider settings resolution supports global defaults and project overrides. |
 | `evals/fixtures/builder-kit-workflow-state` | Builder Kit workflow-state fixtures | `evals/static/test_workflow_skills.sh` | Keep while Builder Kit state contract and resume behavior are documented in workflow skill contracts. |
 | `evals/fixtures/console-learning-projection` | console learning projection fixtures | `evals/integration/test_console_learning_projection.sh` | Keep while learning projection supports correction and open-route examples. |
+| `evals/fixtures/economics` | per-run kit-economics record fixtures (#349): a transcript with .message.usage blocks, state.json/acceptance.json/critique.json join sources, a session.usage event, and the golden expected kontour.console.economics record | `evals/integration/test_economics_record.sh` | Keep while the `kontour.console.economics` v0.1 record contract (docs/specs/economics-record-contract.md) is enforced; the golden proves cost-from-transcript, defects-from-critique, verdict-from-state, and the R7 co-required guard. |
 | `evals/fixtures/flow-kit-repository` | Flow Kit repository contract fixtures | `evals/integration/test_flow_kit_repository.sh`, `evals/integration/test_local_flow_kit_install.sh`, `evals/integration/test_runtime_adapter_activation.sh`, `evals/integration/test_activate_npx_context.sh`, `evals/integration/test_flow_kit_install_git.sh`, `evals/static/test_workflow_skills.sh` | Keep valid and invalid cases paired with the Flow Kit repository contract. |
 | `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/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 | `evals/integration/test_usage_cost.sh`, `evals/integration/test_telemetry_usage_pipeline.sh` | Keep while telemetry.sh's Stop-hook usage pipeline (usage_parse_transcript / usage_model_from_transcript_usage) is proven against a hermetic multi-model transcript 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/implementing-trust-reconciliation.md

@@ -0,0 +1,129 @@
+# Implementing Trust Reconciliation Correctly
+
+> Status: DRAFT for review (not yet a merged doc). Companion to
+> ADR 0017 (anti-gaming trust/security model), ADR 0020 (reconcile manifest +
+> claim classification), and ADR 0022 (fail-closed delivery reconciliation).
+
+This guide is the "how to build it without re-breaking it" companion to the
+trust ADRs. Every principle below either drew blood in a real delivery or is
+load-bearing config in `.github/workflows/trust-reconcile.yml`. If you are
+porting this pattern to another repo/org, read this first.
+
+## The one sentence to internalize
+
+**The trust gate fires at PR time; after merge, the same bundle becomes an
+audit record, not a gate.**
+
+That single framing decides where the check lives and what the artifact is
+_for_ at each stage:
+
+- **At PR time** the reconcile job is a required, admin-enforced status check.
+  It is the thing that prevents a bad merge.
+- **After merge** the committed bundle is a dated, immutable receipt of what was
+  claimed and how it was verified — provenance, not enforcement.
+
+Get this wrong and you either gate on the post-merge `main` push (which either
+no-ops or falsely fails — see §2) or you misjudge what the bundle is worth once
+the work has landed.
+
+## Gate mechanics (the non-obvious CI gotchas)
+
+### 1. CI must re-run verification fresh; the bundle is only a divergence detector
+
+Never let the reconcile job _believe_ the bundle's "pass." Re-run the canonical
+verification in a clean CI environment the agent does not control, and use the
+bundle solely to detect divergence ("claimed pass, CI fails" / "claimed pass,
+command CI never ran" / "checkpoint-only bundle"). If your job reads the bundle
+and trusts it, you have built theater, not a gate. This is invariant #1.
+
+### 2. Fail closed on ambiguity — which forces full git history
+
+Ownership is decided by: _is the bundle's checkpoint commit a git-ancestor of
+(or equal to) the change's HEAD?_ (`git merge-base --is-ancestor`). On a shallow
+clone that check is unresolvable (exit 128) and MUST be treated as stale/fail,
+never pass. Therefore the reconcile job's checkout needs full history
+(`fetch-depth: 0`); the default shallow clone would falsely stale every
+legitimate bundle. Cause and required config travel together.
+
+### 3. Compare against the PR head SHA, not the synthetic merge SHA
+
+On a `pull_request` trigger, `github.sha` is GitHub's ephemeral merge commit
+(`refs/pull/N/merge`) — a commit no locally-sealed checkpoint ever stamps. Use
+`pull_request.head.sha` for the ownership comparison (fall back to `github.sha`
+only on `push`/`workflow_dispatch`, where it IS the real commit). Get this wrong
+and every bundle falsely stales. Silent footgun; call it out.
+
+### 4. Post-merge is a deliberate no-op — don't re-gate it
+
+A squash-merge creates a new commit with no git ancestry back to the
+feature-branch commit the checkpoint was sealed against. The reconcile job on
+the post-merge `main` push must be a loud no-op: gating already happened at PR
+time. Event-scope enforcement by trigger (`pull_request` gates; `push` to `main`
+observes). Do not "strengthen" this into a main-branch gate — it will only ever
+falsely fail on squash ancestry.
+
+### 5. Bundles seal to the work-commit and tolerate lag — don't regenerate per push
+
+The ancestor check (§2) plus the fresh re-run (§1) absorb new commits landing on
+top of a sealed checkpoint. Re-seal only when the _claim set_ materially
+changes, not on every commit. A bundle sealed at commit A is still valid at
+HEAD B as long as A is an ancestor of B. Building "regenerate on every push"
+flows is brittle and unnecessary.
+
+## Claims (and the single worst trap)
+
+### 6. Separate executable manifest commands from human-readable evidence — never `bash -lc` the prose
+
+If you build any re-check/backstop layer, it must reconcile ONLY against
+declared, runnable manifest commands. Attestation summaries, check descriptions,
+and acceptance-criteria prose are DATA, not code. Re-executing a check's
+_summary_ as `bash -lc "<summary text>"` yields garbage exit codes (2/127) and
+false "caught false-completion" alarms — noise that can mask a real failure
+sitting in the same run. This is the highest-frequency failure mode observed in
+practice; guard against it explicitly.
+
+### 7. `not_verified`-by-design is correct, not a gap
+
+An agent that cannot run a command-backed check should record it at
+`not_verified` with the exact reconcile-manifest command attached; CI runs it
+for real and reconciles. This is the auditor-session pattern. Do not let agents
+"helpfully" self-mark those `pass` — that reintroduces gaming. Require every
+command-backed claim to either name its exact manifest command or be typed
+`external` (an independent-review/human attestation that CI does not re-run).
+
+## Storage & retention (git is the authority)
+
+### 8. Two stores, two retention tiers
+
+Git is the authority: the bundle is committed (`delivery/<slug>/trust.bundle`)
+and pinned to the merge commit — permanent, distributed, survives any console
+outage. The database/console is a _rebuildable, queryable projection_ over those
+bundles. Keep coarse audit records (bundles, decisions, gate/claim outcomes)
+long; expire and roll up the fine-grained raw telemetry firehose. Retention here
+is a cost decision, not a correctness one.
+
+Rule of thumb from real data: one delivery ≈ a handful of small bundle rows; a
+single working session ≈ tens of thousands of raw tool-event rows. The bundles
+are not what grows — the raw event stream is. Prune the firehose; keep the
+ledger.
+
+### 9. Make the projection actually rebuildable from the authority
+
+If the console cannot re-hydrate itself from the committed bundles across repos,
+then "the DB is just a cache of git" is false in practice — a restart/wipe loses
+queryability until producers re-push. If you claim the projection is derived,
+build the backfill/import from `delivery/*/trust.bundle` that proves it.
+
+### Bonus: "stale as history" is not "stale as current state"
+
+A bundle is a dated receipt; it never becomes _wrong_, it only misleads if you
+surface an old one as _current_ truth. The query layer answers "true now?" from
+latest-state-per-subject and "true at commit X?" from the bundle. The same
+principle keeps the audit ledger from leaking into the operational
+"needs-attention" view — attention is a view-filter (terminal-state + recency),
+never a delete-sweep of history.
+
+## The tagline
+
+**The agent proposes, CI disposes, git remembers, the console indexes — and
+nothing re-executes prose.**

package/docs/index.md

@@ -4,24 +4,24 @@ title: Kontour Flow Agents
 
 # Flow Agents
 
-<p class="home-lede">A portable process-discipline layer for agentic work: canonical policies, evidence, and telemetry that compile to whatever hook surface a host exposes — coding-agent harnesses today, agent frameworks next. Flow Agents keeps work inspectable from idea to release readiness so you ask for outcomes and the system supplies the path, the state, the checks, and the proof.</p>
+<p class="home-lede">A portable process-discipline layer for agentic work: a kit-neutral engine for FlowDefinition interpretation, gates, runtime adapters, evidence, trust, and kit validation — plus opt-in kits such as Builder, Knowledge, Release Evidence, and Veritas Governance. Flow Agents keeps work inspectable so you ask for outcomes and the selected kit supplies the path, the state, the checks, and the proof.</p>
 
 <div class="value-grid">
   <section>
-    <strong>Four canonical policies</strong>
-    <span>Workflow steering, quality gate, stop-goal-fit, and config protection — each a canonical script under <code>scripts/hooks/</code> that compiles to the host's native hook format. Claude Code and Codex are the L2 reference implementations.</span>
+    <strong>Kit-neutral engine</strong>
+    <span>FlowDefinition interpretation, gates, runtime and harness adapters, SDK/evidence/trust primitives, and kit validation. The engine is not Builder Kit; Builder is one kit on top.</span>
   </section>
   <section>
     <strong>Survive context loss</strong>
-    <span>Durable sidecar state under <code>.flow-agents/</code> records acceptance criteria, evidence, critique, and handoff, so any session resumes from recorded state instead of chat memory.</span>
+    <span>Durable sidecar state under <code>.kontourai/flow-agents/</code> records acceptance criteria, evidence, critique, and handoff, so any session resumes from recorded state instead of chat memory.</span>
   </section>
   <section>
-    <strong>Evidence over confidence</strong>
-    <span>Hooks catch stop-short behavior, and important work ends with tests, browser checks, CI results, review findings, or an explicit <code>NOT_VERIFIED</code> gap — never just a confident summary.</span>
+    <strong>Tamper-evident trust</strong>
+    <span>Local capture is advisory and best-effort; the controlled CI re-run reconciles manifest commands and git diff as the authoritative anchor before evidence is treated as CI-verified.</span>
   </section>
   <section>
     <strong>Flow Kits — workflow + output shape</strong>
-    <span>A kit bundles a workflow and its opinionated output shape as a validated, installable unit. Two reference kits ship today: Builder Kit (shaping → delivery pipeline) and Knowledge Kit (gated store with five pipeline flows, pluggable adapters, and an Obsidian rendering layer). <a href="kit-authoring-guide.html">Author your own</a> using the same path.</span>
+    <span>A kit bundles flows and optional skills, docs, adapters, evals, and assets as a validated, installable unit. The catalog lists Builder, Knowledge, Release Evidence, and Veritas Governance; <a href="kit-authoring-guide.html">bring your own kit</a> through the same manifest path.</span>
   </section>
 </div>
 
@@ -45,7 +45,9 @@ flowchart LR
   Evidence -->|not verified| Plan
 ```
 
-Flow Agents adds the operating layer around the model: skills choose the right workflow, sidecars preserve state, hooks enforce the four canonical policies, and evals keep the bundle honest as it changes. The gate semantics underneath — definitions, runs, evidence, route-back — belong to <a href="https://kontourai.github.io/flow/">Kontour Flow</a>; Flow Agents compiles those policies to whatever hook surface a host exposes.
+Flow Agents adds the operating layer around the model: the engine preserves state, evaluates evidence, activates selected kits, renders structured kit triggers, and compiles canonical policies to host hooks. The gate semantics underneath — definitions, runs, evidence, route-back — belong to <a href="https://kontourai.github.io/flow/">Kontour Flow</a>.
+
+Kits supply the workflow. Builder and Knowledge are examples on the engine, not the engine itself. The built-in catalog also includes Release Evidence and Veritas Governance, both useful proof points that a kit can be agentless and still run through the same manifest and gate model.
 
 ## Process-discipline layer
 
@@ -78,7 +80,11 @@ Install into your workspace in one command:
 npx @kontourai/flow-agents init --runtime <your-agent> --dest .
 ```
 
-Where `--runtime` is `claude-code`, `codex`, `kiro`, `opencode`, or `pi`. The Builder Kit installs automatically and gives your agent two gated flows: `builder.shape` (idea → slices → filed work items) and `builder.build` (selected work item → design probe → plan → execute → verify → PR → learn).
+Where `--runtime` is `claude-code`, `codex`, `kiro`, `opencode`, or `pi`. Kits are opt-in. Activate Builder when you want its two gated flows: `builder.shape` (idea → slices → filed work items) and `builder.build` (selected work item → design probe → plan → execute → verify → PR → learn).
+
+```bash
+npx @kontourai/flow-agents init --runtime <your-agent> --dest . --activate-kit builder
+```
 
 Ask your agent to shape an idea:
 
@@ -110,6 +116,10 @@ Use fix-bug. Reproduce the problem, diagnose root cause, implement the fix, and
     <strong>Builder Kit Quick Start</strong>
     <span>Zero to a running, gated build flow in two minutes: install, shape an idea into a work item, build it through the builder.shape and builder.build flows, and see what the evidence gates do.</span>
   </a>
+  <a class="doc-card" href="architecture-engine-and-kits.html">
+    <strong>Engine and Kits</strong>
+    <span>The canonical split: product-neutral engine, opt-in kits, catalog + kit.json plugin model, structured workflow triggers, and marketplace metadata with no runtime privilege.</span>
+  </a>
   <a class="doc-card" href="workflow-usage-guide.html">
     <strong>Workflow Usage Guide</strong>
     <span>Every stage from shaping ideas to learning review, with example prompts and expected behavior.</span>