icdev 0.0.3__py3-none-any.whl

goals/golden_path.md

@@ -0,0 +1,77 @@
+# CUI // SP-CTI
+
+# F9: Golden Path Scaffolder
+
+## Purpose
+
+Generate new project scaffolds from opinionated, compliance-ready templates ("golden paths"). Each template embeds security controls, CI/CD pipelines, NIST mappings, and coding standards so every new project starts compliant by default.
+
+## Prerequisites
+
+- `data/icdev.db` initialized with project tables
+- Template catalog populated (built-in templates available at first run)
+
+## Workflow Steps
+
+### 1. List Templates
+```bash
+python tools/scaffold/golden_path.py --list --json
+```
+**Expected output:** JSON array of available templates with name, description, language, framework, compliance level, and included controls.
+
+### 2. Scaffold Project
+```bash
+python tools/scaffold/golden_path.py --scaffold --template "python-fastapi-il4" --project-name "my-service" --output-dir /path/to/output --json
+```
+**Expected output:** JSON with generated file manifest, directory structure, applied controls, CI/CD pipeline path, and post-scaffold instructions.
+
+### 3. Validate Output
+```bash
+python tools/scaffold/golden_path.py --validate --project-dir /path/to/output --json
+```
+**Expected output:** JSON with validation results: file completeness check, control presence verification, CI/CD pipeline syntax check, and pass/fail status.
+
+### 4. Show Template Details
+```bash
+python tools/scaffold/golden_path.py --details --template "python-fastapi-il4" --json
+```
+**Expected output:** JSON with full template specification including file list, variable placeholders, embedded controls, and customization options.
+
+### 5. Register Custom Template
+```bash
+python tools/scaffold/golden_path.py --register --template-dir /path/to/custom-template --name "custom-flask-il2" --json
+```
+**Expected output:** JSON with registration status, template ID, and validation results.
+
+## Decision Reference
+
+| Decision | Description |
+|----------|-------------|
+| D-INV-33 | Templates use Jinja2 with string-replacement fallback -- air-gap safe |
+| D-INV-34 | Built-in templates: python-fastapi-il4, python-flask-il2, node-express-il2, rust-axum-il4 |
+| D-INV-35 | Compliance bootstrap embeds control stubs, CUI headers, and .gitignore for secrets |
+| D-INV-36 | Validation checks structural completeness -- does not compile or execute generated code |
+
+## Edge Cases
+
+- Unknown template name returns available templates list with suggestions
+- Output directory already exists returns error unless `--force` flag provided
+- Template with missing variables uses defaults and logs warnings
+- Validation of non-scaffolded project checks against closest matching template
+
+## Tier Gating
+
+| Capability | Community | Pro |
+|------------|-----------|-----|
+| List built-in templates | Yes | Yes |
+| Scaffold from built-in | Yes | Yes |
+| Validate output | Yes | Yes |
+| Register custom templates | No | Yes |
+| Compliance bootstrap (NIST controls) | No | Yes |
+
+## Security
+
+- Scaffold operations logged to audit trail
+- Generated projects include .gitignore excluding secrets and .env files
+- CUI markings applied to all generated source files at IL4+
+- No secrets or credentials embedded in templates -- placeholder references only

goals/harness_engineering.md

