feat(agent): add NVIDIA-backed OpenCode development loop

docs/operations/opencode-commercial-development-loop.md

@@ -0,0 +1,165 @@
+# OpenCode commercial development loop runbook
+
+## Purpose
+
+The `OpenCode Commercial Development` workflow may implement one explicitly eligible LifeOS buyer-gap issue each hour. It does not merge, deploy, release, modify repository settings, or bypass the existing review loop. The deterministic Commercial Readiness workflow remains the authoritative audit and exact-head merge path.
+
+## Enablement prerequisites
+
+1. Store the NVIDIA provider credential as the repository secret `NVIDIA_NIM_API_KEY`.
+2. Optionally configure repository variable `OPENCODE_NVIDIA_MODEL` with one NVIDIA NIM chat model identifier. When the value omits the provider prefix, the workflow prefixes `nvidia/`.
+3. Keep `product/opencode-commercial-development-policy.json` under normal pull-request review.
+4. Add an issue title to `eligible_issue_titles` only through a reviewed pull request after confirming the issue fits the initial non-destructive write boundary.
+5. Verify the exact OpenCode package and `pnpm-lock.yaml` pin after every OpenCode update.
+
+The workflow is disabled functionally when the NVIDIA secret is absent: it emits a credential-free `provider_credential_missing` receipt and performs no remote branch mutation.
+
+## Hourly sequence
+
+```mermaid
+sequenceDiagram
+    participant Schedule as GitHub schedule
+    participant Audit as Deterministic audit
+    participant Selector as Policy selector
+    participant OpenCode
+    participant Validator as Diff validator
+    participant GitHub as GitHub mutation step
+    participant Review as Existing review loop
+
+    Schedule->>Audit: Snapshot repository and open PRs
+    Audit->>Selector: Bounded issue and PR projections
+    alt open PR or no eligible issue
+      Selector-->>Schedule: no_eligible_issue receipt
+    else eligible issue
+      Selector->>OpenCode: Fixed prompt + untrusted issue JSON
+      OpenCode->>OpenCode: Edit temporary UUIDv4 branch worktree
+      OpenCode-->>Validator: Working tree only
+      Validator->>Validator: Path, object, byte, line, content, base checks
+      alt rejected or verification failed
+        Validator-->>Schedule: credential-free rejected/failed receipt
+      else accepted and exact base unchanged
+        Validator->>GitHub: One commit, one branch, one draft PR
+        GitHub->>Review: Normal CI and review gates
+      end
+    end
+```
+
+## Credentials and trust boundaries
+
+### NVIDIA credential
+
+`NVIDIA_NIM_API_KEY` is present in exactly one workflow step. That step starts a loopback HTTP bridge as the separate system user `opencode_bridge`; only that bridge receives the credential and forwards bounded requests to NVIDIA NIM. OpenCode runs as `opencode_model` with `NVIDIA_API_KEY=local-loopback-placeholder` and a provider base URL pointing to the bridge.
+
+During model execution, UID-based `iptables` rules reject other IPv4 and all IPv6 egress from `opencode_model`, permitting only the configured loopback bridge port. The workflow terminates the bridge before repository verification and removes the model and bridge processes, firewall rules, private homes, configuration, prompt, bridge code, and log in the `always()` cleanup step.
+
+The credential must never appear in:
+
+- Git configuration;
+- issue or pull-request bodies;
+- retained receipts or artifacts;
+- model prompts or source files;
+- the OpenCode/model process;
+- repository tests or scripts;
+- test logs;
+- the `@life-os/commercial-development-agent` process;
+- the GitHub mutation step;
+- the existing review-agent credential scheme.
+
+A suspected credential disclosure requires immediate secret rotation, cancellation of active runs, deletion of unreferenced automation branches, and review of workflow logs and draft pull requests. Do not retain or upload the raw OpenCode log while investigating. Treat `opencode_bridge`, rather than the OpenCode/model process, as the credential-bearing process during exposure analysis.
+
+### GitHub credential
+
+The checkout disables persisted credentials. OpenCode receives no `GITHUB_TOKEN` or `GH_TOKEN`. A later deterministic step receives `github.token` only after the diff, repository tests, and exact base SHA pass. That step may create one commit, push one same-repository UUIDv4 branch, and open one draft pull request. It cannot merge or release.
+
+## Policy changes
+
+Changes to allowed paths, issue titles, limits, model profiles, credentials, permissions, or mutation authority are security-sensitive architecture changes. They require:
+
+- updated design and plan;
+- realistic prompt-injection and policy tests;
+- AppGuardrail, Semgrep, Security Scan, Commercial Readiness, CodeRabbit, and human review;
+- exact-head success before merge.
+
+The agent is prohibited from modifying its own workflow or policy in the initial slice.
+
+## Receipts
+
+The retained artifact contains only `receipt.json` using schema:
+
+```text
+life-os.opencode-commercial-development-receipt.v1
+```
+
+Retention is seven days. The receipt records counts, stable classifications, exact base SHA, external GitHub references, UUIDv4 run/branch identity, OpenCode version, model label, and deterministic validation outcomes. It excludes source paths, source diff, issue body, prompt, model output, hidden reasoning, credentials, provider bodies, raw logs, and stack traces.
+
+## Failure handling
+
+| Reason code                   | Operator interpretation                                                       | Remote mutation                                                |
+| ----------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `no_eligible_issue`           | Open PRs remain or no allowlisted issue is available                          | None                                                           |
+| `provider_credential_missing` | NVIDIA secret is absent                                                       | None                                                           |
+| `provider_unavailable`        | Provider or OpenCode run failed                                               | None                                                           |
+| `opencode_unavailable`        | Exact OpenCode CLI cannot execute                                             | None                                                           |
+| `invalid_configuration`       | Policy, model, or workflow configuration is invalid                           | None                                                           |
+| `prompt_rejected`             | Prompt exceeds or violates the fixed contract                                 | None                                                           |
+| `diff_rejected`               | Working-tree output violates path, object, size, content, or no-change policy | None                                                           |
+| `base_changed`                | `main` advanced after the run began                                           | None                                                           |
+| `verification_failed`         | Repository tests or build failed                                              | None                                                           |
+| `draft_pull_request_failed`   | A validated commit could not become a draft PR                                | Possible unreferenced automation branch; reconcile immediately |
+| `completed`                   | One draft PR was created; normal review is still required                     | One branch and one draft PR                                    |
+
+The receipt contract reserves `opencode_unavailable`, `invalid_configuration`, and `prompt_rejected`; the current workflow receipt composer does not emit those codes.
+
+## Branch reconciliation
+
+Automation branches use:
+
+```text
+automation/opencode-commercial-<uuidv4>
+```
+
+An automation branch may be deleted when all conditions hold:
+
+- no open or closed pull request references it;
+- it is not the current head of an active workflow;
+- the deterministic receipt does not report a pending draft-PR operation;
+- an operator has verified that no unique reviewed work would be lost.
+
+Never force-push an automation branch. If `main` advances, abandon the branch and rerun from the new exact base rather than silently rebasing model output.
+
+## OpenCode update procedure
+
+1. Create a feature branch.
+2. Resolve the current official `opencode-ai` version once.
+3. Add it with an exact version and update `pnpm-lock.yaml`.
+4. Verify `opencode --version` and `opencode run --help`.
+5. Run package and workflow-contract tests.
+6. Inspect the lockfile and transitive dependency change.
+7. Remove the temporary write-capable bootstrap workflow.
+8. Obtain normal exact-head security and review evidence.
+
+Never use a floating version, mutable installer script, or `curl | sh` in the persistent workflow.
+
+## Central `.github` migration
+
+The organization-central `.github` repository may later host a reusable wrapper that performs common checkout, OpenCode installation, secret scoping, and receipt upload. LifeOS must continue to own:
+
+- issue-selection policy;
+- product prompt policy;
+- allowed/prohibited paths;
+- realistic fixtures;
+- receipt validation;
+- package tests;
+- branch and merge policy.
+
+A central migration must pin the reusable workflow by exact commit SHA and preserve the existing review-agent credentials unchanged.
+
+## Disablement
+
+To stop model-assisted development immediately without affecting deterministic audit or merge behavior:
+
+1. remove or rotate `NVIDIA_NIM_API_KEY`; or
+2. remove every title from the eligible backlog through a reviewed policy change; or
+3. disable the `OpenCode Commercial Development` workflow in GitHub Actions.
+
+Do not disable the independent Commercial Readiness workflow when responding to a model-provider incident.

