icdev 0.0.3__py3-none-any.whl

goals/ato_simulator.md

@@ -0,0 +1,78 @@
+# CUI // SP-CTI
+
+# F11: Monte Carlo ATO Simulator
+
+## Purpose
+
+Simulate ATO (Authority to Operate) timelines using Monte Carlo methods. Build task dependency graphs with probabilistic duration estimates, run thousands of iterations to produce confidence intervals, and identify schedule risk drivers.
+
+## Prerequisites
+
+- `data/icdev.db` initialized with project and compliance tables
+- ATO task definitions (or use built-in FedRAMP Moderate template)
+- Python stdlib `random` module (no external dependencies)
+
+## Workflow Steps
+
+### 1. Build Task Graph
+```bash
+python tools/simulation/ato_simulator.py --build-tasks --project-id "sparkpilot" --template fedramp-moderate --json
+```
+**Expected output:** JSON with task list including task ID, name, dependencies, optimistic/likely/pessimistic duration estimates (days), and critical path flag.
+
+### 2. Simulate Timeline
+```bash
+python tools/simulation/ato_simulator.py --simulate --project-id "sparkpilot" --iterations 1000 --json
+```
+**Expected output:** JSON with simulation results: P10/P25/P50/P75/P90 completion dates, mean duration, standard deviation, and iteration count.
+
+### 3. Review Percentiles
+```bash
+python tools/simulation/ato_simulator.py --percentiles --project-id "sparkpilot" --json
+```
+**Expected output:** JSON with percentile table (P5 through P95 in 5-point increments), each with calendar date and total business days.
+
+### 4. Identify Risk Drivers
+```bash
+python tools/simulation/ato_simulator.py --risk-drivers --project-id "sparkpilot" --json
+```
+**Expected output:** JSON array of tasks ranked by schedule sensitivity (correlation of task duration to total timeline), with risk category (HIGH/MEDIUM/LOW).
+
+### 5. Compare Scenarios
+```bash
+python tools/simulation/ato_simulator.py --compare --project-id "sparkpilot" --scenario-a "baseline" --scenario-b "parallel-stig" --json
+```
+**Expected output:** JSON comparing P50 and P90 dates between scenarios, delta in business days, and recommendation.
+
+## Decision Reference
+
+| Decision | Description |
+|----------|-------------|
+| D-INV-41 | PERT distribution for task durations: (optimistic + 4*likely + pessimistic) / 6 |
+| D-INV-42 | Critical path computed via topological sort with longest path algorithm |
+| D-INV-43 | Sensitivity analysis uses Spearman rank correlation per task vs total duration |
+| D-INV-44 | Python stdlib random only -- no numpy required, air-gap safe |
+
+## Edge Cases
+
+- Circular dependency in task graph returns error with cycle path
+- Single task returns deterministic result (no simulation needed)
+- Zero iterations defaults to 1000
+- Task with optimistic > pessimistic returns validation error
+
+## Tier Gating
+
+| Capability | Community | Pro |
+|------------|-----------|-----|
+| Build task graph | Yes | Yes |
+| Simulate timeline | 1000 max iterations | 10000+ iterations |
+| Percentile review | P25/P50/P75 only | Full P5-P95 |
+| Risk driver analysis | Yes | Yes |
+| Custom task parameters | No | Yes |
+
+## Security
+
+- Simulation results are append-only (NIST AU compliant)
+- Task graphs scoped to project -- no cross-project access
+- CUI markings applied to exported simulation reports
+- Random seed logged for reproducibility

goals/audit_engine.md

