Harness Graph Integrity

Harness Graph Integrity

harness graph status answers "how big is the graph?". It cannot answer "is any of this true?". This skill answers the second question, and reports what it examined so a quiet result can never be mistaken for a clean one.

When to Use

• Before trusting any graph-derived answer for a decision — impact analysis, traceability, blast radius
• After a connector is added, re-keyed, or moved into CI, to confirm it is actually ingesting
• After upgrading the CLI, to catch extractor regressions that silently mint junk nodes
• On a milestone, as a cheap standing check on graph trustworthiness
• NOT for graph freshness or staleness (use harness-dependency-health)
• NOT for whether the code compiles, lints, and tests (use harness-verify)

Relationship to Other Skills

Process

Phase 1: INSPECT

Run the check from the project root:

harness graph integrity

Add --findings-json when a runner needs the machine-readable count, and --report-only to see findings without failing the step.

Do not hand-parse .harness/graph/graph.json or sync-metadata.json yourself. Detection lives in the CLI so that it is tested and versioned; this skill orchestrates it and interprets the result.

Phase 2: TRIAGE

Findings come in two families, and they need different responses.

Connector findings — the graph is missing data it claims to have.

GI-C001 is almost always a credential or network problem. Read the evidence line — it carries the connector's own error. Fix the cause, re-run harness graph ingest --source <name>, then re-run this check. Do not suppress it: the timestamp will keep reporting the connector as freshly synced.

GI-C002 is a warning because it is genuinely ambiguous — a connector with nothing new to fetch looks identical to one that did not run. Confirm against the source system before dismissing it.

Node findings — the graph contains assertions that were never true.

These come from a code extractor matching prose. The evidence line gives file:line and the extracted content, so the source is always one click away.

Critically: a node finding cannot be cleared by re-ingesting. The node is re-derived from unchanged source on every run, so harness graph ingest --full will faithfully recreate it. The fix belongs in the extractor. Report the file:line and the extracted content upstream rather than trying to scrub the store.

Phase 3: REPORT

Always lead with the denominators the command prints:

Checked: 6 connector(s), 50 extractor-derived node(s)

Then state the outcome in one of exactly three shapes:

• Findings — list them by severity, errors first, each with its evidence.
• Clean — say what was examined: "50 extractor-derived nodes and 6 connectors checked, no untrusted content."
• Abstained — say so plainly: "nothing to inspect." Never render this as a pass.

Harness Integration

• Backed by harness graph integrity (packages/cli/src/commands/graph/integrity.ts); detection logic is packages/graph/src/integrity/GraphIntegrityChecker.ts.
• Emits the standard maintenance findings envelope under --findings-json, so harness maintenance run consumes the count directly instead of recovering it from prose.
• Exit codes follow the CLI-wide contract:
  • 0 — inspected something, nothing untrusted found
  • 1 — error-severity findings (softened to 0 by --report-only)
  • 2 — the command itself failed
  • 3 — ZERO_DENOMINATOR: no graph, or nothing to inspect
• Reads only. It never edits the graph store, and never rewrites source.

Success Criteria

• The command ran and its denominators were reported, not just its verdict.
• Every finding was attributed to a family (connector or node) and given the remediation that family needs.
• No node finding was "fixed" by re-ingesting — the extractor was named instead.
• An abstention was reported as an abstention, with the reason it could not inspect anything.

Gates

• Graph must exist. No graph is exit 3, not a pass. Run harness graph scan and re-check.
• Zero denominator blocks a green claim. If checkedNothing is true, the skill may not report the graph as trustworthy.
• Error-severity findings block. Do not pass --report-only to make a red result green; use it only to survey.
• Detection stays in the CLI. If a new defect class needs catching, add it to GraphIntegrityChecker with a test — never as ad-hoc parsing inside this skill.

Escalation

• A node finding that the extractor owns — file upstream with the file:line and extracted content from the evidence line. Do not hand-edit graph.json; the next ingest overwrites it.
• A connector that cannot be fixed locally (no credentials available in this environment) — report it as a known gap with the connector name and what it was meant to supply, so downstream graph answers are read with that gap in view.
• A finding you believe is a false positive — escalate rather than suppress, with the node's kind, language, and content. The reserved-word set is deliberately conservative and cross-language; a genuine miss is a bug worth fixing centrally.

Examples

A graph whose connectors all silently failed

$ harness graph integrity
Checked: 6 connector(s), 50 extractor-derived node(s)

Graph integrity: 8 error(s), 0 warning(s)

  [ERROR] GI-C001 jira
    Connector "jira" reports last synced 2026-08-12T00:31:45.448Z but its last run failed
    and ingested nothing. The timestamp reads as a successful sync.
    evidence: Missing API key: environment variable "JIRA_API_KEY" is not set
  ...
  [ERROR] GI-N001 extracted:enum-constants:bbc78dbb
    Extracted "or" as a business_term, but that is a reserved word, not an identifier.
    The extractor almost certainly matched prose.
    evidence: ts/src/guardian/coverage.ts:1043 - enum or { function, const, if, if, if, return }

Correct report: six connectors are dark and the graph is missing everything they were meant to supply; one node is extractor debris from a JSDoc comment at coverage.ts:1043 and will survive any re-ingest.

A graph with nothing to inspect

$ harness graph integrity
Checked: 0 connector(s), 0 extractor-derived node(s)

ABSTAINED: nothing to inspect - no connectors configured and no extractor-derived
nodes in the graph. This is not a pass.

Correct report: the check could not verify anything. Exit 3. Reporting this as "integrity OK" is the exact failure the skill exists to prevent.

Rationalizations to Reject