@kontourai/flow-agents 3.2.0 → 3.4.0

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/trust-reconcile.md

@@ -1,20 +1,53 @@
 ---
-status: needs-decision
+status: current
 subject: Trust-reconcile and delivery reconciliation
-decided: 2026-07-03
+decided: 2026-07-04
 evidence:
   - 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/coordination-guide.md
 ---
 # Trust-reconcile and delivery reconciliation
 
-This subject has provenance in frozen ADR history ([0020-trust-reconcile-manifest-and-claim-classification.md](../adr/0020-trust-reconcile-manifest-and-claim-classification.md), [0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md](../adr/0022-fail-closed-delivery-reconciliation-with-governed-exemptions.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.** Delivery is **fail-closed with governed exemptions**. `publishDelivery()` passes a
+bundle through three distinct, type-discriminated tiers — fail-soft (absent bundle tolerated) →
+shape gate (`InvalidBundleShapeError`, #356) → hold gate (`NotFreshHolderError`, #293) — and CI's
+reconcile is fail-closed by default (`onUnderivable: 'fail'`). A local `reconcile-preflight`
+mirrors CI's shape check via the *shared* `scripts/lib/reconcile-shape.js` so the two cannot
+drift. Concurrent deliveries are isolated by **per-session paths** (`delivery/<slug>/`, #379), and
+a checkpoint's `commit_sha` must be an ancestor of HEAD (seal-at-parent) so a stale bundle can't be
+replayed onto a moved branch. See the [coordination guide](../coordination-guide.md#how-delivery-itself-is-made-tamper-resistant).
 
-When a living decision is ratified for Trust-reconcile and delivery reconciliation, update this
-file's `status` to `current`, add rationale, and keep the `adr` evidence
-links as provenance for the history that led here.
+**Rationale.** The default must be safe: an underivable status fails the run rather than passing
+it, and a hard block on the shared publish path is applied only on high-confidence signals so it
+never false-blocks legitimate work. The frozen ADRs ([0020](../adr/0020-trust-reconcile-manifest-and-claim-classification.md),
+[0022](../adr/0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md)) hold the
+immutable rationale.
+
+## Implementation note (#356, iteration 1)
+
+A local, pre-push `reconcile-preflight` now exists (`workflow-sidecar reconcile-preflight
+<artifact-dir>`), reusing — never forking — the shape-classification logic CI's
+`scripts/ci/trust-reconcile.js` enforces via the shared `scripts/lib/reconcile-shape.js`
+module. `publishDelivery()` is itself fail-closed on shape-invalidity: it calls the same
+preflight before copying anything into `delivery/`, and refuses to publish a bundle that
+fails the shape check.
+
+The reduced-coverage degradation (trusting a session-local claim's self-reported status when
+CI-side re-derivation is unavailable) is a **LOCAL-preflight-only** opt-in
+(`sessionLocalShapeIssues(..., { onUnderivable: 'reduce' })`). CI's `trust-reconcile.js`
+always calls the shared function with `{ onUnderivable: 'fail' }` (also the function's
+default when no mode is given) and remains fail-closed: when status re-derivation is
+unavailable, every session-local pass-asserting claim becomes a `status-underivable`
+divergence and the run fails, exactly as before the shape logic was extracted.
+
+## Implementation note (#379, per-session delivery paths)
+
+Concurrent deliveries no longer contend on a shared `delivery/trust.bundle`. Each session writes
+its bundle under `delivery/<slug>/`; CI selects prefer-newest. Publishing must **restore sibling
+`delivery/<slug>/` directories** from `origin/main` before committing — after a soft-reset,
+`git add -A` would otherwise stage the deletion of other sessions' delivery dirs that the branch
+predates. This is the standard step in the publish sequence documented in the coordination guide.

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,14 +17,18 @@ 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/trust-reconcile-exploits` | WS8 trust-reconcile anti-gaming exploit fixtures (frozen negative regressions) | `evals/integration/test_trust_reconcile_negatives.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 | `evals/integration/test_trust_reconcile_mixed_bundle.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/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). |
 | `evals/fixtures/usage-feedback` | usage feedback import/outcome fixtures | `evals/integration/test_usage_feedback_import.sh`, `evals/integration/test_usage_feedback_outcomes.sh`, `evals/integration/test_usage_feedback_report.sh` | Keep while usage feedback import, outcome, and report flows accept JSONL fixture input. |
 | `evals/fixtures/veritas-governance-adapter` | Veritas governance adapter fixtures | `evals/integration/test_veritas_governance_adapter.sh` | Keep while the Veritas adapter supports pass, unconfigured, and secret-failure governance paths. |

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>
@@ -118,6 +128,10 @@ Use fix-bug. Reproduce the problem, diagnose root cause, implement the fix, and
     <strong>System Guidebook</strong>
     <span>The plain-language map of how Flow Agents is assembled and how it should feel to use.</span>
   </a>
+  <a class="doc-card" href="coordination-guide.html">
+    <strong>Parallel-Session Coordination</strong>
+    <span>Run many sessions against one repo without collisions: the two-stream model (liveness + assignment), the four guard points, the one hard publish fence, and how delivery defends itself.</span>
+  </a>
   <a class="doc-card" href="skills-map.html">
     <strong>Workflow Map</strong>
     <span>See the core skills, gates, artifacts, and route-back behavior.</span>