Governance — Master Skill

Skill Classification

DETERMINISTIC — findings are verifiable without AI. GROUNDED — claims traceable to external authority with confidence levels. MODEL-JUDGMENT — requires AI interpretation; review before acting.

Mode Selection

If mode is ambiguous, ask: "Which governance mode? scaffold / adr / tdr / verify / diagram / audit / sanitize"

MODE: scaffold

Initialize the .ai-arch/ Architecture Repository for any new or existing project.

When to scaffold

• User starts a new project
• User says "set up the project properly" or "do this from scratch"
• A project directory exists but has no .ai-arch/ folder
• User asks about project documentation, ADRs, or NFRs

Step 1 — Ask for project context (if not already known)

Confirm before creating files:

1. What does this project do? (one sentence)
2. Who are the users? (list roles)
3. What is the deployment target? (NAS, cloud, laptop, etc.)
4. What data does it handle? (PII? Financial? Public?)
5. What is the timeline / team size?

Extract from existing context if already described. Do NOT ask questions already answered.

Step 2 — Create the .ai-arch/ directory structure

Create all 10 files in <project-root>/.ai-arch/ and a charts/ directory:

.ai-arch/
  01_README.md                  ← What this folder is + TOGAF mapping
  02_PROJECT_CONTEXT.md         ← Why, who, what it is NOT
  03_PRE_PROJECT_CHECKLIST.md   ← 6 governance documents (fill from context)
  04_ASSUMPTIONS.md             ← What must be true for the system to work
  05_COMPLEXITY_ANALYSIS.md     ← Effort estimate with reasoning
  06_ARCHITECTURE_OVERVIEW.md   ← Conceptual layer diagram prose (HTML Link)
  07_ARCHITECTURE_DECISIONS.md  ← Empty ADR log, ready for entries
  08_AI_ASSISTANCE_MAP.md       ← Track AI-generated vs human files
  09_API_REFERENCE.md           ← Core API endpoint catalog
  10_OBSERVABILITY_STRATEGY.md  ← L.M.T.A Framework (Logs, Metrics, Traces, Alerts)
  charts/                       ← Dynamic HTML Architecture Charts
  AUDIT_SCORES.json             ← Audit history (created on first audit run)
  pc2e/                         ← PC2E Mandatory Workspaces files
    SYSTEM_LOG.md
    PORTS.md
    Project_Context.md
    SECURITY_FRAMEWORK.md

Step 3 — Generate ARCHITECTURE_OVERVIEW.md

1. Create the high-res HTML diagram in charts/architecture-overview.html: Do NOT use Mermaid. Use HTML/CSS Grid and Flexbox to build a responsive, native architecture diagram.

• Must include a "Download as PNG" button natively powered by <script src="https://cdnjs.cloudflare.com/ajax/libs/html2canvas/1.4.1/html2canvas.min.js"></script> and a simple click handler.
• Build a dark-mode layered stack: Business → Integration → Intelligence → Delivery
• Include vertical pillars for Data Persistence and Security/Gov
• Avoid absolute positioning; use CSS Flexbox/Grid

2. Create 06_ARCHITECTURE_OVERVIEW.md:

• Do NOT include Mermaid blocks.
• Provide a clear markdown link: 👉 **[View the High-Res HTML Layered Architecture](charts/architecture-overview.html)**
• Follow the link with: one prose paragraph per layer + one per cross-cutting bar.

Step 4 — Add .ai-arch/ to .gitignore

# AI Architecture Repository — internal governance notes, gitignored
.ai-arch/

Step 5 — Fill each file from project context

• PRE_PROJECT_CHECKLIST.md: Complete all 6 sections — Business Case, Stakeholder RACI, NFRs (minimum: performance, security, data retention), Data Classification, Risk Register, Assumptions.
• COMPLEXITY_ANALYSIS.md: Traditional dev vs AI-augmented table, effort drivers, human judgment tasks.
• ARCHITECTURE_DECISIONS.md: Initialize ## Architectural & Technical Trade-Off Matrix table at the top with a baseline entry, and create ADR-001 immediately (framework/stack choice vs alternatives).
• pc2e/SYSTEM_LOG.md: Initialize ## Technical Decision Records (TDR) section template.
• 01_README.md: Include TOGAF ADM Deliverable Mapping (see table below).

TOGAF ADM Deliverable Mapping (embed in 01_README.md):

## TOGAF ADM Deliverable Mapping

| File | TOGAF Phase | Deliverable |
|------|-------------|-------------|
| 01_README.md | Preliminary | Architecture Repository orientation + TOGAF mapping |
| 02_PROJECT_CONTEXT.md | Phase A | Statement of Architecture Work |
| 03_PRE_PROJECT_CHECKLIST.md | Preliminary | Architecture Principles + Capability Assessment |
| 04_ASSUMPTIONS.md | Phase A | Architecture Vision — assumptions & constraints |
| 05_COMPLEXITY_ANALYSIS.md | Phase A | Architecture Vision — feasibility & effort |
| 06_ARCHITECTURE_OVERVIEW.md | Phase A | Architecture Vision (HTML layer diagram) |
| 07_ARCHITECTURE_DECISIONS.md | A–D | Architecture Decision Log (append-only) |
| 08_AI_ASSISTANCE_MAP.md | B–D | Architecture Definition Document — provenance |
| 09_API_REFERENCE.md | Phase C | Architecture Definition Document — interfaces |
| 10_OBSERVABILITY_STRATEGY.md | F–G | Migration Planning / Implementation Governance |
| charts/ | B–D | Domain views |

