@accelerationguy/accel 1.0.0

package/modules/radar/src/transform/schemas/playbook.md

@@ -0,0 +1,205 @@
+---
+id: playbook
+name: Remediation Playbook
+version: 1.0.0
+used_by:
+  - remediation-architect
+  - pedagogy-agent
+  - guardrail-generator
+---
+
+## Purpose
+
+A Playbook is the atomic unit of Transform output — a structured remediation plan for a single finding. Where a Finding (@schema:finding) describes what is wrong and why it matters, a Playbook describes how to fix it, why the fix is correct, what risks the fix introduces, and how to verify the fix works.
+
+Playbooks bridge the gap between diagnosis and action through the 4-layer transformation model. Each layer refines the remediation from abstract principle ("externalize secrets") through framework-specific guidance ("use dotenv with validation") to project-specific implementation ("replace lines 12-14 of config/database.py with os.environ lookups"). This layered approach prevents the most common failure mode in AI-generated fixes: context-free suggestions that are technically correct but architecturally wrong for the target codebase.
+
+Every Playbook is governed by an intervention level (@schema:intervention-level) that constrains what Transform is permitted to recommend. A Playbook at the Suggesting level is informational. A Playbook at the Authorizing level is a full change specification with risk assessment and verification plan. The intervention level is not a quality indicator — it is a governance gate that reflects the confidence and evidence behind the remediation.
+
+Playbooks are Layer B (remediation knowledge) output. They are the primary input to the Layer C execution pipeline and, when at Authorizing or Executing level, to Drive for human-supervised change orchestration.
+
+## Template
+
+```markdown
+### {playbook_id}
+
+**Finding:** {finding_ref}
+**Intervention Level:** {intervention_level}
+
+---
+
+#### Transformation Layers
+
+##### Layer 1 — Abstract Pattern
+
+{abstract_pattern}
+
+##### Layer 2 — Framework Mapping
+
+{framework_mapping}
+
+##### Layer 3 — Language Mapping
+
+{language_mapping}
+
+##### Layer 4 — Project Context
+
+{project_context}
+
+---
+
+#### Before (Anti-Pattern)
+
+```{language}
+{before_example}
+```
+
+#### After (Correct Pattern)
+
+```{language}
+{after_example}
+```
+
+---
+
+#### Verification Steps
+
+{verification_steps}
+
+---
+
+#### Risk Metadata
+
+| Dimension | Score | Evidence |
+|-----------|-------|----------|
+| Blast Radius | {blast_radius_score}/5 | {blast_radius_evidence} |
+| Coupling Risk | {coupling_risk_score}/5 | {coupling_risk_evidence} |
+| Regression Probability | {regression_probability_score}/5 | {regression_probability_evidence} |
+| Architectural Tension | {architectural_tension_score}/5 | {architectural_tension_evidence} |
+
+---
+
+#### Educational Context
+
+{educational_context}
+```
+
+## Field Reference
+
+| Field | Type | Required | Description | Valid Values |
+|-------|------|----------|-------------|--------------|
+| `playbook_id` | string | yes | Unique identifier. Format: `PB-{DD}-{NNN}` where DD is the domain number from the source finding and NNN is sequence. | Pattern: `PB-\d{2}-\d{3}` |
+| `finding_ref` | string | yes | The finding this playbook remediates. Must match a valid finding ID from @schema:finding. | Pattern: `F-\d{2}-\d{3}` (e.g., `F-04-001`) |
+| `intervention_level` | enum | yes | Governance tier for this remediation. Determines what Transform is permitted to recommend and what evidence is required. | `suggesting`, `planning`, `authorizing`, `executing` |
+| `abstract_pattern` | string | yes | Layer 1 — The general remediation principle independent of any language, framework, or project. Describes the pattern to apply and why it is correct. | Free-form, 2-4 sentences. Must not reference project-specific files or frameworks. |
+| `framework_mapping` | string | yes | Layer 2 — How the abstract pattern maps to the target project's framework. References framework conventions, idioms, and standard approaches. | Free-form, 2-4 sentences. Must reference the specific framework. |
+| `language_mapping` | string | yes | Layer 3 — Language-specific implementation guidance. Covers syntax, standard library usage, language idioms, and common pitfalls. | Free-form, 2-4 sentences. Must reference the specific language. |
+| `project_context` | string | yes | Layer 4 — Project-specific implementation. References actual files, existing patterns in the codebase, and integration points. This is the most concrete layer. | Free-form, 2-4 sentences. Must reference specific files in the target codebase. |
+| `before_example` | string | yes | Code showing the anti-pattern as it exists in the target codebase. Must be actual code from the codebase, not a generic example. | Fenced code block with language tag. |
+| `after_example` | string | yes | Code showing the correct pattern after remediation. Must be compilable/runnable and follow the project's existing code style. | Fenced code block with language tag. |
+| `verification_steps` | list of strings | yes | Ordered steps to verify the fix works. Each step must be concrete and executable — a command to run, a condition to check, or a behavior to observe. | Minimum 2 steps. Each must be actionable (not "make sure it works"). |
+| `blast_radius_score` | integer | yes | How widely the change ripples through the codebase. | 1 (single file, no dependents) to 5 (cross-system, multiple services affected) |
+| `blast_radius_evidence` | string | yes | Justification for the blast radius score. Must reference specific files, modules, or dependency chains. | Free-form. Must cite concrete artifacts. |
+| `coupling_risk_score` | integer | yes | Whether the change introduces or tightens coupling between components. | 1 (no new coupling) to 5 (creates hard dependency on external system) |
+| `coupling_risk_evidence` | string | yes | Justification for the coupling risk score. Must reference specific interfaces, imports, or dependency relationships. | Free-form. Must cite concrete artifacts. |
+| `regression_probability_score` | integer | yes | Likelihood the change breaks existing functionality. | 1 (change is additive, no existing behavior modified) to 5 (modifies core logic with no test coverage) |
+| `regression_probability_evidence` | string | yes | Justification for the regression probability score. Must reference test coverage data or lack thereof. | Free-form. Must cite test files or coverage metrics. |
+| `architectural_tension_score` | integer | yes | Whether the change conflicts with the codebase's architectural direction. | 1 (aligns with existing patterns) to 5 (contradicts established architecture, requires migration) |
+| `architectural_tension_evidence` | string | yes | Justification for the architectural tension score. Must reference architectural patterns or design decisions in the codebase. | Free-form. Must cite concrete patterns. |
+| `educational_context` | string | no | Pedagogical explanation for AI-assisted developers. Explains why the anti-pattern is harmful and why the remediation is preferred. Written for a developer learning the concept, not an expert. | Free-form, 3-6 sentences. If present, must explain the "why" not just the "what". |
+
+## Validation Rules
+
+1. `playbook_id` must be unique across the entire audit. No two playbooks may share an ID. Format must match `PB-{DD}-{NNN}`.
+2. `finding_ref` must reference an existing finding ID from the current audit. A playbook without a valid source finding is orphaned and invalid.
+3. `intervention_level` must be one of the four enumerated values. The level must be justified by the source finding's confidence — see @schema:intervention-level for minimum confidence thresholds per level.
+4. All four transformation layers must be populated. Layer 1 must not reference project-specific details. Layer 4 must reference project-specific files. If any layer simply repeats another layer's content, the playbook is invalid — each layer must add specificity.
+5. `before_example` and `after_example` must both be non-empty fenced code blocks with a language tag. The before example must show actual code from the target codebase (not a generic illustration). The after example must be syntactically valid in the target language.
+6. `verification_steps` must contain at least 2 concrete steps. Each step must be actionable — a command to run, a file to check, a behavior to observe. "Verify it works" is not a valid step.
+7. All four `risk_metadata` dimensions must have both a score (integer 1-5) and evidence (non-empty string). A score without evidence is an unsupported assertion. Evidence must reference concrete artifacts (files, tests, dependencies), not general claims.
+8. If `educational_context` is present, it must explain why the anti-pattern is harmful (not just what to do instead). A restatement of the after_example in prose is not educational context.
+9. A playbook at `intervention_level: authorizing` or `executing` must have a corresponding verification plan (@schema:verification-plan) and change risk assessment (@schema:change-risk). Playbooks at `suggesting` or `planning` levels do not require these.
+10. The `before_example` and `after_example` must address the same code location. A before example from `config/database.py` paired with an after example from `lib/secrets.py` without explaining the relocation is invalid.
+
+## Examples
+
+### Example: Planning-Level Playbook for Hardcoded Credentials
+
+```markdown
+### PB-04-001
+
+**Finding:** F-04-001
+**Intervention Level:** planning
+
+---
+
+#### Transformation Layers
+
+##### Layer 1 — Abstract Pattern
+
+Secrets must be externalized from source code into environment-injected configuration. This is the principle of separation of configuration from code — application behavior is defined in source, but deployment-specific values (credentials, endpoints, keys) are injected at runtime. Externalization ensures secrets are not version-controlled, are rotatable without code changes, and can differ per environment.
+
+##### Layer 2 — Framework Mapping
+
+In Python web applications using Flask or Django, the standard approach is environment variables loaded via `os.environ` with a `.env` file for local development (using `python-dotenv`). The framework's configuration system should be the single point of secret access — individual modules should not read environment variables directly. Django uses `settings.py`; Flask uses `app.config`.
+
+##### Layer 3 — Language Mapping
+
+Python's `os.environ` provides direct access to environment variables. For required secrets, use `os.environ["KEY"]` (raises `KeyError` if missing) rather than `os.environ.get("KEY")` (returns `None` silently). The `python-dotenv` package loads `.env` files into the environment for local development. Type coercion (e.g., `int(os.environ["PORT"])`) should happen at the configuration boundary, not at point of use.
+
+##### Layer 4 — Project Context
+
+Replace the hardcoded values in `config/database.py` (lines 12-14) with `os.environ["DB_USER"]`, `os.environ["DB_PASS"]`, and `os.environ["DB_HOST"]`. Add `python-dotenv` to `requirements.txt`. Create `.env.example` with placeholder keys (no values) for developer onboarding. Add `.env` to `.gitignore`. The existing `config/__init__.py` already imports from `database.py`, so no import changes are needed.
+
+---
+
+#### Before (Anti-Pattern)
+
+```python
+# config/database.py
+DB_USER = "admin"
+DB_PASS = "pr0d_s3cret_2024"
+DB_HOST = "prod-db.internal.company.com"
+```
+
+#### After (Correct Pattern)
+
+```python
+# config/database.py
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+DB_USER = os.environ["DB_USER"]
+DB_PASS = os.environ["DB_PASS"]
+DB_HOST = os.environ["DB_HOST"]
+```
+
+---
+
+#### Verification Steps
+
+1. Run `grep -r "pr0d_s3cret\|admin\|prod-db.internal" config/` — must return no results (no hardcoded secrets remain)
+2. Run `python -c "from config.database import DB_USER; print(DB_USER)"` with `.env` file present — must print the configured value without error
+3. Run `python -c "from config.database import DB_USER"` without `.env` file or environment variables — must raise `KeyError` (fail-closed behavior)
+4. Verify `.env` is listed in `.gitignore`
+5. Verify `.env.example` exists with keys but no values
+
+---
+
+#### Risk Metadata
+
+| Dimension | Score | Evidence |
+|-----------|-------|----------|
+| Blast Radius | 2/5 | Change is confined to `config/database.py` and `requirements.txt`. One downstream consumer (`config/__init__.py`) imports these values but the interface (variable names) is unchanged. |
+| Coupling Risk | 2/5 | Introduces dependency on `python-dotenv` package and on environment variable availability. Both are standard Python patterns with no lock-in. |
+| Regression Probability | 2/5 | Existing tests in `tests/test_config.py` mock the database configuration. Tests will need `.env` file or environment variables set in test fixtures. Test coverage for config module is 78%. |
+| Architectural Tension | 1/5 | Environment-based configuration aligns with the project's existing pattern in `config/api.py` (line 8) which already uses `os.environ` for the API key. This change makes the database config consistent with established practice. |
+
+---
+
+#### Educational Context
+
+Hardcoded credentials in source code are one of the most common and dangerous security anti-patterns. When secrets are committed to version control, they persist in git history even after removal, they are accessible to anyone with repository access, and they cannot be rotated without a code change and deployment. Environment variable injection separates the secret lifecycle from the code lifecycle — secrets can be rotated, scoped per environment, and managed through dedicated secrets infrastructure without touching application code. The principle extends beyond credentials to any deployment-specific value: API endpoints, feature flags, rate limits.
+```

