Overview

The Compliance Auditor Framework is the enforcement arm of the vault’s YAML schema. It scans vault files against the canonical Reference — Ora YAML Schema and produces either a Drift Report (read-only) or a user-confirmed migration that brings drifted files into compliance. Without the auditor, schema drift accumulates silently — properties go out of canonical order as files are edited by hand, retired YAML fields linger from old templates, dates appear in mixed formats, type values fall out of the controlled vocabulary, and Phase 3 framework migrations have no validator to gate against. The auditor is the runtime mechanism that keeps the substrate consistent enough for the rest of the Ora apparatus (RAG provenance weighting, the type-driven retrieval tier, the relationship taxonomy) to operate reliably.

The framework runs in two modes that share all validation logic. A-Audit is the read-only scan: apply include and exclude globs to the vault path, extract YAML frontmatter from every candidate file, run the ten validation rules (V1–V10), compose a structured Markdown Drift Report with summary statistics, per-file entries for every drifted or invalid file, and hot-spot identification (top three files with most drift items; top three rules most violated). No file modifications happen in A-Audit; the report is the artifact, and the user reviews it before deciding whether to remediate. A-Migrate applies user-confirmed remediations from a prior A-Audit pass: the mode presents a Migration Plan listing every file to be edited with the unified-diff-style change for each, requests explicit user confirmation, then applies edits sequentially, re-running V1–V10 on each modified file to confirm now-compliant. The Apply Log records per-file success or failure. The discipline of always-A-Audit-before-A-Migrate is structural — A-Migrate refuses to run without a prior A-Audit report, because the migration target list is derived from the Drift Report’s per-file entries rather than from re-scanning during the migration pass.

The framework’s load-bearing intellectual content is the ten validation rules that operationalize the schema. V1 — required core properties present (nexus, type, tags, date created, date modified). V2 — type value in canonical vocabulary (one of: engram, framework, mode, reference, resource, incubator, chat, working, web, matrix, supervision). V3 — canonical property order, with absent properties shifting up while preserving relative order. V4 — no retired properties (strip-list includes title, content, use, state, verification_status, confidence, provenance, provenance_score, framework_version, execution_tier, domain, purpose, last-updated, pipeline_step). V5 — date format YYYY-MM-DD with dashes (linter-managed). V6 — tags only in YAML, no inline #tag in body. V7 — subtype scoped to atomic; values: fact, process_principle, definition, causal_claim, analogy, evaluative. V8 — project_type scoped to type: matrix; list form, not scalar. V9 — three-dash delimiters with blank line after closing ---. V10 — empty property form (bare key, not empty string or null).

The framework also names eleven canonical failure modes observed in pre-2026-04-29 vault state — stale type values; retired YAML fields lingering from older templates; date format drift (slashes or verbose strings); inline body tags; subtype on non-atomic notes; project_type as scalar; properties out of canonical order from missed linter runs; title fields surviving the pre-cleanup era; provenance properties written explicitly when they should now be derived from type; Working — drafts mistakenly in scope; scalar nexus instead of list-form nexus. The named failure modes drive the auditor’s per-file remediation guidance — each drift item names the rule, the current value, the required value, and the one-sentence remediation.

The framework is honest about what it does not do. It validates schema conformance only, not the conceptual fit between a file’s declared type and its content (a file declaring type: framework but containing no executable specification will pass V2 but is conceptually wrong; that judgment is a Phase 3 migration concern, not an auditor concern). It does not check that nexus values resolve to entries in Reference — Master Matrix (that is a separate validation pass). It does not verify body conformance to the output templates in Schema §12 (those govern AI-emitted note bodies, not pre-existing content). The auditor’s lane is YAML schema enforcement; staying within the lane is what makes the auditor’s findings unambiguous and its remediations safe to apply.

Systemic context

