docs(directive): sync product-goal-directive.md with the user's current text

[seonghobae]

Summary

• Closes the "loop-prompt-vs-file drift" question two peer sessions independently flagged to the user this cycle: I now have the user's actual current /loop text (pasted directly into this session) and diffed it against docs/product-goal-directive.md section by section.
• Six of nine sections had genuinely new content missing from the file — appended as dated addenda, preserving every existing quoted section and prior Devin/CodeRabbit correction note untouched.
• docs/doctoring/product-goal-directive-sync-20260903.md records the full diff table and resolves the open question: the "i18n list" and "core-foundation ownership map" content a peer had briefly mis-cited as being in the wrong section of the file was real content — it just wasn't in the file at all yet.

Test plan

• Docs-only change; ran the two existing contract tests that assert specific substrings of docs/product-goal-directive.md (tests/test_noema_orchestrator_workflow_contract.py, tests/test_pr_review_autofix_writer_security_contract.py) — both pass, confirming the pinned substrings survived the edit.
• python3 -m pytest tests/test_noema_orchestrator_workflow_contract.py tests/test_pr_review_autofix_writer_security_contract.py -q → 16 passed.

🤖 Generated with Claude Code

---

[coderabbitai]

Warning

Review limit reached

Next included review available in 8 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: f1c34df8-2291-4be7-b4f9-fa17f2130761

📥 Commits

Reviewing files that changed from the base of the PR and between fe827e1 and 6c296c7.

📒 Files selected for processing (2)

• docs/doctoring/product-goal-directive-sync-20260903.md
• docs/product-goal-directive.md

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[seonghobae]

The single red check here is not caused by this pull request and cannot be fixed from this branch. Recording the evidence so the next person does not spend the diagnosis again, and re-running only the failed job rather than pushing a commit.

What actually failed

noema-review, run 33969604299, step Prepare Noema model verdict, on a runner it held for 35.5 minutes:

"provider": "nvidia_nim"
"provider": "nvidia_nim_sub"      "error_type": "HTTPError"
"provider": "nvidia_nim_sub"      "error_type": "HTTPError"
"provider": "nvidia_nim_sub"

##[error]Noema gateway transport failed: HTTPError: HTTP Error 503: Service Unavailable;
         caller attempts=1, duration=1433.5s, phase=response_error,
         served_model=deepseek-ai/deepseek-v4-flash-0731

Every route the sidecar probed is nvidia_nim or nvidia_nim_sub — no OpenRouter or Bytez route at all, so the gateway's failover loop had a single upstream family to fail over within. When that family stalled it held the slot for 1433 s and returned 503 to the caller.

This is the org-wide chain already root-caused elsewhere: scripts/ci/contextual_orchestrator_review_launcher.py:129 drops every OpenRouter row before serving —

return [model for model in (discovered or []) if not getattr(model, "evidence_only", False)]

— while the policy layer had admitted free routes across three credential accounts. #1476 is the fix and is still open (mergeable, behind); that line is unchanged on main as of this comment.

Why no commit was pushed here

This PR is documentation-only (docs/product-goal-directive.md). Nothing in its diff reaches the review sidecar. A commit would have:

• failed the same way, since the launcher defect is still live on main — merging main in does not help either;
• re-fanned all 22 checks, of which 13 are currently green, forcing them to be re-earned in a queue that is at its 60-job ceiling;
• burned another multi-minute runner slot on the same 503.

Instead I re-ran only the failed job (rerun-failed-jobs, now attempt 2, queued). The 13 green checks are untouched. A retry can pass if it lands on a healthy NVIDIA endpoint, which is the only lever available from this side until #1476 lands.

If this check goes red again with the same nvidia_nim-only probe list and a 5xx, that is the same structural failure, not a regression in this PR.

🤖 Generated with Claude Code

[seonghobae]

Correction to my comment above: the cause I named is wrong. The conclusion is unchanged — this failure is not from this PR and no commit here fixes it — but the mechanism is not the launcher's evidence_only filter. I verified the real one from source before writing this.

