mindforge-cc 11.3.0 → 11.4.0

package/.claude/commands/mindforge/context-budget.md

@@ -0,0 +1,70 @@
+---
+description: "Analyze and optimize context window allocation. Usage: /mindforge:context-budget [--analyze] [--optimize] [--max-tokens N]"
+---
+
+<objective>
+Analyze and optimize context window allocation to maximize signal density, ensuring the most relevant information occupies the available token budget while pruning low-value content.
+</objective>
+
+<execution_context>
+@.mindforge/skills/context-engineering/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (optional --analyze for audit, --optimize for active pruning, --max-tokens N for budget cap)
+Knowledge: Current context items, token costs, relevance scoring, compaction strategies.
+</context>
+
+<process>
+1. **Inventory current context items**: Catalog everything in the active context:
+   - System prompts and instructions (CLAUDE.md, rules, project docs)
+   - Conversation history (messages, tool calls, results)
+   - Injected files and code snippets
+   - Skill definitions and execution contexts
+   - State files (HANDOFF.json, auto-state.json)
+   - Measure token count per item using tiktoken estimation
+
+2. **Measure token costs per item**: For each context item:
+   - Calculate raw token count
+   - Assess information density (unique facts per 100 tokens)
+   - Score temporal relevance (how recently referenced)
+   - Score task relevance (direct bearing on current objective)
+   - Identify redundancy (same info stated multiple ways)
+   - Flag stale items (conversation turns > 10 back with no references)
+
+3. **Prioritize by relevance**: Apply the priority matrix:
+   - P0 (Critical): Active task instructions, current file contents, error messages
+   - P1 (High): Architecture context, type definitions, test fixtures
+   - P2 (Medium): Historical decisions, related file contents, examples
+   - P3 (Low): General documentation, old conversation turns, verbose outputs
+   - Score each item 0-10 on task alignment
+
+4. **Apply budget allocation (60/20/10/10)**: Distribute max-tokens:
+   - 60% — Active working context (current files, task, instructions)
+   - 20% — Supporting context (types, tests, architecture docs)
+   - 10% — History and decisions (conversation, rationale)
+   - 10% — Buffer for tool results and new information
+   - Adjust ratios based on task type (debugging needs more history)
+
+5. **Identify compaction candidates**: Find items that can be compressed:
+   - Long tool outputs that can be summarized (test results → pass/fail counts)
+   - Verbose file contents where only specific functions matter
+   - Repeated context that can be deduplicated
+   - Conversation segments that can be summarized into key decisions
+   - Large code blocks where only the interface/signature matters
+
+6. **Prune low-value items**: Remove or compress based on scoring:
+   - Drop items scoring < 3 on task relevance
+   - Summarize items scoring 3-5 into single-line references
+   - Compact items scoring 5-7 to essential excerpts
+   - Keep items scoring 7+ in full
+   - Document what was pruned for recovery if needed
+
+7. **Verify essentials retained**: Post-optimization validation:
+   - Confirm all P0 items are present in full
+   - Verify no broken references (file mentioned but content pruned)
+   - Check that task can still be completed with remaining context
+   - Ensure error context is preserved for debugging tasks
+   - Calculate final utilization percentage and headroom
+   - Output budget report with before/after comparison
+</process>

package/.claude/commands/mindforge/contract-test.md

@@ -0,0 +1,30 @@
+---
+description: "Design consumer-driven contract test suite. Usage - /mindforge:contract-test [service] [--consumer|--provider] [--broker]"
+---
+
+<objective>
+Design and implement a consumer-driven contract testing strategy that validates
+service interactions at integration boundaries without requiring full end-to-end
+environments. Ensures providers never break consumer expectations.
+</objective>
+
+<execution_context>
+@.mindforge/skills/contract-testing/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Identify all consumers and providers for the target service. Map the dependency graph showing which services call which endpoints.
+2. Define consumer expectations as explicit contract specifications — request shape, response shape, status codes, and headers that each consumer relies on.
+3. Generate Pact files (or equivalent contract format) from consumer test suites. Each consumer writes tests that describe what it expects from the provider.
+4. Set up a contract broker (Pact Broker or PactFlow) to store and version contracts. Configure webhook notifications for new contracts published.
+5. Verify the provider against all published consumer contracts. Run provider verification tests that replay consumer expectations against the real provider.
+6. Integrate contract tests into CI pipeline — consumer tests run on consumer PRs, provider verification runs on provider PRs. Block merges on contract failures.
+7. Configure can-i-deploy checks to gate deployments. Before any service deploys, verify its contracts are satisfied by the currently-deployed versions of its dependencies.
+8. Set up contract versioning strategy (git SHA or semantic) and configure participant version selectors (latest from main, deployed environments).
+9. Document the contract testing workflow: how to add new interactions, how to handle breaking changes, and how to use pending/WIP pacts for new consumers.
+10. Log contract-test invocation in AUDIT with: service, role (consumer/provider), broker configured, interactions count.
+</process>

