y-graph-codex

name: y-graph-codex description: Build a minimal React Flow-ready graph from SummaryRoot JSON and attach it as a git note under y-codex-session-graph.

Purpose

Read SummaryRoot JSON and emit a minimal graph representation focused on user messages, decisions, files, artifacts, and objective/outcome. Attach the graph JSON as a git note under namespace y-codex-session-graph.

Inputs

SummaryRoot JSON path (absolute or relative).
Output directory for graph.json.

Required Output

graph.json: GraphRoot JSON.
Git note: write full graph.json body under namespace y-codex-session-graph for the commit.

Graph Schema (GraphRoot)

{
  "schema_version": "1",
  "nodes": [
    { "id": "...", "type": "...", "data": { "label": "...", "detail": "...", "timestamp": "...", "evidence_refs": ["..."] } }
  ],
  "edges": [
    { "id": "...", "source": "...", "target": "...", "type": "...", "label": "..." }
  ],
  "meta": { "commit": "..." }
}

This structure is React Flow-ready (nodes/edges only, no positions).

Determinism Rules

Use stable ordering: by timestamp when present, then by original index.
Use deterministic IDs, e.g. sha256("<kind>|<timestamp>|<label>|<index>").
Do not use random values.

Nodes to Create

message nodes from user_message_ledger.messages.
decision nodes from decisions_and_tradeoffs.decisions.
file nodes from files_edited_and_why.files.
artifact nodes from structured_output_artifacts.artifacts plus JSON/markdown summary pointers.
objective and outcome nodes from executive_summary.

Edges to Create

message_sequence: message[i] -> message[i+1].
message_to_decision: if decision rationale evidence references a user evidence record that matches message timestamp or snippet overlap.
decision_to_file: if decision rationale evidence and file.why share any evidence id.
decision_to_artifact: if decision rationale mentions artifact location in text.
objective_to_decision and decision_to_outcome for overall flow.

Validation

Ensure unique IDs.
Ensure all edges reference existing node IDs.
Ensure at least one node exists; otherwise fail with an actionable error.

Notes

Include evidence refs in node data.evidence_refs where they exist.
Keep node label short and readable; put long text in detail.