scripts/ci/contextual_orchestrator_review_launcher.py:129 does drop evidence_only rows, but on the pinned contextual-orchestrator revision OpenRouter rows carry evidence_only=False and pass through it. That line is a hardening concern, not what starved this run.

What actually starves it — an account cap the sidecar raises above the policy default.

scripts/ci/contextual_orchestrator_review_sidecar.sh:38   CATALOG_LIMIT="${ORCHESTRATOR_CATALOG_LIMIT:-12}"
scripts/ci/contextual_orchestrator_review_sidecar.sh:43   CATALOG_ACCOUNT_CAP="${ORCHESTRATOR_CATALOG_ACCOUNT_CAP:-8}"

scripts/ci/contextual_orchestrator_review_policy.py:34    DEFAULT_CATALOG_LIMIT = 12
scripts/ci/contextual_orchestrator_review_policy.py:35    DEFAULT_ACCOUNT_CAP = 4

build_zdr_prioritized_catalog sorts by (cost_rank, zdr_rank, provider, model) — provider is the third key, so ties break alphabetically — and then fills:

for row in eligible_rows:
    account = provider_account(str(row["provider"]))
    if per_account[account] >= account_cap:   # 8, from the sidecar
        continue
    per_account[account] += 1
    picked.append(row)
    if len(picked) >= limit:                  # 12
        break

nvidia_nim < nvidia_nim_sub < openrouter alphabetically. With account_cap = 8: nvidia_nim takes 8 and hits its cap, nvidia_nim_sub takes 4, len(picked) reaches the 12 limit, and the loop breaks before OpenRouter is ever examined. With the policy's own default of 4 it would be 4 + 4 + 4 — three accounts, same 12 routes.

That is the 8 + 4 in the log quoted above, and why the failover loop had one upstream family to fail over within before returning 503 after 1433 s.

Credit: jan lane found and corrected this after host1 refuted the launcher explanation from source; I re-derived the cap/sort interaction here rather than relaying it.

What does not change: this PR is documentation-only, nothing in its diff reaches the sidecar, and merging main in does not help — the cap line is unchanged on main. Re-running only the failed job (attempt 2) was still the right lever, and the 13 green checks are still untouched. #1476 is not the fix for this; the fix is a change to the sidecar's cap default plus round-robin fill across accounts within a tier, which the jan lane has claimed.

🤖 Generated with Claude Code

[seonghobae]

noema-review 실패 원인은 이 브랜치가 아닙니다 — 게이트웨이 상류입니다 (6c296c7b)

직전 헤드 cb7c1f5b의 noema run(33993350600)은 실제로 실행됐고(잡 17스텝, runner 1001695032) 13번 스텝 Prepare Noema model verdict에서 죽었습니다. 로그의 종결 라인:

##[error]Noema gateway transport failed: HTTPError: HTTP Error 502: Bad Gateway;
         caller attempts=1, duration=3576.0s, phase=response_error
##[warning]Noema gateway attempt outcome=failed phase=response_error
           duration=3576.0s served_model=deepseek-ai/deepseek-v4-flash-...

3576초(59.6분)를 소비하고 502입니다. 이 PR 트리에 있는 어떤 것도 이 결과를 만들지 않습니다.

일회성이 아닙니다

.github의 최근 noema 실패 4건을 표본으로 종결 라인을 뽑았습니다:

run	phase	duration	served_model
33995259290	validating	324.2s	dots-studio/dots-3-note-preview:free
33994984541	response_error	575.5s	deepseek-ai/deepseek-v4-flash-0731
33993637015	response_error	542.2s	deepseek-ai/deepseek-v4-flash-0731
33993624878	response_error	998.9s	deepseek-ai/deepseek-v4-pro-0813

모델도 소요시간도 제각각인데 phase=response_error(게이트웨이 HTTP 오류)로 수렴합니다. 최근 100건 분포는 success 11 / failure 36 / cancelled 34 / queued 13 / in_progress 6입니다.

같은 로그에 사이드카 기동 경고도 있습니다(치명적이진 않음): provider_discovery_failed provider=bytez code=http_status_50x.