package/.claude/commands/mindforge/cost-report.md

@@ -0,0 +1,44 @@
+---
+description: "Token usage analytics, model routing decisions, and cost optimization recommendations. Usage - /mindforge:cost-report [--window 7d] [--by-model] [--by-task] [--phase N]"
+---
+
+<objective>
+Produce a detailed cost and token usage report from the token-ledger, showing
+spend by model, by task type, and recommending optimizations.
+</objective>
+
+<execution_context>
+@.mindforge/engine/cost-tracking/token-ledger.md
+@.mindforge/engine/cost-tracking/router.md
+@.mindforge/engine/cost-tracking/budget-enforcer.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Parse flags: --window (time period, default: current session), --by-model, --by-task, --phase.
+2. Read `.mindforge/metrics/token-ledger.jsonl` for the specified window.
+3. **Compute totals:**
+   - Total tokens (input, output, cached)
+   - Total estimated cost (USD)
+   - Budget remaining (session, project-weekly)
+4. **By-model breakdown** (if --by-model or default):
+   - For each model used: calls, tokens, cost, % of total
+   - Identify the most expensive model and its usage pattern
+5. **By-task breakdown** (if --by-task):
+   - For each task type: avg cost, avg tokens, count
+   - Identify tasks where cheaper models could have sufficed
+6. **Efficiency metrics:**
+   - Cache hit rate (cached_input / total_input)
+   - Routing accuracy (% of tasks where tier matched actual need)
+   - Over-spend rate (tasks exceeding estimate by >2x)
+7. **Optimization recommendations:**
+   - Tasks using opus that could use sonnet
+   - Repeated context that could benefit from caching
+   - Tasks that could be batched for efficiency
+8. Present report in formatted table.
+9. Compare against budget limits from config.json.
+10. If approaching warn threshold: alert user with projection.
+</process>

package/.claude/commands/mindforge/costs.md

@@ -0,0 +1,15 @@
+---
+description: "Real-time cost tracking for all AI model usage."
+---
+
+# MindForge v2 — Costs Command
+# Usage: /mindforge:costs [--phase N] [--session ID] [--window 7d]
+
+## Purpose
+Real-time cost tracking for all AI model usage.
+Enforce daily budgets and see per-model spend.
+
+## Metrics
+- Total spend: $X.XX
+- Daily limit usage: XX%
+- Per-model breakdown (Tokens/Cost)

package/.claude/commands/mindforge/council.md

