Skip to content

Codebase Constitution Audit

Document: docs/product/audit-brief.md
Brief ID: AUDIT-01
Status: Ready to execute
Last updated: 2026-04-06
Authority: Tim Rignold, UCCA Inc
Executor: Alex (agentic AI)

Purpose

This brief instructs Alex to conduct a comprehensive compliance audit of the RTOpacks codebase against the product constitution documents established in Session 42. The audit produces a written report identifying what is compliant, what deviates, and what is unresolved. The output of this audit is the baseline from which all future development proceeds.

Context

Across Sessions 1–41, the RTOpacks platform has been built at speed. Architectural decisions have been made, revised, and refined across those sessions. The product constitution has now been formally written for the first time:

  • docs/product/object-model.md
  • docs/product/security-posture.md
  • docs/product/routing-structure.md
  • docs/product/presentation-tiers.md
  • docs/product/design-foundation.md
  • docs/product/mode-system.md
  • docs/product/l4-customisation.md

This audit reconciles the built codebase against those documents. It is not a destructive process — no changes are made to the codebase during the audit. The output is a report. Changes are executed via subsequent briefs raised against findings.

Pre-Audit Reading

Before beginning any audit work, Alex must read the following documents in full:

  1. docs/product/object-model.md
  2. docs/product/security-posture.md
  3. docs/product/routing-structure.md
  4. docs/product/presentation-tiers.md
  5. docs/product/design-foundation.md
  6. docs/product/mode-system.md
  7. docs/product/l4-customisation.md
  8. docs/ops/standing-rules.md
  9. docs/ops/infrastructure-reference.md
  10. docs/ops/kn-personality-standard.md

These documents are the audit criteria. Every finding must reference the specific document and section it relates to.

Audit Scope

1. Object Model Compliance

Check that the codebase correctly implements the five primitive objects as defined in object-model.md:

  • Are all five objects (Unit, Qualification, Skill Set, RTO, General Education Unit) represented in the codebase?
  • Is rtopacks-db accessed as READ ONLY everywhere? Are there any write operations, migrations, or upserts targeting it?
  • Is the HARD SEPARATION rule enforced — no NRT data in microcredentials-db, no gen-ed data in rtopacks-db, no business data in either?
  • Is all NRT data access going through internal-api.rtopacks.com.au — no direct DB queries from apps?
  • Is the KN sacred count (15,128) referenced correctly wherever KN data is accessed?
  • Is kn_criteria_reasoning accessed only through the correct pathway with no ad-hoc queries against it?

Document all deviations with: file path, line reference, nature of deviation, severity (critical / significant / minor).

2. Security Posture Compliance

Check that the codebase implements the security posture defined in security-posture.md:

  • Is auth implemented as magic link only — no social login providers in the codebase?
  • Are all auth events logged to ops-db?
  • Is there any route or endpoint that exposes data without authentication?
  • Are there any bulk export endpoints — endpoints that return unbounded result sets?
  • Are there any API keys, Worker secrets, or DB credentials visible in client-side code or rendered output?
  • Is rate limiting configured on public-facing Workers and API routes?
  • Is there any structured data markup or sitemap configuration that would expose data object URLs to search engines?
  • Are all export/print events logged to ops-db?
  • Is per-session token embedding implemented? If not, flag as SEC-01 prerequisite.

Document all deviations with: file path, nature of deviation, severity, recommended remediation brief ID.

3. Routing Structure Compliance

Check that the routing structure conforms to routing-structure.md:

  • Map all existing routes across all surfaces (site, workspace, admin, ops)
  • Identify any routes that expose data object URLs publicly without auth
  • Identify any routes not yet in routing-structure.md that should be added (amendment candidates)
  • Confirm that /qual/[code], /unit/[code], /skill-set/[code], /rto/[code], /gen-ed/[code] on the public site are gated or return 404/redirect
  • Confirm that mobile graceful degradation is implemented for Workspace Studio designer below 1280px
  • Identify any routes that exist in the codebase but are not documented in routing-structure.md

Output: A complete route map of all existing routes, with compliance status for each.

4. Presentation Tier Compliance

Check that existing components conform to presentation-tiers.md:

  • Identify all existing qual/unit/RTO presentation components across all apps
  • Map them to the Chip/Card/Drawer/Page tier model — what tier does each existing component correspond to?
  • Identify components that don't fit a tier cleanly — are they missing a tier, or are they tier hybrids?
  • Is the @rtopacks/training-ui package created? If not, flag as the first build priority.
  • Is the sync script (SHARED-01 pattern) in place for sharing components across apps?
  • Is KN content only appearing at Drawer tier and above? Are there any Card or Chip components rendering KN content they should not?
  • Is the print primitive implemented? Where does print functionality currently live, and is it consistent?
  • Is the universal print footer implemented and consistent across all surfaces?
  • Are print events logged?

