Skip to content

docs: map graph engineering onto griff generation - #159

Closed
PhysShell wants to merge 3 commits into
mainfrom
agent/graph-engineering-notes-20260727
Closed

PhysShell wants to merge 3 commits into
mainfrom
agent/graph-engineering-notes-20260727

Conversation

@PhysShell

Copy link
Copy Markdown
Owner

Summary

Add a current-tree design note explaining graph engineering in griff as a deterministic musical dataflow and optimization problem, not a pretext for replacing transparent algorithms with a committee of agents.

The note:

  • maps the live corpus → request → strategy/seed fan-out → generation → axes → rerank → optional layered-DP candidate-chain path;
  • distinguishes the execution/dataflow graph from the layered optimization graph;
  • records current edge contracts: exact track/bar provenance, rhythm precedence, deterministic seed derivation, explainable scoring, compatibility refusal, DP tie-breaking, and canonical float association;
  • identifies the correct future loops: audition/feedback, offline evaluation, leakage-safe holdout, and bounded search widening;
  • defines a typed boundary for any future LLM-assisted composer;
  • compares griff’s graph with 007’s execution/evidence/control graph.

README gains a short link to the design note.

Current-tree audit

Verified against main at e094d9ab4b7633f4a1939b73c9fa06e24bab6dd0 on 2026-07-27.

Inspected current contracts in:

  • core/src/generation_input.rs;
  • core/src/generate.rs;
  • core/src/rerank.rs;
  • core/src/layered_path.rs;
  • core/src/candidate_chain.rs;
  • root Cargo.toml, README.md, and AGENTS.md;
  • ADR-0013, ADR-0017, ADR-0029, ADR-0030, and the current proposed ADR-0031.

The key correction is explicit: griff already has a real graph layer. Candidate fan-out and reranking form a deterministic dataflow graph, while layered_path + candidate_chain implement an actual layered DAG optimization problem. The useful next work is durable lineage, evaluation, feedback, and reachability edges, not rhythm agent -> harmony agent -> critic agent.

Validation

Documentation-only change.

  • Branch is based exactly on the audited main SHA.
  • Compare result: 0 commits behind; only docs/graph-engineering.md and a three-line README link differ.
  • Document references were checked against current repository paths; incorrect guessed ADR filenames were caught and corrected before opening this PR.
  • No Rust, manifests, schemas, scoring policy, generation behavior, or UI behavior changed.
  • Cargo tests were not run because this PR changes documentation only.

@coderabbitai

coderabbitai Bot commented Jul 27, 2026

Copy link
Copy Markdown

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: feafcd0a-8bc7-4968-98cd-ee895c9d17f8

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch agent/graph-engineering-notes-20260727

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

Copy link
Copy Markdown
Owner Author

Closing as a stale snapshot, not as a bad idea.

docs/graph-engineering.md describes the pipeline as it stood on 2026-07-27 and
presents itself as a current-tree audit. That is no longer true. Since then S15
Phase 2 and S7 Slice C both landed, and the note's own sections are where the
drift shows: "Ranked set to candidate chain" and "Layered problem to path
solution" describe a search layer that now also has solve_k_best, a diversity
rule, and a fail-closed arithmetic they do not mention.

A document whose value is "this is what the code currently does" cannot be
merged once that has stopped being the case — it would ship stale on day one,
and a reader has no way to tell which parts aged.

There is also a placement question worth settling before any successor: this is
a free-floating docs/graph-engineering.md, and the routing in AGENTS.md
knows ADRs, proposals, stage docs, the decisions log, and the glossary. A design
note is a sixth category that does not currently exist.

If the material is wanted, it is cheaper and more honest to rewrite it against
current main than to revive 393 lines of prose about a tree that has moved.


Generated by Claude Code

@PhysShell PhysShell closed this Aug 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant