witsoc 0.1.0__py3-none-any.whl

witsoc/__init__.py

@@ -0,0 +1,13 @@
+"""Installable Witsoc package.
+
+The first package release keeps the existing script tree as the compatibility
+surface and exposes a stable console entrypoint. New code should prefer
+importable modules under this package as scripts are migrated.
+"""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"
+

witsoc/__main__.py

@@ -0,0 +1,10 @@
+"""Run `python -m witsoc`."""
+
+from __future__ import annotations
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

witsoc/cli.py

@@ -0,0 +1,129 @@
+"""Console entrypoint for the installable Witsoc package."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .legacy import PASSTHROUGH, run_script
+from .registry import BY_TIER, command_rows
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if argv and argv[0] in PASSTHROUGH:
+        return run_script(PASSTHROUGH[argv[0]], argv[1:])
+    if len(argv) >= 2 and argv[0] == "strategy":
+        aliases = {
+            "rank-lanes": "strategy-rank-lanes",
+            "select-barrier": "strategy-select-barrier",
+            "select-product": "strategy-select-product",
+            "stop": "strategy-stop",
+            "allocate": "strategy-allocate",
+        }
+        if argv[1] in aliases:
+            return run_script(PASSTHROUGH[aliases[argv[1]]], argv[2:])
+    if len(argv) >= 2 and argv[0] == "lovasz":
+        aliases = {
+            "rank-dag": "lovasz-rank-dag",
+            "select-mutation": "lovasz-select-mutation",
+            "rank-results": "lovasz-rank-results",
+            "next-action": "lovasz-next-action",
+            "packet": "lovasz-packet",
+        }
+        if argv[1] in aliases:
+            return run_script(PASSTHROUGH[aliases[argv[1]]], argv[2:])
+    if argv and argv[0] == "commands":
+        return _commands(argv[1:])
+
+    parser = argparse.ArgumentParser(prog="witsoc")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_route = sub.add_parser("route")
+    p_route.add_argument("prompt", nargs="*")
+    p_route.add_argument("--field", choices=["route", "announcement", "reason", "chain", "confidence", "state", "json"], default="json")
+    p_route.add_argument("--state-out", default=None)
+    p_route.add_argument("--no-state", action="store_true")
+
+    p_strategy = sub.add_parser("strategy")
+    strategy_sub = p_strategy.add_subparsers(dest="strategy_cmd", required=True)
+    strategy_sub.add_parser("rank-lanes").add_argument("args", nargs=argparse.REMAINDER)
+    strategy_sub.add_parser("select-barrier").add_argument("args", nargs=argparse.REMAINDER)
+    strategy_sub.add_parser("select-product").add_argument("args", nargs=argparse.REMAINDER)
+    strategy_sub.add_parser("stop").add_argument("args", nargs=argparse.REMAINDER)
+    strategy_sub.add_parser("allocate").add_argument("args", nargs=argparse.REMAINDER)
+
+    p_lovasz = sub.add_parser("lovasz")
+    lovasz_sub = p_lovasz.add_subparsers(dest="lovasz_cmd", required=True)
+    lovasz_sub.add_parser("rank-dag").add_argument("args", nargs=argparse.REMAINDER)
+    lovasz_sub.add_parser("select-mutation").add_argument("args", nargs=argparse.REMAINDER)
+    lovasz_sub.add_parser("rank-results").add_argument("args", nargs=argparse.REMAINDER)
+    lovasz_sub.add_parser("next-action").add_argument("args", nargs=argparse.REMAINDER)
+    lovasz_sub.add_parser("packet").add_argument("args", nargs=argparse.REMAINDER)
+
+    p_commands = sub.add_parser("commands", help="list lazy command tiers")
+    p_commands.add_argument("--tier", choices=sorted(BY_TIER), default=None)
+    p_commands.add_argument("--json", action="store_true")
+
+    args = parser.parse_args(argv)
+
+    if args.cmd == "route":
+        route_args = ["--field", args.field]
+        if args.state_out:
+            route_args += ["--state-out", args.state_out]
+        if args.no_state:
+            route_args += ["--no-state"]
+        route_args += args.prompt
+        return run_script("route.py", route_args)
+
+    if args.cmd == "strategy":
+        aliases = {
+            "rank-lanes": "strategy-rank-lanes",
+            "select-barrier": "strategy-select-barrier",
+            "select-product": "strategy-select-product",
+            "stop": "strategy-stop",
+            "allocate": "strategy-allocate",
+        }
+        return run_script(PASSTHROUGH[aliases[args.strategy_cmd]], args.args)
+
+    if args.cmd == "lovasz":
+        aliases = {
+            "rank-dag": "lovasz-rank-dag",
+            "select-mutation": "lovasz-select-mutation",
+            "rank-results": "lovasz-rank-results",
+            "next-action": "lovasz-next-action",
+            "packet": "lovasz-packet",
+        }
+        return run_script(PASSTHROUGH[aliases[args.lovasz_cmd]], args.args)
+
+    if args.cmd == "commands":
+        rows = command_rows(tier=args.tier)
+        if args.json:
+            print(json.dumps({"schema": "witsoc.command_registry.v1", "commands": rows}, indent=2))
+        else:
+            _print_rows(rows)
+        return 0
+    return 2
+
+
+def _commands(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog="witsoc commands")
+    parser.add_argument("--tier", choices=sorted(BY_TIER), default=None)
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    rows = command_rows(tier=args.tier)
+    if args.json:
+        print(json.dumps({"schema": "witsoc.command_registry.v1", "commands": rows}, indent=2))
+    else:
+        _print_rows(rows)
+    return 0
+
+
+def _print_rows(rows: list[dict[str, str]]) -> None:
+    for row in rows:
+        print(f"{row['name']:<28} {row['tier']:<10} {row['cost']:<6} {row['description']}")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

witsoc/legacy.py

@@ -0,0 +1,46 @@
+"""Compatibility helpers for running the legacy Witsoc script tree."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from contextlib import contextmanager
+from importlib import resources
+from pathlib import Path
+from typing import Iterator
+
+from .registry import PASSTHROUGH
+
+
+def source_skill_root() -> Path | None:
+    """Return the source-tree skill root when running from a checkout."""
+
+    here = Path(__file__).resolve()
+    for parent in here.parents:
+        candidate = parent.parent / "scripts" / "route.py"
+        if parent.name == "src" and candidate.exists():
+            return parent.parent
+    return None
+
+
+@contextmanager
+def script_path(script: str) -> Iterator[Path]:
+    """Yield a filesystem path for a packaged or source-tree legacy script."""
+
+    root = source_skill_root()
+    if root is not None:
+        yield root / "scripts" / script
+        return
+
+    traversable = resources.files("witsoc").joinpath("scripts", script)
+    with resources.as_file(traversable) as path:
+        yield path
+
+
+def run_script(script: str, args: list[str]) -> int:
+    with script_path(script) as path:
+        if script.endswith(".py"):
+            cmd = [sys.executable, str(path), *args]
+        else:
+            cmd = ["bash", str(path), *args]
+        return subprocess.call(cmd)

