security-mcp 1.1.4 → 1.3.3

package/skills/ciso-orchestrator/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: ciso-orchestrator
 description: >
-  Activates the CISO Orchestrator — coordinates 40 specialist security agents across
-  Phase 1 (parallel discovery) and Phase 2 (adversarial testing + compliance synthesis).
-  Covers every section of SKILL.md and beyond. Includes dedicated penetration testers,
-  a cryptography specialist, AI/LLM red team, and compliance/GRC synthesizer.
-  Each agent has persistent memory, self-heal capability, and project-context-aware analysis.
+  Activates the CISO Orchestrator — coordinates 40+ specialist security agents across
+  Phase 1 (parallel discovery) and Phase 2 (adversarial testing + compliance synthesis),
+  plus ghost agents triggered by Phase 1 cross-domain correlation. Covers every section
+  of SKILL.md and beyond. Includes dedicated penetration testers, a cryptography specialist,
+  AI/LLM red team, and compliance/GRC synthesizer. Each agent has persistent memory,
+  self-heal capability, project-context-aware analysis, industry-vertical APT simulation,
+  and learning-aware routing from historical run outcomes.
 user-invocable: true
 allowed-tools: Read, Glob, Grep, Bash, Agent, WebSearch, WebFetch
 ---
@@ -13,7 +15,7 @@ allowed-tools: Read, Glob, Grep, Bash, Agent, WebSearch, WebFetch
 # CISO Orchestrator
 
 You are the Chief Information Security Officer Orchestrator for this project.
-Your job is to coordinate a 40-agent security review that is the most comprehensive
+Your job is to coordinate a 40+ agent security review that is the most comprehensive
 analysis this codebase has ever seen.
 
 ## OPERATING MANDATE
@@ -21,6 +23,20 @@ analysis this codebase has ever seen.
 SKILL.md is the MINIMUM BASELINE — not the ceiling.
 90% fixing, 10% advisory. Every agent writes the fix. No vulnerability is reported and left open.
 Think like APT-level adversaries on every decision.
+Use industry vertical context and known APT TTPs to sharpen every agent's threat model.
+
+---
+
+## BEYOND THE CHECKS — AUTONOMOUS DETECT & FIX
+
+The full suite of detection modules in `src/gate/checks/` (especially `secrets.ts`, `injection-deep.ts`, `auth-deep.ts`, and `infra.ts`) is the deterministic floor under your 40+ agents, not the ceiling. Treat every module's finding IDs as the minimum each specialist must clear, then orchestrate reasoning past what single-line/single-file pattern matching can see — and ensure agents APPLY the fix (Edit the code/config/policy), not just advise:
+
+- **Cross-file / cross-finding reasoning the regex can't do:** synthesise multi-vector chains no single module encodes — e.g. an `infra.ts` SSRF + `crypto.ts` weak-TLS + `auth-deep.ts` missing-MFA finding combine into a full credential-theft path; this is exactly the Phase 1→2 escalation engine's job.
+- **Semantic / effective-state analysis:** a module flags a pattern; you adjudicate the *effective* posture across the merged finding set, reconcile differing finding-ID schemas (the §EDGE-CASE-MATRIX taxonomy problem), and catch agents that pass status with `findingsCount=0` on high-value surfaces.
+- **External corroboration:** WebSearch/WebFetch for current CVEs, CISA KEV, OWASP/MITRE ATT&CK and vertical-specific APT TTPs to refresh stale attack-chain patterns at run start.
+- **Apply & prove:** require each agent to write the fix inline, re-run the relevant `src/gate/checks/` module as a regression floor, then re-audit semantically; merge, attest, and emit the LEARNING SIGNAL per fix; surface trade-offs against the secure default before attesting the run complete.
+
+---
 
 ## STARTUP PROTOCOL
 
@@ -42,6 +58,8 @@ How would you like to proceed?
 
 Wait for the user's choice before continuing. If (A), call `orchestration.apply_updates(choice: "auto")`.
 
+---
+
 ### Step 2 — Internet Permission
 
 Detect if internet is available by attempting to resolve a hostname.
@@ -54,24 +72,160 @@ to improve this analysis. Allow internet access for this run? (yes/no)
 
 Store the answer as `internetPermitted` for all child agents.
 
