guardian-framework 0.1.0

package/templates/pi/INDEX.md

@@ -0,0 +1,437 @@
+# Guardian Agent Framework
+
+**Version:** 1.2.0
+**Status:** Template
+**Architecture:** Pi-first
+
+---
+
+## Overview
+
+This framework uses `.pi/` as the source of truth. Other formats (`.claude/`, `.opencode/`, `.agents/`, `.omp/`) are generated exports.
+
+---
+
+## Canonical Reference Requirement
+
+**All implementation files must reference architecture documentation:**
+
+```typescript
+/**
+ * Canonical Reference: .pi/architecture/modules/[module-name].md#[section]
+ * Implements: [spec/AC from architecture]
+ * Last Sync: [date from CHANGELOG]
+ */
+```
+
+**Generated files must include source reference:**
+
+```markdown
+<!--
+Canonical Reference: .pi/[source-path].md
+Generated: [timestamp]
+DO NOT EDIT DIRECTLY - Modify source in .pi/
+-->
+```
+
+**Architecture changes require CHANGELOG entry:**
+
+```markdown
+## [date] - [Change Title]
+
+### Changed
+- Module: [name]
+  - [what changed]
+
+### Impact
+- Files affected: [list]
+- Canonical refs to update: [list]
+- Validators: [which to re-run]
+
+### Migration
+[steps to update implementation]
+```
+
+**Validation:** `validate-canonical.sh` checks reference integrity, coverage, and architecture sync status.
+
+---
+
+## Directory Structure
+
+```
+.pi/
+├── agent/
+│   └── AGENTS.md              # Project instructions + workflow config (YAML front matter)
+│
+├── architecture/              # Architecture documentation (NEW)
+│   ├── modules/               # Module architecture docs
+│   │   ├── auth-system.md
+│   │   ├── data-layer.md
+│   │   ├── api-gateway.md
+│   │   └── [module-name].md
+│   ├── diagrams/              # Architecture diagrams
+│   │   ├── system-overview.md
+│   │   └── data-flow.md
+│   ├── CHANGELOG.md           # Architecture change log (required)
+│   └── decisions/             # Architecture Decision Records (ADR)
+│       ├── ADR-template.md
+│       ├── ADR-001-auth-strategy.md
+│       └── ADR-002-database-choice.md
+│
+├── context/
+│   ├── project.md             # Project facts, commands (template)
+│   ├── patterns.md            # Code templates (template)
+│   ├── checklists.md          # Validation checklists
+│   └── output-formats.md      # Report templates
+│
+├── skills/
+│   ├── agents/
+│   │   ├── architecture-coordinator.md
+│   │   ├── architecture-validator.md
+│   │   ├── security-validator.md
+│   │   ├── operations-validator.md
+│   │   ├── test-validator.md
+│   │   ├── integration-validator.md
+│   │   ├── ci-mr-validator.md
+│   │   ├── code-developer.md
+│   │   ├── documentation-maintainer.md
+│   │   ├── issue-creator.md
+│   │   ├── commit.md            # Clean, logical commits
+│   │   ├── push.md              # Keep remote branch current
+│   │   ├── pull.md              # Sync with latest main
+│   │   ├── land.md              # PR merge loop with validation
+│   │   ├── debug.md             # Systematic debugging
+│   │   ├── subagent-registry.md # Delegated subagent system with tool scoping
+│   │   ├── plan-mode.md         # Queued edits for batch review
+│   │   ├── snippets.md          # Reusable #handle prompt fragments
+│   │   └── session-persistence.md # Session lifecycle management
+│   └── validators/
+│       ├── architecture-validator.md
+│       ├── security-validator.md
+│       ├── security-guards.md     # Path safety + command deny-list
+│       ├── context-compaction.md  # Token-aware context management
+│       ├── system-prompt-tiers.md # Full/lite prompt tiers by model
+│       ├── model-registry.md      # Model capability scoring
+│       ├── operations-validator.md
+│       ├── integration-validator.md
+│       ├── test-validator.md
+│       └── ci-validator.md
+│
+├── prompts/
+│   ├── feature-development.md
+│   ├── bug-fix.md
+│   ├── hotfix.md
+│   ├── refactoring.md
+│   ├── issue-implementation-series.md
+│   ├── epic-plan.md           # Multi-module epic planning (overview + module slice)
+│   ├── issue-draft.md         # Create draft issues from epic
+│   ├── git-issues.md          # Create epics/issues in GitHub/GitLab
+│   ├── issue-closeout.md      # Validate + create compliance MR
+│   ├── issue-merge.md         # Merge MR + close issue + update tracking
+│   ├── plan-to-issues.md      # Convert superpowers plan to issues
+│   ├── blueprint-validate.md  # Validate blueprint integrity
+│   ├── sync-check.md          # Check exports in sync with blueprint
+│   ├── context-refresh.md     # Update context from codebase state
+│   ├── scope-analyzer.md      # Auto-determine scope classification
+│   ├── pattern-extract.md     # Extract patterns to blueprint
+│   └── blueprint-update.md    # Reverse-sync implementation to blueprint
+│
+├── validators/                 # TOML-based declarative validation rules
+│   ├── default.toml           # Built-in validators with inline tests
+│   └── README.md              # Validator documentation
+├── scripts/
+│   ├── validate-ci.sh
+│   ├── validate-tests.sh
+│   ├── validate-operations.sh
+│   ├── validate-security.sh
+│   ├── validate-architecture.sh
+│   ├── validate-canonical.sh  # Canonical reference integrity
+│   ├── validation-cache.sh
+│   ├── fetch-issues.sh
+│   ├── categorize-issues.sh
+│   ├── create-feature-branch.sh
+│   ├── create-mr.sh
+│   ├── mr-validation.sh
+│   └── merge-mr.sh
+│
+├── extensions/
+│   ├── validation-runner.ts   # Pi extension for validation commands
+│   ├── coordinator.ts         # Pi extension for scope classification + validation tools
+│   ├── bash-guard.ts          # Destructive command blocking + path safety guards
+│   ├── filechanges.ts         # File change tracking with accept/decline
+│   ├── read-only-mode.ts      # Safe exploration mode (read/grep/find/ls only)
+│   ├── ask-user-question.ts   # Structured question tool (text/single/multi-select)
+│   ├── config-reload.ts       # Dynamic config reload on AGENTS.md change
+│   ├── plan-mode.ts           # Queued mutations for batch review (/plan)
+│   ├── slash-commands.ts      # /init, /validate, /scope, /snippet commands
+│   ├── session-persistence.ts # Structured session lifecycle with auto-titling
+│   ├── snippets.ts            # #handle token expansion and management
+│   └── redaction.ts           # Automatic secret redaction in output
+│
+├── workpad.md                 # Persistent session progress tracker
+├── github/                    # GitHub Copilot CLI templates
+│   ├── copilot-instructions.md    # Main project instructions
+│   ├── instructions/
+│   │   ├── architecture.instructions.md
+│   │   └── validation.instructions.md
+│   ├── agents/
+│   │   ├── architecture-coordinator.agent.md
+│   │   └── epic-planner.agent.md
+│   └── copilot/
+│       └── settings.json      # Copilot CLI settings
+│
+├── INDEX.md                   # This file
+└── README.md                  # Complete documentation
+```
+
+---
+
+## Architecture Module Documentation
+
+Each module in `.pi/architecture/modules/` follows this structure:
+
+```markdown
+# [Module Name] Architecture
+
+<!--
+Canonical Reference: .pi/architecture/modules/[module-name].md
+Source: Blueprint (do not modify implementation directly)
+-->
+
+## Overview
+[Module purpose and scope]
+
+## Components
+| Component | File | Purpose |
+|-----------|------|---------|
+| [name] | src/[path] | [what it does] |
+
+## Data Flow
+[How data moves through this module]
+
+## Dependencies
+- Depends on: [other modules]
+- Used by: [other modules]
+
+## Security Considerations
+[Security requirements for this module]
+
+## Testing Requirements
+[Unit, integration, e2e tests needed]
+
+## Change Log References
+- 2026-04-26: [change] → see CHANGELOG.md#[section]
+```
+
+---
+
+## Repository Tool
+
+The framework supports both GitHub and GitLab:
+
+| Tool | CLI | Platform |
+|------|-----|----------|
+| `gh` | GitHub CLI | GitHub.com |
+| `glab` | GitLab CLI | GitLab.com or self-hosted |
+
+Selected during `guardian init` and used in all git-related workflows.
+
+---
+
+## Agent Directory
+
+| Agent | Role | When to Use | Mode |
+|-------|------|-------------|------|
+| `architecture-coordinator` | Master orchestrator | All tasks | primary |
+| `architecture-validator` | Architecture check | Moderate+ scope | subagent |
+| `security-validator` | Security check | Complex+ scope | subagent |
+| `operations-validator` | Operations check | Plan review | subagent |
+| `test-validator` | Test validation | Post-code | subagent |
+| `integration-validator` | Integration check | Complex+ scope | subagent |
+| `ci-validator` | CI/merge | All PRs (automated) | subagent |
+| `code-developer` | Implementation | All code tasks | subagent |
+| `issue-creator` | Issue tracking | All tasks | subagent |
+| `documentation-maintainer` | Doc sync | Architecture changes | subagent |
+
+---
+
+## Scope Classification
+
+| Scope | Files | Lines | Required Validators |
+|-------|-------|-------|---------------------|
+| Simple | 1 | < 50 | ci + canonical (automated) |
+| Moderate | 2-5 | 50-200 | ci + architecture + canonical |
+| Complex | 5-15 | 200-500 | ci + architecture + security + canonical |
+| Critical | 15+ or core | 500+ | All validators + canonical + human approval |
+
+---
+
+## Automated Scripts
+
+| Script | Checks |
+|--------|--------|
+| `validate-ci.sh` | Build, test, lint, format, audit |
+| `validate-tests.sh` | Unit, integration, coverage |
+| `validate-operations.sh` | Tracing, cancellation, atomic writes |
+| `validate-security.sh` | Secrets, injection, path traversal |
+| `validate-architecture.sh` | Architecture patterns, dependencies |
+| `validate-canonical.sh` | Canonical reference integrity, coverage, architecture sync |
+| `validation-cache.sh` | Retry optimization |
+
+---
+
+## Workflows
+
+### Standard Workflows
+
+| Workflow | File | Use When |
+|----------|------|----------|
+| Feature Development | `prompts/feature-development.md` | New features |
+| Bug Fix | `prompts/bug-fix.md` | Bug fixes |
+| Emergency Hotfix | `prompts/hotfix.md` | Production issues |
+| Refactoring | `prompts/refactoring.md` | Code improvement |
+| Issue Implementation | `prompts/issue-implementation-series.md` | Batch implementation |
+
+### Epic/Issue Management Workflows
+
+| Workflow | File | Purpose |
+|----------|------|---------|
+| Epic Plan (Overview) | `prompts/epic-plan.md` | Cross-module epic planning across all architectures |
+| Epic Plan (Module Slice) | `prompts/epic-plan.md` | Module-specific epic planning from architecture doc |
+| Epic Plan (Free-Form) | `prompts/epic-plan.md` | Quick single-feature planning |
+| Issue Draft | `prompts/issue-draft.md` | Create draft issues from approved epic |
+| Git Issues | `prompts/git-issues.md` | Create epics/milestones + issues + tracking in GitHub/GitLab |
+| Issue Closeout | `prompts/issue-closeout.md` | Verify AC → validators → canonical → compliance MR |
+| Issue Merge | `prompts/issue-merge.md` | Merge MR → close issue → update tracking → close epic |
+| Plan to Issues | `prompts/plan-to-issues.md` | Convert superpowers plan to GitHub/GitLab issues |
+
+### Blueprint Management Workflows
+
+| Workflow | File | Purpose |
+|----------|------|---------|
+| Blueprint Validate | `prompts/blueprint-validate.md` | Validate `.pi/` structure and integrity |
+| Sync Check | `prompts/sync-check.md` | Verify exports match blueprint source |
+| Context Refresh | `prompts/context-refresh.md` | Update context from codebase reality |
+| Scope Analyzer | `prompts/scope-analyzer.md` | Auto-determine change scope + validators |
+| Pattern Extract | `prompts/pattern-extract.md` | Extract patterns to `patterns.md` |
+| Blueprint Update | `prompts/blueprint-update.md` | Reverse-sync implementation changes |
+
+### Workflow Sequence
+
+```
+Blueprint Setup (one-time):
+/blueprint-validate → /sync-check → [ready for implementation]
+
+Multi-Module Planning (from scratch):
+/epic-plan --overview → discover all modules, map dependencies, plan cross-module epics
+  → /issue-draft (per epic in dependency order)
+    → /git-issues → [implement] → /issue-closeout → /issue-merge
+
+Single-Module Planning (targeted):
+/epic-plan --module frontend docs/frontend-architecture.md
+  → analyze gap, slice next epic, validate
+  → /issue-draft → /git-issues → [implement] → /issue-closeout → /issue-merge
+
+From Superpowers Plan:
+/plan-to-issues → /git-issues → [implement] → /issue-closeout → /issue-merge
+                      ↑                                          ↓
+                      └────────────── next issue ────────────────┘
+
+Maintenance:
+/context-refresh → /pattern-extract → /blueprint-update → /sync-check → guardian generate
+```
+
+---
+
+## Implementation Phase Requirements
+
+**All implementation phases must:**
+
+1. **Add canonical reference header** pointing to architecture module:
+```typescript
+/**
+ * Canonical Reference: .pi/architecture/modules/[module].md#[section]
+ * Implements: [spec from architecture doc]
+ * Issue: #[issue-number]
+ */
+```
+
+2. **Check architecture CHANGELOG** for recent changes affecting the module
+
+3. **Reference specific sections** not just files: `.pi/architecture/modules/auth-system.md#token-validation`
+
+---
+
+## Validation Phase Requirements
+
+**All validation phases must:**
+
+1. **Run canonical validator**: `bash .pi/scripts/validate-canonical.sh`
+
+2. **Check coverage**: Implementation files should have ≥50% canonical reference coverage
+
+3. **Verify architecture sync**: Check if CHANGELOG has pending changes affecting implementation
+
+4. **Validate accuracy**: References must point to existing architecture sections
+
+5. **Report gaps**: Files without references flagged, architecture changes needing sync
+
+---
+
+## Architecture Change Workflow
+
+When architecture changes:
+
+1. **Update module doc**: `.pi/architecture/modules/[module].md`
+2. **Add CHANGELOG entry**: `.pi/architecture/CHANGELOG.md`
+3. **Identify impacted files**: List files needing canonical ref updates
+4. **Notify via workflow**: Run `/blueprint-update` after implementation
+5. **Validate sync**: Run `validate-canonical.sh` to verify updates
+
+---
+
+## Key Principles
+
+1. **Template-driven** - Workflows in templates, not dynamic generation
+2. **DAG-based** - Task nodes with dependencies, topological execution
+3. **Minimal LLM** - LLM = planning tool only
+4. **Bounded autonomy** - Hard caps on dynamic behavior
+5. **Bounded retries** - Max 3 retries with exponential backoff + jitter (±25%)
+6. **Risk-gated** - Safe=auto, Medium=confirm, Dangerous=dry-run
+7. **Pre-validated** - Validator catches errors BEFORE execution
+8. **Auditable** - Planning decisions tracked and diffable
+9. **Architecture-traced** - All code linked to architecture documentation
+10. **Change-log-governed** - Architecture changes tracked, migrations documented
+
+---
+
+## Generation Mappings
+
+When running `guardian-framework generate`, `.pi/` files are transformed:
+
+| Source | Destination | Transformation |
+|--------|-------------|----------------|
+| `AGENTS.md` | `.claude/CLAUDE.md`, `.opencode/context.md` | Direct copy + canonical header |
+| `AGENTS.md` | `.github/copilot-instructions.md` | YAML frontmatter + canonical header |
+| `architecture/modules/*.md` | `.claude/architecture/*.md` | Direct copy + canonical header |
+| `architecture/CHANGELOG.md` | `.claude/architecture/CHANGELOG.md` | Direct copy |
+| `skills/agents/*.md` | `.claude/agents/*.md`, `.github/agents/*.agent.md` | Direct copy + YAML frontmatter |
+| `skills/validators/*.md` | `.opencode/prompts/*.txt` | Convert to .txt, compress |
+| `context/*.md` | `.claude/context/*.md`, `.opencode/context/*.md` | Direct copy + canonical header |
+| `context/*.md` | `.github/instructions/*.instructions.md` | YAML frontmatter + canonical header |
+| `prompts/*.md` | `.opencode/workflows/*.md` | Nest under workflows/ |
+| `scripts/*.sh` | `.pi/scripts/*.sh`, `.pi/scripts/*.sh` | Direct copy |
+| `extensions/*.ts` | `extensions/*.ts` (pi only) | No export |
+| `github/copilot/settings.json` | `.github/copilot/settings.json` | Direct copy |
+
+---
+
+## Language Patterns
+
+Language-specific code patterns are stored in `templates/languages/`:
+- `rust-patterns.md`
+- `typescript-patterns.md`
+- `python-patterns.md`
+- `go-patterns.md`
+
+Selected during `guardian init` based on project language.

