@kontourai/flow-agents 2.2.0 → 2.4.0

package/docs/spikes/graph-provider-2026-07.md

@@ -0,0 +1,155 @@
+# SPIKE findings — graph database provider experience: Neo4j Community vs Kuzu (embedded)
+
+- Issue: kontourai/flow-agents#318
+- Executed: 2026-07-03 (agent session)
+- **Graph snapshot timestamp: `2026-07-03T05:14:42Z`** (point-in-time; two builds in flight during the spike — #312 flow-agents, #314 traverse — so backlog edges may have moved since)
+- Provider interface (#317) had NOT landed → used a throwaway extractor (`build-graph.js`) over the real stores, per scope.
+- Engines exercised: **BOTH** — Neo4j Community 5 (Docker) AND Kuzu 0.11.3 (embedded, in-process via npm). All 5 canonical queries ran on both.
+
+---
+
+## 1. Node / edge counts (identical on both engines)
+
+**Nodes: 200**
+
+| Label | Count | Source |
+|---|---|---|
+| Issue | 116 | flow-agents (112) + traverse (4), via `gh issue list --json` |
+| Session | 40 | `.kontourai/flow-agents/archive/sweep-2026-07-02.json` (`archived[]`) |
+| Decision | 23 | `docs/adr/*.md` (the *living* `docs/decisions/` registry from #310 does not exist yet — ADRs are the current decision records) |
+| PR | 13 | flow-agents PRs that carry `closingIssuesReferences` |
+| Learning | 8 | numbered sections of `docs/learnings/2026-07-improvement-program.md` |
+
+**Edges: 227**
+
+| Type | Count | Derivation |
+|---|---|---|
+| RELATES | 141 | prose `#NNN` cross-references (+ cross-repo `traverse#NN`, + ADR-0007 number collision) |
+| MENTIONS | 35 | Decision→Issue and Learning→Issue `#NNN` references in doc bodies |
+| BLOCKED_BY | 27 | metadata markers (`work-item-metadata.blockers[]`) AND prose ("blocked by/depends on #N") |
+| CLOSES | 14 | PR→Issue from `closingIssuesReferences` |
+| EVIDENCE_OF | 10 | Session→Decision/Issue — **heuristic** slug/title token overlap (≥2 shared ≥5-char tokens), flagged `heuristic:true` |
+
+AC1 satisfied: both engines loaded the real graph; counts reported.
+
+---
+
+## 2. Engine setup friction
+
+### Neo4j Community (Docker)
+- `docker run -d -p 7474:7474 -p 7687:7687 -e NEO4J_AUTH=neo4j/… neo4j:5-community` — image pull + boot to "Started" in ~30s. Zero config.
+- **Schema-free load**: no DDL. `UNWIND $rows AS r CREATE (n:Label) SET n=r` for nodes; `UNWIND … MATCH (a{id}),(b{id}) CREATE (a)-[x:TYPE]->(b) SET x=r.props` for edges. Endpoints matched by `id` regardless of label — polyglot property bags "just work."
+- Bulk load of 200 nodes + 227 edges via batched UNWIND: **~1.8s**.
+- Ops cost: a running server + two ports + auth. Fine locally; a real dependency in CI/prod.
+
+### Kuzu (embedded, npm)
+- `npm install kuzu` → `new kuzu.Database(path)` + `new kuzu.Connection(db)`. In-process, no server, no ports. SQLite-for-graphs as advertised.
+- **Typed schema REQUIRED up front**: `CREATE NODE TABLE Issue(id STRING PRIMARY KEY, …)` and `CREATE REL TABLE BLOCKED_BY(FROM Issue TO Issue, …)`. Multi-pair rel tables (`FROM Decision TO Issue, FROM Learning TO Issue`) are supported and needed here. This is more rigor than Neo4j but also more friction for an evolving/heterogeneous graph.
+- **Escaping gotcha**: string literals with `'` fail the Cypher parser even with SQL-style `''` doubling — had to switch to parameterized `conn.prepare()`/`conn.execute()`. (Real backlog titles contain apostrophes, em-dashes, emoji — this bit immediately.)
+- **Cleanup gotcha**: the DB is a file *plus* a `.wal` sidecar. Deleting only the file leaves a stale catalog → "Issue already exists in catalog" on reload. Must remove `<db>` and `<db>.wal`.
+- Load of the same graph via per-row prepared statements: **~3.3s** (Kuzu's real strength is bulk `COPY FROM`, which I didn't use for 200 rows).
+
+### ⚠️ Material viability finding (dominates the recommendation)
+**Kuzu is abandoned upstream.** The npm package (`kuzu@0.11.3`) prints *"Package no longer supported"* on install. In October 2025 Kùzu Inc. was acquired (reporting: by Apple), the GitHub repo was **archived**, and active development/support ended. It remains MIT-licensed and usable; community forks exist (Kineviz **"bighorn"**, **"Ladybug"**) but are early. Adopting Kuzu today means betting on a fork or freezing on an unmaintained pin. Sources: The Register 2025-10-14 "KuzuDB graph database abandoned"; npm deprecation notice on `kuzu`.
+
+---
+
+## 3. Query ergonomics — side-by-side Cypher (where they differ)
+
+Q1–Q3 were **byte-identical Cypher** across engines. Q3, Q4, Q5 differed:
+
+**Q1 — transitive blocker closure (identical):**
+```cypher
+MATCH (i:Issue {id:'FA#313'})-[:BLOCKED_BY*1..10]->(b:Issue)
+RETURN DISTINCT b.id, b.state ORDER BY b.id
+```
+Both engines accept the `*1..10` variable-length syntax verbatim.
+
+**Q3 — orphans (no inbound). DIFFERS:**
+```cypher
+-- Neo4j: pattern-predicate + labels()[0]
+MATCH (n) WHERE NOT ( ()-->(n) ) RETURN labels(n)[0] AS label, count(*) ...
+-- Kuzu: EXISTS-subquery + label() (singular)
+MATCH (n) WHERE NOT EXISTS { MATCH ()-[]->(n) } RETURN label(n) AS label, count(*) ...
+```
+
+**Q4 — duplicate candidates (string/list functions DIFFER):**
+```cypher
+-- Neo4j: split() + list comprehension + substring()
+[w IN split(toLower(t),' ') WHERE size(w)>=5 | substring(w,0,5)]
+-- Kuzu: string_split() + list_transform()/list_filter() + list_contains()
+list_transform(list_filter(string_split(lower(t),' '), x->size(x)>=5), x->substring(x,1,5))
+```
+Note `substring` is **0-indexed in Neo4j, 1-indexed in Kuzu**.
+
+**Q5 — shortest path between two decisions. DIFFERS most:**
+```cypher
+-- Neo4j: shortestPath() function + list comprehension over path nodes
+MATCH p=shortestPath((a:Decision {id:'ADR-0011'})-[*..8]-(b:Decision {id:'ADR-0021'}))
+RETURN [n IN nodes(p) | n.id] AS path, length(p)
+-- Kuzu: SHORTEST keyword in the pattern + list_transform for projection
+MATCH p=(a:Decision {id:'ADR-0011'})-[* SHORTEST 1..8]-(b:Decision {id:'ADR-0021'})
+RETURN list_transform(nodes(p), x->x.id) AS path, length(p)
+```
+Kuzu rejected the Neo4j-style `[n IN nodes(p) | n.id]` projection ("Variable n is not in scope") — `list_transform` is the Kuzu idiom. Both returned the same path.
+
+**Takeaway:** ~80% of Cypher is portable; the divergence is entirely in (a) existence predicates, (b) string/list stdlib, (c) path projection + shortest-path spelling. A provider abstraction would need a thin dialect shim for exactly those three areas.
+
+---
+
+## 4. What the queries REVEALED (surprises > confirmations)
+
+**Q1 — SURPRISE / the headline.** #313's transitive blockers = **{#312 (OPEN), #310 (CLOSED)}** — and *nothing else*. The orchestrator's stated ground truth ("#313's transitive blockers now include #317") **does NOT hold in this snapshot.** No edge from #313 (or its blockers #312/#310) to #317 exists in metadata OR prose; #317 is referenced only by this spike (#318, soft blocker). Verified with a fresh individual `gh issue view` on #313/#312/#310. Interpretation: the intended #313→(knowledge provider #317) dependency is **not yet encoded** — either the edit is still in flight (builds #312/#314 open) or the coupling lives only in humans' heads. *This is exactly the class of gap a graph pass surfaces mechanically: an expected transitive dependency that isn't in the data.* The #310–#314 chain itself is confirmed: #310→{#311,#312,#314}, #312→#313.
+
+**Q2 — contradiction candidates: the ADR failure mode caught red-handed.** Top hit is **ADR-0007 vs ADR-0007b** — two files sharing decision number 0007 ("Flow/Skill/Kit/Tool Boundary"), one `Accepted`, one status-less, both citing #62. This is *literally* the numbering-collision + contradiction-accumulation failure that #310 was written to kill, sitting in the current ADR tree. Also surfaced: ADR-0014 (`Proposed`, superseded) contradicting ADR-0015/0016 (`Accepted`) over the same subject (#183, the core-vs-domain boundary), and ADR-0011/0012 (`Accepted`) vs ADR-0021 (`Draft`) over #137. These are real "divergent status over shared subject" pairs.
+
+**Q3 — orphans: reveals a modeling lesson, not just data.** "No inbound edge" flags 43 issues, all 40 sessions, 21 decisions, all 13 PRs, all 8 learnings. But Sessions/PRs/Learnings are *source-only node types by construction* (EVIDENCE_OF/CLOSES/MENTIONS all originate from them), so flagging them wholesale is noise. **Finding: orphan detection needs node-type awareness** ("issues/decisions with no inbound" is the meaningful query; leaf-type nodes should be excluded). The genuinely interesting orphans are the 21 Decisions (ADRs) that *nothing* in the backlog references — candidate stale/undiscoverable decisions.
+
+**Q4 — duplicate candidates: naive title-token overlap MISSES the known duplicate.** With exact ≥5-char token matching, the ground-truth **traverse#14 ~ traverse#8** duplicate did **not** appear (they share only `extraction`; `chunk` vs `chunking` don't match exactly). It surfaced only after switching to **5-char-prefix stemming** (`extra`,`chunk`), on *both* engines. Lesson: mechanical dup-detection needs stemming + shared-evidence (both issues cite the same 23-item listing-page truncation (downstream consumer pilot) in their *bodies*, which title-only matching can't see — full-text/evidence-ref overlap is required, exactly what #317's "shared evidence refs" clause calls for). Bonus real find: the **runtime-compatibility-canary trio #75/#93/#247** ranks top — recurring near-duplicate canary-failure issues.
+
+**Q5 — shortest path.** ADR-0011 ↔ ADR-0021 resolves to `ADR-0011 → FA#137 ← ADR-0021` (length 2): two decisions connected through the backlog issue they both touch. Clean, and a genuinely useful "how are these two decisions related" primitive.
+
+AC2 satisfied: all five queries executed on both engines, interpreted against ground truth.
+
+---
+
+## 5. Visualization notes
+
+- **Neo4j Browser** (http://localhost:7474) is the real differentiator. Captured screenshot (`neo4j-graph.png`, via Playwright) shows the Browser **connected to the live instance** (`neo4j://localhost:7687`, Community 5.26) rendering `MATCH p=(a:Issue)-[:BLOCKED_BY]->(b:Issue) RETURN p LIMIT 60` as a **d3-force graph — 26 Issue nodes / 27 BLOCKED_BY relationships in several distinct clusters** (the backlog's blocker chains, visually separable at a glance). The left Database Information panel simultaneously confirms the full loaded graph: **Nodes (200)** color-coded by all five labels (Decision, Issue, Learning, PR, Session) and **Relationships (227)** across all five types (BLOCKED_BY, CLOSES, EVIDENCE_OF, MENTIONS, RELATES), plus the property-key catalog (id, state, status, superseded, heuristic, overlap, markerStatus, crossRepo, …). Interactive force-directed exploration, click-to-expand neighborhoods, and color-by-label are its standout value for *human* exploration of the blocker/decision subgraph — Kuzu has no equivalent.
+- **Kuzu** ships **no built-in visualization** in the embedded npm path (Kuzu Explorer exists only as a separate Docker image — which defeats the "zero-ops embedded" pitch). For an embedded engine you bring your own viz (export to a JS graph lib).
+- Screenshot path: `/Users/brian/.claude/jobs/90beb625/tmp/graph-spike/neo4j-graph.png`.
+
+---
+
+## 6. Recommendation: **DEFER adoption** (build the model now, pick the engine later)
+
+The spike's own gate ("adoption stays gated on a real query going slow/awkward over file providers") did **not** trip: all five queries ran in milliseconds over 200 nodes / 227 edges. At portfolio scale (hundreds of issues, dozens of decisions, ~120 sessions) this graph is *tiny* — an in-memory JS object graph, or even the throwaway extractor + array scans, answers every canonical query without a database engine at all. **The value proven tonight is the MODEL and the QUERIES, not either engine.**
+
+**What to build now (regardless of engine):** the #317 typed graph model (nodes/edges/provenance) + the read-side extractors validated here (metadata markers + prose blockers + ADR/tombstone status + archive index + PR closes). That model is what caught the ADR-0007 collision, the missing #313→#317 edge, and the traverse#14 dup.
+
+**Trigger conditions to REVISIT an engine (adopt-when):**
+1. Graph exceeds ~10k nodes / ~50k edges, OR a canonical query (transitive closure, all-pairs shortest path, dup-scan) measurably lags in the naive JS implementation.
+2. Multi-hop/variable-length traversal or shortest-path becomes a *frequent, interactive* need (not batch) — this is where hand-rolled JS gets painful and Cypher pays off.
+3. Interactive human exploration of the knowledge graph becomes a workflow (not just automated health passes) — pulls toward Neo4j Browser specifically.
+
+**If/when a trigger fires, prefer Neo4j Community over Kuzu**, primarily because **Kuzu is abandoned upstream (Oct 2025)** — the "zero-ops embedded" advantage is real but is now offset by no maintenance, no security updates, and a fork-or-freeze decision. Neo4j Community is heavier (server + ports) but actively maintained, has the browser, and its Cypher is the portable baseline. *Caveat:* re-evaluate the Kuzu forks (bighorn/Ladybug) at revisit time — if one is credibly maintained, embedded-Kuzu-fork reclaims the zero-ops win for the automated-health-pass use case.
+
+**What a provider implementation (#317) would need:**
+- Read-side extractors for each store (validated here): work-item adapter (issues + `work-item-metadata` markers + prose refs), git-repo-docs adapter (ADR/decision status + tombstones + evidence[] + CONTEXT.md vocabulary + learnings), archive-index adapter (sessions). **Robustness note:** 3 of 19 metadata markers failed to JSON-parse and several `blockers[].ref` were `undefined` — the extractor MUST tolerate malformed markers and fall back to prose.
+- A typed node/edge schema (Kuzu proved you *can* enforce types; the model should own the contract independent of storage).
+- Proposal-only writes where the store is human-curated (decision registry, CONTEXT.md).
+- A **dialect shim** if any real engine is used, covering exactly the three divergences found: existence predicates, string/list stdlib (incl. 0- vs 1-indexed substring), and shortest-path/path-projection syntax.
+- Dup-detection needs **stemming + shared-evidence-ref overlap**, not exact title tokens (proven by the traverse#14~#8 miss).
+
+AC3 satisfied: explicit adopt/defer recommendation with trigger conditions and provider requirements.
+
+---
+
+## Appendix — artifacts in this scratch dir (auto-cleaned with the job; nothing committed)
+- `build-graph.js` — throwaway extractor → `graph.json` (200 nodes / 227 edges)
+- `kuzu-load.js`, `kuzu-queries.js` — Kuzu embedded loader + 5 queries
+- `neo4j-load.js`, `neo4j-queries.js`, `neo4j-q4-stem.js` — Neo4j loader + queries
+- `graph.json`, `fa-issues.json`, `traverse-issues.json`, `fa-prs.json`, `adr.json` — snapshots
+- `kuzu-db` (+`.wal`) — embedded DB file
+- `neo4j-browser.png` — visualization screenshot
+- Docker container `graph-spike-neo4j` — **torn down at end of session** (see cleanup)

package/docs/standards-register.md

@@ -50,13 +50,13 @@ Flow Agents may need local schemas for reliability glue that existing standards
 
 | Format | Purpose | Target Location | Status |
 | --- | --- | --- | --- |
-| Workflow state | Current phase, owner, next action, status, and resumability data | `.flow-agents/<slug>/state.json` | Draft schema: `schemas/workflow-state.schema.json` |
-| Acceptance criteria | Criteria, source request, evidence requirements, and goal-fit status | `.flow-agents/<slug>/acceptance.json` | Draft schema: `schemas/workflow-acceptance.schema.json` |
-| Evidence summary | Proof commands, standard refs, skipped checks, not-verified gaps, and external evidence links | `.flow-agents/<slug>/evidence.json` | Draft schema: `schemas/workflow-evidence.schema.json` |
-| Handoff | What another agent or future session needs to continue safely | `.flow-agents/<slug>/handoff.json` | Draft schema: `schemas/workflow-handoff.schema.json` |
-| Critique record | Reviewer passes, findings, severity, and resolution state for critique loops | `.flow-agents/<slug>/critique.json` | Draft schema: `schemas/workflow-critique.schema.json` |
-| Release readiness | Merge, release, deploy, hold, rollback, docs, and operational readiness decisions | `.flow-agents/<slug>/release.json` | Draft schema: `schemas/workflow-release.schema.json` |
-| Learning record | Repeated failure, correction, pattern, and recommended system update | `.flow-agents/<slug>/learning.json` or `.telemetry/outcomes.jsonl` | Draft schema: `schemas/workflow-learning.schema.json` |
+| Workflow state | Current phase, owner, next action, status, and resumability data | `.kontourai/flow-agents/<slug>/state.json` | Draft schema: `schemas/workflow-state.schema.json` |
+| Acceptance criteria | Criteria, source request, evidence requirements, and goal-fit status | `.kontourai/flow-agents/<slug>/acceptance.json` | Draft schema: `schemas/workflow-acceptance.schema.json` |
+| Evidence summary | Proof commands, standard refs, skipped checks, not-verified gaps, and external evidence links | `.kontourai/flow-agents/<slug>/evidence.json` | Draft schema: `schemas/workflow-evidence.schema.json` |
+| Handoff | What another agent or future session needs to continue safely | `.kontourai/flow-agents/<slug>/handoff.json` | Draft schema: `schemas/workflow-handoff.schema.json` |
+| Critique record | Reviewer passes, findings, severity, and resolution state for critique loops | `.kontourai/flow-agents/<slug>/critique.json` | Draft schema: `schemas/workflow-critique.schema.json` |
+| Release readiness | Merge, release, deploy, hold, rollback, docs, and operational readiness decisions | `.kontourai/flow-agents/<slug>/release.json` | Draft schema: `schemas/workflow-release.schema.json` |
+| Learning record | Repeated failure, correction, pattern, and recommended system update | `.kontourai/flow-agents/<slug>/learning.json` or `.telemetry/outcomes.jsonl` | Draft schema: `schemas/workflow-learning.schema.json` |
 | Context map | Compact project map: structure, commands, conventions, test strategy, Kits, and recent state | Generated under `.flow-agents/` or configurable cache | Planned |
 | Kit Catalog | Product-facing catalog of Flow Kits and their activation, layered over the always-installed standalone base | `kits/catalog.json` plus generated export catalog metadata | Catalog: `kits/catalog.json` |
 | Governance adapter | Optional bridge from Flow Agents evidence gates to tools such as Veritas | `context/contracts/governance-adapter-contract.md` | Draft contract |

package/docs/trust-anchor-adoption.md

@@ -106,12 +106,91 @@ for the files that declare what CI runs:
 
 ```
 # Trust anchor config — requires owner review.
-# An agent cannot weaken verify-command without a human approving the change.
+# An agent cannot weaken verify-command or the reconcile manifest without a human
+# approving the change.
 .github/workflows/trust-verify.yml  @your-org/owners
 package.json                         @your-org/owners
+evals/ci/run-baseline.sh             @your-org/owners
 ```
 
-Adjust paths and team names for your repo structure.
+`package.json` covers both `trust-reconcile-verify` and the `trust-reconcile-manifest`
+declaration (see below); `evals/ci/run-baseline.sh` covers the manifest registry when you
+source the manifest from a `run-baseline.sh`-shaped registry. Adjust paths and team names
+for your repo structure.
+
+## Declaring a Manifest (Multiple Commands)
+
+The single `trust-reconcile-verify` command above is the anchor's standalone fresh-verify
+(and the legacy reconcile path — a manifest of size 1). To reconcile **granular,
+per-acceptance-criterion** evidence — some commands, some session-local/manual/provider
+evidence — declare a **reconcile manifest**: a set of named, individually-re-runnable
+commands, each of which must actually run in a required CI lane (see ADR 0020).
+
+Resolution priority (first match wins):
+
+1. CLI `--manifest '<json>'`
+2. `TRUST_RECONCILE_MANIFEST` environment variable (JSON)
+3. `package.json` `"trust-reconcile-manifest"` — either an inline array, or a string
+   command that emits the JSON:
+
+   ```json
+   {
+     "trust-reconcile-manifest": [
+       { "id": "unit",  "command": "npm test" },
+       { "id": "lint",  "command": "npm run lint" },
+       { "id": "types", "command": "npm run typecheck" }
+     ]
+   }
+   ```
+
+   Every `id`/`command` here must be a command your required CI actually runs. If your repo
+   already has a lane registry that CI invokes, point the key at its machine-readable emit
+   instead of duplicating it (this is what Flow Agents does — see the mirror section):
+
+   ```json
+   { "scripts": { "trust-reconcile-manifest": "bash evals/ci/run-baseline.sh --manifest-json" } }
+   ```
+4. `evals/ci/run-baseline.sh --manifest-json` (auto-detected, if present).
+
+**How classification works.** A claim reconciles per-command against fresh CI results only
+when its evidence is `evidenceType: "test_output"` **and** its command matches a manifest
+entry. Honest session-local evidence (`human_attestation`, `crawl_observation`,
+`document_citation`, `policy_rule`, `source_excerpt`, `attestation`) is never flagged
+"not-run" for lacking a command — it is accepted on its Surface-derived `verified`/`assumed`
+status. A `test_output` claim whose command is not in the manifest is still a divergence
+(you cannot self-label an arbitrary command `test_output` to dodge the manifest).
+
+**Session-local passes are loudly, not quietly, marked.** A non-command-backed claim that
+re-derives `verified` (and carries no waiver) is NOT independently re-runnable by CI — the
+anchor can only confirm the bundle is internally self-consistent, not that the underlying
+attestation is true. It prints a distinct line for every such claim:
+
+```
+[trust-reconcile] ATTESTED (not independently verifiable at L0): '<claimId>' (<claimType>) evidenceType=<type> — accepted on bundle-internal consistency only; see ADR 0020 Residuals
+```
+
+plus a summary count (`N attested claim(s) accepted without independent verification`). This
+does not change the exit code — attestations are not blocked, only disclosed — so review the
+`ATTESTED` lines and count in any bundle before trusting it. See the **Residuals** section of
+[ADR 0020](adr/0020-trust-reconcile-manifest-and-claim-classification.md) for the full
+disclosure (fabricated self-consistent attestations, unauthenticated `approved_by`, and the
+evidenceType-laundering route).
+
+**Waiving an accepted gap.** For an honestly-accepted gap, record it with both flags:
+
+```bash
+npm run workflow:sidecar -- record-evidence <artifact-dir> --verdict pass \
+  --check-json '{"id":"load-test","kind":"external","status":"skip","summary":"sustained-load perf test"}' \
+  --accepted-gap-reason "load-test env not provisioned this cycle; tracked for the perf milestone" \
+  --waived-by "your-name"
+```
+
+Both `--accepted-gap-reason` and `--waived-by` are required together — an accepted gap
+with no justification or approver is refused (no silent waiver). Reuse a **separate**
+`record-evidence` invocation for waived checks: the flags apply to every check in the
+invocation. The anchor prints each waived claim on a distinct, un-suppressible
+`[trust-reconcile] WAIVED: ...` line in the required job's own log — reviewed and visible,
+never silent.
 
 ## Configuring the Verify Command
 
@@ -164,9 +243,14 @@ Flow Agents uses the same pattern in its own repository:
 
 - **`scripts/ci/trust-reconcile.js`** — the anchor script (runs in
   `.github/workflows/trust-reconcile.yml`).
-- **`package.json` `trust-reconcile-verify`** — `npm run build && npm run eval:static`.
+- **`package.json` `trust-reconcile-verify`** — `npm run build && npm run eval:static`
+  (the standalone fresh-verify / legacy single-command reconcile path).
+- **`package.json` `trust-reconcile-manifest`** — `bash evals/ci/run-baseline.sh
+  --manifest-json` (the reconcile manifest *is* the live `run-baseline.sh` `LANE_*`
+  registry — every entry runs in a required `ci.yml` lane by construction).
 - **`evals/ci/antigaming-suite.sh`** — the regression suite that proves the gate and
-  anchor work; runs in the required `ci.yml` lane.
+  anchor work (including `test_trust_reconcile_manifest.sh` and the end-to-end
+  `test_trust_reconcile_mixed_bundle.sh`); runs in the required `ci.yml` lane.
 - **Branch protection** on `main` — `Trust Reconcile` required, `enforce_admins` on.
 
 ## Adoption Checklist
@@ -192,6 +276,23 @@ the mismatch. Fix the underlying test failure.
 **"trust divergence: command contains exit-code-laundering operator"**: A claimed
 command used `||`, `; true`, or `; exit 0`. These mask real exit codes. Remove them.
 
+**"command is not in the reconcile manifest"**: A `test_output` claim named a command that
+is not a manifest entry. Either declare the command in your `trust-reconcile-manifest` (and
+ensure it runs in a required CI lane), or, if the evidence is genuinely session-local
+(manual/provider/observation), record it with a non-`test_output` `evidenceType` so it is
+classified session-local instead of expected to be CI-re-runnable.
+
+**"session-local claim ... asserts pass ... but has no waiver and no Surface-derived
+verified/assumed status"**: An honest session-local claim must either resolve a real
+`verified`/`assumed` Surface status from its own evidence, or be explicitly waived with
+`--accepted-gap-reason` + `--waived-by`. Classification is not a pass bypass.
+
 **"checkpoint-only bundle cannot be reconciled per-command"**: A `delivery/trust.bundle`
 was expected but only `delivery/trust.checkpoint.json` was found. The deliver skill
 publishes the full bundle; ensure it ran correctly.
+
+**"ATTESTED (not independently verifiable at L0): ..."**: Not an error — the job still
+passes. This is the anchor telling you a claim was accepted on bundle-internal consistency
+only (no CI command to re-run and no independent, cryptographically-verified attestation).
+Review each `ATTESTED` line and the summary count before trusting the bundle; see
+[ADR 0020's Residuals section](adr/0020-trust-reconcile-manifest-and-claim-classification.md).

package/docs/work-item-adapters.md

@@ -69,4 +69,4 @@ Do not treat missing CI, missing required review, missing branch protection data
 
 ## Artifact Lifecycle
 
-Local workflow artifacts under `.flow-agents/<slug>/` or a distribution-specific artifact root are runtime/session state by default. Provider records may link to those artifacts, but long-lived decisions should be promoted into durable docs, release notes, changelogs, ADRs, or provider comments/descriptions that are intended to persist.
+Local workflow artifacts under `.kontourai/flow-agents/<slug>/` or a distribution-specific artifact root are runtime/session state by default. Provider records may link to those artifacts, but long-lived decisions should be promoted into durable docs, release notes, changelogs, ADRs, or provider comments/descriptions that are intended to persist.

package/docs/workflow-artifact-lifecycle.md

@@ -4,7 +4,7 @@ title: Workflow Artifact Lifecycle
 
 # Workflow Artifact Lifecycle
 
-Flow Agents treats task artifacts as useful working memory, not permanent product documentation. Feature branches should promote durable planning, decisions, evidence pointers, and acceptance notes into normal project docs, source, schemas, or provider records instead of carrying `.flow-agents/` runtime files.
+Flow Agents treats task artifacts as useful working memory, not permanent product documentation. Feature branches should promote durable planning, decisions, evidence pointers, and acceptance notes into normal project docs, source, schemas, or provider records instead of carrying `.kontourai/flow-agents/` runtime files.
 
 The local artifact root is a current-state dashboard first and a short-lived recovery cache second. It should answer "what needs attention now?" without forcing agents to sift through old successful deliveries.
 
@@ -17,17 +17,19 @@ npm run workflow-artifact-cleanup-audit -- --artifact-root .flow-agents
 npm run workflow-artifact-cleanup-audit -- --artifact-root .flow-agents --json
 ```
 
+The default root for local runtime artifacts is `.kontourai/flow-agents`. `.flow-agents` may hold explicit durable Flow Agents config/install state, but it is not a runtime fallback. Move old local sessions with the migration script instead of relying on automatic fallback reads.
+
 The command scans immediate workflow directories, skips non-workflow lanes such as `archive/`, and reports active WIP separately from cleanup candidates, terminal done records, active learning follow-ups, and invalid sidecars. This first slice is dry-run classification only: it does not delete, archive, move, or rewrite runtime artifacts by default, and it has no apply mode.
 
 Use the Current-State Semantics and Local Retention Policy sections below to interpret each bucket. In particular, learning records with `learning.status: followup_required` or any `routing[].status: open` remain active learning follow-ups until every route is completed, opened elsewhere, deferred with a trigger, accepted, or rejected.
 
 ## Artifact Lanes
 
-Use one local lane under `.flow-agents/`:
+Use one local non-durable lane under `.kontourai/flow-agents/`:
 
 | Lane | Path | Commit Policy | Purpose |
 | --- | --- | --- | --- |
-| Runtime workspace | `.flow-agents/<slug>/` | Do not commit | Local session state, sidecars, delegate events, scratch evidence, and recovery notes. |
+| Runtime workspace | `.kontourai/flow-agents/<slug>/` | Do not commit | Local session state, sidecars, delegate events, scratch evidence, and recovery notes. |
 
 The runtime workspace stays local because it may contain stale session state, machine-specific paths, or noisy intermediate artifacts. When a branch needs cross-session or cross-person traceability, promote the durable summary, decisions, evidence pointers, and acceptance notes into docs, source, schemas, or provider records instead of committing runtime artifacts.
 
@@ -41,10 +43,71 @@ Treat `state.json` as the active-work signal for local users and `pull-work`.
 | `verified` with `next_action.status: continue` | Local evidence passed, but release, final acceptance, or learning is not closed. | Active shepherding candidate. |
 | `verified` with `next_action.status: done` | Evidence passed and the next phase was completed outside the state machine or by a provider record. | Cleanup candidate; should be advanced to a terminal state during final acceptance. |
 | `accepted` with `phase: learning` and `learning.status: followup_required` | Learning was captured but at least one routed follow-up is still open or undecided. | Active learning follow-up until routed to backlog, docs, evals, skills, knowledge, or an explicit deferred trigger. |
-| `delivered`, `accepted`, or `archived` with `phase: done`, or `accepted`/`archived` with closed learning routing | Completed local workflow. | Not active WIP; retain only while useful for recovery or audit. |
+| `delivered`, `accepted`, or `archived` with `phase: done`, or `accepted`/`archived` with closed learning routing | Completed local workflow. | Terminal only once a promotion claim is recorded (see [Promote-Then-Archive Gate](#promote-then-archive-gate)); a delivered/accepted session with no promotion claim is a cleanup candidate, not terminal. Retain only while useful for recovery or audit. |
 
 `verified` is not a terminal state. It means the verifier supplied evidence. Final acceptance must still record the provider change, CI/release result, docs promotion decision, and any learning route before the workflow stops being active.
 
+## Promote-Then-Archive Gate
+
+Archiving a delivered session is not a parallel chore to promoting its durable
+residue — it is **gated on** it. The sequence is:
+
+```
+final acceptance  ->  promote  ->  archive
+```
+
+Durable-residue extraction is the archival act. A delivered session's decisions,
+vocabulary, learnings, and doc updates must be promoted into durable living docs
+(`docs/decisions/<slug>.md`, `CONTEXT.md`, `docs/learnings/*`, `README.md`,
+`context/contracts/`, schemas, provider records) before the session is retired,
+so no delivered work is retired without its knowledge extracted.
+
+### The promotion claim
+
+The `promote` step records **what was promoted where** and writes a **promotion
+claim** into the session `trust.bundle`:
+
+```bash
+# Real durable residue: each --evidence-path must exist on disk at record time.
+flow-agents workflow-sidecar promote <session-dir> \
+  --evidence-path docs/decisions/<slug>.md \
+  --evidence-path CONTEXT.md
+```
+
+The claim is **session-local by construction** (check kind `policy` ->
+`policy_rule` evidence, no command / `execution.label`). It therefore 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 durable doc paths are the
+claim's evidence refs; each is verified to exist on disk when the claim is
+recorded (a missing path fails loud), and they are mirrored into an auditable
+`promotion.json` in the session directory. The claim is detectable by the archive
+gate and validators via `claim.metadata.promotion` without any manifest change.
+
+### Empty-promotion path
+
+When a delivered session genuinely produced **no durable residue** (e.g. a pure
+refactor with no decision, vocabulary, or doc change), record an explicit,
+auditable no-residue promotion rather than skipping the gate:
+
+```bash
+flow-agents workflow-sidecar promote <session-dir> \
+  --none --reason "<why nothing durable was promoted>"
+```
+
+This still produces a promotion claim (with `none: true` and the reason), so the
+decision that nothing needed promoting is recorded, not silently assumed.
+
+### Archive enforcement
+
+`workflow-artifact-cleanup-audit` classifies a **delivered or accepted** session
+that reached a terminal shape **without** a promotion claim as a
+`cleanup_candidate` (blocked from archive) with a reason naming the `promote`
+remedy — not `terminal_done`. With the claim (real residue **or** `--none`) it
+classifies `terminal_done` and may be archived. Already-`archived` sessions are
+past the gate and are never re-flagged; this gate is not a backfill of historical
+archives.
+
 ## Learning Closeout
 
 Learning records are a routing surface, not a permanent parking lot.
@@ -75,13 +138,13 @@ Durable learning should be promoted by target:
 
 ## Local Retention Policy
 
-For local-only users, keep enough local state to recover recent work, but do not use `.flow-agents/<slug>/` as the long-term system of record.
+For local-only users, keep enough local state to recover recent work, but do not use `.kontourai/flow-agents/<slug>/` as the long-term system of record.
 
 Recommended defaults:
 
 | Artifact class | Retain locally | Durable destination |
 | --- | --- | --- |
-| Active WIP, blockers, and unresolved decisions | Until resolved | Current `.flow-agents/<slug>/` state and handoff. |
+| Active WIP, blockers, and unresolved decisions | Until resolved | Current `.kontourai/flow-agents/<slug>/` state and handoff. |
 | Recently merged or accepted deliveries | 14-30 days, or until the next queue audit | PR body, issue comments, release records, promoted docs, or archived evidence refs. |
 | Security, migration, release, or provider-governance evidence | 30-90 days when useful for audit | Provider record, release note, durable doc, or external evidence store. |
 | Routine successful local runtime artifacts | Delete or archive after durable promotion and recovery window | Usually none beyond provider record and docs. |
@@ -117,10 +180,10 @@ Before merge to `main`:
 
 1. Promote durable behavior, contracts, decisions, operations notes, and usage guidance into long-lived docs such as `README.md`, `docs/`, `docs/adr/`, schema docs, runbooks, changelogs, or provider records.
 2. Make sure the durable record names the promotion targets and any accepted gaps.
-3. Confirm `.flow-agents/` runtime artifacts remain untracked.
+3. Confirm `.kontourai/flow-agents/` runtime artifacts remain untracked.
 4. Keep links to provider records, durable docs, or archived external evidence instead of relying on temporary local files.
 
-`main` must not contain tracked files under `.flow-agents/`. If runtime artifacts still seem necessary after merge, their durable content has not been promoted yet.
+`main` must not contain tracked files under `.kontourai/flow-agents/`. If runtime artifacts still seem necessary after merge, their durable content has not been promoted yet.
 
 ## Promotion Targets
 
@@ -138,4 +201,4 @@ Do not promote raw intermediate thinking wholesale. Promote the resulting decisi
 
 ## Enforcement
 
-Runtime state remains ignored under `.flow-agents/`. Static package validation fails if runtime artifacts are tracked. Reviewers should reject PRs that omit durable docs, source, schema, provider, or evidence updates needed to understand shipped behavior.
+Runtime state remains ignored under `.kontourai/flow-agents/`. Static package validation fails if runtime artifacts are tracked. Reviewers should reject PRs that omit durable docs, source, schema, provider, or evidence updates needed to understand shipped behavior.

package/docs/workflow-eval-strategy.md

@@ -49,7 +49,7 @@ These check that skill contracts preserve non-negotiable guardrails:
 
 Static evals prove documented contracts did not drift. They do not prove the agent follows them in conversation.
 
-Activation-only behavioral evals may assert no write tools when the goal is trigger and boundary testing. Artifact-quality evals must allow controlled writes to `.flow-agents/<slug>/*.md` and inspect the resulting artifact contracts.
+Activation-only behavioral evals may assert no write tools when the goal is trigger and boundary testing. Artifact-quality evals must allow controlled writes to `.kontourai/flow-agents/<slug>/*.md` and inspect the resulting artifact contracts.
 
 ### 2. Behavioral Activation Evals
 
@@ -79,7 +79,7 @@ These should verify:
 
 ### 3. Artifact Quality Evals
 
-Inspect generated `.flow-agents/<slug>/*.md` files and provider-backed work item drafts for required structure.
+Inspect generated `.kontourai/flow-agents/<slug>/*.md` files and provider-backed work item drafts for required structure.
 
 The local artifact-quality gate is:
 
@@ -117,7 +117,7 @@ These cases check that the gates resist pressure and ambiguity:
 - CI passes only after unexplained reruns; `evidence-gate` should degrade confidence.
 - Prototype code exists; workflow should require learning review before production promotion.
 - Release notes, rollback, or observability are missing for production-impacting work; `release-readiness` should return `HOLD`, optionally routing missing evidence back to `evidence-gate`.
-- Agent tries to stop with an active `.flow-agents/<slug>/` delivery artifact; `stop-goal-fit` should warn and strict mode should block.
+- Agent tries to stop with an active `.kontourai/flow-agents/<slug>/` delivery artifact; `stop-goal-fit` should warn and strict mode should block.
 - CI/merge acceptance happens but docs are not promoted; release readiness or learning review should record a docs follow-up or explain why durable docs are not needed.
 - Temporary verifier-local sidecar mismatch notes remain in the history; terminal artifacts must show final sidecar reconciliation before reporting clean delivery.
 - Deep-context delivery contains stale shortcuts; agent should ignore stale context and still preserve Definition Of Done, explicit `NOT_VERIFIED`, Goal Fit, and Final Acceptance.

package/docs/workflow-shared-contracts.md

@@ -27,7 +27,7 @@ That reference is docs-only guidance for new resource-shaped contracts and does
 The lifecycle for in-progress and completed workflow artifacts is documented in the Workflow Artifact Lifecycle:
 https://github.com/kontourai/flow-agents/blob/main/docs/workflow-artifact-lifecycle.md
 
-Runtime workflow artifacts under `.flow-agents/` remain local and ignored. Completed work must promote durable behavior, decisions, contracts, and evidence into long-lived docs, source, schemas, or provider records before merge to `main`.
+Runtime workflow artifacts under `.kontourai/flow-agents/` remain local and ignored. Explicit durable Flow Agents config/install state may live under `.flow-agents/` when documented, but runtime readers do not fall back there. Completed work must promote durable behavior, decisions, contracts, and evidence into long-lived docs, source, schemas, or provider records before merge to `main`.
 
 ## How Skills And Agents Use Them