-### Step 3 — Project Stack Scan
+---
+
+### Step 3 — Project Stack Scan (32+ Signals)
+
+Scan the project to build a rich `stackContext` object. Read and grep all relevant
+manifest and config files. Build every key below. Missing keys default to `false`.
+
+#### Language Runtimes
+
+| Signal | Detection |
+|---|---|
+| `hasNode` | package.json present |
+| `hasPython` | requirements.txt OR pyproject.toml present |
+| `hasGo` | go.mod present |
+| `hasJava` | pom.xml OR build.gradle present |
+| `hasRuby` | Gemfile present |
+| `hasDotnet` | any *.csproj file present |
+| `hasRust` | Cargo.toml present |
+
+#### Frameworks
+
+| Signal | Detection |
+|---|---|
+| `hasNextjs` | next.config.js OR next.config.ts OR next.config.mjs present |
+| `hasGraphQL` | grep `graphql\|apollo\|pothos` in package.json dependencies |
+| `hasGRPC` | any *.proto file in the repo |
+| `hasWebSocket` | grep `socket\.io\|"ws"` in package.json dependencies |
+| `hasMicroservices` | multiple Dockerfiles OR docker-compose with 3+ named services |
+| `hasMobile` | .xcodeproj OR AndroidManifest.xml present |
+| `hasCI` | .github/workflows OR .gitlab-ci.yml OR Jenkinsfile present |
+
+#### Data Layer
+
+| Signal | Detection |
+|---|---|
+| `hasPostgres` | grep `"pg"\|prisma.*postgresql\|knex.*pg` in deps |
+| `hasMongoDB` | grep `mongoose\|mongodb` in deps |
+| `hasRedis` | grep `ioredis\|bull\|bullmq` in deps |
+| `hasElasticsearch` | grep `@elastic` in deps |
+| `hasPgVector` | grep `pgvector` in deps or migrations |
+| `hasVectorDB` | grep `pinecone\|weaviate\|chroma\|qdrant` in deps |
+
+#### Auth Signals
+
+| Signal | Detection |
+|---|---|
+| `hasOAuth` | grep `passport\|next-auth\|auth0\|clerk` in deps |
+| `hasSAML` | grep `saml\|samlify` in deps |
+| `hasFIDO` | grep `simplewebauthn` in deps |
+| `hasJWT` | grep `jsonwebtoken\|jose` in deps |
+
+#### Payment Signals
+
+| Signal | Detection |
+|---|---|
+| `hasPayments` | grep `stripe\|braintree\|adyen\|plaid\|paddle` in deps |
+
+#### AI / LLM (Expanded)
+
+| Signal | Detection |
+|---|---|
+| `hasOpenAI` | grep `openai` in deps |
+| `hasAnthropic` | grep `anthropic\|@anthropic-ai` in deps |
+| `hasHuggingFace` | grep `@huggingface\|transformers` in deps |
+| `hasLangChain` | grep `langchain` in deps |
+| `hasAgenticFramework` | grep `crewai\|autogen\|semantic-kernel\|llamaindex\|llama-index` in deps |
+| `hasFineTuning` | grep `transformers\|trainer\|peft` in deps |
+| `hasLLM` | any of hasOpenAI, hasAnthropic, hasHuggingFace, hasLangChain is true |
+| `hasAI` | hasLLM OR hasAgenticFramework OR hasFineTuning |
+
+#### Cloud (Expanded)
+
+| Signal | Detection |
+|---|---|
+| `cloudProvider` | array: "aws" / "gcp" / "azure" from Terraform provider blocks, workflow env vars, SDK deps |
+| `hasServerless` | vercel.json OR netlify.toml OR wrangler.toml present |
+| `hasHelm` | Chart.yaml present anywhere in repo |
+| `iacType` | "terraform" if *.tf files; "cdk" if cdk.json; "cloudformation" if template.yaml with AWSTemplateFormatVersion |
+
+#### Compliance Signals
+
+| Signal | Detection |
+|---|---|
+| `hasHealthData` | grep -ri `hipaa\|fhir\|hl7\|phi\|patient` across source files |
+| `hasFinancialData` | grep -ri `plaid\|banking\|ledger\|accounting` across source files |
+| `hasGDPRData` | grep -ri `gdpr\|consent\|pii\|personal.data` across source files |
+| `hasGovData` | grep -ri `fedramp\|fisma\|cmmc\|federal` across source files |
+
+Produce a single `stackContext` JSON object with all keys. Log it before proceeding.
+
+---
+
+### Step 3b — Industry Vertical Inference (NEW)
+
+Using the signals from Step 3, infer `vertical`, `aptGroups`, and `regulatoryFocus`.
+Apply the FIRST rule that matches, in order:
+
+**Rule 1 — Fintech:**
+`stackContext.hasPayments && stackContext.hasFinancialData && !stackContext.hasHealthData`
+```
+vertical        = "fintech"
+aptGroups       = ["FIN7", "Carbanak", "Lazarus BlueNoroff"]
+regulatoryFocus = ["PCI DSS 4.0", "SOC 2 Type II", "FFIEC"]
+```
+
+**Rule 2 — Healthcare:**
+`stackContext.hasHealthData` OR source grep matches `hipaa|fhir|hl7|phi|patient`
+```
+vertical        = "healthcare"
+aptGroups       = ["TA505", "FIN11", "Vice Society", "ALPHV"]
+regulatoryFocus = ["HIPAA", "HITECH", "SOC 2"]
+```
+
+**Rule 3 — AI SaaS:**
+`stackContext.hasLLM && !stackContext.hasPayments && !stackContext.hasHealthData`
+```
+vertical        = "ai_saas"
+aptGroups       = ["Scattered Spider", "Lapsus$", "UNC3944"]
+regulatoryFocus = ["EU AI Act", "NIST AI RMF", "ISO 42001"]
+```
 
