@kontourai/flow-agents 2.3.0 → 2.4.0

package/docs/adr/0022-fail-closed-delivery-reconciliation-with-governed-exemptions.md

@@ -0,0 +1,283 @@
+---
+title: "ADR 0022: Fail-Closed Delivery Reconciliation with Governed Exemptions"
+---
+
+# ADR 0022: Fail-Closed Delivery Reconciliation with Governed Exemptions
+
+**Date:** 2026-07-02
+**Status:** Proposed (shaped with Brian Anderson, 2026-07-02). Refines the Layer-2 CI
+anchor established in [ADR 0017](./0017-anti-gaming-trust-security-model.md) and hardened in
+[ADR 0020](./0020-trust-reconcile-manifest-and-claim-classification.md); does not change
+their layered-defense posture.
+
+---
+
+## Context
+
+`scripts/ci/trust-reconcile.js` — the external CI trust anchor ADR 0017 designed as the
+un-forgeable Layer-2 boundary — has run **fail-open on bundle absence** since it existed. Its
+own header states the behavior plainly:
+
+> "Fail-open on bundle absence: if no bundle is provided (and none auto-discovered at
+> `delivery/trust.bundle` or `delivery/trust.checkpoint.json`), only the fresh verify is
+> enforced."
+
+`discoverBundle()` (trust-reconcile.js:461-470) returns `null` when neither file exists, and
+`runTrustReconcile()` (trust-reconcile.js:529-533) treats `null` as "Step 2 does not apply" —
+Step 1 (fresh `npm run build && npm run eval:static`) still runs, but the actual anti-gaming
+machinery ADR 0017/0020 built — reconciling claimed-pass commands, catching laundering,
+catching never-captured claims, catching status-misassertion — never engages. The bundle is
+also **fail-soft to produce**: `publishDelivery()` (`src/cli/workflow-sidecar.ts`, documented
+in `delivery/README.md`) "does nothing if `trust.bundle` is absent (no crash, no error)." So
+the single condition that turns Layer 2 on or off — whether a bundle exists in the diff — is
+entirely under the delivering agent's control, and skipping it costs nothing and raises no
+alarm.
+
+That is a **kill switch by omission**: the agent, not an external anchor, decides whether the
+anchor applies. This directly contradicts ADR 0017's own threat model ("no purely-local
+control is airtight; the authoritative anchor must live somewhere the agent cannot
+pre-disable or post-forge") — except here the "pre-disable" move is not a local hack at all,
+it is simply *not delivering the artifact CI depends on to reconcile*, and CI accepts that
+silently.
+
+The historical record makes the exposure concrete, not theoretical: every PR before #265
+passed the Trust Reconcile lane trivially via bundle absence (`git log --follow --
+delivery/trust.bundle` shows the file's first appearance at #269, "veritas-governance kit —
+readiness→trust-bundle adapter with settled gate semantics" — the first live,
+capture-backed publish this repository ever produced). For roughly the entire history of the
+anchor, Layer 2 has been running Step 1 only.
+
+## Decision
+
+### 1. The predicate: every change is agent-delivered by default; identification signals inform, never gate
+
+Research into how agent-delivered changes are identifiable today turned up three candidate
+signals, and all three share the same flaw: **they are agent-writable, agent-omittable, or
+both.**
+
+| Signal | Where it lives | What it proves when present | Why it cannot gate alone |
+|---|---|---|---|
+| Runtime-session commit trailer (`Claude-Session: https://claude.ai/code/session_...`, and the analogous `Codex-Session:` / `Opencode-Session:` / `Pi-Session:` forms implied by the same runtime set the actor-identity resolver already enumerates, `scripts/hooks/lib/actor-identity.js:58-65` `RUNTIME_SESSION_ID_VARS`) | Free text the agent appends to its own commit message | Positive proof of agent delivery, attributable to a runtime/session | Purely self-asserted; an agent that wants to hide simply omits the trailer. No repo code enforces its presence today — it is observed convention (present on essentially every recent merged PR per `git log`), not a contract. |
+| `delivery/trust.bundle` / `trust.checkpoint.json` present in the diff | Committed transport path (`delivery/README.md`) | Positive proof of agent delivery (only `publishDelivery()` writes these) | This is the exact signal already in play — its **absence** is today's loophole. Trusting presence-only leaves absence exactly as exploitable as it is now. |
+| A "required marker" naming the delivering agent | Does not exist today | Would prove delivery mechanism | Nothing in the codebase currently stamps a required, non-omittable, non-agent-writable marker of agent origin. |
+
+No positive-detection signal can be the enforcement gate, because closing a gap that an agent
+controls by omission with *another* agent-controlled, omittable signal reproduces the same
+bug one layer up. The predicate therefore **inverts**: reconciliation applies to every change
+by default. The three signals above are retained as **diagnostic and audit inputs only** —
+they explain and attribute what the anchor already treats as agent-delivered; they do not
+decide whether it treats it that way. Concretely, per signal:
+
+1. **Commit trailer present** — logged by the reconciler (new `[trust-reconcile] identified:
+   runtime-session trailer '<trailer>' on <ref>` line) for audit; does not change the exit
+   path. Reconciliation already applies (default).
+2. **`delivery/trust.bundle` present** — unchanged from today: Step 2's existing
+   reconcile-against-manifest logic (ADR 0020) runs exactly as it does now.
+3. **Neither present (today's common "nothing shipped" case, indistinguishable from a
+   legitimate human-only PR)** — this is the ambiguous case, and it is the one the fail-open
+   bug lived in. It now resolves to **agent-delivered, fail closed**: `trust-reconcile.js`'s
+   bundle-absence branch gains a new check — is there a well-formed DECLARED marker (§2) in
+   scope for this ref? No → **new divergence type**, `bundle-required-no-declared-marker`,
+   job exits 1. Yes → exempted, see below.
+4. **Malformed DECLARED marker** (missing any of the four required fields, §2) — treated as
+   absent; falls through to case 3's fail-closed default, with a diagnostic naming the
+   missing field(s) so a human fixing it does not have to guess the schema.
+
+### 2. The DECLARED no-agent-delivery marker
+
+Humans and other legitimate non-agent changes (release-automation bots, direct maintainer
+pushes) opt out via a committed `delivery/DECLARED` JSON file — the same `delivery/`
+transport path `trust.bundle` already uses, so the anchor gains exactly one new
+auto-discovery target, not a new mechanism:
+
+```json
+{
+  "scope": "ref:release-please--branches--main",
+  "reason": "release-please automation PR; no agent delivery involved",
+  "approved_by": "briananderson1222",
+  "declared_at": "2026-07-02T00:00:00Z"
+}
+```
+
+All four fields are required for "well-formed." `scope` matches either a single ref/commit
+range or a durable pattern (author or branch-prefix match — see Consequences for why this
+matters for bot PRs). Presence and content are printed **loudly**, mirroring ADR 0020's
+`WAIVED:` convention exactly:
+
+```
+[trust-reconcile] DECLARED (no-agent-delivery): <scope> — <reason> (approved by <approved_by>, declared <declared_at>)
+```
+
+A DECLARED marker exempts **Step 2 only** (bundle-required enforcement). Step 1 (fresh
+verify) is never exempted by anything in this ADR — a human PR still has to build and pass
+static evals; only the anti-gaming reconcile step, which presumes an agent-produced bundle
+to reconcile against, is skippable, and only with attribution.
+
+`delivery/DECLARED` is added to `.github/CODEOWNERS` alongside the other verify-config and
+anchor paths (`/scripts/ci/`, `/package.json`, `/evals/run.sh`) it already lists — the same
+mitigation ADR 0017 Layer 4 uses for every other self-asserted, unauthenticated field
+(`approved_by` on a waiver has the identical shape and the identical residual; carried over
+here rather than re-solved).
+
+### 3. Layering: the governance kit issues and audits; the anchor enforces
+
+Per ADR 0017's own framing ("kits declare process; the anchor enforces"), exemption
+*issuance* and *audit* — the human-approval workflow, not the enforcement decision — belong
+in `kits/veritas-governance`, the kit this repository already stood up (#269, migrated #285)
+for exactly this class of "turn a governance verdict into gate evidence" concern. It ships
+today as a single flow/single gate (`flows/readiness-check.flow.json`: step `readiness` →
+gate `gate-check-gate`, requiring a verified `software-readiness-verdict` trust.bundle
+claim). This ADR specifies a second flow of the identical shape:
+
+- **`flows/exemption-issuance.flow.json`** — agentless, K0, mirroring
+  `readiness-check.flow.json`'s structure: step `request` → gate `human-approval-gate`
+  (`expects` a trust.bundle claim of `claimType: "no-agent-delivery-exemption-approval"`,
+  `subjectType: "delivery-scope"`, `accepted_statuses: ["verified"]` — satisfiable only by
+  human-attached evidence, the same pattern `gate-check-gate` uses for the readiness verdict)
+  → step `issue`, which writes the resulting `delivery/DECLARED` file once the gate passes.
+- **`exemption-usage-review`** — a periodic audit skill/flow that walks
+  `delivery/DECLARED` history (`git log --follow -- delivery/DECLARED`) merged in a review
+  window and surfaces every standing exemption (scope, reason, approver, age) for owner
+  re-confirmation — process visibility, not enforcement.
+
+The load-bearing property: **uninstalling `veritas-governance` must never weaken
+enforcement.** `trust-reconcile.js`'s marker-reading logic — auto-discover
+`delivery/DECLARED`, require all four fields, print the DECLARED line, exempt Step 2 only —
+lives in `scripts/ci/` (already CODEOWNERS-protected, already anchor-owned) and has zero
+runtime dependency on the kit. A human can hand-author a compliant `delivery/DECLARED`
+without the kit installed; they simply lose the guided issuance flow and the periodic-review
+tooling. This is the concrete test of the layering claim, not just its statement.
+
+### 4. Breaking change — no legacy fallback
+
+This changes the exit code of every future agent-delivered change (which, under the inverted
+default, is every change unless explicitly DECLARED otherwise) that does not ship a
+`delivery/trust.bundle`. There is no flag, no grace window, no opt-in period — matching the
+owner's explicit direction to document this as a breaking change rather than carry a legacy
+fail-open path indefinitely. Concretely:
+
+- Any PR that today merges by passing Trust Reconcile "trivially via absence" starts failing
+  the moment this ships, until it either (a) publishes a bundle via the existing
+  `publishDelivery()` path, or (b) carries a DECLARED marker in scope.
+- **Repos consuming `.github/workflows/trust-reconcile.yml` as a template** (ADR 0017 §
+  Consequences names this the intended reuse path) must pin to the pre-ADR-0022 commit until
+  ready, then adopt in one migration PR that either wires bundle publication into their
+  delivery flow or authors an initial `delivery/DECLARED` covering their known non-agent
+  actors (see Consequences below for the concrete bot case).
+
+## Scope boundaries
+
+**`hasBuild` fail-open in `stop-goal-fit.js` (line 185; `loadActiveFlowStep`,
+lines 305-316) is the same absence-controls-enforcement asymmetry in miniature — it is
+explicitly out of scope for this ADR.** One-line rationale: it is a Layer-1, local,
+**non-authoritative** fallback (its own comment: "Fail-open: returns null when build/ is
+absent... the caller treats null as 'no active FlowDefinition' and falls back to the
+`workflow.*` path") — Layer-1 heuristics were explicitly frozen by
+[ADR 0018](./0018-freeze-local-shell-heuristics.md), which routes *all* new enforcement
+concerns to the external anchor rather than adding local surface. This ADR *is* that
+external-anchor hardening; extending the local `hasBuild` check would both violate the
+freeze and buy nothing, since a determined agent controls its own local `build/` presence
+regardless of what the local heuristic does. Cross-ref: ADR 0017 §Layer 1 vs Layer 2;
+ADR 0018 §Decision.
+
+## Residuals (honest — ADR 0017 §Residuals / ADR 0020 §Residuals style; a bar-raiser, not a wall)
+
+- **Forged human attribution.** `approved_by` on `delivery/DECLARED` is free text, not bound
+  to an authenticated identity — the identical residual ADR 0020 already carries for
+  `WAIVED`'s `approved_by`, and the identical mitigation: the loud, un-suppressible DECLARED
+  line plus CODEOWNERS review, not identity attestation. Not solved here; explicitly
+  inherited.
+- **Shared credentials collapse the human/agent distinction.** An agent operating under
+  commit/push rights indistinguishable from a human collaborator (a shared PAT, a service
+  account with CODEOWNERS review rights) can author and approve its own DECLARED marker. This
+  is ADR 0017's already-named "trust-the-humans boundary... documented, not closed" —
+  unchanged by this ADR.
+- **Identification signals undercount, they do not overcount.** Because the enforcement
+  default no longer depends on the commit-trailer or delivery-artifact signals (§1), an agent
+  can still freely omit both. Any future audit tooling built on those signals ("which PRs
+  were agent-delivered") will therefore undercount attribution — this ADR fixes the
+  enforcement default, not attribution completeness.
+- **CI checkout depth limits trailer detection today.** `trust-reconcile.yml`'s
+  `actions/checkout` step does not currently widen fetch depth to cover a PR's full commit
+  range, so the commit-trailer diagnostic in §1's table is aspirational for CI-side logging
+  until checkout is widened. This does not block the ADR: the trailer is diagnostic-only,
+  never gating, per §1.
+- **Bot/automation PRs need a durable, not per-PR, DECLARED scope**, or every dependabot /
+  release-please PR starts failing the moment this ships (see Consequences). `scope`
+  supports author/branch-pattern matching for exactly this reason, but the pattern-matching
+  logic itself is new surface this ADR specifies and a future implementation must get right;
+  a narrow pattern match is itself a residual surface (a scope pattern that is too broad
+  re-opens a blanket exemption).
+
+## Consequences
+
+- Trust Reconcile stops being satisfiable by doing nothing. The anti-gaming machinery ADR
+  0017/0020 built (reconcile, laundering screen, status re-derivation, `ATTESTED`/`WAIVED`
+  disclosure) now actually runs on every agent-delivered change by default, closing the gap
+  the historical record (`delivery/trust.bundle`'s first appearance at #269) shows has been
+  open for the anchor's entire prior history.
+- **`dependabot.yml` and `release-please.yml`-authored PRs** (both present in this repo's
+  `.github/`) will start failing Trust Reconcile the moment this ships unless a durable,
+  author/branch-scoped `delivery/DECLARED` marker is authored for each before rollout — a
+  concrete, non-hypothetical migration item, not a theoretical edge case.
+- `veritas-governance` gains a second flow and a periodic-review surface; its "unverified,
+  not first-party-allowlisted" trust status (per its own README) is unaffected by this ADR —
+  the anchor-side enforcement this ADR specifies works whether or not the kit is installed.
+- `.github/CODEOWNERS` gains one new protected path (`/delivery/DECLARED` or a `/delivery/`
+  pattern narrow enough to exclude `trust.bundle`/`trust.checkpoint*`, which remain
+  agent-written).
+- Downstream repos treating `trust-reconcile.yml` as a template inherit a breaking change on
+  adoption, not a gradual one — flagged explicitly per the owner's direction (§ Decision 4).
+
+## Alternatives Considered
+
+- **Positive-detection predicate (trust the commit trailer or bundle presence as the sole
+  signal).** Rejected in §1: any agent-writable/omittable positive signal reproduces the
+  fail-open bug at one remove — an agent that wants to evade omits the signal being checked,
+  exactly as it omits the bundle today.
+- **Extend `hasBuild` / Layer-1 heuristics to close the analogous gap locally.** Rejected —
+  violates the ADR 0018 freeze and cannot be authoritative regardless (Scope boundaries,
+  above); the correct fix lives in Layer 2, which is what this ADR does.
+- **Grace period / opt-in flag before flipping the default.** Rejected per the owner's
+  explicit direction: document as a breaking change, do not carry a legacy fail-open path.
+- **Require cryptographic (Sigstore-signed) attribution for the DECLARED marker instead of
+  free-text `approved_by`.** Deferred, not rejected — this is exactly the Assurance-profile
+  remedy ADR 0020's Residuals names for the identical `WAIVED` gap ("extending Layer 3's
+  keyless-Sigstore minting... to individual human-attestation events"). It does not exist yet
+  for waivers; inventing it first for DECLARED markers alone would be inconsistent scope.
+  When/if that Assurance profile lands, both `WAIVED` and `DECLARED` should adopt it together.
+- **Put exemption enforcement inside `veritas-governance` itself (kit owns both issuance and
+  enforcement).** Rejected — this is precisely the layering ADR 0017 already establishes
+  ("kits declare process; the anchor enforces") and the explicit requirement that uninstalling
+  a kit must never weaken enforcement; enforcement logic must live anchor-side regardless of
+  which kit (if any) is installed.
+
+## References
+
+- [ADR 0017: The Anti-Gaming Trust Security Model](./0017-anti-gaming-trust-security-model.md)
+  — the layered defense this ADR refines Layer 2 of; the threat-model framing ("no purely-local
+  control is airtight") this ADR's problem statement is a direct instance of.
+- [ADR 0018: Freeze the Local Shell-Parsing Heuristics](./0018-freeze-local-shell-heuristics.md)
+  — the freeze that puts the `hasBuild` miniature explicitly out of scope and routes this
+  ADR's fix to the external anchor instead.
+- [ADR 0020: Trust-Reconcile Manifest, Claim Classification, and Waivers](./0020-trust-reconcile-manifest-and-claim-classification.md)
+  — the `WAIVED`/`ATTESTED` disclosure conventions this ADR's `DECLARED` marker mirrors; its
+  Residuals section (`approved_by` unauthenticated, mitigated by CODEOWNERS + the loud log
+  line) is inherited verbatim for `DECLARED`.
+- `scripts/ci/trust-reconcile.js` (`discoverBundle`, lines 461-470; `runTrustReconcile`
+  bundle-absence branch, lines 529-533) — the code this ADR changes.
+- `src/cli/workflow-sidecar.ts` `publishDelivery()` / `delivery/README.md` — confirms the
+  bundle is fail-soft to produce today, the root of the omission loophole.
+- `scripts/hooks/lib/actor-identity.js` (`RUNTIME_SESSION_ID_VARS`, lines 58-65) — the
+  runtime enumeration the commit-trailer signal's naming is grounded in.
+- `scripts/hooks/stop-goal-fit.js` (`hasBuild`, line 185; `loadActiveFlowStep`, lines
+  305-316) — the Layer-1 miniature explicitly scoped out.
+- `kits/veritas-governance/` (`kit.json`, `flows/readiness-check.flow.json`,
+  `docs/README.md`) — the existing kit shape §3's `exemption-issuance.flow.json` mirrors.
+- `.github/CODEOWNERS` — the existing self-asserted-field mitigation pattern extended to
+  `delivery/DECLARED`.
+- `.github/dependabot.yml`, `.github/workflows/release-please.yml` — the concrete bot-PR
+  migration case named in Consequences.
+- #274 — the issue this ADR resolves; #269 — the first live capture-backed bundle publish
+  cited in Context; #265 — the last PR to merge before that (i.e. the boundary of "every PR
+  before #265 passed Trust Reconcile trivially via absence").

package/docs/agent-system-guidebook.md

@@ -73,7 +73,7 @@ The hidden supports are:
 | “Keep going until nothing is left.” | Use hooks and workflow state to avoid stopping early, then continue through verification and docs. |
 | “Use subagents to critique.” | Delegate critique as report-only work, record findings, fix failures, and re-run verification. |
 | “Can we validate this on Flow Agents itself?” | Use Flow Agents artifacts, hooks, evals, and learning loops on Flow Agents itself. |
-| “What slug are we on?” | Resolve `.flow-agents/current.json`; do not depend on memory from chat. |
+| “What slug are we on?” | Resolve `.kontourai/flow-agents/current.json`; do not depend on memory from chat. |
 
 ## Mental Model
 
@@ -192,7 +192,7 @@ npm run workflow:sidecar -- current --format path
 npm run workflow:sidecar -- record-agent-event ...
 ```
 
-`ensure-session` creates or selects the workflow and writes `.flow-agents/current.json`. `current` resolves the active workflow path. `record-agent-event` lets parallel workers append progress to `agents/<agent-id>/events.jsonl` without guessing the slug.
+`ensure-session` creates or selects the workflow and writes `.kontourai/flow-agents/current.json`. `current` resolves the active workflow path. `record-agent-event` lets parallel workers append progress to `agents/<agent-id>/events.jsonl` without guessing the slug.
 
 This is the key answer to multi-agent coordination: agents should not rely on conversational memory for the current slug. The orchestrator resolves the active workflow and passes the path to delegates. Delegates append events. The orchestrator consolidates those events into root state, evidence, critique, and handoff.
 
@@ -320,7 +320,7 @@ flowchart LR
   Prompt --> Current --> State --> Handoff --> Evidence --> Action
 ```
 
-The agent should not reconstruct the session from memory. It should resolve the active workflow from `.flow-agents/current.json`, read the sidecars, and continue from the recorded next action. If evidence is missing, it should say `NOT_VERIFIED` or keep working. If critique is open, it should fix or route the finding. If everything is clean, it can deliver.
+The agent should not reconstruct the session from memory. It should resolve the active workflow from `.kontourai/flow-agents/current.json`, read the sidecars, and continue from the recorded next action. If evidence is missing, it should say `NOT_VERIFIED` or keep working. If critique is open, it should fix or route the finding. If everything is clean, it can deliver.
 
 ## One-Page Cheat Sheet
 

package/docs/agent-usage-feedback-loop.md

@@ -12,7 +12,7 @@ The loop has three parts:
 2. Sync quality outcomes from task artifacts, evals, release gates, or humans.
 3. Report usage and outcome metrics by repo, runtime, profile, prompt, skill, or task type.
 
-Quality outcomes are not inferred from raw telemetry alone. The CLI can automatically derive coarse outcomes from task artifacts such as `.flow-agents/<slug>/*.md`: `delivered` and `complete` become `success`, `failed` becomes `failure`, and optionally open artifacts can be recorded as `not_verified`. It does not invent `quality_score` or `human_minutes_saved`; those remain human/eval/release-gate facts.
+Quality outcomes are not inferred from raw telemetry alone. The CLI can automatically derive coarse outcomes from task artifacts such as `.kontourai/flow-agents/<slug>/*.md`: `delivered` and `complete` become `success`, `failed` becomes `failure`, and optionally open artifacts can be recorded as `not_verified`. It does not invent `quality_score` or `human_minutes_saved`; those remain human/eval/release-gate facts.
 
 ## Storage Defaults
 
@@ -158,7 +158,7 @@ Usage-only metrics can be computed from telemetry. Quality and value metrics req
 
 ### Project Dashboard
 
-Generate the local HTML dashboard. This syncs terminal task artifacts from `.flow-agents` into `.telemetry/outcomes.jsonl` before rendering:
+Generate the local HTML dashboard. This syncs terminal task artifacts from `.kontourai/flow-agents` into `.telemetry/outcomes.jsonl` before rendering:
 
 ```bash
 npm run usage-feedback -- dashboard --force
@@ -170,7 +170,7 @@ Sync artifacts without rendering the dashboard:
 
 ```bash
 npm run usage-feedback -- sync-artifacts \
-  --artifact-dir .flow-agents \
+  --artifact-dir .kontourai/flow-agents \
   --repo flow-agents \
   --profile-id codex-default \
   --prompt-id deliver-v1 \
@@ -185,7 +185,7 @@ npm run usage-feedback -- import-codex \
   --telemetry-dir .telemetry/repo-a \
   --source-id repo-a \
   --repo repo-a \
-  --profile-id codex-kdev \
+  --profile-id codex-builder \
   --prompt-id deliver-v1 \
   --skill-id deliver
 ```
@@ -213,7 +213,7 @@ npm run usage-feedback -- record-outcome \
   --runtime codex \
   --repo repo-a \
   --agent dev \
-  --profile-id codex-kdev \
+  --profile-id codex-builder \
   --prompt-id deliver-v1 \
   --skill-id deliver \
   --task-type delivery \
@@ -221,7 +221,7 @@ npm run usage-feedback -- record-outcome \
   --result success \
   --quality-score 5 \
   --human-minutes-saved 35 \
-  --evidence .flow-agents/agent-usage-feedback-loop/agent-usage-feedback-loop--deliver.md
+  --evidence .kontourai/flow-agents/agent-usage-feedback-loop/agent-usage-feedback-loop--deliver.md
 ```
 
 Generate a report:

package/docs/context-map.md

@@ -10,7 +10,7 @@ Generated by `npm run context-map`. Regenerate after changing agents, skills, sc
 
 - Start here when a session is long, resumed, or context-constrained.
 - Load only the specific skill, contract, schema, or doc that matches the task.
-- Treat `.flow-agents` as runtime state and `dist/` as generated output.
+- Treat `.kontourai/flow-agents` as runtime state and `dist/` as generated output.
 
 ## Repository Shape
 
@@ -29,7 +29,8 @@ Generated by `npm run context-map`. Regenerate after changing agents, skills, sc
 | scripts | canonical copy | Build, validation, hook, telemetry, workflow, and import/export utilities. |
 | skills | canonical copy | On-demand capability instructions and workflow primitives. |
 | dist | generated | Generated bundle exports. Do not edit by hand. |
-| .flow-agents | runtime | Cross-session workflow artifacts and sidecars. Not committed by default. |
+| .kontourai/flow-agents | runtime | Non-durable workflow artifacts, sidecars, and generated projections. Not committed by default. |
+| .flow-agents | durable local state | Explicit Flow Agents config/install state. Not a runtime artifact fallback. |
 
 ## Core Commands
 
@@ -38,7 +39,7 @@ Generated by `npm run context-map`. Regenerate after changing agents, skills, sc
 | Source tree | npm run validate:source |
 | Static suite | bash evals/run.sh static |
 | Integration suite | bash evals/run.sh integration |
-| Workflow artifacts | npm run workflow:validate-artifacts -- --require-sidecars --require-critique .flow-agents/<slug> |
+| Workflow artifacts | npm run workflow:validate-artifacts -- --require-sidecars --require-critique .kontourai/flow-agents/<slug> |
 | Workflow sidecars | npm run workflow:sidecar -- --help |
 | Claim lookup | npm run workflow:sidecar -- claim <id> <dir> |
 | Context map drift | npm run context-map:check |
@@ -46,11 +47,12 @@ Generated by `npm run context-map`. Regenerate after changing agents, skills, sc
 
 ## Workflow Sidecars
 
-Machine-readable workflow state lives beside Markdown artifacts in `.flow-agents/<slug>/`.
+Machine-readable workflow state lives beside Markdown artifacts in `.kontourai/flow-agents/<slug>/`.
 
 | Schema | Title | ID |
 | --- | --- | --- |
 | backlog-provider-settings.schema.json | Flow Agents Backlog Provider Settings | https://flow-agents.dev/schemas/backlog-provider-settings.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 |
 | 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 |
@@ -109,10 +111,10 @@ Primary tools: `npm run workflow:sidecar`, `npm run workflow:validate-artifacts`
 | tool-explore-patterns | kimi-k2.5 | 6 | Delegate to me for Pattern detection - identifies architectural patterns, frameworks, and coding conventions |
 | tool-explore-structure | kimi-k2.5 | 6 | Delegate to me to scout out the project structure - maps directory layout and identifies key folders in a codebase |
 | tool-explore-tests | kimi-k2.5 | 6 | Delegate to me to find and understand testing strategies - locates test files and understands testing strategy |
-| tool-planner | claude-sonnet-4.6-1m | 7 | Delegate to me for codebase analysis and execution planning. Explores code, identifies patterns and dependencies, and writes plan/sidecar artifacts under .flow-agents. No production file modifications. |
+| tool-planner | claude-sonnet-4.6-1m | 7 | Delegate to me for codebase analysis and execution planning. Explores code, identifies patterns and dependencies, and writes plan/sidecar artifacts under .kontourai/flow-agents. No production file modifications. |
 | tool-playwright | claude-sonnet-4.6-1m | 25 | Delegate to me for browser automation, testing, and debugging - loading real pages, testing navigation, checking accessibility via structured snapshots, evaluating scripts, and visual verification. Anything that would otherwise require a... |
 | tool-security-reviewer | claude-sonnet-4.6-1m | 7 | Delegate to me for security analysis. Checks OWASP Top 10, secrets detection, input validation, injection vulnerabilities, auth/authz, and rate limiting. Read-only analysis with shell for scanning tools. |
-| tool-verifier | claude-sonnet-4.6-1m | 8 | Delegate to me for implementation verification. Read-only + shell for source code; writes review/evidence artifacts under .flow-agents. Verifies acceptance criteria and produces PASS/FAIL/NOT_VERIFIED verdicts with evidence. No productio... |
+| tool-verifier | claude-sonnet-4.6-1m | 8 | Delegate to me for implementation verification. Read-only + shell for source code; writes review/evidence artifacts under .kontourai/flow-agents. Verifies acceptance criteria and produces PASS/FAIL/NOT_VERIFIED verdicts with evidence. No... |
 | tool-worker | claude-sonnet-4.6-1m | 1 | Delegate to me for writing and developing source code for a project. Works best when a detailed plan can be provided. NO access to web tools. Can be used in parallel for any coding tasks that require trusted access to the write and shell... |
 
 ## Optional Powers
@@ -125,7 +127,7 @@ Primary tools: `npm run workflow:sidecar`, `npm run workflow:validate-artifacts`
 ## Current Workflow State
 
 Runtime workflow state is excluded from the committed map.
-Regenerate locally with `npm run context-map -- --include-runtime` to include recent `.flow-agents` state.
+Regenerate locally with `npm run context-map -- --include-runtime` to include recent `.kontourai/flow-agents` state.
 
 ## Context Loading Rules
 

package/docs/decisions/decision-records.md

@@ -0,0 +1,57 @@
+---
+status: current
+subject: Decision records
+decided: 2026-07-03
+evidence:
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/310
+  - kind: session-archive
+    ref: .kontourai/flow-agents/decision-registry-shape/decision-registry-shape--idea-to-backlog.md
+  - kind: pr
+    ref: https://github.com/kontourai/flow-agents/pull/316
+---
+
+# Decision records
+
+New decisions are recorded as **topic-keyed living decision records** at
+`docs/decisions/<topic-slug>.md`, one file per decision subject. Numbered ADRs
+(`docs/adr/NNNN-*.md`) are frozen history and are never written for new
+decisions.
+
+## Decision
+
+- Topic files are keyed by decision **subject** slugs drawn from the CONTEXT.md
+  domain vocabulary; the vocabulary is the topic namespace. This removes ADR
+  numbering collisions and makes topic identity downstream of ubiquitous
+  language.
+- **Supersession is an edit** to the topic file. Contradicting appendices are
+  impossible by construction; the file always holds the current answer plus lean
+  rationale. `superseded_by` / `merged_into` tombstones cover the rarer case of a
+  subject moving or merging to another slug.
+- The context that led to a decision is **linked** to archived session artifacts,
+  PRs, and frozen ADRs via `evidence[]`, never inlined. This fixes ADR bloat;
+  promotion-as-retirement provides the archive.
+- **CONTEXT.md is the only external compatibility surface** (grill-with-docs
+  interop). The numbered-ADR file format is not adopted for new decisions — the
+  behavior is inherited, not the failure mode.
+- Existing ADRs are **frozen and indexed, never converted**; history stays
+  immutable provenance. (Freeze tooling is issue #314.)
+- Frontmatter is YAML validated by `schemas/decision-record.schema.json`
+  (`status`, `subject`, `decided`, `evidence[]`, and the relationship fields),
+  enabling machine health checks.
+- A generated `docs/decisions/index.md` (slug + one-liner) is referenced from
+  CONTEXT.md so retrieval-at-write matching has a cheap, always-loaded index.
+
+## Rationale
+
+Numbered ADRs accumulate contradictions (new decisions append rather than
+supersede), bloat (derivation context inlined with the decision), and numbering
+collisions at multi-contributor scale — observed across ~6 portfolio repos and
+owner-ratified as a redesign on 2026-07-03. Topic-keyed living records make the
+current answer to any settled question findable in one place, make supersession
+an edit rather than a contradicting appendix, and let multiple contributors work
+without colliding on sequence numbers.
+
+flow-agents is the first consumer: this record self-hosts the decision, and the
+full normative contract lives at
+`context/contracts/decision-registry-contract.md`.

package/docs/decisions/index.md

@@ -0,0 +1,14 @@
+---
+title: Decision Index
+---
+
+# Decision Index
+
+Generated by `npm run gen:decisions-index`. Do not edit by hand.
+Topic-keyed living decision records per `context/contracts/decision-registry-contract.md`.
+Numbered ADRs under `docs/adr/` are frozen history and are not listed here.
+
+| Topic | Status | Decision |
+| --- | --- | --- |
+| [decision-records](./decision-records.md) | current | Decision records |
+| [promotion-gate](./promotion-gate.md) | current | Promotion gate |

package/docs/decisions/promotion-gate.md

@@ -0,0 +1,52 @@
+---
+status: current
+subject: Promotion gate
+decided: 2026-07-02
+evidence:
+  - kind: issue
+    ref: https://github.com/kontourai/flow-agents/issues/312
+  - kind: session-archive
+    ref: .kontourai/flow-agents/decision-registry-shape/decision-registry-shape--idea-to-backlog.md
+  - kind: doc
+    ref: docs/workflow-artifact-lifecycle.md
+---
+
+# Promotion gate
+
+Archiving a delivered session is **gated on** promoting its durable residue. The
+sequence is `final acceptance -> promote -> archive`; durable-residue extraction
+is the archival act, not a parallel checklist chore.
+
+## Decision
+
+- The sidecar `promote` step records **what was promoted where** and writes a
+  **promotion claim** into the session `trust.bundle`. The claim is
+  **session-local by construction** — check kind `policy`, evidence type
+  `policy_rule`, no command / `execution.label` — so it needs **no new
+  reconcile-manifest entry** and can **never** become a `[not-run]` /
+  unbacked-command divergence at CI `trust-reconcile`. The reconciler classifies
+  it session-local and accepts it as an ATTESTED claim.
+- The claim's evidence refs are the **durable doc paths written**
+  (`docs/decisions/<slug>.md`, `CONTEXT.md`, `docs/learnings/*`, …); each is
+  verified to exist on disk at record time (a missing path fails loud) and is
+  mirrored into an auditable `promotion.json`. The claim is detected by the
+  archive gate and validators via `claim.metadata.promotion`.
+- An **explicit empty-promotion** path (`promote --none --reason "<why>"`) records
+  an auditable no-residue claim, so "nothing needed promoting" is a recorded
+  decision rather than a silent skip.
+- `workflow-artifact-cleanup-audit` classifies a **delivered/accepted** session
+  that reached a terminal shape **without** a promotion claim as a
+  `cleanup_candidate` (archive blocked) with a remedy naming the `promote` step;
+  **with** the claim (real residue or `--none`) it stays `terminal_done`.
+  Already-`archived` sessions are past the gate and are never re-flagged (no
+  backfill of historical archives).
+
+## Rationale
+
+Docs-promotion was a Final Acceptance checklist item done inconsistently; the
+2026-07 archival sweep retired ~40 sessions whose promotion had happened ad hoc.
+Making promotion **structural** — a claim the archive classifier checks — means no
+delivered work is retired without its knowledge extracted. Reusing the existing
+trust.bundle / stop-gate machinery (rather than a parallel mechanism) keeps the
+signal visible to validators without new manifest surface, and the session-local
+claim shape guarantees the gate can never masquerade as a CI-reconcilable command.

package/docs/developer-architecture.md

@@ -106,7 +106,7 @@ flowchart TB
   Evidence -->|missing evidence| Plan
 ```
 
-**Current state:** The durable handoff surface is a pair of human-readable Markdown artifacts and machine-readable JSON sidecars under `.flow-agents/<slug>/`. Verification, critique, release, and learning records are explicit artifacts rather than hidden chat memory.
+**Current state:** The durable handoff surface is a pair of human-readable Markdown artifacts and machine-readable JSON sidecars under `.kontourai/flow-agents/<slug>/`. Verification, critique, release, and learning records are explicit artifacts rather than hidden chat memory.
 
 **Programmatic API (for native hosts):** The canonical sidecar writer/validator is importable as a library, not only via the `flow-agents-workflow-sidecar` CLI. A host that records workflow evidence natively should import the package root rather than reimplement validated read / merge / write:
 

package/docs/fixture-ownership.md

@@ -22,6 +22,9 @@ run `npm run validate:source --` and `npm run fixture:retirement-audit --`.
 | `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/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/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/flow-kit-repository-contract.md

@@ -30,7 +30,7 @@ npm run kit -- status example-kit --dest /path/to/installed-flow-agents
 npm run kit -- activate --dest /path/to/installed-flow-agents --format json
 ```
 
-`--dest` is the installed bundle or workspace root. When omitted, the command uses the current working directory. Tests and automation should pass a temp destination; the command does not need to write to a user home directory.
+`--dest` is the installed bundle, workspace root, isolated Codex home, or test fixture destination. When omitted, Codex-oriented kit commands install into the normal Codex home: `CODEX_HOME` when it is set, otherwise `~/.codex`. Pass `--dest` to override that destination for workspace installs, isolated homes, or tests.
 
 Install always runs the same repository validation used by `npm run validate:source -- --kit` before it creates or updates local install state. A validation failure exits nonzero and leaves the destination registry and copied kits unchanged.
 
@@ -64,7 +64,7 @@ Reinstalling the same kit id from the same source with the same content is idemp
 
 ## Runtime Activation
 
-`activate` reads the built-in Kit Catalog and local install overlay, selects a runtime adapter, and writes generated runtime-local files into the destination workspace. When `--adapter` is omitted, Flow Agents selects the only implemented adapter:
+`activate` reads the built-in Kit Catalog and local install overlay, selects a runtime adapter, and writes generated non-durable projection files into the destination workspace. When `--adapter` is omitted, Flow Agents selects the only implemented adapter:
 
 ```text
 codex-local
@@ -80,13 +80,13 @@ The `codex-local` adapter supports only Flow Definition assets declared in `flow
 
 Activation reuses the installed local kit registry at `<dest>/kits/local/installed-kits.json`; it does not duplicate installed kit state and does not edit `kits/catalog.json`.
 
-Generated files are written under:
+Generated adapter projections are written under:
 
 ```text
-<dest>/.flow-agents/runtime/codex/
+<dest>/.kontourai/flow-agents/projections/codex/
 ```
 
-Flow Definition copies are placed under `flows/<kit-id>/<flow-id>.flow.json`, and activation writes an `activation.json` manifest in the same runtime-local area.
+Flow Definition copies are placed under `flows/<kit-id>/<flow-id>.flow.json`, and activation writes an `activation.json` manifest in the same projection area. These files are regenerable from the Kit Catalog plus `kits/local`; they are not the durable run state for a workflow.
 
 The stable activation diagnostics include: