# ADR 0026: Knowledge Discovery and Evidence Classification Surfaces

Status: Implemented

Source: Claude Code architecture review.

## Context

OntoIndex' main value is to help agents and humans find, classify, and trust repository knowledge. The Claude Code architecture review identified useful product patterns, but the reviewed source advertises itself as leaked Claude Code source. OntoIndex must not copy source code, prompts, UI text, or proprietary structure from that repository.

The useful lesson is architectural, not implementation-specific: tools are easier to use safely when discovery, contracts, permissions, diagnostics, and evidence provenance are first-class. OntoIndex already has the right surfaces for this direction:

- `gn_help` for tool discovery.
- `gn_tool_contract` and the tool registry for schema and release contract metadata.
- `gn_diagnose` for health and setup checks.
- MCP resources for contextual knowledge.
- Evidence read ledger and `basedOnReads` metadata for report provenance.
- Existing safe-edit, impact, audit, and freshness policies for authority boundaries.

This ADR decides how to adopt only the useful parts for OntoIndex' knowledge discovery and classification workflow without introducing a second agent runtime or weakening audit trust boundaries.

## Decision

OntoIndex will add a conservative, additive knowledge discovery and evidence classification layer across existing public surfaces.

The implementation should:

1. Extend intent-aware tool discovery through `gn_help` and `gn_tool_contract`.
2. Classify tool, resource, search, diagnostic, and report outputs by evidence type and authority.
3. Connect search and report outputs to `basedOnReads` where reads materially support a recommendation.
4. Add doctor-style diagnostics for MCP setup, LSP availability, model/skill metadata, response limits, and degraded states.
5. Treat permission profiles as contract metadata first, not runtime enforcement.
6. Keep advisory memory, diagnostics, and read-ledger data out of audit status transitions unless separately verified by existing audit gates.

This ADR does not approve a generic agent task runtime, generic file reader, worktree mutation tool, memory write automation, or new public API surface when an existing surface can be extended.

## Knowledge Classification Model

OntoIndex should classify discovered knowledge with a small vocabulary that maps to existing trust boundaries:

| Class | Meaning | Audit authority |
| --- | --- | --- |
| `graph_evidence` | Indexed symbols, relationships, call flows, impact results, structural graph facts. | Can support audit findings when fresh and verified. |
| `docs_evidence` | Project docs, ADRs, guides, plans, generated references. | Contextual; must not override code evidence. |
| `audit_evidence` | Outputs from audit, verification, pre-commit, safe-edit, or replay gates. | Can support status when generated by accepted gates. |
| `runtime_diagnostic` | Health, setup, freshness, LSP, MCP, response-limit, and degradation signals. | Operational context only. |
| `advisory_memory` | Human-authored or imported memory-style knowledge. | Advisory only; never audit evidence by itself. |
| `unknown` | Any source that cannot be classified. | Not trusted for recommendations until classified. |

Search implementation details such as lexical, semantic, graph, or resource-backed retrieval can be represented as secondary metadata. They should not create new authority classes unless a later ADR updates the trust model.

## OntoIndex Surfaces

### `gn_help`

`gn_help` should become the primary intent router for humans and agents. It should support discovery by:

- Query text.
- Mode or workflow intent, such as explore, edit, audit, diagnose, release, or docs.
- Stability tier.
- Permission profile metadata.
- Evidence classes produced by the tool.

Example: an agent asks for a safe way to rename a symbol. `gn_help` should rank `gn_safe_edit_check`, impact analysis, and rename-oriented guidance above raw search tools.

### `gn_tool_contract`

`gn_tool_contract` should expose classification metadata from the registry:

- Tool category and intended workflow.
- Input and output schema.
- Stability and release policy.
- Permission profile.
- Evidence classes produced.
- Whether output may contribute to audit status.
- Whether output is advisory only.

This should extend ADR 0025 rather than create a parallel registry.

### MCP Resources

MCP resources should publish short resource contract summaries:

- Resource name and purpose.
- Expected freshness behavior.
- Evidence class.
- Response-size and truncation policy.
- Whether the resource is suitable for audit evidence, docs context, or diagnostics only.

Resource reads that materially support recommendations should flow into `basedOnReads` through the evidence read ledger.

