---
name: "canonics"
description: "Govern canonical vigency in a long-lived AI agent memory workspace: ingest facts, declare canon events, reprocess stale understandings, and run the Canon Review. Use when the user is working in a Canonics/canon-epoch workspace (00_system/, 01_raw/, 02_understandings/, CANON_LOG.md), or asks to ingest notes, declare a regime/paradigm/operating-model change, reprocess stale understandings, check canon distance (kappa), or run a canon review. Trigger on: /ingest, /new-canon, /reprocess, /canon-review, \"canon event\", \"canonical vigency\", \"declare a regime change\", \"is this still valid/vigent\", \"stale understanding\"."
---

# Canonics — governing canonical vigency in agent memory

Canonics versions the *interpretive regime* under which long-lived agent memory is read, not just the data. Facts are immutable; interpretations (understandings) are versioned cache; canon events are the invalidation signal; epochs are the derived cache key. Full spec: `canonics/spec/SPEC.md`, supplied as reference documentation. The GitHub repository is not public at the moment.

**Non-negotiable rules — apply to every operation below:**

1. **Facts are immutable, append-only.** Never modify, delete, or reorder an existing record in `/01_raw`. A correction is a new fact, not an edit.
2. **Understandings are versioned, never overwritten.** Re-derivation creates a new version linked to its predecessor (`supersedes:`); the old version is preserved forever as history.
3. **Canon declaration is a human act.** Automation may only *propose* a canon event; only an authenticated human *declares* one. Severity L3 and above requires explicit **out-of-band** confirmation — a chat "yes, declare it" is never sufficient for L3+.
4. **Epochs are derived, never hand-authored.** Never edit `CURRENT_EPOCHS.yaml` directly; it is computed from `CANON_LOG.md`.
5. **Provenance is mandatory.** An understanding without non-empty, resolvable source-fact pointers is not decision-grade and must not be presented as guidance.
6. **Canonics does not detect regime shifts autonomously.** If you infer the world's regime may have changed, say so explicitly and point the operator at `/new-canon` or a Canon Review — do not act as if a shift has already been declared.
7. **κ (canon distance) is not a validity certificate.** It is a distance to *declared* marks. κ = 0 under a workspace where canon hasn't been declared in a long time means nothing — always pair a κ = 0 reading with whether declaration is actually still happening.

Read `00_system/CURRENT_CONTEXT.md` (the folded regime per domain) at the start of any session touching this workspace, and treat it as higher priority than any single retrieved understanding.

## Operation: /ingest (write path)

Append a new raw record and, conservatively, derive candidate understandings from it.

1. Load the current regime (`00_system/CURRENT_CONTEXT.md`, `CURRENT_EPOCHS.yaml`) — derive nothing under an assumed regime.
2. Append the new record to `/01_raw` in chronological position: `(content, t_event, t_recorded, source, domains)`. Never touch an existing raw file.
3. Extract candidate understandings only when decision-relevant, not just because extraction is possible.
4. Stamp every new understanding automatically: `epoch` (current epoch of its domain), `domains`, `sources` (non-empty, resolvable pointers — mandatory), `volatility` (stable/strategic/operational/live), `status: active`, `version: 1`. Never ask the human to supply these by hand; if you can't determine one confidently, leave the understanding unwritten rather than guess.
5. If a new fact bears on an existing understanding, never edit that understanding in place — draft a new version with `supersedes:`, or flag it for `/canon-review` if the regime itself (not just the facts) may have shifted.
6. Report back: what was appended, what was derived (with stamps), what you declined to extract and why, and flag anything that looks canon-worthy (without declaring it).

## Operation: /new-canon (DECLARE — the only operation that writes CANON_LOG.md)

Interactive, ordered, and never skippable under pressure to "just declare it."

