docs: add learning and graph specs

2026-06-28 00:34:47 -07:00
parent 5e9929f8da
commit 9870a1c710
12 changed files with 1281 additions and 0 deletions
@@ -0,0 +1,146 @@
+# Graph Discovery Spec
+
+Status: draft  
+Scope: how PodMan discovers graph nodes, edges, risk paths, and learning paths from MongoDB  
+Owner: graph discovery / Team memory observatory
+
+## Purpose
+
+Graph discovery turns MongoDB memory into a legible Team memory graph. It is not
+only layout. It decides which relationships matter, which path is highlighted,
+and which evidence explains the graph.
+
+The graph must answer:
+
+1. Who is working?
+2. Which files or symbols overlap?
+3. Where is the risk?
+4. What did PodMan do?
+5. What outcome changed memory?
+
+## Source Data
+
+Graph discovery reads:
+
+- `pods`
+- `engineer_states`
+- `observations`
+- `collisions`
+- `interventions`
+- `outcomes`
+- `team_model`
+- `graph_nodes`
+- `graph_edges`
+- optional `memory_vectors`
+- optional `agent_runs`
+- optional `strategy_versions`
+
+## UI Graph Contract
+
+```text
+PodGraph
+  podId
+  generatedAt
+  nodes
+  edges
+  metrics
+  loop?
+  activity?
+```
+
+Node kinds:
+
+```text
+engineer, feature, file, collision, intervention
+```
+
+Edge kinds:
+
+```text
+owns, editing, touches, collides, warns, learned_from
+```
+
+## Discovery Rules
+
+### Engineer nodes
+
+Create from pod roster, recent observations, git state, or collision membership.
+
+### File nodes
+
+Create only from normalized real file paths. Reject noise such as URLs, env
+values, scratch names, and non-file strings.
+
+### Collision nodes
+
+Create from distinct collision signatures. Collapse repeats. Prioritize
+collisions referenced by accepted outcomes.
+
+### Intervention nodes
+
+Create one visible intervention per surviving collision unless whole-graph mode
+explicitly expands history.
+
+### Learned paths
+
+Create `learned_from` only when an accepted real outcome links an intervention
+to a durable memory update.
+
+## Path Modes
+
+### Risk path
+
+Default mode. Highlight the clearest current chain:
+
+```text
+engineer -> file -> collision -> intervention -> learned owner
+```
+
+Dim unrelated graph material.
+
+### Learning edges
+
+Highlight `learned_from`, `owns`, and the outcomes that produced them.
+
+### Whole graph
+
+Show all materialized nodes and edges with de-emphasized non-critical edges.
+
+## MongoDB Traversal
+
+Use `graph_edges` for reachability:
+
+```text
+source -> target -> next target
+```
+
+Primary traversal questions:
+
+- What risks does this engineer reach?
+- Which files feed this collision?
+- Which intervention came from this collision?
+- Which learned owner came from this intervention?
+
+## Metrics
+
+Minimum metrics:
+
+- Learned owners.
+- Open risk paths.
+- Accept rate.
+
+Optional metrics:
+
+- Observations.
+- Interventions.
+- Memory vectors.
+- Strategy versions.
+
+## Acceptance Criteria
+
+- Default graph is not a hairball.
+- Every visible learned edge has outcome evidence.
+- Every selected node can explain why it matters.
+- Activity stream matches graph events.
+- Graph can be rebuilt from MongoDB source records.
+