Home / Projects / Orchestrata Ultimate / Rulings overview
Rulings overview
A ruling is a standing instruction from Mohamed that binds all later work, such as "no mocks" or "the host Claude writes no code". Each has an id (RUL-NNN), one file under rulings and a verbatim statement. The canon is the single source of truth: gates and hooks read the git-backed files directly from the filesystem, never through the wiki server, so a wiki outage cannot break a test gate.
Ruling versus ADR. An ADR records a one-way-door design decision and the alternatives rejected. A ruling is a rule of conduct. They link in both directions: a ruling often has a decision record behind it (RUL-041 and ADR-0125, RUL-034 and ADR-0069), and an ADR can amend a ruling, as ADR-0062 amends the path clause of RUL-027. The table's "cited by ADRs" column is that link, read from the ADR texts. Under ADR-0130 a new ruling first lives in scratch notes and is minted as an ADR at the publish step.
Enforcement. RUL-014 says a ruling that exists only in prose is incomplete work. Every ruling must resolve to a mechanism: a hook, a gate, a banned-deps entry, a constitutional article, or an explicit enforcement: none (judgment) mark. scripts/rulings_lint.py parses each file's ## Enforcement section and fails if a declared hook or gate does not exist. The "gate pages" column lists the pages under gates that mention the id, which shows where a mechanism is documented.
Judgment is a legitimate answer, not a gap. Some rules, like the host-writes-no-code rule (RUL-041), need a person to apply them; the file says so, and often names the mechanism still owed. The chart counts mechanical against judgment-only rulings as the files state them. Where the canon index disagrees with a file, the status column shows both.
Reading the table. Start from the ruling sentence, which is the first sentence of the file's Ruling section (quoted verbatim). Follow the id to the full text, evidence and verification. Rulings that no ADR cites and no gate page mentions are listed at the end; they are enforced only by their own mechanism, or by judgment.
Enforcement at a glance
41 rulings: 35 name at least one mechanism (hook, gate, banned-deps, code), 6 are judgment only (none (judgment)).
Every ruling
Each ruling links to its canon file under rulings. Enforcement is read from the file's ## Enforcement section; status and date from the canon index. Gate pages are those under gates that mention the id (the gates index itself is not counted).
| id | date | ruling | enforcement | status | cited by ADRs | gate pages |
|---|---|---|---|---|---|---|
| RUL-001 | 2026-07-26 | NEVER run pytest with xdist (-n auto, -n N, --numprocesses, --dist) in orchestrata-ultimate. |
hook .claude/hooks/no-xdist.shbanned-deps pytest-xdist(+2 more) |
enforced | – | family-suite-preflight, parallel-safety, review-staged, validate-ci |
| RUL-002 | 2026-07-26 | No unittest.mock, no Mock/MagicMock/AsyncMock/patch, no hand-rolled Fake/Stub/Dummy classes, no monkeypatch, no @pytest.mark.skip/skipif. |
gate scripts/test-review.py T1gate scripts/audit_test_purity.py monkeypatch(+1 more) |
enforced | ADR-0064, ADR-0111, ADR-0112 | family-session-hooks, parallel-safety, prolog-gate, review-staged, test-purity |
| RUL-003 | 2026-07-26 | Read env config with inline os.environ.get("X", default) at call time — never a bare os.environ["X"], never a hardcoded literal, and never an import-time constant when the value must be override-able at runtime. |
gate src/orchestrata_ultimate/prolog/gate_rules.pl bare_os_environgate src/orchestrata_ultimate/prolog/gate_rules.pl env_mutation(+3 more) |
enforced | ADR-0075, ADR-0112 | env-contract, env-subnet-scheme, fleet-drift, prolog-gate, validate-ci |
| RUL-004 | 2026-07-26 | The user runs containers on Incus (LXD), which he considers more stable and powerful than Docker. | gate scripts/check_incus_not_docker.py RUL-004banned-deps docker |
enforced (canon index: judgment) | – | ci-pipeline |
| RUL-005 | 2026-07-26 | All test parallelism in this project comes from orchestrata_ultimate.core.threading.test_executor.run_tests_in_parallel (one pytest subprocess per module), driven via scripts/run_tests.py / run_tests_threadpool.py / run_tests_streaming.py — never… |
hook .claude/hooks/no-xdist.shgate scripts/test-review.py T15 |
enforced | – | review-staged |
| RUL-006 | 2026-07-26 | "Any time you see an error, fixing it should be automatic." (verbatim, 2026-07-22). | hook .claude/hooks/no-offer-instead-of-fix.shnone (judgment) |
enforced (canon index: judgment) | ADR-0085 | family-process-gates, family-session-hooks |
| RUL-007 | 2026-07-26 | Do not add Co-Authored-By: Claude ... (or any equivalent attribution to any AI assistant) to git commits, tags, PR bodies, or any other artifact. |
hook scripts/hooks/commit-msggate scripts/check_ai_attribution.py RUL-007 |
enforced (canon index: judgment) | ADR-0100, ADR-0101 | ai-attribution, ci-pipeline, family-process-gates, ship-verify |
| RUL-008 | 2026-07-26 | Before ANY commit: run code review, test review, and architecture review (deterministic gates — ruff, purity/isolation audits, architecture_checker.py, standards, check-deps — plus a reviewer pass for non-trivial changes), and fix every bug found… |
hook scripts/hooks/pre-commitgate scripts/code-review.py --min-severity(+1 more) |
enforced | ADR-0101 | architecture, commit-precheck, family-process-gates, mypy, review-staged, ruff |
| RUL-009 | 2026-07-26 | "do not run tests without it — only by force" (verbatim, 2026-07-10). | hook .claude/hooks/force-test-observation.sh |
enforced | ADR-0078 | coverage-claude, test-phase-cap |
| RUL-010 | 2026-07-26 | "you cannot skip anything." (verbatim, mid-turn, 2026-07-21). | gate scripts/start_test_services.py non-authoritative |
enforced | – | family-suite-preflight, test-purity |
| RUL-011 | 2026-07-26 | For the CXP gRPC kernel port (and ports generally): no hardcoded numeric default, not in source, not in tests. | gate src/orchestrata_ultimate/prolog/gate_rules.pl… |
enforced | – | validate-ci |
| RUL-012 | 2026-07-26 | "include wiring and deployment in your definition of done permanently" and "do not claim completion until you can verify every single word in your completion report." (verbatim, session 242, 2026-07-18). | gate scripts/health_check.py check_orphan_modules |
enforced | ADR-0078 | wiring |
| RUL-013 | 2026-07-26 | Resolve behaviour/contract/version design decisions from specs/SPEC-000..105 + @traces(reqs=[...]) before asking the user to re-decide something a spec already says, and never from a test (tests can enshrine the wrong thing) or a guess. |
gate scripts/check_spec_authority.py RUL-013none (judgment) |
enforced (canon index: judgment) | ADR-0068, ADR-0069, ADR-0071 | family-process-gates, feature-loss, requirement-corpus |
| RUL-014 | 2026-07-26 | Every ruling must resolve to a mechanism: a hook, a gate, a banned-deps entry, a constitutional article, or an explicit enforcement: none (judgment) mark — never left as prose alone. |
gate scripts/rulings_lint.py enforcement: |
enforced | ADR-0063, ADR-0069 | external-tools, family-session-hooks, family-suite-preflight, lexicon-collision, prolog-gate, rulings-lint, uncovered-policies |
| RUL-015 | 2026-07-26 | "whenever a plan is there you should do nothing but execute that plan; the idea of diverting should never come up unless I bring up an issue." (verbatim intent, 2026-07-24). | constitution Article XII |
enforced | – | – |
| RUL-016 | 2026-07-26 | Before importing/ingesting nodes into a graph (Neo4j→Memgraph, source ingest, etc.), design/extend the canonical KG ontology FIRST — never dump raw nodes. | gate scripts/kg_schema.py canongate scripts/sweep_test_pollution.py canonical |
enforced | – | – |
| RUL-017 | 2026-07-27 | Never use weasel words — soft, hedging, or euphemistic vocabulary — in prose, verdict enums, schemas, docs, commit messages, or agent briefs. | hook .claude/hooks/no-guessing-stop.sh |
enforced | – | family-process-gates, family-session-hooks |
| RUL-018 | 2026-07-26 | "Kimi runs at the AGENT level, not the project level" (user requirement, verbatim, SESSION_START.md). |
gate scripts/check_kimi_agent_level.py RUL-018 |
enforced (canon index: judgment) | – | – |
| RUL-019 | 2026-07-26 | Central config modules (core/infra_config.py) use Pydantic BaseSettings, and env files must be auto-loaded (_load_dotenv()) by every entrypoint — never left to direnv or manual sourcing. |
gate scripts/check_env_contract.py RUL-019none (judgment) |
enforced (canon index: judgment) | – | env-contract |
| RUL-020 | 2026-07-26 | "If a function is async def, every call to it must be awaited (or scheduled via asyncio.create_task/gather/ensure_future). |
gate scripts/check_async_await.py reportUnusedCoroutine |
enforced | – | – |
| RUL-021 | 2026-07-27 | "every damn feature branch gets a full env until we merge then it gets deleted" (verbatim, 2026-07-27). | gate scripts/check_worktree_envs.py RUL-021 |
enforced | – | pre-push-guards, prod-separation, review-staged, source-provenance, worktree-envs |
| RUL-022 | 2026-07-27 | The workflow is design → contract diagram → generate → fill in → test, and it is not optional. | hook .claude/hooks/require-design-before-build.sh |
enforced | ADR-0048, ADR-0052 | dispatch-brief, family-process-gates, family-session-hooks |
| RUL-023 | 2026-07-27 | "when I ask for a feature that means wiring the damn thing not just code vomit" (verbatim, 2026-07-27). | gate scripts/health_check.py check_wiring |
enforced | ADR-0042, ADR-0115, ADR-0116, ADR-0118 | feature-loss, wiring |
| RUL-024 | 2026-07-28 | "new rule, create a hook, when you output the word prexisting failure print a message that tells you to fix it" (verbatim, 2026-07-28). | hook .claude/hooks/no-preexisting-excuse.sh |
enforced | ADR-0122 | family-process-gates, family-session-hooks |
| RUL-025 | 2026-08-05 | _scan_non_canonical_nodes (SPEC-106 FR-001, REQ-106-006 — the canonical-schema conformance gate behind kg_schema.py check) counts a keyless canonical-label node as drift only when it carries no test_id property (decision made 2026-08-05, chosen… |
gate src/orchestrata_ultimate/knowledge_graph/canonical_schema.py… |
enforced | – | – |
| RUL-026 | 2026-08-06 | "I wANT IT Automated and the default is sonnet unless you specify" (verbatim, 2026-08-06). | hook .claude/hooks/workflow-default-sonnet.sh |
enforced | – | dispatch-brief |
| RUL-027 | 2026-08-08 | Separate dev code from prod (user command, 2026-08-08). | gate scripts/check_prod_tree_separation.py find_violations |
enforced | ADR-0062, ADR-0067, ADR-0070, ADR-0078 | prod-separation |
| RUL-028 | 2026-08-10 | Requirement and test traceability questions are answered by querying the code-intelligence KB, not by reading or rewriting files in bulk. | hook .claude/hooks/force-trace-intel.sh |
enforced | ADR-0114 | requirement-corpus |
| RUL-029 | 2026-08-10 | Before running the whole suite, ask what the change can reach. | hook .claude/hooks/proportionate-test-scope.sh |
enforced | – | affected-selection |
| RUL-030 | 2026-08-13 | Generated artifacts belong in git (user ruling, 2026-08-13). | gate scripts/check_generated_artifacts.py RUL-030 |
enforced | ADR-0088, ADR-0128 | feature-loss, generated-artifacts, lexicon-drift |
| RUL-031 | 2026-08-19 | A requirement id has one canonical spelling. | gate scripts/check_req_format.py RUL-031 |
enforced | – | family-process-gates, requirement-corpus |
| RUL-032 | 2026-09-22 | A test module that has passed is not run again until the code under test or the test itself changes. | gate scripts/run_tests.py RUL-032gate scripts/test_green_ledger.py RUL-032 |
enforced (canon index: in progress (builder dispatched same session)) | ADR-0060, ADR-0079, ADR-0088, ADR-0093 | affected-selection, codetools-gates, family-suite-preflight, green-ledger, pre-push-guards, ship-verify |
| RUL-033 | 2026-09-23 | Mohamed, 2026-09-23 (plan PLAN-2026-09-23-production-deployable-tools.md, ruling R9): the Read tool is permitted on a Python file whose module the same session has already read through scripts/serialize_codebase_ast.py source <name>. Everything else… |
hook .claude/hooks/force-ast-toolkit.shhook plugins/orchestrata/project-hooks/force-ast-toolkit.sh |
enforced | ADR-0063 | – |
| RUL-034 | 2026-10-06 | Mohamed, 2026-10-06, during SPEC-110 packet S1, verbatim: "do not forget annotations, rtm, documentation, wiki update and 90% code coverage", then, same session: "it should br the definition of done for all specs". | none (judgment) |
judgment | ADR-0069 | coverage-claude, requirement-corpus, rulings-lint |
| RUL-035 | 2026-10-06 | Mohamed, 2026-10-06, during the P4 review of plans/ast-daemon-deployment-plan.md, verbatim: "hooks at user level only but apply to the project in cwd,soo they apply to all projects, add it to the rules". |
none (judgment) |
judgment | ADR-0070, ADR-0086, ADR-0118 | commit-precheck, dispatch-brief, family-session-hooks, plugin-drift, rulings-lint, unshipped-guard, wiring |
| RUL-036 | 2026-10-14 | Mohamed, 2026-10-14, after asking why the suite tests against containers, verbatim: "also tests must be categorized, fnctional vs integration". | none (judgment) |
judgment | ADR-0111 | rehearsal-exclusion, rulings-lint |
| RUL-037 | 2026-10-17 | Mohamed, 2026-10-17, after the orchestrator explained that the Bash write hook's /tmp/claude- scratch escape was why its probes lived in /tmp, verbatim: |
none (judgment) |
judgment (canon index: judgment — 4 mechanisms owed) | ADR-0112, ADR-0113 | rulings-lint |
| RUL-038 | 2026-10-19 | Mohamed, 2026-10-19, after asking "why are you creating containers during test run?", verbatim: "do not test container creation in test runds". | none (judgment) |
judgment (canon index: judgment — 2 gates owed) | ADR-0116, ADR-0117 | codetools-gates, coverage-claude, family-suite-preflight, green-ledger, rehearsal-exclusion, review-staged, rulings-lint, ship-verify, test-phase-cap |
| RUL-039 | 2026-10-19 | "promotion gate = functionality tests only; rehearsal-class (real deploy/ship/incus/terraform/tofu/load) tests exist but NEVER in the gate." | gate scripts/derive_test_categories.py RUL-039gate scripts/run_tests.py RUL-039 |
enforced | – | family-suite-preflight, rehearsal-exclusion |
| RUL-040 | 2026-10-20 | "never escalate=true is meaningless, it must be measured never the whole suite that is a huge bug" | gate scripts/affected_tests.py RUL-040gate scripts/run_tests.py RUL-040 |
enforced | ADR-0122, ADR-0127 | affected-selection, codetools-gates, family-process-gates, family-session-hooks, family-suite-preflight, green-ledger, pre-push-guards |
| RUL-041 | 2026-10-22 | "this claude here remains production claude but it writes no code when working on my project just perfects the briefs checks and workflow with the flagship model while measuring sonnect and qwen and deepseek performance and workflow improvements" | none (judgment) |
judgment | ADR-0125, ADR-0126 | commit-precheck, rulings-lint, unshipped-guard |
Rulings no ADR cites and no gate page mentions
RUL-015, RUL-016, RUL-018, RUL-020, RUL-025
How to regenerate
scripts/gen-decision-pages.py --check