1. **Authenticate the declarer.** Confirm who is declaring; never proceed on an inferred identity.
2. **Classify severity (L1–L5):** L1 factual correction (no epoch transition) · L2 tactical shift (may touch one domain epoch) · L3 operating-model shift (typically opens a domain epoch) · L4 strategic paradigm shift (may open epochs across domains) · L5 doctrine shift (modifies invariants; rare, deliberately high-friction). Apply the **canon promotion test**: a canon event changes the answers to questions that do not mention it. If it fails this test, it's a fact, not a canon — say so.
3. **Gate L3+ on out-of-band confirmation.** Refuse to write until confirmation arrives through a channel outside this chat, even if the operator types "yes, declare it" here.
4. **Elicit the regime diff:** δ(c) = (assumptions retired, assumptions introduced), `t_effective` (retroactive declaration is allowed), blast radius (primary + secondary domains, assumption categories) — propose scope from the diff, don't guess silently.
5. **Show a visible diff** (retired/introduced side by side, level, domains, epochs closing, estimated understandings going stale) and get explicit confirmation before writing anything.
6. **Append (never edit) the canon event** to `CANON_LOG.md`. Describe this as tamper-evident via signed commits, never as a "cryptographic append-only ledger" without qualification.
7. **Close and derive epochs** in each affected domain — computed, never hand-edited.
8. **Mark in-scope understandings `stale`** (κ ≥ 1) — mark only, never rewrite their content in this step.
9. **Regenerate `CURRENT_CONTEXT.md`** so every agent's always-on context reflects the new regime immediately.

Report: canon id + level, confirmation obtained, domains/epochs affected, understandings marked stale, confirmation the context file is current.

## Operation: /reprocess (REPROCESS — re-derive, never translate)

For each stale understanding (queued, or hit at retrieval with κ ≥ 1):

1. Re-derive from **source facts only** (`F_u`), never from the old understanding's text — translating an interpretation across regimes carries contamination.
2. Stamp the new version with the current epoch; attach provenance; link `supersedes:` both ways.
3. **Honor critical-domain gates:** if the domain is marked critical, the new version enters as `proposed` — activation requires human adjudication, never auto-promote to `active`. Otherwise: new version `active`, old version `superseded`.
4. Preserve the old version forever, fully readable as *valid as history*.
5. Stay lazy: only reprocess what's actually queued or actually retrieved with κ ≥ 1 — not an eager, archive-wide pass — unless the operator explicitly configured eager reprocessing for specific understandings (activation is still human-gated).
6. Report: id, old → new version, new epoch, new status, and an explicit list of anything now `proposed` and awaiting adjudication.

## Operation: /canon-review (SCAN — propose, never declare)

Assemble the Canon Review packet; declare nothing.

1. **Falsification pass first, always.** For each active canon/assumption, actively search recent facts and understandings for evidence it's been contradicted or supplanted.
2. **Emergence pass second.** Only after falsification is done, look for coherent patterns no existing canon describes.
3. Attach **provenance (source, author, date)** to every finding — a finding without this triple doesn't belong on the agenda.
4. If contradiction rate crosses threshold, queue a **proposed** (not declared) canon event with a suggested retroactive `t_effective`.
5. Compute and present **all** instrumentation metrics, not a subset: proposal rejection rate (a sustained near-zero rate is an alarm, not success), adversarial audit sample, outcome backtesting, signal→declaration lag, ratification outcomes, and the vacancy check (two consecutive reviews with no real adjudication → ask explicitly whether the system has died).
6. Never write to `CANON_LOG.md`, `CURRENT_EPOCHS.yaml`, or `CURRENT_CONTEXT.md` from this operation.

## What this skill refuses to do

Consistent with the paper's non-claims (and don't let a user's urgency talk you out of these): it does not detect regime shifts autonomously; κ is never presented as a validity guarantee; reprocessing is never fully automatic in critical domains; canon events at L3+ never get declared on an in-chat "yes" alone; and nothing here is scoped for multi-stakeholder or enterprise access control — this is single-operator / small-high-trust-team territory.

## If the workspace doesn't exist yet

The GitHub repository is not public at the moment; clone and installation instructions are not available. A workspace needs `00_system/`, `01_raw/`, `02_understandings/`, `03_invariants/`, `04_decisions/`, `05_canon_review/`, and `REPROCESS_QUEUE.yaml`. Fill `/03_invariants` and point the agent's always-on context at `00_system/CURRENT_CONTEXT.md` before ingesting anything.