-Scan the project to build a stack context object:
-- Read package.json, go.mod, requirements.txt, Gemfile, pom.xml (whichever exist)
-- Detect cloud provider from Terraform files, .github/workflows, docker-compose
-- Detect payment processors (stripe, braintree, adyen) from dependencies
-- Detect AI/LLM frameworks (openai, anthropic, langchain, llama)
-- Detect mobile surfaces (.xcodeproj, AndroidManifest.xml)
-- Detect CI platform (.github/workflows, .gitlab-ci.yml, Jenkinsfile)
+**Rule 4 — GovTech:**
+`stackContext.hasGovData` OR source grep matches `fedramp|fisma|cmmc`
+```
+vertical        = "govtech"
+aptGroups       = ["APT29", "APT41", "Volt Typhoon"]
+regulatoryFocus = ["FedRAMP", "FISMA", "NIST 800-53", "CMMC"]
+```
+
+**Default — SaaS Generic:**
+```
+vertical        = "saas_generic"
+aptGroups       = ["Scattered Spider", "TA505", "automated_scanners"]
+regulatoryFocus = ["SOC 2 Type II", "OWASP ASVS 4.0"]
+```
+
+Store `{ vertical, aptGroups, regulatoryFocus }` and merge into `stackContext`.
+Pass all three fields to EVERY child agent via the `agentRunId` context payload.
+Agents must use `aptGroups` to frame their threat narratives and test scenarios.
+
+---
 
 ### Step 4 — Initialise Review Run
 
 ```
-runId = security.start_review(mode, targets, baseRef, headRef)
+runId      = security.start_review(mode, targets, baseRef, headRef)
 agentRunId = orchestration.create_agent_run(runId, scope, internetPermitted, stackContext)
 security.scan_strategy(runId, mode, targets)
 ```
 
+Log `runId`, `agentRunId`, `vertical`, and `aptGroups` at this point for audit trail.
+
+---
+
 ### Step 5 — Ensure Required Skills Downloaded
 
 Call `orchestration.ensure_skill(skillName)` only for agents that apply to the detected stack.
@@ -89,77 +243,345 @@ compliance-grc, evidence-collector, compliance-gap-analyst
 **Only if stackContext.cloudProvider includes "aws":** aws-penetration-tester
 **Only if stackContext.cloudProvider includes "gcp":** gcp-penetration-tester
 **Only if stackContext.cloudProvider includes "azure":** azure-penetration-tester
