feat(reflect): annotate the graph with work-memory verdicts and surface them in explain/query (#1441)

[TPAteeq]

Summary

Follow-up to #1441. The work-memory loop re-ingests the raw Q&A memory docs into the graph,
but the distilled verdicts graphify reflect computes (preferred / tentative / contested /
dead_end, time-decay scored) only land in reflections/LESSONS.md — a flat file, overwritten
each run, that nothing reads back. This makes those verdicts first-class graph data and
surfaces them where you actually look.

Write side — reflect --annotate-graph

Stamps each cited source node's verdict onto the graph (matched by node id or cited label):

attribute	value
learning_status	preferred / tentative / contested / dead_end
learning_score	signed, time-decayed score (omitted for dead-end-only nodes)
learning_uses	distinct useful results (omitted when 0)

Persistence is by recompute, not storage. annotate_graph clears every learning_* then
re-stamps from the aggregate: deterministic and idempotent (a re-run is byte-identical, a no-op
rewrites graph.json byte-for-byte matching export.to_json), touches only learning_*, never
changes node count or real fields. The durable truth stays graphify-out/memory/*.md → a full
rebuild that drops the attributes is healed by the next reflect. The git
post-commit/post-checkout hooks pass annotate=True after each rebuild so the graph self-heals;
learning_* is excluded from both watch compare functions so an annotation never forces a
needless rebuild.

Read side — the verdicts are actually used (four surfaces)

• graphify explain <node> → Lesson: preferred source (start here) — 2× useful, score=2.0
• graphify query + MCP query_graph → NODE Transformer [src=… learning=preferred]
• GRAPH_REPORT.md → a "Work-memory lessons" section listing preferred sources / known dead ends
• graph.html → annotated nodes get a status-colored ring (green = preferred, red = dead end;
  the community color stays the fill) and a Lesson: field in the node info panel

The status is one of four fixed strings but is sanitize_label'd on every output path (MCP F-010
and HTML), and on the query path appended inside the existing NODE line so the token-budget
truncation accounting is unchanged. Un-annotated graphs are unaffected: no Lesson: line, no
learning= suffix, no report section, no node ring (graph.html gains only a few constant
template lines; the rendered graph is visually identical).

Tests

• annotate_graph: by-id/by-label matching, all four verdicts, idempotency, self-healing,
  byte-identical no-op, non-dict graph → 0, label-less node not matched by a "None" citation,
  end-to-end via reflect(annotate=True) on a real build_from_json graph.
• Both watch compares ignore learning_* (the --no-cluster one without mutating originals).
• Consumers: explain shows/omits the Lesson: line; _subgraph_to_text (query CLI + MCP)
  tags/omits learning=; the GRAPH_REPORT section is present/absent; the HTML ring is present/absent.
• Full suite: 2550 passed, 2 skipped. skillgen --check, ruff clean.

Follow-ups (separate)

• A skill-runbook note that graph nodes carry learning_status (batched to amortize the skillgen
  14-copy regen).

Out of scope by design: no new edges / "Lessons" node — node attributes only (no topology change);
corrections stay question-level in LESSONS.md.

🤖 Generated with Claude Code

[safishamsi]

Thanks for this, and for pushing the work-memory loop forward — surfacing the distilled verdicts where you actually look (explain/query/report/html) is exactly the right instinct, and it shipped on v8 (5779767).

We landed it with one architectural change from this PR: instead of stamping learning_* onto the nodes in graph.json, the verdicts are written to a separate .graphify_learning.json sidecar that the read surfaces merge in at read time. Same four surfaces you targeted, same reuse of the reflect aggregate. The sidecar keeps graph.json purely structural (so it doesn't churn on every reflect and the attributes don't flow into GraphML exports), and it let us add two things cheaply: each verdict now carries its source-question provenance, and a file fingerprint so a verdict on code that's changed since gets flagged 'code changed — re-verify' rather than shown as still-authoritative. Dead-ends stayed question-scoped (report-only) rather than a node attribute.

So I'm closing this PR as implemented-differently rather than merged — the idea and the read-surface design are yours and credited in the commit. Really appreciate it; please keep them coming.