guardian-framework 0.1.0

package/templates/pi/prompts/issue-closeout.md

@@ -0,0 +1,342 @@
+# Issue Closeout Workflow
+
+<!--
+Canonical Reference: .pi/prompts/issue-closeout.md
+Blueprint Source: Guardian Framework v1.2
+-->
+
+**Purpose:** Verify all acceptance criteria are met, run validators (including canonical reference check), and create a compliance merge request (MR) with complete documentation.
+
+---
+
+## Canonical Reference Requirement
+
+**Before closeout, verify all implementation files reference architecture:**
+
+```bash
+bash .pi/scripts/validate-canonical.sh
+```
+
+**Files must include:**
+```typescript
+/**
+ * Canonical Reference: .pi/architecture/modules/[module].md#[section]
+ * Implements: [issue acceptance criteria]
+ * Issue: #[number]
+ */
+```
+
+**Architecture Sync Check:**
+1. Check `.pi/architecture/CHANGELOG.md` for pending changes
+2. Verify implementation matches current architecture spec
+3. If CHANGELOG has pending changes for this module, note in MR
+
+---
+
+## Prerequisites
+
+- Issue implementation completed
+- All code changes committed to feature branch
+- Issue number known
+- Canonical references added to all modified files
+
+---
+
+## Workflow Steps
+
+### 1. Verify Acceptance Criteria
+
+Review the original issue and check each acceptance criterion:
+
+```bash
+# View original issue
+{{REPOTOOL}} issue view [ISSUE_NUMBER]
+```
+
+**Acceptance Criteria Checklist:**
+
+| Criterion | Status | Evidence |
+|-----------|--------|----------|
+| [Criterion 1] | ✅/❌ | [How verified] |
+| [Criterion 2] | ✅/❌ | [How verified] |
+| [Criterion 3] | ✅/❌ | [How verified] |
+
+**Verification Methods:**
+- Manual testing: Describe test steps performed
+- Automated tests: Reference passing test output
+- Code review: Reference specific files changed
+- Documentation: Reference docs updated
+
+### 2. Run Validators
+
+Execute all required validators based on issue scope:
+
+**CI Validator (always required):**
+
+```bash
+bash .pi/scripts/validate-ci.sh
+```
+
+Expected output:
+```
+✅ Build: Passed
+✅ Tests: All passing
+✅ Lint: No errors
+✅ Format: Correct
+✅ Audit: No vulnerabilities
+```
+
+**Test Validator (for moderate+ scope):**
+
+```bash
+bash .pi/scripts/validate-tests.sh
+```
+
+Expected output:
+```
+✅ Unit tests: [X] tests passing
+✅ Integration tests: [Y] tests passing
+✅ Coverage: [Z]% (above threshold)
+```
+
+**Security Validator (for complex+ scope):**
+
+```bash
+bash .pi/scripts/validate-security.sh
+```
+
+Expected output:
+```
+✅ No hardcoded secrets
+✅ No SQL injection patterns
+✅ No path traversal vulnerabilities
+✅ Input validation present
+```
+
+**Operations Validator (for production changes):**
+
+```bash
+bash .pi/scripts/validate-operations.sh
+```
+
+Expected output:
+```
+✅ Tracing implemented
+✅ Cancellation handling correct
+✅ Atomic writes used
+✅ Error handling complete
+```
+
+**Canonical Reference Validator (always required):**
+
+```bash
+bash .pi/scripts/validate-canonical.sh
+```
+
+Expected output:
+```
+✅ Implementation files have canonical references
+✅ References point to valid blueprint sections
+✅ Coverage ≥ 50%
+```
+
+### 3. Validator Results Recording
+
+Document all validator results:
+
+```markdown
+## Validator Results
+
+### CI Validation
+- Status: ✅ PASSED
+- Build: Success (output snippet)
+- Tests: [N] tests passed
+- Lint: 0 errors, 0 warnings
+
+### Test Validation
+- Status: ✅ PASSED
+- Unit Tests: [N] passed
+- Integration Tests: [N] passed
+- Coverage: [X]%
+
+### Security Validation
+- Status: ✅ PASSED
+- Secrets Check: No issues
+- Injection Check: No issues
+- Path Traversal: No issues
+
+### Operations Validation
+- Status: ✅ PASSED
+- Tracing: Implemented in [files]
+- Cancellation: Handled in [files]
+- Atomic Writes: Used in [files]
+
+### Canonical Reference Validation
+- Status: ✅ PASSED
+- Files with references: [X]/[Y]
+- Coverage: [Z]% (above 50% threshold)
+- All references valid
+
+### Overall Validation Status: ✅ ALL PASSED
+```
+
+### 4. Create Compliance MR
+
+Create a merge request with complete compliance documentation:
+
+**MR Title Format:**
+```
+[Issue #X] Issue Title - [brief summary]
+```
+
+**MR Body Template:**
+
+```markdown
+## Issue Closeout
+
+Closes #[ISSUE_NUMBER]
+
+### Summary
+[Brief description of changes made]
+
+### Acceptance Criteria Verification
+
+| Criterion | Status | Evidence |
+|-----------|--------|----------|
+| [AC 1] | ✅ | [Evidence link/description] |
+| [AC 2] | ✅ | [Evidence link/description] |
+| [AC 3] | ✅ | [Evidence link/description] |
+
+### Validator Results
+
+| Validator | Status | Details |
+|-----------|--------|---------|
+| CI | ✅ PASSED | Build, tests, lint all passing |
+| Test | ✅ PASSED | [N] tests, [X]% coverage |
+| Security | ✅ PASSED | No vulnerabilities detected |
+| Operations | ✅ PASSED | Production requirements met |
+| Canonical | ✅ PASSED | [X]% coverage, all refs valid |
+
+### Files Changed
+
+| File | Change Type | Reason |
+|------|-------------|--------|
+| src/foo.ts | modified | [Reason] |
+| tests/foo.test.ts | added | [Reason] |
+| docs/foo.md | updated | [Reason] |
+
+### Testing Evidence
+
+**Unit Tests:**
+```bash
+[Test command output showing passes]
+```
+
+**Integration Tests:**
+```bash
+[Test command output showing passes]
+```
+
+### Manual Testing Performed
+
+- [Test case 1]: [Result]
+- [Test case 2]: [Result]
+
+### Documentation Updates
+
+- [ ] API documentation updated
+- [ ] README updated (if applicable)
+- [ ] Inline comments added for complex logic
+
+### Deployment Notes
+
+- [Any special deployment considerations]
+- [Database migrations required: Yes/No]
+- [Configuration changes required: Yes/No]
+
+### Rollback Plan
+
+[How to rollback if issues arise]
+
+---
+
+## Compliance Checklist
+
+- [ ] All acceptance criteria verified
+- [ ] All validators passed
+- [ ] Tests cover new functionality
+- [ ] Documentation updated
+- [ ] No secrets or sensitive data in code
+- [ ] Branch up-to-date with main
+- [ ] MR ready for review
+
+---
+
+🤖 Generated with Guardian compliance workflow
+```
+
+### 5. Create MR in Repository
+
+**For GitHub (gh):**
+
+```bash
+gh pr create \
+  --title "[Issue #X] Issue Title" \
+  --body "[MR_BODY_FROM_TEMPLATE]" \
+  --base main \
+  --head [feature-branch] \
+  --assignee @me \
+  --label "ready-for-review"
+```
+
+**For GitLab (glab):**
+
+```bash
+glab mr create \
+  --title "[Issue #X] Issue Title" \
+  --description "[MR_BODY_FROM_TEMPLATE]" \
+  --target-branch main \
+  --source-branch [feature-branch] \
+  --assignee @me \
+  --label "ready-for-review"
+```
+
+### 6. Link MR to Issue
+
+**For GitHub:**
+The MR body includes "Closes #X" which auto-links.
+
+**For GitLab:**
+```bash
+glab api projects/:id/issues/[issue_iid] \
+  -f merge_request_id="[mr_id]"
+```
+
+---
+
+## Error Handling
+
+| Error | Solution |
+|-------|----------|
+| Validator failed | Fix issues, re-run validators |
+| Acceptance criteria not met | Complete implementation, re-verify |
+| Tests failing | Debug and fix tests |
+| MR creation failed | Check branch exists and is pushed |
+
+---
+
+## Acceptance Criteria
+
+- [ ] All original issue acceptance criteria verified
+- [ ] All required validators passed
+- [ ] Canonical reference validator passed (≥50% coverage)
+- [ ] Compliance MR created with full documentation
+- [ ] MR linked to original issue
+- [ ] MR status: ready for review
+- [ ] Ready for `/issue-merge` after CI pipeline passes
+
+---
+
+## Next Workflow
+
+After CI pipeline is green and MR approved, run: `/issue-merge`

