# V1 Product Graph + Builder Workbench — TODOS (2026-08-04)

> **Naming, official 2026-08-04:** the omnipresent assistant this file builds
> for is called **Eve** (collision-checked; no prior "Eve" in the repo). Her
> coding agent is **OpenAI Codex CLI** via `tools/eve-codex-agent.mjs` — see
> `V1/OMNIPRESENT_ASSISTANT_DESIGN_2026-08-03.md` §12. References to "the
> assistant" below mean Eve; the original "(Claude Code)" note reflects the
> historical dogfood session, superseded for the autonomous loop.

Deep restructuring of the assistant's product-knowledge representations into ONE
unified, typed, content-addressed property graph (phases 0–8) — extended into a
full builder workbench (phases 9–15): Eve, the omnipresent assistant, becomes an
active co-builder that can create and edit tasks, issues, decisions, and content
briefs from inside the app while walking the product, persisted so a coding
agent (Codex CLI via Eve's harness) picks work up from the database, with
feature and architecture discussions, ADRs, and graph visualization in-app. The
user wears three hats — builder, product manager, content creator — and the
workbench serves all three from the same graph. Every product artifact
(features, e2e journeys, docs, architecture/design docs, TODOS files, anchors,
tours, invocation points, routes) lives in the graph with explicit edges, one
validator, one version, and queryable projections in Postgres AND Neo4j.

## The two-plane architecture (the load-bearing design decision)

Everything below hangs off one split that keeps the system honest:

- **Knowledge plane (derived, read-only):** everything compiled from the repo —
  features, journeys, docs, TODOS checkboxes, architecture docs, anchors, tours,
  routes. Source of truth is CODE; the artifact is content-addressed;
  Postgres/Neo4j are disposable projections. Nothing writes to this plane at
  runtime, ever.
- **Intent plane (live, writable):** work items, issues, proposals, architecture
  decisions (ADRs), discussion threads, content briefs — born in conversation,
  DB-native in Postgres, event-sourced, referencing knowledge-plane node ids.
  This is what the assistant writes and what coding agents pick up.
- **Promotion is the only bridge:** intent becomes knowledge ONLY by traveling
  through code (an agent or human lands a PR; the artifact recompiles; the new
  nodes/edges appear). A work item is proven DONE by the knowledge plane
  changing — never by self-attestation. This one rule preserves every existing
  invariant (artifact-is-truth, curation-in-reviewed-code, fail-loud) while
  making the whole thing writable from inside the app.

**Process discipline:** work these tasks one at a time, sequentially, per
CLAUDE.md Task Verification rules. The checkbox is the sole source of truth.
Each `[ ]` → `[x]` requires reading the specific code in the current session.

## Why (signs of strain in the current shape)

- Five parallel node vocabularies, one implicit ontology: features/flows
  (curated catalog), journeys/checks (e2e inventory), docs pages (search
  corpora + docs-center registry), anchors, tours, invocation points each have
  their own id space; only catalog↔journey has real edges. "Which docs pages
  document flow X", "which anchors belong to feature Y", "which tours walk
  domain Z" are unanswerable today.
- Composition happens at runtime in the BFF (`journey-inventory.ts`) with a
  bespoke merge and a bespoke analyzer per concern (flatten, integrity,
  traceability, coverage). Every new representation adds another hand-rolled
  step.
- Versioning is string-stitched (`${FEATURE_CATALOG_VERSION}+e2e.${hash}`) — it
  does not scale to a third source.
- Route-overlap linkage is a heuristic buried inside `buildVerifyEdges` instead
  of a graph join.

## Current state (inputs to the restructure — read these first)

- `libs/oshun/shell-assistant/src/feature-catalog.ts` — curated catalog
  (v2026-08-04.1, 5 surfaces, 19 domains), `flattenFeatureCatalog`,
  `validateFeatureCatalog`, `CatalogEdgeKind = contains|follows|verifies`.
- `apps/oshun/bff/src/assistant/generated/e2e-journey-inventory.json` — 712
  journeys / 5,880 checks, AST-mined by
  `tools/build-assistant-journey-inventory.mjs`, contentHash fc0881552b66.
- `apps/oshun/bff/src/assistant/journey-inventory.ts` — runtime composition,
  `buildVerifyEdges` (4 signals), `checkCatalogGraphIntegrity`,
  `analyzeCatalogTraceability` (1,117 edges; 712/712 mapped; 19/19 domains;
  30/35 flows verified + 5 waived).
- `apps/oshun/bff/src/assistant/e2e-curation-map.ts` — ~120 group aliases, 17
  file-level flow aliases, 5 reasoned waivers.
- `apps/oshun/bff/src/assistant/docs-search.ts` +
  `generated/docs-search-corpus.*.jsonl` (member/full corpora), built by
  `tools/build-assistant-docs-search.mjs`.
- `libs/oshun/shell-assistant/src/assistant-anchors.ts` — anchor registry.
- Curated tours + tour submissions (`tour-store.ts`), invocation points
  (`apps/oshun/web/src/navigation/assistant-entry.ts`, 32 migrated sites).
- Checkbox TODOS corpus: `TODOS/phase-<n>.md`, root `*_TODOS_*.md` (including
  THIS file), and product-tree TODOS — structured phase/task/checkbox data.
- Architecture & design docs: `V1/ARCHITECTURE.md`, `V1/features.md`,
  `V1/OMNIPRESENT_ASSISTANT_DESIGN_2026-08-03.md`, `docs/`, domain proposals —
  prose sources for `document` nodes.
- Durable audit store pins graph version per run (`audit-store.ts`).
- Reusable workbench machinery already shipped this session: the
  ActionConfirmBridge (do-tier confirmation), plan entitlements, telemetry sink
  (allowlist-by-shape), feedback/tour stores (durable snapshot-store pattern),
  pageContext, structured navigateTo — Phases 10–14 compose these instead of
  building second mechanisms.

## Target invariants (hold at every phase boundary)

- The checked-in composed artifact is the single source of truth. Postgres and
  Neo4j are PROJECTIONS of it — rebuildable from the artifact at any time, never
  hand-edited, never authoritative.
- Curation stays code: alias/waiver tables compile to `curated`-provenance edges
  under the same PR-review gate. No curation lives only in a database.
- Fail-loud everywhere: unknown node refs, unmapped journeys, stale waivers,
  non-contiguous order, and provenance-less nodes/edges are CI failures, not
  warnings.
- Existing endpoints keep their response shapes during migration (adapters over
  the graph), so no consumer breaks mid-way.
- TOTALITY invariants carry over unchanged: 712/712 journeys mapped (or the
  then-current count), every curated domain verified, every unverified flow
  waived with a reason, zero stale waivers, zero integrity errors.
- Two-plane rule: the knowledge plane is never written at runtime; the intent
  plane is never the source of truth for what the product IS — only for what it
  should become. Closure of intent requires an observed knowledge-plane change
  (Phase 12.5), never self-attestation.
- Every intent-plane mutation is an actor-attributed, append-only event with
  conversation provenance. No anonymous writes, no history edits.
- Builder-scope boundary: intent-plane tools, queues, and the graph explorer are
  builder/operator-scoped. Members keep exactly the assistant they have.

---

## Phase 0 — Graph kernel: `libs/oshun/product-graph` (assessment item 1)

One typed property-graph schema + generic validation/traversal, extracted from
what `feature-catalog.ts` + `journey-inventory.ts` already do.

- [x] 0.1 Scaffold the library: `libs/oshun/product-graph/` with `project.json`,
      `package.json`, `tsconfig.json`, tsup build, vitest target; path mapping
      in `tsconfig.base.json`; catalog: deps only.
- [x] 0.2 Node model:
      `ProductGraphNode { id, kind, title, detail, attrs,     provenance }` with
      `kind: 'surface' | 'domain' | 'feature' | 'flow' | 'step' | 'journey' | 'check' | 'docPage' | 'document' | 'task' | 'anchor' | 'tour' | 'invocationPoint' | 'route' | 'workItem' | 'decision' | 'thread' | 'contentBrief'`.
      The compiled artifact may contain ONLY knowledge-plane kinds (everything
      before `workItem`); the intent-plane kinds share the same type vocabulary
      so projections and the visualizer treat both planes uniformly, and the
      validator enforces the split (0.5). `attrs` is a kind-discriminated union
      (e.g. flow carries `outcome`; step carries `action`/`route`/`anchorId`;
      journey carries `app`/`file`/`group`; docPage carries `slug`/`audience`;
      document carries `docType`/`path`; task carries `file`/`phase`/`checked`;
      route carries `path`/`surfaceId`) — NOT a stringly `Record`.
- [x] 0.3 Edge model: `ProductGraphEdge { from, to, kind, provenance }` with
      `kind: 'contains' | 'follows' | 'verifies' | 'documents' | 'anchors' | 'tours' | 'launches' | 'visits' | 'tracks' | 'decides' | 'discusses' | 'supersedes'`.
      Document the direction convention per kind in the fileoverview (e.g.
      `verifies`: journey→curated; `documents`: docPage/document→
      flow/feature/domain; `anchors`: step/invocation point→anchor; `visits`:
      journey/step/docPage/tour→route; `launches`: invocationPoint→
      flow/feature; `tracks`: task/workItem→any node it concerns; `decides`:
      decision→affected nodes; `discusses`: thread→its anchor node;
      `supersedes`: decision→decision, acyclic).
- [x] 0.4 Provenance model:
      `Provenance { source: 'curated' | 'e2e-mined' | 'docs-registry' | 'todos-mined' | 'arch-docs-mined' | 'anchor-registry' | 'tour-registry' | 'invocation-registry' | 'route-derived' | 'intent', contentHash }`
      — REQUIRED on every node and edge; the validator rejects its absence.
      `intent` marks intent-plane records when they are materialized as graph
      nodes for projection/visualization (Phase 15) — never in the artifact.
- [x] 0.5 Kind-aware validator `validateProductGraph(graph)` generalizing
      today's `checkCatalogGraphIntegrity`: unique ids; contiguous DFS order
      within the containment tree; every edge endpoint exists; per-kind edge
      endpoint rules (a `verifies` edge only journey→flow/domain, a `contains`
      edge only along the kind hierarchy, `visits` only INTO `route` nodes,
      etc.); containment is a forest (no cycles, single parent); the compiled
      artifact contains ONLY knowledge-plane kinds (an intent-plane kind in the
      artifact is an error); returns
      `{ ok: true } | { ok: false, errors: string[] }` with every error naming
      the offending id.
- [x] 0.6 Generic traversal/rollup helpers: `children(id)`, `ancestors(id)`,
      `descendants(id)`, `edgesFrom(id, kind?)`, `edgesTo(id, kind?)`,
      `subgraph(rootId)`, and `propagateUp(seedIds, edgeKind)` (the coverage
      propagation used by traceability, made generic). Index-backed (Maps built
      once per graph), not O(n) scans per call.
- [x] 0.7 Content addressing: `hashGraphSection(nodes, edges)` (stable canonical
      JSON → sha256, 12-hex prefix like the journey inventory) and
      `composeVersion(sections)` producing a Merkle-style version string:
      per-source hash + composed hash. Deterministic across key order.
- [x] 0.8 Kernel spec with negative controls: duplicate id, dangling edge,
      backwards `verifies`, cycle in containment, missing provenance,
      non-contiguous order — each must fail with a message naming the id. Plus
      determinism: hashing the same graph twice with shuffled key order yields
      the identical version.
- [x] 0.9 Adversarial pass on the kernel (mandatory grep + read every exported
      function) before commit; build + lint green.

## Phase 1 — First two compilers: curated + e2e (assessment item 2, part 1)

Pure, independently-testable functions `(sourceData) → { nodes, edges }` with
provenance stamped per source.

- [x] 1.1 `compileCuratedCatalog(FEATURE_CATALOG)` in product-graph (or a thin
      `libs/oshun/product-graph/src/compilers/curated.ts` importing from
      shell-assistant): emits surface/domain/feature/flow/step nodes +
      contains/follows edges, provenance `curated`. Node ids preserved exactly
      so existing audit-store rows keep matching.
- [x] 1.2 `compileE2eInventory(inventoryJson)`: emits journey + check nodes
      (checks become real `check` nodes instead of synthesized steps) +
      contains/follows edges, provenance `e2e-mined` with the inventory
      contentHash. Journey ids preserve today's `e2e.<app>.<slug>` scheme.
- [x] 1.3 Curation compiler `compileCurationEdges(map, graph)`: turns
      `E2E_GROUP_CURATION` / `E2E_FILE_CURATION` into `verifies` edges with
      provenance `curated`; unknown targets are compile ERRORS (same semantics
      as today's curationTargetErrors). Waivers compile to a typed waiver set
      carried alongside the graph (not silent).
- [x] 1.4 Intrinsic + route-overlap signals from `buildVerifyEdges` move into
      the composer as graph-native logic (route-overlap becomes a join via
      `visits` edges once Phase 2 lands; until then port the heuristic verbatim
      with a `route-derived` provenance).
- [x] 1.5 Compiler specs: golden counts against the live sources (712 journeys,
      5,880 checks, 19 domains), provenance presence, and a negative control per
      compiler (malformed source → loud error).

## Phase 2 — Routes as first-class nodes (assessment item 3)

- [x] 2.1 Route extraction compiler: collect every distinct route from (a)
      curated step `route` fields, (b) e2e journey/check route mentions (extend
      `tools/build-assistant-journey-inventory.mjs` to mine `page.goto`/router
      pushes into the inventory JSON if not already present), (c) docs pages
      front-matter routes (Phase 3 feeds this). Emit `route` nodes with
      normalized path attrs (param segments normalized like today's prefix
      normalization, e.g. `/tara/:id`).
- [x] 2.2 `visits` edges: step→route, journey→route, docPage→route, tour→route.
      Route-overlap verification becomes a genuine 2-hop graph join (journey
      —visits→ route ←visits— step —ancestor→ flow), replacing the Phase 1.4
      ported heuristic. Delete the heuristic once the join reproduces (or
      consciously supersedes) its edge set — diff the two edge sets in a spec
      and account for every difference before deletion.
- [x] 2.3 Route integrity rules in the validator: every `visits` edge lands on a
      route node; route paths are unique per surface; no route node is an orphan
      (at least one `visits` edge in).
- [x] 2.4 Spec: "everything that touches `/tara`" query returns features,
      journeys, docs, and tours in one call — assert against known-correct
      membership, not just non-emptiness.

## Phase 3 — Remaining compilers: docs, TODOS, architecture docs, anchors, tours, invocation points

- [x] 3.1 Docs compiler: from the docs-search corpus build (extend
      `tools/build-assistant-docs-search.mjs` to also emit graph nodes):
      `docPage` nodes (member + full audience attr) with `documents` edges to
      the curated flows/features/domains they describe. Linkage signals:
      explicit front-matter refs where present, route overlap via `visits`, and
      an explicit curated alias table for the remainder — SAME totality
      discipline as e2e curation (unmapped docs pages fail CI or carry a
      reasoned waiver).
- [x] 3.2 Anchors compiler: `anchor` nodes from the anchor registry; `anchors`
      edges from every curated step and invocation point that references one.
      Validator: anchor referenced ⇒ anchor exists (this subsumes the existing
      anchor-reference spec in shell-assistant).
- [x] 3.3 Tours compiler: `tour` nodes from curated tour plans; `tours` edges
      tour→flow/domain it walks; `visits` edges tour→route; approved tour
      submissions included with their own provenance marker in attrs (still
      `curated` source once approved).
- [x] 3.4 Invocation-points compiler: mine `openAssistantInvocation` point ids
      (extend the invocation-bus guard spec's source scan into a build tool that
      emits JSON); `invocationPoint` nodes + `launches` edges to the
      flow/feature each point opens onto + `anchors` edges where a point has a
      registered anchor.
- [x] 3.5 TODOS compiler: parse the checkbox corpus (`TODOS/phase-<n>.md`, root
      `*_TODOS_*.md`, product-tree TODOS) into `task` nodes (attrs: file, phase,
      checked state, text) with `contains` edges (document→phase-section→task)
      and `tracks` edges task→the graph nodes it concerns (explicit refs where
      the text names ids/routes/files; a curated alias table at FILE level for
      the rest, same totality discipline — every TODOS file mapped or waived;
      task-level linkage best-effort with an honest `unlinked` count, never
      guessed). Checkbox state is DATA, not judgment: the compiler records
      `[x]`/`[ ]` verbatim — verification remains a human/agent act per
      CLAUDE.md rules. THIS todos file becomes part of the graph it describes:
      the workbench manages its own backlog from day one (dogfooding).
- [x] 3.6 Architecture/design-docs compiler: `document` nodes for
      `V1/ARCHITECTURE.md`, `V1/features.md`, design docs, `docs/`, domain
      proposals, product reviews (attrs: docType
      `architecture|design|review|proposal|todos`, path, heading outline);
      `documents` edges to the domains/features/routes they describe
      (heading/front-matter refs + curated aliases, file-level totality);
      SHIPPED sections and dated decision paragraphs mined as attrs so Phase
      11's ADR workbench can backfill real `decision` records from them later —
      the compiler itself does NOT fabricate decisions.
- [x] 3.7 Per-compiler specs with golden counts + one negative control each;
      totality specs for docs (3.1), TODOS files (3.5), and architecture/design
      docs (3.6) mirroring the e2e TOTALITY test.

## Phase 4 — Composer, checked-in artifact, CI gates

- [x] 4.1 Composer `composeProductGraph(sections)`: merges all compiler outputs,
      runs the kind-aware validator, computes the Merkle version (per-source
      hashes + composed hash), returns the full graph or throws with every error
      listed.
- [x] 4.2 Build tool `tools/build-product-graph.mjs`: runs all compilers, writes
      ONE checked-in artifact
      `libs/oshun/product-graph/src/generated/product-graph.json` (or per-source
      sections + composed manifest if the single file exceeds review ergonomics
      — decide by actual size, document the choice). Deterministic output
      (stable ordering) so diffs are reviewable.
- [x] 4.3 Staleness gate: a spec (or CI step) re-runs the compilers and fails if
      the artifact on disk differs from the recomputed graph — the same
      commit-the-merge-before-regen discipline as docs-center, so the artifact
      can never silently rot.
- [x] 4.4 TOTALITY spec ported to the composed graph: every journey mapped,
      every docs page / TODOS file / architecture doc mapped-or-waived, every
      curated domain verified, every unverified flow waived, zero stale waivers,
      zero validator errors, version matches recomputed hashes.
- [x] 4.5 Adversarial pass over composer + build tool; commit + two-line push.

## Phase 5 — Consumers become views (assessment item 4, artifact half)

Existing endpoints keep their shapes; internals read the one graph.

- [x] 5.1 Audit store: `getComposedAssistantCatalogGraph()` becomes an adapter
      over the product graph (filter to surface/domain/feature/flow/step +
      journeys-as-flows, exactly today's composed shape). Version string
      preserved or migrated with an explicit audit-run migration note (runs pin
      versions — decide: keep old format string as an alias, or bump and let
      in-flight runs complete on their pinned version; write the decision down
      in the design doc).
- [x] 5.2 Traceability endpoint `GET /v1/assistant/catalog-traceability`:
      `analyzeCatalogTraceability` reimplemented on kernel helpers
      (`edgesTo`/`propagateUp`); response shape unchanged; spec diffs old vs new
      report on the same inputs.
- [x] 5.3 Feature-catalog endpoint serves the graph-derived view;
      `getTracedAssistantCatalogGraph` becomes `subgraph` + edge filter.
- [x] 5.4 Docs search: result grouping/annotation joins through `documents`
      edges (e.g. each hit can name the curated flow it documents); member vs
      full corpus boundary UNCHANGED (information-disclosure boundary — the
      graph must not leak full-corpus titles to member queries; add a spec
      asserting exactly that).
- [x] 5.5 Coverage board (web `AuditCoverageBoard`): unchanged API; verify live
      in the browser (Claude in Chrome) after the BFF switch, per the
      frontend-testing rule.
- [x] 5.6 Delete the superseded bespoke code paths in `journey-inventory.ts`
      once all consumers read the graph (keep the file as the adapter home or
      fold it away — whichever leaves fewer moving parts); no dead exports left
      behind (inert-field pass).
- [x] 5.7 Full suites green: BFF assistant, shell-assistant, product-graph, web
      assistant specs; commit + two-line push.

## Phase 6 — Postgres projection (assessment item 4, DB half A)

The relational projection for ad-hoc SQL analysis and BFF-local joins. Artifact
remains the source of truth; the tables are rebuildable.

- [x] 6.1 Schema in `oshun_dev`:
      `product_graph_node (id text pk, kind     text, title text, detail text, attrs jsonb, provenance_source text,     provenance_hash text, graph_version text)`,
      `product_graph_edge (from_id     text, to_id text, kind text, provenance_source text, provenance_hash     text, graph_version text, primary key (from_id, to_id, kind))`
      with FKs to node, plus indexes on `(kind)`, `(to_id, kind)`, and a GIN
      index on `attrs`. Migration file follows the BFF's existing migration
      convention (find and match it — do not invent a second mechanism).
- [x] 6.2 Idempotent loader `loadProductGraphIntoPostgres(pool, graph)`:
      transactional full-replace per `graph_version` (delete+insert in one tx,
      or staged table swap) — NOT incremental patching; the artifact is truth.
      Loader refuses (fail loud) if the artifact's composed hash doesn't
      validate.
- [x] 6.3 Wire into BFF boot behind an env flag (e.g.
      `OSHUN_PRODUCT_GRAPH_PG_SYNC=1`): on boot, compare stored `graph_version`
      to the artifact; load only on mismatch. No cron needed — the artifact only
      changes with a deploy.
- [x] 6.4 Query pack as tested SQL (a spec running against real Postgres, like
      the workbench-kit harnesses): recursive-CTE descendants of a domain;
      coverage rollup (verified flows per domain) matching the TypeScript
      analyzer's numbers EXACTLY on the same artifact; "routes with journeys but
      no docs"; "features with no verifying journey and no waiver" (must return
      empty — the SQL restatement of TOTALITY); "unchecked TODOS tasks under a
      domain with their tracking documents" (the repo backlog viewed through the
      graph).
- [x] 6.5 Negative controls: loader rejects a graph whose hash was tampered;
      version-mismatch reload actually replaces rows (assert a row from the old
      version is gone).

## Phase 7 — Neo4j projection (assessment item 4, DB half B)

The native graph projection for exploratory/Cypher analysis, using the compose
`graph` profile that already exists.

- [x] 7.1 Verify the `graph` profile:
      `docker compose -f     docker/docker-compose.dev.yml --profile graph up -d`
      brings up Neo4j; record connection env (`OSHUN_PRODUCT_GRAPH_NEO4J_URL`,
      auth) in root `.env.example` alongside the existing conventions.
- [x] 7.2 Loader `tools/load-product-graph-neo4j.mjs` (build-tool, not BFF
      runtime — Neo4j is an analysis surface, not a serving dependency):
      full-replace per version (`MATCH (n:ProductGraph) DETACH DELETE n` scoped
      by a `graphVersion` property, then batch `UNWIND` creates). Node label per
      kind (`:Flow`, `:Journey`, `:Route`, …) plus a common `:ProductGraph`
      label; relationship type per edge kind (`:CONTAINS`, `:VERIFIES`,
      `:DOCUMENTS`, `:ANCHORS`, `:TOURS`, `:LAUNCHES`, `:VISITS`, `:FOLLOWS`,
      `:TRACKS`, `:DECIDES`, `:DISCUSSES`, `:SUPERSEDES`); provenance + version
      as properties on both.
- [x] 7.3 Constraints/indexes before load: unique constraint on
      `ProductGraph.id`; index on each kind label's `id`; assert constraint
      creation succeeded before loading (fail loud, no partial loads).
- [x] 7.4 Cypher query pack, executed by a gated spec (skips honestly with a
      `not_configured`-style message when Neo4j isn't up; runs for real under
      the `graph` profile): domain coverage rollup matching the TypeScript
      analyzer EXACTLY; shortest path feature→journey→route; orphan scan (any
      `:ProductGraph` node with no edges — must be empty); the `/tara`
      everything-that-touches query from 2.4 expressed as a 1-hop route join;
      one cross-source neighborhood query (open TODOS tasks + docs + journeys +
      decisions for one domain in a single traversal).
- [x] 7.5 Docs: a short `libs/oshun/product-graph/README.md` section — how to
      bring up Neo4j, load, and the query pack; explicitly states the
      artifact-is-truth / projection-is-disposable rule.

## Phase 8 — Curation-as-edges cleanup, docs, memory

- [x] 8.1 `e2e-curation-map.ts` tables become compiler INPUT only (already true
      after 1.3) — confirm nothing else imports them; waivers surface in the
      traceability report exactly as today (5 waivers with reasons, stale
      detection intact).
- [x] 8.2 Design doc: append the SHIPPED section for the restructure to
      `V1/OMNIPRESENT_ASSISTANT_DESIGN_2026-08-03.md` (what moved where, the
      version scheme, the projection rule, endpoint compatibility notes).
- [x] 8.3 Memory file updated (`oshun-v1-omnipresent-assistant.md`): new
      package, artifact path, loader flags, query-pack locations, any new
      landmines found.
- [x] 8.4 Final adversarial verification pass over
      `libs/oshun/product-graph/src/` (mandatory grep, every public + every
      delegated-to private function read, silent-stub scan, test coherence: the
      coverage-rollup specs must assert exact known-correct numbers, not
      shapes).
- [x] 8.5 Full green sweep (product-graph, BFF assistant, shell-assistant, web,
      staleness gate) + commit + MANDATORY two-line push
      (`git push origin <branch>` then `git push origin <branch>:main`), verify
      `origin/main` advanced.

---

Phases 9–15 are the workbench (intent plane). Sequencing: 9–11 can begin once
Phase 4's artifact lands (9.4 needs Phase 6's Postgres projection for ref
validation — stub nothing, order the work instead); 12 needs 9–10; 13–15 need
the phases they visualize/project.

