icdev 1.0.0__py3-none-any.whl

icdev/data/goals/init_project.md

@@ -0,0 +1,235 @@
+# Goal: Initialize New ICDEV Project
+
+## Description
+
+Initialize a new project within the ICDEV framework with full compliance scaffolding, database records, CUI markings, and audit trail. This is the entry point for every new project — nothing gets built without this step completing first.
+
+**Why this matters:** Government and DoD projects require traceability from day one. Retroactively applying compliance is 10x harder than starting with it. This workflow ensures every project is born compliant.
+
+---
+
+## Prerequisites
+
+- [ ] ICDEV database initialized (`python tools/db/init_icdev_db.py`)
+- [ ] `.env` file exists with required configuration
+- [ ] User has provided: project name, project type, classification level
+- [ ] `memory/MEMORY.md` loaded (session context)
+
+---
+
+## Process
+
+### Step 1: Validate Inputs
+
+**Action:** Confirm required parameters before creating anything.
+
+```
+Required:
+  --name         Project name (lowercase, hyphens, no spaces)
+  --type         Project type: webapp | api | microservice | infrastructure | library
+  --classification  CUI | UNCLASSIFIED | FOUO
+```
+
+**Validation rules:**
+- Name must be unique (check DB first)
+- Name must match pattern: `^[a-z][a-z0-9-]{2,48}$`
+- Type must be one of the allowed values
+- Classification defaults to CUI if not specified (safe default)
+
+**Error handling:**
+- Duplicate name → suggest alternative with timestamp suffix
+- Invalid characters → strip and confirm with user
+- Missing classification → default to CUI, inform user
+
+---
+
+### Step 2: Create Project Record in Database
+
+**Tool:** `python tools/project/project_create.py --name <name> --type <type> --classification <classification>`
+
+**Expected output:**
+```
+Project created: <project-id>
+Name: <name>
+Type: <type>
+Classification: <classification>
+Status: initialized
+Created: <timestamp>
+```
+
+**Error handling:**
+- DB locked → retry 3 times with 1s backoff
+- DB missing → run `python tools/db/init_icdev_db.py` first, then retry
+- Creation failed → read error, do not proceed, report to user
+
+**Verify:** Query DB to confirm record exists before proceeding.
+
+---
+
+### Step 3: Scaffold Project Directory
+
+**Tool:** `python tools/project/project_scaffold.py --project-id <project-id> --type <type>`
+
+**Expected output:**
+```
+Scaffolded project directory:
+  projects/<name>/
+  ├── src/
+  ├── tests/
+  │   ├── unit/
+  │   ├── integration/
+  │   └── features/          # Gherkin feature files
+  ├── docs/
+  │   ├── architecture/
+  │   └── compliance/
+  ├── infrastructure/
+  │   ├── terraform/
+  │   ├── ansible/
+  │   └── k8s/
+  ├── security/
+  │   └── scan-results/
+  ├── .gitlab-ci.yml          # Pipeline template
+  ├── Dockerfile              # STIG-hardened base
+  ├── requirements.txt        # or package.json
+  └── README.md
+```
+
+**Error handling:**
+- Directory already exists → check if it's an abandoned scaffold. If empty, remove and re-scaffold. If populated, abort and report.
+- Permission error → report, do not attempt chmod
+
+**Verify:** Confirm directory tree matches expected structure for project type.
+
+---
+
+### Step 4: Apply CUI Markings
+
+**Tool:** `python tools/compliance/cui_marker.py --directory projects/<name>`
+
+**Expected output:**
+```
+CUI markings applied:
+  - Banner added to all source files
+  - README.md marked with classification
+  - .cui-manifest.json created
+  Files marked: <count>
+  Classification: <classification>
+```
+
+**Error handling:**
+- No files to mark → warning only, proceed (empty scaffold is expected)
+- Unknown file type → skip with warning, log skipped files
+
+**Verify:** Spot-check 2-3 files for correct CUI banner format:
+```
+// CUI // CONTROLLED UNCLASSIFIED INFORMATION
+// Authorized distribution only
+```
+
+---
+
+### Step 5: Initialize Compliance Baseline
+
+**Tool:** `python tools/compliance/control_mapper.py --project <name> --control-families "AC,AU,CM,IA,SC"`
+
+**Expected output:**
+```
+Control mapping initialized:
+  - AC (Access Control): 25 controls mapped
+  - AU (Audit): 16 controls mapped
+  - CM (Configuration Management): 11 controls mapped
+  - IA (Identification & Authentication): 11 controls mapped
+  - SC (System & Communications): 44 controls mapped
+  Total: 107 controls
+  Status: NOT_ASSESSED
+```
+
+**Error handling:**
+- Unknown control family → warn, skip that family, continue with valid ones
+- DB write failure → retry, then report
+
+**Verify:** Query compliance status shows project with mapped controls.
+
+---
+
+### Step 6: Log to Audit Trail
+
+**Tool:** `python tools/audit/audit_logger.py --event "project_initialized" --actor "orchestrator" --action "create" --project <name>`
+
+**Expected output:**
+```
+Audit entry logged:
+  ID: <entry-id>
+  Event: project_initialized
+  Actor: orchestrator
+  Action: create
+  Project: <name>
+  Timestamp: <ISO-8601>
+  Hash: <SHA-256>
+```
+
+**Error handling:**
+- Audit log failure is a CRITICAL error — do not proceed silently
+- If audit write fails, mark project as "init_incomplete" in DB
+- Retry 3 times, then escalate to user
+
+**Verify:** Query audit trail confirms entry exists and hash chain is intact.
+
+---
+
+### Step 7: Log to Memory
+
+**Tool:** `python tools/memory/memory_write.py --content "Initialized project <name> (type: <type>, classification: <classification>, id: <project-id>)" --type event --importance 6`
+
+**Expected output:** Confirmation written to daily log and memory DB.
+
+---
+
+## Success Criteria
+
+- [ ] Project record exists in database with correct metadata
+- [ ] Directory structure matches expected scaffold for project type
+- [ ] CUI markings applied to all applicable files
+- [ ] NIST 800-53 control families mapped (minimum: AC, AU, CM, IA, SC)
+- [ ] Audit trail entry logged with valid hash
+- [ ] Memory entry recorded
+
+**All 6 checks must pass.** If any fail, the project is in an inconsistent state — investigate and fix before proceeding to any other workflow.
+
+---
+
+## Edge Cases & Notes
+
+1. **Re-initialization:** If a project with the same name exists but is marked "abandoned" or "init_incomplete", offer to clean up and re-initialize rather than failing.
+2. **Offline mode:** If DB is unavailable, create the directory scaffold anyway but mark it clearly as "unregistered" — the user can register it later.
+3. **Classification upgrade:** If a project starts as UNCLASSIFIED and later needs CUI, re-run Step 4 with the new classification. Do NOT downgrade classifications.
+4. **Batch initialization:** For multiple projects, run sequentially — do not parallelize DB writes.
+5. **Project naming collisions:** The timestamp suffix approach (`my-project-20260214`) prevents collisions but creates ugly names. Prefer asking the user for an alternative.
+
+---
+
+## GOTCHA Layer Mapping
+
+| Step | GOTCHA Layer | Component |
+|------|-------------|-----------|
+| Validate inputs | Args | User-provided parameters |
+| Create DB record | Tools | project_create.py |
+| Scaffold directory | Tools | project_scaffold.py |
+| Apply CUI markings | Tools | cui_marker.py |
+| Initialize compliance | Tools | control_mapper.py |
+| Log to audit | Tools | audit_logger.py |
+| Orchestrate all steps | Orchestration | AI (you) |
+
+---
+
+## Related Files
+
+- **Tools:** `tools/project/project_create.py`, `tools/project/project_scaffold.py`, `tools/compliance/cui_marker.py`, `tools/compliance/control_mapper.py`, `tools/audit/audit_logger.py`
+- **Database:** `data/icdev.db` (projects table)
+- **Context:** `context/classification_guide.md` (CUI marking rules)
+
+---
+
+## Changelog
+
+- 2026-02-14: Initial creation