Output: A component inventory mapping existing components to the tier model, with gaps identified.

5. Design Foundation Compliance

Check that the existing UI conforms to design-foundation.md:

  • Are there any hardcoded hex colour values in component code that should be CSS variables?
  • Are there any components using font weights above 500?
  • Are there any components that are not dark-mode compliant?
  • Are there any external asset dependencies (fonts, icons, images loaded from third-party CDNs) that violate the EXT-ASSET rule?
  • Are there any components using ALL CAPS or Title Case in UI text labels?
  • Is the KN rendering standard (kn-personality-standard.md) correctly implemented wherever KN content appears?

Output: A list of Foundation violations with file paths and severity.

6. Mode System Compliance

Check that the LIVE/GUIDED/COMPLIANCE mode system conforms to mode-system.md:

  • Is the mode system implemented as global session-level state, not component-level state?
  • Is mode persisted in KV for the session duration?
  • Is mode switching logged as a session event in ops-db?
  • Are the three modes (LIVE/GUIDED/COMPLIANCE) implemented consistently across all surfaces?
  • Is the compliance mode export button present and functional on relevant pages?
  • Is the mode selector visible in the navigation of all authenticated surfaces?
  • Is access to compliance mode correctly gated at L4 minimum?

Output: Mode system implementation status — what exists, what is partially implemented, what is missing.

7. Database Integrity Check

Check database usage across the entire codebase:

  • Produce a complete list of all D1 database IDs referenced in the codebase
  • Confirm each ID matches the canonical list in object-model.md and infrastructure-reference.md
  • Identify any database queries that cross the HARD SEPARATION boundaries
  • Confirm that rtopacks-db (334ac8fb) has no write operations anywhere
  • Identify any database references in client-side code (should be zero — all DB access via Workers/API)
  • Confirm all Workers that access external APIs have a corresponding reference doc in docs/ops/ (EXT-API rule)

Output: Database usage map with compliance status.

8. Unresolved Items and Forward Flags

Identify anything in the codebase that represents:

  • A decision that was made and then superseded by the constitution (needs remediation)
  • A feature that was partially implemented and left incomplete
  • An architectural pattern that is inconsistent across the codebase (some surfaces do it one way, others differently)
  • Any TODO, FIXME, HACK, or similar markers that represent known technical debt
  • Any brief IDs referenced in comments or config that have not been executed
  • Any Worker, route, or component that Alex built under its own interpretation rather than a formal brief (flag these for Tim review — they may be correct, incorrect, or need formalising)

The compliance mode export button (observed by Tim, not formally specified) is an example of this last category — it exists, it may be correct, but it needs to be reviewed against mode-system.md and either formalised or corrected.

Output Format

Alex produces a single audit report document at:

docs/product/audit-report-AUDIT-01.md

The report structure:

# AUDIT-01 — Codebase Constitution Audit Report
Date: [date]
Executor: Alex

## Executive Summary
[3–5 sentences: overall compliance posture, critical findings count, recommended priority order]

## Critical Findings
[Items that represent security risks, data integrity risks, or architectural violations]
[Each finding: location, description, relevant constitution document + section, recommended brief ID]

## Significant Findings
[Items that deviate from the constitution but are not immediately critical]
[Same format as critical]

## Minor Findings
[Small inconsistencies, style violations, incomplete implementations]

## Route Map
[Complete table of all routes with compliance status]

## Component Inventory
[Complete table of existing components mapped to presentation tiers]

## Database Usage Map
[Complete table of DB references with compliance status]

## Unresolved Items
[Items flagged for Tim review]

## Recommended Brief Order
[Prioritised list of briefs to raise against audit findings]

## Amendment Candidates
[Items that represent correct current state but are not yet in the constitution — candidates for document amendments]

What Alex Does Not Do During This Audit

  • Does not make any changes to the codebase
  • Does not raise or execute any briefs
  • Does not modify any database
  • Does not redeploy any Workers
  • Does not interpret constitution documents — reports what exists vs what the document says, without editorialising about whether the constitution is correct

If Alex encounters something ambiguous — where the constitution is unclear or where there are conflicting signals — it flags it in the report under "Unresolved Items" for Tim's judgment. It does not resolve ambiguity autonomously during an audit.

Amendment Log

Date Change Authority
2026-04-06 Initial brief written — AUDIT-01 ready to execute Tim Rignold