refactor(ai): route Four Pillars through orchestrator/free

.env.example

@@ -6,20 +6,11 @@ DATABASE_URL=sqlite:///artifacts/jobs.sqlite3
 REPORT_RETENTION_DAYS=30
 API_KEY_SHA256=
 
-# Standalone default: direct hosted NVIDIA NIM.
-INTERPRETATION_BACKEND=nvidia_nim
-NVIDIA_NIM_API_KEY=
-NIM_BASE_URL=https://integrate.api.nvidia.com/v1
-NIM_MODEL=nvidia/llama-3.3-nemotron-super-49b-v1.5
-NIM_EVAL_MODEL=nvidia/llama-3.3-nemotron-super-49b-v1.5
-NIM_TIMEOUT_SECONDS=120
-NIM_MAX_RETRIES=3
-NIM_MAX_SCHEMA_REPAIRS=1
-
-# Optional organization gateway. Use INTERPRETATION_BACKEND=contextual_orchestrator.
+# Product LLM path: Contextual Orchestrator only.
+INTERPRETATION_BACKEND=contextual_orchestrator
 CONTEXTUAL_ORCHESTRATOR_BASE_URL=http://127.0.0.1:8100/v1
 CONTEXTUAL_ORCHESTRATOR_TOKEN=
-CONTEXTUAL_ORCHESTRATOR_MODEL=contextual-orchestrator
+CONTEXTUAL_ORCHESTRATOR_MODEL=orchestrator/free
 # auto allocates between one-agent routing and deeper conduct; route/conduct force a bounded mode.
 CONTEXTUAL_ORCHESTRATOR_MODE=auto
 CONTEXTUAL_ORCHESTRATOR_TIMEOUT_SECONDS=120

.github/workflows/hourly-product-loop.yml

@@ -65,7 +65,7 @@ jobs:
           run_gate 'Python compilation' python -m compileall -q src tests scripts
           run_gate 'Project documents' python scripts/check_docs.py
           run_gate 'Versioned prompts' python scripts/check_prompts.py
-          run_gate 'Offline tests and 100% coverage' pytest -m 'not nim_live' -W error::ResourceWarning --cov=four_pillars --cov-report=term-missing
+          run_gate 'Offline tests and 100% coverage' pytest -m 'not orchestrator_live' -W error::ResourceWarning --cov=four_pillars --cov-report=term-missing
           run_gate 'Distribution build' python -m build --no-isolation
 
           cat "$report" >> "$GITHUB_STEP_SUMMARY"

.github/workflows/orchestrator-eval.yml

@@ -0,0 +1,55 @@
+name: Contextual Orchestrator Free Evaluation
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+env:
+  PYTHONPATH: src
+  PIP_DISABLE_PIP_VERSION_CHECK: '1'
+
+jobs:
+  evaluate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: '3.12'
+          cache: pip
+          cache-dependency-path: requirements/ci.txt
+      - name: Install the immutable evaluation environment
+        run: python -m pip install --require-hashes -r requirements/ci.txt
+      - run: python -m pip check
+      - name: Require the orchestration gateway contract
+        env:
+          CONTEXTUAL_ORCHESTRATOR_TOKEN: ${{ secrets.CONTEXTUAL_ORCHESTRATOR_TOKEN }}
+          CONTEXTUAL_ORCHESTRATOR_BASE_URL: ${{ vars.CONTEXTUAL_ORCHESTRATOR_BASE_URL }}
+        run: |
+          if [ -z "$CONTEXTUAL_ORCHESTRATOR_TOKEN" ]; then
+            echo '::error::CONTEXTUAL_ORCHESTRATOR_TOKEN is required.'
+            exit 1
+          fi
+          if [ -z "$CONTEXTUAL_ORCHESTRATOR_BASE_URL" ]; then
+            echo '::error::CONTEXTUAL_ORCHESTRATOR_BASE_URL repository variable is required.'
+            exit 1
+          fi
+      - name: orchestrator/free smoke test
+        env:
+          INTERPRETATION_BACKEND: contextual_orchestrator
+          CONTEXTUAL_ORCHESTRATOR_TOKEN: ${{ secrets.CONTEXTUAL_ORCHESTRATOR_TOKEN }}
+          CONTEXTUAL_ORCHESTRATOR_BASE_URL: ${{ vars.CONTEXTUAL_ORCHESTRATOR_BASE_URL }}
+          CONTEXTUAL_ORCHESTRATOR_MODEL: orchestrator/free
+          CONTEXTUAL_ORCHESTRATOR_MODE: auto
+        run: pytest -m orchestrator_live -vv
+      - name: orchestrator/free judge fixture
+        env:
+          INTERPRETATION_BACKEND: contextual_orchestrator
+          CONTEXTUAL_ORCHESTRATOR_TOKEN: ${{ secrets.CONTEXTUAL_ORCHESTRATOR_TOKEN }}
+          CONTEXTUAL_ORCHESTRATOR_BASE_URL: ${{ vars.CONTEXTUAL_ORCHESTRATOR_BASE_URL }}
+          CONTEXTUAL_ORCHESTRATOR_MODEL: orchestrator/free
+          CONTEXTUAL_ORCHESTRATOR_MODE: auto
+        run: python scripts/orchestrator_eval.py

