codetools / Blockers

codetools Blockers

Gaps measured on 2026-10-23

Every gap was measured with read-only commands during the documentation pass of 2026-10-23. Each one gives its evidence, at least two options, and a recommendation. A recommendation is not a ruling.

1. The repository has no remote

• Evidence: git remote -v in ~/workspace/orchestrata.codetools is empty. Every consumer reaches the repo by local path: ct-install --repo ., the directory plugin marketplace, and orchestrata's path dependency on /opt/codetools/current. No copy exists off this machine.
• Options: (A) a GitLab remote; (B) move it into orchestrata as packages/codetools.
• Recommendation: A. The comparison is on codetools deploy.

2. /opt/codetools does not follow ADR-0035 or parts of ADR-0030

• Evidence:
  • 52 release directories (4.0 GB). ADR-0035 (Accepted) says "one release on disk".
  • current, bin, .venv and VERSION are symlinks. ADR-0030 rule 3 says "The install location holds no symbolic links", with a regular CURRENT file instead.
  • VERSION records repo .. ADR-0030 says VERSION "records absolute paths and the wheel hash, never repo .". Older releases, such as 6b4babfeaac2e008, recorded the absolute repo path; the change came with ct-install --repo ..
  • The venv's pyvenv.cfg home is uv's minor-version link ~/.local/share/uv/python/cpython-3.14+freethreaded-.... The ADR-0030 erratum requires the immutable store /opt/codetools/interpreters/<exact-version>/, and that directory does not exist.
  • The prefix also holds builds/ (2.4 GB), 46 coverage databases and many verify records: 9.3 GB in all, on the worn root NVMe.
• Options:
  • (a) Bring the engine to the ADRs: prune to one release after a successful proof, write CURRENT and absolute VERSION paths, and build on a prefix-local interpreter store.
  • (b) Amend the ADRs to what runs, which is symlink switching with N retained releases for the rollback that ct-install relies on.
  • (c) Do (b) for retention and (a) for VERSION.
• Recommendation: (c). ct-install's rollback needs the previous release on disk, which ADR-0035 removed. VERSION should name its source unambiguously. A ruling is needed either way. Pruning builds/ and old coverage databases is safe housekeeping in all three options, but it deletes data, so it needs Mohamed's go-ahead.

3. The installer skips the verify gate (Hermes model) with no ADR

• Evidence: ct-install always passes --no-verify, which the engine's help calls "bootstrap/rescue". REQ-012-018 and ADR-0003 say the promote runs verified once a release exists. The ruling ("make the installer like hermes", 2026-10-22) is recorded only in the launcher comment. The last two full verify baselines, from 2026-10-18, are red, with 20 and 28 failures.
• Options: (a) mint an ADR that amends ADR-0003: tests run before the merge, deploy proves identity and smoke; (b) restore a verified promote with a time budget; (c) keep both, with the gate in the per-merge batch (gate run) and the launcher for deploy.
• Recommendation: (c), recorded as one ADR. Until the suite is green again, "tests run before the merge" has no green record behind it.

4. Running MCP servers serve an old release

• Evidence: three codetools mcp serve processes, started 2026-10-21 and 2026-10-22, run /opt/codetools/releases/6b4babfeaac2e008 (commit 55221698, 2026-10-14). They lack ast_map, deploy_select_affected and the rename_* tools. See codetools MCP.
• Options: (a) restart the Claude sessions after a deploy; (b) have deploy verify-identity --mcp-json also inspect running mcp serve processes and report stale ones; (c) make the server re-exec when current moves.
• Recommendation: (b), so the drift is visible. (c) is a design change that needs a ruling.

5. The plugin calls verbs that do not exist, and cannot find codetools

• Evidence:
  • The skills and commands run ct snapshot, ct verify, ct diagram, ct rtm, ct coverage and ct blast. None is a CLI verb.
  • bin/ct runs exec codetools, but codetools is not on PATH.
  • runtime/swipl/bin/ is empty, although the installed README says "PROLOG INCLUDED".
  • The plugin was installed from a working tree (directory marketplace, recorded sha 00b1304c, which has no plugins/).
• Options and recommendation: on codetools plugin.

6. The ADR-0020 layers gate is not in the repo

• Evidence: ADR-0020 (Accepted) makes the layer order an enforced import contract: a per-project layer map, Prolog rules in layers.pl loaded as data, run by deploy verify. No layers.pl and no layer-map table were found in the repo on 2026-10-23. pyproject.toml has no layer section. Four packages are outside the ADR's layer table: ast, coverage, gate and verbs.
• Options: (a) build the gate as the ADR says; (b) amend the ADR to place the four packages and record the gate as not yet built.
• Recommendation: (b) now, so the table matches the tree; then (a) as a slice.

7. Duplicated code

• Evidence: CpusetPlan is defined in both gate/cpuset.py and gate/cpuset_plan.py. The edit-region functions are defined in both foundation/edit_regions.py and templates/edit_regions.py, under the same names.
• Options: (a) keep one definition and re-export it from the other path; (b) leave them, if they are intentionally different, and rename one.
• Recommendation: (a), after graph blast or rename report shows the importers.

8. Leftover test state on the host

• Evidence:
  • 7 stopped containers in the Incus project orchestrata (codetools-bdd-*, codetools-ensure-715440, codetools-preexisting-715440, ct-installer-test, ct-prov-e710843a).
  • A transient unit codetools-_TEST_cc4c05dd_78e4153173c9.service from test_deploy_verify_identity_ok0.
  • /opt/codetools/verify-tmp/.
• Options: (a) the suites reclaim what they create, using per-test ids (the test-isolation pattern); (b) a sweep verb.
• Recommendation: (a). Deleting the existing leftovers needs Mohamed's go-ahead.