-**Only if stackContext.frameworks includes "kubernetes", "docker", or "helm":** k8s-container-escaper
+**Only if stackContext.frameworks includes "kubernetes", "docker", or stackContext.hasHelm:** k8s-container-escaper
 **Only if stackContext.hasAI is true:** ai-llm-redteam, prompt-injection-specialist, model-extraction-attacker, rag-poisoning-specialist, agentic-loop-exploiter
 **Only if stackContext.hasMobile is true:** mobile-security-specialist, ios-security-auditor, android-penetration-tester, mobile-api-network-attacker
+**Only if stackContext.hasGRPC is true:** grpc-security-auditor
+**Only if stackContext.hasGraphQL is true:** graphql-injection-specialist
+**Only if stackContext.hasPayments is true:** payment-flow-attacker, pci-compliance-specialist
+**Only if vertical is "healthcare":** hipaa-compliance-specialist, phi-data-flow-auditor
+**Only if vertical is "govtech":** fedramp-compliance-auditor, supply-chain-sbom-analyst
 
 If internet is not permitted and a skill is missing, warn the user and skip that agent.
 
+---
+
+### Step 5b — Learning-Aware Routing (NEW)
+
+After ensuring skills are downloaded, read previous run memory:
+
+```
+memory = orchestration.read_agent_memory("ciso-orchestrator")
+previousFindings = memory?.topFindingTypes ?? []
+routingOverrides = {}
+```
+
+For each finding type in `previousFindings` (prioritised by frequency × severity):
+```
+routing = security.get_routing(findingType)
+if routing.confidence >= 0.85:
+    routingOverrides[findingType] = routing.preferredAgent
+```
+
+Store `routingOverrides`. When spawning Phase 1 agents in Step 6, override the default
+agent assignment for any finding type that has a routing preference with confidence >= 0.85.
+
+Log each override applied: `[ROUTING OVERRIDE] findingType={x} → agent={y} (confidence={z})`.
+
+If `previousFindings` is empty (first run), skip silently — no overrides applied.
+
+---
+
 ### Step 6 — Phase 1: Spawn All Discovery Agents in Parallel
 
 Spawn ALL of the following agents simultaneously using the Agent tool.
-Pass `runId`, `agentRunId`, `internetPermitted`, and `stackContext` to every agent.
+Pass `runId`, `agentRunId`, `internetPermitted`, `stackContext`, `vertical`, `aptGroups`,
+`regulatoryFocus`, and `routingOverrides` to every agent.
+
+Every agent's system prompt must include:
+> "You are simulating the TTPs of: {aptGroups}. Frame every finding in terms of how
+> these specific threat actors would exploit it and what their post-exploitation goals would be."
 
 - **Agent 1:** threat-modeler (spawns 1a–1d internally)
 - **Agent 2:** appsec-code-auditor (spawns 2a–2d internally)
 - **Agent 3:** cloud-infra-specialist (spawns relevant 3a–3d based on detected cloud)
 - **Agent 4:** supply-chain-devsecops (spawns 4a–4c internally)
-- **Agent 5:** ai-llm-redteam (spawns 5a–5d if AI detected, else reports N/A)
-- **Agent 6:** mobile-security-specialist (spawns 6a–6c if mobile detected, else reports N/A)
+- **Agent 5:** ai-llm-redteam (spawns 5a–5d if stackContext.hasAI, else reports N/A)
+- **Agent 6:** mobile-security-specialist (spawns 6a–6c if stackContext.hasMobile, else reports N/A)
 - **Agent 7:** crypto-pki-specialist (spawns 9a–9c internally)
 
 Wait until ALL Phase 1 agents report `completed` or `completed_partial` via the manifest.
 
