[Curriculum] Promote Principle 9 (Diagnostics ≠ Explainability) to a curriculum-wide concept

[rahuldass19]

Problem

QWED Principle 9 states:

Diagnostics are NOT explainability.
Verification diagnostics (status, proof_ref, developer_fields, constraint_id) are structured, machine-readable, and designed for enforcement. AI model explanations (attention maps, rationale text, chain-of-thought) are human-readable, probabilistic, and designed for understanding. They serve different purposes and must never be conflated.

The audit found that only Module 12 (Agentic Security Guards) explicitly teaches this distinction — via the S-CoT guard which allows free-form reasoning (explainability) while verifying structure (diagnostics).

All other modules score PARTIAL on Principle 9. They produce structured diagnostic output (evidence fields, IRAC audit trails, verification receipts) but never teach the learner that this is fundamentally different from AI model explanations.

This is a philosophy gap because:

1. QWED v5.2.0 DiagnosticResult architecture enforces this distinction structurally — Layer 1 (agent_message), Layer 2 (developer_fields), and Layer 3 (proof_ref) are all diagnostics. They are separate from any model explanation that an LLM might produce. The course already references agent_message and evidence but never explains why they exist as separate layers.

2. Conflating diagnostics with explainability is a common failure mode — Guardrails frameworks, LLM-as-Judge, and monitoring tools all claim to "explain" AI behavior. QWED claims something different: to verify it. If the course doesn't teach this distinction, students will treat QWED's diagnostic output as just another kind of explainability tool.

3. It is the most teachable principle — The "Draft vs. Decision" boundary (already in Module 0) naturally maps to this: the LLM provides explanations (draft), QWED provides diagnostics (decision). These are different layers with different trust guarantees.

What needs to change

Module 0 — Add a dedicated Principle 9 section

Insert after the "Proof vs Confidence" file or as a new subsection. Content should cover:

• The distinction: Explanations are from the LLM (probabilistic, narrative, untrusted). Diagnostics are from the verifier (deterministic, structured, trusted).
• Why it matters: An LLM can explain why it gave a wrong answer convincingly. The diagnostic says whether the answer is correct, with a proof_ref that can be independently audited.
• The three layers: agent_message (Layer 1) is safe for end-users. developer_fields (Layer 2) is for engineers. proof_ref (Layer 3) is for auditors. These are not explanations — they are evidence.
• Real example: result.status = "VERIFIED" with proof_ref = "sha256:abc..." is a diagnostic. An LLM saying "I think the answer is correct because the derivative of x^2 is 2x" is an explanation. They look similar. They are not the same thing.

ARCHITECTURE.md — Add a new diagram or section

Add a "Layer Separation" diagram after the existing "Result States Matter" section:

graph LR
    subgraph "LLM (Explainability)"
        A["Natural language reasoning"]
        B["Chain-of-thought"]
        C["Confidence scores"]
    end
    subgraph "QWED (Diagnostics)"
        D["agent_message (Layer 1)"]
        E["developer_fields (Layer 2)"]
        F["proof_ref (Layer 3)"]
    end
    G["These are separate systems"]

Loading

Each module — Add a "Diagnostics vs Explainability" callout

In every module that produces diagnostic output (evidence, IRAC, verification receipts), add a note:

🔍 Diagnostics ≠ Explainability
The structured output you see here (result.status, developer_fields) is a diagnostic — it tells you what the verifier decided and why, in a machine-readable format. It is not an AI model explaining its reasoning. The LLM's chain-of-thought, if any, is a separate signal that must never override this diagnostic verdict.

Specifically:

• Module 3 (Hands-On): Add after the VerificationError and evidence examples
• Module 6 (Domains): Add after the verification receipts section
• Module 9 (DevSecOps): Add after the verification-report.json section
• Module 11 (Legal Auditor): Add after the IRAC audit fields
• Module 13 (Secure Orchestration): Add after the "QWED is the checkpoint" section
• Capstone: Add after the audit_log.jsonl section

CHEAT_SHEET.md — Add a quick-reference line

## Diagnostics vs Explainability
- Diagnostics = structured, machine-readable, enforcement-grade (status, proof_ref, constraint_id)
- Explainability = human-readable, probabilistic, understanding-grade (chain-of-thought, attention)
- QWED produces diagnostics. Never treat them as explanations.

GLOSSARY.md — Add entries

• Diagnostic: A structured verification output (status, agent_message, developer_fields, proof_ref) used for enforcement and audit. Not an explanation.
• Explainability: Human-readable reasoning about why an AI system produced a given output. Probabilistic. Not a substitute for diagnostics.
• Layer 1 (Agent-Safe Diagnostics): Diagnostic output safe for end-users and LLM agents. Contains no implementation details.
• Layer 2 (Developer Diagnostics): Diagnostic output with structured fields for engineers. Contains constraint_id, advisory_checks, symbol tables, etc.
• Layer 3 (Proof Diagnostics): Cryptographic proof artifact reference (proof_ref) that ties a VERIFIED status to a specific verification execution.

Acceptance criteria

• Module 0 has a dedicated Principle 9 section or file explaining diagnostics ≠ explainability
• ARCHITECTURE.md has a new diagram or section on layer separation
• Each module that produces diagnostic output (3, 6, 9, 11, 13) has a callout note
• CHEAT_SHEET.md has a quick-reference line
• GLOSSARY.md has entries for Diagnostic, Explainability, Layer 1/2/3
• A student who completes the course can articulate the difference between diagnostic output and model explanation in their own words

Non-goals

• Rewriting architecture model or result types (Issue [Curriculum] Architecture sync — migrate VerificationResult model to DiagnosticResult + proof_ref #7)
• Changing import paths (Issue [Curriculum] Import path and package reality audit — make every code example runnable #8)
• Version synchronization (Issue [Curriculum] Version and ecosystem synchronization — resolve stale version references and architecture diagrams #9)
• Adding ecosystem content (Issue 4 — qwed-infra module)

Why this is P2

Principle 9 is the most subtle QWED principle. A learner who understands deterministic verification, fail-closed, and proof_ref might still conflate diagnostics with explainability — because in practice, every other AI safety framework presents its output as "explanations." QWED must differentiate. This issue should be addressed after the architecture model is correct (Issue #7) and code examples run (Issue #8), but before adding major new content.