Knowledge Wiki Orchestrata Ultimate

Lessons — supervisor session 2026-10-19/20

Canonical home: the repo (wt-COMPONENTS, branch components) — reports/errors-and-lessons-2026-10-19.md (L1–L26 with evidence cites) and docs/supervisor-workflow.md (the operating manual the lessons feed). This page is the visible summary so no future session re-pays for them. A lesson without an owner is just a story — every row names where it now lives.

The ten that change behaviour (top of the ledger)

  1. Only mechanical enforcement changes behaviour (L1). RUL-037 mechanized: 780 inline-Python calls → 0. Stated-only rules fired 500+ times unlearned. A guard firing >30×/week is a template bug. → the automation ledger M1–M12.
  2. A verdict artifact, or it did not happen (L2). 48% of dispatch runs had no verdict; rc=0 after auto-reject; commits claimed N/N over N−1 artifacts. → coordinator re-runs every check; commits cite artifact paths; M1.
  3. Worker replies fabricate under pressure (L11). Invented prod subnet 10.53.3.x, false "earlier work" provenance disproved by timestamps. → everything measured before adoption.
  4. The REWORK failure corpus flips runs (L12). Reject → append measured failures to the brief → next run repeated none of them. Standard after any reject.
  5. Verify contract CONSTANTS, not just shape (L13). Fabricated env keys (ORCH_TEST_DEADLINE vs declared ORCHESTRATA_TEST_DEADLINE, missing sanctioned-runner stamp) passed a shape-only review; the cap mechanism was dead on arrival. → constant-contract check in verification + the T17 env-key-drift gate rule.
  6. Pre-commit is the LAST wall, not the first (L14). Run test-review/ruff/black/gate yourself before committing; the T5 block caught what re-runs missed.
  7. Producer before any deletion (L15). The 35 "pollution" nodes were REQ-008-006 feature nodes; a permission granted on a wrong premise does not survive the premise's correction.
  8. Prod graph writes verify PER-INSTANCE (L16/L17). The routing URI served fresh and ANCIENT views in the same minute; direct bolt main+replica is the truth; Memgraph rejects IN-list/UNWIND
    • OPTIONAL MATCH shapes; never 2>/dev/null a new query shape.
  9. Recover ruling verbatims from the corpus and register them (L22). "SELECTED, COUNTED and CAPPED" lived only in a code comment until transcript recovery (3a241b76:2659/2678: HARD 300s cap, exit non-zero, ledger resume, multi-file refusal) — registration then ruled on two live defects (invented 120s default; capped∧failed>0 false-green). → RUL-038 amendment.
  10. Model routing is spend-driven, explicit, and verified after dispatch (L4/L24). The month's NULL-modelID week and the spend-limit first-turn kill are the counter-evidence; session_v2 peek after every dispatch is the countermeasure.

The full ledger

Detailed pages — one per lesson, with the story, verbatim evidence, and worked bad/good examples — live in the repo at docs/lessons/ (index: docs/lessons/README.md). L1–L10 (the week-of-history audit, four-section swarm over Claude/OpenCode/dispatch/codetools corpora): the README maps each to its audit-section incident ids in reports/history-audit-2026-10-19/ and the synthesis in reports/errors-and-lessons-2026-10-19.md §2. L11–L26 (this session's own, incl. the fake-venv/uv-symlink fixture trap L18, measure-before-prescribing L19, fence-includes-VERIFY-artifacts L20, ambiguous-fence-language L21, failure-cluster-exonerates-code L23, stale-observer-record triage L25, and import-shadow-contaminated-proof L26): §7 of the same file, each with its own docs/lessons/ page.

L26 is the one to read before trusting ANY cross-repo green: a direnv PYTHONPATH made codetools resolve its pinned orchestrata-ultimate dependency out of a live foreign worktree, so a transfer's "178 passed" was really 175 passed + 3 failed and two undeclared couplings passed unnoticed. It is owned by a mechanism, not a discipline — codetools' root conftest now refuses a session whose PYTHONPATH redirects its imports, and its sanctioned runner strips external entries from every child, so the contaminated run is impossible rather than merely discouraged.

What shipped while learning them

Step A component-DAG seed (prod-verified per-instance), INT-01 release scaffold (after one reject), P-ARCHSYNC (orchgraph replaces the Neo4j row in the graph's own vocabulary; Kernel required=true; cxpt wording; scoped --retire-legacy with a canonical-label whitelist after verification caught a label-injection surface), the RUL-038 cap adoption (three fix waves; 146/146 green), ADR-0076 graphs-stage landing, the fake-venv sweep, and the T17 env-key-drift rule (dispatched). Commits and evidence lines are in the repo's session log and the commit messages cited above.