## Phase 9 — Intent plane: workbench data model (event-sourced, PG-native)

The writable half. Lives in Postgres from birth (NOT in the artifact); every
record references knowledge-plane node ids; every mutation is an event.

- [x] 9.1 Tables (BFF migration convention):
      `work_item (id, kind     'task'|'issue'|'idea'|'content-brief', title, body, status, priority,     created_by jsonb, lease jsonb, expectation jsonb, graph_refs text[],     created_at, updated_at)`;
      `decision (id, title, status     'draft'|'proposed'|'accepted'|'superseded'|'rejected', context, options     jsonb, decision, consequences, supersedes_id, graph_refs text[])`;
      `thread (id, anchor_node_id, title)` +
      `thread_message (thread_id, seq,     actor jsonb, body, created_at)`;
      `workbench_event (seq bigserial,     entity_kind, entity_id, event_type, actor jsonb, payload jsonb,     conversation_ref, created_at)`
      — the append-only ledger EVERY write goes through. Event-sourced for real:
      current rows are a projection of the ledger, and a spec proves
      `replay(ledger) == rows` (make the invariant checkable by comparison, not
      by reading code).
- [x] 9.2 Actor model: every event carries
      `{ type: 'human' | 'assistant' | 'coding-agent', id, conversationRef?,     model? }`
      — who did it, in which conversation, with which model. The store refuses
      anonymous writes (fail loud).
