Concepts

OpenCanon has four core objects and one daemon.

Docs

Docs are normal Markdown headings referenced from decisions with docs refs such as docs/opencanon/canon/architecture.md#imports. The project rules OpenCanon can show to humans and agents. Context queries reach prose through the decisions whose topics and applies globs match the work.

Decisions

Decisions are structured records in docs/opencanon/decisions.json. Records that explain a rule, why it exists, and which validators enforce it. Each decision explains a rule, its applicability, the docs headings it depends on, and the validators that enforce it.

Validators

Validators are TypeScript functions. They read facts from the daemon and return findings. They can use graph facts for symbol search, callers, callees, references, and impact. Fixtures pin each validator's behavior.

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.
• decision: the decision the rule 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.

Daemon

The daemon watches the repository, extracts facts, stores SQLite state, and serves the local API used by CLI, hooks, and UI.

What OpenCanon is not

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