guardian-framework 0.1.0

package/templates/pi/agents/bootstrap-implementer.md

@@ -0,0 +1,37 @@
+---
+title: Bootstrap Implementer
+role: builder
+---
+
+# Bootstrap Implementer
+
+## Purpose
+Execute ONE issue at a time with strict acceptance-criteria closure and minimal drift. Owns Phase C (Implementation). Produces working code, passing tests, and evidence for each acceptance criterion.
+
+## Authority
+**May:** Create feature branches, implement code and tests, update documentation and runbooks within issue scope, run local validation and quality gates.
+**May not:** Change scope, implement work outside the assigned issue's acceptance criteria, modify contracts without explicit issue scope, skip validation path, merge without architecture validation.
+
+## Inputs
+- Single assigned issue from Phase B (with acceptance criteria, verification requirements, canonical references)
+- Planning packet (for scope context)
+- Dependency status (earlier issues complete?)
+- `.pi/architecture/modules/` — relevant module docs
+- `.pi/architecture/decisions/` — relevant ADRs
+
+## Outputs
+- Implementation report containing:
+  - Readiness check (dependencies satisfied, issue implementation-ready)
+  - Acceptance criteria trace map (each criterion → files changed → evidence → validation command)
+  - Files changed
+  - Tests and CI impacts
+  - Toolchain validation results
+  - Documentation/runbook impacts
+  - Done/not-done per acceptance criterion with evidence
+- Code, tests, config, docs changes on a feature branch
+
+## Definition of Done
+Done when all acceptance criteria are met, evidence is collected for each, the correct validation path has passed, tests are written and passing, and the implementation report is ready for architecture validator review.
+
+## Escalation Rule
+If dependencies are not satisfied (earlier issues incomplete), stop and escalate. Do not implement against blocked dependencies. If the implementation reveals unplanned scope or architecture concerns, flag them but do not deviate from the assigned issue.

package/templates/pi/agents/issue-factory.md

@@ -0,0 +1,31 @@
+---
+title: Issue Factory
+role: coordinator
+---
+
+# Issue Factory
+
+## Purpose
+Convert an approved planning packet into a set of independently-reviewable Git issues with proper dependency ordering, acceptance criteria, verification requirements, and canonical references. Owns Phase B (Issue Generation).
+
+## Authority
+**May:** Decompose scope into individual issues, set dependency order, assign labels (layer, type, risk), write acceptance criteria and verification requirements, select the appropriate issue template for each work unit.
+**May not:** Redefine scope, change dependency order without coordinator approval, skip mandatory validators or CI gates, produce issues without an approved planning packet.
+
+## Inputs
+- Approved planning packet from Architecture Coordinator (Phase A output)
+- Issue template set (contract, schema, service, handler, verification, rollout)
+- `.pi/architecture/modules/` — for canonical references
+- `.pi/architecture/decisions/` — for ADR references
+
+## Outputs
+- Epic draft with title, description, milestone, labels
+- Issue set with dependency order
+- Each issue: one primary outcome, one primary owner, clear acceptance criteria, verification criteria, canonical references
+- Labels (layer::*, type::*, risk::*)
+
+## Definition of Done
+Done when every issue is independently reviewable, references canonical source sections, and is ordered to match the dependency graph. No issue should require clarification from the coordinator before implementation starts.
+
+## Escalation Rule
+If planning inputs contradict each other (e.g., scope and dependency graph disagree), return the packet to Architecture Coordinator for re-scoping. Do not invent a reconciliation step.

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

