@heretek-ai/epistemic-swarm 0.5.0 → 0.7.0

package/.agents/skills/factory/SKILL.md

@@ -0,0 +1,13 @@
+# Factory (thin adapter stub)
+
+This file is a POINTER, not the implementation. It exists so harness skill
+discovery finds an entry; the real skill lives in the IUMBTEMS repo.
+
+- Canonical prose & scripts: `skills/factory/`
+- Canonical programmatic surface: `python3 runner/mcp_server.py` (stdio MCP),
+  or one-shot: `python3 runner/mcp_server.py call <tool> '{...json...}'`
+- MCP tools for this skill: `iumbtems_brainstorm`, `iumbtems_darkharvest`, `iumbtems_socratic_frontier`
+
+Epistemic rules apply regardless of harness: tag claims as
+`[VERIFIED: <hash>]`, `[INFERRED: <reasoning>]`, `[HYPOTHESIS: <test>]`, or
+`[NEGATIVE_KNOWLEDGE: <query>]`. Writes go only to `.research/`.

package/.claude-plugin/marketplace.json

@@ -36,6 +36,26 @@
       "category": "research",
       "source": "./plugins/research-cache",
       "homepage": "https://github.com/Heretek-AI/IUMBTEMS"
+    },
+    {
+      "name": "darkharvest",
+      "description": "Product-level competitor teardown and clean-room harvest engine.",
+      "author": {
+        "name": "Heretek AI"
+      },
+      "category": "research",
+      "source": "./plugins/darkharvest",
+      "homepage": "https://github.com/Heretek-AI/IUMBTEMS"
+    },
+    {
+      "name": "factory",
+      "description": "Coding-factory Manager loop with grill-gated phased builds and dual QA.",
+      "author": {
+        "name": "Heretek AI"
+      },
+      "category": "agents",
+      "source": "./plugins/factory",
+      "homepage": "https://github.com/Heretek-AI/IUMBTEMS"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "epistemic-swarm",
-  "version": "0.4.8",
+  "version": "0.7.0",
   "description": "High-Integrity Dialectic Research Agent Harness for Claude Code enforcing empirical evidence over parametric hallucination.",
   "author": {
     "name": "Heretek AI",
@@ -69,6 +69,8 @@
     "./skills/swarm_config",
     "./skills/code_audit",
     "./skills/oss_scout",
-    "./skills/brainstorming"
+    "./skills/brainstorming",
+    "./skills/darkharvest",
+    "./skills/factory"
   ]
 }

package/.omp/commands/domainexpansion.md

@@ -0,0 +1,9 @@
+---
+description: Autonomous agent-guided self-improvement loop (count-flagged)
+---
+
+Run the IUMBTEMS domain-expansion loop for `$1` loops (max 10):
+
+Bypasses per-loop gates; stops on count OR `.factory/STOP` file OR user kill.
+Each loop: agents propose direction, quick swarm check, implement, dual-QA verify.
+Enforce via `python3 skills/factory/scripts/factory.py expansion --run <run> --loops $1`.

package/.omp/commands/factory.md

@@ -0,0 +1,9 @@
+---
+description: Coding-factory Manager loop with grill-gated phased builds
+---
+
+Run the IUMBTEMS coding-factory Manager loop for `$1`:
+
+1. Grill until `.factory/frontier.json` is settled (max 5 swarm cycles per gate); explicit user approve advances each gate.
+2. Per gate: `python3 runner/research_swarm.py --mode brainstorm` plus `--mode darkharvest` (mock-first), then synthesize `.roadmap/<phase>/` GOAL.md + dossier.json.
+3. Programmer subagent per phase; qa-a plus qa-b per phase; retries tracked via `python3 skills/factory/scripts/factory.py` (3 failures escalate).

package/MARKETPLACE.md