- [x] 9.3 Lifecycle state machines in code (workbench-kit style — look for an
      existing kit module to compose with before writing a second machine): work
      item
      `draft → triaged → ready → leased → in-progress → in-review →     shipped → verified`,
      with `parked`/`rejected` exits; illegal transitions refuse loudly with the
      attempted edge named. The `verified` transition is MACHINE-ONLY (granted
      by the Phase 12.5 artifact-diff verifier) — unreachable through any API
      caller including the assistant. Decisions:
      `draft → proposed → accepted | rejected`, accepted → `superseded` only via
      a superseding decision.
- [x] 9.4 graph_refs integrity: refs validated against the knowledge-plane
      projection on write (unknown ref → refuse, id named). When a NEW artifact
      version drops a referenced node, the item is flagged `orphaned-ref` —
      surfaced in the workbench view and traceability report, never silently
      kept or deleted.
- [x] 9.5 Store + service specs against real Postgres (calibrated harness with
      negative controls that must come back red: illegal transition, anonymous
      actor, unknown graph ref, direct-to-verified attempt, replay mismatch).

## Phase 10 — Assistant write tools: capture intent in conversation

The omnipresent assistant becomes a co-builder: while walking the product (audit
mode, a discussion, or free chat) it can add/edit tasks, issues, and briefs —
with the human confirming every write.

