@accelerationguy/accel 1.0.0

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

@@ -0,0 +1,211 @@
+# Persona Convention
+
+## Purpose
+
+Personas define **WHO** an agent is. They encode identity, risk philosophy, thinking style, mental models, confidence calibration, and hard behavioral constraints. A persona is the cognitive fingerprint of an agent — it determines *how* the agent reasons, *what* it prioritizes, and *where* it draws lines.
+
+Personas must be **strong and distinct**. When composed with domain modules at assembly time, a weak persona gets diluted — its reasoning style flattens into generic analysis. A strong persona maintains its character regardless of which domains it operates across. The security engineer should *think differently* from the principal engineer even when examining the same code.
+
+Radar uses 12 persona files, one per agent identity. Radar Transform adds 5 additional persona files for intervention specialists, bringing the total to 17.
+
+## Location
+
+```
+src/core/personas/      (12 Core audit personas)
+src/transform/personas/ (5 Transform intervention personas)
+```
+
+## Naming
+
+**Pattern:** `{kebab-name}.md`
+
+**Examples:**
+- `principal-engineer.md`
+- `security-engineer.md`
+- `sre.md`
+- `devils-advocate.md`
+- `data-engineer.md`
+- `api-designer.md`
+
+The kebab-name becomes the persona's `id` and is used as the reference key across the framework.
+
+## Required Structure
+
+Every persona file consists of YAML frontmatter followed by exactly 8 XML-tagged sections.
+
+### Frontmatter (Required)
+
+```yaml
+---
+id: {kebab-name}
+name: [Display Name]
+role: [One-line role description]
+active_phases: [list of Radar phases 0-5 where this persona is active]
+---
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | yes | Kebab-case identifier, must match filename without extension |
+| `name` | string | yes | Human-readable display name |
+| `role` | string | yes | One-line description of what this agent is responsible for |
+| `active_phases` | list of integers | yes | Radar phases (0-5 for Core, 6-8 for Transform) where this persona participates |
+
+### Body Sections (All Required)
+
+Each section uses XML tags. Order matters — maintain the sequence below.
+
+| Section | Tag | Purpose |
+|---------|-----|---------|
+| Identity | `<identity>` | Who this agent is. Role, core responsibility, what they are accountable for. |
+| Mental Models | `<mental_models>` | How they think. Bulleted list of reasoning patterns and frameworks. |
+| Risk Philosophy | `<risk_philosophy>` | Stance on risk. Conservative vs aggressive, what they worry about, what they deliberately ignore. |
+| Thinking Style | `<thinking_style>` | Problem-solving approach. Deductive/inductive, depth-first/breadth-first, structured/exploratory. |
+| Triggers | `<triggers>` | What raises concern. Specific patterns, signals, or absences that compel deeper investigation. |
+| Argumentation | `<argumentation>` | How they argue and present findings. Communication style, evidence standards, rhetorical approach. |
+| Confidence Calibration | `<confidence_calibration>` | Self-assessment methodology. When they are certain, when they hedge, how they express uncertainty. |
+| Constraints | `<constraints>` | "Must never" rules. Hard, non-negotiable boundaries on this persona's behavior. |
+
+## Cross-References
+
+| Direction | What | How |
+|-----------|------|-----|
+| Referenced BY | Agent assembly manifests (`src/agents/`) | `persona: {id}` field in agent frontmatter |
+| Does NOT reference | Domains, tools, schemas, rules | Those are composed at assembly time, not baked into identity |
+
+Personas are **leaf nodes** in the dependency graph. They reference nothing; they are only referenced.
+
+## Example Skeleton
+
+````markdown
+---
+id: security-engineer
+name: Security Engineer
+role: Identifies vulnerabilities, threat vectors, and security architecture weaknesses
+active_phases: [1, 2, 3, 4]
+---
+
+<identity>
+[Define who this agent is. What they are responsible for. What outcomes they own.
+Be specific — not "reviews security" but "identifies exploitable vulnerabilities,
+evaluates threat models, and assesses whether security controls match the
+application's risk profile."]
+</identity>
+
+<mental_models>
+- [Mental model 1 — e.g., "Attacker mindset: always asks 'how would I break this?'"]
+- [Mental model 2 — e.g., "Defense in depth: single controls are insufficient"]
+- [Mental model 3 — e.g., "Least privilege: every permission is a potential attack surface"]
+- [Additional models as appropriate for this persona]
+</mental_models>
+
+<risk_philosophy>
+[Describe this persona's relationship with risk. Are they conservative or aggressive?
+What categories of risk keep them up at night? What do they deliberately deprioritize?
+Example: "Treats any unauthenticated endpoint as critical regardless of data sensitivity.
+Willing to accept performance trade-offs for security guarantees. Ignores cosmetic
+code quality issues unless they mask security concerns."]
+</risk_philosophy>
+
+<thinking_style>
+[How does this persona approach a problem? Do they enumerate attack surfaces
+systematically or follow intuition to high-risk areas? Do they work from
+the perimeter inward or from sensitive data outward? Are they exhaustive
+or targeted?]
+</thinking_style>
+
+<triggers>
+- [Trigger 1 — e.g., "Any use of `eval()`, `exec()`, or dynamic code execution"]
+- [Trigger 2 — e.g., "Authentication logic that isn't centralized"]
+- [Trigger 3 — e.g., "Absence of rate limiting on public endpoints"]
+- [Trigger 4 — e.g., "Secrets or credentials adjacent to source code"]
+- [Additional triggers specific to this persona's concerns]
+</triggers>
+
+<argumentation>
+[How does this persona present findings? Do they lead with impact or evidence?
+Do they use formal severity frameworks or narrative risk descriptions?
+Example: "Leads with exploitability — always demonstrates a plausible attack
+path before discussing remediation. Cites CWE/CVE identifiers when applicable.
+Distinguishes between theoretical and practical risk."]
+</argumentation>
+
+<confidence_calibration>
+[When is this persona highly confident? When do they hedge? How do they
+communicate uncertainty?
+Example: "High confidence when a known CVE matches an exact dependency version.
+Medium confidence on architectural weaknesses that require specific deployment
+conditions. Low confidence on business logic flaws outside their security domain.
+Always states assumptions explicitly when confidence is below high."]
+</confidence_calibration>
+
+<constraints>
+- [Constraint 1 — e.g., "Must never dismiss a finding based on 'it's only internal'"]
+- [Constraint 2 — e.g., "Must never assume network segmentation exists without evidence"]
+- [Constraint 3 — e.g., "Must never recommend 'security through obscurity' as a control"]
+- [Additional hard boundaries]
+</constraints>
+````
+
+### Transform Persona Example
+
+````markdown
+---
+id: remediation-architect
+name: Remediation Architect
+role: Translates diagnostic findings into structured, risk-scored remediation plans
+active_phases: [6, 8]
+---
+
+<identity>
+[Not a fixer. Not a coder. An architect of change. Responsible for
+synthesizing disparate findings into coherent, dependency-aware
+remediation plans that minimize risk while maximizing impact.]
+</identity>
+
+[... remaining 7 sections follow the same structure as Core personas
+but with intervention-oriented content ...]
+````
+
+## Transform Persona Conventions
+
+Transform personas are **intervention specialists** — fundamentally different from Core diagnostic personas.
+
+**Core personas optimize for finding truth.** They are aggressive investigators, skeptical of clean narratives, biased toward surfacing problems.
+
+**Transform personas optimize for producing safe, actionable change.** They are conservative planners, biased toward caution, focused on risk management and verification.
+
+**Key differences:**
+
+| Aspect | Core Persona | Transform Persona |
+|--------|-------------|-------------------|
+| Optimization target | Find truth | Produce safe change |
+| Risk posture | Aggressive (find everything) | Conservative (don't break anything) |
+| Output type | Findings (observations + judgments) | Playbooks, risk scores, plans, guardrails |
+| Independence | Operates alone per domain | Coordinates with other Transform agents |
+| Failure mode to avoid | Missing a real problem | Proposing a harmful change |
+
+**The 5 Transform personas:**
+
+| Persona ID | Name | Role | Active Phases |
+|-----------|------|------|--------------|
+| `remediation-architect` | Remediation Architect | Translates diagnosis into structured change plans | [6, 8] |
+| `change-risk-modeler` | Change Risk Modeler | Scores blast radius, coupling, regression, architectural tension | [7] |
+| `pedagogy-agent` | Pedagogy Agent | Explains fixes for AI-assisted developers | [6] |
+| `guardrail-generator` | Guardrail Generator | Writes project rules for future AI usage | [7] |
+| `execution-validator` | Execution Validator | Defines verification plans — how to prove fixes work | [8] |
+
+**Transform persona structure follows the same 8-section format** (identity, mental_models, risk_philosophy, thinking_style, triggers, argumentation, confidence_calibration, constraints) but with intervention-oriented content rather than diagnostic-oriented content.
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Wrong |
+|--------------|----------------|
+| Embedding domain-specific failure patterns | Failure patterns belong in `src/domains/` files. A persona defines *how* an agent thinks, not *what* it knows about specific failure modes. Mixing these makes personas impossible to compose with different domain sets. |
+| Listing specific tools or their outputs | Tool knowledge belongs in `src/tools/` files. Personas should not know or care which tools exist. They interpret signals; they don't operate scanners. |
+| Including output format specifications | Output structure belongs in `src/schemas/` files. A persona reasons; a schema structures the output of that reasoning. |
+| Making the persona so generic it could be any agent | If you can swap two persona files and behavior wouldn't change, the personas are too weak. Each persona must have a *distinctive* reasoning fingerprint — different mental models, different triggers, different risk stances. |
+| Describing what the persona does instead of who they are | "Analyzes code for security issues" is a job description. "Thinks like an attacker, assumes every input is hostile, traces data flow from entry to storage" is an identity. Write identity, not job descriptions. |
+| Overlapping constraints between personas | Constraints that apply to ALL agents belong in `src/rules/`, not in individual personas. Persona constraints are unique to that persona's boundaries. |
+| Transform persona with diagnostic triggers | Transform personas should not trigger on code smells or vulnerabilities — that's Core's job. Transform triggers are about remediation risk: 'proposed change touches 50+ files', 'no tests cover this code path', 'framework migration pattern detected'. |
+| Mixing diagnostic and intervention postures | A persona cannot simultaneously optimize for aggressive truth-finding and conservative change-planning. If you feel the need to merge these, the persona should be split into Core and Transform variants. |

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

@@ -0,0 +1,218 @@
+# Rule Convention
+
+## Purpose
+
+Rules define **CONSTRAINTS** — epistemic governance that applies to all agents uniformly. They are the non-negotiable invariants of the Radar system: principles that no persona can override, no workflow can skip, and no domain can contradict.
+
+Rules exist because multi-agent systems are prone to epistemic drift. Without explicit constraints, agents fabricate confidence, suppress disagreement, anchor on tool output, and produce findings that sound authoritative but lack evidence. Rules prevent these failure modes by codifying the behavioral boundaries that keep agent output honest, calibrated, and defensible.
+
+Radar uses a small number of rule files. Fewer rules with higher enforcement rigor is preferable to many rules with spotty compliance.
+
+Radar Transform introduces additional rule categories for safety governance. Transform rules constrain the intervention pipeline — ensuring that remediation is conservative, confidence-gated, and never auto-executed.
+
+## Location
+
+```
+src/rules/            (Shared — applies to all agents)
+src/transform/rules/  (Transform-specific safety rules)
+```
+
+## Naming
+
+**Pattern:** `{kebab-name}.md`
+
+**Examples:**
+- `epistemic-hygiene.md`
+- `disagreement-protocol.md`
+- `agent-boundaries.md`
+- `safety-governance.md`
+- `conservative-bias.md`
+- `confidence-gating.md`
+
+## Required Structure
+
+Every rule file consists of YAML frontmatter followed by 4 mandatory sections.
+
+### Frontmatter (Required)
+
+```yaml
+---
+id: {kebab-name}
+name: [Rule Name]
+scope: [which component types this rule applies to]
+priority: [critical | quality | guidance]
+---
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | yes | Kebab-case identifier, must match filename without extension |
+| `name` | string | yes | Human-readable rule name |
+| `scope` | string or list | yes | What this rule applies to: `all_agents`, `personas`, `workflows`, `schemas`, `transform_agents`, or a combination |
+| `priority` | enum | yes | `critical` (violation invalidates output), `quality` (violation degrades output), `guidance` (best practice, not enforced) |
+
+### Body Sections (All Required)
+
+| Section | Header | Purpose |
+|---------|--------|---------|
+| Purpose | `## Purpose` | Why this rule exists. What specific failure mode it prevents. What goes wrong without it. |
+| Rules | `## Rules` | Numbered list of rules, each with statement, rationale, and enforcement mechanism. |
+| DO | `## DO` | Concrete examples of conforming behavior. |
+| DON'T | `## DON'T` | Concrete examples of violations with explanation of why each is wrong. |
+
+## Cross-References
+
+| Direction | What | How |
+|-----------|------|-----|
+| Referenced BY | Agent assembly manifests (`src/agents/`) | `rules: [{rule-id}, ...]` field in agent frontmatter |
+| Referenced BY | Workflows (`src/workflows/`) | For enforcement during execution |
+| Does NOT reference | Specific domains, personas, tools | Rules are universal; they don't depend on specific component instances |
+
+## Example Skeleton
+
+````markdown
+---
+id: epistemic-hygiene
+name: Epistemic Hygiene
+scope: all_agents
+priority: critical
+---
+
+## Purpose
+
+[Why this rule exists and what goes wrong without it.
+
+Example: "Without epistemic hygiene rules, agents produce findings that sound
+confident but lack evidence, assert severity without justification, and treat
+tool output as ground truth. This rule ensures that every agent claim is
+grounded in verifiable evidence, every confidence assessment is calibrated
+to actual certainty, and every severity judgment includes explicit reasoning."]
+
+## Rules
+
+### 1. [Rule Statement — e.g., "Every finding must include verifiable evidence"]
+
+**Rationale:** [Why this rule matters. What failure mode it prevents.
+Example: "Findings without evidence are unfalsifiable assertions. They cannot
+be verified, challenged, or acted upon with confidence. Evidence grounds
+findings in observable reality."]
+
+**Enforcement:** [How this rule is checked. Example: "Workflow validation
+step rejects findings where the evidence field contains no file paths,
+code snippets, or signal references."]
+
+### 2. [Rule Statement — e.g., "Confidence must reflect actual certainty, not rhetorical force"]
+
+**Rationale:** [Why this rule matters.
+Example: "Agents default to 'high confidence' because it sounds more
+authoritative. Miscalibrated confidence leads to misallocated remediation
+effort — teams fix 'high confidence' issues first, even if the confidence
+was inflated."]
+
+**Enforcement:** [How this rule is checked. Example: "Agents must provide
+a one-sentence justification for any confidence rating of 'high'. Confidence
+of 'high' without justification is automatically downgraded to 'medium'."]
+
+### 3. [Rule Statement — e.g., "Tool output is signal, not truth"]
+
+**Rationale:** [Why this rule matters.]
+
+**Enforcement:** [How this rule is checked.]
+
+[Additional rules. Aim for 3-7 per rule file. More than 10 indicates the
+file should be split.]
+
+## DO
+
+- [Conforming example 1 — e.g., "Finding states: 'Confidence: medium — Semgrep
+  flagged this pattern but the custom sanitizer at line 45 may handle it.
+  Manual verification needed.'"]
+- [Conforming example 2 — e.g., "Finding severity is 'high' with explicit
+  reasoning: 'Unauthenticated endpoint exposes PII. Impact is data breach
+  of user records. Exploitability is trivial — no authentication required.'"]
+- [Conforming example 3 — e.g., "Agent disagrees with tool output: 'Semgrep
+  reports SQL injection at line 32, but the parameterized query builder at
+  line 28 prevents this. Downgrading to informational — false positive.'"]
+- [Additional examples of correct behavior]
+
+## DON'T
+
+- [Violation 1 — e.g., "Finding states 'Confidence: high' with no justification."]
+  **Why this is wrong:** [Explanation — "Unsubstantiated high confidence inflates
+  the apparent reliability of the finding and distorts prioritization."]
+
+- [Violation 2 — e.g., "Finding repeats Semgrep output verbatim as its description
+  and evidence."]
+  **Why this is wrong:** [Explanation — "Tool output is a signal, not an analysis.
+  The agent's job is to interpret, contextualize, and validate — not to parrot."]
+
+- [Violation 3 — e.g., "Agent assigns 'critical' severity to every finding
+  'to be safe'."]
+  **Why this is wrong:** [Explanation — "Severity inflation is the opposite of
+  safety. When everything is critical, nothing is. Teams learn to ignore severity
+  ratings, defeating the purpose of risk prioritization."]
+
+- [Additional violations with explanations]
+````
+
+## Transform Safety Rules
+
+Transform introduces a new category of rules: **safety governance**. These rules constrain what Transform agents are allowed to produce and at what confidence levels.
+
+**Safety Rule Categories:**
+
+**1. Conservative Bias**
+- Default to the lowest intervention level that serves the user
+- When uncertain about intervention level, downgrade (Authorizing → Planning, Planning → Suggesting)
+- Never escalate intervention level without explicit evidence justification
+- Enforcement: Workflow validates that intervention level assignment includes evidence
+
+**2. Confidence Gating**
+- Minimum finding confidence required per intervention level:
+  - Suggesting: Low (any finding can produce a suggestion)
+  - Planning: Medium (requires at least 2 evidence sources)
+  - Authorizing: High (requires 3+ evidence sources with cross-validation)
+  - Executing (via Drive): High (requires 3+ cross-validated sources)
+- Enforcement: Schema validation rejects playbooks where intervention level exceeds confidence threshold
+
+**3. Unsafe Context Flagging**
+- If any change risk dimension exceeds "high" threshold, flag as unsafe
+- Unsafe changes are automatically downgraded to Suggesting intervention level
+- Must explain why the change is risky (specific dimension and evidence)
+- Enforcement: Risk scoring workflow checks thresholds before allowing higher intervention levels
+
+**4. No Auto-Execution**
+- Radar Transform NEVER applies changes to codebases
+- Transform produces plans; Drive executes plans with human oversight
+- No bypass mechanism, no trusted mode, no override
+- This is a hard architectural boundary, not a configuration option
+- Enforcement: No Transform workflow includes file-modification steps. If a workflow attempts to write to the target codebase (outside `.radar/`), it is a critical violation.
+
+**5. Change Risk Rules**
+- Every remediation must have blast radius assessment with evidence
+- Coupling analysis required before recommending structural changes
+- Regression probability must be stated with evidence (test coverage data)
+- Changes to untested code paths require explicit "no test coverage" warning
+- Enforcement: Playbook schema requires risk_metadata object with all four dimensions
+
+**6. Liability Rules**
+- System is Advisor when producing Suggesting/Planning outputs
+- System is Architectural Actor when producing Authorizing outputs
+- Higher liability levels require higher confidence and lower change risk
+- When acting as Architectural Actor, must include explicit disclaimer and confidence statement
+- Enforcement: Authorizing-level playbooks must include liability acknowledgment section
+
+**Transform rules have `priority: critical` by default.** A Transform agent that violates safety governance produces output that is potentially harmful. Unlike Core rules where a quality violation degrades output, a Transform safety violation can cause damage to the target codebase.
+
+## Anti-Patterns
+
+| Anti-Pattern | Why It's Wrong |
+|--------------|----------------|
+| Rules that are actually domain knowledge | "Always check for SQL injection" is domain knowledge (belongs in `src/domains/`). Rules govern *how agents behave*, not *what they look for*. A rule like "every finding must have evidence" governs behavior universally. |
+| Rules that are persona traits | "Be conservative about risk" is a persona characteristic (belongs in `src/personas/`). Different personas *should* have different risk postures. Rules apply equally to all agents regardless of persona. |
+| Unenforceable rules | "Write good findings" is unenforceable because "good" is undefined. Every rule must have a concrete enforcement mechanism — a validation check, a required field, a measurable criterion. If you can't describe how to detect a violation, the rule is too vague. |
+| Too many rules | Governance fatigue is real. When agents are loaded with 50 rules, they effectively follow zero. Keep rule files few (3-5 files) and keep rules per file focused (3-7 rules). Every rule should justify its existence by preventing a specific, documented failure mode. |
+| Rules without rationale | A rule without a "why" is an arbitrary constraint. Agents (and the humans maintaining Radar) need to understand the reasoning. If you can't articulate why a rule exists, it probably shouldn't. |
+| Rules that duplicate schema validation | "Severity must be one of: critical, high, medium, low, informational" is schema validation (belongs in `src/schemas/`). Rules govern behavior and reasoning quality, not data format compliance. |
+| Safety rules treated as guidance | Transform safety rules are critical, not guidance. A playbook that bypasses confidence gating is not 'slightly wrong' — it is potentially harmful. Treat safety rules with the same rigor as the epistemic hygiene rules. |
+| Generic safety rules without enforcement mechanism | 'Be careful with changes' is not a safety rule. 'Reject playbooks where intervention level is Authorizing and finding confidence is below High' is a safety rule. Every safety rule must have a concrete, automatable enforcement mechanism. |