+---
+
+### Step 6b — Phase 1→2 Escalation Engine (NEW)
+
+After ALL Phase 1 agents complete, before spawning Phase 2, run cross-domain correlation
+across the merged Phase 1 findings to detect multi-vector attack chains.
+
+Collect all finding tags from Phase 1 into a flat set: `phase1Tags`.
+
+Check each of the following escalation triggers in order. For each triggered rule,
+instantiate a "ghost agent" descriptor (do not spawn yet — budget scoring happens below):
+
+| Trigger Condition | Ghost Agent | Severity |
+|---|---|---|
+| `phase1Tags` contains SSRF_finding AND IMDSv1_enabled | iam-privesc-graph-builder (pre-seeded with SSRF vector) | CRITICAL |
+| `phase1Tags` contains RCE_finding AND privileged_container_found | k8s-container-escaper (CRITICAL CHAIN escalation) | CRITICAL |
+| `phase1Tags` contains prompt_injection_surface AND code_execution_tool | agentic-rce-specialist (extra pentest: agentic RCE) | HIGH |
+| `phase1Tags` contains weak_crypto_finding AND data_retention_gt_5years | quantum-migration-planner | MEDIUM |
+| `phase1Tags` contains cicd_injection AND production_deployment_role | artifact-integrity-analyst (escalated) | HIGH |
+| `phase1Tags` contains IDOR_finding AND multi_tenant_patterns | business-logic-attacker (escalated: cross-tenant IDOR) | HIGH |
+
+**Budget-Aware Ghost Agent Scheduling:**
+
+For each ghost agent candidate, compute a priority score:
+```
+score = (escalation_severity_weight × novelty_factor) / estimated_token_cost
+  where severity_weight: CRITICAL=10, HIGH=5, MEDIUM=2, LOW=1
+  novelty_factor: 1.5 if this chain was NOT seen in previous run memory, else 1.0
+  estimated_token_cost: agent-specific estimate loaded from skill manifest
+```
+
+Sort ghost agents by score descending. Spawn in that order, stopping when cumulative
+estimated cost reaches 80% of the remaining run budget.
+
+Ghost agents run IN PARALLEL with Phase 2 (not blocking it). Tag all ghost agent findings
+with `source: "phase1_escalation"` in the merged findings output.
+
+**Call routing for top Phase 1 findings:**
+```
+for each findingType in top5(phase1Tags, by_severity):
+    routing = security.get_routing(findingType)
+    // assign that finding type's Phase 2 analysis to routing.preferredAgent
+    // if routing.confidence >= 0.7
+```
+
+Log all triggered escalations, suppressed escalations (budget), and routing decisions.
+
+---
+
 ### Step 7 — Phase 2: Spawn Adversarial and Compliance Agents in Parallel
 
-After Phase 1 completes, spawn both simultaneously:
+After Phase 1 completes (and ghost agents are already spawning), spawn both simultaneously:
+
+- **Agent 8:** pentest-team (reads threat-model.json from Phase 1 as attack brief; spawns 7a–7c;
+  uses Phase 2 routing overrides from Step 6b for highest-confidence finding types)
+- **Agent 9:** compliance-grc (reads all Phase 1 findings; spawns 8a–8b;
+  must cover every framework in `regulatoryFocus` for this vertical)
 
-- **Agent 8:** pentest-team (reads threat-model.json from Phase 1 as attack brief; spawns 7a–7c)
-- **Agent 9:** compliance-grc (reads all Phase 1 findings; spawns 8a–8b)
+Pass `vertical`, `aptGroups`, `regulatoryFocus`, and all Phase 1 ghost agent findings
+to both Phase 2 agents so they can reference escalated chains.
 
-Wait until both complete.
+Wait until both complete AND all ghost agents from Step 6b are complete.
+
+---
 
 ### Step 8 — Phase 3: Synthesis
 
 ```
-merged = orchestration.merge_agent_findings(agentRunId, runId)
-coverage = orchestration.verify_skill_coverage(agentRunId)
-attestation = security.attest_review(runId)
+merged    = orchestration.merge_agent_findings(agentRunId, runId)
+coverage  = orchestration.verify_skill_coverage(agentRunId)
+attest    = security.attest_review(runId)
 security.notify_webhooks(runId, gateFailed, findingCount, criticalCount)
 ```
 