### `gn_diagnose`

`gn_diagnose` should be the single doctor-style surface for setup and degraded-state checks:

- MCP transport and configuration health.
- MCP auth/config prerequisites where applicable.
- OntoIndex index freshness and repo binding.
- LSP availability and degradation state.
- Tool registry and contract snapshot health.
- Response-limit and truncation behavior.
- Installed skill/model-pack metadata when available.

Diagnostics should explain why a recommendation may be lower confidence, but must not promote advisory or diagnostic data into audit evidence.

### Reports And Recommendations

Review, audit, and docs recommendations should expose the evidence classes they used. This keeps organic recommendations explainable:

- "Recommended because graph impact and safe-edit checks agree."
- "Advisory only because the source is docs evidence."
- "Lower confidence because LSP diagnostics are degraded."
- "Not audit evidence because the source is advisory memory."

Recommendations should prefer graph and verified audit evidence over docs, memory, or diagnostics when the goal is code safety.

## Rejected And Deferred

Rejected for this ADR:

- Generic task or agent execution tools.
- Multi-agent orchestration inside OntoIndex.
- Generic file read/write tools outside existing scoped resources and safe-edit flows.
- Worktree mutation automation.
- Prompt or implementation reuse from the reviewed Claude Code repository.
- New public routes or tools that duplicate existing OntoIndex surfaces.

Deferred:

- Runtime permission enforcement.
- Memory authoring and lifecycle automation.
- New UI flows for diagnostics.
- A broader evidence-class taxonomy beyond the classes listed here.

## Implementation Plan

1. Extend tool registry metadata with evidence class, workflow intent, permission profile, and advisory/audit-authority flags.
2. Update `gn_tool_contract` to expose that metadata with release-policy tests and stable snapshots.
3. Add intent and evidence-class filtering to `gn_help`.
4. Add resource contract summaries for existing MCP resources.
5. Extend `gn_diagnose` with setup, LSP, response-limit, and contract-health sections.
6. Thread evidence classes into recommendation/report outputs and `basedOnReads` where applicable.
7. Add focused unit tests for classification, help filtering, contract output, diagnostics, and no-audit-authority regressions.

## Review: Planned vs Done

Reviewed with OntoIndex and direct source review on 2026-05-22 against commit
`39cf8a1d54402d7b55656f6cb467157f218470ee`.

OntoIndex evidence:

- `gn_diagnose({repo: "OntoIndex"})` reports degraded retrieval context because the graph index is stale (`01b797718afe7468166072b7a24bee36129b8b20` indexed vs `39cf8a1d54402d7b55656f6cb467157f218470ee` current) and embeddings are unavailable.
- `gn_tool_contract({includeFacades: true})` reports `status: "ok"` with no missing advertised tools and no extra callable tools.
- Direct source review confirms the current HEAD implementation because stale graph evidence cannot prove recently committed code.

Review findings:

1. **ADR 0026 is implemented as an additive layer:** Existing public surfaces were extended instead of adding a second agent runtime or duplicate tool registry.
2. **Trust boundaries are preserved:** Advisory memory and runtime diagnostic classes are explicitly non-authoritative, and high-confidence organic recommendations require graph or audit evidence.
3. **The remaining risk is maintenance drift:** The registry, help output, resource summaries, diagnostics, organic recommendation gate, and stable snapshot must stay synchronized as tools/resources change.
4. **Snapshot validation must compare semantic JSON:** The committed snapshot is formatted by repository tooling, so release tests compare parsed JSON rather than raw whitespace.

