feat(ai): add NVIDIA NIM live proposal conformance

.github/workflows/ai-proposal-live-conformance.yml

@@ -0,0 +1,293 @@
+name: AI Proposal Live Conformance
+
+on:
+  schedule:
+    - cron: '47 * * * *'
+  workflow_dispatch:
+    inputs:
+      models:
+        description: Optional comma-separated NVIDIA NIM chat model identifiers
+        required: false
+        type: string
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ai-proposal-live-conformance-${{ github.repository }}
+  cancel-in-progress: false
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+  CONTEXTUAL_ORCHESTRATOR_COMMIT: 6841b71935e0b7cb98fb52bcb4709cc5100c8d87
+  PROVIDER_BASE_URL: https://integrate.api.nvidia.com/v1
+  PROVIDER_ALLOWED_HOST: integrate.api.nvidia.com
+  LIVE_ENABLED: ${{ vars.AI_NIM_LIVE_CONFORMANCE_ENABLED }}
+  MODEL_INPUT: ${{ github.event_name == 'workflow_dispatch' && inputs.models || vars.NVIDIA_NIM_CHAT_MODELS }}
+
+jobs:
+  evaluate:
+    runs-on: ubuntu-24.04
+    timeout-minutes: 120
+    services:
+      postgres:
+        image: postgres:16-alpine@sha256:57c72fd2a128e416c7fcc499958864df5301e940bca0a56f58fddf30ffc07777
+        env:
+          POSTGRES_DB: life_os_live_conformance
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres -d life_os_live_conformance"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 10
+
+    steps:
+      - name: Checkout LifeOS
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 22
+
+      - name: Install reproducible LifeOS dependencies
+        run: |
+          corepack enable
+          pnpm install --frozen-lockfile
+
+      - name: Verify deterministic live-evidence contracts
+        run: |
+          pnpm --filter @life-os/ai-service exec vitest run \
+            src/contextual-orchestrator-proposal-contract.test.ts \
+            src/contextual-orchestrator-live-model.test.ts \
+            src/proposal-quality-live-conformance.test.ts \
+            src/proposal-quality-live-command.test.ts \
+            src/proposal-quality-live-cli.test.ts \
+            src/proposal-quality-live-workflow.test.ts \
+            --no-file-parallelism
+          pnpm --filter @life-os/ai-service build
+
+      - name: Validate model inventory and create agent configuration
+        id: models
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          python3 - <<'PY'
+          import json
+          import os
+          import re
+          from pathlib import Path
+
+          enabled = os.environ.get('LIVE_ENABLED') == 'true'
+          raw = os.environ.get('MODEL_INPUT', '')
+          models = []
+          if enabled and raw.strip():
+              models = [item.strip() for item in raw.split(',')]
+              pattern = re.compile(r'^[A-Za-z0-9][A-Za-z0-9._:/-]{0,199}$')
+              if (
+                  len(models) > 4
+                  or len(set(models)) != len(models)
+                  or any(not pattern.fullmatch(item) for item in models)
+              ):
+                  raise SystemExit('Configured NVIDIA model inventory is invalid')
+
+          agent_ids = [
+              'nvidia_route_alpha',
+              'nvidia_route_bravo',
+              'nvidia_route_charlie',
+              'nvidia_route_delta',
+          ]
+          agents = [
+              {
+                  'id': agent_ids[index],
+                  'model': model,
+                  'base_url': os.environ['PROVIDER_BASE_URL'],
+                  'credential_key': 'NVIDIA_NIM_API_KEY',
+                  'tags': [
+                      'analysis',
+                      'planning',
+                      'reasoning',
+                      'review',
+                      'writing',
+                  ],
+                  'priority': index + 1,
+              }
+              for index, model in enumerate(models)
+          ]
+          config_path = Path(os.environ['RUNNER_TEMP']) / 'nvidia-nim-agents.json'
+          config_path.write_text(
+              json.dumps({'agents': agents}, separators=(',', ':')) + '\n',
+              encoding='utf-8',
+          )
+
+          with open(os.environ['GITHUB_OUTPUT'], 'a', encoding='utf-8') as output:
+              output.write(f"configured={'true' if models else 'false'}\n")
+              output.write(f"model_count={len(models)}\n")
+          with open(os.environ['GITHUB_ENV'], 'a', encoding='utf-8') as environment:
+              environment.write(f"NVIDIA_NIM_CHAT_MODELS={','.join(models)}\n")
+              environment.write(f"NVIDIA_NIM_AGENTS_PATH={config_path}\n")
+          PY
+
+      - name: Set up Python
+        if: env.LIVE_ENABLED == 'true' && steps.models.outputs.configured == 'true'
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v6
+        with:
+          python-version: '3.13'
+
+      - name: Checkout pinned contextual-orchestrator
+        if: env.LIVE_ENABLED == 'true' && steps.models.outputs.configured == 'true'
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: ContextualWisdomLab/contextual-orchestrator
+          ref: ${{ env.CONTEXTUAL_ORCHESTRATOR_COMMIT }}
+          path: _contextual_orchestrator
+          persist-credentials: false
+
+      - name: Verify contextual-orchestrator identity
+        if: env.LIVE_ENABLED == 'true' && steps.models.outputs.configured == 'true'
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          actual_commit="$(git -C _contextual_orchestrator rev-parse HEAD)"
+          if [ "$actual_commit" != "$CONTEXTUAL_ORCHESTRATOR_COMMIT" ]; then
+            echo '::error::Pinned contextual-orchestrator checkout does not match the reviewed commit.'
+            exit 1
+          fi
+
+      - name: Install pinned contextual-orchestrator dependencies
+        if: env.LIVE_ENABLED == 'true' && steps.models.outputs.configured == 'true'
+        run: |
+          python -m pip install \
+            --disable-pip-version-check \
+            --no-input \
+            --require-hashes \
+            -r _contextual_orchestrator/requirements.lock
+
+      - name: Create ephemeral orchestrator runtime configuration
+        if: env.LIVE_ENABLED == 'true' && steps.models.outputs.configured == 'true'
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          python3 - <<'PY'
+          import os
+          import secrets
+
+          values = {
+              'CONTEXTUAL_ORCHESTRATOR_KV_BACKEND': 'postgres',
+              'CONTEXTUAL_ORCHESTRATOR_KV_DSN': (
+                  'postgresql+psycopg://postgres:postgres@127.0.0.1:5432/'
+                  'life_os_live_conformance'
+              ),
+              'CONTEXTUAL_ORCHESTRATOR_KV_PASSPHRASE': secrets.token_urlsafe(48),
+              'CONTEXTUAL_ORCHESTRATOR_INFERENCE_TOKEN': secrets.token_urlsafe(48),
+              'CONTEXTUAL_ORCHESTRATOR_ADMIN_TOKEN': secrets.token_urlsafe(48),
+              'CONTEXTUAL_ORCHESTRATOR_ALLOWED_PROVIDER_HOSTS': (
+                  os.environ['PROVIDER_ALLOWED_HOST']
+              ),
+              'CONTEXTUAL_ORCHESTRATOR_LIVE_URL': 'http://127.0.0.1:8765',
+              'AI_LIVE_MODEL_REQUEST_TIMEOUT_MS': '120000',
+          }
+          with open(os.environ['GITHUB_ENV'], 'a', encoding='utf-8') as environment:
+              for name, value in values.items():
+                  environment.write(f'{name}={value}\n')
+          PY
+
+      - name: Seed NVIDIA credential through the encrypted KV bootstrap
+        id: seed_nvidia
+        if: env.LIVE_ENABLED == 'true' && steps.models.outputs.configured == 'true'
+        working-directory: _contextual_orchestrator
+        env:
+          NVIDIA_NIM_API_KEY: ${{ secrets.NVIDIA_NIM_API_KEY }}
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          if [ -z "$NVIDIA_NIM_API_KEY" ]; then
+            echo 'available=false' >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          printf '%s' "$NVIDIA_NIM_API_KEY" | \
+            python -m contextual_orchestrator register-credential \
+              --name NVIDIA_NIM_API_KEY \
+              --value-stdin
+          echo 'available=true' >> "$GITHUB_OUTPUT"
+
+      - name: Start the loopback contextual-orchestrator
+        if: steps.seed_nvidia.outputs.available == 'true'
+        working-directory: _contextual_orchestrator
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          nohup python -m contextual_orchestrator \
+            --serve \
+            --agents "$NVIDIA_NIM_AGENTS_PATH" \
+            --host 127.0.0.1 \
+            --port 8765 \
+            --budget-max-output-tokens 200000 \
+            > "${RUNNER_TEMP}/contextual-orchestrator.log" 2>&1 &
+          echo "$!" > "${RUNNER_TEMP}/contextual-orchestrator.pid"
+
+          for _ in $(seq 1 60); do
+            if curl \
+              --silent \
+              --show-error \
+              --fail \
+              --max-time 2 \
+              http://127.0.0.1:8765/healthz \
+              > /dev/null; then
+              exit 0
+            fi
+            sleep 1
+          done
+          echo '::error::Contextual-orchestrator did not become healthy.'
+          exit 1
+
+      - name: Generate credential-free live conformance evidence
+        env:
+          AI_NIM_LIVE_CONFORMANCE_ENABLED: ${{ env.LIVE_ENABLED }}
+          NVIDIA_NIM_API_KEY_AVAILABLE: ${{ steps.seed_nvidia.outputs.available }}
+          LIFE_OS_COMMIT_SHA: ${{ github.sha }}
+          CONTEXTUAL_ORCHESTRATOR_COMMIT_SHA: ${{ env.CONTEXTUAL_ORCHESTRATOR_COMMIT }}
+          CONTEXTUAL_ORCHESTRATOR_LIVE_TOKEN: ${{ env.CONTEXTUAL_ORCHESTRATOR_INFERENCE_TOKEN }}
+          PROPOSAL_LIVE_REPORT_PATH: ${{ runner.temp }}/ai-proposal-live-conformance.json
+        run: pnpm --filter @life-os/ai-service quality:live
+
+      - name: Validate retained live report
+        env:
+          PROPOSAL_LIVE_REPORT_PATH: ${{ runner.temp }}/ai-proposal-live-conformance.json
+        run: |
+          node <<'NODE'
+          const { readFileSync } = require('node:fs');
+          const {
+            validateProposalLiveConformanceReport,
+          } = require('./apps/ai-service/dist/proposal-quality-live-conformance.js');
+          validateProposalLiveConformanceReport(
+            JSON.parse(readFileSync(process.env.PROPOSAL_LIVE_REPORT_PATH, 'utf8')),
+          );
+          NODE
+
+      - name: Upload credential-free live conformance report
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v4
+        with:
+          name: ai-proposal-live-conformance-${{ github.run_id }}
+          path: ${{ runner.temp }}/ai-proposal-live-conformance.json
+          if-no-files-found: error
+          retention-days: 14
+          compression-level: 9
+
+      - name: Stop the ephemeral orchestrator
+        if: always()
+        shell: bash
+        run: |
+          set -Eeuo pipefail
+          pid_file="${RUNNER_TEMP}/contextual-orchestrator.pid"
+          if [ -f "$pid_file" ]; then
+            pid="$(cat "$pid_file")"
+            kill "$pid" 2>/dev/null || true
+            wait "$pid" 2>/dev/null || true
+          fi
+          rm -f "${RUNNER_TEMP}/contextual-orchestrator.log"

