docs(governance): align AGENTS/CLAUDE LLM guidance with canonical orchestrator owner

[seonghobae]

Finding

Protected develop@042b0c70531b229af3acbd0421a2f23098d848b3 contains two live agent-authority contradictions that can steer future writers into a forbidden routing path.

AGENTS.md still states that the central Strix required workflow uses GitHub Models by default via STRIX_GITHUB_MODELS_TOKEN, https://models.github.ai/inference, explicit GitHub-model fallbacks, and manual direct-provider modes. The live CWL contract now assigns model routing/fallback to the canonical ContextualWisdomLab/contextual-orchestrator owner and requires model-backed Actions to consume the central .github reusable workflow through orchestrator/free; Naruon must not recreate provider/model routing authority.

CLAUDE.md also diagrams the FastAPI control plane as calling OpenAI-compatible LLM providers directly and describes LLM base_url as a Naruon egress surface. That language no longer matches the intended canonical-owner boundary for production LLM work. Local deterministic/non-production model fixtures may remain where explicitly documented, but they must not be presented as production provider authority.

Exact protected blobs at finding time:

• AGENTS.md blob 9104dd1f4baaf64cf9083e83d798d2fca799b5b0
• CLAUDE.md blob be67bc80c989157aad087055bc20b1b8e189d3b1

No open Naruon PR or issue matched the exact STRIX_GITHUB_MODELS_TOKEN stale contract at discovery time, so this is not knowingly duplicating an existing leaf owner.

Repair boundary

Keep this as a Naruon docs/governance repair. Do not edit .github or contextual-orchestrator source from this repository, copy their implementation, introduce a mutable cross-repo dependency, or add a repo-local model workflow.

Update AGENTS.md and CLAUDE.md so they describe only the released central owner contract that Naruon actually consumes. The text should distinguish:

• Naruon-owned domain/tool/context authorization from LLM provider/model routing;
• central .github workflow consumption from repo-local workflow ownership;
• production orchestrator/free behavior from explicitly non-production/local deterministic fixtures;
• owner-path failure handling: fail closed and repair the canonical owner rather than falling back to a direct provider.

Search the same protected head for adjacent direct-provider/GitHub-Models prose and repair only statements that are stale under the same contract. Preserve unrelated historical documentation unless it is presented as current guidance.

RED / GREEN

RED: a deterministic docs-contract test or equivalent repository check demonstrates that live agent guidance still contains current-production assertions for STRIX_GITHUB_MODELS_TOKEN, models.github.ai, or direct production provider routing outside the canonical boundary.

GREEN: the exact PR head has no contradictory current-production routing guidance; AGENTS/CLAUDE agree with applicable ADR/architecture and central owner semantics; existing required workflow/security checks remain unchanged; exact-head OpenCode/Noema evidence and post-last-push independent approval satisfy the then-live protected rules.

Do not weaken gates, create dummy commits, self-approve, force-push, or treat central review-control failures as Naruon source defects.

[seonghobae]

Repair lane is now open as #1549 on docs/align-llm-owner-guidance from protected develop@042b0c70531b229af3acbd0421a2f23098d848b3.

RED is executable at fb2c244c0b9d5459a47ee57c6075907f6ae288c4: backend/tests/test_agent_llm_authority_docs.py rejects the stale STRIX_GITHUB_MODELS_TOKEN / models.github.ai / direct-provider guidance and requires the canonical contextual-orchestrator owner plus fail-closed boundary.

A bounded branch-only source-repair workflow at 45f115de3c1f019daf51551fd4e475b6c7fb1937 is queued to patch the large AGENTS/CLAUDE files, run the focused contract and git diff --check, commit the causal repair, and delete itself in the same successor. It uses pinned actions and contents: write only on this branch. No direct-provider fallback or mutable contextual-orchestrator dependency is being introduced. Keep #1548 open until #1549 reaches exact-head GREEN and normal protected merge.

[seonghobae]

Progress on canonical repair PR #1549: ordinary source commits now move CLAUDE.md off the direct-provider architecture description. Exact current head is 75e6c09c03dcb79cedbff60dfd87696a9ec60f71, direct child lineage with no force-push; protected-base compare is behind_by=0 and the net PR delta is currently CLAUDE.md + backend/tests/test_agent_llm_authority_docs.py. CLAUDE.md now names the released contextual-orchestrator consumer contract, assigns provider/model routing to that owner, keeps Naruon ownership at product/domain/tool/authorization/context assembly, marks direct-provider base_url surfaces as migration debt, and keeps Ollama/MLX local paths non-production only.

The issue is intentionally still open: AGENTS.md retains the stale GitHub-Models/direct-provider Strix policy block, so the deterministic docs contract remains RED. Fresh exact-head PR workflows were regenerated by the source push and are queued/pending; no predecessor check or approval is being carried forward.

[seonghobae]

Current repair evidence after fresh diff validation: #1549 advanced non-force to a2b0a315d68fd5dbe070af0d07d8c6febef3911f. The intended AGENTS.md authority edit at predecessor 6ca9879c1bb55b7240f9adfa8585510568ec887d correctly removed the stale GitHub-Models/direct-provider routing block, but commit-diff inspection found an unrelated collateral deletion of the final Code-owner review gates — disabled (on hold) policy because the bounded source snapshot was incomplete. That is not acceptable completion evidence. Direct non-force child a2b0a315... restores the exact protected-base AGENTS.md blob, preserving the intervening commit in history and avoiding force-push/rebase. Net protected-base delta is therefore back to the valid CLAUDE.md authority repair plus the intentional RED docs-contract test; AGENTS.md remains the open causal repair. Fresh exact-head workflows were regenerated and are queued/pending, so #1548 remains open and #1549 remains Draft.

[seonghobae]

Fresh adjacent governance evidence — 2026-09-09

Protected develop@042b0c70531b229af3acbd0421a2f23098d848b3 still has the same owner-boundary contradiction outside AGENTS/CLAUDE in root ARCHITECTURE.md blob 9d2cbba18126830bc3def90a67aef80859dafa6d: the current system-shape diagram says API --> LLM[OpenAI APIs when configured].

This is current-architecture prose, not historical documentation, so it should be consumed by this existing canonical governance lane under the issue's own instruction to search adjacent direct-provider prose. Repair should describe Naruon as consuming the released contextual-orchestrator contract/ACL rather than owning direct provider routing, while keeping local deterministic/non-production fixtures explicitly separate. No new competing docs PR/issue is needed.

[seonghobae]

2026-09-15 authority update: the Naruon LLM-governance stack was non-force repaired against the current dependency-security owner rather than mechanically restacked. #1528 is now zero-effective-delta provenance at ee2540c9efbfa8261e5517ecfff5d37c2701fa37 (exact #1623 tree), #1549 is the active successor at 34850c3decc2e27f9d78e6583d6b917c68e650e8, and #1625 consumes that stack at f740158a4a8367adc63eb3763a99cdd6b7ca68ac. The repair removes stale dependency/test/lock reversions from the governance stack.

Issue remains open: #1549's older AGENTS/CLAUDE blobs still delete the newest #1623 pnpm importer-provenance guidance (4 lines in AGENTS, 5 in CLAUDE). Executable dependency-security contracts are preserved, but docs are not yet code-current. Do not mark #1548 complete or merge #1549/#1625 until those two doc overlaps are semantically restored and the final unchanged heads receive fresh checks/review.