The Compliance Auditor Framework is the runtime enforcement mechanism for the Reference — Ora YAML Schema. It composes downstream of the schema itself (any schema rev triggers a re-audit pass) and upstream of every Phase 3 framework migration that depends on schema-compliant inputs. The default include scope (Framework — *.md, Reference — *.md, Specification — *.md, *Matrix*.md at vault root and inside Engrams/Matrix/) covers the canonical artifact tier; the default exclude scope (*(archived)*.md, *.bak, Working — *.md, Workshop/*, Modes/*, Lenses/*) covers files whose YAML is intentionally non-conforming or handled separately. The auditor is invoked three ways: directly by the user when the schema is updated; after a batch of framework migrations lands; before any A-Migrate pass to preview the work. The Phase 4 separate-treatment of Modes/* and Lenses/* reflects domain-specific schema concerns that the canonical auditor does not handle; those domains have their own validators.

Ora’s output

Example question: I just updated the YAML schema to add a new subtype enum value (speculative) and to retire the old confidence field. I do not know how many vault files are now drifted. Run the auditor in A-Audit mode and tell me what needs to change.

Ora’s response (running the Compliance Auditor in A-Audit mode):

A schema update is the canonical A-Audit trigger. I will run the read-only scan against the default scope, produce the Drift Report per the Output Contract, and stop without making any file modifications. You can then review and decide whether to dispatch A-Migrate against the drifted files.

Layer 1 — File enumeration. Apply include globs (Framework — *.md, Reference — *.md, Specification — *.md, *Matrix*.md at vault root and inside Engrams/Matrix/) and exclude globs (*(archived)*.md, *.bak, Working — *.md, Workshop/*, Modes/*, Lenses/*) to the vault path. Candidate file list produced: 247 files in scope.

Layer 2 — Frontmatter extraction. Read first 50 lines of each file; extract YAML between opening --- and closing ---. Three files fail extraction (no closing delimiter on one; malformed YAML indentation on two) — marked INVALID and skipped from the rule passes.

Layer 3 — Apply validation rules V1–V10. Aggregate counts:

V1 (required core properties): 0 drift. V2 (type vocabulary): 0 drift. V3 (canonical property order): 7 drift from manual edits. V4 (no retired properties): 37 drift — 31 from the just-retired confidence field plus 6 from older retired provenance and verification_status. V5 (date format): 2 drift (slashes instead of dashes). V6 (tags only in YAML): 1 drift (inline body tag). V7, V8, V9, V10: 0 drift each. INVALID: 3 files (frontmatter unparseable).

Layer 4 — Per-file drift entry composition. Each drifted file gets a structured entry naming status, frontmatter snapshot, and per-rule drift items with current value, required value, and remediation. Compliant files listed by name only in an appendix.

Layer 5 — Summary and hot spots. Total scanned: 247. Compliant: 203. Drifted: 41. Invalid: 3. Most-violated rule: V4 (37 instances). Top drifted files: Framework — Old Working Spec.md (5 hits); Reference — Project Type Registry.md (4 hits); Specification — Legacy Pipeline.md (4 hits).

Layer 6 — A-Audit emits Drift Report and stops. No file modifications.

The Drift Report. Header (vault path, schema, mode, scope, timestamp). Summary statistics. Per-file entries for the 41 drifted and 3 invalid files. Hot spots. Compliant-files appendix.

What this means. The schema update produced an expected migration burden of 31 files for the retired confidence field. The other drift items are pre-existing drift the audit surfaced. The 3 INVALID files need manual frontmatter repair first — the auditor cannot remediate them because YAML extraction failed.

Next step (your call). If you want to remediate, the canonical move is A-Migrate against the 41 drifted files. The mode will produce a Migration Plan with the unified-diff-style change per file, request explicit confirmation, then apply edits sequentially with per-file re-validation. The framework will not run A-Migrate without explicit go-ahead — applying file edits without confirmation is the operational failure mode the discuss-before-execute discipline is defending against.

That is what the Compliance Auditor produces in A-Audit mode: a structured drift report against the ten validation rules, with per-file remediation guidance and explicit handoff to A-Migrate when the user is ready to apply the changes.

Commercial AI comparison

Comparison content auto-populates when the comparison-refresh framework runs against this question. Drafters do not author this section.

Brief comparison commentary

Auto-populates with the comparison content above.

How to use this framework

You can run the Compliance Auditor pattern with any AI of your choice that has filesystem access to your vault. The composition is single-pass for either mode.

For A-Audit (the read-only scan, the canonical starting point):

[Paste the framework specification]

Run the Compliance Auditor in A-Audit mode against the vault.

Vault path: [Absolute path to vault directory.]

Schema: [Path to Reference — Ora YAML Schema.md.]

Include scope (optional): [Override the defaults if needed.]

Exclude scope (optional): [Override the defaults if needed.]

Apply rules V1–V10. Produce the Drift Report per the Output Contract. No file modifications.

For A-Migrate (applies user-confirmed remediations from a prior A-Audit):

[Paste the framework specification]

Run the Compliance Auditor in A-Migrate mode for files [list from prior A-Audit report].

Schema: Reference — Ora YAML Schema.

Apply rules V1–V10 to compose a Migration Plan. Wait for user confirmation. On go-ahead, apply edits sequentially and emit an Apply Log with per-file re-validation results.

The AI runs the mode-appropriate output: for A-Audit, the structured Drift Report with summary statistics, per-file drift entries, and hot spots; for A-Migrate, the Migration Plan with explicit confirmation prompt followed by the Apply Log with re-validation results.

For best results:

  1. Always run A-Audit before A-Migrate. A-Migrate’s target list is derived from a prior Drift Report, not from a fresh re-scan during the migration. The discipline ensures the user reviewed the changes before authorizing them.
  2. Never skip the explicit confirmation step in A-Migrate. The auditor will refuse to apply edits without an explicit go-ahead between the Migration Plan and the file modifications. Confirmation is structural, not procedural.
  3. Do not expand scope to the exclude lists. Working — *.md, Workshop/*, Modes/*, and Lenses/* are excluded for reasons (drafts in progress, raw chat content, separate domain schemas). Pulling them into scope produces drift findings that are not actionable.
  4. Re-audit after schema updates. A schema rev (new validation rule, retired property, new enum value) is the canonical A-Audit trigger. Without the re-audit, drift accumulates silently against the new schema.
  5. Manually repair INVALID files before re-running A-Audit on them. When YAML extraction fails (no closing delimiter, malformed YAML indentation), the auditor cannot remediate because the rules cannot run against unparseable frontmatter.

The framework is deliberately implementation-agnostic. The two-mode separation (A-Audit / A-Migrate), the ten validation rules, the canonical failure-mode catalog, the always-audit-before-migrate discipline, and the explicit-confirmation requirement all survive the lift to any environment that can read and edit Markdown files with YAML frontmatter.

Other examples

  • A scheduled re-audit after a Phase 3 framework migration batch. Twelve framework files have just been migrated to a new specification format. Run A-Audit to verify all twelve are now schema-compliant; the report should show 0 drift across the twelve. If drift surfaces, the Phase 3 migration introduced regressions that need fixing before the migration is considered complete. Demonstrates the auditor as the gate between Phase 3 work and its acceptance.
  • A vault-wide drift sweep before a major release. The user wants every canonical artifact in the vault to be schema-compliant before a public-facing release of the framework set. Run A-Audit at the broadest in-scope coverage; review the Drift Report; run A-Migrate against the drifted files; re-run A-Audit to confirm 0 drift. Demonstrates the auditor’s role in pre-release hygiene.
  • A targeted re-audit of one specific subdirectory. A user has been working in Engrams/Matrix/ for a week and wants to confirm those files are still compliant before continuing. Run A-Audit with the include scope narrowed to Engrams/Matrix/*Matrix*.md. The report covers only the targeted files. Demonstrates the auditor’s flexibility for narrow-scope sanity checks.

Citations

The Compliance Auditor Framework draws on a small set of operational disciplines from configuration management and schema validation traditions. Schema-driven validation (the discipline of checking artifact conformance against an externally-defined specification rather than against ad-hoc per-artifact rules) is the lineage of XML Schema validation, JSON Schema validation, and Kubernetes admission controllers. The two-mode separation (read-only audit vs. user-confirmed migration) follows the discipline of operational change management — preview every change before applying, gate every apply on explicit authorization, log every result. The named-failure-mode catalog approach (eleven specific patterns observed in pre-2026-04-29 vault state) draws on defect-pattern cataloging in software quality engineering — the most-frequently-observed defects deserve named status because the validator’s value is in catching them reliably.

The framework is internal to Ora and emerged from observing that hand-edited YAML frontmatter accumulates drift faster than any periodic-cleanup discipline can absorb, and that drift in the substrate degrades downstream apparatus (RAG provenance weighting, type-driven retrieval tier, relationship taxonomy) in ways that produce subtle quality regressions long before they become visible failures. The runtime principle (if a process can be executed at runtime, it must be executed at runtime) applies: the auditor is a runtime validator, not a scheduled cleanup script. The framework was originated 2026-04-29; v1.0 is the current version with the ten validation rules and the two-mode separation as specified.

Downloads

  • Framework specification (PDF) — link to ora-ai.org canonical artifact when published
  • Framework specification (plain text) — link to ora-ai.org canonical artifact when published
  • Full white paper (PDF) — link when published