- [x] 10.1 Agent tools `create_work_item`, `update_work_item`, `open_thread`,
      `comment_thread`, `link_graph_refs` on the BFF agent loop — strict
      schemas; the current pageContext (route → graph node via the `visits`
      join) auto-suggests graph_refs which the model must surface for
      confirmation, never silently apply.
- [x] 10.2 Every mutating tool rides the existing ActionConfirmBridge (do-tier):
      the user SEES "create issue: <title> → linked to <nodes>" and confirms
      in-UI before the write lands; unconfirmed proposals expire. One
      confirmation mechanism, not two.
- [x] 10.3 AuthZ + entitlements + telemetry: builder/operator scope required for
      all intent-plane writes (NOT member-wide); plan-entitlement gates reused;
      telemetry sink records tool usage allowlist-by-shape (no free-text
      leakage).
- [x] 10.4 Provenance capture: the confirmed write's event carries the
      conversation ref + assistant turn id — every task/issue traces back to the
      exact discussion that created it.
- [x] 10.5 Transport-level route specs + one LIVE browser pass (Claude in
      Chrome): walk a domain in audit mode, say "log an issue about X", confirm,
      then read the item back out of the Postgres rows and see it in the
      workbench view (assert the rows, not just the UI). _(2026-08-04: transport
      half DONE — `workbench-agent-tools.integration.spec.ts` drives the tools
      through the REAL toolset + confirm bridge at real Postgres: park → no row,
      confirm → row + ledger provenance (conversationRef/turnId/model), decline
      → no row, one-shot confirm, ghost-ref failed execution.)_ _(2026-08-04
      LIVE LLM BROWSER PASS RUN — credential blocker lifted with an OpenRouter
      key, `OSHUN_ASSISTANT_PROVIDER=openrouter`, `deepseek/deepseek-v4-flash`.
      Member leg: real signup → "Start my feature audit" → `audit_begin` live
      (747-flow composed catalog, coverage restated), agent started the shell
      tour (TourPlayer honest-skip states, Next/Back/End, outcome → replanned
      ADJUSTED tour), "mark visited" → durable snapshot row in Postgres
      (`audit-473d9379`, 1 visited/746 pending, real note) → the
      /assistant/audit board rendered the same run. Builder leg: admin console
      Copilot → "log an issue about the Tara enroll flow" → `create_work_item`
      PARKED (row count 0 asserted), Approve on the confirm card →
      `wi-5861c8bd…` in `work_item` with ledger actor
      `assistant:operator-studio-01` + model + turnId + conversationRef →
      "what's open on tara?" → `list_work_items` cited the new row AND spotted a
      near-duplicate → item verified riding the workbench-board payload. Bonus:
      the pass caught the always-on catalog-drift warning (getCoverage compared
      the composed run pin against curated-only FEATURE_CATALOG_VERSION) — fixed
      to `this.graph.version` same day.)_