이번에 한 것

문제의 run은 created_at 21:32:39Z로 #1939 머지(17:25:33Z) 이후 생성이라 이미 현행 라운드로빈 카탈로그로 돌았습니다. 즉 카탈로그 구성 문제가 아닙니다.

그래서 범위 안에서 실제로 유효한 것만 했습니다 — 이 헤드가 다시 behind가 되어 있었으므로 현재 main(fe827e13)을 병합했습니다. 새 리뷰 시도는 그에 딸려옵니다. 게이트: uvx ruff check --select F821 All checks passed, 전체 스위트 2904 passed / 0 failed. fast-forward, force push 없음.

noema-review를 "고쳤다"고 주장하지 않습니다. 그 체크는 게이트웨이가 5xx를 그만 반환할 때 초록이 됩니다. 이 PR 브랜치에서 할 수 있는 일이 아닙니다.

🤖 Generated with Claude Code

[seonghobae]

세 번째 noema-review 실패 — 이번엔 원인이 다르고, 재푸시하지 않았습니다

새 헤드 6c296c7b의 run 34001934528은 이전과 다른 스텝에서 죽었습니다: 13번 Prepare Noema model verdict(59.6분 후 502)가 아니라 12번 Provision contextual-orchestrator review sidecar(5분 26초). 즉 모델 호출까지 가지도 못했습니다.

#1944가 추가한 noema-sidecar-evidence 아티팩트(9981236606)를 받아 contextual-orchestrator-preflight.json을 그대로 파싱했습니다. 로그 라인은 잘려 있어 파싱이 안 되므로 아티팩트가 권위 있는 기록입니다.

probed=12  ready=0  rejected=12  escalation_budget=4  escalations_used=0

provider	http_status	model
nvidia_nim	404	google/gemma-3-12b-it
nvidia_nim	404	google/gemma-3-4b-it
nvidia_nim	429	deepseek-ai/deepseek-v4-flash-0731
nvidia_nim	TimeoutError	deepseek-ai/deepseek-v4-pro-0813
nvidia_nim_sub	404	google/gemma-3-12b-it
nvidia_nim_sub	404	google/gemma-3-4b-it
nvidia_nim_sub	429	deepseek-ai/deepseek-v4-flash-0731
nvidia_nim_sub	TimeoutError	deepseek-ai/deepseek-v4-pro-0813
openrouter	429	cohere/north-mini-code:free
openrouter	429	dots-studio/dots-3-note-preview:free
openrouter	429	google/gemma-4-26b-a4b-it:free
openrouter	429	google/gemma-4-31b-it:free

좋은 소식 — #1939의 4+4+4가 프로덕션에서 확인됩니다

nvidia_nim 4 / nvidia_nim_sub 4 / openrouter 4. 라운드로빈 카탈로그 채우기는 의도대로 동작합니다. 병목이 "카탈로그 구성"에서 **"경로 건강성"**으로 옮겨갔습니다.

나쁜 소식 — 12슬롯 중 4개가 구조적으로 낭비됩니다

두 NVIDIA 계정이 완전히 같은 4개 모델을 중복 탐침합니다. 계정만 다르고 모델 다양성은 0입니다. 그중 gemma-3-12b-it과 gemma-3-4b-it은 양쪽 계정 모두 404(상장 폐지로 보임)라, 12개 슬롯 중 4개가 매 실행마다 확정적으로 죽습니다. 남은 8개는 429 6건 + 타임아웃 2건입니다.

그리고 escalation_budget=4인데 escalations_used=0입니다 — 12/12 전멸 상황에서 에스컬레이션 예산 4를 하나도 쓰지 않았습니다.