@@ -0,0 +1,177 @@
+# Goal: Audit Engine — Unified Compliance Report Card
+
+## Description
+
+The Audit Engine provides a unified compliance report card for ICDEV, modules, child apps, and bring-your-own-software (BYOS). It scans targets against all supported compliance frameworks, generates per-regime scores with side-by-side gap analysis, and provides AI-powered recommendations for score improvement.
+
+### Key Capabilities
+
+1. **Multi-regime scoring** — Scan once, score against all 8 frameworks (NIST 800-53, 800-171, FedRAMP, CMMC, CISA SbD, DoD CSSP, IEEE 1012, DoDI 5000.87)
+2. **Side-by-side comparison** — "I'm 800-171 compliant — what do I need for 800-53?"
+3. **AI-powered recommendations** — Dual-ranked by impact (biggest score boost) and effort (easiest to implement)
+4. **BYOS scanning** — Audit any codebase via directory path or git URL (SSH + HTTPS)
+5. **Pluggable regimes** — Drop JSON files into `args/audit_regimes/` for custom frameworks
+6. **Eject-ready** — Package as standalone application via eject scaffold
+
+---
+
+## Pipeline: SCAN → EVALUATE → SCORE → ADVISE → REPORT
+
+### Phase 1: SCAN — Collect Evidence
+
+#### Tools Used
+- `tools/audit_engine/scanner.py` — Orchestrates all scanners
+- `tools/security/sast_runner.py` — SAST analysis (fallback: builtin patterns)
+- `tools/security/secret_detector.py` — Secret detection (fallback: regex patterns)
+- `tools/security/dependency_auditor.py` — Dependency vulnerability audit
+- `tools/compliance/stig_checker.py` — STIG compliance (ICDEV/child apps only)
+- `tools/compliance/sbom_generator.py` — SBOM generation
+- `tools/compliance/sbd_assessor.py` — Secure by Design assessment
+
+#### Pre-conditions
+- Target path exists (directory or valid git URL)
+- For git URLs: auth credentials available (SSH key or HTTPS token)
+
+#### Implementation Steps
+1. Determine target type (auto-detect or explicit)
+2. If git URL: clone via `git_fetcher.py`
+3. Run applicable scanners based on target type
+4. Normalize findings into `AuditEvidence` format
+5. Aggregate into scan result
+
+#### Post-conditions
+- Scan result dict with evidence from all sources
+- No modification to target files
+
+---
+
+### Phase 2: EVALUATE — Map Evidence to Controls
+
+#### Tools Used
+- `tools/audit_engine/engine.py` — Core evaluation logic
+- `tools/audit_engine/regime_loader.py` — Load regime definitions
+
+#### Implementation Steps
+1. Load regime definition(s) from `args/audit_regimes/`
+2. For each control in regime:
+   a. Check explicit evidence sources from regime YAML/JSON
+   b. Fall back to NIST control-family heuristic mapping
+   c. Determine status: pass / partial / fail / not_applicable / not_assessed
+3. Compute per-category scores
+
+#### Scoring Formula
+```
+category_score = (passed + 0.5 * partial) / (total - not_applicable) * 100
+overall_score = weighted average across categories
+```
+
+---
+
+### Phase 3: SCORE — Generate Report Card
+
+#### Tools Used
+- `tools/audit_engine/report_card.py` — Format output
+- `tools/audit_engine/engine.py` — Store results
+
+#### Implementation Steps
+1. Compute letter grade from score (A+ ≥ 95, A ≥ 90, ... F < 50)
+2. Generate report card with per-regime cards
+3. Store results in `audit_engine_results` and `audit_engine_scores` tables
+4. Log audit event to `audit_trail` (append-only, D6)
+
+---
+
+### Phase 4: ADVISE — AI Recommendations
+
+#### Tools Used
+- `tools/audit_engine/ai_advisor.py` — Recommendation engine
+
+#### Implementation Steps
+1. Identify failing/partial controls across all regimes
+2. Deduplicate (same NIST control across multiple regimes = one recommendation)
+3. Map to recommendation catalog (deterministic, scanner tier)
+4. Calculate impact score (severity × status weight)
+5. Calculate effort score (config change = 1, architecture = 7)
+6. Compute ROI = impact / effort
+7. Optionally enhance with LLM (worker tier) for top 5 by impact
+8. Return three ranked lists: by_impact, by_effort, by_roi + quick_wins
+
+---
+
+### Phase 5: REPORT — Output and Compare
+
+#### Tools Used
+- `tools/audit_engine/comparator.py` — Side-by-side comparison
+- `tools/audit_engine/report_card.py` — Format output
+
+#### Implementation Steps
+1. If comparison requested: build crosswalk map between regimes
+2. Identify shared, baseline-only, and target-only controls
+3. Compute gap analysis (failing controls unique to target)
+4. Generate human-readable recommendation summary
+5. Output in selected format (JSON, Markdown, terminal)
+
+---
+
+## CLI Commands
+
+```bash
+# Full audit scan
+python tools/audit_engine/cli.py scan --json
+python tools/audit_engine/cli.py scan --target /path --type byos --json
+python tools/audit_engine/cli.py scan --target https://github.com/org/repo.git --type byos --auth token --token ghp_xxx --json
+python tools/audit_engine/cli.py scan --target git@github.com:org/repo.git --type byos --auth ssh --json
+
+# Compare regimes
+python tools/audit_engine/cli.py compare --baseline nist_800_171 --target nist_800_53 --json
+
+# AI recommendations
+python tools/audit_engine/cli.py advise --regime nist_800_53 --json
+
+# Regime management
+python tools/audit_engine/cli.py regimes --json
+python tools/audit_engine/cli.py regime-import --file /path/to/regime.json --json
+python tools/audit_engine/cli.py regime-export --output /path/to/export --json
+
+# Score trend
+python tools/audit_engine/cli.py trend --regime nist_800_53 --json
+```
+
+## Dashboard
+
+- Route: `/audit-engine`
+- API: `/api/audit-engine/run`, `/api/audit-engine/compare`, `/api/audit-engine/advise`, `/api/audit-engine/regimes`, `/api/audit-engine/trend`
+
+## Database Tables
+
+| Table | Purpose |
+|-------|---------|
+| `audit_engine_results` | Full audit results (append-only) |
+| `audit_engine_scores` | Per-regime scores per audit run |
+
+## Architecture Decisions
+
+- **D-AE-1:** Audit engine is core module (`tools/audit_engine/`) with eject capability
+- **D-AE-2:** Regime definitions are JSON files in `args/audit_regimes/` (pluggable)
+- **D-AE-3:** Scoring formula: `(passed + 0.5 * partial) / (total - not_applicable) * 100`
+- **D-AE-4:** AI advisor uses scanner tier (deterministic) + optional worker tier (LLM)
+- **D-AE-5:** BYOS supports both SSH and HTTPS token auth for private repos
+- **D-AE-6:** Cloned repos go to `.tmp/audit_clones/` and are cleaned up after scan
+- **D-AE-7:** All 8 existing compliance frameworks shipped as built-in regime definitions
+- **D-AE-8:** Regime updater uses SHA-256 content hash for tamper detection (D-INV-5 pattern)
+- **D-AE-9:** Results are append-only in DB (NIST AU compliance, D6)
+
+## Error Handling
+
+- Scanner failures: isolated per-scanner, don't block other scanners
+- Git clone failures: return error with sanitized message (no token leakage)
+- Regime not found: skip with error in report card
+- LLM unavailable: fall back to deterministic recommendations
+- DB unavailable: scan still runs, results not persisted
+
+## Guardrails
+
+- Never modify target files during scan (read-only)
+- Never expose auth tokens in output or logs
+- Audit trail is append-only (no UPDATE/DELETE)
+- CUI markings on all generated artifacts