Source: TOGAF® Standard, 10th Edition (Open Group, 2022). Confidence: HIGH.

Interview Answer (embed in PRE_PROJECT_CHECKLIST.md bottom):

"Six documents before any code is written: Business Case, Stakeholder RACI, NFRs, Data Classification, Risk Register, and Assumptions. The most commonly skipped and most consequential is NFRs — without them, you cannot justify a single architecture decision."

Scaffold Rules

• Never leave placeholder text in generated files
• ADRs must always include rejected alternatives — a decision without alternatives is a guess
• AI_ASSISTANCE_MAP.md must list every file created by AI in this session
• ASSUMPTIONS.md must distinguish: infrastructure assumptions (could be wrong) vs business assumptions (require domain expert)

MODE: adr

Write a new Architecture Decision Record.

When to write ADR (vs TDR)

• Use ADR for macro-architectural decisions:
  • System topology, deployment model, physical/virtual tier splits (e.g. edge vs remote compute node)
  • Data storage paradigm (relational vs document vs graph), replication, and data sovereignty boundaries
  • Authentication and authorization models (RBAC, JWT, session lifecycle, multi-tenant data isolation)
  • Communication patterns and protocols (REST vs gRPC vs SSE vs WebSockets, synchronous vs message queues)
  • Boundary contracts, structural seams, and major architectural refactorings
• User explicitly asks to "log an architecture decision" or "write an ADR".
• Do not use ADR for specific packages, libraries, or tool additions — use tdr mode instead.

ADR Format (strict)

## ADR-XXX — [Decision Title] ([DATE YYYY-MM-DD])

**Context:**
[2-4 sentences. What was the situation? What architectural forces, constraints, or security vectors were active?]

**Decision:** [One clear sentence stating what architectural approach or structure was chosen.]

**Consequences (+):**
- [Positive architectural outcome or capability gained 1]
- [Positive architectural outcome or capability gained 2]

**Consequences (−):**
- [Negative outcome, architectural debt, or operational trade-off 1]
- [Negative outcome, architectural debt, or operational trade-off 2]

**Rejected alternatives:** [Alternative A] ([why rejected with technical rationale]); [Alternative B] ([why rejected with technical rationale]).

ADR Rules

1. Rejected alternatives are mandatory. Minimum 2 per ADR with explicit technical rejection reasons. A decision without alternatives is an unvalidated assumption.
2. ADRs are never edited. If reversed or revised, write a new sequential ADR and mark the old one [SUPERSEDED by ADR-XXX].
3. Number sequentially. Read existing 07_ARCHITECTURE_DECISIONS.md to determine the next number (e.g. ADR-001, ADR-002).
4. Date it accurately. Date when the decision was agreed upon (YYYY-MM-DD), not documented.
5. Consequences must be honest. List real operational and architectural negatives. An ADR with only positives is ungrounded.
6. Mandatory Trade-Off Matrix Update: When appending an ADR to 07_ARCHITECTURE_DECISIONS.md, the agent MUST immediately append or update the corresponding row in the ## Architectural & Technical Trade-Off Matrix at the top of 07_ARCHITECTURE_DECISIONS.md. Also update 08_AI_ASSISTANCE_MAP.md.

MODE: tdr

Write a new Technical Decision Record adhering to Global Rule 8.

When to write TDR (vs ADR)

• Use TDR for technology, package, library, and runtime choices:
  • Introducing any new dependency, framework, npm/pip package, or external tool to a project (Rule 8)
  • Selecting between competing libraries (e.g., Next.js 15 vs Next.js 16, Prisma vs Drizzle, Pino vs Winston, sessionStorage vs localStorage)
  • Concrete runtime utilities, compilation scripts, or CI gate verification helpers (e.g., custom Node audit script vs audit-ci)
  • Choosing specific runtime engines, container base images, or database client drivers
• User asks to "write a TDR", "record tech decision", "log technology choice", or when introducing a dependency.

TDR Format (strict adhering to Global Rule 8)

### TDR-XX: [Technology / Package / Tool Title]

* **Status**: Approved & Implemented ([DATE YYYY-MM-DD])
* **Context**: [2-4 sentences explaining why this technology/tool was needed, the technical gap, or security requirement]
* **Proposed Solution**: [Clear explanation of what the technology does and why this choice over alternatives]
* **Trade-offs & Known Limitations**:
  * [Trade-off or limitation 1]
  * [Trade-off or limitation 2]
* **Alternatives Considered**:
  1. *[Alternative A]*: [Why rejected - concrete technical rationale]
  2. *[Alternative B]*: [Why rejected - concrete technical rationale]
* **Decision**: [Clear concluding rationale for this specific technology]
* **Migration Path**: [Clear exit/migration path if the technology becomes unmaintained, deprecated, or needs upgrading]

TDR Rules

1. Mandatory 4 Core Fields (Rule 8):
   • What it does and why this choice over alternatives
   • Trade-offs and known limitations
   • At least 2 alternatives considered with explicit technical rejection reasons
   • Migration path if it becomes unmaintained, deprecated, or needs major version migration