icdev/data/goals/innovation_engine.md

@@ -0,0 +1,199 @@
+# Innovation Engine — Autonomous Self-Improvement Pipeline
+
+CUI // SP-CTI
+
+## Purpose
+
+The Innovation Engine enables ICDEV to continuously and autonomously improve itself by:
+1. Discovering developer pain points, CVEs, compliance changes, and competitive gaps
+2. Scoring and triaging discoveries through compliance-first gates
+3. Generating solution specifications using existing ATLAS/M-ATLAS workflow
+4. Publishing solutions to the ICDEV marketplace for ecosystem-wide benefit
+5. Learning from feedback to improve future discovery quality
+
+## Architecture Decision Records
+
+- **D199:** Scan frequency configurable per source in `args/innovation_config.yaml` (D26 pattern)
+- **D200:** Human-in-the-loop threshold: score >= 0.80 auto-queues, 0.50-0.79 suggests, < 0.50 logs only
+- **D201:** Innovation budget: max 10 auto-generated solutions per PI to prevent scope creep
+- **D202:** IP/license scanning blocks GPL/AGPL/SSPL solutions (copyleft risk for Gov/DoD)
+- **D203:** Introspective analysis is air-gap safe (no web access needed, reads internal DB only)
+- **D204:** Standards body monitoring degrades gracefully when offline (skips HTTP, logs warning)
+- **D205:** Competitive intel for GitHub-based competitors only (website scraping requires additional setup)
+- **D206:** All innovation signals are append-only in DB (D6 pattern), triage decisions are audited
+- **D207:** Trend detection uses deterministic keyword co-occurrence (no LLM required, air-gap safe)
+- **D208:** Solution specs are template-based (not LLM-generated), validated by spec_quality_checker
+
+## Pipeline Overview
+
+```
+DISCOVER (web + introspective + competitive + standards)
+    → SCORE (5-dimension weighted average)
+        → TRIAGE (5-stage compliance gate)
+            → GENERATE (template-based spec)
+                → BUILD (ATLAS/M-ATLAS TDD)
+                    → PUBLISH (marketplace 7-gate pipeline)
+                        → MEASURE (adoption + impact)
+                            → CALIBRATE (weight adjustment)
+```
+
+## Tools
+
+| Tool | File | Purpose |
+|------|------|---------|
+| Web Scanner | `tools/innovation/web_scanner.py` | Scan GitHub, NVD, Stack Overflow, HN for signals |
+| Signal Ranker | `tools/innovation/signal_ranker.py` | 5-dimension innovation scoring |
+| Trend Detector | `tools/innovation/trend_detector.py` | Cross-signal pattern detection |
+| Triage Engine | `tools/innovation/triage_engine.py` | 5-stage compliance-first triage |
+| Solution Generator | `tools/innovation/solution_generator.py` | Auto-generate solution specs |
+| Innovation Manager | `tools/innovation/innovation_manager.py` | Main orchestrator + daemon mode |
+| Introspective Analyzer | `tools/innovation/introspective_analyzer.py` | Internal telemetry mining |
+| Competitive Intel | `tools/innovation/competitive_intel.py` | Competitor feature monitoring |
+| Standards Monitor | `tools/innovation/standards_monitor.py` | NIST/CISA/DoD change tracking |
+| MCP Server | `tools/mcp/innovation_server.py` | MCP tools for Claude Code integration |
+
+## Configuration
+
+- `args/innovation_config.yaml` — All settings: sources, scoring weights, triage rules, scheduling
+
+## Database Tables
+
+| Table | Purpose |
+|-------|---------|
+| `innovation_signals` | Discovered signals (append-only) |
+| `innovation_triage_log` | Triage decisions per signal (append-only) |
+| `innovation_solutions` | Generated solution specs |
+| `innovation_trends` | Detected trend clusters |
+| `innovation_competitor_scans` | Competitive intel scan results |
+| `innovation_standards_updates` | Standards body change tracking |
+| `innovation_feedback` | Feedback loop metrics for calibration |
+
+## Stage 1: Discovery
+
+### Web Intelligence Sources
+1. **GitHub** — Trending repos, issues (bug/enhancement/security), discussions
+2. **CVE Databases** — NVD (CRITICAL/HIGH), GitHub Security Advisories
+3. **Stack Overflow** — Top-voted questions in DevSecOps/compliance/K8s/IaC tags
+4. **Hacker News** — High-score stories on security/devops/compliance topics
+5. **Package Registries** — PyPI/npm trending packages in security/compliance categories
+6. **Compliance Updates** — FedRAMP marketplace, CMMC AB, Federal Register
+
+### Introspective Sources (Air-Gap Safe)
+1. **Failed Self-Heals** — ICDEV problems it can't solve yet (confidence < 0.3)
+2. **Gate Failure Frequency** — Which gates fail most? Build better tooling
+3. **Unused Tools** — Improve discoverability or deprecate
+4. **Slow Pipeline Stages** — Performance optimization targets
+5. **NLQ Gaps** — Questions with no answers = knowledge gaps
+6. **Knowledge Gaps** — Self-heal patterns with no resolution
+
+### Competitive Intelligence
+- Monitor GitHub repos: backstage, snyk, trivy, checkov
+- Track releases and new features
+- Gap analysis: what competitors have that ICDEV doesn't
+
+### Standards Body Monitoring
+- NIST CSRC publications (SP 800, FIPS, IR series)
+- CISA advisories and binding operational directives
+- DoD CIO memos (zero trust, DevSecOps, CMMC, cATO, MOSA)
+- FedRAMP updates and marketplace changes
+
+## Stage 2: Scoring
+
+5-dimension weighted average (D21 pattern):
+
+| Dimension | Weight | Metric |
+|-----------|--------|--------|
+| Community Demand | 0.30 | Stars, votes, upvotes, issue frequency |
+| Impact Breadth | 0.25 | ICDEV tenants/projects potentially affected |
+| Feasibility | 0.20 | Can ICDEV build with existing tools? |
+| Compliance Alignment | 0.15 | Strengthens (not weakens) compliance |
+| Novelty | 0.10 | Not already addressed by ICDEV |
+
+### Thresholds
+- **>= 0.80** — Auto-queue for solution generation
+- **0.50 - 0.79** — Suggest to human, require approval
+- **< 0.50** — Log for trend analysis only
+
+## Stage 3: Triage (5-Stage Compliance Gate)
+
+Every signal passes through ALL 5 stages:
+
+1. **Classify Signal** — Map to category via keyword matching
+2. **GOTCHA Fit Check** — Must map to Goal/Tool/Arg/Context/HardPrompt
+3. **Boundary Impact** — GREEN/YELLOW/ORANGE/RED assessment
+4. **Compliance Pre-Check** — Block if would weaken compliance posture
+5. **Duplicate/License Check** — Dedup + license compatibility
+
+### Blocking Rules
+- RED boundary impact → BLOCKED (no auto-generation)
+- Compliance-weakening detected → BLOCKED
+- GPL/AGPL/SSPL license → BLOCKED
+- Duplicate signal (similarity > 0.85) → BLOCKED
+- No GOTCHA layer fit → BLOCKED
+
+## Stage 4: Solution Generation
+
+Template-based spec generation with sections:
+1. Problem Statement
+2. GOTCHA Layer mapping
+3. Proposed Solution (layer-specific template)
+4. Acceptance Criteria (BDD-style)
+5. Compliance Impact assessment
+6. Test Plan (unit + BDD)
+7. Marketplace Asset Type
+8. Estimated Effort (S/M/L/XL)
+
+## Stage 5-6: Build & Publish
+
+Reuse existing ICDEV pipelines:
+- **Build:** ATLAS/M-ATLAS workflow via `/icdev-build`
+- **Test:** Full test suite via `/icdev-test`
+- **Security:** SAST + dependency audit via `/icdev-secure`
+- **Compliance:** CUI markings + STIG via `/icdev-comply`
+- **Publish:** Marketplace 7-gate pipeline via `/icdev-market`
+
+## Stage 7: Feedback & Calibration
+
+Metrics that feed back into scoring weight calibration:
+1. Marketplace install count (high installs = good signal quality)
+2. Marketplace rating (high ratings = good solution quality)
+3. Self-heal pattern hits (patterns that prevent future failures)
+4. Gate failure reduction (solutions that reduce gate failures)
+5. Tenant feature requests (addressed vs total)
+
+Weight adjustment: max 0.02 step per calibration cycle, min 10 data points.
+
+## Scheduling
+
+- **Daemon mode:** Continuous background scanning
+- **Quiet hours:** No solution generation during 02:00-06:00 UTC
+- **Budget:** Max 10 auto-generated solutions per PI
+- **Rate limiting:** Per-source configurable (GitHub: 60/hr, NVD: careful)
+
+## Security Gates
+
+| Gate | Condition |
+|------|-----------|
+| Innovation Triage | 5-stage compliance check must pass |
+| License Check | No GPL/AGPL/SSPL (copyleft risk) |
+| Boundary Impact | RED items blocked from auto-generation |
+| Compliance Alignment | Must not weaken existing compliance posture |
+| Solution Build | Must pass all existing security gates (SAST, deps, secrets, CUI) |
+| Marketplace Publish | Must pass 7-gate marketplace pipeline |
+| Budget Cap | Max 10 auto-solutions per PI |
+
+## Error Handling
+
+- Web scanner failures: log error signal, continue with other sources
+- Database missing: return error with migration instructions
+- Air-gapped mode: skip web sources, run introspective analysis only
+- Rate limiting: back off and retry with exponential delay
+- Budget exceeded: log signal for next PI, don't generate solution
+
+## Edge Cases
+
+1. **Same CVE from NVD + GitHub Advisories** — Dedup by content_hash (CVE ID)
+2. **Competitor releases a feature ICDEV already has** — Novelty score = 0, auto-logged
+3. **Standards body publishes draft (not final)** — Flag as draft, lower priority
+4. **Innovation signal maps to multiple GOTCHA layers** — Pick primary, note others
+5. **Solution spec fails quality check** — Block generation, log for manual review

