@accelerationguy/accel 1.0.0

package/modules/radar/docs/standards/agents.md

@@ -0,0 +1,197 @@
+# Agent Convention
+
+## Purpose
+
+Agents define **ASSEMBLY** — thin composition manifests that declare which persona, domains, tools, schemas, and rules compose each runtime agent. An agent file is not a prompt. It is not an identity description. It is not domain knowledge. It is a bill of materials: a declaration of which components are assembled together to create a functioning audit agent.
+
+The agent manifest is intentionally thin. Identity lives in the persona file. Domain knowledge lives in domain files. Tool execution lives in tool files. Output structure lives in schema files. Behavioral constraints live in rule files. The agent file simply says: "compose these components together, and here are the assembly notes."
+
+Radar uses 12 agent files, one per agent identity, mirroring the persona set. Radar Transform adds 5 agent files for intervention specialists, bringing the total to 17.
+
+## Location
+
+```
+src/core/agents/      (12 Core agent assemblies)
+src/transform/agents/ (5 Transform agent assemblies)
+```
+
+## Naming
+
+**Pattern:** `{kebab-name}.md`
+
+Agent filenames match their corresponding persona filenames. The kebab-name is the shared identifier.
+
+**Examples:**
+- `security-engineer.md`
+- `principal-engineer.md`
+- `sre.md`
+- `devils-advocate.md`
+- `data-engineer.md`
+- `api-designer.md`
+
+## Required Structure
+
+Agent files are **primarily frontmatter**. The body is minimal — assembly notes and session context only.
+
+### Frontmatter (Required)
+
+```yaml
+---
+id: {kebab-name}
+name: [Agent Display Name]
+persona: {persona-id}
+domains: [{DD}, {DD}]
+tools: [{tool-id}, {tool-id}]
+schemas:
+  output: [finding, disagreement]
+  confidence: confidence
+  signal_input: signal
+rules: [epistemic-hygiene, disagreement-protocol]
+active_phases: [{N}, {N}]
+parallel_eligible: [true | false]
+---
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | yes | Kebab-case identifier, must match filename without extension |
+| `name` | string | yes | Human-readable agent display name |
+| `persona` | string | yes | ID of the persona file this agent uses (from `src/personas/`) |
+| `domains` | list of strings | yes | Two-digit domain numbers this agent covers (from `src/domains/`) |
+| `tools` | list of strings | yes | Tool IDs this agent consumes signals from (from `src/tools/`) |
+| `schemas.output` | list of strings | yes | Schema IDs for output format (from `src/schemas/`) |
+| `schemas.confidence` | string | yes | Schema ID for confidence assessment format |
+| `schemas.signal_input` | string | yes | Schema ID for incoming signal format |
+| `rules` | list of strings | yes | Rule IDs this agent must comply with (from `src/rules/`) |
+| `active_phases` | list of integers | yes | Radar phases (0-5 for Core, 6-8 for Transform) where this agent is invoked |
+| `parallel_eligible` | boolean | yes | Whether this agent can run concurrently with others in the same phase |
+
+### Body Sections (Minimal)
+
+The body must contain exactly 2 sections. Keep them short.
+
+| Section | Header | Purpose |
+|---------|--------|---------|
+| Assembly Notes | `## Assembly Notes` | Special composition instructions not captured by the component references alone. |
+| Session Context | `## Session Context` | What context this agent receives at session start — prior phase outputs, signals, schemas to enforce. |
+
+**Critical constraint:** If the body exceeds 20 lines of content (excluding headers and blank lines), content is being duplicated from persona or domain files. Refactor it back to the source.
+
+## Cross-References
+
+| Direction | What | How |
+|-----------|------|-----|
+| References | One persona (`src/personas/`) | `persona: {id}` |
+| References | Multiple domains (`src/domains/`) | `domains: [{DD}, {DD}]` |
+| References | Multiple tools (`src/tools/`) | `tools: [{id}, {id}]` |
+| References | Multiple schemas (`src/schemas/`) | `schemas.output`, `schemas.confidence`, `schemas.signal_input` |
+| References | Multiple rules (`src/rules/`) | `rules: [{id}, {id}]` |
+| Referenced BY | Workflows (`src/workflows/`) | Agent invocation by ID |
+
+Agents are the **hub** of the dependency graph — they reference almost everything and are referenced by workflows.
+
+## Example Skeleton
+
+````markdown
+---
+id: security-engineer
+name: Security Engineer
+persona: security-engineer
+domains: ["04", "06"]
+tools: [semgrep, gitleaks, trivy, grype]
+schemas:
+  output: [finding, disagreement]
+  confidence: confidence
+  signal_input: signal
+rules: [epistemic-hygiene, disagreement-protocol, agent-boundaries]
+active_phases: [1, 2, 3, 4]
+parallel_eligible: true
+---
+
+## Assembly Notes
+
+[Any special composition instructions. Keep this brief — only document behavior
+that isn't captured by the persona + domain combination.
+
+Example: "This agent has primary ownership of domain 04 (Security) and secondary
+review responsibility for domain 06 (Infrastructure). For domain 06, this agent
+focuses exclusively on security-relevant infrastructure concerns (IAM, network
+exposure, secrets in IaC) and defers operational concerns to the SRE agent.
+
+When this agent and the SRE agent both produce findings for domain 06, the
+disagreement resolution workflow arbitrates based on the finding's primary
+concern (security vs. operational)."]
+
+## Session Context
+
+[What this agent receives at session start. Be explicit about which artifacts
+from prior phases are loaded into context.
+
+Example:
+- **Phase 1 input:** Repository structure map, technology inventory, .radar/STATE.md
+- **Phase 2 input:** All normalized signals from tools listed in `tools` field,
+  prior agents' findings for domains listed in `domains` field
+- **Phase 3 input:** Cross-domain findings that reference this agent's domains,
+  disagreement records involving this agent
+- **Phase 4 input:** Consolidated finding set for final severity calibration]
+````
+
+## Transform Agent Conventions
+
+Transform agents follow a different assembly pattern than Core agents, reflecting the centralized intervention model.
+
+**Core Design Principle:** *Diagnosis is decentralized. Intervention is centralized.*
+
+**Key architectural differences:**
+
+| Aspect | Core Agent | Transform Agent |
+|--------|-----------|-----------------|
+| Domain scope | 1-3 specific domains | ALL domains (full finding access) |
+| Execution model | Parallel (independent) | Sequential (coordinated pipeline) |
+| Input source | Tool signals + prior phase findings | Complete Layer A record (all findings, disagreements, reports) |
+| Output target | findings/{agent-id}/ | remediation/ or execution/ |
+| Rule set | Epistemic governance | Epistemic governance + safety rules |
+
+**Transform agent assembly:**
+
+```yaml
+---
+id: remediation-architect
+name: Remediation Architect
+persona: remediation-architect
+domains: ["00", "01", "02", "03", "04", "05", "06", "07", "08", "09", "10", "11", "12", "13"]
+tools: [git-history]
+schemas:
+  output: [playbook, change-risk]
+  confidence: confidence
+  signal_input: finding
+  layer_a_input: [finding, disagreement, report-section]
+rules: [epistemic-hygiene, safety-governance, conservative-bias]
+active_phases: [6, 8]
+parallel_eligible: false
+---
+```
+
+Note the differences from Core assembly:
+- `domains` includes ALL 14 domains (Transform agents see everything)
+- `schemas.signal_input` is `finding` (consumes Layer A findings, not raw tool signals)
+- `schemas.layer_a_input` — new field for Transform agents specifying which Core schemas they consume
+- `rules` includes safety-specific rules alongside shared epistemic rules
+- `parallel_eligible: false` — Transform agents execute sequentially in a coordinated pipeline
+
+**Transform agents consume ALL Core findings,** not just domain-scoped subsets. This is because remediation requires holistic understanding — a security fix may have architectural implications, a performance fix may have testing implications.
+
+**Transform agents share a common intervention pipeline** — they execute sequentially within each phase, not in parallel. Phase 6: Remediation Architect → Pedagogy Agent. Phase 7: Change Risk Modeler → Guardrail Generator. Phase 8: Execution Validator.
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Wrong |
+|--------------|----------------|
+| Duplicating persona content | Identity, mental models, risk philosophy, triggers — all of this belongs in `src/personas/`. If the agent body describes *who* the agent is, that content should be in the persona file instead. The agent manifest just references it. |
+| Duplicating domain knowledge | Failure patterns, audit questions, red flags — all domain knowledge belongs in `src/domains/`. If the agent body lists what to look for, move it to the appropriate domain file. |
+| Large body content | The body should be under 20 lines. Agent files are thin manifests. If you find yourself writing paragraphs, you are putting content in the wrong layer. Ask: "Does this describe identity (persona), knowledge (domain), structure (schema), constraint (rule), or assembly (agent)?" |
+| Missing component references | Every agent must reference at least: one persona, one or more domains, one or more tools, output and confidence schemas, and at least one rule. An agent without rules is ungoverned. An agent without tools has no signal input. Incomplete manifests produce broken agents. |
+| Persona-agent ID mismatch | The agent `id` and `persona` field should align. The agent named `security-engineer` should reference the persona `security-engineer`. Mismatches create confusion about which identity drives which agent. |
+| Embedding prompt instructions | Agent manifests are not prompts. "You are a security expert who should..." is prompt engineering. The persona file handles identity. The workflow handles invocation. The agent file just assembles the pieces. |
+| Transform agent with domain-scoped input | Transform agents must see all findings, not just findings from their 'assigned' domains. Remediation that ignores cross-domain effects produces fixes that create new problems. |
+| Parallel-eligible Transform agents | Transform agents must execute sequentially. The Pedagogy Agent needs the Remediation Architect's output. The Guardrail Generator needs the Change Risk Modeler's scores. Parallelism breaks the intervention pipeline. |

package/modules/radar/docs/standards/commands.md

@@ -0,0 +1,250 @@
+# Command Convention
+
+## Purpose
+
+Commands define **ENTRY** — user-facing slash commands that provide a guided wizard UX for interacting with Radar. Commands are thin wrappers around workflows. They present options, collect user input, validate prerequisites, and delegate execution to the appropriate workflow.
+
+Commands are the only part of Radar that users interact with directly. Everything else — personas, domains, tools, schemas, rules, agents, workflows — operates behind the command layer. A well-designed command makes Radar feel like a guided experience rather than a raw framework.
+
+Radar uses approximately 8 command files: 4 for Core audit operations and 4 for Transform remediation operations.
+
+## Location
+
+```
+src/core/commands/      (Core audit commands)
+src/transform/commands/ (Transform remediation commands)
+```
+
+## Naming
+
+**Pattern:** `{kebab-name}.md`
+
+**Core examples:**
+- `audit.md`
+- `resume.md`
+- `status.md`
+- `report.md`
+
+**Transform examples:**
+- `transform.md`
+- `playbook.md`
+- `remediate.md`
+- `guardrails.md`
+
+Commands are invoked by users as `radar:{kebab-name}` (e.g., `/radar:audit`).
+
+## Required Structure
+
+Every command file consists of YAML frontmatter followed by XML-tagged sections.
+
+### Frontmatter (Required)
+
+```yaml
+---
+name: radar:{kebab-name}
+description: [One-line description]
+argument-hint: "[optional-arg]"
+---
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | yes | Command invocation name. Format: `radar:{kebab-name}` |
+| `description` | string | yes | One-line description shown in command help |
+| `argument-hint` | string | no | Hint for optional arguments (e.g., `"[path-to-repo]"`, `"[phase-number]"`) |
+
+### Body Sections (All Required)
+
+| Section | Tag | Purpose |
+|---------|-----|---------|
+| Objective | `<objective>` | What the command does, when to use it, what it produces. |
+| Execution Context | `<execution_context>` | `@` references to workflows and framework resources the command needs. |
+| Context | `<context>` | Runtime context: arguments, state files, configuration. |
+| Process | `<process>` | Guided wizard flow with numbered options and clear routing to workflows. |
+| Success Criteria | `<success_criteria>` | Measurable outcomes. Checklist of what "done" looks like. |
+
+## Cross-References
+
+| Direction | What | How |
+|-----------|------|-----|
+| References | Core Workflows (`src/core/workflows/`) | By path in `<execution_context>` |
+| References | Transform Workflows (`src/transform/workflows/`) | By path in `<execution_context>` |
+| References | `.radar/` state files | For prerequisite checking and state display |
+| Referenced BY | Users | Slash command invocation (e.g., `/radar:audit`, `/radar:transform`) |
+
+Commands are the **entry points** of the dependency graph. Users invoke commands; commands invoke workflows; workflows invoke agents.
+
+## Example Skeleton
+
+````markdown
+---
+name: radar:audit
+description: Run a Radar audit on a codebase
+argument-hint: "[path-to-repo]"
+---
+
+<objective>
+[What this command does, when to use it, what the user gets.
+
+Example: "Runs a full or partial Radar audit on a target codebase. This is the
+primary entry point for starting a new audit, resuming an interrupted audit, or
+re-running specific phases. Produces a structured audit report with findings,
+severity assessments, and remediation recommendations."]
+</objective>
+
+<execution_context>
+@src/workflows/phase-0-context.md
+@src/workflows/phase-1-reconnaissance.md
+@src/workflows/phase-2-domain-audits.md
+@src/workflows/phase-3-cross-domain.md
+@src/workflows/phase-4-severity-calibration.md
+@src/workflows/phase-5-report.md
+@src/workflows/session-handoff.md
+[Additional workflow references as needed]
+</execution_context>
+
+<context>
+$ARGUMENTS
+@.radar/STATE.md
+@.radar/MANIFEST.md
+</context>
+
+<process>
+
+## Step 1: Determine Audit Scope
+
+Check if $ARGUMENTS contains a repository path. If not, use the current working
+directory.
+
+Check if .radar/STATE.md exists:
+- If YES: An audit is in progress. Present resume options (Step 2).
+- If NO: This is a new audit. Present initialization options (Step 3).
+
+## Step 2: Resume Existing Audit
+
+Display current audit state from .radar/STATE.md:
+- Last completed phase
+- Finding count so far
+- Any unresolved disagreements
+- Any errors or incomplete phases
+
+Present options:
+```
+[1] Resume from last checkpoint (recommended)
+[2] Re-run phase {N} (last completed phase)
+[3] Re-run from phase {N} (specific phase)
+[4] Start fresh (WARNING: deletes existing .radar/ state)
+[5] Cancel
+```
+
+Route to appropriate workflow based on selection.
+
+## Step 3: Initialize New Audit
+
+Display target repository information:
+- Path
+- Detected languages/frameworks
+- Repository size estimate
+
+Present audit scope options:
+```
+[1] Full audit — all phases, all domains (recommended for first run)
+[2] Targeted audit — select specific domains
+[3] Quick scan — phase 0-2 only (reconnaissance + domain audits, no synthesis)
+[4] Cancel
+```
+
+If [2] selected, present domain checklist:
+```
+[ ] 00 — Context
+[ ] 01 — Architecture
+[ ] 02 — Code Quality
+...
+[ ] 13 — Risk Synthesis
+```
+
+After selection, delegate to phase-0-context workflow to begin.
+
+## Step 4: Confirm and Execute
+
+Display audit plan:
+- Scope (full / targeted / quick)
+- Phases to execute
+- Estimated session count
+- Domains included
+
+```
+[1] Start audit (recommended)
+[2] Modify scope
+[3] Cancel
+```
+
+If [1] selected, delegate to first workflow in sequence.
+
+</process>
+
+<success_criteria>
+- [ ] Audit scope is clearly defined and confirmed by user
+- [ ] All prerequisite checks pass (tools installed, repository accessible)
+- [ ] Workflow delegation begins successfully
+- [ ] .radar/ directory is initialized with STATE.md and MANIFEST.md
+- [ ] User receives clear feedback on what will happen next
+</success_criteria>
+````
+
+## Transform Command Conventions
+
+Transform commands are entry points to the remediation pipeline. They follow the same structural conventions as Core commands (frontmatter + XML sections) but include Transform-specific safety requirements.
+
+**The 4 Transform commands:**
+
+| Command | Invocation | Purpose |
+|---------|-----------|---------|
+| Transform | `/radar:transform` | Initiate Transform pipeline on a completed audit |
+| Playbook | `/radar:playbook {finding-id}` | Generate remediation playbook for a specific finding |
+| Remediate | `/radar:remediate` | Generate full remediation plan (all findings) |
+| Guardrails | `/radar:guardrails` | Generate project rules from audit findings |
+
+**Safety requirement:** All Transform commands must display intervention level and confidence information before proceeding with any output generation. The user must confirm before Transform produces output at Planning level or above.
+
+**Example Transform command flow:**
+
+```
+/radar:transform
+
+[1] Check prerequisites:
+    - Verify completed Core audit (.radar/report/ exists)
+    - Verify Layer A integrity (all phases 0-5 complete)
+
+[2] Display Transform scope:
+    - Finding count: N findings across M domains
+    - Estimated playbook count: ~P
+    - Maximum intervention level available: [based on confidence distribution]
+
+[3] Select Transform scope:
+    [1] Full Transform — all findings, all phases (6-8)
+    [2] Selective — choose specific findings or domains
+    [3] Playbooks only — Phase 6 only (no risk scoring or Drive project)
+    [4] Cancel
+
+[4] Confirm and execute:
+    - Display: "Transform will produce remediation at intervention levels: Suggesting (N), Planning (M), Authorizing (K)"
+    - Require explicit confirmation before proceeding
+```
+
+**Transform commands delegate to Transform workflows** in `src/transform/workflows/`, following the same delegation pattern as Core commands.
+
+**Prerequisite enforcement:** Transform commands MUST verify that Core audit is complete before allowing Transform to proceed. A Transform command that runs against an incomplete Layer A record produces unreliable remediation.
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Wrong |
+|--------------|----------------|
+| Embedding execution logic | Commands delegate to workflows; they do not execute audit logic themselves. "Run Semgrep on the codebase" is workflow/tool logic. Commands say "delegate to phase-1-reconnaissance workflow which handles tool execution." |
+| Missing guided wizard options | Commands must present clear, numbered choices at every decision point. Dumping the user into a workflow without confirming scope, showing state, or offering alternatives is poor UX. The command layer exists specifically to provide guided interaction. |
+| No success criteria | Without measurable outcomes, there is no way to verify the command worked. "Audit started" is not a success criterion. "STATE.md created with phase-0 status, MANIFEST.md lists all agents, tools installed and verified" is a success criterion. |
+| Duplicating workflow steps | If the command's `<process>` section contains detailed analysis steps, those steps should be in a workflow file instead. The command guides the user to the right workflow and hands off. It does not replicate the workflow's internals. |
+| Hardcoded paths or tool names | Commands should reference workflows and state files by their standard locations. Hardcoding tool names or specific file paths (beyond `.radar/` conventions) makes commands brittle when the framework evolves. |
+| Missing cancellation options | Every decision point must include a way to cancel or go back. Users should never feel trapped in a command flow. Always include a "Cancel" or "Pause" option. |
+| Transform command without safety display | Every Transform command must show intervention levels and confidence before producing output. Generating remediation without user awareness of the intervention level violates the safety framework. |
+| Transform command that skips prerequisite check | Transform requires a complete Layer A record. A command that allows Transform to run against an incomplete audit produces remediation based on partial information — potentially dangerous. |

package/modules/radar/docs/standards/domains.md

@@ -0,0 +1,191 @@
+# Domain Convention
+
+## Purpose
+
+Domains define **WHAT** to audit. They encode failure patterns, audit questions, red flags, tool affinities, and relevant standards for a specific area of technical concern. A domain is a structured knowledge base — neutral, factual, and independent of any persona's reasoning style.
+
+Domains are the *subject matter* that agents apply their personas against. The security persona applies its attacker mindset to the security domain's failure patterns. The SRE persona applies its reliability thinking to the observability domain's red flags. The domain supplies the knowledge; the persona supplies the reasoning.
+
+Domains also supply the best-practice pattern knowledge that Transform agents use when producing remediation. A domain that only describes failures without corresponding correct patterns cannot feed the Transform pipeline.
+
+Radar uses 14 domain files, numbered 00-13, covering the full surface area of a codebase audit.
+
+## Location
+
+```
+src/domains/
+```
+
+## Naming
+
+**Pattern:** `{DD}-{kebab-name}.md`
+
+The two-digit prefix (`DD`) establishes canonical ordering and serves as the domain's numeric identifier across the framework.
+
+**Examples:**
+- `00-context.md`
+- `01-architecture.md`
+- `04-security.md`
+- `07-testing.md`
+- `13-risk-synthesis.md`
+
+## Required Structure
+
+Every domain file consists of YAML frontmatter followed by 7 markdown-headed sections.
+
+### Frontmatter (Required)
+
+```yaml
+---
+id: domain-{DD}
+number: {DD}
+name: [Domain Name]
+owner_agents: [list of agent IDs that cover this domain]
+---
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | yes | `domain-` prefix followed by two-digit number |
+| `number` | string | yes | Two-digit domain number (e.g., `00`, `04`, `13`) |
+| `name` | string | yes | Human-readable domain name |
+| `owner_agents` | list of strings | yes | Agent IDs (from `src/agents/`) responsible for this domain |
+
+### Body Sections (All Required)
+
+Sections use standard markdown headers (`##`), not XML tags. Order matters.
+
+| Section | Header | Purpose |
+|---------|--------|---------|
+| Overview | `## Overview` | What this domain covers and why it matters to an audit. |
+| Audit Questions | `## Audit Questions` | Specific questions an agent should answer about this domain. Bulleted list. |
+| Failure Patterns | `## Failure Patterns` | Known failure modes. Each with: pattern name, description, indicators, severity tendency. |
+| Best Practice Patterns | `## Best Practice Patterns` | Correct patterns that correspond to each failure pattern. Required for Transform remediation. |
+| Red Flags | `## Red Flags` | Quick indicators that something is wrong. Bulleted list of observable signals. |
+| Tool Affinities | `## Tool Affinities` | Which tools produce signals relevant to this domain. Structured table. |
+| Standards & Frameworks | `## Standards & Frameworks` | Relevant industry standards. Bulleted list with brief relevance notes. |
+| Metrics | `## Metrics` | Quantifiable measurements. Structured table with healthy ranges. |
+
+## Cross-References
+
+| Direction | What | How |
+|-----------|------|-----|
+| Referenced BY | Agent assembly manifests (`src/agents/`) | `domains: [{DD}, {DD}]` field in agent frontmatter |
+| References | Tool IDs (`src/tools/`) | In the Tool Affinities section table |
+| Does NOT reference | Personas, schemas, rules | Domain knowledge is neutral; persona reasoning is applied at runtime |
+| Referenced BY | Transform agents (`src/transform/agents/`) | Transform agents consume domain best-practice patterns for remediation context |
+
+## Example Skeleton
+
+````markdown
+---
+id: domain-04
+number: "04"
+name: [Security]
+owner_agents: [security-engineer]
+---
+
+## Overview
+
+[What this domain covers. Scope boundaries — what's included and what's explicitly
+excluded. Why this domain matters in the context of a codebase audit.
+
+Example: "Covers application-layer security: authentication, authorization, input
+validation, cryptography, secrets management, and dependency vulnerabilities.
+Does NOT cover infrastructure/network security (that's domain-06) or compliance
+frameworks (domain-12)."]
+
+## Audit Questions
+
+- [Question 1 — e.g., "Are all user inputs validated and sanitized before processing?"]
+- [Question 2 — e.g., "Is authentication centralized or scattered across the codebase?"]
+- [Question 3 — e.g., "Are secrets hardcoded, environment-injected, or vault-managed?"]
+- [Question 4 — e.g., "Do dependencies have known CVEs at the versions in use?"]
+- [Question 5 — e.g., "Is authorization checked at every access point or only at the perimeter?"]
+- [Additional questions — aim for 8-15 per domain]
+
+## Failure Patterns
+
+### [Pattern Name — e.g., "Broken Authentication"]
+
+- **Description:** [What this failure pattern is. One to two sentences.]
+- **Indicators:** [Observable signals that this pattern may be present]
+  - [Indicator 1 — e.g., "Custom authentication logic instead of framework-provided"]
+  - [Indicator 2 — e.g., "Session tokens with predictable patterns"]
+  - [Indicator 3 — e.g., "Missing account lockout after failed attempts"]
+- **Severity Tendency:** [typical severity — critical | high | medium | low]
+
+### [Pattern Name — e.g., "Injection Vulnerabilities"]
+
+- **Description:** [What this failure pattern is.]
+- **Indicators:**
+  - [Indicator 1]
+  - [Indicator 2]
+- **Severity Tendency:** [typical severity]
+
+[Repeat for each failure pattern. Aim for 5-10 per domain.]
+
+## Best Practice Patterns
+
+### [Pattern Name — e.g., "Centralized Authentication"]
+
+- **Replaces Failure Pattern:** [Which failure pattern this corrects — e.g., "Broken Authentication"]
+- **Abstract Pattern:** [Language-agnostic principle — e.g., "Authentication should be handled by a single, well-tested module that all request handlers delegate to"]
+- **Framework Mappings:**
+  - [Framework 1]: [Implementation — e.g., "Laravel: Use middleware guards with `auth:sanctum`"]
+  - [Framework 2]: [Implementation — e.g., "Express: Use passport.js with centralized strategy configuration"]
+  - [Framework 3]: [Implementation — e.g., "Spring Boot: Use Spring Security filter chain"]
+- **Language Patterns:**
+  - [Language 1]: [Pattern — e.g., "PHP: `Auth::check()` middleware, never inline credential comparison"]
+  - [Language 2]: [Pattern — e.g., "Node.js: JWT verification middleware with centralized secret management"]
+
+[Repeat for each best practice pattern. Every failure pattern should have a corresponding best practice.]
+
+## Red Flags
+
+- [Red flag 1 — e.g., "Any file named `password`, `secret`, or `key` in source tree"]
+- [Red flag 2 — e.g., "HTTP endpoints accepting user input without validation middleware"]
+- [Red flag 3 — e.g., "Commented-out authentication checks"]
+- [Red flag 4 — e.g., "Use of MD5 or SHA1 for password hashing"]
+- [Additional red flags — quick, observable signals]
+
+## Tool Affinities
+
+| Tool ID | Signal Type | Relevance |
+|---------|-------------|-----------|
+| [semgrep] | [Static analysis findings for injection, auth, crypto patterns] | [primary] |
+| [gitleaks] | [Detected secrets and credentials in source] | [primary] |
+| [trivy] | [Known CVEs in dependencies] | [supporting] |
+| [syft-grype] | [SBOM-based vulnerability matching] | [supporting] |
+
+Relevance levels: `primary` (core signal source), `supporting` (supplementary data), `contextual` (useful but not essential).
+
+## Standards & Frameworks
+
+- [OWASP Top 10 — application security risk taxonomy]
+- [CWE/SANS Top 25 — most dangerous software weaknesses]
+- [NIST SP 800-53 — security and privacy controls (relevant sections)]
+- [Additional standards relevant to this domain]
+
+## Metrics
+
+| Metric | What It Measures | Healthy Range |
+|--------|-----------------|---------------|
+| [Critical CVE count] | [Number of critical-severity known vulnerabilities in dependencies] | [0] |
+| [Secrets detected] | [Count of hardcoded secrets or credentials in source] | [0] |
+| [Input validation coverage] | [Percentage of user-input endpoints with validation] | [95-100%] |
+| [Auth centralization ratio] | [Percentage of auth logic in centralized modules vs scattered] | [>90% centralized] |
+````
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Wrong |
+|--------------|----------------|
+| Embedding persona reasoning style | Writing "A security engineer would think..." imports persona logic into domain knowledge. Domains are neutral knowledge bases. The persona applies its reasoning *to* the domain at runtime. |
+| Including risk judgments or severity assessments | Severity tendency in failure patterns describes *typical* severity, not assessed severity. Actual severity assessment happens in phases 6-7 when agents apply judgment. Domains provide the raw patterns, not the verdict. |
+| Making tool affinities prescriptive | "You MUST run Semgrep" is prescriptive. "Semgrep produces relevant signals for this domain" is descriptive. Workflows decide what runs; domains describe what's useful. |
+| Opinion leaking into failure patterns | "This terrible pattern" or "developers often lazily..." introduces bias. Failure patterns are factual: here is the pattern, here are its indicators, here is its typical severity. No editorializing. |
+| Mixing domain scopes | Each domain has clear boundaries. Security does not discuss testing strategy. Architecture does not discuss deployment. If a concern spans domains, each domain covers its slice and cross-references are handled at the agent level through multi-domain assignments. |
+| Omitting the Tool Affinities section | Even if a domain has no direct tool signals, state that explicitly. An empty section with "No direct tool signals; this domain relies on manual analysis and agent reasoning" is better than a missing section. |
+| Domains that only describe failures | A domain without best-practice patterns cannot feed Transform remediation. Anti-patterns without corresponding correct patterns produce diagnosis without treatment. |
+| Generic best practices without framework mapping | A best practice that says "use authentication middleware" without framework-specific implementations is not actionable at Layers 2-4 of the transformation model. |