@@ -0,0 +1,32 @@
+---
+title: Operations Validator
+role: validator
+---
+
+# Operations Validator
+
+## Purpose
+Verify that implementations are production-ready with proper observability, runbooks, rollback paths, and SLOs. Reviews planning packets (Phase A) and implementation reports (Phase D) for operational impact.
+
+## Authority
+**May:** Pass, pass-with-recommendations, or fail an epic/issue based on operational readiness. Define required monitoring, alerting, runbook, and release-readiness criteria.
+**May not:** Redefine deployment architecture, implement operational changes directly, override architecture or security findings without escalation.
+
+## Inputs
+- Planning packet (for production-impacting epics only)
+- Implementation diff
+- Implementation report
+- `.pi/architecture/modules/<operations>.md` — operations module docs
+- `.pi/architecture/decisions/` — relevant ADRs
+
+## Outputs
+- Validation decision (pass / pass_with_recommendations / fail / n/a)
+- Blocking operational gaps
+- Non-blocking operational recommendations
+- Release-readiness judgment
+
+## Definition of Done
+Done when observability obligations are explicit, runbooks are updated for the changed behavior, rollback path is documented, and release readiness is assessed.
+
+## Escalation Rule
+If the implementation changes production behavior without observability or rollback plan, block and escalate. Do not approve production-blind changes.

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

@@ -0,0 +1,33 @@
+---
+title: Security Validator
+role: validator
+---
+
+# Security Validator
+
+## Purpose
+Verify that implementations maintain security controls and do not introduce regressions. Reviews planning packets (Phase A) and implementation reports (Phase D) for security impact.
+
+## Authority
+**May:** Pass, pass-with-recommendations, or fail an epic/issue based on security conformance. Distinguish between required-now and acceptable-later security work. Require changes before merge approval.
+**May not:** Redefine architecture security policy, implement security fixes directly, override architecture or operations findings without escalation.
+
+## Inputs
+- Planning packet (for security-impacting epics only)
+- Implementation diff
+- Implementation report
+- `.pi/architecture/modules/<security>.md` — security module docs
+- `.pi/architecture/decisions/` — relevant ADRs
+- `.pi/validators/` — security rule configurations
+
+## Outputs
+- Validation decision (pass / pass_with_recommendations / fail / n/a)
+- Blocking security findings
+- Non-blocking security recommendations
+- Required issue changes now vs. deferred security work
+
+## Definition of Done
+Done when all trust boundaries have been reviewed, no security control regressions remain in the issue scope, and security obligations are explicitly documented as required-now or acceptable-later.
+
+## Escalation Rule
+If the implementation introduces a trust boundary violation, secrets leak, or auth bypass, block immediately and escalate. Do not defer high-severity findings.

package/templates/pi/architecture/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Architecture Change Log
+
+<!--
+Canonical Reference: .pi/architecture/CHANGELOG.md
+Blueprint Source: Guardian Framework v1.2
+DO NOT EDIT GENERATED FILES - Modify this source only
+-->
+
+This document tracks all architecture changes requiring implementation updates.
+
+---
+
+## Change Log Format
+
+Each entry follows this structure:
+
+```markdown
+## [YYYY-MM-DD] - [Change Title]
+
+### Changed
+- Module: [module-name]
+  - [Component]: [what changed]
+  - [Component]: [what changed]
+
+### Impact Analysis
+- Files affected:
+  - src/[path1]
+  - src/[path2]
+- Canonical refs to update:
+  - .pi/architecture/modules/[module].md#[section]
+- Validators required:
+  - [validator-name]
+
+### Migration Steps
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+### Status
+- [ ] Architecture doc updated
+- [ ] CHANGELOG entry added
+- [ ] Implementation updated
+- [ ] Canonical refs updated
+- [ ] Validators run
+```
+
+---
+
+## Entries
+
+<!-- Add new entries above this line -->
+
+---
+
+## Template Usage
+
+When making architecture changes:
+
+1. **Before change**: Review existing architecture docs
+2. **During change**: Update `.pi/architecture/modules/[module].md`
+3. **After change**: Add entry to this CHANGELOG
+4. **Implementation**: Follow migration steps, update canonical refs
+5. **Validation**: Run `validate-canonical.sh` to verify sync
+
+---
+
+## Architecture Sync Status
+
+Track which changes have been synced to implementation:
+
+| Date | Change | Module | Sync Status | Validator Status |
+|------|--------|--------|-------------|------------------|
+| [date] | [title] | [module] | [pending/complete] | [pass/fail] |
+
+---
+
+*Last updated: [date]*
+*Framework version: 1.2.0*

package/templates/pi/architecture/decisions/ADR-template.md