@@ -0,0 +1,91 @@
+# CUI // SP-CTI
+# Harness Engineering — AI Agent Orchestration Scaffolding
+
+## Purpose
+Ensure AI agents operate reliably through structured constraints, feedback loops,
+progress tracking, and self-correcting middleware. Harness engineering is the
+discipline of building the system around the model — not the model itself.
+
+## References
+- Anthropic: "Effective Harnesses for Long-Running Agents"
+- OpenAI: "Harness Engineering"
+- LangChain: "Improving Deep Agents with Harness Engineering"
+- Mitchell Hashimoto: Harness Engineering adoption path
+
+## Architecture Decisions
+- D-HARNESS-1: Loop state in .tmp/sessions/ JSON (ephemeral, not DB)
+- D-HARNESS-2: Loop detection is soft-signal only (stderr, exit 0)
+- D-HARNESS-3: Progress file is JSON (models handle structured data better)
+- D-HARNESS-4: Exit criteria in args/ YAML (GOTCHA separation)
+- D-HARNESS-5: Trace analyzer scanner-tier only (zero Claude tokens)
+- D-HARNESS-6: Maturity assessor read-only, advisory-only
+- D-HARNESS-7: Scaffolder generates 3 hooks (minimal), not all 7
+- D-HARNESS-8: One new append-only DB table (harness_trace_recommendations)
+
+## Maturity Levels
+| Level | Name | Description |
+|-------|------|-------------|
+| 0 | None | Raw model calls, no structure |
+| 1 | Initial | Fixed pipeline with stable prompts |
+| 2 | Managed | Token budgets, input/output validation |
+| 3 | Defined | Exit criteria the agent evaluates itself |
+| 4 | Optimized | Harness as infrastructure — versioned, monitored, rollback-able |
+
+## Components
+
+### 1. Loop Detection Middleware
+- **Where:** .claude/hooks/post_tool_use.py
+- **What:** Tracks (tool_name, file_path) edits per session
+- **Config:** args/harness_config.yaml → loop_detection block
+- **Behavior:** Warn at threshold (default 5), escalate at 2x (default 10)
+- **Output:** stderr warnings (soft signal, never blocks)
+
+### 2. Progress Tracking
+- **Where:** .claude/hooks/post_tool_use.py + stop.py
+- **What:** Appends significant events to .tmp/sessions/{session_id}/progress.json
+- **Tracks:** files_modified, files_created, tests_run/passed/failed, events
+- **Config:** args/harness_config.yaml → progress_tracking block
+
+### 3. Exit Criteria Registry
+- **Where:** args/exit_criteria.yaml
+- **What:** Machine-readable exit conditions per workflow type
+- **Workflows:** build, test, deploy, comply, secure, review
+- **Evaluator:** tools/harness/exit_criteria_evaluator.py
+
+### 4. Trace-Driven Improvement
+- **Where:** tools/harness/trace_analyzer.py
+- **What:** Analyzes hook_events for patterns, suggests improvements
+- **Detects:** Repetitive edits, long sessions, loop state triggers
+- **Stores:** harness_trace_recommendations table (append-only)
+
+### 5. Maturity Assessor
+- **Where:** tools/harness/maturity_assessor.py
+- **What:** Scores project 0-4 across 6 dimensions
+- **Dimensions:** hooks, gates, exit criteria, tracing, loop detection, progress
+- **Read-only:** Never modifies files
+
+### 6. Harness Scaffolder
+- **Where:** tools/harness/scaffold_harness.py
+- **What:** Generates baseline harness for child apps
+- **Output:** 3 hooks, harness_config.yaml, exit_criteria.yaml, security_gates.yaml
+- **Impact-level:** IL4+ gets stricter gates
+
+## Workflow
+
+1. **Assess** — Run maturity assessor on project: `python tools/harness/maturity_assessor.py --project-dir . --json`
+2. **Scaffold** — If missing, generate baseline: `python tools/harness/scaffold_harness.py --output-dir . --json`
+3. **Configure** — Tune args/harness_config.yaml thresholds for project needs
+4. **Monitor** — Loop detection + progress tracking run automatically via hooks
+5. **Analyze** — Periodically run trace analyzer: `python tools/harness/trace_analyzer.py --last-n 5 --json`
+6. **Evaluate** — Before declaring done, check exit criteria: `python tools/harness/exit_criteria_evaluator.py --workflow build --json`
+
+## Security Gate
+```yaml
+harness:
+  blocking:
+    - loop_detection_threshold_exceeded_critical
+  warning:
+    - loop_detection_escalation_triggered
+    - exit_criteria_not_defined
+    - harness_maturity_below_managed
+```

goals/integration_testing.md