| Planned item | Done state | Evidence | Challenge |
| --- | --- | --- | --- |
| Reuse a small evidence vocabulary | Done | `EvidenceReadClass` and `ORGANIC_RECOMMENDATION_EVIDENCE_CLASSES` use `graph_evidence`, `docs_evidence`, `audit_evidence`, `advisory_memory`, `runtime_diagnostic`, and `unknown`. | Keep this as the single authority vocabulary; do not add duplicate tool-local classifications. |
| Extend tool registry metadata with evidence class, permission profile, and authority flags | Done | `ToolContractMetadata` and `PublicToolRegistryEntry` include `workflowIntents`, `producesEvidenceClasses`, `permissionProfile`, `auditAuthority`, and `advisoryOnly`. | Inferred defaults are useful, but new high-risk tools should override metadata explicitly when category inference is too broad. |
| Expose classification metadata through `gn_tool_contract` | Done | `serializeToolContract()` emits ADR 0026 metadata and the stable contract snapshot covers it. | Snapshot tests must remain semantic-format stable so Prettier does not create false release failures. |
| Add intent and evidence-class filtering to `gn_help` | Done | `gn_help` supports `query`, `intent`, `evidenceClass`/`evidenceClasses`, `stability`, non-authoritative evidence opt-in, and `limit`. | Query ranking is static lexical scoring; do not treat it as semantic retrieval quality. |
| Add resource contract summaries | Done | Resource definitions/templates include compact contract metadata with purpose, freshness, evidence class, response policy, and suitability. | Resource descriptions are compact strings, not a standalone schema endpoint; add one only if clients need machine-readable resource contracts. |
| Extend `gn_diagnose` doctor-style checks | Done | `gn_diagnose` reports classification summary, resource contract counts, MCP setup/auth metadata, response limits, degraded context, freshness, embeddings, LSP, and tool-contract health. | Model/skill metadata remains environment-dependent; keep it diagnostic, never audit authority. |
| Thread evidence classes into reports and `basedOnReads` | Done | `gn_docs`, `gn_diff_impact`, and `gn_pre_commit_audit` expose `basedOnReads`; organic recommendations carry `evidenceClasses`. | Keep connecting new report producers to the evidence read ledger when recommendations depend on resource reads. |
| Preserve trust boundaries | Done | Advisory memory reads carry `notAuditEvidence`; non-authoritative classes are excluded from `gn_help` evidence filtering unless explicitly requested; organic high confidence rejects low-authority-only evidence. | Do not promote diagnostics, docs, or memories into audit status without existing verification gates. |
| Add tests for ADR 0026-specific behavior | Done | Tests cover tool-contract classification inventory, schema metadata, help filters, resource contract summaries, diagnostics classification, and organic authority gating. | Add a regression test whenever a new public tool/resource introduces a new evidence class or authority rule. |

Verdict: ADR 0026 is implemented. Future work should be operational hardening only: keep the tool registry, resource contract summaries, diagnostics, recommendation gates, and stable snapshots synchronized as new OntoIndex surfaces are added.

Follow-up recommendations:

1. Re-run the focused ADR 0026 suite whenever public MCP tools or resources change.
2. Prefer explicit metadata overrides for release, write, or runtime-admin tools instead of relying only on category inference.
3. Keep `advisory_memory` and `runtime_diagnostic` non-authoritative by default in every new discovery or recommendation surface.
4. Do not add new public APIs for classification until clients prove the compact contract metadata is insufficient.
5. Re-index OntoIndex before using graph evidence to challenge future ADR 0026 status claims.

## Acceptance Criteria

- Existing public surfaces are extended instead of duplicated.
- Every public tool and resource has a declared evidence class or an explicit `unknown` classification.
- Advisory memory and diagnostics never change audit, verification, or release status by themselves.
- `gn_help` can answer intent-based discovery questions without requiring agents to know exact tool names.
- `gn_tool_contract` exposes stable classification metadata.
- Resource-backed recommendations record supporting reads through `basedOnReads`.
- Response-size limits and truncation metadata remain visible.
- Tests cover classification defaults and no-authority regressions.

## Consequences

Positive:

- OntoIndex recommendations become easier to explain and safer to consume.
- Agents can discover the right tool by intent instead of memorizing tool names.
- Report readers can see whether a recommendation came from graph facts, docs, diagnostics, or advisory memory.
- Claude Code-inspired lessons are adopted only as general architecture patterns.

Negative:

- Public contract metadata expands and must be release-gated.
- Existing resources and reports will need classification coverage.
- `unknown` classifications may temporarily reduce recommendation confidence until backfilled.

## Validation

Minimum validation for an implementation:

```bash
cd ontoindex && npm run build
cd ontoindex && npm test
cd ontoindex && npx tsc --noEmit
```

If only docs change, run Markdown/link checks when available and review the ADR against ADR 0018, ADR 0023, ADR 0024, and ADR 0025 for trust-boundary conflicts.