@@ -30,6 +30,8 @@ claude plugin marketplace list
 | **`epistemic-swarm`** | `research` | **Flagship Swarm Harness**: Multi-agent dialectic research harness pairing Agent Alpha (Thesis) against Agent Beta (Red Team), audited by an Epistemic Auditor with verbatim empirical quote validation. | `claude plugin install epistemic-swarm@heretek-official` |
 | **`socratic-grilling`** | `agents` | **Socratic Ideation**: Matt Pocock-style Socratic interrogation, premise inversion, and lateral exploration skill. | `claude plugin install socratic-grilling@heretek-official` |
 | **`research-cache`** | `research` | **Source Hasher**: Content-addressed SHA256 Markdown source hashing and verbatim quote verification engine. | `claude plugin install research-cache@heretek-official` |
+| **`darkharvest`** | `research` | **Competitor Teardown**: Product-level teardown with per-feature `depend\|vendor\|clean-room\|skip` verdicts and SPDX attribution. | `claude plugin install darkharvest@heretek-official` |
+| **`factory`** | `agents` | **Coding Factory**: Manager loop with grill-gated phases, programmer spawns, and dual QA. | `claude plugin install factory@heretek-official` |
 
 ---
 
@@ -72,6 +74,32 @@ claude plugin marketplace list
   claude plugin install research-cache@heretek-official
   ```
 
+### 4. `darkharvest` (Modular Tool)
+- **Manifest**: [`plugins/darkharvest/.claude-plugin/plugin.json`](file:///plugins/darkharvest/.claude-plugin/plugin.json)
+- **Components**:
+  - **Skill**: `skills/darkharvest` (competitor × capability teardown).
+  - **Agents**: `harvest-proponent` (per-feature verdicts), `harvest-redteam` (license/Bloat/CVE vetting).
+  - **Evals**: `plugins/darkharvest/evals/teardown-verdict` (skill fires + license-line rubric).
+- **Install**:
+  ```bash
+  claude plugin install darkharvest@heretek-official
+  ```
+
+### 5. `factory` (Modular Agent Pack)
+- **Manifest**: [`plugins/factory/.claude-plugin/plugin.json`](file:///plugins/factory/.claude-plugin/plugin.json)
+- **Components**:
+  - **Skill**: `skills/factory` (Manager loop, gates, QA bounds).
+  - **Agents**: `factory-manager`, `programmer`, `qa-functional`, `qa-adversarial`.
+  - **Evals**: `plugins/factory/evals/gate-halt` (skill fires + gates-first rubric).
+- **Install**:
+  ```bash
+  claude plugin install factory@heretek-official
+  ```
+
+### Flagship agents & evals
+- **Agents** (repo-root `agents/`): `alpha-thesis`, `beta-antithesis`, `epistemic-auditor` — condensed from `prompts/agent_alpha_thesis.md`, `prompts/agent_beta_antithesis.md`, `prompts/epistemic_auditor.md`.
+- **Evals** (repo-root `evals/`): `grill-fires`, `darkharvest-fires`, `factory-gate` — each `prompt.md` plus `tool_used: Skill` and `llm` graders. Run `claude plugin eval .` (billable model calls); CI gates via `.github/workflows/plugin-evals.yml` on release/dispatch.
+
 ---
 
 ## 💡 Lateral Brainstorming (`/brainstorming`)

package/README.md

@@ -149,6 +149,13 @@ iumbtems brainstorm "Where do we go from here?"
 # Product competitor teardown with per-feature harvest verdicts
 iumbtems darkharvest "Paseo-class agent harness competitor" --seeds https://github.com/a/b,https://github.com/c/d --max-repos 6 --mock-claude
 
+# Coding-factory run-state helper (init, phase-add, qa-record, expansion, stop)
+iumbtems factory init --run arena
+iumbtems factory phase-add --run arena --phase 01-handoff --goal "Session handoff" --accept "round-trips;STOP kills loop"
+iumbtems factory expansion --run arena --loops 10
+
+# OpenCode slash commands (also Pi/OMP/Gemini): /factory, /domainexpansion, /darkharvest, /scout, /audit, /grill, /swarm
+
 # Run Socratic grilling and decision frontier calculation
 iumbtems grill --objective "L1 vs L2 state verification trade-offs"
 
@@ -164,6 +171,8 @@ iumbtems test
 - **`/code-audit`**: Dialectic codebase review pairing a Structural Architect (thesis) with a Vulnerability Red-Teamer (antithesis) enforcing line-number proofs (`file:///path#L10-25`).
 - **`/oss-scout`**: Evaluates GitHub repositories, package ecosystems (npm, crates.io, PyPI), license contamination (GPL/AGPL copyleft vs MIT/Apache), and outputs clean-room re-implementation blueprints.
 - **`/darkharvest`**: Product competitor teardown (seed inspirations + prompt, expand to adjacents). Competitor × capability matrix, both-ways white-space gaps, per-feature `depend|vendor|clean-room-rebuild|skip` verdicts with SPDX attribution. Permissive-only vendoring; GPL/AGPL spec-rebuild only.
