guardian-framework 0.1.0

package/templates/pi/github/instructions/architecture.instructions.md

@@ -0,0 +1,71 @@
+---
+description: 'Module architecture documentation and canonical references'
+applyTo: 'src/**/*.ts,src/**/*.js,src/**/*.tsx,src/**/*.jsx'
+---
+<!--
+Canonical Reference: .pi/github/instructions/architecture.instructions.md
+Blueprint Source: Guardian Framework v1.2
+DO NOT EDIT DIRECTLY - Source: .pi/architecture/modules/
+-->
+
+# Architecture Implementation Guidelines
+
+## Required Header Format
+
+Every source file must include a canonical reference header:
+
+```typescript
+/**
+ * Canonical Reference: .pi/architecture/modules/[module-name].md#[section]
+ * Implements: [what this file implements from architecture]
+ * Module: [module this belongs to]
+ * Last Sync: [date from CHANGELOG.md]
+ */
+
+// Rest of file...
+```
+
+## Architecture Module Reference
+
+Before implementing, read the architecture module documentation:
+
+```bash
+# View architecture for a module
+cat .pi/architecture/modules/[module-name].md
+
+# Check for pending changes
+grep "Status.*pending" .pi/architecture/CHANGELOG.md
+```
+
+## Module Structure
+
+Each architecture module defines:
+- **Components**: What files implement this module
+- **Data Flow**: How data moves through the module
+- **Dependencies**: What other modules it uses
+- **Security**: Security considerations
+- **Testing**: Test requirements
+
+## Implementation Checklist
+
+When implementing from architecture:
+1. [ ] Read architecture module doc
+2. [ ] Check CHANGELOG for pending changes
+3. [ ] Add canonical reference header
+4. [ ] Follow patterns from module doc
+5. [ ] Implement security requirements
+6. [ ] Add tests per requirements
+7. [ ] Run validate-canonical.sh
+
+## Validation
+
+```bash
+# Check canonical reference coverage
+bash .pi/scripts/validate-canonical.sh
+
+# Expected: ≥50% coverage, all refs valid
+```
+
+---
+
+*Reference: .pi/architecture/modules/*.md*

package/templates/pi/github/instructions/validation.instructions.md

@@ -0,0 +1,69 @@
+---
+description: 'Validation and quality gate requirements'
+applyTo: '.pi/scripts/*.sh,tests/**/*,scripts/**/*'
+---
+<!--
+Canonical Reference: .pi/github/instructions/validation.instructions.md
+Blueprint Source: Guardian Framework v1.2
+DO NOT EDIT DIRECTLY - Source: .pi/scripts/
+-->
+
+# Validation Guidelines
+
+## Scope-Based Validators
+
+| Scope | Required Validators |
+|-------|---------------------|
+| Simple | CI + Canonical |
+| Moderate | CI + Architecture + Canonical |
+| Complex | CI + Architecture + Security + Canonical |
+| Critical | All validators + human approval |
+
+## Validator Scripts
+
+### CI Validator (always required)
+```bash
+bash .pi/scripts/validate-ci.sh
+```
+Checks: Build, tests, lint, format, audit
+
+### Architecture Validator (moderate+)
+```bash
+bash .pi/scripts/validate-architecture.sh
+```
+Checks: Layer structure, module boundaries, circular deps
+
+### Security Validator (complex+)
+```bash
+bash .pi/scripts/validate-security.sh
+```
+Checks: Secrets, injection, path traversal
+
+### Canonical Validator (always required)
+```bash
+bash .pi/scripts/validate-canonical.sh
+```
+Checks: Reference integrity, coverage ≥50%, architecture sync
+
+## Validation Workflow
+
+```bash
+# Always run these
+bash .pi/scripts/validate-ci.sh
+bash .pi/scripts/validate-canonical.sh
+
+# Scope determines additional validators
+# Check scope: grep "scope:" .pi/INDEX.md
+```
+
+## Pre-Commit Checklist
+
+- [ ] CI validator passes
+- [ ] Canonical validator passes
+- [ ] Coverage ≥50%
+- [ ] Architecture CHANGELOG checked
+- [ ] Scope-appropriate validators run
+
+---
+
+*Reference: .pi/scripts/validate-*.sh*