icdev/data/goals/integration_testing.md

@@ -0,0 +1,189 @@
+# Goal: Integration Testing (Phase 13)
+
+## Purpose
+Validate the complete ICDEV system through multi-layer testing: unit tests (pytest), BDD tests (behave/Gherkin), E2E browser tests (Playwright MCP), security gate evaluation, and compliance gate evaluation — with automatic retry and failure resolution.
+
+## Trigger
+- `/icdev-test` skill invoked
+- Post-build validation in ATLAS workflow
+- Pre-merge gate check
+- Pre-deployment validation
+
+## Inputs
+- Project directory path
+- Project UUID (optional, for compliance gates)
+- Test orchestrator config (`args/project_defaults.yaml`)
+- E2E test specs (`.claude/commands/e2e/*.md`)
+- Playwright MCP config (`playwright-mcp-config.json`)
+
+## Testing Architecture (Adapted from ADW)
+
+### Test Layers
+| Layer | Framework | Config | Purpose |
+|-------|-----------|--------|---------|
+| Unit | pytest | tests/ | Function-level correctness |
+| BDD | behave (Gherkin) | features/ | Business requirement validation |
+| E2E (native) | Playwright CLI | tests/e2e/*.spec.ts | Browser-based UI validation (preferred) |
+| E2E (MCP) | Playwright MCP | .claude/commands/e2e/*.md | Browser-based UI validation (fallback) |
+| Security | ICDEV security tools | security_gates.yaml | Vulnerability assessment |
+| Compliance | ICDEV compliance tools | project_defaults.yaml | NIST 800-53 gate evaluation |
+
+### Key ADW Patterns Adopted
+1. **Pydantic data types** — TestResult, E2ETestResult, CheckResult (structured, validated)
+2. **parse_json()** — Handles markdown-wrapped JSON output from Claude Code
+3. **Retry with resolution** — Max 4 unit retries, max 2 E2E retries, stop if no progress
+4. **Fail-fast E2E** — Stop on first E2E failure (sequential execution)
+5. **Health check gating** — Validate environment before test execution
+6. **Dual logging** — File (DEBUG) + console (INFO)
+7. **Safe subprocess env** — Filter environment variables for subprocess security
+8. **Playwright MCP** — Chromium headless, 1920x1080, video recording, screenshot capture
+9. **stdin=DEVNULL** — Prevent Claude Code hanging in subprocess (E2B sandbox lesson)
+
+## Process
+
+### Step 1: Health Check
+**Tool:** `tools/testing/health_check.py`
+- Validate environment variables
+- Check database connectivity (28 tables)
+- Verify Python dependencies
+- Check tool availability
+- Validate MCP server configs
+- Test Claude Code CLI
+
+### Step 2: Unit Tests (pytest)
+**Tool:** `tools/testing/test_orchestrator.py` → `run_pytest()`
+- Run pytest with verbose output and coverage
+- Parse results into `TestResult` objects
+- Record results in audit trail
+- **Gate:** All tests must pass
+
+### Step 3: BDD Tests (behave)
+**Tool:** `tools/testing/test_orchestrator.py` → `run_behave()`
+- Run behave with JSON output
+- Parse Gherkin scenario results
+- Map to `TestResult` objects with `test_type="bdd"`
+- **Gate:** All scenarios must pass
+
+### Step 4: Retry Logic
+**Tool:** `tools/testing/test_orchestrator.py` → `run_tests_with_resolution()`
+- If failures detected, log failure details
+- Retry up to `MAX_TEST_RETRY_ATTEMPTS` (4)
+- Stop early if no progress between retries
+- Each retry re-runs full suite
+
+### Step 5: E2E Tests (Playwright Native + MCP Fallback)
+**Tool:** `tools/testing/e2e_runner.py`
+- **Native mode (preferred):** Run `tests/e2e/*.spec.ts` via `npx playwright test`
+  - Auto-detected when Playwright CLI installed and `.spec.ts` files exist
+  - JSON reporter output parsed into E2ETestResult objects
+  - Supports Chromium, Firefox, WebKit (configurable via `--project`)
+  - Config: `playwright.config.ts`
+- **MCP mode (fallback):** Discover `.claude/commands/e2e/*.md` specs
+  - Executed via Claude Code CLI + Playwright MCP
+  - Used when native Playwright not installed
+- Capture screenshots to `.tmp/test_runs/{run_id}/screenshots/`
+- Record video per `playwright.config.ts` (native) or `playwright-mcp-config.json` (MCP)
+- **Fail-fast:** Stop on first E2E failure
+- Retry up to `MAX_E2E_TEST_RETRY_ATTEMPTS` (2)
+- **CUI verification:** Check CUI banners on every page
+
+### Step 6: Security Gate
+**Tool:** `tools/testing/test_orchestrator.py` → `evaluate_security_gate()`
+- Run SAST (bandit)
+- Run secret detection
+- Evaluate against security_gates.yaml thresholds
+- **Gate:** 0 HIGH SAST findings, 0 secrets detected
+
+### Step 7: Compliance Gate
+**Tool:** `tools/testing/test_orchestrator.py` → `evaluate_compliance_gate()`
+- Check CUI markings on all source files
+- Verify STIG findings (0 CAT1)
+- Verify SBOM currency
+- **Gate:** All blocking gates must pass
+
+### Step 8: Summary Report
+Generate CUI-marked test report:
+- Unit test results (pass/fail per test)
+- BDD test results (pass/fail per scenario)
+- E2E test results (pass/fail per spec, with screenshots)
+- Security gate result
+- Compliance gate result
+- Overall pass/fail
+- Save to `.tmp/test_runs/{run_id}/summary.md`
+
+### Step 9: Audit Trail
+**Tool:** `tools/audit/audit_logger.py`
+- Record: event_type=test.complete
+- Include: all counts, gate results, run_id
+- **NIST Controls:** SA-11, SA-15, CM-3
+
+## Testing Tools
+
+| Tool | File | Purpose |
+|------|------|---------|
+| Data Types | tools/testing/data_types.py | Pydantic models for test results |
+| Utilities | tools/testing/utils.py | JSON parsing, logging, safe env |
+| Health Check | tools/testing/health_check.py | System validation (7 checks) |
+| Test Orchestrator | tools/testing/test_orchestrator.py | Full test pipeline with retry |
+| E2E Runner | tools/testing/e2e_runner.py | Native Playwright + MCP test execution |
+| Playwright Config | playwright.config.ts | Playwright test runner configuration |
+| E2E Specs | tests/e2e/*.spec.ts | Native Playwright test specifications |
+
+## Configuration
+
+### Playwright Native (playwright.config.ts)
+```typescript
+// Sequential execution for audit traceability, JSON + HTML reporters
+// Supports chromium, firefox, webkit projects
+// Screenshots on, video on, 1920x1080 viewport
+// Output: .tmp/test_runs/playwright-results.json, .tmp/test_runs/playwright-report/
+```
+
+### Playwright MCP (playwright-mcp-config.json — fallback)
+```json
+{
+  "browser": {"browserName": "chromium", "launchOptions": {"headless": true}},
+  "contextOptions": {
+    "recordVideo": {"dir": "./videos", "size": {"width": 1920, "height": 1080}},
+    "viewport": {"width": 1920, "height": 1080}
+  }
+}
+```
+
+### MCP Server (.mcp.json — for MCP fallback mode)
+```json
+{
+  "playwright": {
+    "command": "npx",
+    "args": ["@playwright/mcp@latest", "--isolated", "--config", "./playwright-mcp-config.json"]
+  }
+}
+```
+
+## Outputs
+- Test run state: `.tmp/test_runs/{run_id}/state.json`
+- Summary report: `.tmp/test_runs/{run_id}/summary.md`
+- Execution log: `.tmp/test_runs/{run_id}/test_orchestrator/execution.log`
+- Screenshots: `.tmp/test_runs/{run_id}/screenshots/`
+- Videos: `.tmp/test_runs/playwright-artifacts/` (native) or `./videos/` (MCP)
+- Playwright JSON: `.tmp/test_runs/{run_id}/playwright-results.json`
+- Playwright HTML Report: `.tmp/test_runs/playwright-report/`
+- pytest XML: `{project_dir}/test-results.xml`
+- behave JSON: `{project_dir}/behave-results.json`
+- Audit trail entry
+
+## Edge Cases
+- No tests found: report "no tests" and PASS (testing framework works, project needs tests)
+- pytest not installed: skip unit tests with warning, continue to BDD/E2E
+- behave not installed: skip BDD tests with warning, continue to E2E
+- Playwright not installed: skip E2E with warning, continue to gates
+- Native tests exist but Playwright CLI missing: fall back to MCP mode
+- Health check fails: warn but continue (non-blocking)
+- All retries exhausted: report final state, exit with failure code
+- Claude Code not available: E2E runs in validation-only mode
+
+## Related Goals
+- `tdd_workflow.md` — TDD test generation (RED phase creates tests this goal runs)
+- `code_review.md` — Uses gate results for merge decisions
+- `security_scan.md` — Security tools invoked during security gate
+- `compliance_workflow.md` — Compliance tools invoked during compliance gate