docs/research/2026-08-07-opencode-commercial-development-loop-standards.md

@@ -0,0 +1,95 @@
+# OpenCode commercial development loop: standards and research basis
+
+**Reviewed:** 2026-08-07  
+**Scope:** Hourly NVIDIA-backed OpenCode development in `ContextualWisdomLab/life-os`
+
+## Evidence-status rule
+
+LifeOS distinguishes normative standards and final vendor documentation from conference papers, research releases, and preprints. Research results motivate hypotheses and ablations; they do not grant repository authority or replace deterministic tests, security review, and exact-head merge gates.
+
+## Normative security and governance basis
+
+### NIST AI RMF and Generative AI Profile
+
+The AI Risk Management Framework organizes governed AI risk work around Govern, Map, Measure, and Manage. The Generative AI Profile extends that framework with risks such as confabulation, information integrity, privacy, human-AI configuration, and value-chain integration. LifeOS maps these concepts into explicit policy, bounded authority, retained measurements, credential-free receipts, and independent deterministic review (National Institute of Standards and Technology, 2023, 2024).
+
+### GitHub Actions hardening
+
+GitHub recommends least-privilege `GITHUB_TOKEN` permissions, immutable third-party action references, protected branches, careful treatment of untrusted input, and separation of trusted and untrusted execution. The OpenCode step therefore receives no GitHub credential, runs against an exact main snapshot, and cannot push. A later deterministic step receives narrowly scoped repository authority only after the diff and base SHA have passed validation (GitHub, 2026a).
+
+A future organization-central wrapper should use a reusable workflow pinned by exact commit SHA. Repository-specific issue, path, prompt, receipt, and merge policy remains inside LifeOS so shared automation cannot silently broaden product authority (GitHub, 2026b).
+
+### OWASP risks for model-assisted software changes
+
+The OWASP Top 10 for LLM Applications identifies prompt injection, sensitive-information disclosure, excessive agency, improper output handling, supply-chain risk, and unbounded consumption as material concerns. LifeOS treats issue text and model output as untrusted, prevents the model from receiving GitHub credentials, validates source output before execution or push, pins OpenCode and GitHub actions, scopes the NVIDIA key to one process, and enforces file, byte, line, time, recursion, decomposition, and concurrency limits (OWASP Foundation, 2025).
+
+## OpenCode and NVIDIA provider boundary
+
+OpenCode exposes a non-interactive `run` command and provider/model configuration. LifeOS uses one exact reviewed `opencode-ai` package version and verifies both the installed version and command contract. Auto-update and sharing are disabled. The model receives a private configuration and a source archive without `.git`; Bash is denied by default except for reviewed `pnpm`, `node`, `python3`, `grep`, `rg`, `find`, `ls`, and `cat` command patterns, while web-fetch, web-search, and external-directory access are denied. The prompt is attached from a private file instead of carrying issue text in process arguments (Anomaly, 2026).
+
+NVIDIA NIM exposes hosted OpenAI-compatible inference authenticated with an API key. `NVIDIA_NIM_API_KEY` is mapped only to a loopback bridge running as `opencode_bridge`. OpenCode runs separately as `opencode_model` with a placeholder API-key value and an allowlisted minimal environment; UID-based `iptables` rules restrict its model-phase egress to the bridge. GitHub, review-agent, deployment, and unrelated repository credentials are absent. Provider availability is evidence, not a deterministic merge prerequisite (NVIDIA Corporation, 2026).
+
+## Test-time compute allocation
+
+### Strong single-agent baseline
+
+Xu et al. report that a multi-turn single agent can match homogeneous multi-agent workflows in several evaluated settings and can benefit from KV-cache reuse. Because broader orchestration adds coordination and attack surface, LifeOS requires a strong single-model route as the mandatory baseline and does not assume that more agents are better (Xu et al., 2026b).
+
+### Fugu
+
+Sakana AI reports a system that dynamically selects between direct answering and an expert team. This supports an explicit routing decision rather than always-on multi-agent execution. LifeOS treats the result as a final research release and measures whether repository-specific issue fixtures justify deeper orchestration (Sakana AI, 2026).
+
+### Conductor
+
+Conductor learns natural-language communication topologies and targeted instructions, including recursive self-selection for dynamic test-time scaling. The final ICLR 2026 conference paper motivates explicit topology, access-list, recursive-depth, and decomposition fields in the LifeOS ablation contract (Nielsen et al., 2026).
+
+### TRINITY
+
+TRINITY reports a lightweight evolved coordinator assigning Thinker, Worker, and Verifier roles across multiple turns. The final ICLR 2026 conference paper motivates role-specific reasoning effort and explicit verification rather than an undifferentiated agent pool (Xu et al., 2026a).
+
+## LifeOS design conclusions
+
+The initial workflow intentionally runs one high-effort OpenCode model with recursion depth one. It records a versioned contract for planner, worker, verifier, and synthesizer roles but does not enable hidden multi-agent delegation. A contextual-orchestrator profile may be introduced only when:
+
+1. the same realistic issue fixtures are used for route and orchestrated cells;
+2. issue selection, prompt policy, source authority, and diff validation remain deterministic;
+3. prompt-injection and sensitive-information tests do not regress;
+4. quality or heterogeneous capability improves materially;
+5. unsupported profile fields remain explicit rather than simulated;
+6. the exact contextual-orchestrator commit and dependency hashes are reviewed;
+7. retained artifacts exclude prompt, response, hidden reasoning, source diff, and credentials.
+
+Latency and token use are recorded for cost and capacity review but are not the primary optimization objective. Product correctness, security, auditability, and buyer-visible quality determine the routing decision.
+
+## Limitations
+
+- Vendor documentation describes interfaces, not independent security assurance.
+- The initial dry-run fixtures cannot establish general autonomous-development reliability.
+- The workflow applies UID-based `iptables` restrictions to `opencode_model`—allowing only the loopback bridge during model execution and denying IPv6—but does not provide a general-purpose operating-system sandbox; the model also receives a source archive without `.git` or GitHub credentials.
+- Provider-side retention and processing remain subject to the deployment operator's NVIDIA agreement and data-governance assessment.
+- The model cannot discover or authorize new backlog work in this slice; issue eligibility is an explicit reviewed policy.
+- A draft pull request is evidence for review, not proof of correctness or permission to merge.
+
+## References
+
+Anomaly. (2026). _OpenCode documentation_. https://opencode.ai/docs/
+
+GitHub. (2026a). _Security hardening for GitHub Actions_. https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions
+
+GitHub. (2026b). _Reusing workflows_. https://docs.github.com/en/actions/using-workflows/reusing-workflows
+
+National Institute of Standards and Technology. (2023). _Artificial intelligence risk management framework (AI RMF 1.0)_ (NIST AI 100-1). https://doi.org/10.6028/NIST.AI.100-1
+
+National Institute of Standards and Technology. (2024). _Artificial intelligence risk management framework: Generative artificial intelligence profile_ (NIST AI 600-1). https://doi.org/10.6028/NIST.AI.600-1
+
+Nielsen, S., Cetin, E., Schwendeman, P., Sun, Q., Xu, J., & Tang, Y. (2026). _Learning to orchestrate agents in natural language with the Conductor_ [Conference paper]. International Conference on Learning Representations. https://openreview.net/forum?id=U23A2BUKYt
+
+NVIDIA Corporation. (2026). _API reference—NVIDIA NIM for large language models_. https://docs.nvidia.com/nim/large-language-models/latest/api-reference.html
+
+OWASP Foundation. (2025). _OWASP Top 10 for large language model applications 2025_. https://genai.owasp.org/llm-top-10/
+
+Sakana AI. (2026, June 22). _Sakana Fugu: One model to command them all_ [Final research release]. https://sakana.ai/fugu-release/
+
+Xu, J., Sun, Q., Schwendeman, P., Nielsen, S., Cetin, E., & Tang, Y. (2026a). _TRINITY: An evolved LLM coordinator_ [Conference paper]. International Conference on Learning Representations. https://doi.org/10.48550/arXiv.2512.04695
+
+Xu, J., Koesdwiady, A., Bei, S., Han, Y., Huang, B., Wang, D., Chen, Y., Wang, Z., Wang, P., Li, P., & Ding, Y. (2026b). _Rethinking the value of multi-agent workflow: A strong single agent baseline_ [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2601.12307