@@ -0,0 +1,76 @@
+# Architecture Decision Record: [ADR-XXX]
+
+<!--
+Canonical Reference: .pi/architecture/decisions/ADR-XXX-[title].md
+Blueprint Source: Guardian Framework v1.2
+-->
+
+## Title
+
+[Short title describing the decision]
+
+## Status
+
+- [ ] Proposed
+- [ ] Accepted
+- [ ] Deprecated
+- [ ] Superseded by ADR-XXX
+
+## Context
+
+[Describe the situation and problem that motivated this decision]
+
+## Decision
+
+[Describe the decision that was made]
+
+## Alternatives Considered
+
+| Alternative | Pros | Cons | Reason Rejected |
+|-------------|------|------|-----------------|
+| [Option 1] | [Pros] | [Cons] | [Why not chosen] |
+| [Option 2] | [Pros] | [Cons] | [Why not chosen] |
+| [Option 3] | [Pros] | [Cons] | [Why not chosen] |
+
+## Consequences
+
+### Positive
+- [Benefit 1]
+- [Benefit 2]
+
+### Negative
+- [Drawback 1]
+- [Drawback 2]
+
+### Neutral
+- [Effect 1]
+
+## Implementation
+
+**Affected Modules:**
+- `.pi/architecture/modules/[module1].md`
+- `.pi/architecture/modules/[module2].md`
+
+**Files to Update:**
+- `src/[path1]`
+- `src/[path2]`
+
+**Canonical References:**
+Implementation files should reference: `.pi/architecture/decisions/ADR-XXX-[title].md`
+
+## Validation
+
+**Validators Required:**
+- architecture-validator: [Check layer compliance]
+- security-validator: [If security implications]
+- [Other validators]
+
+## References
+
+- Related ADRs: [ADR-XXX, ADR-YYY]
+- External references: [Links to docs/articles]
+
+---
+
+*Decision date: [date]*
+*Decision makers: [Names/roles]*

package/templates/pi/architecture/diagrams/system-overview.md

