code-intelligence-contract

Code Intelligence Contract

Overview

Use one provider-neutral capability contract for optional code intelligence. Graph output can guide source inspection, but it never replaces source ownership, tests, runtime evidence, mutation approval, or reviewer judgment.

When to use

Use for pre-change impact analysis, independent post-change comparison, cross-subsystem debugging, changed-symbol review, unfamiliar-project onboarding, architecture or domain-flow discovery, and cross-repository contract analysis when a provider is available.

When NOT to use

Do not use this skill for pure project intake, pure debugging, or pure mutation work that does not need graph context. Do not use graph output as runtime proof, source authority, generated-file authority, or permission to install, index, clean, hook, or expand write scope.

Required inputs and context discovery

Collect a stable query ID; provider and resolved version; repository, revision, worktree identity, capability, required languages, and artifacts; an explicit privacy-safe untracked content identity when untracked files are present; index identity and state; query subject; edge provenance; affected paths; generated authorities; side-effect observations; reviewer; and the owning workflow's source/test fallback.

Safety and risk level

The graph lane is read-only. Provider installation, index creation or refresh, hooks, generated project-local skills, and cleanup are mutations outside this contract. Any observed provider write is SIDE_EFFECT_VIOLATION, blocks the graph lane, and requires separate report-only planning and approval.

Workflow

1. For each recorded preference/opt-in candidate, probe installed provider version and index status without mutation. Completion criterion: discovered version and index facts are recorded without install, refresh, hooks, cleanup, or writes.
2. Before selection, require repository scope plus repository/HEAD/worktree/language/side-effect binding. Do not read untracked file contents; when untracked files are present, require the provider wrapper to supply a privacy-safe content identity or keep repository identity incomplete and the graph lane BLOCKED. Treat USER_DISABLED as ineligible, filter for the exact required capability and language, then select the highest-priority FRESH eligible provider. If no exact match exists, selection remains BLOCKED; never silently substitute a weaker capability. Completion criterion: query ID, binding, eligibility filters, priority, and selection blocker are recorded.
3. Classify index state before using output. Use STALE_HEAD when indexed revision differs, STALE_WORKTREE when worktree identity differs, PARTIAL_LANGUAGE when any required language is unsupported, SIDE_EFFECT_VIOLATION when the read-only boundary is broken, and EMPTY_UNCERTAIN when the provider returns no result. Broken, unavailable, disabled, and unsupported providers are also BLOCKED. Completion criterion: only a fresh, read-only, language-complete result proceeds; every other state records a source/test fallback.
4. Run the smallest provider-neutral capability query: context, dependency path, impact, cross-repository contract, architecture, onboarding, or domain flow. Completion criterion: query ID, subject, affected paths, artifacts, limitations, and exact provider output are recorded without widening write ownership.
5. Resolve exactly one query subject before classifying edges. Only source-derived EXTRACTED edges may be Verified, and only for extraction at the bound snapshot. confidence=INFERRED and semantic/LLM evidence stay Snapshot or Unverified; zero or multiple resolved subjects and other unresolved ambiguity are BLOCKED. Completion criterion: extraction, inference, semantic interpretation, and runtime behavior have separate labels.
6. Confirm material paths against source owners, generated authorities, tests, logs, or runtime evidence. The implementer runs pre-change impact before editing. The verifier independently runs a fresh post-change query with the same query ID and compares pre/post affected paths. Completion criterion: source disagreements, dynamic dispatch, reflection, generated paths, and post-change freshness limits are explicit.
7. For mutation without usable graph evidence, record Decision: REVIEWER_ACKNOWLEDGED_FALLBACK; explicit missing graph coverage/blocker; authoritative source owners; known callers/consumers; generated authorities or exact NOT_APPLICABLE; focused test commands; named reviewer; and residual risk. Preserve existing risk, approval, backup, and restore gates. Any unresolved generated, cross-repository, or dynamic boundary remains BLOCKED, and graph verdict stays BLOCKED. Inspect every generated-source, dynamic-dispatch, language, repository, security, database, service, or release boundary; if source/tests cannot cover any unresolved boundary, the owning workflow remains BLOCKED. Completion criterion: the full fallback record exists, approved write scope stays bounded, and Graph verdict remains BLOCKED.