witsoc/references/core/algorithmic_strategy.md

@@ -0,0 +1,149 @@
+# Algorithmic Strategy
+
+Witsoc algorithms provide decision support. They rank lanes, barriers,
+products, mutations, and stop/continue options. They never decide mathematical
+truth and never override the orchestrator's strategy authority.
+
+## Boundary
+
+Algorithms may:
+
+- score candidate actions;
+- explain why an option is promising or risky;
+- surface alternatives;
+- recommend validators;
+- penalize repeated failures;
+- identify the best reportable product.
+
+Algorithms must not:
+
+- emit `SOLVED`, `VERIFIED`, or `CHECKED` unless copying an existing validated
+  ledger status with its evidence;
+- authorize Generator;
+- claim a full solution;
+- block the orchestrator from trying a creative route;
+- turn an advisory ranking into a hard workflow.
+
+Validators decide trust. The orchestrator decides strategy.
+
+## Shared Scoring Dimensions
+
+Scores are normalized to `[0, 1]` and should include reasons.
+
+- `target_relevance`: how directly the option connects to the frozen target.
+- `evidence_potential`: chance of producing checkable evidence.
+- `verifier_friendliness`: how likely the result can be checked/formalized.
+- `uncertainty_reduction`: how much the option clarifies the open core.
+- `novelty_potential`: chance of producing nontrivial progress.
+- `dependency_centrality`: how much a DAG node blocks the target.
+- `cost`: rough runtime/human/agent cost.
+- `repeat_risk`: chance this repeats a known failed approach.
+- `user_value`: usefulness for the requested deliverable.
+
+## Core Algorithms
+
+### Attackability
+
+Estimate whether the target should be attacked by formalization, computation,
+counterexample pressure, barrier decomposition, or creative ideation.
+
+```text
+attackability =
+  0.25 * formalization_readiness
++ 0.20 * counterexample_searchability
++ 0.20 * known_theorem_connectivity
++ 0.15 * decomposition_potential
++ 0.10 * computational_tractability
++ 0.10 * novelty_or_user_value
+- 0.20 * repeat_failure_risk
+- 0.15 * foundation_or_status_risk
+```
+
+### Lane Ranking
+
+Rank a deep-run mission menu.
+
+```text
+lane_score =
+  0.30 * expected_evidence_gain
++ 0.20 * target_relevance
++ 0.15 * verifier_friendliness
++ 0.15 * uncertainty_reduction
++ 0.10 * novelty_potential
++ 0.10 * cheapness
+- 0.25 * repeat_risk
+```
+
+### Barrier Selection
+
+Choose which barrier or DAG node is worth attacking next.
+
+```text
+node_score =
+  0.35 * dependency_centrality
++ 0.25 * unlock_value
++ 0.15 * formalization_readiness
++ 0.15 * evidence_available
++ 0.10 * theorem_connectivity
+- 0.25 * repeat_failure_risk
+```
+
+### Mutation Selection
+
+Select a one-axis mutation from the current gap class.
+
+```text
+mutation_score =
+  0.30 * gap_match
++ 0.20 * novelty_against_failure_memory
++ 0.20 * verification_friendliness
++ 0.15 * expected_unlock
++ 0.15 * cheapness
+```
+
+### Best Product Selection
+
+Rank the current products for reportability.
+
+```text
+product_score =
+  0.35 * evidence_strength
++ 0.25 * target_fidelity
++ 0.15 * dependency_path_quality
++ 0.10 * novelty
++ 0.10 * formalization_readiness
++ 0.05 * user_value
+- 0.30 * remaining_gap_penalty
+```
+
+### Stop/Continue
+
+Decide whether the run needs repair, bus fulfillment, continuation, honest stop,
+or user input.
+
+```text
+failed_gate -> repair_gate
+bus_pending -> continue_after_bus
+reviewed verified/checkable product -> stop_honestly_with_product
+open barrier and next mutation -> continue
+all lanes failed with failure classes -> stop_honestly_with_barrier_report
+target unclear -> ask_user
+otherwise -> continue_lowest_cost_uncertainty_reduction
+```
+
+### Portfolio Allocation
+
+Suggest worker allocation from ranked lanes.
+
+```text
+workers_i = round(total_workers * lane_score_i / sum(lane_scores))
+```
+
+Constraints:
+
+- at least one skeptic lane when promoting a product;
+- at least one counterexample lane for open-style targets when available;
+- at most 40% idea-generation unless no formalizable rung exists;
+- at least one formalization lane if WIT/Lean is requested and available.
+
+Every allocation is advisory.