package/templates/pi/agent/AGENTS.md

@@ -0,0 +1,166 @@
+---
+# Guardian Workflow Configuration
+# YAML front matter = runtime settings. Body = agent prompt.
+# Changes to this file are detected and re-applied without restart.
+
+workspace:
+  root: ".pi/workspaces"
+  hooks:
+    timeout_ms: 60000
+
+agent:
+  max_turns: 20
+  max_retry_backoff_ms: 300000
+  stall_timeout_ms: 300000
+
+system_prompt_tier: full
+
+generate:
+  on_conflict: warn
+  atomic_writes: true
+
+validate:
+  fail_fast: false
+  timeout_ms: 300000
+
+goal:
+  enabled: true
+  max_turns: 20
+  judge_validator: true
+
+kanban:
+  enabled: true
+  auto_create_tasks: true
+
+hooks:
+  pre_tool_call: []
+  post_tool_call: []
+  pre_llm_call: []
+  post_llm_call: []
+  on_session_start: []
+  on_session_end: []
+  subagent_stop: []
+
+curator:
+  enabled: true
+  stale_after_days: 30
+  archive_after_days: 90
+  auto_review: true
+
+delegation:
+  max_spawn_depth: 1
+  max_concurrent_children: 3
+  max_iterations: 50
+  child_timeout_ms: 600000
+---
+
+# Project Context
+
+> **Purpose:** Single source of truth for project-specific knowledge. All agents load this ONCE.
+> **Customize:** Fill in the sections below for your project. The YAML front matter above already has working defaults.
+
+## Project Overview
+
+- **Name:** [Project Name]
+- **Version:** 0.1.0
+- **Language:** [TypeScript / Python / Rust / Go]
+- **Type:** [CLI / Web App / Library]
+- **Repository:** [owner/repo]
+
+## Core Principles
+
+> These are loaded into EVERY agent's context. Keep to 5-8 items.
+
+1. **Read before edit** — Always read a file before modifying it. Never mutate blindly.
+2. **Validate early** — Run `bash .pi/scripts/ci/run_preflight.sh` before committing.
+3. **Architecture traceability** — Every implementation file must reference its architecture source in `.pi/architecture/modules/`.
+4. **DRY context** — Shared knowledge lives in `.pi/context/`, not scattered across agent files.
+5. **Shift-left validation** — Plans are validated before code is written.
+
+## Commands
+
+> Essential commands agents need to run. Update these for your project.
+
+| Command | Purpose |
+|---------|---------|
+| `[build command]` | Build project |
+| `[test command]` | Run tests |
+| `[lint command]` | Lint check |
+| `bash .pi/scripts/ci/run_preflight.sh` | Run local preflight checks |
+| `bash .pi/scripts/validate-*.sh` | Run specific validator |
+
+## Architecture
+
+### Structure
+
+```
+[project]/
+├── src/              # Source code
+├── tests/            # Test files
+├── docs/             # Documentation
+└── [other dirs]
+```
+
+### Key Files
+
+> Files every agent should know about. Keep under 10.
+
+| File | Purpose |
+|------|---------|
+| `.pi/architecture/modules/` | Canonical architecture modules |
+| `.pi/agent/AGENTS.md` | This file — project context + runtime config |
+| `.pi/scripts/` | Validation scripts |
+| `.pi/extensions/` | Pi extensions (tools, commands, hooks) |
+
+## Quality Gates
+
+### Before Commit
+
+```bash
+bash .pi/scripts/ci/run_preflight.sh
+[build command]
+```
+
+### Before Push
+
+```bash
+[test command]
+[lint command]
+```
+
+## Subagent Delegation
+
+| Task | Subagent | Tools |
+|------|----------|-------|
+| Explore codebase | `explore` | read-only (read, grep, glob) |
+| Code review | `code-review` | read-only (read, grep, glob) |
+| Security audit | `security-review` | read-only (read, grep, glob) |
+
+Subagents have **restricted tool access** and **fresh context**. Include all relevant context in the spawn prompt.
+
+## Snippets
+
+Available `#handle` tokens for quick instruction injection:
+
+| Handle | Purpose |
+|--------|---------|
+| `#security-review` | Security audit instructions |
+| `#no-comments` | Suppress comments unless WHY is non-obvious |
+| `#test-first` | TDD workflow instructions |
+
+## Environment
+
+> Variables agents may reference. Use `$VAR_NAME` in scripts.
+
+| Variable | Purpose |
+|----------|---------|
+| `$GITHUB_TOKEN` | GitHub API authentication |
+| `$CI` | CI environment indicator |
+
+## Security Guards
+
+Path safety guards are enforced by extensions (`.pi/extensions/bash-guard.ts`):
+
+- **Read blocklist:** `.env*`, `*.pem`, `*.key`, `.ssh/*`, `.aws/*`, `.git/*`
+- **Write blocklist:** Inherits read restrictions + `/etc/`, `/System/`, `/private/`
+- **Command deny-list:** `rm -rf /`, `mkfs`, `dd of=/dev/*`, `terraform destroy`, `kubectl delete`

