Graph Quality Overnight Refactor

This is parked work for a long unattended agent pass.

Goal

Make the graph more useful for coding agents by refactoring noisy idea and behaviour nodes into stronger semantic hubs, while preserving detail as artifacts, suites, tests, or implementation evidence.

The working rule:

Keep a node only when it changes what an agent would read, edit, or test.

Starting Point

Current post-cleanup graph snapshot:

  • 1560 graph nodes
  • 14253 edges
  • 340 idea nodes
  • 223 behaviour nodes
  • 0 local-colon idea IDs
  • 0 path-shaped studies / readme / package idea smells
  • 0 source-backed grounding issues

Expected Shape

Behaviours are actionable ideas. Over time, the graph should probably have fewer abstract ideas and clearer behaviour coverage.

Target direction:

idea -> behaviour -> implementation -> suite -> test

Files stay atomic: each file claims what it is and what it directly touches. The graph emerges from those claims.

Candidate First Slices

Start with one vertical slice, not the whole repository.

Good candidates:

  • CV pipeline
  • dashboard shell
  • realtime collaboration
  • QA platform
  • JobCache ingest

For the chosen slice:

  1. Read the current idea, behaviour, implementation, suite, and test nodes.
  2. Collapse aliases where the same node would send an agent to the same files, tests, and invariants.
  3. Promote real user/system actions to behaviour nodes.
  4. Demote scenario IDs, page/modal names, package names, service surfaces, and implementation facts out of idea/behaviour nodes unless they truly express a durable concept.
  5. Refactor code or tests if the graph exposes real coupling, not just naming noise.
  6. Regenerate graph claims and run strict checks.

Likely Reduction Budget

Conservative estimate:

  • 30-45 idea nodes can still merge without losing meaning.
  • 20-35 behaviour nodes can merge or move downward.

With code/test refactoring:

  • 60-90 ideas may be reducible.
  • 40-70 behaviours may be reducible.

Do not optimize for the lowest node count. Optimize for agent usefulness.

Semantic Lint To Add

Add checks that flag, at minimum:

  • idea IDs containing namespace colons;
  • idea IDs shaped like readme, package, api, mcp, ui, worker, or pure surface names;
  • behaviour IDs shaped like test case IDs (p1-g6-s1, e1, story-*, etc.);
  • duplicate node entries inside one file;
  • self-links;
  • suite nodes with fewer than two tests;
  • implementations without a clear idea or behaviour path;
  • tests without both suite and implementation links.

Done Criteria

Each refactor slice is done only when:

  • graph extraction is strict-clean;
  • graph coverage remains strict-clean;
  • source-backed grounding remains clean;
  • wiki graph frontmatter verifies;
  • package checks still pass for changed packages;
  • any affected code/tests are refactored or explicitly left as follow-up.
Source: wiki/content/working-memory/graph-quality-overnight-refactor.md