witsoc/references/core/architecture.md

@@ -0,0 +1,70 @@
+# Witsoc Architecture (R0/R1)
+
+The structural map of the system. `python3 scripts/witsoc.py map` prints the
+machine-readable version; this file explains it.
+
+## Layout rule
+
+Files stay **flat on disk** under `scripts/` — the external
+`skill-which witsoc/scripts/<name>.py` resolution contract (orchestrators,
+SKILL.md command blocks) depends on stable flat paths. The *logical* structure
+is the `GROUPS` registry in `witsoc.py`: every tool belongs to exactly one
+group, the flat CLI is derived from the registry (a collision is a startup
+error), and `witsoc <group> <cmd>` / `witsoc <group>` / `witsoc map` expose
+the grouping.
+
+## The five groups
+
+| Group | Role | Boundary rule |
+|---|---|---|
+| `engines` | Strategy-free services: input in, certificate/result out | Never assign trust, never choose the next move |
+| `campaign` | Lovasz-owned candidate machinery: loops, dispatch, evolution, scheduling | Campaign entry points need a run context or explicit `--standalone`; gates decide trust |
+| `knowledge` | The stores: atlases, libraries, ledgers, registries | Trust tiers + provenance mandatory; metadata never upgrades a claim |
+| `gates` | Honesty: validators, skeptics, audits, claim protocols | Demote-only; a gate never upgrades |
+| `core` | Run substrate: WIT cycle, routing, artifacts, the run ledger | Deterministic; no LLM |
+
+`witsoc services` remains the boundary-contract registry (a curated subset of
+the map with per-service contracts).
+
+## R1: the unified run ledger
+
+The historical design scattered one run's state across ~15 JSON ledgers
+(`proof_dependency_dag.json`, `worker_results.json`, `gap_feedback.json`,
+`blueprint.json`, `actual_lemma_queue.json`, `skeptic_reviews.json`, handoffs,
+`lovasz.soc`, failure/retry/mutation ledgers…), with the same fact stored in
+several files and a fleet of validators checking cross-file consistency.
+
+`run_ledger.py` (`witsoc ledger`) is the replacement substrate: **one
+`run.sqlite3` per run, the DAG node as the single entity.** Worker results,
+gap feedback, blueprint obligations, and skeptic reviews are records attached
+to nodes; "blueprint status" and "gap class" are computed views, not files.
+
+- `ingest <run>` — read every legacy JSON ledger into the database
+  (idempotent upserts; safe to re-run after any tool writes).
+- `status <run>` — the single-pane view that previously required reading ten
+  files: phase, escalation, node counts, ready frontier, gaps, attempts.
+- `consistency <run>` — the cross-ledger validators as QUERIES: accepted
+  nodes need reviews and evidence, dependencies resolve to accepted nodes,
+  no cycles, failed nodes carry gap feedback, statuses legal.
+- `export <run>` — regenerate the legacy JSON ledgers from the database, so
+  current consumers keep working during migration.
+- `nodes <run>` — the node-centric joined view (node + attempts + reviews +
+  gaps + blueprint state in one record).
+
+### Migration path
+
+1. **Now (R1):** the ledger is a derived index — tools keep writing JSON;
+   `ingest` after each phase gives the unified view and query-based
+   consistency. The E2E and validators run on either representation.
+2. **Next (R1.5):** high-traffic readers (reports, return packets, manifests)
+   read from the ledger; writers dual-write through a small witcore API.
+3. **Then (R2):** the ledger is the only store; `export` exists solely for
+   archival/interop; the redundant per-fact files and their cross-file
+   validators are retired.
+
+## Deferred (explicitly)
+
+- Physical file moves into package directories — blocked on the skill-which
+  flat-path contract; revisit only with a coordinated orchestrator change.
+- `witcore.py` split into submodules — cosmetic until R3's batch/session
+  engine room work, where it pays for itself.

