Canonicalization

The Canonicalization Engine registers concepts: each has exactly one canonicalPath and optional mirrors (docs, generated maps). Gates and MCP tools detect drift and plan fixes.

Configure concepts

Create .ags/canonical.yml:

.ags/canonical.yml yaml

schemaVersion: 1
concepts:
  - id: versioning-config
    label: Versioning policy
    canonicalPath: .ags/versioning.yml
    kind: config
    mirrors:
      - docs/versioning/
  - id: deployment-config
    label: Deployment policy
    canonicalPath: .ags/deployment.yml
    kind: config
    mirrors:
      - docs/deployment/
graphArtifact: docs/canonical-map/latest.json

graphArtifact is where the engine writes the live canonical map (commit it so CI can diff).

MCP tools

Tool	Does
canon_get	Read registry / graph
canon_validate	Validate concept entries
canon_enforce	Fail on missing SoT or illegal duplicates
canon_drift	Diff committed map vs live state
canon_plan_fix	Produce restore actions for a concept

Example calls json

// MCP tool: canon_enforce
{}

// MCP tool: canon_drift
{}

// MCP tool: canon_plan_fix
{ "conceptId": "versioning-config" }

Gate

gate.canonical can be required in CI or inside the enforcement session so merges cannot land with a drifting SoT map. Canonical checks often call into Data arrays when a concept’s SoT is itself a governed list.

Showcase: Canonicalization.