package/templates/pi/prompts/issue-draft.md

@@ -0,0 +1,218 @@
+# Issue Draft Workflow
+
+**Purpose:** Issue-creator agent reads the approved epic and creates draft GitHub/GitLab issues for review before publishing.
+
+---
+
+## Prerequisites
+
+- Epic proposal approved by all validators (from `/epic-plan`)
+- Epic name and issue breakdown defined
+
+---
+
+## Workflow Steps
+
+### 1. Read Epic Proposal
+
+Load the approved epic proposal from previous workflow:
+
+```bash
+# Check for epic proposal file (if saved)
+cat .pi/context/epic-proposal.md  # if exists
+```
+
+Or use the epic details from the `/epic-plan` output.
+
+### 2. Create Issue Drafts
+
+For each issue in the epic breakdown, create a detailed draft:
+
+**Issue Template:**
+
+```markdown
+## Issue: [ISSUE_TITLE]
+
+### Epic: [EPIC_NAME]
+
+### Type: [feature/bug/refactor/docs]
+
+### Priority: [high/medium/low]
+
+### Description
+[Clear description of what needs to be done]
+
+### Acceptance Criteria
+- [ ] [Criterion 1 - specific and testable]
+- [ ] [Criterion 2 - specific and testable]
+- [ ] [Criterion 3 - specific and testable]
+
+### Implementation Notes
+- [Technical approach hints]
+- [Files likely affected]
+- [Patterns to follow from .pi/context/patterns.md]
+
+### Dependencies
+- [Depends on issue #X]
+- [Blocks issue #Y]
+
+### Estimated Scope
+- Files: [X]
+- Lines: [Y]
+- Validator Scope: [simple/moderate/complex]
+
+### Testing Requirements
+- [Unit tests required for X]
+- [Integration tests required for Y]
+
+### Documentation Updates
+- [API docs for X]
+- [README section for Y]
+```
+
+### 3. Epic Draft (GitHub/GitLab Milestone)
+
+Create the epic/milestone draft:
+
+**Epic Template (GitHub):**
+```markdown
+## Epic: [EPIC_NAME]
+
+### Milestone Title: [EPIC_NAME]
+
+### Description
+[Summary from epic proposal]
+
+### Goals
+- [Goal 1]
+- [Goal 2]
+- [Goal 3]
+
+### Issues Included
+1. #[issue_number] - [Issue title]
+2. #[issue_number] - [Issue title]
+3. #[issue_number] - [Issue title]
+
+### Tracking Issue
+[Reference to tracking issue #X]
+
+### Timeline
+- Start: [date]
+- Target Completion: [date]
+
+### Success Metrics
+- [Metric 1]
+- [Metric 2]
+```
+
+**Epic Template (GitLab):**
+```markdown
+## Epic: [EPIC_NAME]
+
+### Labels: [epic, scope:X]
+
+### Description
+[Summary from epic proposal]
+
+### Child Issues
+- #[issue_number] - [Issue title]
+- #[issue_number] - [Issue title]
+
+### Related Epics
+- #[epic_number] - [Related epic]
+
+### Milestone
+[Milestone name]
+```
+
+### 4. Tracking Issue Draft
+
+Create a tracking issue that monitors epic progress:
+
+**Tracking Issue Template:**
+
+```markdown
+## Tracking: [EPIC_NAME]
+
+### Type: tracking
+
+### Purpose
+This issue tracks the overall progress of the [EPIC_NAME] epic.
+
+### Issues Checklist
+- [ ] #[issue_1] - [title] - Status: [open/in-progress/review/merged]
+- [ ] #[issue_2] - [title] - Status: [open/in-progress/review/merged]
+- [ ] #[issue_3] - [title] - Status: [open/in-progress/review/merged]
+
+### Progress
+- Total Issues: [N]
+- Completed: 0/N (0%)
+- In Progress: 0/N (0%)
+
+### Dependencies
+- [External dependency 1]
+- [External dependency 2]
+
+### Timeline
+- Start: [date]
+- Current: [date]
+- Target: [date]
+
+### Notes
+- [Any important notes about epic execution]
+```
+
+### 5. Review Drafts
+
+Before creating in git, review all drafts:
+
+**Review Checklist:**
+- [ ] All issues have clear acceptance criteria
+- [ ] Dependencies correctly mapped
+- [ ] Scope estimates reasonable
+- [ ] Testing requirements specified
+- [ ] Documentation updates noted
+- [ ] Tracking issue includes all issues
+
+---
+
+## Output Format
+
+Save drafts for review:
+
+```
+.pi/context/issue-drafts/
+├── epic-draft.md
+├── tracking-issue-draft.md
+├── issue-1-draft.md
+├── issue-2-draft.md
+├── issue-3-draft.md
+└── review-checklist.md
+```
+
+---
+
+## Git Repository Tool
+
+Using `{{REPOTOOL}}`:
+
+| Tool | Command Preview |
+|------|-----------------|
+| **gh** | `gh issue create --title "[TITLE]" --body "[BODY]" --label "[LABELS]"` |
+| **glab** | `glab issue create --title "[TITLE]" --description "[BODY]" --label "[LABELS]"` |
+
+---
+
+## Acceptance Criteria
+
+- [ ] All issue drafts created with full details
+- [ ] Epic/milestone draft created
+- [ ] Tracking issue draft created
+- [ ] All drafts reviewed and approved
+- [ ] Ready for `/git-issues`
+
+---
+
+## Next Workflow
+
+After draft approval, run: `/git-issues` to create in repository.