package/modules/radar/src/transform/schemas/verification-plan.md

@@ -0,0 +1,134 @@
+---
+id: verification-plan
+name: Verification Plan
+version: 1.0.0
+used_by:
+  - execution-validator
+  - guardrail-generator
+---
+
+## Purpose
+
+A Verification Plan defines the checks that must be performed before, after, and in regression testing of a proposed change, along with the conditions that trigger rollback and the procedure to undo the change. Every change that reaches Authorizing or Executing intervention level (@schema:intervention-level) must have a corresponding Verification Plan. Changes at lower levels may optionally include one.
+
+Verification Plans exist because remediation without verification is hope, not engineering. A fix that passes the developer's mental model but breaks an integration test, a deployment pipeline, or a downstream service is worse than no fix — it introduces a new defect while consuming the effort meant to resolve an existing one. Structured verification catches these failures before they propagate.
+
+The three check categories serve different purposes. Pre-change checks establish a baseline — confirming that the system is in a known-good state before the change is applied. Post-change checks confirm the fix works as intended — the anti-pattern is resolved, the new behavior is correct, and the change integrates properly. Regression checks confirm that nothing else broke — the full test suite passes, dependent services respond correctly, and deployment smoke tests succeed.
+
+Rollback criteria and procedures ensure every change is reversible. A change that cannot be rolled back carries inherently higher risk and should be reflected in the change-risk assessment (@schema:change-risk). The rollback procedure must be concrete — "revert the commit" is only valid when the change is a single commit with no database migrations or infrastructure changes.
+
+## Template
+
+```markdown
+### Verification Plan: {change_id}
+
+---
+
+#### Pre-Change Checks
+
+| # | Check | Command/Instruction | Expected Result |
+|---|-------|---------------------|-----------------|
+| 1 | {check_name} | {command_or_instruction} | {expected_result} |
+| 2 | {check_name} | {command_or_instruction} | {expected_result} |
+
+#### Post-Change Checks
+
+| # | Check | Command/Instruction | Expected Result |
+|---|-------|---------------------|-----------------|
+| 1 | {check_name} | {command_or_instruction} | {expected_result} |
+| 2 | {check_name} | {command_or_instruction} | {expected_result} |
+
+#### Regression Checks
+
+| # | Check | Command/Instruction | Expected Result |
+|---|-------|---------------------|-----------------|
+| 1 | {check_name} | {command_or_instruction} | {expected_result} |
+| 2 | {check_name} | {command_or_instruction} | {expected_result} |
+
+---
+
+#### Rollback Criteria
+
+{rollback_criteria}
+
+#### Rollback Procedure
+
+{rollback_procedure}
+```
+
+## Field Reference
+
+| Field | Type | Required | Description | Valid Values |
+|-------|------|----------|-------------|--------------|
+| `change_id` | string | yes | The change this verification plan covers. Must match a change-risk assessment's `change_id` from @schema:change-risk. | Pattern: `CR-\d{3}` |
+| `pre_change_checks` | list of objects | yes | Checks to run before applying the change. Establish that the system is in a known-good state. Each object must contain `check_name`, `command_or_instruction`, and `expected_result`. | Minimum 1 check. At least one must be a test-suite execution. |
+| `pre_change_checks[].check_name` | string | yes | Short descriptive name for the check. | Free-form, max 60 characters. Should describe what is being verified. |
+| `pre_change_checks[].command_or_instruction` | string | yes | The exact command to run or instruction to follow. Must be copy-pasteable into a terminal or actionable without interpretation. | Executable command or concrete instruction. Not "run the tests" — specify which tests. |
+| `pre_change_checks[].expected_result` | string | yes | What the check should produce when the system is in a correct state. Must be observable and unambiguous. | Specific output, exit code, or observable condition. Not "it works." |
+| `post_change_checks` | list of objects | yes | Checks to run after applying the change. Confirm the fix works as intended. Same object structure as pre_change_checks. | Minimum 1 check. Must include at least one check specific to the remediation (not just general tests). |
+| `regression_checks` | list of objects | yes | Checks to confirm no existing functionality is broken. Same object structure as pre_change_checks. | Minimum 1 check. Must include the full test suite or a representative subset. |
+| `rollback_criteria` | list of strings | yes | Conditions under which rollback is required. Each criterion must be a specific, observable condition — not a judgment call. | Minimum 1 criterion. Each must be falsifiable (you can definitively say whether it occurred). |
+| `rollback_procedure` | string | yes | Step-by-step procedure to undo the change and restore the previous state. Must be concrete — specific commands, specific files, specific actions. | Free-form. Must include at least 2 concrete steps. "Undo the change" is not a valid procedure. |
+
+## Validation Rules
+
+1. `change_id` must match a `change_id` from an existing change-risk assessment in the current audit. A verification plan without a corresponding risk assessment is orphaned — the risk profile is unknown.
+2. `pre_change_checks` must contain at least one entry, and at least one check must execute the project's test suite (or relevant subset). If the project has no test suite, this must be noted as a check: "Confirm no test suite exists" with expected result "No test runner configured" — the absence of tests is itself a verifiable condition.
+3. `post_change_checks` must contain at least one check that is specific to the remediation being verified. A generic "run all tests" is a regression check, not a post-change check. Post-change checks must verify that the specific anti-pattern is resolved and the correct pattern is in place.
+4. `regression_checks` must contain at least one check. For projects with a test suite, this must include a full test-suite run. For projects without tests, regression checks must describe manual verification of key functionality.
+5. Every check's `command_or_instruction` must be actionable without interpretation. "Run the relevant tests" is invalid — specify "Run `pytest tests/test_config.py -v`". "Check the deployment" is invalid — specify "Run `curl -s http://localhost:8000/health | jq .status` and confirm output is `ok`".
+6. Every check's `expected_result` must be observable and unambiguous. "It works correctly" is invalid. "Exit code 0, all tests pass, no new warnings" is valid. "Output contains `DB_USER` with non-empty value" is valid.
+7. `rollback_criteria` must contain at least one entry. Each criterion must be a specific, observable condition — not a judgment call. "If something goes wrong" is invalid. "If `pytest tests/` exits with non-zero code after applying the change" is valid. "If application fails to start within 30 seconds of configuration change" is valid.
+8. `rollback_procedure` must contain at least 2 concrete steps. "Revert the change" is valid only when accompanied by the specific revert mechanism (e.g., "Run `git revert HEAD`" or "Restore `config/database.py` from backup at `.radar/backups/CR-001/database.py`"). If the change involves database migrations, infrastructure changes, or external service configuration, the rollback procedure must address each.
+
+## Examples
+
+### Example: Verification Plan for Credential Externalization
+
+```markdown
+### Verification Plan: CR-001
+
+---
+
+#### Pre-Change Checks
+
+| # | Check | Command/Instruction | Expected Result |
+|---|-------|---------------------|-----------------|
+| 1 | Existing tests pass | `pytest tests/ -v` | Exit code 0, all tests pass |
+| 2 | Current config loads | `python -c "from config.database import DB_USER; print(DB_USER)"` | Prints `admin` (current hardcoded value) |
+| 3 | Git working tree clean | `git status --porcelain` | Empty output (no uncommitted changes) |
+
+#### Post-Change Checks
+
+| # | Check | Command/Instruction | Expected Result |
+|---|-------|---------------------|-----------------|
+| 1 | No hardcoded secrets remain | `grep -r "pr0d_s3cret\|admin\|prod-db.internal" config/` | No output (no matches found) |
+| 2 | Config loads from environment | Set `DB_USER=test_user DB_PASS=test_pass DB_HOST=localhost` then run `python -c "from config.database import DB_USER; print(DB_USER)"` | Prints `test_user` |
+| 3 | Missing env vars fail-closed | Run `unset DB_USER && python -c "from config.database import DB_USER"` | Raises `KeyError: 'DB_USER'` |
+| 4 | .env.example exists | `cat .env.example` | Contains `DB_USER=`, `DB_PASS=`, `DB_HOST=` with no values |
+| 5 | .env is gitignored | `git check-ignore .env` | Output: `.env` |
+
+#### Regression Checks
+
+| # | Check | Command/Instruction | Expected Result |
+|---|-------|---------------------|-----------------|
+| 1 | Full test suite | `pytest tests/ -v` with `.env` file present | Exit code 0, all tests pass (including test_config.py) |
+| 2 | Application starts | `python app.py &` with `.env` file, then `curl http://localhost:8000/health` | Returns 200 with `{"status": "ok"}` |
+| 3 | Config module interface unchanged | `python -c "from config import DB_USER, DB_PASS, DB_HOST; print('OK')"` | Prints `OK` (imports still work via config/__init__.py) |
+
+---
+
+#### Rollback Criteria
+
+- `pytest tests/` exits with non-zero code after applying the change and the failures are in config-related tests
+- Application fails to start with error referencing `DB_USER`, `DB_PASS`, or `DB_HOST` environment variables
+- Any downstream service reports connection failures to the database after deployment
+
+#### Rollback Procedure
+
+1. Restore the original `config/database.py` from git: `git checkout HEAD~1 -- config/database.py`
+2. Remove `python-dotenv` from `requirements.txt`: `git checkout HEAD~1 -- requirements.txt`
+3. Remove `.env.example` if it was newly created: `rm .env.example`
+4. Run `pytest tests/ -v` to confirm tests pass with restored hardcoded values
+5. If already deployed: redeploy with the reverted code and confirm database connectivity
+```

package/modules/radar/src/transform/workflows/phase-6-remediation.md

@@ -0,0 +1,148 @@
+<purpose>
+Orchestrates remediation synthesis by invoking the Remediation Architect to group Core findings by root cause and produce layered playbooks, then the Pedagogy Agent to enrich those playbooks with educational context — producing the complete Layer B remediation knowledge base.
+</purpose>
+
+<phase_context>
+Phase: 6 — Remediation Synthesis
+Prior phase output: Complete Core audit record — Phase 5 report (.radar/report/), all findings (.radar/findings/), all disagreements (.radar/disagreements/), resolution records, confidence scores, audit scope (.radar/scope.md)
+Agents invoked: remediation-architect (first), pedagogy-agent (second) — sequential, not parallel
+Output: remediation/playbooks/ (layered remediation plans), remediation/patterns/ (cross-cutting analysis), remediation/REMEDIATION-SUMMARY.md
+</phase_context>
+
+<required_input>
+@.radar/STATE.md
+@.radar/MANIFEST.md
+@.radar/scope.md
+@.radar/report/Radar-REPORT.md
+@.radar/findings/*.md (all agent finding sets)
+@.radar/disagreements/*.md (all disagreement records)
+@~/.claude/radar/transform/agents/remediation-architect.md
+@~/.claude/radar/transform/agents/pedagogy-agent.md
+@~/.claude/radar/transform/schemas/playbook.md
+@~/.claude/radar/transform/schemas/intervention-level.md
+@~/.claude/radar/transform/rules/safety-governance.md
+@~/.claude/radar/transform/rules/change-risk-rules.md
+@~/.claude/radar/transform/workflows/transform-safety.md
+</required_input>
+
+<process>
+
+<step name="validate_prerequisites" priority="first">
+1. Verify .radar/STATE.md shows Phase 5 (Report Generation) complete:
+   a. Check phase_5_complete: true
+   b. Check .radar/report/Radar-REPORT.md exists
+   c. Verify all findings and disagreement records are present
+2. If Phase 5 is not complete:
+   a. Halt with error: "Phase 5 (Report Generation) not complete. Core audit must finish before Transform begins."
+   b. Do not proceed.
+3. Load audit scope to understand remediation boundaries.
+4. Update .radar/STATE.md:
+   a. current_phase: 6
+   b. phase_status: in_progress
+</step>
+
+<step name="load_layer_a_record" priority="blocking">
+1. Load the complete Layer A record:
+   a. All finding files from .radar/findings/ (per-agent finding sets)
+   b. All disagreement records from .radar/disagreements/
+   c. Resolution records and principal responses
+   d. Confidence scores attached to each finding
+   e. Phase 5 report for severity calibration context
+2. Build a unified finding index:
+   a. Total findings by domain, severity, and confidence level
+   b. Cross-references between findings that share code paths or root causes
+   c. Disagreements that affect remediation scope (unresolved high-severity disagreements block remediation for affected findings)
+3. Record Layer A summary metrics in .radar/STATE.md.
+</step>
+
+<step name="invoke_remediation_architect" priority="blocking">
+1. Load agent manifest from src/transform/agents/remediation-architect.md.
+2. Resolve all component references:
+   a. Persona: src/transform/personas/remediation-architect.md
+   b. Domains: all 14 domain modules (src/domains/00-*.md through src/domains/13-*.md)
+   c. Schemas: src/transform/schemas/playbook.md, src/transform/schemas/intervention-level.md
+   d. Rules: src/transform/rules/safety-governance.md, src/transform/rules/change-risk-rules.md
+3. Provide the complete Layer A record as input.
+4. Instruct agent to:
+   a. Group findings by root cause across domain boundaries
+   b. Produce playbooks at all 4 transformation layers (abstract → framework → language → project)
+   c. Classify each playbook by intervention level
+   d. Record unremediated findings with reasons (insufficient confidence, unclear root cause)
+5. Validate all playbook output against src/transform/schemas/playbook.md.
+6. Record remediation-architect session completion in .radar/STATE.md.
+</step>
+
+<step name="validate_intervention_levels" priority="blocking">
+1. Invoke transform-safety workflow (src/transform/workflows/transform-safety.md):
+   a. Pass all playbooks with their intervention level classifications
+   b. Pass finding confidence scores for each referenced finding
+2. Safety workflow validates:
+   a. Confidence gating: each playbook's intervention level matches its evidence base
+   b. Risk threshold check (preliminary — full risk scoring happens in Phase 7)
+   c. No-auto-execution boundary: playbooks contain plans only, no execution commands
+3. Apply any downgrades returned by the safety workflow:
+   a. Record original and downgraded intervention levels
+   b. Add downgrade rationale to affected playbooks
+4. Record safety validation results in .radar/STATE.md.
+</step>
+
+<step name="invoke_pedagogy_agent" priority="blocking">
+1. Load agent manifest from src/transform/agents/pedagogy-agent.md.
+2. Resolve component references:
+   a. Persona: src/transform/personas/pedagogy-agent.md
+   b. Schemas: src/transform/schemas/playbook.md
+   c. Rules: src/transform/rules/safety-governance.md
+3. Provide Remediation Architect's playbook output + original findings.
+4. Instruct agent to:
+   a. Enrich each playbook with educational context at all 4 transformation layers
+   b. Add before/after examples where applicable
+   c. Add "why this matters" explanations grounding fixes in principles
+   d. Add best-practice rationale for each remediation approach
+   e. Surface pattern-level teaching (not just instance-level fixes)
+5. Validate enriched playbooks still conform to playbook schema.
+6. Record pedagogy-agent session completion in .radar/STATE.md.
+</step>
+
+<step name="persist_and_finalize" priority="blocking">
+1. Write all playbook files to remediation/playbooks/:
+   a. One file per root cause group
+   b. Each includes all 4 transformation layers + educational enrichment
+   c. Each carries intervention level classification and confidence metadata
+2. Write cross-cutting pattern analysis to remediation/patterns/:
+   a. Patterns that span multiple root cause groups
+   b. Systemic issues identified across domains
+3. Generate remediation/REMEDIATION-SUMMARY.md:
+   a. Total playbooks generated
+   b. Playbooks by intervention level
+   c. Unremediated findings with reasons
+   d. Key patterns identified
+4. Update .radar/STATE.md:
+   a. current_phase: 6
+   b. phase_status: complete
+   c. phase_6_complete: true
+   d. playbook_count, unremediated_count, intervention_level_distribution
+   e. next_phase: 7
+   f. timestamp
+</step>
+
+</process>
+
+<output>
+Artifacts created:
+- remediation/playbooks/{root-cause-group}.md — Layered remediation playbooks with educational enrichment (one per root cause group)
+- remediation/patterns/{pattern-name}.md — Cross-cutting pattern analysis
+- remediation/REMEDIATION-SUMMARY.md — Phase 6 summary with metrics and intervention level distribution
+- .radar/STATE.md — Updated with Phase 6 completion and remediation metrics
+
+All playbook files conform to src/transform/schemas/playbook.md.
+All intervention levels validated by transform-safety workflow.
+</output>
+
+<error_handling>
+- **Phase 5 not complete:** Halt immediately. Display: "Core audit (Phases 0-5) must complete before Transform begins. Run phase-5-report workflow first." Do not proceed.
+- **Finding cannot be remediated:** Record as "unremediated" with specific reason (insufficient confidence, unclear root cause, conflicting remediation approaches). Include in REMEDIATION-SUMMARY.md. Do not force remediation where evidence is insufficient.
+- **Intervention level downgrade by safety workflow:** Apply downgrade, record rationale. This is correct behavior, not an error. A playbook that claims Authorizing but has Medium confidence MUST be downgraded to Planning.
+- **Pedagogy Agent cannot enrich a playbook:** Mark playbook as "unenriched" with reason. Proceed with remaining playbooks. An unenriched playbook is still a valid remediation plan — it just lacks educational context.
+- **Schema validation failure on playbook output:** Return to producing agent with specific field-level errors. Allow up to 2 retry attempts. On third failure, log playbook as "unvalidated" and flag for manual review.
+- **Unresolved high-severity disagreement blocks remediation:** Do not produce remediation for findings affected by unresolved high-severity disagreements. Record as blocked with reference to disagreement ID. This is safety-correct behavior.
+</error_handling>

package/modules/radar/src/transform/workflows/phase-7-risk-validation.md

@@ -0,0 +1,161 @@
+<purpose>
+Orchestrates change risk validation by invoking the Change Risk Modeler to score every proposed change across 4 risk dimensions, then the Guardrail Generator to produce machine-enforceable constraints from audit patterns — completing the risk-aware remediation pipeline.
+</purpose>
+
+<phase_context>
+Phase: 7 — Change Risk Validation
+Prior phase output: Phase 6 remediation playbooks (remediation/playbooks/), cross-cutting patterns (remediation/patterns/), remediation summary (remediation/REMEDIATION-SUMMARY.md)
+Agents invoked: change-risk-modeler (first), guardrail-generator (second) — sequential, not parallel
+Output: execution/risk-scores.yaml (dimensional risk profiles), remediation/guardrails/ (machine-enforceable constraints), risk assessment report
+</phase_context>
+
+<required_input>
+@.radar/STATE.md
+@.radar/MANIFEST.md
+@.radar/signals/git-history.md
+@.radar/findings/*.md (for guardrail context)
+@remediation/playbooks/*.md (Phase 6 output)
+@remediation/patterns/*.md (cross-cutting patterns)
+@~/.claude/radar/transform/agents/change-risk-modeler.md
+@~/.claude/radar/transform/agents/guardrail-generator.md
+@~/.claude/radar/transform/schemas/change-risk.md
+@~/.claude/radar/transform/schemas/playbook.md
+@~/.claude/radar/transform/schemas/intervention-level.md
+@~/.claude/radar/transform/rules/safety-governance.md
+@~/.claude/radar/transform/rules/change-risk-rules.md
+@~/.claude/radar/transform/workflows/transform-safety.md
+@~/.claude/radar/domains/11-*.md (change risk domain)
+@~/.claude/radar/tools/git-history.md (tool adapter)
+@~/.claude/radar/tools/semgrep.md (tool adapter for guardrail format)
+</required_input>
+
+<process>
+
+<step name="validate_prerequisites" priority="first">
+1. Verify .radar/STATE.md shows Phase 6 (Remediation Synthesis) complete:
+   a. Check phase_6_complete: true
+   b. Check remediation/playbooks/ contains at least one playbook
+   c. Check remediation/REMEDIATION-SUMMARY.md exists
+2. If Phase 6 is not complete:
+   a. Halt with error: "Phase 6 (Remediation Synthesis) not complete. Run phase-6-remediation workflow first."
+   b. Do not proceed.
+3. Load Phase 6 output metrics from .radar/STATE.md.
+4. Update .radar/STATE.md:
+   a. current_phase: 7
+   b. phase_status: in_progress
+</step>
+
+<step name="load_risk_context" priority="blocking">
+1. Load all Phase 6 playbooks from remediation/playbooks/.
+2. Load git-history signals from .radar/signals/git-history.md:
+   a. Change frequency per file/module
+   b. Co-change coupling data
+   c. Contributor patterns
+3. Load codebase structure map (from Phase 0 context).
+4. Load test coverage signals if available.
+5. Build a change inventory:
+   a. Every proposed modification from every playbook
+   b. Affected files, modules, and interfaces per change
+   c. Dependencies between proposed changes
+6. Record change inventory metrics in .radar/STATE.md.
+</step>
+
+<step name="invoke_change_risk_modeler" priority="blocking">
+1. Load agent manifest from src/transform/agents/change-risk-modeler.md.
+2. Resolve all component references:
+   a. Persona: src/transform/personas/change-risk-modeler.md
+   b. Domains: src/domains/11-*.md (change risk domain)
+   c. Tools: src/tools/git-history.md
+   d. Schemas: src/transform/schemas/change-risk.md, src/transform/schemas/intervention-level.md
+   e. Rules: src/transform/rules/safety-governance.md, src/transform/rules/change-risk-rules.md
+3. Provide playbooks + git history + codebase structure as input.
+4. Instruct agent to:
+   a. Score every proposed change across 4 risk dimensions (blast radius, coupling, regression probability, architectural tension)
+   b. Present risk as dimensional profiles, never single aggregate scores
+   c. Flag changes where ANY dimension exceeds "high" threshold
+   d. Identify compound risk where multiple changes target the same module
+5. Validate all risk scores against src/transform/schemas/change-risk.md.
+6. Record change-risk-modeler session completion in .radar/STATE.md.
+</step>
+
+<step name="validate_risk_thresholds" priority="blocking">
+1. Invoke transform-safety workflow (src/transform/workflows/transform-safety.md):
+   a. Pass all risk-scored changes with their dimensional profiles
+   b. Pass current intervention level for each affected playbook
+2. Safety workflow validates:
+   a. Risk threshold check: any dimension exceeding "high" → force intervention level downgrade to Suggesting
+   b. Confidence gating re-check with risk context
+   c. Refusal conditions check (risk exceeds bounds, insufficient test coverage)
+3. Apply any downgrades or refusals:
+   a. Record original and adjusted intervention levels
+   b. Record any refused changes with refusal reasons
+4. Establish final risk-adjusted priority ordering:
+   a. Order changes by combined risk profile (lowest risk first for conservative sequencing)
+   b. Respect dependency ordering from Phase 6 playbooks
+5. Record safety validation results in .radar/STATE.md.
+</step>
+
+<step name="invoke_guardrail_generator" priority="blocking">
+1. Load agent manifest from src/transform/agents/guardrail-generator.md.
+2. Resolve component references:
+   a. Persona: src/transform/personas/guardrail-generator.md
+   b. Tools: src/tools/semgrep.md (rule format reference)
+   c. Schemas: src/transform/schemas/playbook.md
+   d. Rules: src/transform/rules/safety-governance.md, src/transform/rules/change-risk-rules.md
+3. Provide playbooks + risk scores + original findings as input.
+4. Instruct agent to:
+   a. Identify failure patterns that warrant structural prevention
+   b. Produce machine-enforceable constraints organized by mechanism:
+      - CLAUDE.md rules (AI coding assistant constraints)
+      - .cursorrules (IDE-level enforcement)
+      - Custom linter configurations
+      - Pre-commit hook specifications
+      - Custom Semgrep rules (using Semgrep rule format from tool adapter)
+   c. Include failure mode rationale and invalidation conditions per constraint
+   d. Evaluate each constraint against false guardrail test
+5. Validate guardrail output conforms to playbook schema (guardrails are a playbook subtype).
+6. Record guardrail-generator session completion in .radar/STATE.md.
+</step>
+
+<step name="persist_and_finalize" priority="blocking">
+1. Write risk scores to execution/risk-scores.yaml:
+   a. Dimensional risk profile per proposed change
+   b. Final intervention level (post-safety-validation)
+   c. Risk-adjusted priority ordering
+   d. Compound risk warnings
+2. Write guardrail files to remediation/guardrails/:
+   a. Organized by enforcement mechanism
+   b. Each includes failure mode rationale and invalidation conditions
+3. Generate risk assessment report.
+4. Update .radar/STATE.md:
+   a. current_phase: 7
+   b. phase_status: complete
+   c. phase_7_complete: true
+   d. changes_scored, high_risk_count, downgrades_applied, guardrails_generated
+   e. next_phase: 8
+   f. timestamp
+</step>
+
+</process>
+
+<output>
+Artifacts created:
+- execution/risk-scores.yaml — Dimensional risk profiles per proposed change with final intervention levels
+- remediation/guardrails/{mechanism-type}.md — Machine-enforceable constraints organized by enforcement mechanism
+- Risk assessment report (in .radar/reports/ or execution/)
+- .radar/STATE.md — Updated with Phase 7 completion and risk metrics
+
+All risk scores conform to src/transform/schemas/change-risk.md.
+All guardrails conform to src/transform/schemas/playbook.md (guardrail subtype).
+All intervention levels validated by transform-safety workflow.
+</output>
+
+<error_handling>
+- **Phase 6 not complete:** Halt immediately. Display: "Phase 6 (Remediation Synthesis) must complete before risk validation. Run phase-6-remediation workflow first." Do not proceed.
+- **Risk scoring fails for a change:** Default to maximum risk across all 4 dimensions. Flag for human review. Do not assign low risk by default — unknown risk is treated as high risk.
+- **Git history signals unavailable:** Proceed with reduced evidence for coupling and change frequency dimensions. Change Risk Modeler's confidence vectors should reflect limited signal diversity. Blast radius and architectural tension can still be assessed from static structure.
+- **Risk threshold forces intervention level downgrade:** Apply downgrade. This is correct behavior. Record original level, downgraded level, and which dimension triggered the downgrade.
+- **Guardrail generation fails for a pattern:** Record as "unguarded" with reason. Proceed with remaining patterns. A missing guardrail is noted in the output but does not block Phase 7 completion.
+- **False guardrail detected during validation:** Remove the constraint. A constraint that does not actually prevent its target failure mode is worse than no constraint. Log removal with analysis.
+- **Refusal condition met:** Safety workflow refuses to generate remediation for affected findings. Record refusal with specific condition. This is the correct safety behavior — not an error to recover from.
+</error_handling>