podman/docs/graph-discovery/policy.md

Graph Discovery Policy

Status: draft
Scope: graph hygiene, evidence thresholds, and UI truthfulness

Prime Rule

The graph must be sparse enough to explain the learning loop and truthful enough to audit from MongoDB.

Node Policy

Create nodes only when they add explanation value.

Allowed:

• Current engineers.
• Real files.
• Current or recent collisions.
• Interventions tied to surviving collisions.
• Learned ownership paths.

Avoid:

• Test engineers.
• Scratch files.
• URLs or environment values misread as files.
• Repeated identical intervention diamonds.
• Orphan nodes with no story value.

Edge Policy

Edges need evidence.

Edge	Required evidence
editing	observation or git state
touches	file involved in collision
collides	collision prediction
warns	intervention record
learned_from	accepted real outcome
owns	learned or configured ownership

De-Hairball Policy

Default mode must not show every relationship equally.

Rules:

• Default to risk path.
• Collapse repeated collision signatures.
• Cap files and collisions.
• Dim non-risk edges.
• Bundle or curve dense edges.
• Hide low-priority labels until hover or select.
• Prefer selected-node explanation over labels everywhere.

Truthfulness Policy

• Do not show learned_from for orphaned or dismissed outcomes.
• Do not label vector similarity as learned memory.
• Do not show demo seed as live learning unless labeled.
• Do not hide false positives from activity or memory.

Privacy Policy

Graph labels should not expose secrets, raw terminal output, or sensitive file contents. File paths are acceptable when they are repo paths and not secret values.

Visual Policy

Semantic colors stay stable:

• Engineer: blue.
• File: slate.
• Feature: amber.
• Collision: red.
• Intervention: violet.
• Learned: violet dashed edge.

Chrome should use the app's light shadcn tokens.