package/templates/pi/agents/architecture-coordinator.md

@@ -0,0 +1,40 @@
+---
+title: Architecture Coordinator
+role: coordinator
+---
+
+# Architecture Coordinator
+
+## Purpose
+Turn a goal into a bounded execution stream with explicit issue order, controls, and forbidden shortcuts. Owns Phase A (Planning) of the delivery pipeline. Decides what work will be done and in what order.
+
+## Authority
+**May:** Define scope boundaries, classify stream type (feature/hardening/migration/control), build dependency graphs, assign validators, select CI gates, decide the first implementation issue.
+**May not:** Implement code, invent architecture that contradicts ADRs, skip mandatory validators, produce issues (that's Issue Factory's job).
+
+## Inputs
+- Business goal or feature request
+- `.pi/architecture/modules/` — module architecture docs (read impacted modules only)
+- `.pi/architecture/decisions/` — ADRs (read all relevant accepted/proposed)
+- `.pi/architecture/CHANGELOG.md` — recent architecture changes
+- `.pi/context/project.md` — project knowledge and constraints
+- `.pi/domain/exploration.md` — domain exploration output (when available)
+
+## Outputs
+A planning packet containing:
+- Stream classification (feature/hardening/migration/control)
+- Scope summary with explicit in-scope and out-of-scope boundaries
+- Impacted layers/modules checklist
+- Risk classification (low/medium/high) with justification
+- Dependency graph with execution order
+- Mandatory validators list (at minimum: architecture-validator)
+- Mandatory CI gates list
+- Forbidden shortcuts
+- First implementation issue recommendation
+- Open questions and escalation items
+
+## Definition of Done
+Done when a downstream agent (Issue Factory) can create epics and issues without ambiguity. The planning packet must pass `check_planning_packet.py` deterministic validation before handoff.
+
+## Escalation Rule
+If canonical docs conflict, scope is unclear, or impacted layers can't be identified with confidence, stop and raise the gap. Do not smooth over ambiguity to produce a packet faster.

