@kontourai/flow-agents 2.3.0 → 3.0.0

package/docs/learnings/2026-07-improvement-program.md

@@ -0,0 +1,203 @@
+---
+title: "2026-07 Improvement Program — Learning Review"
+---
+
+# 2026-07 Improvement Program — Learning Review
+
+This document records durable learnings from a multi-week, multi-repository improvement
+program run across the Kontour portfolio in June and July 2026. The program touched
+Flow Agents, Surface, Veritas, Flow, Survey, Traverse, and the shared hachure trust-bundle
+schema. Every finding below was hit empirically during the program and resolved or worked
+around; none are speculative.
+
+It is written for a future maintainer who was not present for the program. Where a finding
+implies a rule you should keep following, that rule is stated explicitly. Cross-repository
+pull requests and issues are linked so you can trace the underlying change.
+
+## Scope and source material
+
+- Corroborating provider issues: [flow-agents#267](https://github.com/kontourai/flow-agents/issues/267),
+  [flow-agents#268](https://github.com/kontourai/flow-agents/issues/268),
+  [flow-agents#281](https://github.com/kontourai/flow-agents/issues/281).
+- Representative pull requests:
+  - Flow Agents: [#264](https://github.com/kontourai/flow-agents/pull/264) (cross-kit
+    dependencies, skill-collision fixes, sidecar governance),
+    [#266](https://github.com/kontourai/flow-agents/pull/266) (manifest-based reconcile,
+    claim classification, loud attestations),
+    [#269](https://github.com/kontourai/flow-agents/pull/269) (veritas-governance kit —
+    readiness→trust-bundle adapter),
+    [#277](https://github.com/kontourai/flow-agents/pull/277) (migrate to
+    `@kontourai/surface` 2.0.0, `Claim.facet` rename).
+  - Surface: [#103](https://github.com/kontourai/surface/pull/103) (order-independent
+    multi-producer merge; hachure 0.7.0 conformance),
+    [#104](https://github.com/kontourai/surface/pull/104) (sync to hachure 0.8.0,
+    vendor-neutral `$id`s), [#105](https://github.com/kontourai/surface/pull/105)
+    (`Claim.surface` → `facet`, spec 0.9.0 parity — a breaking change).
+  - Veritas: [#107](https://github.com/kontourai/veritas/pull/107) (blocking failures win
+    over `promotion_allowed` short-circuit), [#109](https://github.com/kontourai/veritas/pull/109)
+    (migrate `Claim.surface` → `facet`, Surface ^2.0.0, schemaVersion 5).
+  - Flow: [#100](https://github.com/kontourai/flow/pull/100) (migrate to Surface 2.0.0 —
+    shipped as a `chore:` and therefore went unreleased; see Finding 6),
+    [#101](https://github.com/kontourai/flow/pull/101) (trust bundles emit `facet` +
+    schemaVersion 5; Surface 2.0, hachure 0.9).
+  - Survey: [#100](https://github.com/kontourai/survey/pull/100) (migrate to Surface 2.0.0
+    facet rename), released via [#99](https://github.com/kontourai/survey/pull/99) /
+    [#101](https://github.com/kontourai/survey/pull/101).
+  - hachure trust-bundle schema releases 0.6.0 through 0.9.0, which drove the coordinated
+    Surface / Veritas / Flow / Survey / Flow Agents migrations above.
+
+The rest of this document is organized by finding. Each finding states what happened, why
+it matters, and the working discipline or fix to carry forward.
+
+## 1. Trust-ledger write discipline
+
+The trust ledger (`trust.bundle` plus its `evidence.json` / critique inputs) has write
+semantics that are easy to corrupt if you interleave commands:
+
+- `record-evidence` **replaces** `trust.bundle` wholesale. At the time of the program it
+  rebuilt the bundle with a hardcoded `critiques: []`, so any previously recorded critique
+  was silently dropped.
+- `record-critique` is **append-only** and has no supersession mechanism: a reviewer cannot
+  close or retract a disputed finding once written ([flow-agents#267](https://github.com/kontourai/flow-agents/issues/267)).
+- The checks/critiques round-trip through the bundle is contaminating: prior critique claims
+  get re-absorbed as command-less `test_output` checks, turning a critique claim into a
+  divergent, command-less check ([flow-agents#268](https://github.com/kontourai/flow-agents/issues/268)).
+  This is amplified under `--flow-id`, where a **single** critique write is enough to
+  contaminate the ledger.
+
+**Working discipline until the tooling is fixed:**
+
+1. Record **all** evidence first.
+2. Record **at most one** critique write, and make it the **last** write.
+3. Never run any `record-*` command after that final critique write.
+4. If a ledger becomes contaminated, **restart the session** rather than trying to iterate
+   or repair a contaminated ledger in place.
+
+This program's learning-review session itself follows the rule: it was created with
+`ensure-session` **without** `--flow-id` precisely to avoid the single-critique-write
+amplification described above.
+
+## 2. Post-merge ledger staleness
+
+A session whose `trust.bundle` was frozen mid-iteration causes stop-gate "caught
+false-completion" storms after the branch merges. The stale iteration claims are recomputed
+in a changed context (the merged tree no longer matches the frozen claims), and the stop gate
+repeatedly flags the session as falsely complete.
+
+**Pattern to recover:** rebuild the bundle from the current `evidence.json` via
+`record-evidence`, then re-advance state. Do not hand-edit the frozen bundle; regenerate it
+from current evidence so the claims match the post-merge tree.
+
+## 3. Evidence must be executable in the CI/backstop context
+
+Evidence checks are re-run by CI and by the backstop reconciler, not just locally. Several
+checks passed locally but failed in CI because they were not executable in that context. Keep
+evidence portable:
+
+- Check commands must be **repo-root-relative** and must reference files that live **inside
+  the session directory** (for example under `verify-scratch/`), never an agent's private
+  scratchpad that does not exist in CI.
+- Summaries must be **runnable commands**. For prose that is not a command, use the
+  `true # ...` form so the "command" still exits zero when executed.
+- Reconcilable claims need **manifest-exact bare labels** — no environment-variable
+  annotations on the label — so the reconciler can match them against the manifest.
+- Keep reconcilable sets **small**. `runCommand` enforces a 180-second per-command timeout;
+  heavy test suites trip that timeout in CI while passing locally. Split or scope the suite
+  so each reconciled command finishes well under the limit.
+
+## 4. Critique semantics and resolved sessions
+
+Under the current validator rule, a top-level `pass` verdict forbids any `fail` or
+`not_verified` member claims. Consequently a **resolved** session cannot retain historical
+`verdict: fail` critiques — the validator rejects the bundle even though the failure was
+genuine and later fixed.
+
+**Reconciliation pattern:** move the historical failing critique to `superseded` and then
+`comment`, preserving the original outcome in the summary text so the audit trail survives.
+The `fail` verdict is not deleted from history; it is superseded, and the summary records
+what the original verdict was and how it was resolved.
+
+This deserves an explicit convention note, and possibly a validator/schema affordance for a
+first-class `superseded_by` relationship so the original verdict can be preserved structurally
+rather than only in prose. That tooling gap is filed as a follow-up issue (see below).
+
+## 5. Shim scope coupling in cross-repo schema migrations
+
+Surface 2.0's read-tolerance shim (the compatibility layer that accepts both the old
+`Claim.surface` and new `Claim.facet` shapes) only protects consumers that go through
+**Surface's JavaScript API**. Anything that validates against the hachure JSON Schema
+**directly** bypasses the shim and breaks. During this program that included:
+
+- Flow's Ajv gate (validates bundles against the raw schema),
+- Veritas's schema dependency,
+- Flow Agents `attach-evidence` using a **vendored** copy of the old hachure schema.
+
+Each of these had to bump hachure **in lockstep** with the Surface bump; the shim did not
+cover them.
+
+**Rule for future cross-repo schema migrations:** map **both** axes before you start —
+(a) the JS-API consumers, which the shim protects, and (b) the raw-schema validators, which
+it does not. Every raw-schema validator (including vendored schema copies) must be bumped in
+the same coordinated wave. See Surface [#105](https://github.com/kontourai/surface/pull/105),
+Veritas [#109](https://github.com/kontourai/veritas/pull/109), Flow
+[#101](https://github.com/kontourai/flow/pull/101), Survey
+[#100](https://github.com/kontourai/survey/pull/100), and Flow Agents
+[#277](https://github.com/kontourai/flow-agents/pull/277) for the coordinated set.
+
+## 6. Release mechanics
+
+Two independent release-mechanics traps surfaced:
+
+- **release-please ignores `chore:` commits.** Flow [#100](https://github.com/kontourai/flow/pull/100)
+  shipped real functionality (the Surface 2.0 migration) as a `chore:` commit, so
+  release-please never cut a release and the functionality sat unreleased until a subsequent
+  `feat!:` signal commit ([#101](https://github.com/kontourai/flow/pull/101)) triggered the
+  release. If a `chore:` PR changes shipped behavior, it will not be released on its own —
+  pair it with a `feat:`/`fix:`/`feat!:` signal commit or it stays dark.
+- **GitHub App installation repo-access is a separate axis from org secrets/vars grants.**
+  A Traverse release was blocked because the GitHub App was not installed on that repository,
+  which is distinct from whether org-level secrets and variables were granted. App
+  installation repo-access is org-owner-only, so this class of block cannot be self-resolved
+  by the release author and must be escalated to an org owner.
+
+## 7. Runtime-artifact hygiene
+
+Bulk worktree operations reset filesystem `mtime`s en masse. Any recency heuristic based on
+`mtime` is therefore unreliable after a sweep. Session recency must be read from
+`state.json`'s `updated_at` field, not from file `mtime` (established during the WS6 sweep —
+the WS6 sweep was the pass that audited and pruned stale local runtime sessions).
+
+The `workflow-artifact-cleanup-audit` CLI is **dry-run only**: it classifies sessions into
+active WIP, cleanup candidates, terminal done records, active learning follow-ups, and
+invalid sidecars, but it does not delete, archive, or rewrite anything and has no apply mode.
+An apply mode may be worth filing so cleanup can be executed, not just recommended. That
+tooling gap is filed as a follow-up issue (see below).
+
+## 8. Gate operations
+
+Operational discipline for running gates and merging, learned the hard way during parallel
+waves:
+
+- **Never dispatch fixes while gates are running.** Wait for **all** outstanding gates to
+  finish before acting on any result; dispatching a fix mid-run races the gate and produces
+  confusing, interleaved state.
+- **Run mutation testing only in scratch copies**, never against the working tree the gate is
+  evaluating.
+- **Keep `gh pr merge` stderr visible.** Do not swallow it; the merge failure reasons you
+  need (behind-base, pending checks, blocked) come through stderr.
+- Use `gh pr merge --auto` for pending checks so the merge lands when checks go green, and use
+  branch update (`update-branch`) when a PR is `BEHIND` the base.
+
+## Follow-up tooling issues
+
+Findings 4 and 7 imply concrete Flow Agents tool changes. Both were checked against the open
+issue list for duplicates and filed fresh:
+
+- Finding 4 → [flow-agents#282](https://github.com/kontourai/flow-agents/issues/282): a
+  validator/schema affordance for `superseded_by` on critique claims, so a resolved session
+  can preserve a historical `fail` verdict structurally rather than only in the summary prose.
+- Finding 7 → [flow-agents#283](https://github.com/kontourai/flow-agents/issues/283): an
+  apply mode for `workflow-artifact-cleanup-audit`, so the dry-run classification can be
+  executed.
+
+Both issues were checked against the open issue list before filing; no duplicates existed.

package/docs/migrations.md

@@ -6,11 +6,12 @@ title: Migrations
 
 ## Unreleased
 
-- Workflow runtime artifacts now live under `.flow-agents/` instead of
-  `.agents/flow-agents/`. Move any local session directories, sidecars, or
-  `current.json` pointers you want to keep into the new root. Runtime state
-  remains ignored; promote durable outcomes into docs, source, schemas, or
-  provider records before merge.
+- Workflow runtime artifacts now live under `.kontourai/flow-agents/` instead
+  of earlier runtime roots such as `.flow-agents/` or `.agents/flow-agents/`.
+  Move any local session directories, sidecars, or `current.json` pointers you
+  want to keep into the new root. Runtime readers do not fall back to old roots.
+  Runtime state remains ignored; promote durable outcomes into docs, source,
+  schemas, or provider records before merge.
 - Flow Agents setup no longer accepts Console bearer tokens as CLI arguments.
   Replace `--console-token TOKEN` with `--console-token-file PATH` for
   headless installs, or use the prompted `flow-agents init` flow. Interactive

package/docs/north-star.md

@@ -206,7 +206,7 @@ Exit criteria:
 
 - A workflow can resume from artifacts without relying on the model remembering prior turns.
 - Goal Fit, evidence status, and next action can be read mechanically.
-- Multiple agents can share one workflow root by resolving `.flow-agents/current.json` and appending agent-local events instead of racing on root state.
+- Multiple agents can share one workflow root by resolving `.kontourai/flow-agents/current.json` and appending agent-local events instead of racing on root state.
 
 ## Phase 3: Add Just-In-Time Guidance
 
@@ -261,7 +261,7 @@ Tasks:
 - Add promotion gates so guidance becomes stricter only after evidence shows it helps.
 - Make dashboards answer whether Flow Agents is improving outcomes over time.
 - Dogfood the workflow artifacts on Flow Agents changes: each substantial pass should produce sidecars, run artifact validation, delegate critique, update durable docs, and route accepted critique into the next slice. **Started:** `npm run workflow:sidecar -- dogfood-pass` records evidence, required critique, optional release readiness, optional learning, state, and handoff in one fail-closed validated pass.
-- Automatically create or select the current session artifact so self-validation does not depend on the user or orchestrator hand-picking `.flow-agents/<slug>`. **Started:** `npm run workflow:sidecar -- ensure-session` creates or selects a delivery session artifact plus initial state, acceptance, and handoff sidecars.
+- Automatically create or select the current session artifact so self-validation does not depend on the user or orchestrator hand-picking `.kontourai/flow-agents/<slug>`. **Started:** `npm run workflow:sidecar -- ensure-session` creates or selects a delivery session artifact plus initial state, acceptance, and handoff sidecars.
 
 Exit criteria:
 

package/docs/operating-layers.md

@@ -18,7 +18,7 @@ For the concrete directory-by-directory source map, generated output policy, run
 | Skills | Reusable procedures an agent can invoke when a task matches | Always-on policy, credentials, or long-lived memory | Agent Skills / `SKILL.md` |
 | Powers | Tool bundles, MCP configs, and activation guidance | Workflow gates or repo-specific policy semantics | MCP, OpenAPI, OAuth/OIDC |
 | Agents | Role prompts, delegation boundaries, and scoped tool access | Generic task procedures that should be skills | Harness-native subagents/profiles |
-| Workflows | Durable state, gates, handoffs, acceptance criteria, and phase transitions | Domain-specific knowledge records or tool internals | JSON Schema sidecars plus Markdown summaries |
+| Workflows | Resumable state, gates, handoffs, acceptance criteria, and phase transitions | Domain-specific knowledge records or tool internals | JSON Schema sidecars plus Markdown summaries |
 | Knowledge | People, organizations, meetings, decisions, commitments, notes, and follow-ups | Verification verdicts or runtime telemetry | CommonMark, JSContact, iCalendar, JMAP, WebVTT/SRT, JSON-LD |
 | Evidence | Proof, telemetry, findings, evals, provenance, and quality outcomes | User-facing procedure instructions | OpenTelemetry, SARIF, CycloneDX, SLSA, JSON Schema |
 
@@ -37,7 +37,8 @@ Governance tools such as Veritas belong at the Evidence boundary. Flow Agents sh
 | `kits/` | Flow Kits | Kit Catalog entries, Flow Kit manifests, Flow Definitions, and supporting assets. Builder Kit is the first proof point. |
 | `prompts/` | Skills / Rules | Saved invocations. Promote repeatable procedures into skills when they grow stable. |
 | `docs/workflow-*.md` | Workflows | Human-readable workflow contracts and usage guidance. |
-| `.flow-agents/` | Workflows | Cross-session task artifacts. Runtime state stays local and ignored; durable outcomes are promoted into docs, source, schemas, or provider records before merge. |
+| `.kontourai/flow-agents/` | Workflows | Non-durable cross-session task artifacts and generated projections. Runtime state stays local and ignored; durable outcomes are promoted into docs, source, schemas, or provider records before merge. |
+| `.flow-agents/` | Workflows | Flow Agents-owned durable config/install state when a distribution explicitly owns that path. Not a runtime artifact fallback. |
 | `scripts/` | Evidence / Workflows / Packaging | Validation, build, telemetry, hooks, and artifact tooling. |
 | `src/` | Workflows / Evidence / Packaging | TypeScript CLI, runtime adapter, Flow Kit, shared library, build, validation, context-map, packaging, and CLI helper source compiled into `build/src/`. |
 | `evals/` | Evidence | Static, behavioral, integration, and acceptance checks. |
@@ -80,7 +81,7 @@ Builder Kit evidence gates can reference Surface trust state without naming a pr
 Workflow artifacts have their own lifecycle policy:
 https://github.com/kontourai/flow-agents/blob/main/docs/workflow-artifact-lifecycle.md
 
-Use `.flow-agents/<slug>/` for local runtime/session state. If in-progress planning needs review or handoff, promote the durable decision, behavior, and evidence summary into normal docs or provider records before merge; keep runtime artifacts out of git.
+Use `.kontourai/flow-agents/<slug>/` for local runtime/session state. Keep `.flow-agents/` for explicit durable Flow Agents config/install state. If in-progress planning needs review or handoff, promote the durable decision, behavior, and evidence summary into normal docs or provider records before merge; keep runtime artifacts out of git.
 
 If a proposed artifact seems to belong to multiple layers, split it. For example, a dependency-checking capability may have:
 

package/docs/repository-structure.md

@@ -10,7 +10,7 @@ This is the canonical developer-facing map for the Flow Agents repository. Use i
 
 - Edit canonical source in the repo root areas listed below, then regenerate derived output with the documented commands.
 - Do not edit `dist/`, `build/`, or `_site/` by hand. They are generated from tracked source.
-- Do not commit local runtime state from `.flow-agents/<slug>/`, `.kontourai/`, `.codex/`, `.claude/`, `.omx/`, `.promptfoo/`, `.telemetry/`, `.surface/`, generated `.veritas/` output, or tool caches; intentionally tracked `.veritas/` governance/config remains durable source.
+- Do not commit local runtime state from `.kontourai/flow-agents/<slug>/`, `.codex/`, `.claude/`, `.omx/`, `.promptfoo/`, `.telemetry/`, `.surface/`, generated `.veritas/` output, or tool caches; intentionally tracked `.veritas/` governance/config remains durable source.
 - Runtime workflow artifacts stay local and ignored; promote reviewable or durable outcomes to docs, source, schemas, or provider records before merging to `main`.
 - Treat generated exports and installed runtime config as products of `packaging/manifest.json`, `src/tools/build-universal-bundles.ts`, `scripts/install-*.sh`, and the source directories they copy.
 - Use `.kontourai/` for non-durable local or generated Kontour workspace state. Keep durable tracked files in intuitive product-owned paths such as `.veritas/`, `.flow/`, `.agents/`, `.claude/commands`, and `docs/`; existing transition ignores remain during migration.
@@ -33,15 +33,15 @@ This is the canonical developer-facing map for the Flow Agents repository. Use i
   docs/                        # durable docs and GitHub Pages source
   integrations/                # optional external integration config
   dist/ build/ _site/           # generated output; ignored
-  .flow-agents/ .kontourai/ .codex/ .claude/ ... # local runtime state; ignored by default
+  .kontourai/ .flow-agents/ .codex/ .claude/ ... # local/generated or installed state; ignored by default
 ```
 
 ## Top-Level Inventory
 
 | Path | Classification | Source of truth | Generated or runtime policy | Safe cleanup rule |
 | --- | --- | --- | --- | --- |
-| `.flow-agents/` | runtime state | Workflow tools write local session artifacts. | Ignored. | Do not commit task runtime roots; promote durable decisions to docs, source, schemas, or providers before merge. |
-| `.kontourai/` | local/generated workspace state | Local Kontour tools and developer workflows. | Ignored. | Safe local cleanup when no active workflow needs it; durable source and decisions stay in product-owned tracked paths. |
+| `.kontourai/` | local/generated workspace state | Local Kontour tools and developer workflows, including `.kontourai/flow-agents/<slug>/` runtime sessions. | Ignored. | Safe local cleanup when no active workflow needs it; durable source and decisions stay in product-owned tracked paths. |
+| `.flow-agents/` | durable local Flow Agents state | Explicit Flow Agents config/install records when documented. | Ignored unless a repo-specific contract intentionally tracks a durable file. | Do not use for non-durable workflow sessions; migrate old runtime artifacts into `.kontourai/flow-agents/`. |
 | `.claude/` | installed runtime config | Generated bundle or local runtime install. | Ignored. | Reinstall from `dist/claude-code/` instead of editing as source. |
 | `.codex/` | installed runtime config | Generated bundle or local runtime install. | Ignored. | Reinstall from `dist/codex/` or `scripts/install-codex-home.sh`; do not treat local hooks as canonical. |
 | `.githooks/` | canonical repo tooling | Tracked repository hook scripts. | Source, not runtime agent hooks. | Keep compatible with `npm run setup:repo-hooks` and `npm run validate:repo-hooks --`. |
@@ -115,7 +115,7 @@ The package requires Node `>=22`, and GitHub Actions runs CI on Node 22. Keep `@
 
 `.codex/` and `.claude/` at the repo root are installed runtime configuration surfaces. They can be useful for local testing, but canonical hook scripts and runtime config live in `scripts/hooks/`, `context/`, `packaging/`, and generated bundle output. The stale local `.codex/hooks.json` incident came from treating an installed runtime file as if it were canonical source. The fix is to regenerate or reinstall runtime config and update the canonical builder/install sources when behavior must change.
 
-`.flow-agents/<slug>/` is workflow working memory. Keep plans, sidecars, evidence, and handoffs there while work is active. Promote stable outcomes into `docs/`, schemas, source, or provider records before final acceptance.
+`.kontourai/flow-agents/<slug>/` is workflow working memory. Keep plans, sidecars, evidence, and handoffs there while work is active. `.flow-agents/` is reserved for Flow Agents-owned durable config/install state when explicitly documented; do not use it for non-durable sessions. Promote stable outcomes into `docs/`, schemas, source, or provider records before final acceptance.
 
 Across Kontour repos, `.kontourai/` is the simple ignored home for non-durable local/generated workspace state. It is not a durable source root. Keep durable governance, Flow config, agent source, command source, and documentation in the product-owned tracked paths where developers expect them, including `.veritas/`, `.flow/`, `.agents/`, `.claude/commands`, and `docs/`. Existing transition ignores such as `.flow-agents/`, `.kontour/`, `.surface/`, `.veritas/evidence/`, `.flow/runs/`, and `.telemetry/` remain in place during migration.
 

package/docs/skills-map.md

@@ -82,7 +82,7 @@ This view shows how each phase is composed. The left rail is the durable phase s
       <section class="phase-lane phase-lane--primary"><h3>Primary</h3><p><code>builder-shape</code> <code>idea-to-backlog</code></p></section>
       <section class="phase-lane"><h3>Support</h3><p><code>search-first</code> <code>explore</code> <code>frontend-design</code> <code>github-cli</code> <code>knowledge-capture</code></p></section>
       <section class="phase-lane"><h3>Nested sections / future primitives</h3><p>intake/dedupe, separate ideas, thinnest meaningful slice, opportunity review, explore options, <code>shape-work</code>, prioritize work, sync executable backlog</p></section>
-      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Idea, slice, shape, and backlog gates. Writes shaped briefs and GitHub issue links in <code>.flow-agents/&lt;slug&gt;/</code>.</p></section>
+      <section class="phase-lane phase-lane--gate"><h3>Gate & artifact</h3><p>Idea, slice, shape, and backlog gates. Writes shaped briefs and GitHub issue links in <code>.kontourai/flow-agents/&lt;slug&gt;/</code>.</p></section>
     </div>
   </article>
   <article class="phase-row">
@@ -137,15 +137,15 @@ The highest-leverage future extractions are likely `shape-work`, `test-map`, `sc
 
 Each workflow phase ends with an explicit gate and durable artifact:
 
-- `builder-shape` invokes Builder Kit shape, delegates to `idea-to-backlog`, links `kits/builder/flows/shape.flow.json`, and writes the standard `.flow-agents/<slug>/<slug>--idea-to-backlog.md` artifact.
-- `idea-to-backlog` writes `.flow-agents/<slug>/<slug>--idea-to-backlog.md` and produces shaped briefs plus GitHub issue links.
-- `pull-work` writes `.flow-agents/<slug>/<slug>--pull-work.md` with selected issues, WIP notes, blockers, pickup Probe decisions or accepted gaps, worktree decision, expected modified files, conflict risks, and a `plan-work` handoff.
-- `plan-work` and `deliver` write `.flow-agents/<slug>/<slug>--*.md` artifacts with `Definition Of Done`, `Goal Fit Gate`, and `Final Acceptance` sections.
+- `builder-shape` invokes Builder Kit shape, delegates to `idea-to-backlog`, links `kits/builder/flows/shape.flow.json`, and writes the standard `.kontourai/flow-agents/<slug>/<slug>--idea-to-backlog.md` artifact.
+- `idea-to-backlog` writes `.kontourai/flow-agents/<slug>/<slug>--idea-to-backlog.md` and produces shaped briefs plus GitHub issue links.
+- `pull-work` writes `.kontourai/flow-agents/<slug>/<slug>--pull-work.md` with selected issues, WIP notes, blockers, pickup Probe decisions or accepted gaps, worktree decision, expected modified files, conflict risks, and a `plan-work` handoff.
+- `plan-work` and `deliver` write `.kontourai/flow-agents/<slug>/<slug>--*.md` artifacts with `Definition Of Done`, `Goal Fit Gate`, and `Final Acceptance` sections.
 - `review-work` writes reviewer artifacts when available and updates `critique.json` with quality, security, architecture, standards, and resolution state.
 - `verify-work` writes verification artifacts and updates `evidence.json` with behavior evidence mapped to acceptance criteria.
-- `evidence-gate` writes `.flow-agents/<slug>/<slug>--evidence-gate.md` with acceptance evidence, CI summary, integrity report, verdict, and next step.
-- `release-readiness` writes `.flow-agents/<slug>/<slug>--release-readiness.md` with release scope, evidence reference, risk review, operational plan, rollback plan, observability plan, post-deploy checks, and decision.
-- `learning-review` writes `.flow-agents/<slug>/<slug>--learning-review.md` with outcomes, evidence, decisions, gaps, follow-ups, knowledge updates, and verdict.
+- `evidence-gate` writes `.kontourai/flow-agents/<slug>/<slug>--evidence-gate.md` with acceptance evidence, CI summary, integrity report, verdict, and next step.
+- `release-readiness` writes `.kontourai/flow-agents/<slug>/<slug>--release-readiness.md` with release scope, evidence reference, risk review, operational plan, rollback plan, observability plan, post-deploy checks, and decision.
+- `learning-review` writes `.kontourai/flow-agents/<slug>/<slug>--learning-review.md` with outcomes, evidence, decisions, gaps, follow-ups, knowledge updates, and verdict.
 
 Core gates:
 

package/docs/spec/runtime-hook-surface.md

@@ -86,8 +86,8 @@ Flow Agents currently ships five canonical policy classes. Each policy class has
 **Canonical trigger event**: `userPromptSubmit` and `agentSpawn`/`SessionStart` (active-goal re-grounding), `postToolUse` (after `InvokeSubagents` tool calls)
 
 **Inputs consumed**:
-- `.flow-agents/<slug>/state.json` — current workflow phase and status
-- `.flow-agents/<slug>/critique.json` — open critique findings
+- `.kontourai/flow-agents/<slug>/state.json` — current workflow phase and status
+- `.kontourai/flow-agents/<slug>/critique.json` — open critique findings
 - `docs/context-map.md` — structure hint for repo navigation
 
 **Decision contract**: Non-blocking. Always exits 0. Appends steering text to the agent's context via `additionalContext` in the hook response. Does not block any action. It re-grounds the active workflow goal (status, phase, recorded next step) at the start of every user turn — not only for flagged/blocked states — and on `SessionStart`, which fires after context compaction and on resume. This is the mechanism that keeps an in-flight goal alive across context loss instead of relying on the model voluntarily re-reading the sidecar.
@@ -125,12 +125,14 @@ Flow Agents currently ships five canonical policy classes. Each policy class has
 **Canonical trigger event**: `stop`
 
 **Inputs consumed**:
-- `.flow-agents/<slug>/*.md` — workflow artifact files (scanned for active status, DOD, Goal Fit Gate sections)
-- `.flow-agents/<slug>/state.json` — workflow phase and next action
-- `.flow-agents/<slug>/evidence.json` — verification verdict and NOT_VERIFIED gaps
-- `.flow-agents/<slug>/critique.json` — critique status and open findings
-- `.flow-agents/<slug>/command-log.jsonl` — the deterministic capture log written by the Evidence Capture policy (see §2.5); cross-referenced against `evidence.json` claimed-pass command checks
-- `.flow-agents/<slug>/acceptance.json` — acceptance criteria; a criterion's `command`-kind `evidence_ref` (`excerpt`) is the most-trusted backstop command
+- `.kontourai/flow-agents/<slug>/*.md` — workflow artifact files (scanned for active status, DOD, Goal Fit Gate sections)
+- `.kontourai/flow-agents/<slug>/state.json` — workflow phase and next action
+- `.kontourai/flow-agents/<slug>/evidence.json` — verification verdict and NOT_VERIFIED gaps
+- `.kontourai/flow-agents/<slug>/critique.json` — critique status and open findings
+- `.kontourai/flow-agents/<slug>/command-log.jsonl` — the deterministic capture log written by the Evidence Capture policy (see §2.5); cross-referenced against `evidence.json` claimed-pass command checks
+- `.kontourai/flow-agents/<slug>/acceptance.json` — acceptance criteria; a criterion's `command`-kind `evidence_ref` (`excerpt`) is the most-trusted backstop command
+- `.kontourai/flow-agents/current.json` (`active_flow_id`/`active_step_id`) — when present, resolves the active kit FlowDefinition's gate `expects[]` via the compiled `build/src/lib/flow-resolver.js` (`loadActiveFlowStep`, ADR 0016 Abstraction A P-c); requires `build/` to exist and fails open to the legacy `workflow.*`-only behavior when it does not (the `hasBuild` guard — the same fail-open pattern already used for the trust-bundle validator)
+- The active kit's `kits/<kit>/flows/<flow>.flow.json` — the FlowDefinition file `current.json` resolves against; the matching gate's `expects[].bundle_claim.claimType` values become the declared claim types enforced for the active step (see FlowDefinition-driven claim selection below)
 - `FLOW_AGENTS_GOAL_FIT_MODE` env var — `block` | `warn` | `off` (the legacy `FLOW_AGENTS_GOAL_FIT_STRICT=true` is an alias for `block`)
 - `FLOW_AGENTS_GOAL_FIT_MAX_BLOCKS` env var — consecutive-identical-block cap before the escape hatch releases (default 3)
 - `FLOW_AGENTS_GOAL_FIT_BACKSTOP` env var — `block` (default) | `off`/`warn` | `skip`; controls the capture backstop re-run (see Capture cross-reference below)
@@ -143,6 +145,8 @@ Flow Agents currently ships five canonical policy classes. Each policy class has
 - `off`: silent (exits 0, no stderr).
 - Escape hatch: in `block` mode the same goal-fit gap is refused up to `FLOW_AGENTS_GOAL_FIT_MAX_BLOCKS` (default 3) consecutive times, then released (exit 0 with a loud notice) so a genuinely-unsatisfiable goal cannot trap the agent. A changing gap resets the streak.
 
+**FlowDefinition-driven claim selection (ADR 0016 Abstraction A)**: When `current.json` resolves an active flow/step, `bundleEnforcement`'s claim-selection predicate (`isSelectedClaim`) is a **union**: `workflow.*`-prefixed claims are always selected as a baseline floor, and the active gate's declared `claimType` set (from `expects[].bundle_claim.claimType`, e.g. `builder.verify.tests`) is selected *in addition to* that floor — never instead of it. An earlier design used a pure if/else (declared types selected only when a FlowDefinition was active, with no `workflow.*` fallback) and was found in PR #215 to compose into a HIGH-severity gate-bypass chain: a forged `current.json` pointing at an `expects: []` flow made the if/else select zero claims, silently skipping all re-derivation, tamper-detection, and high/critical enforcement. The union floor closed that chain and is a **permanent** design decision, not a transitional step toward the if/else — see [ADR 0016](../adr/0016-three-hard-boundary-model.md) and the PR #215 post-mortem in [ADR 0015](../adr/0015-flow-flow-agents-boundary-reconciliation.md). Consequently, an active FlowDefinition whose gate resolves to an **empty** `expects[]` is always a `HARD_BLOCK` (`gate misconfiguration: active FlowDefinition has empty expects[]...`) — an empty declared set is treated as a possible tampered flow definition, never as a legitimately-empty gate that quietly enforces nothing beyond the floor.
+
 **Capture cross-reference (capture-first determinism)**: For each `evidence.checks[]` of `kind:"command"` claiming `status:"pass"` that carries a `command`, the gate cross-references the deterministic capture log (`command-log.jsonl`, §2.5) *before* trusting the model's claim:
 
 1. **Log shows the command ran and FAILED** → this is a caught false-completion → a blocking goal-fit gap (feeds the existing block/`MAX_BLOCKS` machinery).
@@ -186,9 +190,9 @@ Flow Agents currently ships five canonical policy classes. Each policy class has
 **Inputs consumed**:
 - `tool_name` + `tool_input.command` — identifies a command/shell execution (a command string present, with a command-shaped tool name; when no tool name is present but a command string is, it is still captured).
 - `tool_response` / `tool_output` / `error` — the host tool result (per §1, `postToolUse`); the source of the deterministically-observed outcome.
-- `.flow-agents/current.json` (`active_slug` / `artifact_dir`) then newest-mtime `state.json` — resolves the active artifact dir, the same way Workflow Steering and Stop-Goal-Fit do.
+- `.kontourai/flow-agents/current.json` (`active_slug` / `artifact_dir`) then newest-mtime `state.json` — resolves the active artifact dir, the same way Workflow Steering and Stop-Goal-Fit do.
 
-**Output**: appends one JSON object per line to `.flow-agents/<slug>/command-log.jsonl`:
+**Output**: appends one JSON object per line to `.kontourai/flow-agents/<slug>/command-log.jsonl`:
 
 ```json
 { "command": "npm test", "observedResult": "pass", "exitCode": 0, "capturedAt": "2026-06-23T00:00:00Z", "source": "postToolUse-capture" }
@@ -561,7 +565,7 @@ The CLI command is:
 flow-agents kit activate --adapter strands-local [--dest DIR] [--source-root DIR]
 ```
 
-This writes activated flow files to `.flow-agents/runtime/strands/flows/<kit-id>/<asset-id>.flow.json` and produces a parity-diagnostic `activation.json` (same schema as codex-local: `schema_version`, `adapter`, `supported_asset_classes`, `generated_runtime_files`, `skipped_assets`, `warnings`, `errors`).
+This writes activated flow files to `.kontourai/flow-agents/projections/strands/flows/<kit-id>/<asset-id>.flow.json` and produces a parity-diagnostic `activation.json` (same schema as codex-local: `schema_version`, `adapter`, `supported_asset_classes`, `generated_runtime_files`, `skipped_assets`, `warnings`, `errors`).
 
 ### 9.2 Steering context surfacing (AC2)
 
@@ -572,7 +576,7 @@ This writes activated flow files to `.flow-agents/runtime/strands/flows/<kit-id>
 ```
 hooks = FlowAgentsHooks(workspace=".")
 system_prompt = base_prompt + hooks.steering_context()
-# steering_context() includes KIT FLOWS section if .flow-agents/runtime/strands/flows/ is populated
+# steering_context() includes KIT FLOWS section if .kontourai/flow-agents/projections/strands/flows/ is populated
 ```
 
 **TypeScript usage**:
@@ -580,14 +584,14 @@ system_prompt = base_prompt + hooks.steering_context()
 ```typescript
 const hooks = new FlowAgentsHooks({ workspace: "." });
 const systemPrompt = basePrompt + hooks.steeringContext();
-// steeringContext() includes KIT FLOWS section if .flow-agents/runtime/strands/flows/ is populated
+// steeringContext() includes KIT FLOWS section if .kontourai/flow-agents/projections/strands/flows/ is populated
 ```
 
 ### 9.3 Co-existence with codex-local
 
 The `codex-local` and `strands-local` runtime directories are independent:
 
-- `codex-local` writes to `.flow-agents/runtime/codex/`
-- `strands-local` writes to `.flow-agents/runtime/strands/`
+- `codex-local` writes to `.kontourai/flow-agents/projections/codex/`
+- `strands-local` writes to `.kontourai/flow-agents/projections/strands/`
 
 Running either adapter does not affect the other's runtime directory. Both adapters skip non-flow asset classes (skills, docs, adapters, evals, assets) with `reason: "asset class is diagnostic-only for <adapter>"`.

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)