copilot-guardian 0.2.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Flamehaven
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+<div align="center">
+
+<img src="docs/Logo.png" alt="Copilot Guardian Logo" width="400"/>
+
+# Copilot Guardian
+
+Deterministic safety layer for Copilot-driven CI healing.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/flamehaven01/copilot-guardian/actions/workflows/ci.yml/badge.svg)](https://github.com/flamehaven01/copilot-guardian/actions/workflows/ci.yml)
+[![Version: 0.2.5](https://img.shields.io/badge/version-0.2.5-blue.svg?style=flat-square)](https://github.com/flamehaven01/copilot-guardian/releases)
+[![Release: v0.2.5](https://img.shields.io/badge/release-v0.2.5-0A66C2.svg?style=flat-square)](https://github.com/flamehaven01/copilot-guardian/releases/tag/v0.2.5)
+[![Copilot CLI Challenge](https://img.shields.io/badge/GitHub-Copilot_Challenge-181717.svg?style=flat-square&logo=github&logoColor=white)](https://dev.to/challenges/github-2026-01-21)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-3178C6.svg?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![MCP](https://img.shields.io/badge/MCP-Enabled-FF5722.svg?style=flat-square)](https://modelcontextprotocol.io/)
+
+[Why Challenge](#why-this-is-a-copilot-cli-challenge-submission) • [Judge Quick Test](#judge-quick-test-90-seconds) • [Final GIF](#final-gif-slot-submission-finalization) • [Quick Start](#quick-start) • [How It Works](#how-it-works) • [Docs](#documentation-links)
+
+</div>
+
+---
+
+## Why This Is a Copilot CLI Challenge Submission
+
+This project demonstrates five advanced Copilot usage patterns under real CI failures:
+
+1. Multi-hypothesis reasoning with explicit confidence and evidence
+2. Patch synthesis across conservative, balanced, and aggressive strategies
+3. Deterministic fail-closed guardrails against slop and bypass patterns
+4. MCP-enriched context to improve diagnosis quality
+5. Transparent artifact trail (`analysis.json`, raw responses, patch index)
+
+Runtime clarification:
+- Production path uses `@github/copilot-sdk`
+- CLI fallback is for local experimentation only
+
+---
+
+## Judge Quick Test (90 seconds)
+
+```bash
+copilot-guardian run \
+  --repo flamehaven01/copilot-guardian \
+  --last-failed \
+  --show-options \
+  --fast \
+  --max-log-chars 20000
+```
+
+Expected:
+1. Structured diagnosis in `analysis.json`
+2. Patch spectrum in `patch_options.json`
+3. Safety verdicts in `quality_review.*.json`
+
+For extended trace mode (slower), add `--show-reasoning`.
+
+---
+
+## Final GIF Slot (Submission Finalization)
+
+Final demo artifact:
+
+![Judge Quick Test Demo](docs/screenshots/final-demo.gif)
+
+Runtime: 3m43s, Profile: --fast --max-log-chars 20000 (reasoning hidden for stable demo)
+
+---
+
+## Forced Abstain Policy (NOT PATCHABLE)
+
+Guardian intentionally abstains for non-patchable failure classes such as:
+- `401/403` auth failures
+- token permission errors
+- API rate-limit or infra-unavailable patterns
+
+When abstaining, `abstain.report.json` is emitted and patch generation is skipped.
+
+---
+
+## Copilot Challenge Showcase: Five Advanced Usage Patterns
+
+1. Multi-turn structured reasoning
+2. Schema-constrained JSON outputs
+3. Risk-calibrated generation
+4. Independent validation loop
+5. Fail-closed enforcement
+
+Why this matters: AI slop in CI can produce green-looking but unsafe results.
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js >=18
+- GitHub CLI (`gh`) authenticated
+- GitHub Copilot subscription (SDK access)
+
+### Installation
+
+```bash
+npm install -g copilot-guardian
+# or
+npx copilot-guardian --help
+```
+
+### Core Commands
+
+```bash
+# Stable demo profile
+copilot-guardian run \
+  --repo owner/repo \
+  --last-failed \
+  --show-options \
+  --fast \
+  --max-log-chars 20000
+
+# Analysis only
+copilot-guardian analyze \
+  --repo owner/repo \
+  --run-id <run_id> \
+  --fast \
+  --max-log-chars 20000
+
+# Evaluate multiple failed runs
+copilot-guardian eval \
+  --repo owner/repo \
+  --failed-limit 5 \
+  --fast \
+  --max-log-chars 50000
+
+# Interactive follow-up
+copilot-guardian debug \
+  --repo owner/repo \
+  --last-failed
+```
+
+---
+
+## How It Works
+
+Full architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+
+```mermaid
+graph TB
+    A[GitHub Actions Failure] --> B[Guardian CLI]
+    B --> C[Context Fetch]
+    C --> D[Multi-Hypothesis Analysis]
+    D --> E[Copilot SDK]
+    E --> F[Patch Strategies]
+    F --> G[Deterministic Quality Guard]
+    G --> H{GO?}
+    H -->|NO_GO| I[Reject and Re-diagnose]
+    H -->|GO| J[Patch Candidate]
+    J --> K[Safe Branch PR or Auto-Heal]
+```
+
+### Key Modules
+
+| Layer | Module | Purpose |
+|---|---|---|
+| Detection | `src/engine/github.ts` | Collect failure context |
+| Intelligence | `src/engine/analyze.ts` | Multi-hypothesis diagnosis |
+| Decision | `src/engine/patch_options.ts` | Strategy generation |
+| Validation | Deterministic + model review | Slop and bypass control |
+| Action | `src/engine/auto-apply.ts` | Safe branch/PR workflow |
+
+---
+
+## Output Files
+
+Artifacts are generated under `.copilot-guardian/`:
+
+| File | Purpose |
+|---|---|
+| `analysis.json` | Diagnosis + selected hypothesis |
+| `reasoning_trace.json` | Hypothesis trace |
+| `patch_options.json` | Strategy index + verdicts |
+| `fix.*.patch` | Patch files |
+| `quality_review.*.json` | Per-strategy quality results |
+| `abstain.report.json` | Forced abstain classification |
+| `copilot.*.raw.txt` | Raw model output snapshots |
+
+---
+
+## Documentation Links
+
+- Architecture: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)
+- Demo walkthrough: [examples/demo-failure/README.md](examples/demo-failure/README.md)
+- Changelog: [CHANGELOG.md](CHANGELOG.md)
+- Security: [SECURITY.md](SECURITY.md)
+- Contributing: [CONTRIBUTING.md](CONTRIBUTING.md)
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+
+## Credits
+
+Built by Flamehaven (Yun) for the [GitHub Copilot CLI Challenge](https://dev.to/challenges/github-2026-01-21).
+
+---
+
+Trust is built on receipts.

package/SECURITY.md

@@ -0,0 +1,150 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 0.2.x   | :white_check_mark: |
+
+## Security Philosophy
+
+Copilot Guardian is designed with security-first principles:
+
+### 1. Secret Redaction
+All logs and context sent to AI models are automatically sanitized:
+- GitHub tokens (`ghp_*`, `ghs_*`, `gho_*`)
+- Bearer tokens
+- API keys
+- Passwords in error messages
+
+### 2. Local-First Processing
+- All analysis happens locally via GitHub Copilot CLI
+- No data is sent to external servers (except GitHub's Copilot API via authenticated CLI)
+- Full audit trail maintained in `.copilot-guardian/` directory
+
+### 3. Transparency
+- All raw inputs and outputs are saved (`.raw.txt` files)
+- Users can inspect exactly what data was sent to AI models
+- No hidden telemetry or data collection
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in Copilot Guardian, please:
+
+1. **DO NOT** open a public issue
+2. Email: info@flamehaven.space
+3. Include:
+   - Description of the vulnerability
+   - Steps to reproduce
+   - Potential impact
+   - Suggested fix (if any)
+
+### Response Timeline
+- **24 hours**: Initial acknowledgment
+- **7 days**: Detailed assessment and action plan
+- **30 days**: Fix implementation and disclosure
+
+## Security Best Practices for Users
+
+### Authentication
+```bash
+# Ensure GitHub CLI is authenticated
+gh auth status
+
+# Use token with minimal required scopes
+# Required: repo, workflow
+```
+
+### Environment Variables
+```bash
+# Never commit .env files
+# Use GitHub Secrets for CI/CD environments
+```
+
+### Patch Review
+```bash
+# Always review patches before applying
+copilot-guardian fix --interactive
+
+# Use Conservative mode for production
+# Review the "Quality Verdict" before accepting
+```
+
+## Known Limitations
+
+### 1. GitHub CLI Security
+- Guardian inherits gh CLI's authentication model
+- Ensure `gh` is up to date: `gh version`
+
+### 2. AI Model Limitations
+- LLMs can hallucinate - always review patches
+- Use the Anti-Slop quality checks
+- Test patches in non-production environments first
+
+### 3. Rate Limits
+- GitHub API rate limits apply
+- Copilot API rate limits apply
+- Guardian implements exponential backoff
+
+## Security Audit Trail
+
+Every Guardian run creates:
+```
+.copilot-guardian/
+├── [timestamp]-context.raw.txt    # What was sent to AI
+├── [timestamp]-analysis.json      # AI response (structured)
+└── [timestamp]-patches.json       # Generated patches
+```
+
+This enables:
+- Post-incident forensics
+- Compliance audits
+- Privacy verification
+
+## Data Privacy
+
+### What Guardian Collects
+- GitHub Actions logs (for analysis)
+- Repository metadata (via gh CLI)
+- Source code context (when using MCP)
+
+### What Guardian DOES NOT Collect
+- User credentials
+- Unrelated source code
+- Personal information
+- Telemetry or usage statistics
+
+### Data Retention
+- All data is stored locally in `.copilot-guardian/`
+- User controls retention (can delete directory)
+- No cloud storage or external databases
+
+## Compliance
+
+### GDPR
+- All processing is local
+- No data transfer to third parties (except GitHub Copilot API via user's authenticated session)
+- User has full control and right to erasure
+
+### Enterprise Use
+- Compatible with GitHub Enterprise
+- Works within corporate firewalls
+- No external dependencies beyond GitHub APIs
+
+## Security Updates
+
+Subscribe to security advisories:
+```bash
+gh repo subscribe flamehaven01/copilot-guardian --alerts
+```
+
+## Contact
+
+- Security Issues: info@flamehaven.space
+- General Issues: [GitHub Issues](https://github.com/flamehaven01/copilot-guardian/issues)
+- Documentation: [docs/](./docs/)
+
+---
+
+**Last Updated**: 2026-02-12
+**Security Policy Version**: 0.2.5