Historical task source. The Eve task board holds current task state.
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— seeV1/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
buildVerifyEdgesinstead 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 bytools/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 bytools/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 fordocumentnodes. - 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.
- 0.1 Scaffold the library:
libs/oshun/product-graph/withproject.json,package.json,tsconfig.json, tsup build, vitest target; path mapping intsconfig.base.json; catalog: deps only. - 0.2 Node model:
ProductGraphNode { id, kind, title, detail, attrs, provenance }withkind: '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 beforeworkItem); 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).attrsis a kind-discriminated union (e.g. flow carriesoutcome; step carriesaction/route/anchorId; journey carriesapp/file/group; docPage carriesslug/audience; document carriesdocType/path; task carriesfile/phase/checked; route carriespath/surfaceId) — NOT a stringlyRecord. - 0.3 Edge model:
ProductGraphEdge { from, to, kind, provenance }withkind: '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). - 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.intentmarks intent-plane records when they are materialized as graph nodes for projection/visualization (Phase 15) — never in the artifact. - 0.5 Kind-aware validator
validateProductGraph(graph)generalizing today'scheckCatalogGraphIntegrity: unique ids; contiguous DFS order within the containment tree; every edge endpoint exists; per-kind edge endpoint rules (averifiesedge only journey→flow/domain, acontainsedge only along the kind hierarchy,visitsonly INTOroutenodes, 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. - 0.6 Generic traversal/rollup helpers:
children(id),ancestors(id),descendants(id),edgesFrom(id, kind?),edgesTo(id, kind?),subgraph(rootId), andpropagateUp(seedIds, edgeKind)(the coverage propagation used by traceability, made generic). Index-backed (Maps built once per graph), not O(n) scans per call. - 0.7 Content addressing:
hashGraphSection(nodes, edges)(stable canonical JSON → sha256, 12-hex prefix like the journey inventory) andcomposeVersion(sections)producing a Merkle-style version string: per-source hash + composed hash. Deterministic across key order. - 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. - 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.
- 1.1
compileCuratedCatalog(FEATURE_CATALOG)in product-graph (or a thinlibs/oshun/product-graph/src/compilers/curated.tsimporting from shell-assistant): emits surface/domain/feature/flow/step nodes + contains/follows edges, provenancecurated. Node ids preserved exactly so existing audit-store rows keep matching. - 1.2
compileE2eInventory(inventoryJson): emits journey + check nodes (checks become realchecknodes instead of synthesized steps) + contains/follows edges, provenancee2e-minedwith the inventory contentHash. Journey ids preserve today'se2e.<app>.<slug>scheme. - 1.3 Curation compiler
compileCurationEdges(map, graph): turnsE2E_GROUP_CURATION/E2E_FILE_CURATIONintoverifiesedges with provenancecurated; unknown targets are compile ERRORS (same semantics as today's curationTargetErrors). Waivers compile to a typed waiver set carried alongside the graph (not silent). - 1.4 Intrinsic + route-overlap signals from
buildVerifyEdgesmove into the composer as graph-native logic (route-overlap becomes a join viavisitsedges once Phase 2 lands; until then port the heuristic verbatim with aroute-derivedprovenance). - 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)#
- 2.1 Route extraction compiler: collect every distinct route from (a)
curated step
routefields, (b) e2e journey/check route mentions (extendtools/build-assistant-journey-inventory.mjsto minepage.goto/router pushes into the inventory JSON if not already present), (c) docs pages front-matter routes (Phase 3 feeds this). Emitroutenodes with normalized path attrs (param segments normalized like today's prefix normalization, e.g./tara/:id). - 2.2
visitsedges: 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. - 2.3 Route integrity rules in the validator: every
visitsedge lands on a route node; route paths are unique per surface; no route node is an orphan (at least onevisitsedge in). - 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#
- 3.1 Docs compiler: from the docs-search corpus build (extend
tools/build-assistant-docs-search.mjsto also emit graph nodes):docPagenodes (member + full audience attr) withdocumentsedges to the curated flows/features/domains they describe. Linkage signals: explicit front-matter refs where present, route overlap viavisits, 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). - 3.2 Anchors compiler:
anchornodes from the anchor registry;anchorsedges 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). - 3.3 Tours compiler:
tournodes from curated tour plans;toursedges tour→flow/domain it walks;visitsedges tour→route; approved tour submissions included with their own provenance marker in attrs (stillcuratedsource once approved). - 3.4 Invocation-points compiler: mine
openAssistantInvocationpoint ids (extend the invocation-bus guard spec's source scan into a build tool that emits JSON);invocationPointnodes +launchesedges to the flow/feature each point opens onto +anchorsedges where a point has a registered anchor. - 3.5 TODOS compiler: parse the checkbox corpus (
TODOS/phase-<n>.md, root*_TODOS_*.md, product-tree TODOS) intotasknodes (attrs: file, phase, checked state, text) withcontainsedges (document→phase-section→task) andtracksedges 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 honestunlinkedcount, 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). - 3.6 Architecture/design-docs compiler:
documentnodes forV1/ARCHITECTURE.md,V1/features.md, design docs,docs/, domain proposals, product reviews (attrs: docTypearchitecture|design|review|proposal|todos, path, heading outline);documentsedges 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 realdecisionrecords from them later — the compiler itself does NOT fabricate decisions. - 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#
- 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. - 4.2 Build tool
tools/build-product-graph.mjs: runs all compilers, writes ONE checked-in artifactlibs/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. - 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.
- 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.
- 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.
- 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). - 5.2 Traceability endpoint
GET /v1/assistant/catalog-traceability:analyzeCatalogTraceabilityreimplemented on kernel helpers (edgesTo/propagateUp); response shape unchanged; spec diffs old vs new report on the same inputs. - 5.3 Feature-catalog endpoint serves the graph-derived view;
getTracedAssistantCatalogGraphbecomessubgraph+ edge filter. - 5.4 Docs search: result grouping/annotation joins through
documentsedges (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). - 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. - 5.6 Delete the superseded bespoke code paths in
journey-inventory.tsonce 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). - 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.
- 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 onattrs. Migration file follows the BFF's existing migration convention (find and match it — do not invent a second mechanism). - 6.2 Idempotent loader
loadProductGraphIntoPostgres(pool, graph): transactional full-replace pergraph_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. - 6.3 Wire into BFF boot behind an env flag (e.g.
OSHUN_PRODUCT_GRAPH_PG_SYNC=1): on boot, compare storedgraph_versionto the artifact; load only on mismatch. No cron needed — the artifact only changes with a deploy. - 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).
- 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.
- 7.1 Verify the
graphprofile:docker compose -f docker/docker-compose.dev.yml --profile graph up -dbrings up Neo4j; record connection env (OSHUN_PRODUCT_GRAPH_NEO4J_URL, auth) in root.env.examplealongside the existing conventions. - 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 nscoped by agraphVersionproperty, then batchUNWINDcreates). Node label per kind (:Flow,:Journey,:Route, …) plus a common:ProductGraphlabel; relationship type per edge kind (:CONTAINS,:VERIFIES,:DOCUMENTS,:ANCHORS,:TOURS,:LAUNCHES,:VISITS,:FOLLOWS,:TRACKS,:DECIDES,:DISCUSSES,:SUPERSEDES); provenance + version as properties on both. - 7.3 Constraints/indexes before load: unique constraint on
ProductGraph.id; index on each kind label'sid; assert constraint creation succeeded before loading (fail loud, no partial loads). - 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 thegraphprofile): domain coverage rollup matching the TypeScript analyzer EXACTLY; shortest path feature→journey→route; orphan scan (any:ProductGraphnode with no edges — must be empty); the/taraeverything-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). - 7.5 Docs: a short
libs/oshun/product-graph/README.mdsection — 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#
- 8.1
e2e-curation-map.tstables 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). - 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). - 8.3 Memory file updated (
oshun-v1-omnipresent-assistant.md): new package, artifact path, loader flags, query-pack locations, any new landmines found. - 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). - 8.5 Full green sweep (product-graph, BFF assistant, shell-assistant, web,
staleness gate) + commit + MANDATORY two-line push
(
git push origin <branch>thengit push origin <branch>:main), verifyorigin/mainadvanced.
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.
- 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 provesreplay(ledger) == rows(make the invariant checkable by comparison, not by reading code). - 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). - 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, withparked/rejectedexits; illegal transitions refuse loudly with the attempted edge named. Theverifiedtransition 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 →supersededonly via a superseding decision. - 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. - 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.
- 10.1 Agent tools
create_work_item,update_work_item,open_thread,comment_thread,link_graph_refson the BFF agent loop — strict schemas; the current pageContext (route → graph node via thevisitsjoin) auto-suggests graph_refs which the model must surface for confirmation, never silently apply. - 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.
- 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).
- 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.
- 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.tsdrives 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_beginlive (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_itemPARKED (row count 0 asserted), Approve on the confirm card →wi-5861c8bd…inwork_itemwith ledger actorassistant:operator-studio-01+ model + turnId + conversationRef → "what's open on tara?" →list_work_itemscited 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 tothis.graph.versionsame 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.
- 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 viadocuments, journeys viaverifies, routes viavisits, open work viatracks) + docs search — answers cite graph evidence, and the context pack is the NEIGHBORHOOD, size-bounded, not the whole graph. - 11.2 ADR model as first-class
decisionrecords: context, options considered (each with tradeoffs), decision, consequences, status,supersedeschain (acyclic, validator-checked);decidesrefs to affected nodes. The assistant DRAFTS an ADR from a thread ("summarize this into a decision") — it staysdraftuntil a human proposes/ accepts via confirmed action; acceptance is never autonomous. - 11.3 Feature proposals: a work_item whose
expectationpayload 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. - 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").
- 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.
- 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. - 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).
- 12.3 Agent access surface: an
oshun-workbenchMCP 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. - 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 themcp__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. - 12.4 Report-back discipline: reports append events (never edit history);
completion moves the item to
in-review, and toshippedwhen the PR lands on main (verify by observing the repo — commit SHA/merge — not by trusting the report). NEVER toverified. - 12.5 HONEST CLOSURE — the promotion contract made executable:
verifiedis granted only by the artifact-diff verifier, which runs when a new knowledge-plane artifact version appears and checks the item's machine-readableexpectationagainst the diff (expected nodes/edges present, TOTALITY still green, referenced journeys exist in the e2e inventory). Shipped items whose expectation is unmet flagship-verify-gap— surfaced, never silently closed. Items without a machine-checkable expectation stay honestly atshippedwith the gap stated (an honest seam, not a fake verify). - 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)#
- 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. - 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).
- 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).
- 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).
- 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.
- 14.1
content-briefwork items: target domain/flow/route refs, audience, goal, outline — the assistant drafts briefs from discussion via the Phase 10 machinery verbatim (confirmed writes, provenance). - 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.
- 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.
- 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).
- 14.5 Specs + one live browser pass: discuss → brief → draft → dispatch →
publish-path → verify. (2026-08-04:
content-lane.integration.spec.ts3/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#
- 15.1 Knowledge↔intent joins in Postgres (intent already lives there): an
unnested
work_item_graph_refsview + 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). - 15.2 Neo4j intent sync: extend the loader to project work_items,
decisions, threads as
:WorkItem/:Decision/:Threadnodes with:TRACKS/:DECIDES/:DISCUSSESrelationships into the SAME graph db (propertyplane: 'intent', synced from Postgres on demand). Projection rule intact: Postgres is the intent plane's truth; Neo4j remains disposable for BOTH planes. - 15.3 Cypher pack additions mirroring 15.1 with EXACTLY matching answers on the same data, including the reconciliation query in both engines.
- 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;
verifiedis 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
studiodomain's representative flow + studio e2e edges already cover the surface).