AGENTS.md

@@ -1,9 +1,87 @@
-# AGENTS.md
+# LifeOS agent contract
 
-## Code-owner review gates — disabled (on hold)
+This file is the canonical repository-wide operating contract for coding agents. `ARCHITECTURE.md` defines durable system boundaries, while feature specifications, implementation plans, and runbooks provide scoped detail.
 
-As of 2026-08-04, code-owner review requirements (`require_code_owner_reviews` in branch
-protection, `require_code_owner_review` in rulesets) are disabled across the ContextualWisdomLab
-org: there is a single maintainer (solo developer), so a code-owner approval gate can never be
-satisfied. This is ON HOLD until the org has multiple maintainers — do NOT re-enable these
-settings or add CODEOWNERS-based merge gates before then.
+## Pull-request loop
+
+For every open pull request:
+
+1. inspect the exact current head;
+2. read every human, CodeRabbit, AppGuardrail, code-scanning, and security finding;
+3. diagnose the root cause of failed or required checks;
+4. make a complete correction with tests and documentation;
+5. rerun or wait for checks on the corrected exact head while continuing independent work;
+6. resolve only review threads whose underlying issue is addressed;
+7. merge only when all required evidence passes and no actionable review finding remains;
+8. continue with the next buyer-visible development slice.
+
+Never use an administrative bypass or claim completion from stale checks. Routine progress narration is not repository evidence.
+
+## Code-owner review gates — disabled on hold
+
+As of 2026-08-04, code-owner review requirements (`require_code_owner_reviews` in branch protection and `require_code_owner_review` in rulesets) are disabled across the ContextualWisdomLab organization because there is one maintainer and that gate cannot be satisfied. Do not re-enable CODEOWNERS-based merge gates until the organization has multiple maintainers. Independent automated review, security checks, and exact-head verification remain required where configured.
+
+## Modular MSA rules
+
+- Every bounded service must run independently and remain composable in the LifeOS monorepo deployment.
+- Services communicate through versioned HTTP, event, saga, plugin, or MCP contracts.
+- A service must not read or mutate another service's database tables.
+- Each service owns migrations, runtime configuration, observability, tests, and shutdown behavior.
+- Internal identifiers are opaque UUIDv4 strings. Numeric provider identifiers never become internal primary keys.
+- Database objects use names containing at least two words, preferably `snake_case`, unless an external protocol mandates another form.
+- Rename stale internal product or caller names when they no longer match the public software identity.
+
+## Quality and documentation
+
+- Production declarations require explanatory docstrings sufficient for a new contributor to understand the contract without reconstructing the implementation.
+- Packages that enforce coverage gates must retain 100% statement, branch, function, and line coverage.
+- Tests prove realistic domain accuracy and failure behavior, not only mocked call counts.
+- Standards, papers, and research claims are recorded in `docs/research/` or the approved feature specification with APA 7 references and clear final/draft/preprint status.
+- Update `ARCHITECTURE.md`, `CLAUDE.md`, `CHANGELOG.md`, capability evidence, design specifications, implementation plans, and operating runbooks when their boundary changes.
+- A release version and tag are created only when the repository proves release readiness; otherwise changes remain under `CHANGELOG.md` → `Unreleased`.
+
+## AI and model-provider rules
+
+- AI proposals are inert, explainable suggestions and cannot silently mutate user-owned data.
+- `COPILOT_GITHUB_TOKEN` is prohibited.
+- Model-assisted tests and scheduled agents use `NVIDIA_NIM_API_KEY` through the approved OpenCode or contextual-orchestrator boundary.
+- Do not alter or reuse the key scheme of existing review agents.
+- Provider credentials, browser cookies, bearer material, raw prompts, raw responses, hidden reasoning, and stack traces do not enter retained artifacts.
+- Live-provider availability is not a deterministic pull-request merge requirement; missing or unavailable providers produce explicit sanitized evidence.
+
+### Test-time compute allocation
+
+A strong single-model route is the mandatory baseline. Deeper orchestration is justified only by measured quality or heterogeneous capability coverage. Explicitly model and ablate:
+
+- reasoning effort;
+- workflow stages;
+- planner, worker, verifier, and synthesizer roles;
+- task decomposition;
+- recursive depth;
+- access lists and communication topology;
+- homogeneous versus heterogeneous model pools.
+
+Fugu release evidence (final product release and technical report; Fugu Team, 2026), Conductor (peer-reviewed ICLR 2026 conference paper; Nielsen et al., 2026), TRINITY (peer-reviewed ICLR 2026 conference paper; Xu et al., 2026), and strong-single-agent evidence (arXiv preprint and ICLR 2026 submission; Xu et al., 2026) guide the design, but repository tests and retained measurements determine the deployed policy. Latency is recorded but is not the sole or primary decision criterion. Complete APA 7 references and publication-status links are maintained in [`docs/superpowers/specs/2026-08-06-ai-nim-live-conformance-design.md`](docs/superpowers/specs/2026-08-06-ai-nim-live-conformance-design.md#references).
+
+## Mathematical and psychometric modules
+
+Any future mathematical or psychometric computation layer must:
+
+- implement numerical kernels in Rust;
+- support deterministic CPU multithreading with low context switching and a GPU execution boundary;
+- test true-parameter recovery, bias, interval coverage, convergence, and RMSE on realistic simulations;
+- model multilevel and multiple-membership structure to avoid atomistic fallacy;
+- model temporal change, repeated measurement, drift, or state evolution where the estimand changes over time;
+- document assumptions, estimands, numerical precision, fallback behavior, and reproducibility controls with APA 7 references.
+
+## Security and privacy
+
+- Treat every external response, stored JSON value, environment value, model output, and connector result as untrusted until bounded and validated.
+- Keep SQL structure static and parameterize dynamic values.
+- Fail closed on malformed ownership, identifiers, signatures, digests, timestamps, pagination, or provider configuration.
+- Public problems, metrics, logs, and artifacts are credential-free and bounded.
+- Temporary write-capable repair workflows must be removed before merge; persistent workflows receive the least permissions needed.
+
+## Waiting and escalation
+
+Waiting for checks, reviews, or a long-running OpenCode agent is not a blocker. Continue non-conflicting analysis, documentation, testing, or the next planned slice. Escalate only when a product decision or permission cannot be derived from repository policy, evidence, standards, or available tools.