docs: build orchestrator code trace

[dsmcewan]

What

Adds docs/build-orchestrator-trace.md: a line-level trace of build-gate/build-orchestrator.mjs on main at 0c9b539. It is the deep companion to §3.1 of the repository code trace in #193.

Contents:

• Where the file sits: its three exports, every import, and every static caller (tests, evidence runs, proposal-orchestrator.mjs).
• buildProject phase by phase with line numbers: what each phase returns, what is on disk when it exits, and which module re-derives each trusted input.
• makeTeamDispatch step by step (routing by id, declared-file clamp, re-resolve after mkdirSync, inner adaptation loop, respec hand-up) with a table of which test covers which behaviour and which branches are uncovered.
• makeTeamKeyring and the execution half it reaches in merkle-dag/orchestrate.mjs and ledger-gate.mjs.
• Six findings, each cited to source and two reproduced with a probe script:
  • F1: ok:true does not mean certified. In legacy advisory mode buildProject returns ok:true while council.certified === false.
  • F2: each node's test command runs three times on the happy path (dispatch pre-flight, Rule-3 verify, ledger-gate verify).
  • F3: the docstring phase list at :141 is stale (missing situation, pre-reorder order).
  • F4: the lifecycle councilContext/gateSource branches at :192-197 are dead (same as F7 in docs: repository code trace + fix the keyless evidence scripts broken by signed-by-default (F1, F1b) #193).
  • F5: a runBuild refusal (PLAN_TAMPERED, MUTATE_FAILED, …) would throw a TypeError at :223 instead of returning a phased result; the lifecycle path guards this at proposal-orchestrator.mjs:316.
  • F6: capability packets are never supplied to the gate from this entry point.
• Commit lineage of the file (seven commits, PR numbers) and a reading order.

Documentation only. No code, contracts, or governance records change.

Checklist

• Affected package suites run locally (list them below with results)
• No new dependencies or lockfiles in zero-dependency packages
• No runtime .telos/ artifacts, secrets, .env*, or *.pem files committed
• Hash-pinned/signed artifacts untouched (or regenerated through their own runners, with the regeneration described below)
• If governance records or contracts changed: not applicable, none changed

Test results

Node 22.22.2, on main at 0c9b539 (the doc adds no code, these verify the claims in it):

• node --check build-gate/build-orchestrator.mjs -> ok
• node build-gate/scripts/test-build-orchestrator.mjs -> 13 cases OK
• node build-gate/scripts/test-runtime-adaptation.mjs -> OK
• cd build-gate && npm test -> exit 0 (runs breakout too)
• probe script for F1/F2 (advisory legacy build): ok:true, certified:false, safe_next_action: advisory-only-NOT-certified-do-not-merge, node test executed 3 times

🤖 Generated with Claude Code

https://claude.ai/code/session_01JrjwsLBYk3FcnkneUTqqkQ

---

Generated by Claude Code

[dsmcewan]

CI status on 18b60d5:

• CI (ci.yml, all package suites + fail-closed proof): green.
• Claude Code Review / review (code-review.yml): failed. The job installed Claude Code, initialized, and returned is_error:true after 2 s with total_cost_usd: 0 and modelUsage: {}, so no review ran. That is the fast-fail signature the workflow's own comment describes for a lapsed CLAUDE_CODE_OAUTH_TOKEN (or exhausted subscription balance).

This is not this PR's failure: the diff is one Markdown file under docs/, and the same check failed identically on PR #193 (runs 293, 294, 295) and on about half of the 2026-09-20 dependabot PRs (#165, #167, #168), each within ~20 s and before any model call. No fix for it exists in the repository; the secret has to be re-minted with claude setup-token and stored as CLAUDE_CODE_OAUTH_TOKEN, which only a repo admin can do.

I have re-run the failed job once. If it stays red, this PR is waiting only on that secret.

---

Generated by Claude Code

[dsmcewan]

Follow-up on the review check, closing the test from my earlier comment.

Third attempt at 00:35 UTC (one hour after the first two) failed identically: CLAUDE_CODE_OAUTH_TOKEN is delivered to the job (masked *** in the action's env dump, so the secret is present and readable), OIDC and app-token exchange succeed, Claude Code 2.1.247 initializes on claude-sonnet-5, then the first turn returns is_error:true with total_cost_usd: 0 and empty modelUsage. PR #195's run at 00:04 failed the same way, as did every run on #193.

So this is not a missing vault entry and, given the hour's gap and the failure on a fresh PR, unlikely to be a transient usage cap. The remaining cause is the OAuth token itself (expired or revoked). Fix, for a repo admin: run claude setup-token and replace the CLAUDE_CODE_OAUTH_TOKEN secret. Nothing in this PR can change the outcome; no further re-runs from me until the secret changes.

Everything else on this PR is green and mergeable.

---

Generated by Claude Code

[dsmcewan]

Resolved. After the CLAUDE_CODE_OAUTH_TOKEN secret was replaced, the re-run of the review job at 04:42 UTC completed successfully in 43 s and posted no findings. All 32 checks on 18b60d5 are green, there is no merge conflict, and there are no open review threads. The PR is now waiting only on human review; it is still marked as a draft.

---

Generated by Claude Code