@@ -0,0 +1,83 @@
+---
+description: "Invoke the 4-voice decision council (Architect, Skeptic, Pragmatist, Critic) for ambiguous architectural decisions. Usage - /mindforge:council [decision description] [--id decision-id]"
+---
+
+<objective>
+Run a structured multi-voice debate to resolve an ambiguous decision. Four specialist
+voices (Architect, Skeptic, Pragmatist, Critic) analyze the decision via the
+council-runtime engine, producing a verdict with consensus scoring and documented dissent.
+</objective>
+
+<execution_context>
+@bin/engine/council-runtime.js
+@bin/council-cli.js
+@.mindforge/engine/council/council-protocol.md
+@.mindforge/engine/council/council-templates.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Parse the decision description from $ARGUMENTS. Extract --id if provided.
+
+2. **Execute the council runtime** by running:
+   ```bash
+   node bin/council-cli.js --id "<decision-id>" "<the full question>"
+   ```
+   - If no --id is provided, omit it (the runtime defaults to "council-latest").
+   - The CLI outputs structured JSON to stdout and a human-readable summary to stderr.
+   - Capture the JSON output for formatting.
+
+3. **Parse the JSON result** which has this shape:
+   ```json
+   {
+     "question": "...",
+     "positions": [
+       { "voice": "architect", "recommendation": "PROCEED|REVISE", "confidence": 0.0-1.0, "rationale": "..." },
+       ...
+     ],
+     "consensus": 0.0-1.0,
+     "verdict": "PROCEED|REVISE|NO_CONSENSUS",
+     "dissent": [...]
+   }
+   ```
+
+4. **Present the structured result** to the user in this format:
+
+   ### Council Verdict
+
+   **Question:** <the question>
+
+   #### Positions
+
+   For each position:
+   - **[VOICE]** — <RECOMMENDATION> (confidence: <N.NN>)
+     > <rationale>
+
+   #### Consensus: <X.X%>
+
+   #### Verdict: <PROCEED / REVISE / NO_CONSENSUS>
+
+   If NO_CONSENSUS — show the full dissent split (all voices with their stances).
+   If PROCEED or REVISE — show only the dissenting voices.
+
+5. **Decision record** — The runtime automatically writes the decision to
+   `.planning/decisions/council-<id>.json`. Confirm the file path to the user.
+
+6. Log council invocation in AUDIT with: decision, voices, consensus, verdict.
+
+7. Remind user: "Council is advisory — you have final say."
+
+**Exit codes from the CLI:**
+- 0 = PROCEED
+- 1 = REVISE
+- 2 = NO_CONSENSUS
+- 3 = Error (show the error message)
+
+**If the CLI fails** (exit code 3 or missing API keys), fall back to the prose-based
+council protocol: run the debate manually using the 4 voice personas and synthesize
+a verdict using the consensus algorithm (mean approval signal where PROCEED contributes
+confidence and REVISE contributes 1-confidence; threshold 0.75).
+</process>

package/.claude/commands/mindforge/create-skill.md

@@ -0,0 +1,34 @@
+---
+description: "Interactive skill creation with eval loop and trigger optimization. Usage - /mindforge:create-skill [name] [--from-instinct inst-xxx] [--iterate N]"
+---
+
+<objective>
+Author a new MindForge skill iteratively using interview-driven capture,
+parallel eval comparison (with-skill vs baseline), and trigger optimization.
+</objective>
+
+<execution_context>
+@.mindforge/skills/skill-creator-meta/SKILL.md
+@.mindforge/skills/eval-harness/SKILL.md
+@.mindforge/org/skills/MANIFEST.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. If --from-instinct provided: load instinct as starting point for skill content.
+2. Interview: what does the skill do? When should it trigger? What output format? Edge cases?
+3. Generate draft SKILL.md following schema (frontmatter + body, under 500 lines).
+4. Create test cases in `.mindforge/evals/[name]/test-cases.json` (2-3 realistic prompts).
+5. Run parallel eval: with-skill vs baseline (no-skill) for each test case.
+6. Draft assertions (objectively verifiable), grade outputs, aggregate to benchmark.json.
+7. Create 20 trigger evaluation queries: 10 should-trigger, 10 should-NOT-trigger.
+8. Run trigger optimization (up to 5 iterations on name/description/triggers).
+9. Present results to user: benchmark scores + trigger accuracy.
+10. If user provides feedback: improve skill, retest in next iteration directory.
+11. Repeat until user approves or --iterate limit reached.
+12. On approval: register in MANIFEST.md, verify no trigger conflicts with existing skills.
+13. Log skill creation event in AUDIT.
+</process>

package/.claude/commands/mindforge/cross-review.md

@@ -0,0 +1,21 @@
+---
+description: "Get the same code diff reviewed by multiple AI models simultaneously."
+---
+
+# MindForge v2 — Cross-Review Command
+# Usage: /mindforge:cross-review [--phase N] [--models list] [--focus area]
+
+## Purpose
+Get the same code diff reviewed by multiple AI models simultaneously.
+Claude finds what Claude finds. GPT-4o finds what GPT-4o finds.
+Consensus findings = high confidence issues.
+
+## Round 1: Primary (Claude)
+Senior architect review.
+
+## Round 2: Adversarial (GPT-4o)
+Critical security and edge case review.
+
+## Synthesis
+Consensus detector filters findings.
+Verdict is gating for `/mindforge:ship`.

package/.claude/commands/mindforge/dashboard.md