@@ -0,0 +1,159 @@
+# System Architecture Overview
+
+<!--
+Canonical Reference: .pi/architecture/diagrams/system-overview.md
+Blueprint Source: Guardian Framework v1.2
+-->
+
+## High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         External Clients                         │
+│                    (Web, Mobile, API Consumers)                  │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                        API Gateway Layer                         │
+│              .pi/architecture/modules/api-gateway.md             │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                       Business Logic Layer                       │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
+│  │   Auth       │  │   Core       │  │   Workflow   │          │
+│  │   Module     │  │   Module     │  │   Module     │          │
+│  └──────────────┘  └──────────────┘  └──────────────┘          │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                        Data Layer                                │
+│              .pi/architecture/modules/data-layer.md              │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
+│  │   Database   │  │   Cache      │  │   Storage    │          │
+│  └──────────────┘  └──────────────┘  └──────────────┘          │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Module Layers
+
+| Layer | Modules | Purpose | Entry Point |
+|-------|---------|---------|-------------|
+| Presentation | api-gateway | Request handling, routing | src/api/ |
+| Business | auth-system, core, workflow | Domain logic | src/modules/ |
+| Data | data-layer, cache, storage | Persistence | src/data/ |
+| Infrastructure | config, logging, monitoring | Cross-cutting | src/lib/ |
+
+---
+
+## Module Dependency Graph
+
+```
+api-gateway
+    │
+    ├──→ auth-system
+    │        │
+    │        └──→ data-layer
+    │
+    ├──→ core-module
+    │        │
+    │        ├──→ data-layer
+    │        │
+    │        └──→ cache-layer
+    │
+    └──→ workflow-module
+             │
+             └──→ core-module
+```
+
+---
+
+## Data Flow Overview
+
+### Request Flow
+
+```
+Request → API Gateway → Auth Validation → Business Logic → Data Layer → Response
+                              │
+                              ▼
+                         Cache Check
+                              │
+                              ▼
+                        (if needed)
+```
+
+### Event Flow
+
+```
+Business Logic → Event Bus → Event Handlers → Side Effects
+      │
+      └──→ Logging/Metrics
+```
+
+---
+
+## Deployment Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Load Balancer                            │
+└─────────────────────────────────────────────────────────────────┘
+         │                    │                    │
+         ▼                    ▼                    ▼
+┌─────────────┐        ┌─────────────┐        ┌─────────────┐
+│   App       │        │   App       │        │   App       │
+│   Instance  │        │   Instance  │        │   Instance  │
+│   #1        │        │   #2        │        │   #3        │
+└─────────────┘        └─────────────┘        └─────────────┘
+         │                    │                    │
+         └────────────────────┼────────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │   Shared Data   │
+                    │   Layer         │
+                    └─────────────────┘
+```
+
+---
+
+## Security Boundaries
+
+| Boundary | Enforcement | Module |
+|----------|-------------|--------|
+| External → API Gateway | Rate limiting, CORS | api-gateway |
+| API Gateway → Business | Auth validation | auth-system |
+| Business → Data | Query auth, encryption | data-layer |
+
+---
+
+## Key Integration Points
+
+| Integration | Protocol | Module | Documentation |
+|-------------|----------|--------|---------------|
+| [API Name] | REST/GraphQL | api-gateway | .pi/architecture/modules/api-gateway.md#integrations |
+| [Database] | SQL/NoSQL | data-layer | .pi/architecture/modules/data-layer.md#connections |
+| [Cache] | Redis/Memory | cache-layer | .pi/architecture/modules/cache-layer.md |
+
+---
+
+## Canonical Reference Template
+
+Implementation files should reference this overview when describing system-level behavior:
+
+```typescript
+/**
+ * Canonical Reference: .pi/architecture/diagrams/system-overview.md#[section]
+ * Implements: [component at layer X]
+ */
+```
+
+---
+
+*Last updated: [date]*
+*Architecture version: [version]*

package/templates/pi/architecture/modules/module-template.md

@@ -0,0 +1,152 @@
+# [Module Name] Architecture
+
+<!--
+Canonical Reference: .pi/architecture/modules/[module-name].md
+Blueprint Source: Guardian Framework v1.2
+Generated: NEVER (this is the source)
+-->
+
+## Overview
+
+[Brief description of the module's purpose and scope within the system]
+
+## Responsibilities
+
+- [Responsibility 1]
+- [Responsibility 2]
+- [Responsibility 3]
+
+## Components
+
+| Component | File Path | Purpose | Canonical Section |
+|-----------|-----------|---------|-------------------|
+| [Name] | src/[path] | [Description] | #[section] |
+| [Name] | src/[path] | [Description] | #[section] |
+
+---
+
+## Component Details
+
+### [Component Name]
+
+**Purpose:** [What this component does]
+
+**Implementation File:** `src/[path]`
+
+**Canonical Reference:** `.pi/architecture/modules/[module-name].md#[component-section]`
+
+**Dependencies:**
+- [Dependency 1]
+- [Dependency 2]
+
+**Interface:**
+
+```typescript
+// Public interface
+interface [InterfaceName] {
+  [method signatures]
+}
+```
+
+---
+
+## Data Flow
+
+```
+[Input Source]
+     │
+     ▼
+[Processing Component]
+     │
+     ▼
+[Output Destination]
+```
+
+**Flow Description:**
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+---
+
+## Dependencies
+
+### Depends On
+- **[Module Name]**: [Why/what it provides]
+- **[Module Name]**: [Why/what it provides]
+
+### Used By
+- **[Module Name]**: [Why/what it uses]
+- **[Module Name]**: [Why/what it uses]
+
+---
+
+## Security Considerations
+
+| Concern | Mitigation | Validator |
+|---------|------------|-----------|
+| [Concern 1] | [Mitigation] | security-validator |
+| [Concern 2] | [Mitigation] | security-validator |
+
+**Authentication/Authorization:**
+- [Auth requirements]
+
+**Data Protection:**
+- [Encryption/sanitization requirements]
+
+---
+
+## Testing Requirements
+
+| Test Type | Coverage Target | Files |
+|-----------|-----------------|-------|
+| Unit | [X]% | tests/unit/[module].test.ts |
+| Integration | [Y]% | tests/integration/[module].test.ts |
+| E2E | [Z]% | tests/e2e/[module].test.ts |
+
+**Key Test Scenarios:**
+- [Scenario 1]
+- [Scenario 2]
+- [Scenario 3]
+
+---
+
+## Error Handling
+
+```typescript
+// Error types defined in this module
+class [ErrorType] extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = '[ErrorType]';
+  }
+}
+```
+
+**Error Recovery:**
+- [Error 1]: [Recovery strategy]
+- [Error 2]: [Recovery strategy]
+
+---
+
+## Performance Considerations
+
+| Metric | Target | Monitoring |
+|--------|--------|------------|
+| Latency | [X]ms | [How monitored] |
+| Throughput | [Y] req/s | [How monitored] |
+
+---
+
+## Change Log References
+
+| Date | Change | Section | Status |
+|------|--------|---------|--------|
+| [date] | [description] | #[section] | [synced/pending] |
+
+See full details in `.pi/architecture/CHANGELOG.md`
+
+---
+
+*Last updated: [date]*
+*Module version: [version]*