2. Storage Target: Append to SYSTEM_LOG.md (or .ai-arch/pc2e/SYSTEM_LOG.md or a project docs/decisions/ directory as specified by Rule 8).
3. Number sequentially: Read existing SYSTEM_LOG.md to determine the next number (e.g., TDR-01, TDR-02).
4. Mandatory Trade-Off Matrix Update: When logging a TDR, the agent MUST immediately append or update the corresponding row in the ## Architectural & Technical Trade-Off Matrix located at the top of .ai-arch/07_ARCHITECTURE_DECISIONS.md.
5. No undocumented packages: Never install or commit a new package or framework without a matching TDR.

Architectural & Technical Trade-Off Matrix

Every project maintaining .ai-arch/ MUST maintain a consolidated Architectural & Technical Trade-Off Matrix at the top of 07_ARCHITECTURE_DECISIONS.md.

Matrix Purpose

To provide a scannable, cross-cutting index of all deliberate trade-offs across architecture (ADRs) and technologies (TDRs), ensuring that engineering teams and AI agents immediately understand the costs accepted, compensatory controls applied, and review triggers for every major choice.

7-Column Standard Schema

## Architectural & Technical Trade-Off Matrix

| ID | Decision / Component | Category / Dimension | Benefit Gained (+) | Cost / Trade-off Incurred (−) | Compensating Control / Mitigation | Review / Revisit Trigger |
|---|---|---|---|---|---|---|
| ADR-001 | 3-Tier Edge vs Compute Split | Hardware & Memory | Recovers 8GB+ RAM on primary edge node | Network latency & distributed complexity | Encrypted mesh VPN, automated proxy routing | Edge node hardware upgrade |
| TDR-04 | Next.js 15 Framework Upgrade | Framework & Supply Chain | Resolves critical CVEs within 512MB RAM ceiling | Requires async route parameters | Async parameter handler pattern & backport LTS | Edge container build memory limit increased |

Column Definitions

• ID: ADR-XXX or TDR-XX. If superseded, append [SUPERSEDED by ADR-YYY].
• Decision / Component: Short name of the decision, subsystem, seam, or technology.
• Category / Dimension: Non-functional attribute impacted (e.g. Memory & Hardware, Security & ACE, Storage & PDPA, Multi-Tenancy & Isolation, Framework & Supply Chain, Observability, Latency).
• Benefit Gained (+): Primary positive outcome, capability unlocked, or risk mitigated.
• Cost / Trade-off Incurred (−): Operational cost, technical debt, or limitation accepted.
• Compensating Control / Mitigation: Active mechanism implemented to safeguard against the accepted cost.
• Review / Revisit Trigger: Measurable threshold or event when the decision should be revisited.

Maintenance & Synchronization Rules

1. Synchronous Append: Whenever an ADR or TDR is created, its trade-off row MUST be appended to the matrix during the same edit.
2. Immutability with Supersession: Historical rows are never deleted; if a decision is superseded, append [SUPERSEDED by ADR-YYY] to the ID and annotate the review trigger.
3. Completeness: Gate 2 verification validates that every active ADR and TDR has a corresponding row in the matrix.

Synergy with /improve-codebase-architecture

When using /improve-codebase-architecture to explore deepening opportunities, identify shallow modules, or create seams:

1. Deepened Seam / Module Extraction:
   • If an architectural refactor consolidates shallow modules behind a deep interface, creates a seam, or modifies service boundaries, dispatch /governance adr to log the structural pattern and update the Trade-Off Matrix.
2. New Utility / Package Adoption:
   • If refactoring requires importing an external package, parser, or library, dispatch /governance tdr adhering to Rule 8 (What/Why, Trade-offs, 2 Alternatives, Migration Path) and update the Trade-Off Matrix.
3. Rejection Persistence:
   • If the user rejects an architectural candidate with a load-bearing architectural reason during the grilling loop, record an ADR documenting the rejection and alternatives so future architecture reviews do not re-suggest it.

MODE: verify

Deterministically check which governance gates are missing or incomplete.

Flags

• Default (no flag): --fast mode. File existence and pattern matching only. DETERMINISTIC — findings are reproducible without AI interpretation.
• --deep flag: Also checks file contents for semantic completeness. MODEL-JUDGMENT — output labelled as such. User specifies: "verify compliance --deep" or "deep governance check".

Gate 1 — .ai-arch/ presence

Check: does .ai-arch/ exist with all 10 required files?

Required files: 01_README.md, 02_PROJECT_CONTEXT.md, 03_PRE_PROJECT_CHECKLIST.md, 04_ASSUMPTIONS.md, 05_COMPLEXITY_ANALYSIS.md, 06_ARCHITECTURE_OVERVIEW.md, 07_ARCHITECTURE_DECISIONS.md, 08_AI_ASSISTANCE_MAP.md, 09_API_REFERENCE.md, 10_OBSERVABILITY_STRATEGY.md

PASS: all 10 present | PARTIAL: some missing | FAIL: .ai-arch/ absent

Gate 2 — ADR, TDR & Trade-Off Matrix Quality

Deterministic checks across architectural decisions, technical decisions, and the consolidated trade-off matrix:

1. ADR Check (07_ARCHITECTURE_DECISIONS.md):
   • PASS: Every ADR contains **Rejected alternatives:** with visible text and minimum 2 alternatives.
   • INCOMPLETE: Pattern found but empty, just a dash, or fewer than 2 alternatives.
   • MISSING: No ADRs present at all.