package/templates/pi/agents/architecture-validator.md

@@ -0,0 +1,36 @@
+---
+title: Architecture Validator
+role: validator
+---
+
+# Architecture Validator
+
+## Purpose
+Verify issue/epic output against architecture policy before merge. Owns the architecture review in Phase D (Validation). Ensures implementation matches what was planned and no architecture drift occurred.
+
+## Authority
+**May:** Pass, pass-with-recommendations, or fail an implementation based on architecture conformance. Require changes before merge approval.
+**May not:** Redefine scope, add new requirements, implement code, override security or operations findings.
+
+## Inputs
+- Planning packet from Phase A (for reference on approved scope)
+- Implementation diff from Phase C
+- Implementation report from Bootstrap Implementer
+- Canonical references cited in the issue
+- `.pi/architecture/modules/` — relevant module docs
+- `.pi/architecture/decisions/` — relevant ADRs
+
+## Outputs
+A validation report containing:
+- Decision (pass / pass_with_recommendations / fail)
+- Blocking findings (must fix before proceeding)
+- Non-blocking recommendations
+- Section reference verification (citations support claims)
+- Acceptance criteria verification (each AC evaluated with evidence)
+- Final disposition (approved as-is / approved with minor recommendations / blocked)
+
+## Definition of Done
+Done when the validation report is complete, all blocking findings are either resolved or escalated, and the issue is ready for the next phase (security/operations validation or merge).
+
+## Escalation Rule
+If the implementation contradicts approved ADRs or module architecture without documented rationale, block and escalate to Architecture Coordinator. Do not approve architecture drift silently.