이 두 가지는 이미 추적 중인 항목과 겹칩니다(#1947 transient-rejected 경로 처리, #1949 preflight served set, #1458 escalation budget 순서 편향). 429는 로그에서 transient=True로 분류됩니다. 중복 제기 대신 이 실행의 1차 증거만 남깁니다.

왜 이번엔 푸시하지 않았는가

앞선 두 번은 각각 명분이 있었습니다 — 1차는 구 사이드카 바인딩 해소, 2차는 behind 해소. 지금은 헤드가 최신이고 병합 차단 요인이 없습니다. 남은 유일한 실패는 12/12 경로가 404·429·timeout으로 거부되는 상류 상태이고, 여기에 푸시를 더하면 포화된 대기열(noema queued 11, opencode queued 9)에 리뷰 run을 하나 더 얹어 429를 악화시킬 뿐 성공 확률을 올리지 못합니다.

noema-review는 경로 건강성이 회복되면 초록이 됩니다. 이 PR 브랜치에서 할 수 있는 일이 아니며, 같은 이벤트가 또 오면 그것도 같은 상류 상태의 재보고일 것입니다.

🤖 Generated with Claude Code

[seonghobae]

opencode-review + strix — 세 체크가 하나의 원인으로 수렴합니다 (푸시 없음)

이번 이벤트는 앞의 세 번과 달리 다른 체크였으므로 새로 조사했습니다. 결론: noema-review·strix·opencode-review가 전부 같은 지점에서 나옵니다.

측정

먼저 한 가지 함정: actions/runs?head_sha=는 opencode run 34001934485를 **queued**로 보고합니다. 하지만 그건 coverage-evidence가 아직 대기 중이라서이고, 그 안의 opencode-review 잡은 이미 실패했습니다. run-level 상태는 잡 실패를 가리지 못합니다 — 체크런/잡 레벨로 봐야 합니다. strix는 아예 체크런이 아니라 커밋 상태로 게시됩니다(state=failure, desc=Default-branch repository_dispatch Strix evidence failed).

체크	어디서 죽나	근거
noema-review	스텝 12 Provision contextual-orchestrator review sidecar	probed=12 ready=0 rejected=12
strix	스텝 16 Provision contextual-orchestrator Strix sidecar (run 34004185698)	probed=12 ready=0 rejected=12
opencode-review	스텝 3 Fail closed without a current-head OpenCode verdict (5초)	아래 참조

두 사이드카 preflight는 동일한 서명입니다: probed=12 ready=0 rejected=12 escalation_budget=4 escalations_used=0. strix 로그에서 복원 가능한 경로도 noema와 정확히 일치합니다 — deepseek-v4-flash-0731 429(양쪽 NVIDIA 계정), openrouter free 모델 429, gemma-3-12b-it 404(양쪽 계정).

opencode-review의 실패는 설계된 fail-closed입니다. 로그 원문: No APPROVED or CHANGES_REQUESTED from opencode-agent on the current head. The dispatch workflow will rerun this failed job after publishing an .... 즉 dispatch가 판정을 게시하면 재실행되는 구조인데, dispatch 워크플로 자신이 같은 사이드카 문제로 실패하고 있습니다(최근 opencode-review-dispatch run 중 02:03·02:05·02:06 생성분이 failure).

부수 발견 — strix 쪽에는 증거 아티팩트가 없습니다

#1944가 추가한 noema-sidecar-evidence(preflight JSON + 사이드카 stderr) 덕분에 noema는 12개 경로 전체를 정확히 읽을 수 있습니다. strix run은 strix-reports만 업로드하고, 로그의 preflight 라인은 문자 2333에서 잘립니다. 그래서 strix 쪽은 헤더 숫자와 앞부분 6개 경로까지만 복원 가능하고 나머지는 소실됩니다. #1944와 같은 아티팩트를 strix 경로에도 붙이면 이런 진단이 대칭이 됩니다.

왜 또 푸시하지 않았는가

세 체크 모두 이 PR 트리와 무관한 단일 상류 원인입니다. 헤드는 최신이고 병합 차단 요인이 없습니다. 푸시는 포화 대기열에 run을 더할 뿐 12/12 경로 거부를 바꾸지 못합니다. 이 표면은 이미 #1947(transient-rejected 경로) · #1949(preflight served set) · #1458(escalation budget 편향)로 추적 중이라 중복 제기도 하지 않았습니다.

🤖 Generated with Claude Code