coaia-visualizer 1.6.0 → 1.6.2

package/rispecs/github-project-runtime-memory-integration.spec.md

@@ -0,0 +1,381 @@
+# 🔮 Future Integration: GitHub Project Runtime-Memory Visualization
+
+> How coaia-visualizer COULD render GitHub-Project sync state, project-field
+> provenance, and GitHub-linked action steps so charts produced and synced by
+> the `coaia-github` bridge gain a living "Project lens" without breaking
+> the current rendering pipeline.
+
+**Status**: 🔮 FUTURE / ASPIRATIONAL · spec-only · additive
+**Last Updated**: 2026-05-09
+**Framework**: RISE (Reverse-engineer · Intent-extract · Specify · Export)
+**Cross-references**:
+- [`README.md`](./README.md) — visualizer pillars, 4-pass parse, current components
+- [`pde-integration.spec.md`](./pde-integration.spec.md) — companion future spec, PDE source rendering
+- [`planning-integration.spec.md`](./planning-integration.spec.md) — companion future spec, plan source + sync state rendering
+- [`relation-graph-visualization.spec.md`](./relation-graph-visualization.spec.md) — current relation rendering, grouping by `relationType`
+- `coaia-narrative/rispecs/coaia-github/github-project-runtime-memory-schema-bridge.spec.md` — schema-bridge proposal that produces the metadata this spec consumes
+- `coaia-narrative/rispecs/coaia-github/README.md` — canonical Amun field map
+- `coaia-narrative/rispecs/schema-evolution-and-ecosystem-metadata.spec.md` — typed sub-object pattern (`metadata.pde`, `metadata.plan`, `metadata.accountability`, `metadata.source`)
+- mightyeagle worktree proposal: `rispecs/miadi-code/miadi-agent/orchestration-proposals/260509-github-projects-structural-runtime-memory.md`
+- `jgwill/coaia-agent#18` — runtime/visualizer container context (informational; this spec does not depend on it)
+
+---
+
+## 1. Position Among Future-Integration Specs
+
+This spec is the third in a small family that all share the same posture:
+
+| Spec | Surfaces | Source metadata it reads |
+|---|---|---|
+| `pde-integration.spec.md` | Four-Directions quadrant, PDE provenance breadcrumb, implicit-intent badges, confidence bars | `pde_session` line, `metadata.pde.*` (per schema-evolution spec) |
+| `planning-integration.spec.md` | Plan source badge, parse-confidence color, plan-sync state, source-line link, re-sync action | `metadata.plan.*` |
+| **this spec** — `github-project-runtime-memory-integration.spec.md` | Project source badge, project-field provenance trail, sync-state indicator, project lens switcher, GitHub-linked action step badges | `metadata.github.*`, `metadata.source.system === 'coaia-github'` |
+
+The three specs **compose**: a single chart can carry PDE provenance, a
+plan link, and a GitHub Project mirror simultaneously. None of them
+replaces or hides the others. This spec is the GitHub layer of the same
+provenance trail.
+
+---
+
+## 2. Structural Tension
+
+### 2.1 Current Reality
+- coaia-visualizer treats every chart identically. A chart with
+  `metadata.github.issue` populated looks the same as a hand-authored
+  chart. The 4-pass parse algorithm (`organizeData()`) does not look at
+  `metadata.github.*`, `metadata.source.system === 'coaia-github'`, nor at
+  any `gh:<owner>/<repo>#<num>` virtual entity Encoding B might produce.
+- coaia-visualizer does not write to GitHub at all. Today this is the
+  correct boundary — the visualizer is a renderer, not a bridge — but it
+  also means a practitioner inside the visualizer cannot see whether a
+  chart they are looking at has drifted from its GitHub Project mirror.
+- The relation graph component groups by `relationType` only. Custom-typed
+  relations carrying canonical names like `synced_to_github` (per the
+  schema-bridge spec §4) appear as a generic `custom` group with no
+  affordance.
+- Issue `jgwill/coaia-agent#18` ships the visualizer alongside
+  `coaia-narrative` inside the same `coaia-agent` runtime; that means once
+  the GitHub-bridge metadata is being written, the visualizer is the
+  natural surface to inspect it.
+
+### 2.2 Desired Outcome
+A chart that has been mirrored to a GitHub Project carries that fact
+**visibly** in the visualizer:
+- A `🪐 Project` source badge appears alongside the existing `🔬 PDE` and
+  `📋 Plan` badges.
+- A small sync-state pill (`✅ synced`, `⚠️ diverged`, `❌ conflict`,
+  `🌐 project-only`, `📂 chart-only`) sits under the badge.
+- A "Project lens" dropdown lets the practitioner switch between project
+  contexts when more than one Project mirrors the same chart.
+- Action steps with their own `metadata.github.issue` show a small issue
+  ref badge inline.
+- The relation-graph panel surfaces `synced_to_github` (and adjacent
+  bridge relations) under a dedicated section — not buried in `custom`.
+- A provenance trail row at the chart header reads:
+  `💬 Original Prompt → 🔬 PDE Decomposition → 📊 STC Chart → 🪐 GitHub Project Item`
+  whenever each segment is present.
+
+### 2.3 Tension
+The tension is between **the existing 4-pass parse algorithm** (which
+treats JSONL as a flat stream of entities and relations) and **the new
+provenance dimension** GitHub-bridge metadata adds. Resolution: the parse
+algorithm stays unchanged; rendering reads `metadata.github.*` opportunistically;
+no schema authority moves into the visualizer.
+
+---
+
+## 3. Non-Breaking Posture
+
+This spec commits to four invariants:
+
+1. **No change to the 4-pass parse algorithm in `organizeData()`.** New
+   visualizer logic reads `metadata.github` after parsing, never during.
+2. **No new entity-type rendering path.** Encoding B virtual entities
+   (`entityType: "custom"`, `name: "gh:<owner>/<repo>#<num>"`) render via
+   the existing `custom` entity branch with a new optional badge — they do
+   not become first-class chart components.
+3. **No new relation-type enum reliance.** Bridge relations land via
+   `relationType: "custom"` with `metadata.context` carrying the canonical
+   name; the visualizer reads `metadata.context` to group them under a
+   "GitHub bridge" section. If `coaia-narrative` later promotes those
+   names, the visualizer reads the promoted form transparently.
+4. **No write path to GitHub.** The visualizer never calls `sync_*` tools.
+   Re-sync triggers are *advisory UI* (a button) that surface the bridge
+   tool name and arguments for the user to invoke through the runtime
+   (coaia-agent / coaia-narrative MCP). This mirrors the planning
+   integration's "re-sync trigger" affordance.
+
+---
+
+## 4. Visual Surfaces
+
+### 4.1 Project Source Badge
+
+Component: `ProjectSourceBadge` (new, sibling to the proposed
+`PdeSourceBadge` and `PlanSourceBadge`).
+
+```
+🪐 Project: <ownerLogin>/<projectNumber> · <projectTitle>   [✅ synced]
+```
+
+| Element | Source | Style |
+|---|---|---|
+| `🪐` icon | constant | `indigo-500` to distinguish from `🔬` (amber, PDE) and `📋` (violet, plan) |
+| project ref | `metadata.github.projectItem.{projectOwner,projectNumber}` | tooltip exposes `itemId`, `url`, `projectTitle` |
+| sync pill | `metadata.github.syncState` | green `synced`, amber `diverged`, red `conflict`, slate `project-only`/`chart-only` |
+| lens switcher | when `metadata.github.projectItems` (plural) is present | small dropdown under the badge |
+
+**Trigger**: render only when `metadata.github.issue` exists on the chart
+entity OR when `metadata.source.system === 'coaia-github'` is set.
+
+### 4.2 Issue Ref Badge on Action Steps
+
+Component: `ActionStepIssueBadge`.
+
+```
+☐ Implement field hash routine                               [🪐 #142]
+```
+
+The badge shows `#<number>` only; tooltip expands to
+`<owner>/<repo>#<number>` and the issue URL. Render when an action_step
+entity has `metadata.github.issue`.
+
+### 4.3 Sync-State Pill (chart and action step)
+
+Same pill component reused at chart level (under the project source
+badge) and at action-step level (next to the issue ref badge, only when
+the per-action `metadata.github.syncState` exists). Identical color
+language as the planning-integration sync indicator (§ 1 of
+`planning-integration.spec.md`), so the practitioner reads sync state the
+same way for plans and projects.
+
+### 4.4 Provenance Trail Extension
+
+`pde-integration.spec.md` already proposes the breadcrumb component
+`ProvenanceTrail`. This spec extends it with a final segment when GitHub
+metadata is present:
+
+```
+💬 Original Prompt → 🔬 PDE Decomposition → 📊 STC Chart → 🪐 GitHub Project Item
+```
+
+Each segment remains independently optional. If only PDE and Project
+exist (no plan), the breadcrumb has three segments. Rendering rule: a
+segment appears iff its source metadata exists.
+
+### 4.5 Relation-Graph Section
+
+`relation-graph-visualization.spec.md` groups relations by `relationType`.
+Proposed extension: when grouping, peek at `metadata.context` for
+`custom`-typed relations and pull canonical bridge names into a separate
+"GitHub bridge" header section.
+
+```
+[GitHub bridge] (2)
+  synced_to_github
+    chart_42 → gh:jgwill/coaia-narrative#187           [✅ synced]
+  linked_to_issue
+    chart_42_action_2 → gh:jgwill/coaia-agent#18       [(unstored)]
+```
+
+This section appears only when at least one bridge relation exists. It
+keeps the existing flat-list rendering for charts with no GitHub metadata
+unchanged.
+
+### 4.6 Project Lens Switcher (multi-lens, deferred shape)
+
+When a chart's `metadata.github.projectItems` carries multiple project
+items, the project source badge gains a dropdown that lets the user pick
+which project's lens is "active" in the current visualizer view.
+"Active lens" is a UI state only — it does not change the JSONL. Switching
+lenses changes:
+
+- which `projectTitle` and `projectNumber` show in the badge,
+- which `Status` value the visualizer reads (Status is per project-item),
+- which `accountable_to` / `responsible_for` fields the visualizer prefers
+  if multiple project items disagree (rare but possible).
+
+Default lens: the first item in `projectItems`, OR `projectItem` (singular).
+Deferred until plural form is observed in real JSONL.
+
+---
+
+## 5. Metadata Required From `coaia-narrative`
+
+This is the contract the schema-bridge spec must keep. The visualizer can
+do its job iff `metadata.github` follows the schema-bridge spec §3 shape.
+Concretely the visualizer reads, in this order of preference:
+
+1. `entity.metadata?.github?.issue` (canonical)
+2. `entity.metadata?.sync_target` (deprecated shorthand on chart)
+3. `entity.metadata?.github_ref` (deprecated shorthand on action step)
+
+For sync state:
+
+1. `entity.metadata?.github?.syncState`
+2. otherwise: visualizer renders no sync pill (silence is data — same
+   convention as `coaia-github` field resolution §9).
+
+For project context:
+
+1. `entity.metadata?.github?.projectItem`
+2. `entity.metadata?.github?.projectItems[0]`
+3. `entity.metadata?.sync_target` (legacy fallback)
+
+For source attribution:
+
+1. `entity.metadata?.source?.system === 'coaia-github'` → render
+   "Last synced by `coaia-github` (`<toolName>`) at `<lastSyncedAt>`" on hover.
+
+The visualizer MUST NOT invent any of the above. If metadata is absent,
+the corresponding surface is absent.
+
+---
+
+## 6. What Is Not Stored in the Visualizer
+
+To keep the boundary clean, the visualizer:
+
+- Does not cache GitHub responses. Each render reads only what's in JSONL.
+- Does not maintain a separate "project view" data structure. Project lens
+  rendering is computed per-render from the chart's `metadata.github.*`.
+- Does not ship API tokens or auth flows. Those live in whichever runtime
+  hosts `coaia-github` MCP tools.
+- Does not show "live" GitHub state. If the practitioner needs live state,
+  they invoke `sync_project_to_chart` through the runtime; the visualizer
+  then reflects the refreshed JSONL on the next reload.
+
+This matches the existing pillar from `README.md`: the visualizer is a
+ceremonial instrument for holding tension visible — not a network client.
+
+---
+
+## 7. Connection to `jgwill/coaia-agent#18`
+
+Issue #18 ships the visualizer inside the `coaia-agent` runtime so the
+runtime can act as a service. That makes the visualizer the **natural
+surface** to inspect what the GitHub bridge has done. Two specific
+implications:
+
+1. The visualizer process can rely on whatever JSONL `coaia-agent` writes
+   (per `pde-stc-session-lifecycle.spec.md` and
+   `visualizer-planning-narrative-flow.spec.md`). When `coaia-agent` later
+   invokes `coaia-github` MCP tools, the resulting `metadata.github.*`
+   appears in the same JSONL the visualizer is already watching (envs
+   `COAIAN_MF`, `COAIAV_PORT`, `COAIAV_AUDIO_DIR`).
+2. The "re-sync trigger" UI (§ 4) sends the canonical MCP tool name and
+   arguments back to the runtime. It does not call GitHub directly. This
+   keeps the visualizer port-bound (`4421:4321`, `4422:4422`) and free of
+   credentials.
+
+This spec does not require issue #18 to land before it can be implemented.
+The metadata it consumes can come from any runtime that uses the
+`coaia-github` bridge.
+
+---
+
+## 8. Composition With PDE and Plan Specs (no duplication)
+
+| Concern | Owned by |
+|---|---|
+| Four-Directions quadrant view | `pde-integration.spec.md` |
+| Implicit-intent / confidence rendering | `pde-integration.spec.md` |
+| Plan source badge / parse confidence color | `planning-integration.spec.md` |
+| Plan ↔ chart sync indicator | `planning-integration.spec.md` |
+| Project source badge / project field provenance | **this spec** |
+| Project ↔ chart sync indicator | **this spec** |
+| Project lens switcher (multi-perspective) | **this spec** |
+| Provenance trail breadcrumb | `pde-integration.spec.md` (defines), this spec (extends) |
+| Relation-graph rendering | `relation-graph-visualization.spec.md` (defines), this spec (extends with GitHub-bridge section) |
+| 4-pass parse algorithm | `jsonl-parsing-data-types.spec.md` (unchanged) |
+
+When two indicators apply (e.g. a chart with both plan-sync state and
+project-sync state), they render side-by-side in the chart header. They
+do not collapse, because they describe different bridges.
+
+---
+
+## 9. First Implementation Slice (3–5 steps)
+
+Each step is named with a RISE phase.
+
+1. **Specify**: land this document. Add a row to the `Future Integration
+   Specs` section of `README.md` linking it (one-line entry, additive).
+   *(Spec-only.)*
+2. **Reverse-engineer**: read one real `.coaia/pde/<uuid>.jsonl` file
+   produced after the schema-bridge spec's §10 step 5 ("smallest end-to-
+   end exercise"). Confirm that `metadata.github.*` is present and
+   matches the bridge spec §3 shape. If it does not, file findings into
+   the bridge spec's open questions before any UI work begins.
+3. **Intent-extract**: decide which surface lands first. Recommendation:
+   project source badge + sync-state pill (§4.1, §4.3). They are the
+   smallest visible win and exercise the dual-read fallback in §5.
+4. **Specify**: write a tight component-level rispec
+   `components/project-source-badge.spec.md` here in
+   `coaia-visualizer/rispecs/` that names the component shape, props, and
+   trigger conditions. *(Still spec-only — implementation is a later
+   issue.)*
+5. **Export**: when steps 2–4 hold, produce a single PR that adds the
+   `ProjectSourceBadge` and the sync-state pill, gated behind a feature
+   flag (`COAIAV_GITHUB_BRIDGE=1`). The flag protects existing JSONL
+   renders from any visual change. Do not ship the lens switcher,
+   provenance-trail extension, or relation-graph section in the same PR.
+
+Steps 1, 3, and 4 are spec-only. Step 2 is a single-file inspection. Step
+5 is the smallest UI exercise that does not require the relation-graph
+section or lens switcher.
+
+---
+
+## 10. Quality Criteria
+
+- [x] No change required to `jsonl-parsing-data-types.spec.md` or to the
+      4-pass parse algorithm.
+- [x] No new `entityType` reliance. Encoding B virtual entities render via
+      the existing `custom` entity branch.
+- [x] No new `relationType` enum reliance. Bridge relations enter via
+      `relationType: "custom"` plus `metadata.context`.
+- [x] All UI surfaces are conditional on metadata existence.
+- [x] No write path to GitHub from the visualizer.
+- [x] Composition with `pde-integration.spec.md` and
+      `planning-integration.spec.md` is explicit and side-by-side, not
+      replacement.
+- [x] Required metadata shape is identical to the bridge spec §3 — no
+      visualizer-specific schema.
+- [x] First slice is small enough to ship behind a feature flag.
+
+---
+
+## 11. Open Questions
+
+1. **Color choice for `🪐` Project badge.** Indigo proposed to distinguish
+   from PDE-amber and Plan-violet; final choice deferred to the design
+   pass that produces real component CSS.
+2. **What does sync-state `project-only` show on a chart card?**
+   Recommendation: render the chart with a slate "ghost" treatment and a
+   "Imported from project — chart not yet established" hint. Decision
+   deferred until the `sync_project_to_chart` MCP tool ships and produces
+   real `project-only` entities.
+3. **Relation-graph section for bridge relations.** Should
+   `synced_to_github` to a virtual `gh:` target render as an external
+   node (Encoding B) or as a metadata badge on the chart card (Encoding
+   A)? Per bridge spec §4.1, encoding is per-session config — the
+   visualizer reads whichever is present.
+4. **Lens switcher trigger threshold.** Show the dropdown only when
+   `projectItems.length >= 2`. When exactly one item exists, render it as
+   a flat badge.
+
+---
+
+## 12. Out of Scope (defer)
+
+- Writing to GitHub from the visualizer.
+- Live GitHub-state polling, webhooks, or push-triggered re-renders.
+- Project lens switcher implementation (open question §11.4 must close
+  first).
+- Authentication, rate-limit, or token refresh UI.
+- Editing of `metadata.github.*` from the visualizer (ownership stays
+  with `coaia-github` per bridge spec §8).
+- A "lens entity" rendering pattern beyond the dropdown — see bridge
+  spec §4 promotion criterion.