@@ -0,0 +1,189 @@
+# Goal: Integration Testing (Phase 13)
+
+## Purpose
+Validate the complete SPARKPILOT 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
+- `/sparkpilot-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 | SPARKPILOT security tools | security_gates.yaml | Vulnerability assessment |
+| Compliance | SPARKPILOT 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

goals/knowledge_graph.md

@@ -0,0 +1,128 @@
+# CUI // SP-CTI
+# Knowledge Graph Engine — GOTCHA Goal
+
+## Purpose
+InfraNodus-style text network analysis integrated with ICDEV's RAG pipeline.
+Converts text from any source into interactive co-occurrence knowledge graphs,
+detects topic clusters, identifies structural gaps (blind spots), and generates
+AI-powered research questions to bridge disconnected concepts.
+
+## Architecture Decisions
+- D-KG-1: Pure Python stdlib + minimal deps (air-gap safe)
+- D-KG-2: SQL adjacency list storage (matches D27 pattern)
+- D-KG-3: Louvain community detection (deterministic, no LLM in critical path)
+- D-KG-4: 4-gram sliding window for co-occurrence (InfraNodus standard)
+- D-KG-5: Structural gap = high-distance cross-cluster node pairs
+- D-KG-6: stdlib urllib + html.parser for web scraping (air-gap safe)
+- D-KG-7: Pluggable source adapters (add new types without modifying core)
+- D-KG-8: GraphRAG enhances (not replaces) existing corrective_rag.py
+- D-KG-9: Query expansion via graph neighborhood traversal (BFS depth=2)
+- D-KG-10: Scoring = 0.4 * relevance + 0.3 * centrality + 0.3 * proximity
+- D-KG-11: Scanner-tier LLM routing (qwen3.5 local, zero Claude tokens)
+- D-KG-12: Deterministic gap detection first, LLM enrichment second
+- D-KG-13: All AI outputs are advisory-only (never modifies graph)
+- D-KG-14: Portable for child apps — no ICDEV-specific dependencies in core engine
+
+## Workflow
+
+### 1. Ingest Source
+- **Tool**: `tools/knowledge_graph/ingester.py`
+- **Sources**: text, file (TXT/MD/CSV/JSON/code), URL, YouTube, database, code directory
+- **Output**: Extracted text string
+
+### 2. Build Text Network
+- **Tool**: `tools/knowledge_graph/text_network.py`
+- **Steps**:
+  1. Tokenize (lowercase, stop removal, rule-based lemmatization)
+  2. Build co-occurrence graph (4-gram sliding window)
+  3. Compute betweenness centrality (Brandes algorithm, O(VE))
+  4. Detect communities (Louvain modularity optimization)
+  5. Find structural gaps (cross-cluster edge density analysis)
+- **Output**: Nodes + edges + communities + gaps + stats
+
+### 3. Persist to Database
+- **Tables**: `kg_graphs`, `kg_nodes`, `kg_edges`, `kg_gaps`, `kg_ingestions`
+- **Pattern**: SQL adjacency list (matches D27)
+- **Incremental**: `append_to_graph()` merges new text into existing graphs
+
+### 4. GraphRAG Retrieval
+- **Tool**: `tools/knowledge_graph/graph_rag.py`
+- **Steps**:
+  1. Tokenize query → seed nodes
+  2. Match to graph nodes (exact + partial)
+  3. BFS neighborhood expansion (depth=2)
+  4. Score: 0.4 * relevance + 0.3 * centrality + 0.3 * proximity
+  5. Include community context + structural gap context
+- **Integration**: Enriches existing corrective_rag.py, doesn't replace it
+
+### 5. AI Insight Generation
+- **Tool**: `tools/knowledge_graph/insight_generator.py`
+- **Capabilities**:
+  - Research question generation (template-based + LLM)
+  - Community summarization (label + description)
+  - Deep gap analysis (bridge candidates + narrative)
+  - Layer peeling (remove top nodes → reveal hidden concepts)
+- **LLM Tier**: Scanner (qwen3.5 local, zero Claude tokens)
+
+### 6. Visualization
+- **Dashboard**: `/knowledge-graph` route
+- **Features**:
+  - Force Atlas / Circular / Grid layouts
+  - Node sizing by centrality / degree / occurrences
+  - Community color coding (12-color palette)
+  - Interactive: drag, pan, zoom, hover tooltips
+  - Structural gap display panel
+  - GraphRAG chat panel (queries codebase/infrastructure/frameworks)
+
+## Edge Cases
+- Empty or very short text → return error with token count
+- Single-word text → insufficient for co-occurrence → error
+- Very large text (>100K tokens) → cap at max_nodes/max_edges config
+- No captions on YouTube video → graceful error message
+- Database source with empty table → error with row count
+- LLM unavailable → deterministic-only mode (all features work without LLM)
+
+## Portability (Child Apps)
+- Core engine (`text_network.py`) has zero ICDEV-specific imports
+- Ingester sources are pluggable — child apps register their own
+- Dashboard template extends `base.html` (works with any Flask app)
+- Database tables are self-contained (no FK to other ICDEV tables)
+- Config in `args/knowledge_graph_config.yaml` (GOTCHA args layer)
+- RAG source registry entries are additive (child apps can add more)
+
+## Testing
+- Unit tests: tokenization, co-occurrence, centrality, Louvain, gap detection
+- Integration: full pipeline from text → graph → query → insights
+- E2E: dashboard loads, analyze text, view graph, use chat
+- Edge cases: empty text, unicode, very large input, missing LLM
+
+## CLI Commands
+```bash
+# Analyze text
+python tools/knowledge_graph/text_network.py --text "your text" --save --json
+
+# Ingest from URL
+python tools/knowledge_graph/ingester.py --url "https://example.com" --name "Article" --json
+
+# Ingest from YouTube
+python tools/knowledge_graph/ingester.py --youtube "https://youtube.com/watch?v=xxx" --json
+
+# Ingest from ICDEV database
+python tools/knowledge_graph/ingester.py --db-source compliance_controls --json
+
+# Ingest codebase
+python tools/knowledge_graph/ingester.py --code-dir tools/ --name "ICDEV Codebase" --json
+
+# Append to existing graph
+python tools/knowledge_graph/ingester.py --text "more text" --graph-id <id> --json
+
+# GraphRAG query
+python tools/knowledge_graph/graph_rag.py --query "zero trust architecture" --json
+
+# AI insights
+python tools/knowledge_graph/insight_generator.py --graph-id <id> --questions --json
+python tools/knowledge_graph/insight_generator.py --graph-id <id> --layer-peel --json
+
+# List saved graphs
+python tools/knowledge_graph/text_network.py --list --json
+```

goals/maintenance_audit.md

@@ -0,0 +1,196 @@
+# Goal: Maintenance Audit Workflow
+
+## Description
+Continuously assess and remediate project dependencies to maintain security, compliance, and governance posture. This workflow detects outdated dependencies, checks for known vulnerabilities, enforces remediation SLAs, and auto-implements fixes.
+
+**Standards:**
+- NIST 800-53 SI-2 (Flaw Remediation)
+- NIST 800-53 SA-22 (Unsupported System Components)
+- NIST 800-53 CM-3 (Configuration Change Control)
+- CISA SbD Commitment 4 (Security Patches)
+
+**Why this matters:** Outdated dependencies are the #1 attack vector. This workflow ensures continuous compliance and reduces exposure window through automated detection and remediation with SLA enforcement.
+
+---
+
+## Prerequisites
+- [ ] Project initialized (`goals/init_project.md` completed)
+- [ ] Project has dependency files (requirements.txt, package.json, pom.xml, go.mod, Cargo.toml, *.csproj)
+- [ ] SBOM generated (`goals/compliance_workflow.md`)
+- [ ] Security scans completed (`goals/security_scan.md`)
+
+---
+
+## Process
+
+### Step 1: Scan Dependencies
+**Tool:** `python tools/maintenance/dependency_scanner.py --project-id <id>`
+
+Inventories all dependencies across detected languages. Checks package registries for latest versions. Calculates staleness (days behind latest).
+
+**Outputs:**
+- Dependency inventory stored in `project_dependencies` table
+- Per-language summary (total deps, outdated count, avg staleness)
+- Staleness flags: current (0d), minor (1-30d), moderate (31-90d), major (91-180d), critical (>180d)
+
+**Air-gapped mode:** Use `--offline` flag. Dependencies inventoried from manifest files but latest versions unknown. Staleness set to -1 (unknown).
+
+### Step 2: Check Vulnerabilities
+**Tool:** `python tools/maintenance/vulnerability_checker.py --project-id <id>`
+
+Runs language-native audit tools (pip-audit, npm audit, cargo-audit, etc.). Maps findings to SLA deadlines. Stores in `dependency_vulnerabilities` table.
+
+**SLA Mapping:**
+| Severity | Deadline | Auto-remediate |
+|----------|----------|---------------|
+| Critical | 48 hours | No (manual approval) |
+| High | 7 days | No (manual approval) |
+| Medium | 30 days | Yes |
+| Low | 90 days | Yes |
+
+**Outputs:**
+- Vulnerability records with CVE IDs, CVSS scores, affected versions
+- SLA deadline assignments based on severity
+- Fix availability status (fix_available, no_fix, workaround)
+
+### Step 3: Run Maintenance Audit
+**Tool:** `python tools/maintenance/maintenance_auditor.py --project-id <id>`
+
+Orchestrates full audit: scoring, SLA compliance, trend analysis, CUI-marked report generation.
+
+**Scoring Formula:**
+```
+Start at 100 points
+- Each overdue critical SLA: -20 points
+- Each overdue high SLA: -10 points
+- Each overdue medium SLA: -5 points
+- Each overdue low SLA: -2 points
+- Each critical staleness dep (>180d): -3 points
+- Each major staleness dep (91-180d): -1 point
+Floor at 0, cap at 100
+```
+
+**Gate Evaluation:**
+- Score >= 80: PASS (healthy)
+- Score 50-79: WARN (at_risk, non-blocking)
+- Score < 50: FAIL (critical, blocks deployment)
+
+**Outputs:**
+- Maintenance score (0-100)
+- SLA compliance percentage
+- Trend analysis (vs. previous audit)
+- CUI-marked markdown report at `reports/<project>/maintenance_audit_YYYY-MM-DD.md`
+
+### Step 4: Remediate
+**Tool:** `python tools/maintenance/remediation_engine.py --project-id <id> --auto`
+
+Auto-updates dependency files, creates remediation branches, runs tests, tracks actions.
+
+**Auto-remediation rules:**
+- Medium and low severity: auto-fixed (bump to patched version)
+- Critical and high severity: generate fix plan, require manual approval
+- Dry-run mode: preview all changes without applying
+
+**Process:**
+1. Identify eligible vulnerabilities (medium/low with fix_available)
+2. Generate updated dependency file (requirements.txt, package.json, etc.)
+3. Create git branch `remediate/<project-id>/<date>`
+4. Run test suite to verify no breakage
+5. If tests pass: commit changes, record action
+6. If tests fail: rollback, flag for manual review
+
+**Outputs:**
+- Remediation action records (what changed, test results, branch name)
+- Updated dependency files (if not dry-run)
+- Rollback log for any failed remediations
+
+### Step 5: Verify
+Re-run security scan and test suite to confirm fixes don't break anything.
+
+**Tool:** `python tools/security/dependency_auditor.py --project-dir <path>`
+
+Verify:
+- [ ] No new vulnerabilities introduced
+- [ ] All tests still pass
+- [ ] SBOM updated to reflect new versions
+
+### Step 6: Log to Audit Trail
+**Tool:** `python tools/audit/audit_logger.py --event-type "maintenance.audit" --actor "maintenance-agent" --action "Maintenance audit complete" --project-id <id>`
+
+Record:
+- Audit timestamp and score
+- Vulnerabilities found and remediated
+- SLA compliance status
+- Gate evaluation result
+
+---
+
+## Success Criteria
+- [ ] All dependencies inventoried across all detected languages
+- [ ] Vulnerability check completed against advisory databases
+- [ ] Maintenance score computed (target: >= 70)
+- [ ] SLA deadlines set for all open vulnerabilities
+- [ ] No overdue critical or high SLAs
+- [ ] Remediation actions tracked for all fixes
+- [ ] CUI-marked audit report generated
+- [ ] Audit trail entries logged
+
+---
+
+## Schedule
+- **On every build:** Quick dependency scan (cached versions)
+- **Weekly:** Full maintenance audit with registry checks
+- **On new CVE disclosure:** Immediate vulnerability check
+- **Before deployment:** Gate evaluation (blocking if score < 50)
+
+---
+
+## SLA Thresholds
+| Severity | Deadline | Auto-remediate | Escalation |
+|----------|----------|---------------|------------|
+| Critical | 48 hours | No (manual) | Immediate notification to security team |
+| High | 7 days | No (manual) | Daily reminder after day 3 |
+| Medium | 30 days | Yes | Weekly summary |
+| Low | 90 days | Yes | Monthly summary |
+
+---
+
+## Edge Cases & Notes
+1. **Air-gapped environments:** Use --offline flag. Dependencies inventoried but latest versions unknown. Staleness set to -1. Vulnerability checks use local advisory database snapshot.
+2. **Transitive dependencies:** SBOM includes transitives but scanner focuses on direct deps. Transitive vuln fixes require updating the direct dep that pulls them in.
+3. **Version pinning:** Some projects intentionally pin old versions. Use `risk_accept` status in `dependency_vulnerabilities` to document accepted risk with justification.
+4. **Multi-language projects:** Scanner detects all languages automatically. Each gets its own audit tool chain (pip-audit for Python, npm audit for Node.js, cargo-audit for Rust, etc.).
+5. **Feeds SbD:** Maintenance audit results feed SbD-05 (patch cadence) and SbD-22 (vulnerability scanning) assessments.
+6. **Remediation conflicts:** If two vulnerabilities require conflicting version bumps, flag for manual resolution and document in POAM.
+7. **EOL dependencies:** Dependencies with no maintainer activity >1 year flagged as unsupported per NIST SA-22. Recommend replacement.
+
+---
+
+## GOTCHA Layer Mapping
+| Step | GOTCHA Layer | Component |
+|------|-------------|-----------|
+| Dependency scan | Tools | dependency_scanner.py |
+| Vulnerability check | Tools | vulnerability_checker.py |
+| Maintenance audit | Tools | maintenance_auditor.py |
+| Remediation | Tools | remediation_engine.py |
+| Sequence decisions | Orchestration | AI (you) |
+| SLA thresholds | Args | maintenance_config.yaml |
+| Gate thresholds | Args | security_gates.yaml |
+| Assessment template | Hard Prompts | maintenance_assessment.md |
+| NIST standards | Context | NIST 800-53 SI-2, SA-22, CM-3 |
+
+---
+
+## Related Files
+- **Tools:** `tools/maintenance/dependency_scanner.py`, `tools/maintenance/vulnerability_checker.py`, `tools/maintenance/maintenance_auditor.py`, `tools/maintenance/remediation_engine.py`
+- **MCP Server:** `tools/mcp/maintenance_server.py`
+- **Skill:** `.claude/skills/sparkpilot-maintain/SKILL.md`
+- **Hard Prompt:** `hardprompts/maintenance/maintenance_assessment.md`
+- **Args:** `args/maintenance_config.yaml`, `args/security_gates.yaml`
+- **Feeds from:** `goals/security_scan.md` (SAST/dep findings), `goals/compliance_workflow.md` (SBOM)
+- **Feeds into:** `goals/sbd_ivv_workflow.md` (SbD-05, SbD-22), `goals/deploy_workflow.md` (deployment gate)
+
+---
+
+## Changelog
+- 2026-02-15: Initial creation (Phase 16H)