Orchestrata Ultimate › Plans › handoff-component-fixes-2026-10-20
Handoff — component fixes, continue from here
Source: plans/handoff-component-fixes-2026-10-20.md at 8a2cb42ad · last changed 2026-10-19 · first committed 2026-10-19 · 151 lines.
Prose pending.
Plan text
Handoff — component fixes, continue from here
Status: handoff for the next model. Session 272, branch components, worktree /home/mohamed/workspace/wt-COMPONENTS. Written 2026-10-20.
Read this file first. Then plans/component-fixes-2026-10-19.md and AGENTS.md § "Recognize tools, read the ontology, load the skill". Do not restart finished packets.
0. How to start
- Read
~/workspace/knowledge-wiki/rulings/index.md. Do not callwiki get.~/.local/bin/wikiis not installed. - Read the ontology before describing architecture:
~/workspace/knowledge-wiki/projects/orchestrata-ultimate/architecture-ontology.md~/workspace/knowledge-wiki/projects/orchestrata-ultimate/component-dag.md
- Load the matching skill before the first use. Skill dirs:
~/.claude/skills/, this repo's.claude/skills/and.opencode/skills/.canvasis~/.local/bin/canvas. Load the canvas skill before drawing. - You are the coordinator. Workers do the edits. You verify, then commit an explicit file list. No
--no-verify. No push unless Mohamed asks. - Do not
git add -A. The tree is dirty with files this session did not own.
1. What is already done
| Packet | State | Evidence |
|---|---|---|
| P1 roots + LEVEL0 | committed | cb835859c. Eight packages/<name>/src roots in env/ast-roots.env. packages/knowledge_graph/src, not the ADR-0114 typo packages/kg/src. Integration not added. LEVEL0 says cut-over has not happened. |
| P2 ontology page | written, not in the Wiki.js UI | ~/workspace/knowledge-wiki/projects/orchestrata-ultimate/component-dag.md. Publish by committing that repo. Wiki.js pulls. wiki-kimi remember does not publish. |
| P3 tools seams (ADR-0112) | committed and verified | 9bf101eb9. grep -R orchestrata_kernel packages/tools/src exits 1. orchestrata-kernel is gone from packages/tools/pyproject.toml. Protocols: packages/contracts/src/orchestrata_contracts/protocols/redis_factory.py, embedding_port.py. Default embedding: packages/tools/src/orchestrata_tools/embedding_default.py. |
| ADR-0114 graph sync | done for the named checks | Prod orchkg, project orchestrata-ultimate. Measured 2026-10-20T01:59:52Z. |
Verification queries, all passing:
| Check | Count |
|---|---|
Modules whose file_path contains orchestrata_contracts |
403 |
| Spec | 71 |
| Requirement | 639 |
| RequirementItem | 5786 |
| TRACES_TO from this project's code | 15366 |
| Module nodes | 5232 |
| Method nodes | 31706 of 31730 rows |
Package module counts: contracts 403, governance 254, knowledge_graph 161, kernel 411, session 59, volks 382, gateway 73, tools 28.
Commits on components, not stated as pushed:
cb835859cADR-0114/0113 roots + LEVEL09bf101eb9ADR-0112 tools seams
Accepted ADRs, do not edit the bodies: docs/adr/0112-*.md, 0113-*.md, 0114-*.md.
2. What the next model does, in order
Step A — ontology seed (graph write, after a reviewed module)
The ratified ontology already has Component (id = "{project}:{name}") and DEPENDS_ON. No new node type.
A worker writes a seed module that calls only:
ArchitectureWriter.upsert_componentinpackages/knowledge_graph/src/orchestrata_kg/knowledge_graph/architecture_writer.pyArchitectureWriter.link_depends_on(from_component_id, to_component_id)
The worker does not open a Bolt connection. The coordinator runs the seed after review, against prod orchkg, project slug orchestrata-ultimate.
Rows, from plans/component-fixes-2026-10-19.md §4.2. Tools depends on contracts, knowledge_graph, governance. Not kernel. That is ADR-0112.
| name | import | depends_on | required |
|---|---|---|---|
| contracts | orchestrata_contracts | — | yes |
| governance | orchestrata_governance | contracts | yes |
| knowledge_graph | orchestrata_kg | contracts | yes |
| kernel | orchestrata_kernel | contracts, governance, knowledge_graph | yes |
| session | orchestrata_session | contracts, knowledge_graph, governance | yes |
| volks | orchestrata_volks | contracts, kernel, knowledge_graph, governance | yes |
| gateway | orchestrata_gateway | contracts, kernel, session, knowledge_graph, governance | yes |
| tools | orchestrata_tools | contracts, knowledge_graph, governance | yes |
| integration | orchestrata | kernel, gateway, volks, session, knowledge_graph, governance, tools | no, until it lands |
| plugin | — | gateway, tools, integration | no |
required=no on integration means the node exists as a design component and is not yet a running one. It is not permission to skip building it.
Verify, read-only, after the run: a Component with id orchestrata-ultimate:tools exists, and it has DEPENDS_ON to contracts, knowledge_graph, and governance, and not to kernel.
Step B — INT-01 only
ADR-0113 says L1 builds now. Do not dispatch "build integration". INT-01 only.
Source of the increment, already written:
packages/integration/increments/README.mdrow INT-01packages/integration/design/decisions.mdD-I13 and D-I1
INT-01 is the SPEC-125 delta plus the release scaffold: package inits, release pyproject.toml with component pins and console scripts. No residue reopened in the eight landed packages. Fence: packages/integration/** only. There is no INT-01.md brief yet. Write the brief from those two files, then dispatch a worker. Later increments INT-02..INT-25 are separate briefs. Do not start them in this packet.
Step C — documentation corrections still open
- Publish the wiki pages by committing
~/workspace/knowledge-wiki. Wiki.js pulls (procedures/wikijs-publish-path.md). Pages already edited and not necessarily committed:projects/orchestrata-ultimate/component-dag.md,agents/claude.md,README.md, and the session page next to this handoff. - Memory file
~/.claude/projects/-home-mohamed-workspace-orchestrata-ultimate/memory/components-replaces-ultimate.mdstill says tools are not a package. Replacement sentence, from the plan §4.3: tools landed aspackages/tools(orchestrata_tools) by ADR-0107; codetools remains the separate toolbox; ADR-0112 removes the tools package's kernel imports. A write was permission-denied in session 272. Retry. Do not invent a second memory.
Step D — do not do these
- Do not re-run the suite to decorate a report (RUL-032).
- Do not semantic-re-embed. Count the RAG corpus on a healthy main first. ADR-0109's 500-row bound stays. The count is still unknown.
- Do not edit Accepted ADR bodies, including the
packages/kg/srctypo. A superseding ADR is owed only if Mohamed asks. - Do not remove
src/orchestrata_ultimate. Cut-over has not been reached. - Do not add a node type.
- Do not
sync_ast_to_graph.py fullagain unless the verification queries in §1 fail. A full sync clears the project. The first one died on a SYNC-replica RPC timeout after Class and Function nodes. The resume did not clear, and it finished methods, parameters, and edges. Re-clearing to chase the ADR's expected path prefixpackages.<name>.src…is a new decision. Measured prefix issrc.orchestrata_<import>…because each declared root's directory is namedsrc.file_pathstill carriespackages/<name>/src/…. - Do not point a traces walk at
packages/<name>(the distribution root). That walks.venv. Harvestpackages/<name>/srcand prefix qualified names withsrc.so they match the graph. The stockscripts/sync_traces_to_graph.pymatcher is too slow on this graph (seconds per handful of names). The operational writer was/tmp/opencode/kg_traces_fast.py. It is a scratch script, not a committed fix. - Do not write the test fleet (
10.53.2.10) and call it the graph agents read. Prod identity:KG_ROUTING_URI=neo4j://10.53.1.160:7691, databaseorchkg, fromenv/prod.env. Direnv in this worktree overlaysenv/test.envand will send an unscoped client at the test fleet.
3. Graph facts the next model must not rediscover
Cluster, measured 2026-10-20: instance_2 main at 10.53.1.123:7687, health up. instance_1 replica at 10.53.1.128:7687, health up, sync mode, behind 0 on orchkg when last checked. Coordinators: 10.53.1.160, 10.53.1.109 (leader), 10.53.1.198. SHOW INSTANCES only works on a coordinator bolt port, not on the neo4j:// routing URI.
The routing URI dropped a Bolt handshake during the traces write. The traces write went to the measured main, bolt://10.53.1.123:7687. Re-check SHOW INSTANCES before any prod write. Do not write to the replica.
24 method rows collapsed on duplicate qualified names (31706 nodes from 31730 rows). Module DEFINES is 72301, which matches that collapse. This is not a failed sync.
scripts/sync_ast_to_graph.py DEFINES uses a multi-label MATCH (b:Class|Method|Function). orchgraph 3.11 collapses that UNWIND to one row per distinct key. The resume wrote DEFINES as three single-label passes. Do not "fix" the live graph by re-running the stock method.
4. Model routing
RUL-037 still says a brief whose fence lists a .py file goes to sonnet until M2. Sonnet was unusable in session 272 (Claude monthly spend limit, reset 6pm Detroit 2026-10-20). Mohamed then chose option 1: openrouter/deepseek/deepseek-v4-pro. That route works in this OpenCode CLI. The native deepseek/deepseek-v4-pro route does not. opencode models prints openrouter/deepseek/deepseek-v4-pro, not a deepseek/ line. Adding a provider block to packages/design-scripts/dispatch/templates/opencode-headless.json did not create the route.
If sonnet is still spend-limited, use openrouter/deepseek/deepseek-v4-pro for the worker and say so. Do not retry deepseek/ until opencode models prints a deepseek/ line.
env/test.env sets DEEPSEEK_API_KEY= empty on purpose, after .envrc loads .env. A worker under direnv sees a blank key. The real key is in .env. Do not print it. Do not commit it. Do not remove the blank from env/test.env.
5. Files
Read:
plans/component-fixes-2026-10-19.md— packet contractreports/project-analysis-2026-10-19.md— the measurements the ADRs ratifieddocs/adr/0112-tools-reaches-redis-and-embeddings-through-contracts-protocols-not-kernel-imports.mddocs/adr/0113-*.mdanddocs/adr/0114-orchkg-sees-the-component-packages-and-spec-and-requirement-nodes-are-in-scope.mdpackages/integration/design/decisions.md(D-I1, D-I13)packages/integration/increments/README.md(INT-01 row)
Uncommitted, and part of this work. Review, then commit an explicit list. Do not mix them with the unrelated dirty files.
plans/component-fixes-2026-10-19.mdplans/briefs/adr-0112-tools-seams.mdplans/briefs/adr-0114-roots-and-level0.mdreports/project-analysis-2026-10-19.mdplans/handoff-component-fixes-2026-10-20.md(this file)AGENTS.md,CLAUDE.md,README.md— the tool/ontology/skill instructions added 2026-10-20packages/design-scripts/dispatch/dispatch.pyandtemplates/opencode-headless.json— DeepSeek launch experiments. The native route still fails. Do not commit these unless you have re-read them and they do not log the key.
Unrelated dirty files seen in this session, not this packet: deploy/ship.sh, docs/CODEBASE_MAP.md, docs/CODEBASE_MAP_FULL.md, scripts/run_tests.py, scripts/observe_pytest.py, promotion and pytest-observer sources, plans/ast-*.json, context.json, reports/precommit-walls.ndjson, reports/run-tests-latest.json. Leave them.
packages/contracts/.../redis_factory.py, embedding_port.py, and packages/tools/.../embedding_default.py showed as modified again after 9bf101eb9. Diff them before any commit. Do not assume the extra diff is yours.
6. Definition of done for whatever you ship
ADR-0069 / RUL-034, same ship as the code: @traces, RTM evidence, docs, wiki page, and ≥90% line coverage on every source file you create or modify. Workers do not commit. You verify the brief's checks, then commit the explicit file list.