package/templates/pi/prompts/issue-implementation-series.md

@@ -0,0 +1,173 @@
+# Issue Implementation Series Workflow
+
+## Overview
+Workflow for implementing a series of existing GitHub issues with categorization, batching, and pipeline validation.
+
+## Prerequisites
+- GitHub CLI (`gh`) installed and authenticated
+- Access to repository issues
+
+## Phases
+
+### Phase 1: Fetch Issues
+**Script:** `.pi/scripts/fetch-issues.sh` (or `.pi/scripts/fetch-issues.sh`)
+
+```bash
+# Fetch open issues sorted by priority
+gh issue list --state open --limit 50 --json number,title,labels,body
+```
+
+**Output:** Issues list in `.claude/plans/issues-fetched.json`
+
+### Phase 2: Categorize Issues
+**Agent:** `@architecture-coordinator`
+
+1. Analyze fetched issues
+2. Group by:
+   - **Component:** Same module/files affected
+   - **Priority:** Critical > High > Medium > Low
+   - **Dependency:** Blocking/Blocked relationships
+3. Create batch groups for feature branches
+
+**Output:** `.claude/plans/issue-groups.md`
+
+### Grouping Rules
+
+| Group Type | Criteria | Branch Naming |
+|------------|----------|---------------|
+| Component batch | Same module (2-5 issues) | `feature/{component}-{issue-range}` |
+| Priority batch | All Critical/High | `priority/critical-{date}` |
+| Related batch | Dependencies linked | `feature/{feature-name}-issues` |
+| Single | No grouping possible | `issue/{issue-number}` |
+
+### Phase 3: Plan Batch Implementation
+**Agent:** `@architecture-coordinator`
+
+For each group:
+1. Read all issue details
+2. Create combined plan in `.claude/plans/{branch-name}.md`
+3. Determine implementation order (dependencies first)
+4. Define validation requirements per issue
+
+### Phase 4: Create Feature Branch
+**Script:** `.pi/scripts/create-feature-branch.sh`
+
+```bash
+# Create branch from group name
+git checkout -b {branch-name}
+```
+
+### Phase 5: Implement Issues (Sequential)
+**Agent:** `@code-developer`
+
+For each issue in batch order:
+1. Read issue spec from plan
+2. Implement changes
+3. Run quick validation:
+   ```bash
+   cargo build && cargo test --lib
+   ```
+4. Commit with reference:
+   ```bash
+   git commit -m "feat: implement #123 - {description}"
+   ```
+5. Mark issue in progress: `gh issue comment {num} --body "Implementing in {branch}"`
+
+### Phase 6: Pre-MR Validation
+**Scripts:** Run automated validators
+
+```bash
+# Full validation before MR
+.pi/scripts/validate-ci.sh
+.pi/scripts/validate-tests.sh
+.pi/scripts/validate-security.sh
+.pi/scripts/validate-operations.sh
+```
+
+**Gate:** All scripts must PASS
+
+### Phase 7: Create MR/PR
+**Script:** `.pi/scripts/create-mr.sh`
+
+```bash
+# Push and create PR
+git push -u origin {branch-name}
+
+gh pr create \
+  --title "feat: implement issues {range}" \
+  --body "$(cat .claude/plans/{branch-name}-pr-body.md)" \
+  --base main
+```
+
+### Phase 8: MR Validation Workflow
+**Agent:** `@architecture-coordinator`
+
+Run MR validation sequence:
+
+1. **Automated CI:** Wait for GitHub Actions to complete
+2. **Architecture check:** Run architecture-validator
+3. **Security check:** Run security-validator
+4. **Integration check:** Run integration-validator
+
+**Gate:** All checks green
+
+### Phase 9: Address MR Feedback
+If checks fail:
+1. Read failure logs
+2. Fix issues (not bypass)
+3. Push fixes
+4. Re-run validation
+
+**Max retries:** 3
+
+### Phase 10: Merge
+**Script:** `.pi/scripts/merge-mr.sh`
+
+```bash
+# Merge when green
+gh pr merge --squash --delete-branch
+
+# Close implemented issues
+for issue in {issue-list}; do
+  gh issue close $issue --comment "Implemented in #{pr-number}"
+done
+```
+
+### Phase 11: Next Batch
+Return to Phase 3 for next group.
+
+---
+
+## Scripts Required
+
+| Script | Purpose |
+|--------|---------|
+| `fetch-issues.sh` | Fetch open issues from GitHub |
+| `categorize-issues.sh` | Group issues by component/priority |
+| `create-feature-branch.sh` | Create branch from group |
+| `create-mr.sh` | Create PR with body template |
+| `merge-mr.sh` | Merge PR and close issues |
+| `mr-validation.sh` | Run all MR checks |
+
+## Issue Status Tracking
+
+| State | Action |
+|-------|--------|
+| Open | Fetched, waiting implementation |
+| In Progress | Comment added, branch created |
+| Implemented | Code done, PR created |
+| Closed | Merged, issue resolved |
+
+## Deterministic Checks (Pipeline Must Be Green)
+
+```bash
+# Before MR
+cargo build
+cargo test --all
+cargo clippy -- -D warnings
+cargo fmt --check
+cargo audit
+
+# MR pipeline
+.ci/pipeline.sh  # or equivalent
+```