package/templates/pi/context/checklists.md

@@ -0,0 +1,91 @@
+# Validation Checklists
+
+> **Purpose:** Machine-parseable checklists for all validators. Used for caching — passed items are skipped on retry.
+> **Generic:** Replace check items with your project's validation rules.
+
+---
+
+## Architecture Validation
+
+### Pre-Implementation (Plan Review)
+- [ ] Design follows existing module organization
+- [ ] Error handling approach defined
+- [ ] No duplicate types (grep verified)
+- [ ] Dependencies identified and available
+- [ ] Module structure planned
+
+### Post-Implementation (Code Review)
+- [ ] Wiring: callers exist (not dead code)
+- [ ] No duplicate type definitions
+- [ ] Module declared AND imported
+- [ ] Tools/components registered in registry
+- [ ] Errors integrated into parent error type
+- [ ] E2E tests pass
+- [ ] Architecture contract tests pass
+
+## Security Validation
+
+### All Code Changes
+- [ ] No hardcoded secrets
+- [ ] No command injection (no `Command::new` + `format!`)
+- [ ] Path traversal prevention (canonicalize + starts_with)
+- [ ] Input validation on all external inputs
+- [ ] Secrets not logged
+- [ ] Risk levels properly assigned (Safe/Medium/Dangerous)
+
+## Operations Validation
+
+### Performance
+- [ ] No O(N²) where O(N) expected
+- [ ] Proper data structures used
+- [ ] Memory within bounds
+
+### Observability
+- [ ] `#[instrument]` on public functions
+- [ ] Proper span fields
+- [ ] Events for state changes
+- [ ] No secrets in logs
+
+### Reliability
+- [ ] CancellationToken passed to all async ops
+- [ ] Proper cleanup on cancellation
+- [ ] Atomic writes (write-rename pattern)
+- [ ] Resource cleanup (Drop implementations)
+
+## Test Validation
+
+### Coverage
+- [ ] All tests pass
+- [ ] Coverage ≥ 80%
+- [ ] All new code has tests
+- [ ] Tests follow AAA pattern (Arrange-Act-Assert)
+
+### Quality
+- [ ] No flaky tests
+- [ ] Integration tests pass
+- [ ] E2E tests pass
+- [ ] Architecture contract tests pass
+
+## Integration Validation
+
+### Component Interaction
+- [ ] Component interfaces match design
+- [ ] No circular dependencies
+- [ ] End-to-end flows work
+- [ ] Error propagation across boundaries
+
+## CI/MR Validation
+
+### Build & Test
+- [ ] Build succeeds
+- [ ] All tests pass
+- [ ] Lint passes
+- [ ] Format check passes
+- [ ] Security audit passes
+
+### Merge Readiness
+- [ ] Required approvals present
+- [ ] CI checks all green
+- [ ] No merge conflicts
+- [ ] PR description complete
+- [ ] Issues linked