+- **`/factory`**: Coding-factory Manager loop — grill-gated phased build (manager profile), per-phase programmer spawns, dual QA (3 retries then escalate), explicit sign-off per phase.
+- **`/domainexpansion`**: Autonomous agent-guided self-improvement loop (`/domainexpansion <n>`, max 10); bypasses gates, stops on count OR `.factory/STOP` OR user kill.
 - **`/grilling`**: Socratic assumption-inversion and Matt Pocock-style design tree frontier discovery.
 - **`epistemic_search`**: Zero-key DuckDuckGo Lite search and content-addressed fetch with automatic SHA-256 caching.
 

package/bin/cli.js

@@ -50,6 +50,7 @@ Commands:
   run "<objective>"     Run the dialectic multi-agent research swarm
   brainstorm "<prompt>"  Run lateral brainstorming (feature vectors + spikes)
   darkharvest "<arena>"  Product competitor teardown with harvest verdicts
+  factory <subcommand>  Factory run-state helper (init, phase-add, qa-record, expansion, stop)
   grill                 Launch interactive Socratic decision tree framing
   adapters              Rebuild harness adapter mirrors (skills -> plugins/*, .agents)
   install               Install skills & MCP servers into ~/.claude/
@@ -82,6 +83,7 @@ Examples:
   iumbtems run "Verify sub-millisecond ZK prover latency"
   iumbtems brainstorm "Where do we go from here?"
   iumbtems darkharvest "Paseo-class agent harness competitor" --seeds https://github.com/a/b,https://github.com/c/d --max-repos 6 --mock-claude
+  iumbtems factory init --run arena && iumbtems factory phase-add --run arena --phase 01-x --goal "..." --accept "a;b"
   iumbtems grill --objective "Rollup architecture trade-offs"
   iumbtems doctor
 `);
@@ -174,6 +176,25 @@ switch (command) {
     break;
   }
 
+  case 'factory': {
+    // Factory run-state helper: forward subcommands to skills/factory/scripts/factory.py
+    // e.g. iumbtems factory init --run arena
+    //      iumbtems factory qa-record --run arena --phase 01-x --seat qa-a --verdict pass
+    if (args[1] === '--help' || !args[1]) {
+      console.log([
+        'Usage: iumbtems factory <init|phase-add|qa-record|expansion|stop> [options]',
+        '  init --run <name>',
+        '  phase-add --run <name> --phase <id> --goal "<goal>" --accept "a;b"',
+        '  qa-record --run <name> --phase <id> --seat <qa-a|qa-b> --verdict <pass|fail|conditional> [--reason "..."]',
+        '  expansion --run <name> --loops <n> [--max-loops 10]',
+        '  stop --run <name>   (writes .factory/STOP kill-file)',
+      ].join('\n'));
+      break;
+    }
+    runPython('skills/factory/scripts/factory.py', args.slice(1));
+    break;
+  }
+
   case 'grill': {
     runPython('skills/grilling/socratic_tree.py', args.slice(1));
     break;

package/config/opencode-snippet.json

@@ -99,6 +99,92 @@
         "iumbtems_verify_quote": true,
         "iumbtems_config": true
       }
+    },
+    "manager": {
+      "description": "IUMBTEMS Factory Manager: grill-gated phased builds. Owns gates, swarm dispatch, roadmap synthesis, QA tiebreaks. Never writes code.",
+      "mode": "primary",
+      "temperature": 0.2,
+      "permission": {
+        "edit": "deny",
+        "bash": "ask",
+        "task": {
+          "*": "deny",
+          "factory-*": "allow",
+          "programmer": "allow",
+          "qa-a": "allow",
+          "qa-b": "allow",
+          "brainstormer": "allow",
+          "darkharvester": "allow"
+        }
+      },
+      "tools": {
+        "read": true,
+        "write": true,
+        "grep": true,
+        "glob": true,
+        "task": true,
+        "iumbtems_brainstorm": true,
+        "iumbtems_darkharvest": true,
+        "iumbtems_verify_quote": true,
+        "iumbtems_socratic_frontier": true,
+        "iumbtems_config": true
+      }
+    },
+    "programmer": {
+      "description": "IUMBTEMS Factory Programmer: implements exactly one phase brief per spawn. Cites phase evidence hashes. Never invokes swarms or other programmers.",
+      "mode": "subagent",
+      "temperature": 0.3,
+      "permission": {
+        "edit": "allow",
+        "bash": "ask",
+        "task": {
+          "*": "deny"
+        }
+      },
+      "tools": {
+        "read": true,
+        "write": true,
+        "bash": true,
+        "grep": true,
+        "glob": true,
+        "iumbtems_verify_quote": true
+      }
+    },
+    "qa-a": {
+      "description": "IUMBTEMS Factory QA (functional): verifies phase acceptance criteria pass on the real surface. Read-only plus test execution. Diverged prompt from qa-b.",
+      "mode": "subagent",
+      "temperature": 0.1,
+      "permission": {
+        "edit": "deny",
+        "bash": "ask",
+        "task": {
+          "*": "deny"
+        }
+      },
+      "tools": {
+        "read": true,
+        "bash": true,
+        "grep": true,
+        "glob": true
+      }
+    },
+    "qa-b": {
+      "description": "IUMBTEMS Factory QA (adversarial): hunts edge cases, regressions, and acceptance loopholes the functional pass missed. Read-only plus test execution. Diverged prompt from qa-a.",
+      "mode": "subagent",
+      "temperature": 0.4,
+      "permission": {
+        "edit": "deny",
+        "bash": "ask",
+        "task": {
+          "*": "deny"
+        }
+      },
+      "tools": {
+        "read": true,
+        "bash": true,
+        "grep": true,
+        "glob": true
+      }
     }
   },
   "skills": {
@@ -110,7 +196,8 @@
       "./skills/code_audit",
       "./skills/oss_scout",
       "./skills/brainstorming",
-      "./skills/darkharvest"
+      "./skills/darkharvest",
+      "./skills/factory"
     ]
   }
 }

package/install.sh

@@ -21,7 +21,7 @@ echo "✅ Core prerequisites detected (Python $(python3 --version | cut -d' ' -f
 mkdir -p "$CLAUDE_DIR/skills"
 
 echo "🔗 Linking skills into $CLAUDE_DIR/skills/..."
-for skill in grilling research_cache epistemic_search swarm_config code_audit oss_scout brainstorming; do
+for skill in grilling research_cache epistemic_search swarm_config code_audit oss_scout brainstorming darkharvest factory; do
   # legacy research-cache dir name kept as alias for older configs
   ln -sfn "$REPO_DIR/skills/$skill" "$CLAUDE_DIR/skills/$skill"
   echo "   - $CLAUDE_DIR/skills/$skill -> $REPO_DIR/skills/$skill"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "IUMBTEMS: I Use My Brain To Express My Self — High-Integrity Dialectic Research Agent Harness for Claude Code, OpenCode V2, Pi, OMP (oh-my-pi), Gemini CLI, Codex CLI, and AntiGravity",
   "main": "bin/cli.js",
   "bin": {
@@ -80,7 +80,8 @@
       "./skills/code_audit",
       "./skills/oss_scout",
       "./skills/brainstorming",
-      "./skills/darkharvest"
+      "./skills/darkharvest",
+      "./skills/factory"
     ],
     "prompts": [
       "./prompts/*.md"
@@ -98,7 +99,8 @@
       "./skills/code_audit",
       "./skills/oss_scout",
       "./skills/brainstorming",
-      "./skills/darkharvest"
+      "./skills/darkharvest",
+      "./skills/factory"
     ],
     "prompts": [
       "./prompts/*.md"

package/plugins/antigravity/skills/factory/SKILL.md

@@ -0,0 +1,13 @@
+# Factory (thin adapter stub)
+
+This file is a POINTER, not the implementation. It exists so harness skill
+discovery finds an entry; the real skill lives in the IUMBTEMS repo.
+
+- Canonical prose & scripts: `skills/factory/`
+- Canonical programmatic surface: `python3 runner/mcp_server.py` (stdio MCP),
+  or one-shot: `python3 runner/mcp_server.py call <tool> '{...json...}'`
+- MCP tools for this skill: `iumbtems_brainstorm`, `iumbtems_darkharvest`, `iumbtems_socratic_frontier`
+
+Epistemic rules apply regardless of harness: tag claims as
+`[VERIFIED: <hash>]`, `[INFERRED: <reasoning>]`, `[HYPOTHESIS: <test>]`, or
+`[NEGATIVE_KNOWLEDGE: <query>]`. Writes go only to `.research/`.

package/plugins/codex/skills/factory/SKILL.md

@@ -0,0 +1,13 @@
+# Factory (thin adapter stub)
+
+This file is a POINTER, not the implementation. It exists so harness skill
+discovery finds an entry; the real skill lives in the IUMBTEMS repo.
+
+- Canonical prose & scripts: `skills/factory/`
+- Canonical programmatic surface: `python3 runner/mcp_server.py` (stdio MCP),
+  or one-shot: `python3 runner/mcp_server.py call <tool> '{...json...}'`
+- MCP tools for this skill: `iumbtems_brainstorm`, `iumbtems_darkharvest`, `iumbtems_socratic_frontier`
+
+Epistemic rules apply regardless of harness: tag claims as
+`[VERIFIED: <hash>]`, `[INFERRED: <reasoning>]`, `[HYPOTHESIS: <test>]`, or
+`[NEGATIVE_KNOWLEDGE: <query>]`. Writes go only to `.research/`.

package/plugins/darkharvest/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "darkharvest",
+  "version": "0.1.0",
+  "description": "Product-level competitor teardown and clean-room harvest engine for Claude Code.",
+  "author": {
+    "name": "Heretek AI",
+    "email": "dev@heretek.ai"
+  },
+  "license": "Apache-2.0",
+  "repository": "https://github.com/Heretek-AI/IUMBTEMS",
+  "homepage": "https://github.com/Heretek-AI/IUMBTEMS#readme",
+  "skills": [
+    "./skills/darkharvest"
+  ]
+}

package/plugins/darkharvest/agents/harvest-proponent.md

@@ -0,0 +1,22 @@
+---
+name: harvest-proponent
+description: Competitor-teardown proponent. Inventories what a competitor does well and proposes per-feature harvest verdicts. Use per competitor scope in darkharvest runs.
+model: sonnet
+---
+
+You are the Harvest Proponent in the darkharvest plugin.
+
+Per assigned competitor: build the capability inventory (present / missing /
+partial per capability with `[VERIFIED: <hash>]` evidence from
+`.research/sources/<sha256>.md`), then propose per-feature verdicts:
+`depend | vendor | clean-room-rebuild | skip(reason)`, ranked by
+Impact x Effort x Differentiation.
+
+Legal guardrails (final): permissive licenses only (MIT, Apache-2.0, BSD, ISC)
+may be `depend`/`vendor`. GPL / AGPL / UNKNOWN license means
+`clean-room-rebuild` spec only — never copy code. Workflows clonable;
+copy-text, UI assets, and brand are never copied. Every `vendor` item emits an
+SPDX attribution block (license + upstream URL + files). Closed targets get
+metadata-only rows plus `[NEGATIVE_KNOWLEDGE: <query>]`, never a failed run.
+
+Full specification: `skills/darkharvest/SKILL.md` in the plugin root.

package/plugins/darkharvest/agents/harvest-redteam.md

@@ -0,0 +1,20 @@
+---
+name: harvest-redteam
+description: Competitor-teardown red team. Vets license contamination, bloat, CVEs, and staleness; maps white-space gaps both ways. Use per competitor scope alongside the proponent.
+model: sonnet
+---
+
+You are the Harvest Red Team in the darkharvest plugin.
+
+Per assigned competitor: determine SPDX from LICENSE file plus package
+metadata; flag transitive bloat, CVE/takeover surface, and staleness
+(`STALE` when inactive over 12 months or solo-maintained). Gates are
+warn-only — badge inline per matrix cell plus a risks section, never
+auto-skip. Map white-space gaps in BOTH directions: what the competitor lacks
+that we own or could own, and what we lack.
+
+Challenge every proponent harvest proposal: any `vendor` verdict on
+copyleft or unknown-licensed code must be rewritten as `clean-room-rebuild`
+with reasoning. Benchmarks are optional but, when present, must be VERIFIED.
+
+Full specification: `skills/darkharvest/SKILL.md` in the plugin root.

package/plugins/darkharvest/evals/teardown-verdict/graders/license-line.md

@@ -0,0 +1,6 @@
+---
+type: llm
+---
+
+PASS if the reply distinguishes what may be borrowed directly (permissive licenses) from what must be re-implemented clean-room (copyleft or unknown licenses), or asks which seed competitors to tear down before verdicts.
+FAIL if the reply recommends vendoring GPL/AGPL-licensed code, copying UI assets, or gives harvest verdicts with no license reasoning at all.

package/plugins/darkharvest/evals/teardown-verdict/graders/skill-fired.md

@@ -0,0 +1,5 @@
+---
+type: tool_used
+tool: Skill
+input_match: '"skill"\s*:\s*"(?:[\w-]+:)?darkharvest"'
+---

package/plugins/darkharvest/evals/teardown-verdict/prompt.md

@@ -0,0 +1,6 @@
+---
+max_turns: 10
+allowed_tools: [Read, Glob, Grep, Skill]
+---
+
+I'm building a competitor to a desktop app that orchestrates multiple coding agents. What do similar open-source projects do well, and what could I borrow clean-room?

package/plugins/darkharvest/skills/darkharvest/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: darkharvest
+description: Product-level competitor teardown and clean-room harvest engine. Use when user wants to compete with or learn from existing products (e.g. Paseo, OpenChambers). Seed with inspiration URLs plus prompt, auto-expand to adjacents, clone-scan competitors, compare product plus code, and emit per-feature depend/vendor/clean-room/skip verdicts with SPDX attribution. Never copies GPL/AGPL code or UI assets.
+---
+
+# Darkharvest — Competitor Teardown & Clean-Room Harvest
+
+Product-level teardown, not library scouting. `oss_scout` answers "which Raft lib do I depend on"; `darkharvest` answers "I'm building a Paseo competitor — what do Paseo-likes do well, what white space exists, and what may I harvest clean-room?"
+
+## 1. Invocation
+
+```bash
+# Full dialectic teardown swarm (mock = zero token cost)
+python3 runner/research_swarm.py --mode darkharvest --objective "Paseo-class agent harness competitor" --mock-claude
+
+# Competitor fetch helper (read-only scan, allowlisted, capped)
+python3 skills/darkharvest/scripts/harvest.py --repo https://github.com/owner/repo --show-context
+
+# Via CLI
+iumbtems darkharvest "Paseo-class agent harness competitor" --seeds https://github.com/a/b,https://github.com/c/d --max-repos 6 --mock-claude
+```
+
+In OpenCode V2: `iumbtems_darkharvest` tool. Slash: `/darkharvest <objective>`.
+In Pi / OMP: `/darkharvest <objective>`. In Gemini: skill auto-activates on competitor-teardown intent.
+
+## 2. Input contract (hybrid, merged)
+
+1. Seeds: GitHub/GitLab URLs plus free-text prompt guidance. Unlimited seeds accepted; runner caps at `--max-repos` (default 10, recommended 6 for live runs).
+2. Local baseline: full `brainstorm.py` domain model (tree + README + stack + TODOs + git log/status). Manual prompt ADDS to auto facts; conflicts record both, manual tagged `[HYPOTHESIS: <how to check>]`.
+3. Gaps: open-loops + user wishlist combined.
+
+## 3. Discovery (seed + expand)
+
+- Seeds + 5–8 auto adjacents; direct competitors and adjacent inspirations SPLIT in the report.
+- Similarity: hybrid pre-filter (README topics + feature keywords + dep overlap) then LLM rerank. Never LLM-vibe alone.
+- Rank relevance first, stars second. Any stack allowed with porting-effort note. Stale (>12mo or solo-maintainer) flagged with `⚠️ STALE`, never auto-skipped.
+
+## 4. Fetch & scan budgets (defaults, all flag-overridable)
+
+- Defaults: `--max-repos 10 --depth 3 --per-repo-mb 100 --per-repo-timeout 300s`. Prefer `--max-repos 6 --depth 2` for live runs.
+- `harvest.py` clones to temp then drops; allowlist scan only: tree + README + LICENSE + manifests + key source headers. Skips `.git, node_modules, dist, build, target, .next, .venv, .research`. Caps file count and bytes — full dump without caps will OOM and is banned.
+- Closed or non-cloneable targets: try Firecrawl/docs fetch; when unavailable emit metadata-only row + `[NEGATIVE_KNOWLEDGE: <query>]`, never fail the run.
+- Evidence: every matrix cell needs a SHA-256 cached source (`.research/sources/<sha256>.md`) with verbatim quote, or a `file://<path>#L<start>-L<end>` pointer. Unverified cells are purged to NEGATIVE_KNOWLEDGE.
+
+## 5. Dialectic roles (one scope per competitor)
+
+- Orchestrator decomposes the candidate list into one scope per competitor (DAG default, auction optional).
+- Alpha (harvest proponent): what competitor does well + per-feature harvest proposals.
+- Beta (red-team): license contamination, transitive bloat, CVE/takeover surface, staleness, both-ways missing (white space).
+- Auditor: enforces strict-cells bar, warn-only gates surface as inline `⚠️ LICENSE/CVE/STALE` badges plus a risks section.
+
+## 6. Legal guardrails (final)
+
+- Permissive only (MIT / Apache-2.0 / BSD / ISC) may be `depend` or `vendor`.
+- GPL / AGPL / unknown license → `clean-room-rebuild` spec only, never copy.
+- Workflows clonable; copy-text, UI assets, brand never copied.
+- Every vendored item emits an SPDX attribution block (license + upstream URL + files).
+
+## 7. Output
+
+- `.research/darkharvest_report.md`: competitor × capability matrix (present / missing / partial + evidence) + white-space gaps both directions + harvest backlog (per-feature `depend|vendor|clean-room-rebuild|skip(reason)`, Impact×Effort×Differentiation ranked, top 5) + risks + epistemic audit totals.
+- Machine dossier: `.research/darkharvest_dossier.json` for rerun diffs (changed cells + new/removed candidates).
+- Errors: structured log + NEGATIVE_KNOWLEDGE, never silent. Writes only under `.research/`.
+
+## 8. Anti-patterns (hard bans)
+
+- No auto-install of dependencies, no writes outside `.research/`.
+- No pixel-level UX cloning, no GPL/AGPL vendoring.
+- No parametric repo claims as `[VERIFIED]` — metadata suffices only for rank hints, never for harvest verdicts.
+- No unbounded expansion: seeds + expansion must respect `--max-repos` and per-repo caps.