@@ -0,0 +1,102 @@
+---
+description: "Start the MindForge real-time web dashboard — a live observability UI for the"
+---
+
+# MindForge v2 — Dashboard Command
+# Usage: /mindforge:dashboard [--port 7339] [--open] [--stop] [--status]
+# Version: v2.0.0-alpha.5
+
+## Purpose
+Start the MindForge real-time web dashboard — a live observability UI for the
+entire team. Shows execution progress, quality metrics, pending approvals,
+knowledge graph, and team activity without requiring CLI access.
+
+## Design
+The dashboard is a localhost-only web server:
+- No build step — single HTML file, no bundler, no npm packages on client
+- No authentication — binding to 127.0.0.1 is the security model
+- Live updates via Server-Sent Events — no WebSocket library needed
+- Designed for screensharing at standups, not external access
+
+## Usage
+
+### Start the dashboard
+```
+/mindforge:dashboard
+→ Dashboard running at: http://localhost:7339
+→ Press CTRL+C to stop (or /mindforge:dashboard --stop)
+```
+
+### Start and open in browser
+```
+/mindforge:dashboard --open
+→ Opens http://localhost:7339 in your default browser
+```
+
+### Custom port
+```
+/mindforge:dashboard --port 7340
+→ Useful if 7339 is already in use
+```
+
+### Stop the dashboard
+```
+/mindforge:dashboard --stop
+→ Finds the running dashboard process (from PID file) and sends SIGTERM
+```
+
+### Check dashboard status
+```
+/mindforge:dashboard --status
+→ Checks if dashboard is running, shows port and PID
+→ Also shows: http://localhost:7339/api/status
+```
+
+## Dashboard pages
+
+### Activity (default)
+- Phase name, auto mode status (RUNNING/PAUSED/ESCALATED/IDLE)
+- Wave progress bar (tasks completed / total)
+- Live AUDIT event feed with color-coded event types
+- Steering input: send guidance to auto mode without touching the CLI
+
+### Quality Metrics
+- Session quality score trend (last 20 sessions)
+- Verify pass rate over time
+- Security findings by severity (CRITICAL/HIGH/MEDIUM/LOW)
+- Cost per session trend
+
+### Approvals
+- All pending Tier 2/3 governance requests
+- [Approve] and [Reject] buttons — no CLI needed for approval
+- Tier, phase/plan, description, time since requested, expiry warning
+- Recent approval history
+
+### Knowledge
+- Search the knowledge graph from the browser
+- Entries filtered by confidence, type, tags
+- Color-coded by knowledge type
+
+### Team
+- Active developers (by git email, from AUDIT.jsonl)
+- What each person is working on (last task)
+- File conflict warnings (two developers recently touching the same file)
+
+## Security rules
+1. Never expose the dashboard on 0.0.0.0 — localhost only
+2. Never forward the port externally (no ngrok, no port forwarding)
+3. For remote team visibility: screenshare your browser instead
+4. The dashboard shows project details including code patterns and decisions
+
+## Integration with auto mode
+When `/mindforge:auto` is running and the dashboard is open:
+- Activity feed updates live as tasks complete
+- Wave progress bar advances in real-time
+- Any escalations appear immediately with red indicator
+- The Steering input is active — inject guidance without a second terminal
+
+## AUDIT entry
+```json
+{ "event": "dashboard_started", "port": 7339, "pid": 12345 }
+{ "event": "dashboard_stopped", "pid": 12345 }
+```

package/.claude/commands/mindforge/data-mesh.md