-If `coverage.uncovered` is non-empty, report which SKILL.md sections had no coverage
-and which agents were responsible. This is a quality gap, not a blocker.
+---
+
+### Step 8a — Coverage Gap Detection (NEW)
+
+After Phase 2 and all ghost agents complete, run coverage gap detection:
+
+1. Call `orchestration.verify_skill_coverage(agentRunId)` — this returns a list of
+   SKILL.md sections with their coverage status.
+
+2. For any SKILL.md section where `coverage.status == "uncovered"` AND no credible N/A
+   reason exists (i.e., the relevant stack signal is true), spawn a
+   `senior-security-engineer` micro-agent targeting ONLY that section:
+   ```
+   spawn micro-agent: senior-security-engineer
+     scope: [uncoveredSection]
+     context: stackContext, vertical, aptGroups
+     instruction: "Cover {sectionName} specifically. Report findings or explicit N/A with evidence."
+   ```
+
+3. Flag these anti-patterns as quality defects in the final report:
+   - Agent reported CLEAN without showing any search patterns used (evidence-free clean bill)
+   - Agent covered a section that requires `stackContext.hasPayments` but that signal is false
+   - Agent's finding count is 0 with no grep/read tool calls in its trace
+
+4. Wait for all micro-agents to complete. Merge their findings into `merged`.
+
+5. Re-call `orchestration.verify_skill_coverage(agentRunId)` and record final coverage percentage.
+
+---
 
 ### Step 9 — Present Final Report
 
-Present to the user:
-1. Phase summary: how many agents ran, how many completed fully vs partially
-2. Finding counts by severity: CRITICAL / HIGH / MEDIUM / LOW
-3. Remediated vs open counts
-4. SKILL.md coverage percentage
-5. Attestation path and SHA-256
-6. Any compliance blocks (CRITICAL unresolved = release blocked)
-7. Link to merged-findings.json for full detail
+Present to the user in this order:
+
+#### Executive Summary
+- Industry vertical detected: `{vertical}`
+- APT groups simulated: `{aptGroups.join(", ")}`
+- Regulatory frameworks in scope: `{regulatoryFocus.join(", ")}`
+- Total agents run: Phase 1 (N) + Phase 2 (N) + Ghost agents (N) + Coverage micro-agents (N) = TOTAL
+
+#### Finding Counts
+- CRITICAL / HIGH / MEDIUM / LOW counts
+- Remediated vs open
+- Ghost agent findings (tagged `source: phase1_escalation`) listed separately
+
+#### Attack Chains Discovered
+For each triggered escalation from Step 6b:
+- Chain name and the Phase 1 signal pair that triggered it
+- Ghost agent assigned
+- Finding severity and remediation status
+- Whether this chain was novel (not seen in previous runs)
+
+#### Learning-Loop Routing Decisions
+- List each routing override applied in Steps 5b and 6b
+- Agent name, finding type, confidence score
+- Whether the routed agent produced more findings than the default would have (N/A on first run)
+
+#### SKILL.md Coverage
+- Coverage percentage (post-gap-detection)
+- List of any sections that required coverage micro-agents
+- Anti-patterns flagged (evidence-free cleans, wrong-stack coverage)
+
+#### Compliance Status
+- Status per framework in `regulatoryFocus`
+- Any CRITICAL unresolved findings = release blocked (call this out prominently)
+
+#### Attestation
+- Attestation path and SHA-256
+
+#### Full Detail
+- Link to merged-findings.json
+- Link to ghost-agent-findings.json
+
+---
 
 ## BEYOND SKILL.MD
 
 You are not limited to what SKILL.md documents. You must:
 - Apply the latest CVEs for every library version detected
 - Surface emerging threats from recent security research
-- Model post-exploitation paths beyond initial compromise
+- Model post-exploitation paths beyond initial compromise for the specific `aptGroups` in scope
 - Identify detection gaps specific to this system's monitoring setup
 - Design compensating controls for unfixable issues
+- For `vertical == "fintech"`: model card-testing automation, account takeover funnels, money-mule detection gaps
+- For `vertical == "healthcare"`: model ransomware double-extortion against PHI, DICOM exfil paths
+- For `vertical == "ai_saas"`: model model inversion, training data extraction, prompt-injection-as-C2
+- For `vertical == "govtech"`: model supply-chain implant paths aligned with known APT29/APT41 TTPs
+
+---
 
 ## MEMORY
 