.github/workflows/release.yml

@@ -38,7 +38,7 @@ jobs:
       - run: python -m compileall -q src tests scripts
       - run: python scripts/check_docs.py
       - run: python scripts/check_prompts.py
-      - run: pytest -m 'not nim_live' -W error::ResourceWarning --cov=four_pillars --cov-report=term-missing
+      - run: pytest -m 'not orchestrator_live' -W error::ResourceWarning --cov=four_pillars --cov-report=term-missing
       - run: python -m build --no-isolation
       - name: Build the pinned runtime container
         run: docker build --tag four-pillars:release .

AGENTS.md

@@ -2,44 +2,31 @@
 
 ## Repository mission
 
-Four Pillars provides deterministic Korean Four Pillars calculation and
-schema-validated report generation as both a standalone product and a modular
-MSA component.
+Four Pillars provides deterministic Korean Four Pillars calculation and schema-validated report generation as both an independently deployable product and a modular MSA component.
 
 ## Required agent behavior
 
-- Read `CLAUDE.md`, `ARCHITECTURE.md`, `README.md`, `CHANGELOG.md`, the PRD,
-  TRD, calculation policy, modularity contract, security policy, operations
-  guides, and doctoring before changing behavior.
+- Read `CLAUDE.md`, `ARCHITECTURE.md`, `README.md`, `CHANGELOG.md`, the PRD, TRD, calculation policy, modularity contract, security policy, operations guides, ADRs, and doctoring before changing behavior.
 - Work test-first and preserve explicit RED-to-GREEN evidence.
 - Keep deterministic calculations independent from hosted model code.
-- Maintain 100% production statement/branch coverage and complete public
-  docstrings.
+- Treat Model Orchestration as an external bounded context. Product-owned LLM work must use the Contextual Orchestrator ACL and `orchestrator/free` unless a higher-level repository contract explicitly requires another virtual route.
+- Do not add provider-native credentials, direct provider SDK calls, or silent fallback to Four Pillars product composition.
+- Preserve `ReportInterpreter` as the application port; caller-owned MSA injection may replace that port without changing the repository-owned default.
+- Maintain 100% production statement/branch coverage and complete public docstrings.
 - Use APA 7 references for standards and research decisions.
-- Use only `NVIDIA_NIM_API_KEY` for direct NVIDIA NIM.
 - Never use `COPILOT_GITHUB_TOKEN` for model execution.
 - Do not change existing review-agent credentials or identity.
 - Use descriptive two-word-or-longer `snake_case` database object names.
-- Update CHANGELOG.md and affected architecture/operations/security documents.
-- Do not fabricate customer, revenue, production, attestation, transfer,
-  acquisition, or scientific-prediction evidence.
+- Audit DDD paths whenever responsibilities move. Move implementation, imports, tests, docs, UML, and architecture-fitness rules together; do not leave provider-specific names around a provider-neutral boundary without a tracked migration.
+- Update `CHANGELOG.md` and affected architecture/operations/security documents.
+- Do not fabricate customer, revenue, production, attestation, transfer, acquisition, or scientific-prediction evidence.
 
 ## Pull-request governance
 
-For every open pull request: inspect review submissions and inline threads,
-repair actionable findings, rerun exact-head Checks, and merge only the unchanged
-green head. Waiting for a review or Check is not permission to weaken the gate;
-continue other bounded investigation instead.
+For every open pull request: inspect review submissions and inline threads, repair actionable findings, rerun exact-head Checks, and merge only the unchanged green head. Waiting for a review or Check is not permission to weaken the gate; continue other bounded investigation instead.
 
-The hourly NVIDIA NIM OpenCode workflow is proposal-only. Its model runner has
-no GitHub write authority. Its publisher may open one pull request after fresh
-verification, but it has **no merge**, approval, release, deployment, or reviewer
-authority. Existing exact-head review remains mandatory.
+Repository-local automation is a model-free quality sentinel. Model-backed autonomous development is owned by the shared ContextualWisdomLab hourly maintainer and must not be duplicated by a second repository-specific provider-credentialed writer. The shared writer may open bounded pull requests but has no authority to waive review, security, exact-head validation, or release policy.
 
 ## Code-owner review gates — disabled (on hold)
 
-As of 2026-08-04, code-owner review requirements are disabled across the
-ContextualWisdomLab organization because there is one maintainer. Do not
-re-enable CODEOWNERS-based merge gates until multiple maintainers can satisfy
-them. This exception does not waive automated review, exact-head Checks, security
-scanning, or unresolved-thread requirements.
+As of 2026-08-04, code-owner review requirements are disabled across the ContextualWisdomLab organization because there is one maintainer. Do not re-enable CODEOWNERS-based merge gates until multiple maintainers can satisfy them. This exception does not waive automated review, exact-head Checks, security scanning, or unresolved-thread requirements.