Run live Effort Graph wire-up against actual artifact folders

[tonyketcham]

Point Flatbread at a representative real artifact folder, execute the blocking-decision retrieval path end-to-end, and record the concrete friction/invariants discovered during a live run.

Final outcome

From a freshly spawned agent, query structured Flatbread data for one effort and retrieve artifacts from multiple agents/runs without knowing artifact folder paths.

Context

• @flatbread/proof writes live artifacts under .flatbread/artifacts/dag-*.
• Full runs include task transcripts, _index.md, and _dag.json.
• --findings-dir sidecars can bridge to Decision/Blocker rows.
• Effort Graph exists in docs/fixtures, but live artifacts are not yet queryable relationally.

Relevant files:

• flatbread-agent-artifact-opportunity.md
• flatbread-search-and-memory-research.md
• docs/experiments/issue-167-effort-graph-layout-mapping.md
• docs/experiments/issue-169-agent-artifact-retrieval-benchmark.md
• packages/proof/src/run_dag.ts
• packages/proof/src/findings_sidecar.ts

Scope

In scope:

• Model live artifact folders as relational content.
• Represent Effort, Agent, Run/Session, Artifact, and Decision.
• Query multiple agents’ artifacts for one effort.
• Use this feature’s own implementation artifacts as the test/eval corpus.

Out of scope:

• Remote artifact registry.
• Historical import of every old artifact shape.
• UI browsing.
• Replacing raw artifact files.
• Perfect global agent identity.

Sub-tasks

• Inventory real .flatbread/artifacts/dag-* folders from at least two agents/runs for one effort.
• Define first Effort Graph schema/config with stable IDs and refs.
• Add importer/emitter that turns live artifacts into queryable Flatbread rows.
• Extract decisions/blockers from structured sidecars or markdown sections.
• Add a canonical query from effort id to agents, runs, artifacts, and decisions.
• Use the implementer’s own artifacts as the validation corpus.
• Compare graph retrieval against raw search and record friction/invariants.
• Add focused tests for multi-agent artifact mapping and decision provenance.
• Document the operator workflow and exact validation command/query.

Acceptance criteria

• A fresh agent can query an effort id and retrieve artifacts from multiple agents/runs.
• Retrieval does not depend on knowing artifact folder names.
• Graph rows include explicit refs across effort, agent, run/session, artifact, and decision.
• Validation uses artifacts produced while implementing this feature.
• A blocker/decision lookup returns provenance back to the raw artifact.
• Focused automated tests cover artifact mapping/query behavior.

Open questions

• Should effort id come from DAG metadata, CLI flag, env var, issue/branch metadata, or manifest?
• Should Proof emit rows directly, or should Flatbread import artifact folders after the fact?
• What is the first stable-enough Agent identity?
• Should decisions/blockers be first-class rows now or derived from artifact/finding rows later?