witsoc/references/core/artifact_policy.md

@@ -0,0 +1,42 @@
+# Artifact Policy
+
+Use this protocol for every WIT, Lean, receipt, SOC, log, proof worktree, report, and generated JSON packet.
+
+## Registry First
+
+Every artifact should be registered in `witsoc_artifacts.json` with:
+
+- path,
+- type,
+- owner phase,
+- target hash,
+- status,
+- worktree path and cleanup status when applicable.
+
+The plugin and final report should read the registry first and use filesystem scanning only as fallback.
+
+## Required Artifact Metadata
+
+Artifacts tied to proof claims must record:
+
+```json
+{
+  "artifact_id": "",
+  "type": "wit | lean | receipt | log | report | soc | proof_worktree | json",
+  "path": "",
+  "target_hash": "",
+  "claim_id": "",
+  "owner_phase": "witsoc-explorer | witsoc-research-lovasz | witsoc-generator",
+  "status": "created | checked | verified | failed | stale",
+  "created_by": "",
+  "worktree_status": ""
+}
+```
+
+## Stale Artifact Rule
+
+An artifact is stale if its target hash differs from the frozen target hash and no target mutation record explains the difference. Stale artifacts may be cited as failed attempts or historical context, not as evidence.
+
+## Worktree Rule
+
+WIT/Lean proof artifacts for nontrivial claims must be generated in a session-scoped proof worktree. Preserve proof files, logs, receipts, SafeVerify records, and reports. Clean temporary Lean projects when allowed, but keep evidence artifacts.