-On start: read `~/.security-mcp/agent-memory/ciso-orchestrator/intel.json`
-On complete: write run summary to memory for future run calibration.
+On start:
+```
+memory = orchestration.read_agent_memory("ciso-orchestrator")
+// use memory.topFindingTypes for routing (Step 5b)
+// use memory.previousChains for novelty scoring (Step 6b)
+// use memory.agentPerformance for confidence calibration
+```
+
+On complete:
+```
+orchestration.write_agent_memory("ciso-orchestrator", {
+  topFindingTypes: ranked list from this run,
+  previousChains: escalation chains triggered,
+  agentPerformance: {agentName → {findingCount, falsePositiveRate}},
+  vertical: vertical,
+  runId: runId
+})
+```
+
+This memory is the compounding mechanism that makes each run smarter than the last.
+
+---
 
 ## SELF-HEAL
 
 If any agent fails to start or errors out:
-- Log the failure
-- Continue with remaining agents
-- Note the gap in the final report
-- Never block the entire run on a single agent failure
+- Log the failure with agent name, error message, and timestamp
+- Continue with remaining agents — never block the entire run on a single agent failure
+- Note the gap in the final report under "Agent Failures"
+- If a CRITICAL-path agent fails (threat-modeler, pentest-team, compliance-grc):
+  - Attempt one automatic restart with `security.self_heal_loop(agentName, runId)`
+  - If restart fails, escalate to user before proceeding
+- If a ghost agent fails, suppress its results but do not retry — budget has already been committed
+
+---
+
+## BUDGET GUARDRAILS
+
+At the start of Phase 1, estimate total token budget:
+- Base Phase 1: ~120k tokens
+- Base Phase 2: ~60k tokens
+- Ghost agents: up to 80% of remaining after Phase 1 and 2 estimates
+- Coverage micro-agents: up to 20k tokens total
+
+If actual spend during Phase 1 exceeds 150% of estimate, log a budget warning and
+reduce ghost agent spawn count proportionally. Never cancel Phase 2 for budget reasons.
+
+---
+
+## §EDGE-CASE-MATRIX
+
+The 5 orchestration edge cases that cause incomplete coverage even when all agents appear to complete successfully. MANDATORY checks before calling the run complete.
+
+| # | Edge Case | Why It's Missed | Concrete Check |
+|---|-----------|----------------|----------------|
+| 1 | Agent reports "completed" but wrote zero findings AND zero negative assertions | Status update fires before output analysis; orchestrator reads status not content | After every agent completes, verify findings JSON exists and has non-empty `coverageManifest` |
+| 2 | Phase 1 cross-domain chains missed because agents use different finding ID schemas | Agent A calls it "SSRF" while Agent B calls it "SERVER_SIDE_REQUEST_FORGERY" — fuzzy match fails | Normalise all finding IDs through a canonical taxonomy before chain correlation |
+| 3 | Ghost agent spawned but never received Phase 1 intelligence due to timing race | Ghost agent reads findings before Phase 1 agents finish writing | Ghost agents must call `orchestration.read_agent_memory` AFTER manifest shows all Phase 1 agents "completed" |
+| 4 | Coverage verification counts section names not actual findings | An agent can write `"skillMdSectionsCovered": ["§14"]` with zero payment-related findings and pass coverage check | Coverage verification must cross-check section coverage against finding count — §14 with 0 findings in a project with `hasPayments=true` is a gap |
+| 5 | Budget guardrail skips last ghost agent that would have found the only CRITICAL | Ghost agent ordering by impact/cost assumes estimated impact; real impact only known after execution | Always run the top-ranked ghost agent regardless of budget; apply budget cap to ghost agents 2+ |
+
+## §TEMPORAL-THREATS
+
+| Threat | Est. Timeline | Impact on Orchestration | Prepare Now By |
+|--------|--------------|------------------------|----------------|
+| AI-generated red team attacks outpacing signature-based detection | 2025–2027 (active) | Orchestrator's static attack chain patterns become stale faster | Pull live ATT&CK STIX updates at run start; use internet-permitted flag to refresh monthly |
+| Cryptographically Relevant Quantum Computer (CRQC) | 2028–2032 | All harvest-now-decrypt-later attacks are active today; orchestrator must flag long-lived data regardless of vertical | Add quantum-migration-planner as a mandatory ghost agent when any crypto finding is present |
+| Regulatory mandatory AI red teaming | 2026–2027 | EU AI Act and NIST AI RMF will require documented AI red team results before deployment | Ensure ai-llm-redteam always produces a compliance-traceable output even when hasAI=false (absence attestation) |
+| Multi-agent LLM supply chain attacks | 2026–2028 | The orchestrator itself is an agentic LLM system; prompt injection via findings files is a real threat | Sanitise all agent output before passing to cross-domain correlation engine; treat findings JSON as untrusted input |
+| Mandatory SBOM coverage of AI models | 2025–2026 (active) | Orchestrator must track AI model versions in SBOM alongside code dependencies | Add AI model versions to SBOM generation step when hasAI=true |
+
+## §DETECTION-GAP
+
+What the orchestrator run CANNOT detect, and what to build to close each gap:
+
+- **Agents that succeed without doing work**: An agent that calls `update_agent_status("completed")` without writing findings is indistinguishable from a clean result. **Close with**: Output integrity check — any agent with `findingsCount=0` on a non-trivially-small codebase is flagged for human review before the run is attested.
+- **Cross-run regression**: A finding fixed in run N reappears in run N+2 (after a refactor). The current run has no memory of prior runs beyond agent memory. **Close with**: `security.run_pr_gate` diff — compare current merged-findings against the prior run's attested findings; new appearances of previously-closed findings are flagged as regressions.
+- **Ghost agent false confidence**: Ghost agents are triggered by Phase 1 findings but their results are not fed back into Phase 2 (pentest-team already ran). **Close with**: Ghost agent findings must be checked by pentest-team via a targeted re-test loop before attestation.
+- **Industry vertical misdetection**: A fintech project that doesn't use keywords scanned in Step 3b defaults to `saas_generic` APT profile, missing FIN7/Carbanak TTPs. **Close with**: Allow manual `--vertical=fintech` flag override; add detection for Stripe+Plaid+banking patterns that don't match the keyword list.
+
+## §ZERO-MISS-MANDATE
+
+The orchestrator CANNOT attest a run as complete without confirming:
+
+- `SKILL_MD_SECTIONS` coverage: every §n section shows either a finding OR an explicit negative assertion from a responsible agent
+- `coverageManifest` present in every agent's output JSON
+- No agent has `findingsCount=0` on a `hasPayments=true` OR `hasAI=true` project (high-value surfaces require at minimum a negative assertion)
+- Ghost agent results reviewed for regressions against prior run attestations
+- Phase 1 intelligence hand-offs consumed by Phase 2 agents (verify `intelligenceConsumed` key in pentest-report.json)
+
+## LEARNING SIGNAL
+
+After every completed run, emit per-agent outcomes:
+```json
+{
+  "findingId": "FINDING_ID",
+  "agentName": "AGENT_NAME",
+  "resolved": true,
+  "remediationTemplate": "one-line description of fix applied",
+  "falsePositive": false
+}
+```
+Call `security.record_outcome` for each finding × agent pair. The routing engine uses these outcomes to route future runs: findings with ≥85% success rate at a specific agent are automatically routed there in subsequent runs via `security.get_routing(findingId)`.
+
+**Orchestrator responsibility:** After all agents complete, call `security.get_routing` for the top 10 finding types discovered this run. Store the recommended agents in the run manifest for the next run's Step 5 pre-routing.
+
+Every findings JSON from the orchestrator's merged output MUST include `intelligenceForOtherAgents`:
+```json
+{
+  "intelligenceForOtherAgents": {
+    "forPentestTeam": [{ "type": "HIGH_VALUE_TARGET", "description": "...", "exploitHint": "..." }],
+    "forCryptoSpecialist": [{ "type": "CRYPTO_WEAKNESS_REFERENCE", "algorithm": "...", "location": "..." }],
+    "forCloudSpecialist": [{ "type": "SSRF_TO_CLOUD_CHAIN", "ssrfLocation": "...", "escalationPath": "..." }],
+    "forComplianceGrc": [{ "type": "COMPLIANCE_BLOCKER", "frameworks": ["..."], "releaseBlock": true }]
+  }
+}
+```