@harness-engineering/cli 1.14.0 → 1.16.0

package/dist/agents/skills/codex/harness-code-review/skill.yaml

@@ -0,0 +1,52 @@
+name: harness-code-review
+version: "2.0.0"
+description: Multi-phase code review pipeline with mechanical checks, graph-scoped context, and parallel review agents
+cognitive_mode: adversarial-reviewer
+triggers:
+  - manual
+  - on_pr
+  - on_review
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+  - emit_interaction
+cli:
+  command: harness skill run harness-code-review
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: --comment
+      description: Post inline comments to GitHub PR
+      required: false
+    - name: --deep
+      description: Add threat modeling pass (invokes security-review --deep)
+      required: false
+    - name: --no-mechanical
+      description: Skip mechanical checks (useful if already run)
+      required: false
+    - name: --ci
+      description: Enable eligibility gate, non-interactive output
+      required: false
+    - name: --fast
+      description: Reduced rigor — skip learnings integration, fast-tier agents only
+      required: false
+    - name: --thorough
+      description: Maximum rigor — always load learnings, full agent roster + meta-judge
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-code-review
+    path: string
+type: rigid
+tier: 2
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/skills/codex/harness-codebase-cleanup/SKILL.md

@@ -0,0 +1,224 @@
+# Harness Codebase Cleanup
+
+> Orchestrate dead code removal and architecture violation fixes with a shared convergence loop. Catches cross-concern cascades that individual skills miss.
+
+## When to Use
+
+- After a major refactoring or feature removal when both dead code and architecture violations are likely
+- As a periodic comprehensive codebase hygiene task
+- When `cleanup-dead-code` or `enforce-architecture` individually are not catching cascading issues
+- When you want hotspot-aware safety classification
+- NOT for quick single-concern checks -- use `cleanup-dead-code` or `enforce-architecture` directly
+- NOT when tests are failing -- fix tests first
+- NOT during active feature development
+
+## Flags
+
+| Flag                  | Effect                                                            |
+| --------------------- | ----------------------------------------------------------------- |
+| `--fix`               | Enable convergence-based auto-fix (default: detect + report only) |
+| `--dead-code-only`    | Skip architecture checks                                          |
+| `--architecture-only` | Skip dead code checks                                             |
+| `--dry-run`           | Show what would be fixed without applying                         |
+| `--ci`                | Non-interactive: apply safe fixes only, report everything else    |
+
+## Process
+
+### Phase 1: CONTEXT -- Build Hotspot Map
+
+1. **Run hotspot detection** via git log analysis:
+   ```bash
+   git log --format=format: --name-only --since="6 months ago" | sort | uniq -c | sort -rn | head -50
+   ```
+2. **Build churn map.** Parse output into a `file -> commit count` mapping.
+3. **Compute top 10% threshold.** Sort all files by commit count. The file at the 90th percentile defines the threshold. Files above this threshold are "high churn."
+4. **Store as HotspotContext** for use in Phase 3 (CLASSIFY).
+
+### Phase 2: DETECT -- Run Both Concerns in Parallel
+
+1. **Dead code detection** (skip if `--architecture-only`):
+   - Run `harness cleanup --type dead-code --json`
+   - Captures: dead files, dead exports, unused imports, dead internals, commented-out code blocks, orphaned dependencies
+
+2. **Architecture detection** (skip if `--dead-code-only`):
+   - Run `harness check-deps --json`
+   - Captures: layer violations, forbidden imports, circular dependencies, import ordering issues
+
+3. **Merge findings.** Convert all raw findings into `CleanupFinding` objects using `classifyFinding()`. This normalizes both concerns into a shared schema.
+
+### Phase 3: CLASSIFY -- Safety Classification and Dedup
+
+1. **Apply safety classification.** Each `CleanupFinding` already has a safety level from `classifyFinding()`. Review the classification rules:
+
+   **Dead code safety:**
+
+   | Finding                   | Safety        | Condition                                   |
+   | ------------------------- | ------------- | ------------------------------------------- |
+   | Dead files                | Safe          | Not entry point, no side effects            |
+   | Unused imports            | Safe          | Zero references                             |
+   | Dead exports (non-public) | Safe          | Zero importers, not in package entry point  |
+   | Dead exports (public API) | Unsafe        | In package entry point or published package |
+   | Commented-out code        | Safe          | Always (code is in git history)             |
+   | Orphaned npm deps         | Probably safe | Needs install + test verification           |
+   | Dead internals            | Unsafe        | Cannot reliably determine all callers       |
+
+   **Architecture safety:**
+
+   | Violation                           | Safety        | Condition                  |
+   | ----------------------------------- | ------------- | -------------------------- |
+   | Import ordering                     | Safe          | Mechanical reorder         |
+   | Forbidden import (with alternative) | Probably safe | 1:1 replacement configured |
+   | Forbidden import (no alternative)   | Unsafe        | Requires restructuring     |
+   | Design token (unambiguous)          | Probably safe | Single token match         |
+   | Design token (ambiguous)            | Unsafe        | Multiple candidates        |
+   | Upward dependency                   | Unsafe        | Always                     |
+   | Skip-layer dependency               | Unsafe        | Always                     |
+   | Circular dependency                 | Unsafe        | Always                     |
+
+2. **Apply hotspot downgrade.** For each finding, check if the file is in the top 10% by churn (from Phase 1 HotspotContext). If so, downgrade `safe` to `probably-safe`. Do not downgrade `unsafe` findings.
+
+3. **Cross-concern dedup.** Call `deduplicateFindings()` to merge overlapping findings:
+   - A dead import from a forbidden layer = one finding (dead-code concern, noting architecture overlap)
+   - A dead file that has architecture violations = one finding (dead-code, noting violations resolved by deletion)
+
+### Phase 4: FIX -- Convergence Loop
+
+**Only runs when `--fix` flag is set.** Without `--fix`, skip to Phase 5 (REPORT).
+
+```
+findings = classified findings from Phase 3
+previousCount = findings.length
+iteration = 0
+
+while iteration < 5:
+  iteration++
+
+  # Batch 1: Apply safe fixes silently
+  safeFixes = findings.filter(f => f.safety === 'safe')
+  apply(safeFixes)
+
+  # Batch 2: Present probably-safe fixes
+  if --ci mode:
+    skip probably-safe fixes (report only)
+  else:
+    probablySafeFixes = findings.filter(f => f.safety === 'probably-safe')
+    presentAsDiffs(probablySafeFixes)
+    apply(approved fixes)
+
+  # Verify: lint + typecheck + test
+  verifyResult = run("pnpm lint && pnpm tsc --noEmit && pnpm test")
+
+  if verifyResult.failed:
+    revertBatch()
+    reclassify failed fixes as unsafe
+    continue
+
+  # Re-detect both concerns
+  newFindings = runDetection()  # Phase 2 again
+  newFindings = classify(newFindings)  # Phase 3 again
+
+  if newFindings.length >= previousCount:
+    break  # No progress, stop
+
+  previousCount = newFindings.length
+  findings = newFindings
+```
+
+**Verification gate:** Every fix batch must pass lint + typecheck + test. If verification fails:
+
+1. Revert the entire batch (use git: `git checkout -- .`)
+2. Reclassify all findings in the batch as `unsafe`
+3. Continue the loop with remaining findings
+
+**Cross-concern cascade examples:**
+
+- Dead import from forbidden layer: removing the dead import also resolves the architecture violation. Single fix, both resolved.
+- Architecture fix creates dead code: replacing a forbidden import makes the old module's export dead. Next detect cycle catches it.
+- Dead file resolves multiple violations: deleting a dead file that imports from wrong layers resolves those violations too.
+
+### Phase 5: REPORT -- Actionable Output
+
+Generate a structured report with two sections:
+
+**1. Fixes Applied:**
+For each fix that was applied:
+
+- File and line
+- What was fixed (finding type and description)
+- What action was taken (delete, replace, reorder)
+- Verification status (pass/fail)
+
+**2. Remaining Findings (requires human action):**
+For each unsafe finding that was not auto-fixed:
+
+- **What is wrong:** The finding type, file, line, and description
+- **Why it cannot be auto-fixed:** The safety reason and classification logic
+- **Suggested approach:** Concrete next steps for manual resolution
+
+Example report output:
+
+```
+=== HARNESS CODEBASE CLEANUP REPORT ===
+
+Fixes applied: 12
+  - 5 unused imports removed (safe)
+  - 3 dead exports de-exported (safe)
+  - 2 commented-out code blocks deleted (safe)
+  - 1 forbidden import replaced (probably-safe, approved)
+  - 1 orphaned dependency removed (probably-safe, approved)
+
+Convergence: 3 iterations, 12 → 8 → 3 → 3 (stopped)
+
+Remaining findings: 3 (require human action)
+
+  1. UNSAFE: Circular dependency
+     File: src/services/order-service.ts <-> src/services/inventory-service.ts
+     Why: Circular dependencies require structural refactoring
+     Suggested: Extract shared logic into src/services/stock-calculator.ts
+
+  2. UNSAFE: Dead internal function
+     File: src/utils/legacy.ts:45 — processLegacyFormat()
+     Why: Cannot reliably determine all callers (possible dynamic usage)
+     Suggested: Search for string references, check config files, then delete if confirmed unused
+
+  3. UNSAFE: Public API dead export
+     File: packages/core/src/index.ts — legacyHelper
+     Why: Export is in package entry point; external consumers may depend on it
+     Suggested: Deprecate with @deprecated JSDoc tag, remove in next major version
+```
+
+## Examples
+
+### Example: Post-Refactoring Cleanup
+
+After removing the `legacy-auth` module:
+
+1. **Phase 1 (CONTEXT):** Hotspot analysis shows `src/services/auth.ts` has 42 commits (top 5%).
+2. **Phase 2 (DETECT):** Dead code detects 3 dead exports in `src/utils/token.ts` (were only used by legacy-auth). Architecture detects 1 forbidden import in `src/services/session.ts` (still importing from removed module's location).
+3. **Phase 3 (CLASSIFY):** Dead exports classified as `safe` but downgraded to `probably-safe` because `token.ts` is in a high-churn file. Forbidden import classified as `unsafe` (no alternative configured).
+4. **Phase 4 (FIX):** First iteration removes 3 dead exports (approved as probably-safe). Re-detect finds `token.ts` now has zero exports and becomes a dead file. Second iteration deletes the dead file. Convergence stops -- the forbidden import requires manual restructuring.
+5. **Phase 5 (REPORT):** 4 fixes applied (3 dead exports + 1 dead file), 1 remaining finding (forbidden import requiring restructuring).
+
+## Harness Integration
+
+- **`harness cleanup --type dead-code --json`** -- Dead code detection input
+- **`harness check-deps --json`** -- Architecture violation detection input
+- **`git log` analysis** -- Hotspot context for safety classification (inline command, no skill invocation needed)
+- **`harness validate`** -- Final validation after all fixes
+- **`harness check-deps`** -- Final architecture check after all fixes
+
+## Success Criteria
+
+- All safe fixes are applied without test failures
+- Probably-safe fixes are presented as diffs for approval (or skipped in CI mode)
+- Unsafe findings are never auto-fixed
+- Convergence loop catches cross-concern cascades
+- Report includes actionable guidance for every remaining finding
+- `harness validate` passes after cleanup
+
+## Escalation
+
+- **When convergence loop does not converge after 5 iterations:** The codebase has deeply tangled issues. Stop and report all remaining findings. Consider breaking the cleanup into focused sessions.
+- **When a safe fix causes test failures:** The classification was wrong. Revert, reclassify as unsafe, and investigate the hidden dependency. Document the false positive for future improvement.
+- **When the hotspot detector is unavailable:** Skip the hotspot downgrade. All safety classifications use their base level without churn context.
+- **When dead code and architecture fixes conflict:** The convergence loop handles this naturally. If removing dead code creates an architecture issue (rare), the next detection cycle catches it.

package/dist/agents/skills/codex/harness-codebase-cleanup/skill.yaml

@@ -0,0 +1,65 @@
+name: harness-codebase-cleanup
+version: "1.0.0"
+description: Orchestrate dead code removal and architecture violation fixes with shared convergence loop
+cognitive_mode: systematic-orchestrator
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-codebase-cleanup
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: fix
+      description: Enable convergence-based auto-fix (default detect+report only)
+      required: false
+    - name: dead-code-only
+      description: Skip architecture checks
+      required: false
+    - name: architecture-only
+      description: Skip dead code checks
+      required: false
+    - name: dry-run
+      description: Show what would be fixed without applying
+      required: false
+    - name: ci
+      description: Non-interactive mode (safe fixes only, report everything else)
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-codebase-cleanup
+    path: string
+type: flexible
+tier: 2
+phases:
+  - name: context
+    description: Run hotspot detection, build churn map
+    required: true
+  - name: detect
+    description: Run dead code and architecture detection in parallel
+    required: true
+  - name: classify
+    description: Classify findings, apply hotspot downgrade, cross-concern dedup
+    required: true
+  - name: fix
+    description: Convergence loop - apply safe fixes, verify, re-detect
+    required: false
+  - name: report
+    description: Generate actionable report of fixes applied and remaining findings
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on:
+  - cleanup-dead-code
+  - enforce-architecture
+  - harness-hotspot-detector

package/dist/agents/skills/codex/harness-compliance/SKILL.md

@@ -0,0 +1,303 @@
+# Harness Compliance
+
+> SOC2, HIPAA, GDPR compliance checks, audit trails, and regulatory checklists. Scans codebases for compliance-relevant patterns, classifies data by sensitivity, audits implementation against framework-specific controls, and generates gap analysis reports with remediation plans.
+
+## When to Use
+
+- At milestone boundaries to audit compliance posture before releases to regulated markets
+- On PRs that modify data handling, storage, logging, or user-facing privacy features
+- When preparing for external audits (SOC2 Type II, HIPAA assessment, GDPR DPA review)
+- NOT for runtime security scanning or vulnerability detection (use harness-security-scan)
+- NOT for authentication or authorization implementation (use harness-auth)
+- NOT for infrastructure security hardening (use harness-security-review)
+
+## Process
+
+### Phase 1: SCAN -- Detect Applicable Frameworks and Data Patterns
+
+1. **Identify applicable compliance frameworks.** Scan for indicators:
+   - SOC2: presence of `docs/compliance/soc2/`, audit logging implementation, access control patterns
+   - HIPAA: healthcare-related data models (patient, diagnosis, prescription), PHI field markers
+   - GDPR: EU user data handling, consent collection, cookie banners, privacy policy references
+   - PCI-DSS: payment processing, credit card fields, tokenization, PCI scope markers
+   - Detect from existing compliance documentation, data models, and configuration files
+
+2. **Inventory data stores.** Map all locations where user data is persisted:
+   - Databases: table schemas, column names, migration files
+   - Object storage: S3 buckets, GCS buckets, Azure Blob containers
+   - Caches: Redis keys, Memcached namespaces
+   - Log files: structured logging output, log aggregation configuration
+   - Third-party services: analytics (Segment, Mixpanel), CRM (Salesforce, HubSpot), email (SendGrid, Mailchimp)
+
+3. **Trace data flows.** Map how user data moves through the system:
+   - Ingestion: API endpoints that accept user input, form submissions, file uploads
+   - Processing: services that transform, aggregate, or enrich user data
+   - Storage: where processed data is persisted (primary database, cache, search index)
+   - Egress: data shared with third parties, exported, or displayed to other users
+   - Deletion: how data is removed when retention expires or deletion is requested
+
+4. **Check for existing compliance artifacts.** Look for:
+   - Privacy policy: `PRIVACY.md`, `privacy-policy.md`, or served via web route
+   - Security policy: `SECURITY.md`, security disclosure process
+   - Data processing agreements: `docs/compliance/dpa/`
+   - Audit trail implementation: `src/**/audit/**`, event sourcing patterns
+   - Consent management: cookie consent banners, preference centers
+
+5. **Detect sensitive data patterns.** Grep for fields and patterns that indicate regulated data:
+   - PII: email, phone, address, SSN, date of birth, government ID
+   - PHI: diagnosis, treatment, prescription, medical record number, insurance ID
+   - Financial: credit card number, bank account, routing number, transaction amount
+   - Authentication: password (even hashed), API key, secret, token
+
+---
+
+### Phase 2: CLASSIFY -- Data Sensitivity and Regulatory Scope
+
+1. **Classify data fields by sensitivity.** Apply a tiered classification:
+   - **Critical:** Data whose exposure triggers mandatory breach notification (SSN, credit card, PHI)
+   - **Sensitive:** PII that identifies individuals (email, phone, address, name + DOB)
+   - **Internal:** Business data not publicly available (order history, usage metrics, preferences)
+   - **Public:** Data intentionally shared (username, public profile, published content)
+
+2. **Map regulatory scope per data class.** Determine which frameworks apply to each data class:
+   - Critical financial data -> PCI-DSS scope
+   - PHI data -> HIPAA scope
+   - EU resident PII -> GDPR scope
+   - All customer data in a SOC2-audited system -> SOC2 scope
+
+3. **Identify cross-border data flows.** For GDPR compliance:
+   - Where are data stores physically located? (AWS region, GCP region, Azure region)
+   - Does data transfer to non-EU countries? (US servers, CDN nodes, third-party processors)
+   - Are Standard Contractual Clauses (SCCs) or adequacy decisions in place?
+   - Is data residency configurable per tenant?
+
+4. **Document data retention policies.** For each data class:
+   - What is the defined retention period?
+   - Is automatic deletion implemented (TTL, scheduled job, lifecycle policy)?
+   - What happens to data in backups after retention expires?
+   - Are retention policies documented and accessible?
+
+5. **Produce the data classification matrix.** Output a structured inventory:
+   - Data field, classification tier, applicable frameworks, storage location, retention policy, encryption status
+
+---
+
+### Phase 3: AUDIT -- Check Against Framework Controls
+
+1. **SOC2 Trust Services Criteria audit.** Check implementation against key controls:
+   - **CC6.1 (Logical Access):** Are all endpoints authenticated? Is RBAC/ABAC enforced?
+   - **CC6.2 (Credential Management):** Are passwords hashed with strong algorithms? Is MFA available?
+   - **CC6.3 (Encryption):** Is data encrypted at rest (database, file storage) and in transit (TLS)?
+   - **CC7.2 (System Monitoring):** Are security events logged? Are alerts configured for anomalies?
+   - **CC8.1 (Change Management):** Is there a code review process? Are deployments auditable?
+
+2. **HIPAA Security Rule audit.** If PHI is present:
+   - **164.312(a)(1) Access Control:** Unique user identification, emergency access, automatic logoff, encryption
+   - **164.312(b) Audit Controls:** Record and examine activity in information systems containing PHI
+   - **164.312(c)(1) Integrity:** Protect electronic PHI from improper alteration or destruction
+   - **164.312(d) Authentication:** Verify identity of person or entity seeking access to PHI
+   - **164.312(e)(1) Transmission Security:** Encrypt PHI during electronic transmission
+
+3. **GDPR compliance audit.** If EU data is processed:
+   - **Article 6 (Lawful Basis):** Is consent collected? Is legitimate interest documented?
+   - **Article 13/14 (Transparency):** Is a privacy notice provided at data collection points?
+   - **Article 15 (Right of Access):** Can users export their data? Is there a data export endpoint?
+   - **Article 17 (Right to Erasure):** Can users request deletion? Is it implemented across all stores?
+   - **Article 25 (Data Protection by Design):** Are privacy defaults enforced (minimal data collection)?
+   - **Article 30 (Records of Processing):** Is there a processing activities register?
+   - **Article 32 (Security of Processing):** Encryption, pseudonymization, resilience, regular testing
+   - **Article 33 (Breach Notification):** Is there a 72-hour breach notification process?
+
+4. **PCI-DSS audit.** If payment data is present:
+   - **Requirement 3:** Is cardholder data encrypted at rest? Is PAN masked in displays?
+   - **Requirement 4:** Is cardholder data encrypted in transit?
+   - **Requirement 6:** Are secure development practices followed? Is input validated?
+   - **Requirement 8:** Is access to cardholder data authenticated and authorized?
+   - **Requirement 10:** Are all access events to cardholder data logged?
+
+5. **Audit trail verification.** For all applicable frameworks:
+   - Are audit events immutable (append-only log, write-once storage)?
+   - Do audit records include who, what, when, where, and outcome?
+   - Is the audit log protected from tampering (separate access controls, checksums)?
+   - Is the audit log retained for the required period (SOC2: 1 year, HIPAA: 6 years, GDPR: varies)?
+
+---
+
+### Phase 4: REPORT -- Generate Gap Analysis and Remediation Plan
+
+1. **Score compliance posture per framework.** For each applicable framework:
+   - Total controls assessed
+   - Controls fully met, partially met, and not met
+   - Overall compliance percentage
+   - Risk rating: High (critical controls missing), Medium (non-critical gaps), Low (minor gaps)
+
+2. **Produce the gap analysis.** For each control not fully met:
+   - Control identifier and description
+   - Current implementation status (not started, partial, misconfigured)
+   - Specific code locations or configurations that need change
+   - Remediation steps with effort estimate (hours/days)
+   - Priority based on risk and audit timeline
+
+3. **Generate audit-ready checklists.** Produce framework-specific checklists:
+   - SOC2: Trust Services Criteria checklist with evidence references
+   - HIPAA: Security Rule safeguard checklist with implementation status
+   - GDPR: Article-by-article compliance checklist with data flow references
+   - PCI-DSS: Requirement checklist with scope boundaries
+
+4. **Create remediation plan.** Organize gaps into actionable work:
+   - **Phase 1 (Critical, 0-2 weeks):** Fix blocking gaps that would fail an audit
+   - **Phase 2 (Important, 2-6 weeks):** Address significant gaps that reduce compliance posture
+   - **Phase 3 (Improvement, 6-12 weeks):** Enhance documentation, monitoring, and process maturity
+   - Each item includes: description, affected control, owner placeholder, effort estimate
+
+5. **Output the compliance report.** Generate `docs/compliance/audit-report-YYYY-MM-DD.md`:
+
+   ```
+   Compliance Audit Report — YYYY-MM-DD
+
+   Frameworks Assessed: SOC2, GDPR
+   Data Classifications: 12 critical, 28 sensitive, 45 internal, 15 public
+
+   SOC2 Status: 78% (18/23 controls met, 3 partial, 2 not met)
+     NOT MET:
+       CC7.2 — No security event alerting configured
+       CC8.1 — No deployment audit trail
+     PARTIAL:
+       CC6.1 — RBAC exists but 4 endpoints lack authorization checks
+       CC6.3 — TLS in transit, but database encryption at rest not configured
+       CC6.2 — Passwords hashed, but no MFA available
+
+   GDPR Status: 65% (11/17 controls met, 4 partial, 2 not met)
+     NOT MET:
+       Article 17 — No data deletion endpoint implemented
+       Article 30 — No processing activities register
+     PARTIAL:
+       Article 15 — Data export exists but incomplete (missing analytics data)
+       ...
+
+   Remediation Plan: 7 items (2 critical, 3 important, 2 improvement)
+   Estimated total effort: 45 engineering-hours
+   ```
+
+---
+
+## Harness Integration
+
+- **`harness skill run harness-compliance`** -- Primary CLI entry point. Runs all four phases.
+- **`harness validate`** -- Run after generating compliance artifacts to verify project structure.
+- **`harness check-deps`** -- Verify that compliance-related dependencies (audit logging libraries, encryption modules) are declared.
+- **`emit_interaction`** -- Used at framework selection (checkpoint:decision) when multiple frameworks apply and the team wants to prioritize, and at remediation plan review (checkpoint:human-verify).
+- **`Glob`** -- Discover compliance documentation, audit trail implementations, privacy policies, and data models.
+- **`Grep`** -- Search for PII field patterns, encryption configurations, consent collection, logging patterns, and sensitive data handling.
+- **`Write`** -- Generate compliance reports, audit checklists, and remediation plans.
+- **`Edit`** -- Update existing compliance documentation with current audit status.
+
+## Success Criteria
+
+- All applicable compliance frameworks are identified with justification for inclusion
+- Data classification matrix covers all persisted user data fields with sensitivity tier and storage location
+- Audit checks reference specific framework control identifiers (SOC2 CC6.1, GDPR Article 17, etc.)
+- Gap analysis includes specific file locations and code references, not just abstract control descriptions
+- Remediation plan items have effort estimates and are prioritized by risk and audit timeline
+- Audit-ready checklists can be handed directly to an external auditor as evidence documentation
+
+## Examples
+
+### Example: SaaS Application with SOC2 and GDPR Requirements
+
+```
+Phase 1: SCAN
+  Frameworks detected:
+    - SOC2: docs/compliance/soc2/ directory exists, audit logging in src/audit/
+    - GDPR: EU customers present (detected from i18n locales and privacy policy)
+    - PCI-DSS: Not applicable (payments via Stripe, card data never touches servers)
+  Data stores: PostgreSQL (primary), Redis (cache/sessions), S3 (file uploads)
+  Third-party processors: Stripe, SendGrid, Segment, Datadog
+
+Phase 2: CLASSIFY
+  Critical: None (no SSN, card data handled by Stripe)
+  Sensitive: email, phone, address (users table), IP address (access_logs)
+  Internal: order_history, preferences, usage_metrics
+  Public: username, display_name, avatar_url
+  Cross-border: Primary DB in us-east-1, CDN globally, Segment data to US
+  GDPR gap: No SCCs documented for US-based sub-processors
+
+Phase 3: AUDIT
+  SOC2: 78% compliant (18/23)
+    CC6.3 — PostgreSQL not using column-level encryption for sensitive fields
+    CC7.2 — Datadog alerts exist but no security-specific monitors
+  GDPR: 65% compliant (11/17)
+    Article 17 — DELETE /api/users/:id exists but does not cascade to S3 files or Segment
+    Article 30 — No Records of Processing Activities document
+
+Phase 4: REPORT
+  Generated: docs/compliance/audit-report-2026-03-27.md
+  Remediation plan:
+    Critical (week 1-2):
+      1. Implement cascading deletion across PostgreSQL, S3, Segment, SendGrid
+      2. Create Records of Processing Activities document
+    Important (week 3-6):
+      3. Add column-level encryption for email, phone, address fields
+      4. Create security-specific Datadog monitors for auth failures
+      5. Document SCCs for all US-based sub-processors
+    Improvement (week 7-12):
+      6. Implement data export endpoint including Segment analytics data
+      7. Add automated retention enforcement with TTL-based cleanup jobs
+```
+
+### Example: Healthcare Platform with HIPAA Requirements
+
+```
+Phase 1: SCAN
+  Frameworks detected:
+    - HIPAA: patient, diagnosis, prescription models in src/models/
+    - SOC2: Required by enterprise customers, docs/compliance/soc2/ present
+  Data stores: PostgreSQL (primary), Redis (session cache), AWS S3 (medical records)
+  Third-party processors: Twilio (patient notifications), AWS (infrastructure)
+  BAA status: AWS BAA signed, Twilio BAA signed
+
+Phase 2: CLASSIFY
+  Critical (PHI):
+    - patient_records: name, DOB, SSN, diagnosis_code, treatment_plan
+    - prescriptions: medication, dosage, prescribing_physician
+    - medical_images: stored in S3 bucket 'patient-records-prod'
+  Sensitive: provider email, staff credentials, appointment schedules
+  PHI field count: 23 fields across 8 tables
+
+Phase 3: AUDIT
+  HIPAA Security Rule: 72% compliant
+    164.312(a)(1) — Access control exists but no automatic session logoff
+    164.312(b) — Audit log captures reads but not all PHI access events
+    164.312(c)(1) — No integrity checksums on medical records in S3
+    164.312(e)(1) — TLS 1.2 in transit, AES-256 at rest in PostgreSQL and S3
+  SOC2: 81% compliant
+    All findings overlap with HIPAA gaps
+
+Phase 4: REPORT
+  Generated: docs/compliance/hipaa-audit-2026-03-27.md
+  Remediation plan:
+    Critical (week 1-2):
+      1. Add automatic session timeout (15 min idle) for clinical users
+      2. Extend audit logging to capture all PHI read events with user context
+      3. Add SHA-256 integrity checksums to S3 medical record objects
+    Important (week 3-6):
+      4. Implement minimum necessary access — restrict PHI queries to treating providers
+      5. Add PHI access review report for compliance officer (monthly)
+    Improvement (week 7-12):
+      6. Implement emergency access ("break the glass") with post-access audit
+      7. Add automated HIPAA compliance regression tests to CI pipeline
+```
+
+## Gates
+
+- **No compliance report without data classification.** A compliance audit that does not inventory and classify data fields is incomplete. The classification matrix must be produced before controls can be meaningfully assessed. Without knowing what data exists and where, control checks are theoretical.
+- **No critical control gaps left without remediation plan.** Every control marked "not met" must have a corresponding remediation item with effort estimate and priority. Identifying gaps without a path to closure is shelf-ware.
+- **No PII/PHI field handling changes without re-audit.** When a PR adds or modifies fields classified as sensitive or critical, the compliance audit for affected frameworks must be re-run. Data handling changes can invalidate previous compliance assessments.
+- **No third-party data sharing without documented basis.** Every third-party that receives user data must have a documented lawful basis (GDPR), BAA (HIPAA), or be within scope boundaries (SOC2/PCI-DSS). Undocumented data sharing is a blocking compliance gap.
+
+## Escalation
+
+- **When compliance requirements conflict with business timelines:** Report: "The GDPR Article 17 implementation requires [N] engineering-hours and touches [M] services. If the audit deadline is [date], recommend prioritizing the critical controls and documenting a remediation timeline for the remaining gaps. Partial compliance with a credible plan is better than no plan."
+- **When legal interpretation is needed:** Report: "The application of [specific regulation article] to [specific data handling pattern] requires legal interpretation. This skill identifies technical implementation gaps but cannot determine legal applicability. Recommend consulting with legal counsel on [specific question]."
+- **When third-party processors lack required agreements:** Report: "[Processor] handles [data type] but no [BAA/DPA/SCC] is on file. This is a blocking compliance gap. Options: (1) execute the required agreement with the processor, (2) migrate to an alternative processor with agreements in place, (3) stop sending regulated data to this processor."
+- **When audit trail implementation requires significant architecture changes:** Report: "The current logging infrastructure does not support immutable, tamper-evident audit trails required by [framework]. Options: (1) add append-only audit table with separate write credentials, (2) use a dedicated audit service (e.g., AWS CloudTrail, custom event store), (3) adopt event sourcing for regulated data flows. Effort estimate: [N] weeks."