goals/bite_sized_plans.md

@@ -0,0 +1,225 @@
+# Goal: Bite-Sized Implementation Plans
+
+## Description
+
+Break implementation work into bite-sized tasks (2-5 minutes each) with exact file paths, exact code, exact test commands, and exact expected output. Plans are written assuming the implementer has zero codebase context.
+
+**Adapted from:** [obra/superpowers](https://github.com/obra/superpowers) writing-plans skill.
+
+**The principle:** Write plans clear enough for "an enthusiastic junior engineer with no project context" to follow. Every step is one action. DRY. YAGNI. TDD. Frequent commits.
+
+---
+
+## When to Use
+
+- After a design is approved (`goals/brainstorming_gate.md`)
+- Before any multi-step implementation (3+ files to create/modify)
+- When dispatching work to subagents
+- When breaking a phase into tasks
+
+**Exceptions:**
+- Single-file bug fixes (use `goals/systematic_debugging.md`)
+- Trivial changes the user wants done immediately
+
+---
+
+## Prerequisites
+
+- [ ] Design approved (or user directive clear)
+- [ ] Relevant source files read and understood
+- [ ] Test framework available (pytest, behave)
+
+---
+
+## Process
+
+### Step 1: Write the Plan Header
+
+Every plan MUST start with:
+
+```markdown
+# [Feature Name] Implementation Plan
+
+**Goal:** [One sentence describing what this builds]
+**Architecture:** [2-3 sentences about approach]
+**Key Files:** [List critical existing files to reference]
+
+---
+```
+
+### Step 2: Break Into Bite-Sized Tasks
+
+**Each task is one action (2-5 minutes):**
+
+| Good (one action) | Bad (multiple actions) |
+|---|---|
+| "Write the failing test" | "Write tests and implement the feature" |
+| "Run it to make sure it fails" | "Make it all work" |
+| "Implement the minimal code to pass" | "Add the module with tests" |
+| "Run tests and verify they pass" | "Finish the feature" |
+| "Commit" | "Clean up and commit everything" |
+
+### Step 3: Task Structure
+
+Each task follows this template:
+
+````markdown
+### Task N: [Component Name]
+
+**Files:**
+- Create: `exact/path/to/file.py`
+- Modify: `exact/path/to/existing.py` (lines ~120-145)
+- Test: `tests/exact/path/to/test_file.py`
+
+**Step 1: Write the failing test**
+
+```python
+def test_specific_behavior():
+    """Exact test code — copy-paste ready."""
+    result = function_under_test(input_value)
+    assert result == expected_value
+```
+
+**Step 2: Run test to verify it fails**
+
+```bash
+python -m pytest tests/path/test_file.py::test_specific_behavior -v
+```
+Expected: FAIL with "function_under_test not defined" or similar
+
+**Step 3: Write minimal implementation**
+
+```python
+def function_under_test(input_value):
+    """Exact implementation code — copy-paste ready."""
+    return expected_value
+```
+
+**Step 4: Run test to verify it passes**
+
+```bash
+python -m pytest tests/path/test_file.py::test_specific_behavior -v
+```
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add tests/path/test_file.py src/path/file.py
+git commit -m "feat: add specific feature"
+```
+````
+
+### Step 4: Plan Completeness Checklist
+
+Before finalizing the plan, verify:
+
+- [ ] Every task has exact file paths (no "the config file")
+- [ ] Every task has complete code (no "add validation logic here")
+- [ ] Every task has exact commands with expected output
+- [ ] Every task follows TDD: test first → fail → implement → pass → commit
+- [ ] Tasks are ordered by dependency (no forward references)
+- [ ] Each task is independently verifiable (can confirm it worked)
+
+### Step 5: Save the Plan
+
+```
+docs/plans/YYYY-MM-DD-<feature-name>-plan.md
+```
+
+### Step 6: Execution Handoff
+
+After saving, offer execution choice:
+
+**Option 1: Direct execution** — Execute tasks sequentially in this session, checkpointing every 3 tasks.
+
+**Option 2: Subagent-driven** — Dispatch fresh subagent per task with two-stage review (`goals/subagent_review.md`).
+
+**Option 3: Parallel agents** — If tasks are independent, dispatch multiple agents concurrently (`dispatching-parallel-agents` pattern).
+
+---
+
+## Example: Adding a New API Endpoint
+
+````markdown
+# Widget Counter Implementation Plan
+
+**Goal:** Add a GET /api/widgets/count endpoint that returns widget count per tenant.
+**Architecture:** New route in app.py, new function in widget_manager.py, DB query.
+**Key Files:** `tools/dashboard/app.py`, `tools/widgets/widget_manager.py`
+
+---
+
+### Task 1: Write failing test for count function
+
+**Files:**
+- Create: `tests/test_widget_manager.py`
+
+**Step 1: Write test**
+```python
+from tools.widgets.widget_manager import get_widget_count
+
+def test_get_widget_count_empty():
+    result = get_widget_count(tenant_id="test-tenant")
+    assert result == {"count": 0, "tenant_id": "test-tenant"}
+```
+
+**Step 2: Run — expect FAIL**
+```bash
+python -m pytest tests/test_widget_manager.py::test_get_widget_count_empty -v
+```
+
+### Task 2: Implement minimal count function
+
+**Files:**
+- Modify: `tools/widgets/widget_manager.py`
+
+**Step 1: Add function**
+```python
+def get_widget_count(tenant_id: str) -> dict:
+    from tools.db.storage import get_connection
+    with get_connection() as conn:
+        row = conn.execute(
+            "SELECT COUNT(*) as cnt FROM widgets WHERE tenant_id = ?",
+            (tenant_id,)
+        ).fetchone()
+        count = row[0] if row else 0
+    return {"count": count, "tenant_id": tenant_id}
+```
+
+**Step 2: Run — expect PASS**
+```bash
+python -m pytest tests/test_widget_manager.py::test_get_widget_count_empty -v
+```
+
+**Step 3: Commit**
+```bash
+git add tools/widgets/widget_manager.py tests/test_widget_manager.py
+git commit -m "feat: add get_widget_count function"
+```
+````
+
+---
+
+## Integration with GOTCHA
+
+| Layer | Role |
+|-------|------|
+| **Goals** | This goal defines plan format |
+| **Orchestration** | You write the plan, then execute or delegate |
+| **Tools** | Plans reference exact tool paths and commands |
+| **Args** | Plans may reference config in `args/` |
+| **Context** | Plans are informed by existing codebase |
+| **Hard Prompts** | The plan itself becomes a hard prompt for subagents |
+
+---
+
+## Key Principles
+
+- **Exact file paths always** — never "the config file" or "the test file"
+- **Complete code in plan** — never "add validation" or "implement logic"
+- **Exact commands with expected output** — never "run the tests"
+- **DRY** — don't repeat yourself across tasks
+- **YAGNI** — don't plan features not requested
+- **TDD** — every task starts with a failing test
+- **Frequent commits** — commit after each task or logical group

goals/boundary_supply_chain.md

@@ -0,0 +1,206 @@
+# Goal: ATO Boundary Impact & Supply Chain Intelligence (RICOAS Phase 2)
+
+## Purpose
+
+Assess requirement impact on existing ATO boundaries (4-tier GREEN/YELLOW/ORANGE/RED), manage supply chain risk per NIST 800-161, track ISA/MOU lifecycle, triage CVEs with upstream/downstream blast radius analysis, and generate alternative COAs for ATO-invalidating requirements.
+
+## When to Use
+
+- New requirements need boundary impact assessment against existing ATO systems
+- RED-tier requirements need alternative COAs
+- Supply chain dependency graph needs building or querying
+- CVE triage with blast radius analysis needed
+- ISA/MOU lifecycle review (expiring, overdue review)
+- NIST 800-161 SCRM vendor assessment needed
+- Section 889 prohibited vendor check needed
+
+## Workflow
+
+### ATO Boundary Impact Analysis
+
+1. Register existing ATO systems: `register_ato_system` (MCP) or `boundary_analyzer.py --register-system`
+2. Assess each requirement: `assess_boundary_impact` (MCP) — returns GREEN/YELLOW/ORANGE/RED tier
+3. For RED-tier: `generate_red_alternative` (MCP) — generates 3-5 alternative approaches within existing ATO
+4. List all assessments: filter by tier to find items requiring attention
+
+### Boundary Impact Tiers
+
+| Tier | Score | ATO Impact | Action |
+|------|-------|------------|--------|
+| GREEN | 0-25 | None | Proceed |
+| YELLOW | 26-50 | SSP addendum, possible POAM | ISSO notification |
+| ORANGE | 51-75 | SSP revision, ISSO review | Security assessment, ISA review |
+| RED | 76-100 | ATO-invalidating | **FULL STOP.** Generate alternative COAs |
+
+### Boundary Impact Decision Flowchart
+
+```mermaid
+flowchart TD
+    A["New Requirement"] --> B["Assess Boundary Impact"]
+    B --> C{Impact Score?}
+    C -->|"0-25"| D["GREEN: No ATO Impact"]
+    C -->|"26-50"| E["YELLOW: SSP Addendum"]
+    C -->|"51-75"| F["ORANGE: SSP Revision + ISSO Review"]
+    C -->|"76-100"| G["RED: ATO-Invalidating"]
+    D --> H["Proceed to Build"]
+    E --> I["ISSO Notification"] --> H
+    F --> J["Security Assessment"] --> H
+    G --> K["FULL STOP: Generate Alternative COAs"]
+    K --> L["Customer Selects Alternative"]
+    L --> M{Alternative Viable?}
+    M -->|"Yes"| D
+    M -->|"No"| N["Re-authorization Required"]
+
+    style A fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+    style B fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+    style C fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+    style D fill:#1a3a2d,stroke:#28a745,color:#e0e0e0
+    style E fill:#3a3a1a,stroke:#ffc107,color:#e0e0e0
+    style F fill:#3a2a1a,stroke:#e8590c,color:#e0e0e0
+    style G fill:#3a1a1a,stroke:#dc3545,color:#e0e0e0
+    style H fill:#1a3a2d,stroke:#28a745,color:#e0e0e0
+    style I fill:#3a3a1a,stroke:#ffc107,color:#e0e0e0
+    style J fill:#3a2a1a,stroke:#e8590c,color:#e0e0e0
+    style K fill:#3a1a1a,stroke:#dc3545,color:#e0e0e0
+    style L fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+    style M fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+    style N fill:#3a1a1a,stroke:#dc3545,color:#e0e0e0
+```
+
+### ISA Lifecycle State Diagram
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Active : Signed by both parties
+    Active --> ReviewDue : Review period reached
+    ReviewDue --> Active : Review completed, no changes
+    ReviewDue --> Expiring : Approaching expiration
+    Active --> Expiring : Within 90 days of expiration
+    Expiring --> Renewed : Renewal approved
+    Expiring --> Expired : Expiration date passed
+    Renewed --> Active : New term begins
+    Expired --> [*]
+    Active --> Terminated : Early termination
+    ReviewDue --> Terminated : Review failed
+    Terminated --> [*]
+
+    classDef green fill:#1a3a2d,stroke:#28a745,color:#e0e0e0
+    classDef yellow fill:#3a3a1a,stroke:#ffc107,color:#e0e0e0
+    classDef orange fill:#3a2a1a,stroke:#e8590c,color:#e0e0e0
+    classDef red fill:#3a1a1a,stroke:#dc3545,color:#e0e0e0
+    classDef blue fill:#1a3a5c,stroke:#4a90d9,color:#e0e0e0
+
+    class Draft blue
+    class Active green
+    class ReviewDue yellow
+    class Expiring orange
+    class Renewed green
+    class Expired red
+    class Terminated red
+```
+
+### Supply Chain Dependency Tracking
+
+1. Register vendors: `add_vendor` (MCP) — include country, SCRM tier, Section 889 status
+2. Add dependencies: via `dependency_graph.py --add-dep`
+3. Build graph: `build_dependency_graph` (MCP) — adjacency list with stats
+4. Impact analysis: `propagate_impact` (MCP) — trace downstream blast radius with severity decay
+
+### ISA/MOU Lifecycle
+
+1. Create ISA: `manage_isa` with action=create
+2. Check expiring: `manage_isa` with action=expiring (default 90 days ahead)
+3. Review due: `manage_isa` with action=review_due
+
+### SCRM Assessment (NIST 800-161)
+
+1. Vendor assessment: `assess_scrm` with vendor_id — scores 6 dimensions
+2. Project aggregate: `assess_scrm` with aggregate=true — risk distribution across all vendors
+3. Prohibited check: `scrm_assessor.py --prohibited` — Section 889 compliance
+
+### CVE Triage
+
+1. Triage new CVE: `triage_cve` (MCP) — auto-computes upstream/downstream blast radius
+2. Check SLA compliance: `cve_triager.py --sla-check`
+3. Propagate impact: `cve_triager.py --propagate` — trace through dependency graph
+
+---
+
+## Tools Used
+
+| Tool | Purpose |
+|------|---------|
+| tools/requirements/boundary_analyzer.py | 4-tier ATO boundary impact assessment |
+| tools/supply_chain/dependency_graph.py | Dependency graph build/query/impact |
+| tools/supply_chain/isa_manager.py | ISA/MOU lifecycle tracking |
+| tools/supply_chain/scrm_assessor.py | NIST 800-161 SCRM assessment |
+| tools/supply_chain/cve_triager.py | CVE triage with blast radius |
+| tools/mcp/supply_chain_server.py | MCP server (9 tools) |
+
+## Args
+
+- `args/supply_chain_config.yaml` — SCRM thresholds, CVE SLAs, ISA cadence, country risk tiers
+
+## Context
+
+- `context/supply_chain/nist_800_161_controls.json` — NIST 800-161 control catalog
+- `context/supply_chain/scrm_risk_matrix.json` — Risk scoring matrix
+- `context/supply_chain/isa_templates.json` — ISA/MOU templates and lifecycle
+- `context/requirements/boundary_impact_rules.json` — 4-tier impact rules
+- `context/requirements/red_alternative_patterns.json` — RED alternative COA patterns
+
+## Security Gates
+
+- RED-tier requirement without alternative COA → **blocks**
+- Critical SCRM risk unmitigated → **blocks**
+- ISA expired with active data flow → **blocks**
+- Critical CVE SLA overdue → **blocks**
+- Section 889 prohibited vendor detected → **blocks**
+
+---
+
+## Edge Cases
+
+- Multiple systems affected by single requirement → assess each, use worst-case tier
+- Vendor country changes (acquisition) → trigger re-assessment
+- ISA renewal rejected → flag all dependent data flows
+- CVE affects transitive dependency → propagate with decay factor
+
+---
+
+## Success Criteria
+
+- All requirements assessed with boundary impact tier
+- Zero RED-tier requirements without alternative COAs
+- All vendors assessed per NIST 800-161
+- Zero Section 889 prohibited vendors in supply chain
+- All ISAs current (no expired agreements with active data flows)
+- CVE SLA compliance across all tracked vulnerabilities
+
+---
+
+## GOTCHA Layer Mapping
+
+| Phase | GOTCHA Layer |
+|-------|--------------|
+| ATO System Registration | Goals (define boundary scope) |
+| Boundary Impact Assessment | Orchestration (AI evaluates impact) |
+| Supply Chain Tracking | Tools (dependency graph scripts) |
+| SCRM Assessment | Context (NIST 800-161 controls, risk matrix) |
+| CVE SLA Thresholds | Args (SLA windows, decay factors) |
+| Red Alternative Generation | Hard Prompts (COA generation templates) |
+
+---
+
+## Related Files
+
+- **Goal:** `goals/requirements_intake.md` — RICOAS Phase 1 (intake feeds boundary assessment)
+- **Goal:** `goals/compliance_workflow.md` — Compliance artifacts (SSP addendum for YELLOW/ORANGE)
+- **Goal:** `goals/ato_acceleration.md` — ATO acceleration (boundary changes trigger re-assessment)
+- **Goal:** `goals/maintenance_audit.md` — Maintenance (CVE triage feeds maintenance workflow)
+- **Skill:** `.claude/skills/sparkpilot-boundary/SKILL.md` — Claude Code slash command
+
+---
+
+## Changelog