package/templates/pi/github/workflows/01-planning-workflow.md

@@ -0,0 +1,75 @@
+# Phase A: Planning Workflow
+
+## Purpose
+Turn a goal into a bounded execution packet with validators and CI gates identified. This is the first workflow for every new epic.
+
+## Primary Agent
+- **Architecture Coordinator** (owner)
+- **Architecture Validator** (mandatory review)
+- **Security Validator** (conditional review)
+- **Operations Validator** (conditional review)
+
+## Workflow Steps
+
+### Step 1: Stream Classification
+Classify the goal into one of: **feature**, **hardening**, **migration**, or **control**.
+
+### Step 2: Scope Boundaries
+Define explicit in-scope and out-of-scope boundaries. List impacted layers/modules.
+
+### Step 3: Dependency Graph
+Map execution order. Identify blocked work, parallel-safe work, and the first issue.
+
+### Step 4: Risk Classification
+Assign low/medium/high with justification.
+
+### Step 5: Validator Assignment
+- Architecture Validator: always
+- Security Validator: if security-impacting
+- Operations Validator: if operations-impacting
+
+### Step 6: CI Gate Selection
+Select applicable gates: docs_policy, architecture_conformance, lint, static_analysis, unit, integration, security, migration_verify, release_readiness.
+
+## Output: Planning Packet
+
+```markdown
+## Stream classification
+## Scope summary
+## In scope
+## Out of scope
+## Impacted layers
+## Risk classification
+## Dependency graph
+## Mandatory validators
+## Mandatory CI gates
+## Forbidden shortcuts
+## First implementation issue recommendation
+## Open questions / escalation items
+```
+
+## Deterministic Validation
+```bash
+python scripts/ci/check_planning_packet.py --input=planning_packet.md
+```
+
+## Done Criteria
+- [ ] Scope bounded and explicit
+- [ ] All impacted layers identified
+- [ ] Risk classification explicit
+- [ ] Dependency graph clear
+- [ ] Validators assigned
+- [ ] CI gates identified
+- [ ] First issue clear
+- [ ] Deterministic validation passes
+- [ ] Architecture validation passes
+
+## Next Phase
+**→ Phase B: Issue Generation** (Issue Factory)
+
+## Related Documents
+- `.pi/agents/architecture-coordinator.md`
+- `.pi/agents/architecture-validator.md`
+- `.pi/agents/security-validator.md`
+- `.pi/agents/operations-validator.md`
+- `.pi/context/domain-workflow.md`

package/templates/pi/github/workflows/02-issue-generation-workflow.md

@@ -0,0 +1,69 @@
+# Phase B: Issue Generation Workflow
+
+## Purpose
+Convert an approved planning packet into an epic + issue set that are independently reviewable.
+
+## Primary Agent
+- **Issue Factory** (owner)
+
+## Input
+- Approved planning packet from Phase A
+- Valid planning packet check: pass
+- Architecture validation: pass
+
+## Workflow Steps
+
+### Step 1: Validate Planning Packet
+Check scope is bounded, dependencies are clear, validators assigned, CI gates identified. If contradictions exist, return to Architecture Coordinator.
+
+### Step 2: Create Issues
+For each work unit, produce one issue with:
+- Single outcome and owner
+- Clear acceptance criteria
+- Verification criteria
+- Canonical references
+
+**Issue breakdown pattern (feature stream):**
+1. Contract issue — domain/API contracts first
+2. Schema/Config issue — migrations, indexes, config
+3. Service issue — repositories, adapters
+4. Handler/Runtime issue — business logic, workers
+5. Verification issue — tests, conformance
+6. Rollout/Runbook issue — ops, monitoring
+
+### Step 3: Dependency Ordering
+Order by: contract → schema → service → handler → verification → rollout.
+
+### Step 4: Issue Boundary Check
+Each issue must have: one primary outcome, one owner, clear ACs, out-of-scope explicit, canonical references, independently reviewable.
+
+## Output: Issue Set
+
+```markdown
+## Issues (in dependency order)
+- Issue 1: <title>
+- Issue 2: <title>
+...
+
+## Labels
+- risk::<level>
+- layer::<layers>
+- type::<feature|hardening|migration>
+
+## First implementation issue
+- Issue 1: <title>
+```
+
+## Done Criteria
+- [ ] All issues independently reviewable
+- [ ] Acceptance criteria clear
+- [ ] Verification criteria clear
+- [ ] Dependency order correct
+- [ ] First implementation issue identified
+
+## Next Phase
+**→ Phase C: Implementation** (Bootstrap Implementer)
+
+## Related Documents
+- `.pi/agents/issue-factory.md`
+- `.pi/prompts/issue-template-set.md`

