Concepts

OpenCanon makes Project Canon agent-ready, human-readable, and runtime-enforced through Proof, Knowledge, Activity, and Health.

Project Canon

Project Canon is the typed source of truth for a repository. The enforced project source of truth: Areas, Specs, Changes, conventions, docs, and checks. It contains Areas, Specs, Changes, conventions, impact surfaces, generated docs, and checks. Humans read the generated docs; agents query the richer source model through CLI or MCP.

Areas

Areas describe durable ownership: product surfaces, architectural boundaries, runtime subsystems, or examples that have clear behavior and checks.

Specs

Specs describe durable behavior with scope, scenarios, governing conventions, and checks. Durable product or system behavior with scope, governing conventions, scenarios, and checks. A completed Change can become or update a Spec when the behavior should be permanent.

Changes

Changes describe active implementation plans. Active implementation plans with tasks, related files, surfaces, and declared checks. They connect tasks to files, impact surfaces, checks, and the Project Canon that should guide the work.

Conventions

Conventions explain repeatable rules. They can render docs, enforce runtime validators or gates, or simply document a human rule when runtime enforcement is not useful.

Proof

Proof is the umbrella for validators, gates, fixtures, Doctor, declared task checks, and generated-doc drift checks. Validators read project facts and return findings. Runtime checks that read project facts and return findings.

Findings

A finding is the unit of output. Actionable results with severity, rule id, file location, and optional fixes. It carries:

• rule: the validator that produced it.
• severity: error or warn.
• location: file, line, and optional span.
• docs: the Project Canon docs or definitions the finding backs.
• fix: optional structured edits or an advisory command.

Fix Plans

Fix and refactor helpers are plan-first. Validators can attach structured edits, and the core fixes namespace can plan symbol renames, file moves, import updates, package renames, and module splits before anything is written.

Knowledge

Knowledge is the local index for files, docs, symbols, graph edges, chunks, backlinks, and related-code search. It helps humans and agents find evidence, but durable rules still live in Project Canon and Proof.

Activity

Activity records indexing progress, agent work, check results, events, and logs as derived state. It helps explain what happened without becoming source truth.

Health

Health covers setup, runtime prerequisites, generated-state freshness, hooks, dependency pins, and Doctor checks.

Runtime

The local service watches repositories, starts project runtimes, extracts facts, stores SQLite state, and serves CLI, MCP, hooks, and browser diagnostics. The local service and project runtime that index code, cache derived state, and serve CLI, MCP, hooks, and browser diagnostics.

What OpenCanon is not

• It is not a linter. Validators read structured facts, not source text.
• It is not a CI service. The service runs locally next to the editor.
• It is not a rule DSL. Validators are TypeScript with fixtures.