@@ -0,0 +1,31 @@
+---
+name: "mindforge:data-mesh"
+description: "Design data mesh architecture. Usage: /mindforge:data-mesh [organization] [--domains number] [--governance federated|centralized]"
+argument-hint: "[organization] [--domains number] [--governance federated|centralized]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design comprehensive data-mesh system architecture with best practices and production-ready patterns.
+</objective>
+
+<execution_context>
+@.mindforge/skills/data-mesh/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/data-mesh/`
+State: Analyzes requirements, constraints, and scale to generate optimized data-mesh architecture.
+</context>
+
+<process>
+1. **Requirement Analysis**: Analyze domain-specific requirements, performance constraints, and scalability needs.
+2. **Architecture Design**: Design system architecture with component interaction patterns and data flow.
+3. **Technology Selection**: Evaluate and select appropriate technologies, tools, and frameworks.
+4. **Integration Strategy**: Define integration patterns with existing systems and external dependencies.
+5. **Optimization Approach**: Implement performance, cost, and resource optimization strategies.
+6. **Monitoring Framework**: Design observability, alerting, and debugging mechanisms.
+7. **Deployment Planning**: Create deployment strategy with rollback procedures and disaster recovery.
+</process>

package/.claude/commands/mindforge/data-model.md

@@ -0,0 +1,75 @@
+---
+description: "Design data schema with evolution strategy. Usage: /mindforge:data-model [domain] [--style oltp|olap|hybrid] [--contracts]"
+---
+
+<objective>
+Design a data schema with proper modeling approach, evolution strategy, data contracts, and lineage documentation for a given domain.
+</objective>
+
+<execution_context>
+@.mindforge/skills/data-modeling/SKILL.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (domain name, optional --style oltp|olap|hybrid, optional --contracts flag)
+Knowledge: Current database schemas, domain model, access patterns, data volume projections.
+</context>
+
+<process>
+1. **Identify entities and relationships**: Map the domain:
+   - List all entities (nouns in the domain: User, Order, Product, etc.)
+   - Define relationships (one-to-one, one-to-many, many-to-many)
+   - Identify aggregates (consistency boundaries)
+   - Mark ownership (which service owns which entity)
+   - Document cardinality estimates (how many of each entity expected)
+   - Identify temporal aspects (does data change over time, need history?)
+
+2. **Choose modeling approach**: Based on --style flag or access patterns:
+   - **OLTP (normalized)**: 3NF for transactional workloads, minimize write anomalies
+   - **OLAP (dimensional)**: Star/snowflake schema for analytical queries, optimize reads
+   - **Hybrid**: Normalized for writes + materialized views for reads
+   - Consider: read/write ratio, query patterns, data volume, consistency requirements
+   - Document trade-offs of chosen approach vs alternatives
+
+3. **Define schema**: For each entity, specify:
+   - Table/collection name (plural, snake_case)
+   - Columns with types, constraints, and descriptions
+   - Primary key strategy (UUID v7 for distributed, SERIAL for simple)
+   - Foreign keys and referential integrity rules
+   - Indexes (covering indexes for hot queries, partial indexes for filtered queries)
+   - Partitioning strategy if data volume warrants it (by time, by tenant)
+   - Soft delete vs hard delete decision per entity
+
+4. **Plan evolution strategy**: Design for safe schema changes:
+   - Additive-only migrations (add columns, add tables — never remove in-place)
+   - Expand-contract pattern for breaking changes (3-phase: add new → migrate data → remove old)
+   - Backward compatibility window (N-1 app version must work with N schema)
+   - Migration testing: run against production-size dataset before deploy
+   - Rollback plan for each migration (reverse migration script)
+   - Version tracking: migration numbering, applied_at timestamps
+
+5. **Define data contracts**: When --contracts flag is set:
+   - Schema contract: exact field types, nullability, enum values
+   - SLA contract: freshness (max age), completeness (% populated), volume (expected range)
+   - Quality contract: uniqueness constraints, valid value ranges, referential integrity
+   - Breaking change policy: versioned contracts, deprecation notices, consumer notification
+   - Contract validation: automated checks in CI pipeline
+   - Owner and consumer registry: who produces, who consumes each dataset
+
+6. **Document lineage**: Trace data flow end-to-end:
+   - Source systems (where data originates)
+   - Transformation steps (ETL/ELT pipeline stages)
+   - Storage layers (raw → cleaned → aggregated → served)
+   - Consumers (which services/dashboards read this data)
+   - Freshness chain (latency from source to each consumer)
+   - Data classification (PII, sensitive, public) per field
+
+7. **Output data model**: Deliver:
+   - Entity-relationship diagram (ASCII or description)
+   - DDL scripts (CREATE TABLE with all constraints)
+   - Migration scripts for initial setup
+   - Index strategy document
+   - Data contract definitions (JSON Schema or Avro)
+   - Lineage diagram
+   - Capacity planning estimates (storage growth per month)
+</process>

package/.claude/commands/mindforge/data-pipeline.md

@@ -0,0 +1,34 @@
+---
+name: "mindforge:data-pipeline"
+description: "Design data pipeline with quality gates. Usage: /mindforge:data-pipeline [domain] [--type batch|streaming|hybrid] [--orchestrator airflow|dagster]"
+argument-hint: "[domain] [--type batch|streaming|hybrid] [--orchestrator airflow|dagster]"
+allowed-tools:
+  - list_dir
+  - view_file
+---
+
+<objective>
+Design a data pipeline architecture with schema enforcement, quality gates, orchestration, and lineage tracking that ensures data freshness SLAs are met with full auditability.
+</objective>
+
+<execution_context>
+@.mindforge/skills/data-pipeline-design/SKILL.md
+</execution_context>
+
+<context>
+Skills Directory: `.mindforge/skills/data-pipeline-design/`
+State: Models data flow from sources through transformations to consumers with quality enforcement at each stage.
+</context>
+
+<process>
+1. **Define Data Sources and Consumers**: Inventory all data producers (APIs, databases, event streams, files) and consumers (analytics, ML models, dashboards, downstream services). Document schema expectations at each boundary.
+2. **Choose Batch vs. Streaming**: Evaluate latency requirements, data volume, and processing complexity to select batch (scheduled ETL), streaming (continuous), or hybrid (lambda/kappa architecture). Document the tradeoff decision.
+3. **Design Schema with Registry**: Define schemas for all pipeline stages using a schema registry (Avro, Protobuf, or JSON Schema). Enforce backward/forward compatibility rules and version evolution strategy.
+4. **Implement Extraction Layer**: Design source connectors with change data capture (CDC) where possible. Handle incremental extraction with watermarks, full refresh fallback, and source system rate limiting.
+5. **Add Quality Gates**: Implement data quality checks at ingestion and transformation boundaries — null rate thresholds, value range validation, freshness checks, row count anomaly detection, and schema conformance verification.
+6. **Configure Orchestration**: Design the DAG with appropriate retry policies, backoff strategies, timeout limits, and dependency management. Include SLA monitoring and alerting for late-running tasks.
+7. **Plan Backfill Strategy**: Design the mechanism for historical data reprocessing — idempotent transformations, partition-based reruns, and backfill scheduling that does not interfere with real-time processing.
+8. **Monitor Freshness SLA**: Define freshness targets per dataset and implement monitoring that tracks end-to-end latency from source event to consumer availability. Alert before SLA breach.
+9. **Document Lineage**: Implement column-level lineage tracking showing data provenance from source through all transformations to final consumption. Enable impact analysis for upstream schema changes.
+10. **Design Failure Recovery**: Specify dead-letter handling, partial failure semantics, exactly-once vs. at-least-once guarantees, and manual intervention procedures for unrecoverable failures.
+</process>

package/.claude/commands/mindforge/de-slop.md

@@ -0,0 +1,33 @@
+---
+description: "Run post-implementation cleanup pass. Removes debug code, test slop, commented blocks, inconsistent naming, and TODO hacks. Usage - /mindforge:de-slop [path] [--dry-run] [--category debug|test|comments|naming|todos|all]"
+---
+
+<objective>
+Dedicated cleanup pass that runs AFTER implementation is complete. Finds and
+fixes cosmetic issues without changing behavior. Each fix is an atomic commit.
+</objective>
+
+<execution_context>
+@.mindforge/skills/de-sloppify/SKILL.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+</context>
+
+<process>
+1. Parse target path (default: current diff) and category filter (default: all).
+2. Run tests BEFORE cleanup to establish baseline (must pass).
+3. Scan for slop by category:
+   - debug: console.log, debugger, print(), var_dump() not behind debug flags
+   - test: skipped tests (@skip without reason), commented test blocks, test-only exports
+   - comments: blocks of 3+ commented lines (dead code, not explanations)
+   - naming: camelCase/snake_case mixing within same file
+   - todos: TODO/FIXME/HACK that are actually shipped workarounds
+4. If --dry-run: report findings only (file:line for each), do not modify.
+5. If not dry-run: fix each category in sequence, one atomic commit per category.
+6. After EACH fix commit: re-run tests. If tests fail → revert that commit, report conflict.
+7. Write CLEANUP-REPORT.md with: category, items found, items fixed, items skipped (with reason).
+8. Report summary: "Cleaned X items across Y categories. Z commits. Tests pass."
+9. Log de-slop event in AUDIT.
+</process>