package/templates/pi/github/workflows/03-implementation-workflow.md

@@ -0,0 +1,80 @@
+# Phase C: Implementation Workflow
+
+## Purpose
+Execute ONE issue at a time with strict acceptance-criteria closure and minimal drift.
+
+## Primary Agent
+- **Bootstrap Implementer** (owner)
+- **Architecture Validator** (post-implementation validation)
+
+## Input
+- Single assigned issue from Phase B
+- Planning packet (scope context)
+- Dependency status
+
+## Workflow Steps
+
+### Step 1: Readiness Check
+Verify: epic exists, issue exists, dependencies satisfied, issue is implementation-ready.
+
+### Step 2: Acceptance Criteria Trace Map
+Before coding, create a trace map: each criterion → files to change → evidence → validation command.
+
+### Step 3: Validation Path Selection
+Classify the issue:
+- **Config-only** — changes limited to config, CI wiring, or docs
+- **Application** — any change to source code, contracts, or runtime behavior
+- **Mixed** — both
+
+Run the applicable validation path:
+```bash
+# Config-only path
+bash scripts/ci/check_config.sh
+
+# Application path
+./scripts/ci/run_preflight.sh --staged --json
+```
+
+### Step 4: Implementation
+For each acceptance criterion:
+1. Create feature branch
+2. Read canonical references
+3. Implement minimum to satisfy AC
+4. Write tests
+5. Run validation command
+
+### Step 5: Toolchain Validation
+Run the blocking validation path selected in Step 3.
+
+### Step 6: Evidence Collection
+For each AC, collect: file paths changed, tests written/passed, commands run, output.
+
+### Step 7: Implementation Report
+Produce report with: readiness check, AC trace map, files changed, validation results, done/not-done per AC.
+
+## Output: Implementation Report
+- Readiness check
+- Acceptance criteria trace map
+- Files changed
+- Tests and CI impacts
+- Toolchain validation results
+- Done / not done against acceptance criteria
+- Evidence produced
+
+## Done Criteria
+- [ ] All acceptance criteria met
+- [ ] Evidence collected for each AC
+- [ ] Correct validation path selected
+- [ ] Toolchain validation passes
+- [ ] Tests written and passing
+- [ ] Documentation updated
+- [ ] Implementation report ready for validator
+
+## Next Phase
+**→ Phase D: Validation** (Architecture Validator)
+**→ Next Issue** (if more issues in epic)
+
+## Related Documents
+- `.pi/agents/bootstrap-implementer.md`
+- `.pi/agents/architecture-validator.md`
+- `.pi/prompts/issue-template-set.md`

package/templates/pi/github/workflows/04-validation-workflow.md

