Knowledge Wiki Orchestrata Ultimate

scripts

Reference › scripts

The scripts directory is the repository's command-line layer: single-file programs that people, git hooks, CI jobs and agents run, as opposed to the library code under orchestrata_ultimate. Most are thin: they parse arguments, call library code and set an exit code, and several say so in their own summaries ("thin CLI shim"). Each page here says how the script is invoked (subcommands and main options), what it reads, what it writes and who runs it. The scripts are grouped below by job. For the gates as a policy, see the gates narrative pages; for the library side see the reference index.

Where to start: run_tests for how code is proven, gates for how it is checked before a push, and serialize_codebase_ast for how it is explored.

182 modules, 93,066 lines of code.

Subpackages

Package Modules LOC
migration 1 73

Modules

Module Summary LOC
__init__ 0
_irc_conversation Shared conversation-capture helper for the kimi/IRC SPEC-021 producer. 408
_irc_listen Persistent IRC listener for #agents channel. 310
_irc_send Send one message to #agents and (best-effort) capture it as a SPEC-021 conversation turn. 109
_irc_watchdog Watchdog: checks IRC listener health every 180s, restarts if dead. 54
add_traces_from_evidence Write @traces from EVIDENCE: test citations joined to code via TestMatcher. 418
affected_tests Affected-test selection — the SPEC (plans/workflow-improvements-plan.md Phase 3, Step 3.1) fix for "too long, max… 2375
agent_check Agent check script — run ON THE HOST. 389
agent_notify Agent notification script — run INSIDE the Incus container when task is done. 65
apply_docstring_traces Convert existing docstring/comment REQ mentions into @traces decorators. 234
architecture_checker Architecture checker — validates import rules, module boundaries, and layering constraints. 691
architecture_static_check Static import-graph layer check — the review-methodology complement to architecture_checker.py. 270
ask_openrouter Ask any OpenRouter-hosted model a question, with opt-in scoped context. 642
ast_api FastAPI service exposing the AST toolkit over HTTP — with auto-generated OpenAPI/Swagger docs. 281
ast_daemon Per-repo AST daemon — a warm, in-memory process for the read-only AST toolkit subcommands… 789
ast_daemon_publish The resident AST daemon's snapshot publisher (ADR-0097). 296
ast_live_sync Live code-intelligence sync: file save -> graph updated in seconds. 811
ast_report Advisory AST health report — a single markdown digest of the codebase. 210
attribute_traces_runtime Runtime execution-evidence attribution for the RTM (BDD runtime-tracing Phase 1, plans/bdd-runtime-tracing-plan.md). 406
audit_test_purity Audit test suite for forbidden patterns: mocks, stubs, fakes, monkeypatch, skips. 410
auto_fix Auto-fixer script for orchestrata-ultimate QA Volk pipeline. 249
backfill_thread_links One-shot, idempotent backfill: Thread correlation-anchor nodes + IN_THREAD/HAS_THREAD/BY_VOLK/TO_VOLK… 456
benchmark_code_intel Measure the Step 3.4 code-intelligence SLOs against the live cluster. 426
benchmark_context_pack Performance benchmark for SPEC-106 context-pack selector + packer. 319
benchmark_pipeline Performance benchmarks for PipelineRunner and infrastructure. 482
benchmark_prolog_clips Standalone CLIPS-vs-SWI-Prolog-tabling micro-benchmark. 250
benchmark_prolog_codeintel benchmark_prolog_codeintel.py — Prolog vs Python recursive code-intelligence benchmark. 1401
bootstrap_graphs Idempotent bootstrap for both graphs — derive graph state from source, never hand-build. 439
build_ft_cpython Build a patched free-threaded CPython 3.14 interpreter (SPEC-023 GIL-off doctrine). 161
build_ft_tree_sitter Build free-threaded tree-sitter wheels (SPEC-023 GIL-off doctrine). 389
build_janus_ft Build a versioned release wheel + sdist for the patched free-threaded janus-swi. 250
build_runtime_callgraph Merge runtime call-graph capture into plans/ast-ultimate.json (SPEC-023 traceability payoff). 436
canonical_conformance One-shot, idempotent migration: bring the live Neo4j KG to canonical-schema conformance (reproducibility runbook R4… 508
check_adr_graph_sync ADR graph-sync gate — a READ-ONLY three-way drift detector. 630
check_ai_attribution AI-attribution gate — the executable mechanism for ruling RUL-007. 460
check_async_await Async-correctness gate: fail on un-awaited coroutines (resolve-by-type via Pyright). 150
check_env_contract Env-contract gate — the mechanized half of RUL-019. 1068
check_env_fleet_agreement Env/fleet agreement gate — the committed endpoints must be the IaC's endpoints. 213
check_env_subnet_scheme Env-subnet-scheme gate — the mechanism for the backlog-413 ruling (Mohamed, 2026-08-15): environment subnets are… 138
check_external_tools External-tools gate — enforces [tool.orchestrata.external-tools] against reality, in BOTH directions (RUL-014: a… 668
check_feature_loss Feature-loss gate — a REQ-* must never lose its implementation silently. 1798
check_generated_artifacts Generated-artifacts gate — the mechanism for ruling RUL-030. 1314
check_graph_write_swallow Graph-write-swallow gate — a graph write failure must reach the caller. 549
check_incus_not_docker Incus-not-Docker gate — the mechanism for ruling RUL-004 ("Incus (LXD), not Docker, for containers"), which was… 1117
check_infra_drift Infra drift gate — the mechanism for ADR-0077 item 4. 291
check_kg_connectivity KG connectivity gate — every node must lead to the root :Project node. 287
check_kimi_agent_level Kimi agent-level gate — the mechanised form of RUL-018. 438
check_lexicon_collisions Lexicon/codebase collision gate — a work-type word must not name a subsystem. 275
check_native_build_freshness Native-build freshness gate — a C fix must not be silently discarded. 200
check_prod_tree_separation Prod/dev tree separation gate — the mechanism for ruling RUL-027. 331
check_prolog_boundary Prolog boundary gate — proves every Python Prolog query site targets a predicate/arity that actually exists in the… 1418
check_req_format Requirement-id format gate — the ONE canonical GRAMMAR, enforced forever. 691
check_requirement_corpus Requirement-corpus gate — production code must not cite an ungradeable requirement. 218
check_secret_leaks Secret-leak gate — catches a live credential committed into TRACKED source. 476
check_source_provenance Source-provenance gate — prove the suite imports the checkout it is testing. 189
check_spec_authority Spec-authority gate (RUL-013) — a requirement id cited by a TEST must be grounded in the spec corpus. 283
check_staged_secrets Pre-commit gate: refuse a commit that stages a plaintext secret. 389
check_wiring Wiring gate — RUL-023 ("when I ask for a feature that means wiring the damn thing not just code vomit", verbatim… 469
check_worktree_envs Worktree-environment gate — RUL-021 ("every damn feature branch gets a full env until we merge then it gets deleted"… 527
claude_governance_gate Claude Code PreToolUse hook shim — the ADR-0032 admission-control gate. 597
claude_turn_capture Claude Code conversation producer (SPEC-021 multi-platform producers). 548
code-review Unified Code Review Tool for orchestrata-ultimate. 2059
code_intel CLI + freshness wrapper over the Prolog code-intelligence KB (CodebaseTools). 647
codemod SPEC-110 codemod engine CLI — load-bench, run, report, analyze subcommands. 1183
comprehensive_review Comprehensive Review — Runs all diagnostic tools and generates unified report. 476
container_cpu_accounting Incus container CPU accounting — cgroup cpuacct core-seconds around one suite run… 454
context_pack Thin CLI for the SPEC-106 context pack (FR-002/003/004/005). 164
context_usage_report Aggregate per-layer, per-volk, and per-subject context token spend. 88
coverage_ratchet Coverage-percentage ratchet — fail only if a SCOPE's coverage DROPS below its recorded baseline. 191
ctok_roundtrip_gate ctok round-trip gate — P1's binary acceptance for the ctok-parser contract. 95
derive_rtm scripts/derive_rtm.py — derived RTM attribution over the MERGED static + runtime call graph (reachability-attribution… 425
derive_test_categories Derive test-module categories from AST — the RUL-039 / RUL-036#13 pass. 434
diagnose_test_failure Auto-diagnose a test failure by performing the 7-step diagnostic process. 505
diagram-tools Global CLI entry for orchestrata-tools diagram subcommands — usable from any directory. 49
doc_lint Doc-truth lint — catches hand-written documentation claims drifting from ground reality (the project's… 337
domaingen CLI for SPEC-105 ontology-driven domain model generation. 58
e2e_run End-to-end orchestrata dogfood runner with full real-time observability. 662
enrich_semantic_graph_specs Enrich the orchestrata-ultimate semantic graph with specs and code traces. 122
error_report What is broken right now — one report, printed every session. 307
evaluate_semantic_graph_qa Evaluate semantic graph retrieval against the 100-question benchmark. 280
extract_reference_edges Extract NON-IMPORT reference edges from Python source into a JSON map. 508
factory_amend CLI for the SPEC-033 amendment-direction differential classifier (B16, ADR-0009/0020/0021). 125
factory_anchors CLI for the SPEC-033 semantic anchor registry (B15a, ADR-0012/0013/0016). 329
factory_assumptions CLI for the SPEC-033 assumption ledger + arbiter cascade (B13, Phase 0). 313
factory_c4 CLI for the SPEC-033 C4 declared-formalization detectors (B26, REQ-033-C4). 188
factory_conformance CLI for the SPEC-033 B2 AST≡design conformance engine (ADR-0007/ADR-0008). 121
factory_decision CLI for the SPEC-033 decision phase + DoR gate wiring (B8, ADR-0015/0028). 239
factory_detectors CLI for the SPEC-033 C3 lexical/structural detector set (B22, ADR-0029). 269
factory_dispatch CLI for the SPEC-033 B21 dispatch gates (ADR-0033/0018/0032). 171
factory_dor_procedure CLI for the SPEC-033 DoR construction procedure (B23, REQ-033-C5). 231
factory_enforce CLI for the SPEC-033 state-diff enforcement core (B1a/B1b/B1c, Phase 1). 418
factory_evidence CLI for the SPEC-033 red-first ledger + affected-set mutation testing (§9, B6). 212
factory_fastpath CLI for the SPEC-033 B12 fast-path classifier (ADR-0023). 250
factory_pipeline CLI for the SPEC-033 §9 DAG scheduler + merge queue pipeline (B9). 300
factory_projection CLI for the SPEC-033 rule-driven projection + completeness check (B5, ADR-0006/0025). 143
factory_promote CLI for the SPEC-033 §4 fact-namespace promotion + GC store (B4a, ADR-0004/0019). 179
factory_trace_check CLI for the SPEC-033 B3 structural trace validator (ADR-0007, ADR-0008). 180
fix_ci_permissions Grant Claude the specific permissions the self-hosted-CI work needs. 153
flake_report Read NDJSON recovery events from stdin and print a per-module summary. 114
flaky_test_hunter Automated flaky test detector — runs the suite N times and identifies flaky tests. 443
freshness_guard Freshness guard — detect and refresh every stale-data class the 2026-08-04 run history hit (Mohamed ruling: "no… 408
gate CLI seam for the Prolog gate layer. 543
gate_parallel_safety Gate: Parallel Safety Audit — deterministic static analysis for test flakiness. 1546
gates THE entry point for the RUL-008 review battery. 578
gen_brief_pack gen_brief_pack.py — dispatch-time context pack for swarm agent briefs. 340
gen_codebase_map Generate a compact, always-fresh codebase map for session ingestion. 563
gen_cxp Regenerate the CXP protobuf message stubs from cxp.proto. 169
gen_intent_lexicon Generate prolog/intent_lexicon.gen.pl — the lexicon FACT clauses consumed by intent_grammar.pl's DCG, from the… 154
gen_level0 Generate docs/LEVEL0.md — the always-in-context Level-0 foundation block. 254
gen_tests Generate test stubs using EnhancedTestGenerator and validate syntax. 55
generate_pytest AST-based test generator for orchestrata-ultimate - CORRECTED VERSION. 1924
generate_rtm_evidence Evidence-graded RTM generator — every row carries its proof class. 788
graph_browser Interactive graph browser (Neo4j-Browser-style) for the project's graphs. 402
graph_query CLI for querying the operational knowledge graph. 463
graph_test_preflight Validate test Cypher queries against GRAPH constraints before running tests. 415
health_check Project health check — mandatory before any bulk change or commit. 735
history_intel scripts/history_intel.py -- the TIME dimension over the Prolog code KB. 937
ingest_orchestrata_ultimate Ingest orchestrata-ultimate source code into the Memgraph semantic graph. 376
intent_demo Show what the intent pipeline does with a sentence — the demo seam. 154
kg_retention Recurring KG retention: age out gateway audit exhaust + CXP exhaust. 166
kg_schema CLI for the canonical Knowledge-Graph schema (SPEC-106 FR-001). 194
migrate_legacy_story_ids Migrate legacy story ids (REQ-NNN-USn-MMM) to canonical REQ-NNN-US-NNN-MMM. 431
mine_prompt_history Quarterly prompt-history drift miner (plans/workflow-improvements-plan.md Phase 5, Step 5.1). 571
minimax_irc_task_picker minimax IRC task queue picker. 154
mint_gateway_token Thin CLI shim: mint a gateway JWT via TokenAuthenticator.create_token. 78
observe_pytest Attach to a LIVE pytest run and stream its per-test events in real time. 324
orchestrata_pytest_observer Auto-attach shim for the SPEC-201 live pytest observer. 63
parse_spec_requirements Thin CLI shim for the spec-requirements parser. 86
pipeline_quick_test Quick pipeline test — review work type. 26
project_status Artifact-sourced project status report (workflow-improvements-plan.md Phase 4). 338
prolog_meta_lint Prolog governance-rulebase meta-lint (SPEC-033 §9, task B17). 1333
promote_env Environment promotion tool — advance the code through dev -> test -> prod. 131
provision_worktree_env Materialise .env in whichever worktree we are standing in — idempotently. 202
purge_memgraph_test_schema Purge leaked per-test chunk-label DDL from a Memgraph instance. 313
purge_stray_kg_databases Drop pre-cutover residue databases from an orchgraph cluster. 129
redis_exec Execute one Redis command against the project's real Redis — CLI seam for tooling that cannot import this repo's… 65
refactor CLI for the SPEC-103 tool-calling refactor capability. 94
repair_divergent_volk_aliases One-shot, idempotent repair: fold lowercase-alias Volk duplicates onto the canonical Volk node. 247
repair_orphan_hub_links Repair the KG root-connectivity invariant (session-254 ruling): every node must be reachable from a root :Project… 788
repair_project_hubs One-shot, idempotent repair: re-anchor mis-attributed Project-hub edges. 208
review-tools Global code review tool — usable from any directory with orchestrata-tools installed. 69
rts AST-based safe regression test selection over a Prolog KB (handover artifact). 308
rulings_lint Rulings enforcement lint — closes the prose-only loophole (SPEC-023 Phase 2, plans/workflow-improvements-plan.md… 376
run_ast_pipeline Thin wrapper around orchestrata_ultimate.tools.ast_pipeline for direct invocation. 19
run_conversation_consumer Standing SPEC-021 conversation-turn consumer daemon. 217
run_tests Unified test runner for orchestrata-ultimate. 2153
run_tests_streaming Streaming parallel test runner — live per-module PASS/FAIL. 305
run_tests_threadpool Parallel test runner using ThreadPoolExecutor instead of xdist. 119
scan_imperative_accumulators Inventory every IMPERATIVE_ACCUMULATOR site in the tree. 107
scan_implementation Thin CLI shim for the implementation scanner. 125
schedule_tests CLI for the §9 row B28 CLP(FD) test-module scheduler. 224
secrets_cli CLI that owns the encrypt/decrypt lifecycle for the repo's secrets. 1003
seed_component_dag Seed the orchestrata-ultimate component DAG into the operational knowledge graph. 231
semantic_search Cheap retrieval CLI for the orchestrata-ultimate semantic graph (audit #6). 209
serialize_codebase_ast Full codebase AST serializer + deep semantic comparison engine. 13843
serialize_js_ts_ast Python wrapper for serialize_js_ts_ast.js — runs the Node.js parser and produces the same unified AST JSON schema as… 100
slot_lease slot_lease.py — worker-slot reservation for parallel swarms. 320
spec_word_cloud Spec/requirements term-prominence tool (MVP word cloud) for orchestrata-ultimate. 462
split_skeleton Split skeleton.py into proper module structure. 144
start_test_services Parallel infrastructure readiness check for orchestrata-ultimate. 1665
swarm_supervisor swarm_supervisor.py — heartbeat supervision for delegated swarm tasks. 474
sweep_test_pollution Sweep stale test-pollution nodes from the Neo4j KG — primary AND worker DBs. 862
sync_architecture_semantic_twin Sync the Memgraph semantic twin of the ratified architecture ontology corpus. 212
sync_architecture_to_graph Sync orchestrata-ultimate's own architecture into the knowledge graph. 1072
sync_ast_to_graph CLI wrapper for the Neo4j AST sync engine. 361
sync_traces_to_graph Sync @traces decorator metadata into the knowledge graph. 360
test-gen Global test generation tool — generate test stubs from Python source. 67
test-review Test file reviewer — checks orchestrata-ultimate test standards. 1769
test_durations Pure reader over reports/test-durations.ndjson (plans/workflow- improvements-plan.md Phase 3, Step 3.3). 376
test_green_ledger RUL-032 proven-content ledger — enforcement mechanism 1 of 3 named by… 441
test_isolation_audit Audit test suite for isolation violations: shared state, hardcoded names, missing test_id. 615
test_pipeline_smoke Smoke test v2: PipelineRunner with review work type (QA → Cp). 30
tools_import_closure Static import closure of the tools-deploy entry modules over src/. 349
trace_intel scripts/trace_intel.py — T1 traceability / use-case-narrative engine. 1209
validate_ci Deterministic CI configuration validator. 592
validate_env Environment-contract preflight — fail fast on missing REQUIRED infra keys. 143
vendor_members_hook Hatchling build hook — vendor the three compiled workspace members into the wheel (RUL-052 §5.1 option (b): "vendor… 75
verify_deployment_identity Deployment identity verifier CLI (U-T6). 43
verify_package verify_package.py — trust-but-sample verifier for a completed change. 407
worktree_toolchain Toolchain pinning + locked-package provenance for scripts/worktrees.py. 192
worktrees Worktree lifecycle manager — create, track, and garbage-collect worktrees. 512

Dependency diagram

Package dependency diagram scripts

Truncated: showing 40 of 111 modules/subpackages (most connected first) and 10 of 31 outside packages.