witsoc/references/core/capability_catalog.md

@@ -0,0 +1,172 @@
+# Primitive Capability Catalog
+
+Advisory (strategy layer), except where a row is marked **contract**. This
+catalog presents Witsoc's deterministic machinery as general, composable
+primitives — organized by *what each one does*, not by which phase
+traditionally calls it. Any composition that respects the contract layer is
+legitimate, including ones no protocol file anticipates; record the
+composition chosen and why. Exact invocations live in `tooling.md` and the
+per-script `--help`.
+
+Reading a row: **Primitive** (entry point) — what it does; *applies when*;
+*output grade* (the ceiling of what its result can claim); *composes with*.
+
+## Search & Retrieval
+
+- **Lemma library** (`lemma_library.py`) — semantic search over persistent
+  lemmas, trust-tiered WIT_STRUCTURE → WIT_RECEIPT → LEAN_VERIFIED. *Applies*:
+  before re-deriving anything. *Grade*: as tiered. *Composes*: seeds provers,
+  handoffs, the lemma pool; `verify-lean` upgrades tiers.
+- **Proof bank** (`proof_bank.py`) — archive of successful proofs by goal
+  shape. *Applies*: prompt/example seeding for provers and narrative agents.
+  *Grade*: examples only. *Composes*: nexus, tiered-prove.
+- **Mathlib atlas** (`mathlib_atlas.py`) — formal availability + module path
+  lookup. *Applies*: before any Mathlib dependency enters a plan (contract:
+  no match → availability `UNKNOWN`, search target only). *Grade*:
+  availability fact. *Composes*: handoffs, external-fact records.
+- **Literature engine** (`literature_engine.py`) — dated source ledgers for
+  status claims; 90-day staleness gate. *Applies*: solved/open status, best
+  known results. *Grade*: sourced status. *Composes*: barrier packets,
+  novelty triage.
+- **Knowledge stores** (`witsoc atlas` / `witsoc library` / `witsoc memory`)
+  — curated reference atlas (read-only) + live global library + cross-run
+  memory. *Applies*: start and end of every serious run. *Composes*:
+  everything; promote = the only live→reference path.
+- **Technique atlas** (`analogical-transfer`, fed by `proof-autopsy`,
+  `mathlib-autopsy`) — techniques indexed by applicability fingerprint.
+  *Applies*: stuck steps, transfer checklist. *Grade*: candidate technique.
+- **Goal cache** (`goal_cache.md` machinery) — prior attempts on a goal hash.
+  *Applies*: before any prover dispatch. *Composes*: retry discipline.
+
+## Enumeration, Mining & Falsification
+
+- **Research search** (`research_search.py`) — bounded falsification and
+  witness search across number theory / graphs / finite models; `--inflate`
+  grows a counterexample into an obstruction-family candidate. *Grade*:
+  CHECKED at most, bounded scope. *Composes*: falsification passes, enemy
+  profile, obstruction ledgers.
+- **Empirical miner** (`empirical_miner.py`) — pattern mining over
+  enumerated families. *Grade*: CONJECTURE/CHECKED bounded evidence.
+  *Composes*: conjecture pipeline.
+- **Finite graph backend** (`finite_graph_backend.py`) — exact bounded graph
+  checks (nauty when present). *Grade*: CHECKED on the enumerated scope.
+- **Number theory backend** (`number_theory_backend.py`) — verified
+  arithmetic certificates (factorization with product check, Miller–Rabin,
+  sigma classes, witness checks). *Grade*: CHECKED certificate.
+- **Asymptotic analyzer** (`asymptotic_analyzer.py`) — deterministic
+  asymptotic claim screening. *Applies*: every asymptotic claim before it
+  becomes a proof path. *Grade*: rejection is REJECTED; unavailability is a
+  precondition gap, never evidence.
+- **Counterexample search** (`counterexample_search.py`) — front-end over
+  the engine + evaluators for targeted refutation. *Composes*: dialectic,
+  disproof-first.
+
+## Construction & Synthesis
+
+- **Discovery engine** (`discovery_engine.py` + `discovery_evaluators.py`) —
+  island-model evolutionary search; generation cheap and untrusted, the exact
+  evaluator is the moat; optional LLM-as-mutation-operator sampler. *Applies*:
+  extremal/existence targets with a finite witness. *Grade*: CHECKED witness.
+  *Composes*: program-evolve, lemma promotion to WIT/Lean.
+- **Program evolution** (`witsoc evolve`) — FunSearch/AlphaEvolve-style
+  evolution of `construct(n)` programs against exploit-hardened evaluators
+  with independent re-verification. *Grade*: CHECKED records.
+- **Formula synthesis** (`formula-synthesis`) — parametric witness-formula
+  families (e.g. residue-class witness triples), whole-class statements via
+  exact substitution, then kernel gating. *Grade*: CONJECTURE until the
+  whole-class proof passes the kernel.
+- **Definition synthesis** (`definition-synthesis`) — grammar search for
+  separating invariants; the Invention Mode primitive (never invent a concept
+  by prose). *Grade*: candidate definition, OPEN_UNFALSIFIED.
+- **SAT / reduction hunt** (`sat`, `reduction-hunt`, `smt_synthesizer.py`) —
+  encode finite instance families; CDCL with DRAT-checked UNSAT
+  (RECEIPT_ACCEPTED certificates); `sat` = candidate gadget, `unsat`+core =
+  obstruction evidence. *Applies*: rediscovery brackets, covering systems,
+  Ramsey-type bounds, finite gadgets. *Composes*: computational_certificate
+  DAG nodes.
+- **Construction search** (`construction_search.py`) — direct search drivers
+  for known construction shapes.
+
+## Conjecture Machinery
+
+- **Ideation** (`ideate.py`) — move-class divergence, sampler-fleet widened;
+  generation unfiltered, the kernel stack filters. (Gate floor for open
+  targets: ≥15 ideas, ≥4 move classes.)
+- **Conjecture pipeline** (`conjecture_miner.py`, `conjecture-pipeline`) —
+  mine → rank (`interestingness`, ordering only) → formalize via predicate
+  registry → dispatch. *Grade*: CONJECTURE.
+- **Speculative arena** (`speculative-arena`) — kernel-proved
+  hypothesis→target bridges, leverage-ranked. *Grade*: bridge is VERIFIED
+  conditional; hypothesis stays open.
+- **Lemma repair** (`lemma-repair`) — counterexample-guided one-axis repair
+  of refuted conjectures; survivors are CONJECTURE.
+- **Variant posing** (`pose-variants`, `discovery-lift`) — self-play
+  curriculum around a target; `cluster` attacks target + variants under one
+  shared theory so rungs and refutations transfer.
+
+## Proving & Formalization
+
+- **Tiered prover** (`witsoc tiered-prove --tier light|medium|heavy`) —
+  deterministic saturation → external prover fleet (kernel-replayed) → Nexus.
+  *Grade*: kernel-passing closures only.
+- **Nexus loop** (`witsoc nexus prove|formalize`) — fleet proposals iterating
+  against real Lean compiler diagnostics with proof-bank examples embedded.
+- **Dual narrative agent** (`witsoc narrative compose|ground`) — informal
+  proof first, then step-by-step formal grounding; gaps feed the lemma pool.
+  *Applies*: whole informal arguments.
+- **Lemma pool** (`pool`, `witsoc retrieve build-corpus`) — bridging lemmas
+  mined from real residual diagnostics; proved ones reused everywhere.
+- **Decomposition** (`decompose_problem.py`, `sketch_tournament.py`,
+  `sketch_population.py`, `result_ladder.py`) — competing decompositions and
+  EV-ranked sketch populations; effort allocation only, never status.
+- **Proof search** (`proof_search.py`), **structural induction** drivers,
+  **wit→lean obligation** (`wit_to_lean_obligation.py`) — the kernel-facing
+  floor.
+- **Ontology pivot** (`ontology-pivot`) — functorial transfer to an
+  orthogonal domain; new subgoals still point at the original target. (Gate
+  floor: mandatory after two failed native-domain attacks on a barrier
+  lemma.)
+
+## Verification & Audit — **contract layer**
+
+Not optional once a claim is made, and never LLM-substitutable: `wit check`
+and structural checks, receipt parsing, `lake build` + SafeVerify
+(`lean_verification.md`, `safeverify.md`), target-freeze checks, the
+`validate_*` family (route state, handoffs, Lovasz phases/runs, proof-DAG
+integrity, open-problem runs, mathematical solve), `solve_claim_protocol.py`,
+report grading (`grade_witsoc_report.py`), status legality
+(`status_lattice`), and the rediscovery benchmark (`witsoc rediscovery`) as
+the only honest meaning of "top tier".
+
+## Orchestration & Memory
+
+- **Campaign driver** (`campaign_driver.py`) — one crank of the loop:
+  preflight, dispatch, skeptic, gap feedback, theory update,
+  dialectic, re-ideation, ledgers; `--finalize` for the production-gate
+  sequence. *Applies*: sustained campaigns where turn discipline, not math,
+  is the historical failure mode.
+- **Problem theory** (`problem_theory.py`) — the living causal model:
+  equivalent formulations, example zoo, enemy profile, failure mechanisms,
+  main attack + stall point; embedded in every fleet prompt.
+- **Gap feedback** (`proof_gap_to_barrier_feedback.py`) — **contract** floor
+  for mutation-before-retry.
+- **Barrier machinery** (`barrier_attack.py`, `rung_saturation`,
+  `lovasz_top_tier.py`) — depth spine + breadth ladder + readiness audit.
+- **Run ledger** (`run_ledger.py`, `run.sqlite3`), **trace harvester**
+  (`trace_harvester.py`) — unified state and the machine-checkable reward
+  record `(problem → solution, reward)` for expert iteration.
+- **Self-play** (`witsoc self-play frontier-round`) — keeps the curriculum at
+  the prover's frontier between campaigns.
+
+## Composition Notes
+
+- A primitive's output grade caps every downstream claim: a CHECKED witness
+  piped into a prover does not make the general theorem CHECKED; a
+  CONJECTURE-grade family kernel-verified for its whole class becomes
+  VERIFIED for exactly that class.
+- Prefer a pipeline of two general primitives over one narrow wrapper when
+  both exist; prefer the wrapper when it carries a gate you would otherwise
+  have to re-implement.
+- When a needed primitive is missing, say so explicitly (`backend_pending`
+  is honest) rather than simulating it in prose — and check sibling skills
+  and plugins before concluding it doesn't exist.