@@ -0,0 +1,68 @@
+# Phase D: Validation Workflow
+
+## Purpose
+Verify issue/epic output against architecture and release policy before merge. Runs after each implemented issue and before epic close.
+
+## Primary Agents
+- **Architecture Validator** (owner)
+- **Security Validator** (if security-impacting)
+- **Operations Validator** (if operations-impacting)
+
+## Workflow Steps
+
+### Step 1: Validation Path Selection
+Classify the issue (config-only / application / mixed) and run the applicable validation:
+```bash
+python scripts/ci/validate_agent_output.py --input=implementation_report.md --schema=architecture-validator
+```
+
+### Step 2: Read Implementation
+Review: implementation diff, implementation report, acceptance criteria, canonical references, validation path evidence.
+
+### Step 3: Architecture Validation
+Check: artifact classification, section references, scope-fit, evidence precision, acceptance criteria evaluation, contradiction detection.
+
+### Step 4: Security Validation (if applicable)
+Check: tenant isolation preserved, auth boundaries maintained, secrets handled correctly, no security regressions.
+
+### Step 5: Operations Validation (if applicable)
+Check: observability added, runbooks updated, rollback path clear, SLOs defined.
+
+### Step 6: CI Verification
+Run applicable pipeline stages.
+
+## Output: Validation Summary
+
+```markdown
+## Overall Validation Status
+- pass | pass_with_recommendations | fail
+
+## Validator Decisions
+- Architecture: <decision>
+- Security: <decision or N/A>
+- Operations: <decision or N/A>
+
+## Blocking Findings
+## Non-Blocking Recommendations
+## Required Follow-up
+## Merge Authorization
+- [ ] Architecture validator: APPROVED
+- [ ] Security validator: APPROVED (if applicable)
+- [ ] Operations validator: APPROVED (if applicable)
+- [ ] CI pipeline: PASSED
+- [ ] Ready to merge
+```
+
+## Done Criteria
+- [ ] All validators pass
+- [ ] Correct validation path selected
+- [ ] All CI gates pass
+- [ ] No blocking findings
+- [ ] Follow-up issues created (if needed)
+- [ ] Ready to merge
+
+## Related Documents
+- `.pi/agents/architecture-validator.md`
+- `.pi/agents/security-validator.md`
+- `.pi/agents/operations-validator.md`
+- `scripts/ci/validate_agent_output.py`

package/templates/pi/preflight_report.json

@@ -0,0 +1,99 @@
+{
+  "timestamp": "2026-06-29T22:16:25Z",
+  "mode": "all",
+  "stages_run": [],
+  "summary": {
+    "total": 14,
+    "passed": 1,
+    "failed": 1,
+    "skipped": 12
+  },
+  "duration_seconds": 0,
+  "results": [
+  {
+    "name": "check_mr_traceability.sh",
+    "status": "skip",
+    "message": "script not found",
+    "duration": 0
+  },
+  {
+    "name": "check_docs_sync.sh",
+    "status": "skip",
+    "message": "script not found",
+    "duration": 0
+  },
+  {
+    "name": "check_architecture_conformance.sh",
+    "status": "skip",
+    "message": "script not found",
+    "duration": 0
+  },
+  {
+    "name": "lint",
+    "status": "skip",
+    "message": "no project configuration found",
+    "duration": 0
+  },
+  {
+    "name": "type_check",
+    "status": "skip",
+    "message": "no type checker available",
+    "duration": 0
+  },
+  {
+    "name": "check_arch_sanity.sh",
+    "status": "skip",
+    "message": "script not found",
+    "duration": 0
+  },
+  {
+    "name": "check_import_boundaries.sh",
+    "status": "skip",
+    "message": "script not found",
+    "duration": 0
+  },
+  {
+    "name": "cargo test --lib",
+    "status": "fail",
+    "message": "unit test failures",
+    "duration": 0
+  },
+  {
+    "name": "integration",
+    "status": "skip",
+    "message": "PostgreSQL or Redis not available",
+    "duration": 0
+  },
+  {
+    "name": "secret_scan",
+    "status": "pass",
+    "message": "",
+    "duration": 0
+  },
+  {
+    "name": "dependency_audit",
+    "status": "skip",
+    "message": "no package manager audit tool found",
+    "duration": 0
+  },
+  {
+    "name": "migration_verify",
+    "status": "skip",
+    "message": "PostgreSQL not available",
+    "duration": 0
+  },
+  {
+    "name": "package_build",
+    "status": "skip",
+    "message": "no Dockerfile found",
+    "duration": 0
+  },
+  {
+    "name": "validate-architecture-readiness.sh",
+    "status": "skip",
+    "message": "script not found",
+    "duration": 0
+  }
+],
+  "status": "fail"
+}