2. TDR Check (SYSTEM_LOG.md or pc2e/SYSTEM_LOG.md or docs/decisions/):
   • PASS: Every TDR contains all 4 mandatory Global Rule 8 elements:
     • What it does and why this choice over alternatives
     • Trade-offs and known limitations
     • At least 2 alternatives considered with technical rejection reasons
     • Migration path if unmaintained or deprecated
   • INCOMPLETE: One or more mandatory Rule 8 fields missing.
   • MISSING: Dependencies or packages added to project without recorded TDRs.
3. Trade-Off Matrix Check (07_ARCHITECTURE_DECISIONS.md):
   • PASS: ## Architectural & Technical Trade-Off Matrix table exists with all 7 columns, and every active ADR and TDR has a corresponding mapped row.
   • PARTIAL: Matrix table exists but some ADRs or TDRs are missing mapped rows.
   • FAIL: Matrix table missing or empty.

Report: N of M ADRs compliant, X of Y TDRs compliant, Trade-Off Matrix synchronized (Z entries mapped).

Gate 3 — Data classification consistency

Read 03_PRE_PROJECT_CHECKLIST.md → locate Data Classification section.

--fast mode (existence only):

• Sensitive/sovereign data present → check charts/dataflow.html exists
• Relational DB confirmed (grep 07_ARCHITECTURE_DECISIONS.md for: PostgreSQL/MySQL/SQLite/postgres/mariadb) → check charts/erd.html exists
• Sovereign/edge/hybrid infra (grep for: sovereign/edge/hybrid/NAS/on-premise) → check charts/deployment.html exists

--deep mode (content check, MODEL-JUDGMENT):

• If charts/erd.html exists: does it contain entity definitions with PII annotations where required?
• If charts/dataflow.html exists: does it show data crossing trust boundaries?
• Label all content findings as MODEL-JUDGMENT in output.

Gate 4 — AI component governance

Grep 06_ARCHITECTURE_OVERVIEW.md and 03_PRE_PROJECT_CHECKLIST.md for: LLM / AI / Ollama / agent / GPT / model / inference / transformer

If found:

• PASS: PRE_PROJECT_CHECKLIST references any documented AI runtime governance framework
• FAIL: AI component found with no governance reference
• Remediation: Document your AI governance framework in the Risk Register. Minimum controls required: anti-hallucination rules, prompt injection defence (structural fencing), context window bounding, phantom commitment prevention, mandatory audit logging.

Gate 5 — NFR completeness

03_PRE_PROJECT_CHECKLIST.md must contain minimum 3 NFR types:

• Performance (grep: performance/latency/response time/throughput/SLA)
• Security (grep: security/authentication/authorisation/OWASP)
• Data retention (grep: retention/deletion/archive/purge)

PASS: all 3 found | PARTIAL: 1-2 found | FAIL: none

Gate 6 — Observability Readiness

Check 10_OBSERVABILITY_STRATEGY.md for L.M.T.A (Logs, Metrics, Traces, Alerts) coverage.

• --fast mode: File exists.
• --deep mode: Check if strategy for Logs, Metrics, Traces, and Alerts are defined and aligned with standards (e.g. OpenTelemetry).

PASS: LMTA defined | PARTIAL: Incomplete | FAIL: File missing or empty

Gate 7 — README Quality

Check for the existence and completeness of the root README.md file.

• --fast mode: Checks if README.md exists in the repository root.
• --deep mode: Checks if README.md contains sections for:
  • Prerequisites (e.g. Node.js/Docker versions).
  • Package installation scripts (npm/pnpm/yarn/bun).
  • Standard runtime execution commands (dev, build, start, test).
  • Environment variables configuration details.

PASS: Root README.md exists and contains all required sections | PARTIAL: Exists but missing key sections | FAIL: Root README.md missing or empty

Gate 8 — Version Management & Auto-Updates

Check for automated package update configurations.

• --fast mode: Checks if .github/dependabot.yml or renovate.json exists.
• --deep mode: Verifies if dependencies are pinned (no loose * or wide ranges for critical libraries) and configured to receive auto-updates.

PASS: Auto-update configurations present and configured | PARTIAL: Config exists but inactive or unpinned dependencies found | FAIL: No automated update configurations found

Gate 9 — Repository Community Standards

Verify that standard repository community guidelines and issue templates exist.

• --fast mode: Checks if LICENSE, SECURITY.md, CODE_OF_CONDUCT.md, SUPPORT.md, and CONTRIBUTING.md exist in the root folder.
• --deep mode: Verifies that .github/ISSUE_TEMPLATE/bug_report.md and feature_request.md are present, configured with default assignees, and warn users against public vulnerability reports.

PASS: All files and templates exist | PARTIAL: Standard files exist but templates missing | FAIL: Any core file (LICENSE/SECURITY) is missing

Gate 10 — PII Compliance & Sanitisation

Ensure that personal developer data is not hardcoded inside committed repository files.