## Phase 11 — Discussion & decision workbench (features + architecture)

Discuss features and architecture IN the app; record real ADRs; keep every
discussion attached to the graph nodes it concerns.

- [x] 11.1 Threads anchored to ANY graph node (feature, flow, route, document,
      task): open the assistant on /tara, say "let's discuss the courses
      feature" → a thread anchored to `tara.courses`, with the assistant
      grounded in graph-neighborhood retrieval (docs via `documents`, journeys
      via `verifies`, routes via `visits`, open work via `tracks`) + docs search
      — answers cite graph evidence, and the context pack is the NEIGHBORHOOD,
      size-bounded, not the whole graph.
- [x] 11.2 ADR model as first-class `decision` records: context, options
      considered (each with tradeoffs), decision, consequences, status,
      `supersedes` chain (acyclic, validator-checked); `decides` refs to
      affected nodes. The assistant DRAFTS an ADR from a thread ("summarize this
      into a decision") — it stays `draft` until a human proposes/ accepts via
      confirmed action; acceptance is never autonomous.
- [x] 11.3 Feature proposals: a work_item whose `expectation` payload carries a
      structured proposed change in catalog shape (new flow/feature sketch),
      validated against the kernel types at write time — so the proposal is
      machine-readable by the coding agent that implements it AND by the Phase
      12.5 verifier that closes it.
- [x] 11.4 Discussion → intent wiring: from any thread, spawn work items /
      decisions with one confirmed action; the thread ref lands in the event
      ledger (the "why" permanently attached to the "what").
- [x] 11.5 Specs: neighborhood-grounding assertions (context pack contains the
      neighborhood and cites it), ADR lifecycle negative controls,
      supersedes-chain acyclicity, draft-cannot-self-accept. _(2026-08-04: all
      green vs real PG in `discussion-workbench.integration.spec.ts`; the
      conversational LLM-driven leg of 11.1 shares 10.5's provider-credential
      blocker — the grounding tool, pack, and citations are spec-proven.)_

## Phase 12 — Coding-agent handoff loop (DB → agent → PR → verified)

The loop that makes intent real: a coding agent (Claude Code) picks work from
the DB, does it in the repo, and the knowledge plane proves completion.

- [x] 12.1 Work-queue API: `GET /v1/workbench/queue` (ready items, priority
      ordered, graph_refs included); `POST /v1/workbench/items/:id/lease`
      (idempotent lease with TTL + agent identity — two agents cannot hold one
      item; expired leases return to ready); `POST .../report`
      (progress/completion: branch, commits, PR link, notes). All events, all
      actor-attributed.
- [x] 12.2 Task-brief generator: for a leased item, compile a self-contained
      brief — the item + thread history + decision context + the graph
      NEIGHBORHOOD around its graph_refs (flows, routes, docs, journeys,
      anchors, and the source-file pointers from provenance) — so a fresh agent
      session starts with zero spelunking. Deterministic, size-bounded,
      truncation logged (no silent caps).
- [x] 12.3 Agent access surface: an `oshun-workbench` MCP server (stdio,
      `tools/workbench-mcp/`) exposing queue/lease/brief/report as MCP tools,
      plus a CLI fallback (`pnpm workbench next|lease|brief|report`) — Claude
      Code connects with one connector entry; any other agent can too. Auth via
      a scoped workbench token, not a shared admin secret.
- [x] 12.3b LIVE dogfood check — Claude (the agent working this file) actually
      connects and uses it, not just unit tests: register the server in the
      repo's `.mcp.json` (project-scope, checked in, token via env), restart /
      reconnect so the `mcp__oshun-workbench__*` tools appear in-session, then
      exercise EVERY tool over the real connection against real seeded data:
      list the queue, lease an item, fetch its brief and confirm the brief
      contains the item's graph neighborhood, post a progress report, attempt a
      second lease on the same item (must refuse — lease conflict over MCP, not
      just in the store spec), let a short-TTL lease expire and see the item
      return to ready, and attempt a write with a bad token (must refuse). Run
      the same sweep once through the CLI fallback. Record the actual tool-call
      transcript (commands + responses) in the design doc — this task is NOT
      checkable from unit tests or from reading code; it requires the live
      session evidence.
- [x] 12.4 Report-back discipline: reports append events (never edit history);
      completion moves the item to `in-review`, and to `shipped` when the PR
      lands on main (verify by observing the repo — commit SHA/merge — not by
      trusting the report). NEVER to `verified`.
- [x] 12.5 HONEST CLOSURE — the promotion contract made executable: `verified`
      is granted only by the artifact-diff verifier, which runs when a new
      knowledge-plane artifact version appears and checks the item's
      machine-readable `expectation` against the diff (expected nodes/edges
      present, TOTALITY still green, referenced journeys exist in the e2e
      inventory). Shipped items whose expectation is unmet flag
      `ship-verify-gap` — surfaced, never silently closed. Items without a
      machine-checkable expectation stay honestly at `shipped` with the gap
      stated (an honest seam, not a fake verify).
- [x] 12.6 End-to-end proof (flagship run): create an issue in-app via the
      assistant (Phase 10), lease it from a REAL Claude Code session via the MCP
      tools proven in 12.3b, implement, push, rebuild the artifact → the item
      auto-verifies (watch the status walk leased → in-progress → in-review →
      shipped → verified in the event ledger). Document the full run in the
      design doc.

## Phase 13 — In-app visualization (graph, decisions, roadmap)

- [x] 13.1 Graph explorer at `/assistant/graph` (builder-scoped): hierarchical
      containment view + neighborhood view for any node (self-contained
      canvas/SVG renderer in the shell design system, no external libs);
      overlays for e2e coverage (verified/waived/unverified), docs coverage,
      open work items, decision status — rendering the SAME analyzer numbers the
      BFF serves, never recomputed ad hoc client-side.
- [x] 13.2 Node inspector: click any node → edges by kind, provenance (source +
      hash), linked work items/decisions/threads, and jump-offs (open the route,
      open the doc, open the spec file path).
- [x] 13.3 Work views: kanban/roadmap lens over work_items (status columns,
      domain swimlanes from graph_refs); ADR timeline with supersedes chains; a
      "what changed" view diffing two artifact versions (nodes/edges
      added/removed — promotion history made visible).
- [x] 13.4 Assistant-driven navigation: "show me everything unverified in tara"
      → the assistant deep-links the explorer with the right filter (structured
      navigation + invocation point, same pattern as navigateTo).
- [x] 13.5 Frontend verification LIVE in the browser (Claude in Chrome) per repo
      rule: render, filter, inspect, overlay toggles — visual AND functional.

## Phase 14 — Content-creator lane

The same loop for content: briefs are intent, published content is knowledge.

- [x] 14.1 `content-brief` work items: target domain/flow/route refs, audience,
      goal, outline — the assistant drafts briefs from discussion via the Phase
      10 machinery verbatim (confirmed writes, provenance).
- [x] 14.2 Grounded drafting: the assistant drafts content FROM the graph
      (neighborhood + docs-search retrieval, citations to graph nodes); drafts
      attach to the brief's thread — never auto-published.
- [x] 14.3 Handoff to existing pipelines: dispatch a brief to the Tara content
      workbench / studio authoring flows (graph_refs say where the content
      belongs); dispatch is a confirmed action that records the target system's
      id for round-trip tracking.
- [x] 14.4 Closure: published content re-enters the knowledge plane via the
      docs/content compilers on next build → the brief's expectation check
      verifies it (Phase 12.5 machinery — content briefs close honestly too).
- [x] 14.5 Specs + one live browser pass: discuss → brief → draft → dispatch →
      publish-path → verify. _(2026-08-04: `content-lane.integration.spec.ts`
      3/3 at real PG covers every machinery leg through the same toolset +
      confirm bridge the live assistant runs, incl. the honest gap control; the
      conversational browser leg shares 10.5's provider-credential blocker.)_

## Phase 15 — Cross-plane projections & unified queries

- [x] 15.1 Knowledge↔intent joins in Postgres (intent already lives there): an
      unnested `work_item_graph_refs` view + SQL pack additions — "open work
      touching /tara", "accepted decisions whose refs are unverified flows",
      "unchecked TODOS tasks with no live work item" (the repo-backlog vs
      live-backlog reconciliation query — the two backlogs must be comparable,
      not parallel).
- [x] 15.2 Neo4j intent sync: extend the loader to project work_items,
      decisions, threads as `:WorkItem`/`:Decision`/`:Thread` nodes with
      `:TRACKS`/`:DECIDES`/`:DISCUSSES` relationships into the SAME graph db
      (property `plane: 'intent'`, synced from Postgres on demand). Projection
      rule intact: Postgres is the intent plane's truth; Neo4j remains
      disposable for BOTH planes.
- [x] 15.3 Cypher pack additions mirroring 15.1 with EXACTLY matching answers on
      the same data, including the reconciliation query in both engines.
- [x] 15.4 Design doc SHIPPED section + memory update for the whole workbench;
      final adversarial pass over all intent-plane + workbench code (mandatory
      grep, every public + delegated-to private function read, silent-stub scan,
      test coherence); full green sweep; commit + MANDATORY two-line push;
      verify origin/main advanced.

## Acceptance criteria (DONE when)

- One artifact, one validator, one Merkle version covers ALL compiled source
  kinds (features, e2e, docs, TODOS, architecture docs, anchors, tours,
  invocation points, routes); adding another source is "write a compiler +
  register it".
- Cross-representation queries work in three places with matching answers:
  TypeScript kernel helpers, Postgres SQL pack, Neo4j Cypher pack — for BOTH
  planes, including the repo-backlog vs live-backlog reconciliation.
- TOTALITY still enforced (journeys, docs pages, TODOS files, and architecture
  docs mapped-or-waived), plus the new integrity rules (provenance everywhere,
  visits-into-routes only, orphan-free, supersedes-acyclic,
  artifact-knowledge-kinds-only).
- The full builder loop works end-to-end and HONESTLY: discuss in-app →
  confirmed work item/decision with conversation provenance → coding agent
  leases via MCP → PR lands → artifact rebuilds → item auto-verifies by artifact
  diff (the Phase 12.6 flagship run, documented).
- Every intent-plane mutation is an evented, actor-attributed, replayable
  record; `verified` is unreachable except through the artifact-diff verifier.
- No existing member-facing endpoint changed shape; audit runs survived the
  version migration per the 5.1 decision; the superseded runtime-composition
  code is gone (no dead exports).

## Non-goals

- Neo4j (or Postgres analysis tables) as a serving dependency for member-facing
  requests — projections are for analysis, the workbench, and BFF-internal joins
  only.
- Editing the KNOWLEDGE plane through a database or at runtime — it stays
  code-derived; the intent plane is the writable surface, and promotion into
  knowledge always travels through a reviewed PR + artifact rebuild.
- Member-facing exposure of the workbench: intent-plane tools, queues, and the
  graph explorer are builder/operator-scoped. Members keep exactly the assistant
  they have today.
- A general project-management product: the work model stays minimal (work_item
  / decision / thread) and graph-anchored — no sprints, estimates, or burndown
  theater unless a real need lands one.
- Autonomous acceptance: the assistant drafts and proposes everywhere, but
  accepting decisions, confirming writes, and merging PRs remain human acts.
- Rewriting the docs-center generator — the docs compiler consumes its outputs.
- Studio's 486 web/desktop-only routes as curated flows (they stay governed via
  the operator cockpit; the `studio` domain's representative flow + studio e2e
  edges already cover the surface).