9. orchestrata depends on the deployed release by an editable path

• Evidence: packages/contracts/pyproject.toml has codetools = { path = "/opt/codetools/current", editable = true }. An editable install points at whatever current is at import time. A promote changes orchestrata's test dependency underneath it, and a rollback does so silently.
• Options: (a) pin a published wheel or a git ref of the remote, once gap 1 is closed; (b) pin a specific releases/<id> path.
• Recommendation: (a).

Active (2026-09-21, not re-checked on 2026-10-23)

• Blocker: OpenRouter batch: openai/gpt-5-mini has no batch endpoint (400 "does not have a :batch endpoint") despite its :batch pricing listing.

  • Impact: The −50% OpenAI mini tier can't be used for the bulk stage.
  • Owner: Mohamed (account-side); may be OpenRouter rollout.
  • Next step: Keep using ds-flash / gemini-3.8-flash / gpt-5-nano batch; re-measure when gpt-5-mini routes appear (SPEC-015 open question).

• Risk: dsh web_search tool has no timeout — a stalled search backend deadlocks the whole workflow (the 2026-09-18 swarm hang).

  • Impact: Any future swarm using web_search can hang silently for hours.
  • Owner: harness config (deepseek-harness).
  • Next step: Add per-search timeout / retry cap in the harness; codetools' own SearchBudget hang guard (REQ-015-006) is already in the batch workbench.

Recently Resolved

• Resolved 2026-10-23: /opt/codetools/bin/orchestrata-tools failed with ModuleNotFoundError (session notes, 2026-10-22). After commit a5c419f5 moved orchestrata-ultimate to the openspec extra, the current release's bin/ has no orchestrata entry point at all.

• Resolved 2026-10-22: install 68 died at verify because the launch inherited PYTHONPATH=/opt/orchestrata-tools/shim, which the import-shadow guard rejects. ct-install now unsets PYTHONPATH and PYTEST_ADDOPTS (commit 6979a4ad).

• Resolved 2026-10-22: installs 70 and 71 exited 8 because test collection refused the tmpfs /tmp basetemp. collect_node_ids now passes an on-disk --basetemp (commit e1ffbc36).

• Blocker: all six remaining env-gated xfails → resolved (2026-09-21). Suite now 486 passed / 0 xfailed, gate ok. memgraph (.env URI fallback), ctest (run_ctest + real CTestTestfile fixtures), opentelemetry (real trace_otel span backend), tree-sitter ×3 (grammars rebuilt for cp314t — TS grammar regenerated via the npm CLI; see the runbook), pyinfra (real subprocess executor over a python3.11 venv — gevent has no free-threaded build, quarantined per ADR-I11).

• Blocker: memgraph un-gated needed a store + an install → resolved: own Memgraph 3.11.0 instance launched in the test environment (codetools-memgraph, Incus project orchestrata, bolt://10.222.9.240:7687, boot.autostart — the workspace incus/memgraph-launch.sh pattern); graph/memgraph_store.py implemented (neo4j bolt driver, MERGE-upserted facts, Cypher reverse-closure twin of affected_sym/2, parity_check vs the Prolog reference store); REQ-002-007 suites now run live (479 passed / 6 xfailed). MEMGRAPH_URI persisted in ~/.env.

• Blocker: Host tools missing (tofu) → resolved: OpenTofu v1.9.0 installed to ~/bin/tofu; the iac suites (engine identity, real tofu --version via the BDD scenario, impostor refusals) now run against the genuine binary — the tofu xfails flipped green (suite 475 passed / 7 xfailed).

• Blocker: the protected-branch boundary was bypassable (REQ-011-004) → resolved: refspec normalization at the boundary (refs/heads/ prefixes, inline + force) + regression tests; review record plans/REVIEW-IMPLEMENTATION-2026-09-21.md.

• Blocker: The live SPEC-015 batch run needed the OpenRouter key + a live window.

  • Resolution: Ran live 2026-09-21 (batch-1789995611): 10 units, $0.0008602, 9/10 usable (one finish_reason: length at the 600-token floor — the measured headroom trap, live-confirmed); price arithmetic reproduces the bill exactly. The run also exposed a real driver bug — results arrive as {custom_id, response: {body}} list entries and poll can race a transient 404 right after submit — both fixed with regression tests.

• Blocker: OpenRouter batch validation accepts reasoning-by-default models — small max_tokens yields empty answers (finish_reason: length).

  • Resolution: The recipe is now ENFORCED in batch/drivers/openrouter_batch.py (REQ-015-001): every bulk request must carry "reasoning": {"effort": "none"} + include_reasoning: false + max_tokens ≥ 600, rejected before the first network call.

• Blocker: OpenRouter key in ~/.env returned 402 Insufficient credits.

  • Resolution: The key belonged to a different (overdrawn −$0.21) account; the live key was in opencode's auth (~/.local/share/opencode/auth.json, account balance ≈ $89.55). Swapped into ~/.env; sync + batch now 200/202.

• Blocker: codetools-research-swarm workflow hung 2026-09-18 (3 of 7 research agents stuck in web_search; parent deadlocked ~2h50m).

  • Resolution: Recovered from session history; 4 reports salvaged, 3 research + 4 mining agents re-run, synthesis report written (SWARM-RESEARCH-2026-09-18.md).

• Blocker: SPEC-009 DAP sessions timed out under the real debugpy adapter.

  • Resolution: Root-caused: debugpy's --listen socket requires an attach handshake (deferred until configurationDone) and setBreakpoints must precede it; plus a leaked debugpy held the fixed port. Fixed with a reader-thread response matcher + ephemeral ports (ADR-I1).

Related

• codetools
• codetools deploy
• codetools plugin
• codetools MCP
• codetools decisions
• Deployment