• --fast mode: Scans files (README, Security, Code of Conduct) for hardcoded email/username patterns.
• --deep mode: Verifies that:
  • Maintainer contact details are dynamically populated from .env variables (MAINTAINER_NAME, MAINTAINER_EMAIL, MAINTAINER_GITHUB).
  • Codebase uses a template compiler (compileTemplates.ts) to generate final markdown files from clean template sources (templates/community/*.template).

PASS: PII compliant and templated | PARTIAL: No hardcoded details found but lacks template compilation | FAIL: Hardcoded personal credentials or emails found in committed files

Delta from AUDIT_SCORES.json

If AUDIT_SCORES.json exists in .ai-arch/: read the last verify run and show which gates changed status since then. No delta if no history.

Output format

# Compliance Verification Report

**Repo:** [path]  **Date:** [timestamp]  **Mode:** [--fast / --deep]

## Gate Results

| Gate | Status | Detail |
|------|--------|--------|
| .ai-arch/ presence | ✅ PASS | 10/10 files present |
| ADR quality | ⚠️ PARTIAL | 2 of 4 ADRs missing rejected alternatives |
| Data classification | ✅ PASS | dataflow.html and erd.html present |
| AI governance | ❌ FAIL | AI component found; no governance framework documented in checklist |
| NFR completeness | ✅ PASS | Performance, Security, Retention confirmed |
| Observability | ✅ PASS | LMTA Strategy defined |
| README Quality | ✅ PASS | Root README.md present with prerequisites |
| Version Management | ❌ FAIL | dependabot.yml and renovate.json missing |
| Community Standards | ✅ PASS | LICENSE, SECURITY, and CODE_OF_CONDUCT present |
| PII Compliance | ✅ PASS | All credentials dynamically templated from env |

**Score:** 7.5/10  **Status:** PARTIALLY COMPLIANT

## Findings

### ❌ Gate 4 — AI Governance Missing
- **File:** .ai-arch/03_PRE_PROJECT_CHECKLIST.md
- **Finding:** ARCHITECTURE_OVERVIEW references Ollama. No runtime governance framework documented.
- **Remediation:** Document your AI governance framework in the Risk Register section.
  Minimum controls: anti-hallucination rules, prompt injection defence (structural fencing),
  context window bounding, phantom commitment prevention, mandatory audit logging,
  loop-breaking protocol.
- **Class:** DETERMINISTIC (AI component detected by grep)

### ⚠️ Gate 2 — ADR-003 Missing Rejected Alternatives
- **File:** .ai-arch/07_ARCHITECTURE_DECISIONS.md
- **Finding:** ADR-003 — pattern "**Rejected alternatives:**" not found.
- **Remediation:** Add minimum 2 rejected alternatives.
- **Class:** DETERMINISTIC (pattern match)

After each verify run, append to AUDIT_SCORES.json:

{
  "date": "YYYY-MM-DD",
  "mode": "--fast",
  "gates": {"presence": "PASS", "adr_quality": "PARTIAL", "data_class": "PASS", "ai_governance": "FAIL", "nfr": "PASS", "observability": "PASS", "readme_quality": "PASS", "version_mgmt": "FAIL", "community_standards": "PASS", "pii_compliance": "PASS"},
  "score": 7.5
}

MODE: diagram

Generate dynamic HTML/CSS charts in .ai-arch/charts/. Do NOT use Mermaid.

Invocation

User names the diagram: "draw context diagram", "draw ERD", "draw sequence for [flow]", "draw deployment diagram", "draw state diagram for [entity]", "draw data flow", "draw container diagram".

If not explicitly requested, only 06_ARCHITECTURE_OVERVIEW.md (the conceptual layer diagram) is generated — always mandatory.

HTML Generation Rules

• No Mermaid: Build visual diagrams natively using HTML, CSS Grid, and CSS Flexbox. Avoid brittle absolute positioning.
• Export Script: Every generated .html chart MUST include <script src="https://cdnjs.cloudflare.com/ajax/libs/html2canvas/1.4.1/html2canvas.min.js"></script> and a simple "Download as PNG" button at the top right of the UI.

Mandatory conditions (rule-enforced)

Sub-diagrams

1. Context Diagram (C1) — charts/context.html System as single box at centre. External actors and services as surrounding boxes. Arrows show interaction direction and what flows. Nothing inside the system box — outside-in view only.

2. Container Diagram (C2) — charts/containers.html Each major deployable unit as a box, labelled with technology (e.g., "React + Next.js", "FastAPI", "Ollama"). Arrows between units labelled with protocol. Every technology here must have a corresponding ADR in 07_ARCHITECTURE_DECISIONS.md.

3. Sequence Diagram — charts/sequence_[flow_name].html Vertical timelines or swimlanes per actor/component. Horizontal or flowing vertical blocks in order. Governance gates and HitL checkpoints shown as explicit steps. Max 15 interactions per diagram — break into sub-flows if longer.

4. Deployment Diagram — charts/deployment.html Physical/virtual machines, containers, networks, security zones. Shows where each container runs. Network boundaries as nested CSS Grid rectangles. Data flow arrows labelled with what crosses each boundary and whether it's a trust/sovereignty boundary.

5. State Diagram — charts/state_[entity_name].html States as nodes, transitions as arrows labelled with trigger event. Guards in square brackets [condition]. Governance gates as explicit states. One file per lifecycle entity. Only for entities whose lifecycle drives business logic.

6. ERD — charts/erd.html Entities with key attributes laid out in grid cards. Relationships with cardinality. Primary and foreign keys marked. Any entity containing PII or sensitive data must be annotated with its classification level. Must align with data classification in PRE_PROJECT_CHECKLIST.

7. Data Flow Diagram — charts/dataflow.html Data sources (left) → processing/transformation (middle) → destinations (right). Arrows labelled with what data moves and whether it crosses a trust or sovereignty boundary.

Folder structure

.ai-arch/
├── 01_README.md
├── 02_PROJECT_CONTEXT.md
├── 03_PRE_PROJECT_CHECKLIST.md
├── 04_ASSUMPTIONS.md
├── 05_COMPLEXITY_ANALYSIS.md
├── 06_ARCHITECTURE_OVERVIEW.md    ← always mandatory
├── 07_ARCHITECTURE_DECISIONS.md
├── 08_AI_ASSISTANCE_MAP.md
├── 09_API_REFERENCE.md
├── 10_OBSERVABILITY_STRATEGY.md
├── AUDIT_SCORES.json
├── pc2e/
│   ├── SYSTEM_LOG.md              ← PC2E Mandatory Audit Trail
│   ├── PORTS.md                   ← PC2E Mandatory Port Ledger
│   ├── Project_Context.md         ← PC2E Mandatory High-Level Service Map
│   └── SECURITY_FRAMEWORK.md      ← PC2E Mandatory Security Standards
└── charts/
    ├── context.html
    ├── containers.html
    ├── sequence_[flow].html
    ├── deployment.html
    ├── state_[entity].html
    ├── erd.html
    └── dataflow.html

MODE: audit

Six-pillar code audit with CWE/OWASP citations and weighted comparable scoring.

Step 1 — Determine scope

If path or context already specified, proceed. Otherwise ask: "What should I audit? (directory / feature branch / entire project)"

Step 2 — Check for audit history

Read .ai-arch/AUDIT_SCORES.json if it exists. If present, show delta after scoring.

Pillars

Execute all six in order. Severity levels: CRITICAL, HIGH, MEDIUM, LOW, INFO.

Pillar 1: Tech Debt

Check for:

• Dead code, unused imports, unused dependencies
• TODO/FIXME/HACK/XXX comments (count and categorise)
• Duplicated logic (copy-paste patterns)
• Overly complex functions (cyclomatic complexity > 10, functions > 50 lines)
• Outdated dependencies (major version behind)
• Missing or stale tests for critical paths
• Inconsistent naming conventions
• Hardcoded magic numbers or strings without constants
• Circular dependencies
• Missing error handling (bare catches, swallowed errors)

Tools: grep_search for TODOs/FIXMEs/hardcoded values, list_dir + view_file for structure/complexity, run_command for npm outdated or equivalent, ESLint MCP (lint-files) if available.

Pillar 2: Security

Check for:

• Hardcoded secrets (grep: password=, api_key=, secret=, token=, base64 credentials, bearer tokens)
• SQL injection (string concatenation in queries vs parameterised)
• XSS (unsanitised input rendered in HTML/JSX)
• CSRF (forms without tokens, missing SameSite cookies)
• Insecure dependencies (npm audit or equivalent)
• Missing auth/authorisation on routes
• Overly permissive CORS
• Missing rate limiting on public endpoints
• PII in logs
• Insecure file operations (path traversal, unrestricted uploads)
• Missing input validation on API boundaries
• Docker security (running as root, mounting docker.sock, privileged mode)
• GitHub Actions security:
  • Non-SHA pinned actions (CWE-1395: using tag-based actions instead of SHA hashes).
  • Excessive default permissions for GITHUB_TOKEN (e.g. missing permissions: read-all or explicit minimal scopes in workflow configs).
  • Raw secret exposure (CWE-798: writing secrets directly into run steps/logs).
  • Workflow command injection (CWE-94: evaluating untrusted variables like github.event.issue.title inside shell scripts without escaping/passing via env variables).

Every security finding MUST cite:

- **CWE:** CWE-[ID] ([name])
- **OWASP:** A[NN]:2025 ([category name])

If no CWE/OWASP mapping: downgrade to INFO. Do not fabricate mappings.

Reference table (embed, do not hallucinate IDs):

AI Component Detection (sub-check within Pillar 2):

Grep for: openai, anthropic, gemini, ollama, langchain, langgraph, crewai, agent, llm, inference

If found and no governance documented:

Severity: HIGH
CWE: CWE-1188 (Insecure Default Initialization — insufficient AI oversight)
OWASP: A02: Security Misconfiguration
Description: AI component detected without documented runtime governance framework.
Remediation: Apply a structured AI governance framework covering:
  - Anti-hallucination rules (verify before claiming, cite sources)
  - Prompt injection defence (wrap untrusted inputs in explicit structural fences)
  - Context window bounding (hard clamp num_ctx at API boundary to prevent VRAM exhaustion)
  - Loop-breaking protocol (detect and break agent runaway loops)
  - Phantom commitment prevention (no post-session notifications promised)
  - Mandatory audit logging (all AI decisions logged with rationale)
Document the chosen framework in .ai-arch/03_PRE_PROJECT_CHECKLIST.md Risk Register.

If a documented governance framework is already referenced/applied: downgrade to INFO — AI governance present.

Tools: grep_search, run_command for npm audit, docker inspect, view_file for workflow yaml configurations.

Pillar 3: Deployability

Check for:

• Missing or broken Dockerfile / docker-compose.yml
• Missing health check endpoints
• Missing or incomplete CI/CD configuration (e.g. GitHub Actions workflows)
• Environment-specific hardcoding (localhost URLs, hardcoded ports in app code)
• Missing .env.example or undocumented environment variables
• Build reproducibility (pinned versions, lockfile present)
• Missing graceful shutdown handling (SIGTERM/SIGINT)
• Database migration strategy
• Missing production logging
• Unnecessary dev dependencies in production image
• Missing resource limits in container config
• Rollback strategy documentation
• Mismatched or conflicting lockfiles (e.g. both package-lock.json and pnpm-lock.yaml in the same directory, causing deployment non-determinism).
• Out-of-sync lockfile (lockfile modified date older than package.json, or dependency mismatches).
• Mismatch between package manager commands in scripts (e.g. calling npm run when the codebase uses pnpm).
• Missing runtime configuration details or unpinned Node.js/Bun/Deno runtime engines block in package.json.
• Missing automated dependency update configuration (e.g. .github/dependabot.yml or renovate.json).

Tools: view_file for Dockerfiles, compose files, CI configs, package.json, and lockfiles. grep_search for hardcoded URLs/localhost and dependency manager commands. list_dir to verify expected files and detect duplicate lockfiles.

Pillar 4: Scalability

Check for:

• N+1 query patterns (ORM calls inside loops)
• Missing database indexes on filtered/joined columns
• Synchronous blocking operations in request handlers
• Missing caching strategy
• Monolithic coupling (no clear service boundaries)
• Missing pagination on list endpoints
• Large payloads without streaming
• Missing connection pooling
• Single points of failure (no failover)
• Missing queue/async processing for heavy operations
• Unbounded data growth without archival
• Missing observability (no metrics, no tracing)

Tools: grep_search for query patterns, view_file for DB queries and API handlers.

Pillar 5: Privacy (PDPA/GDPR)

Check for:

• PII collection without documented purpose (names, emails, phone, NRIC, addresses)
• Missing data retention policies
• PII in logs, error messages, stack traces
• Missing encryption at rest and in transit
• Missing consent mechanisms
• Missing data subject access/deletion capabilities
• Cross-border data transfer without safeguards
• Third-party sharing without data processing agreements
• Overly broad data collection
• Missing anonymisation/pseudonymisation for analytics
• Missing audit trail for PII access

Tools: grep_search for PII field patterns (email, phone, nric, address in schemas), view_file for data models and API responses.

Pillar 6: Observability

Check for:

• Missing structured logging framework (e.g., Winston, Pino, Serilog)
• Missing distributed tracing (e.g., OpenTelemetry, Jaeger, Zipkin)
• Missing metrics exposure (e.g., Prometheus /metrics endpoint)
• Missing comprehensive health endpoints (/health/liveness, /health/readiness)
• Hardcoded log destinations instead of stdout/stderr
• Uncaught exception handlers missing logging
• Missing alert routing definitions
• Lack of correlation IDs across distributed boundaries

Tools: grep_search for logger configurations, OpenTelemetry SDKs, health endpoints, and view_file for observability strategy (10_OBSERVABILITY_STRATEGY.md).

Step 3 — Score and output

Weighting formula:

Pillar weights (sum = 100%):
  Security:       25%
  Tech Debt:      20%
  Deployability:  15%
  Privacy:        15%
  Observability:  15%
  Scalability:    10%

Per-finding deductions (pillar score starts at 10, minimum 0):
  CRITICAL: -3.0
  HIGH:     -2.0
  MEDIUM:   -0.5
  LOW:      -0.1

Weighted overall = Σ (pillar_score × pillar_weight)

This formula is fixed. Every audit uses it. Two audits of the same repo are comparable.

Output format:

Produce artifact audit_report.md:

# Dev Audit Report

**Target:** [path]  **Date:** [timestamp]  **Formula version:** 1.1

## Risk Scorecard

| Pillar | Weight | Score | CRITICAL | HIGH | MEDIUM | LOW |
|--------|--------|-------|----------|------|--------|-----|
| Security | 25% | X.X/10 | N | N | N | N |
| Tech Debt | 20% | X.X/10 | N | N | N | N |
| Deployability | 15% | X.X/10 | N | N | N | N |
| Privacy | 15% | X.X/10 | N | N | N | N |
| Observability | 15% | X.X/10 | N | N | N | N |
| Scalability | 10% | X.X/10 | N | N | N | N |
| **Weighted Overall** | 100% | **X.X/10** | **N** | **N** | **N** | **N** |

## Score History (from AUDIT_SCORES.json)

[If history exists:]
| Date | Security | Tech Debt | Deploy | Privacy | Observability | Scale | Overall | Δ Overall |
|------|----------|-----------|--------|---------|---------------|-------|---------|-----------|
| 2026-05-01 | 6.0 | 8.0 | 8.5 | 9.0 | N/A | 7.5 | 7.45 | — |
| 2026-06-17 | 7.5 | 8.0 | 9.0 | 9.0 | 8.0 | 8.0 | 8.05 | +0.60 ↑ |

## Findings

### Security

#### [HIGH] Missing Rate Limiting on Public Endpoints
- **File:** [path#L10-L25]
- **Description:** POST /api/ml/data/upload has no rate limiting middleware.
- **Impact:** Endpoint is vulnerable to resource exhaustion.
- **CWE:** CWE-770 (Allocation of Resources Without Limits)
- **OWASP:** A06:2025 — Insecure Design
- **Remediation:** Add rate-limit middleware (e.g., `express-rate-limit`, `slowapi`). Set max 10 requests/minute per IP.
- **Effort:** small
- **Class:** MODEL-JUDGMENT (confirmed by reading route handler)

...

## Priority Remediation Queue

Ordered by risk × effort (highest impact, lowest effort first):

1. [CRITICAL] ...
2. [HIGH] Missing Rate Limiting — small effort
3. ...

## Deferred / Accepted Risk

- [item] — rationale

Append to AUDIT_SCORES.json after every audit:

{
  "date": "YYYY-MM-DD",
  "target": "[path audited]",
  "formula_version": "1.1",
  "scores": {
    "security": 7.5,
    "tech_debt": 8.0,
    "deployability": 9.0,
    "privacy": 9.0,
    "observability": 8.0,
    "scalability": 8.0,
    "weighted_overall": 8.05
  },
  "finding_counts": {"critical": 0, "high": 1, "medium": 4, "low": 6}
}

AUDIT_SCORES.json stores an array of entries. Append, never overwrite.

Audit Rules

1. Read before judging. Open and inspect every file referenced. Do not guess at contents.
2. Cite with confidence. Every finding links to a specific file and line range. Confidence: HIGH only if file was read.
3. No false positives. Uncertain findings: mark INFO with "verify manually" note, not HIGH.
4. Score honestly. 10/10 means you checked and found zero issues — not that you skipped checking.
5. CWE/OWASP mandatory in Pillar 2. No citation = downgrade to INFO.
6. Formula is fixed. Do not adjust weights per project. Comparability depends on consistency.
7. Respect scope. Audit only what was requested.

MODE: sanitize

Perform a comprehensive scrubbing of Personally Identifiable Information (PII) and internal network/hardware topologies to prepare a repository for public sharing.

When to sanitize

• User asks to "sanitize PII" or "prepare repo for public sharing"
• User explicitly requests scrubbing internal IPs or hardware mentions

Step 1 — Network & Hardware Obfuscation

Check for:

• Internal IP addresses (192.168.x.x, 10.x.x.x, 100.x.x.x etc.)
• Specific proprietary hardware or internal network tooling (e.g., NAS, Synology, Tailscale, Mac Mini M4, DXP4800)

Action:

• Replace internal IP addresses with generic placeholder domains (e.g., internal.network.local) or 1.2.3.4 for examples.
• Abstract hardware to generic cloud-native equivalents:
  • NAS / Synology → Edge Storage Node
  • Tailscale / ZeroTier → Encrypted Mesh VPN
  • Mac Mini M4 → Edge Compute Node

Step 2 — Personal Data (PII) Scrubbing

Check for:

• Developer real names and GitHub handles (e.g., user_name, user_handle)
• Personal email addresses and domains
• *Maintained by...* signatures in markdown documentation

Action:

• Remove developer signatures from markdown files entirely.
• Replace personal emails with generic admin@example.com placeholders.
• Replace personal domains with generic example.com routing.

Step 3 — Container & Configuration Parameterization

Check for:

• Hardcoded host URLs, database connection strings, or system ports inside docker-compose.yml, Dockerfile, or server settings files.

Action:

• Replace raw connection values and parameters with environment variables.
• In container orchestrations (e.g., docker-compose.yml), use variable fallback template syntax: ${VARIABLE:-default_sanitized_placeholder}.
• Target generic local default fallbacks (like localhost, 127.0.0.1, postgres) for the committed configurations.

Step 4 — Gitignore Enforcement

Ensure the .gitignore explicitly prevents the commitment of:

• Internal system datasets (*.csv, *.parquet)
• Serialized ML models (*.pkl, *.pt)
• Analytics and plot output reports

Sanitize Rules

1. Precision: Use rigorous regex (grep_search) to ensure all instances are found before applying changes.
2. Context Awareness: Do not break the compilation of the code; use multi_replace_file_content to surgically replace strings without damaging syntax.
3. Never push automatically: Prepare the commit, but allow the user to push it unless explicitly instructed.

General Rules (All Modes)

1. Read before judging. Open every file you reference. No guessing at contents. (Anti-Hallucination)
2. Cite with confidence. Every external claim references a specific source. HIGH = verified. MEDIUM = inferred. LOW = speculative.
3. No placeholder text. Every generated file is fully populated from context.
4. ADRs and TDRs require rejected alternatives. A decision without alternatives is an unvalidated assumption. ADRs require min 2 rejected alternatives; TDRs require min 2 alternatives considered plus a migration path (Rule 8).
5. Trade-Off Matrix is systematically maintained. Every ADR and TDR must be mapped into the 7-column Architectural & Technical Trade-Off Matrix at the top of 07_ARCHITECTURE_DECISIONS.md.
6. Score formula is version-controlled. Formula version 1.1. If formula changes, bump version. Old scores remain comparable within their version.
7. AI components require governance. Any AI component detected in audit or verify mode must have a documented governance framework. Surface the six minimum controls: anti-hallucination, prompt injection defence (structural fencing), context window bounding, phantom commitment prevention, mandatory audit logging, loop-breaking protocol.
8. Diagram mandatory conditions are enforced, not optional. If relational DB → ERD required. If sensitive data → DATAFLOW required. If sovereign infra → DEPLOYMENT required.
9. AUDIT_SCORES.json is append-only. Never overwrite history.