docs: establish canonical product architecture and evidence model

AGENTS.md

@@ -38,6 +38,26 @@ push or open a PR.
   code-scanning tools can't converge on one PR ref. Gating happens via the
   Security **job results**; do not add tools to the `code_scanning` rule.
 
+### Repository-writer lease and dependency authority
+
+- Enforce **one writer per repository branch**. Before every repository write,
+  refetch the **exact PR head and target blob SHA**. If either changed, inspect
+  the intervening work and reconcile once before editing; never overwrite an
+  independently moved branch from stale state.
+- Repositories outside `ContextualWisdomLab/contextual-orchestrator`, including
+  the central `ContextualWisdomLab/.github` control plane and repositories with
+  their own dedicated maintenance loops, are **read-only dependencies** unless
+  the task is explicitly assigned to that repository. Do not edit their
+  branches, dispatch **write-capable agents**, resolve their review threads, or
+  merge their PRs from this repository's loop.
+- Live GitHub state is authoritative. A predecessor-head, stale-head,
+  cancelled, absent, failed, queued, pending, skipped-required, or
+  synthetic-merge result is not current-head evidence and must never be reused
+  to approve or merge a later tree.
+- Do not create one-shot, self-modifying, encoded-patch, branch-local repair, or
+  temporary write-capable GitHub Actions workflows. Prefer direct reviewed
+  changes tied to the exact current head.
+
 ### Code exploration
 
 - This repo has **no `.codegraph/` index**, so use normal search
@@ -56,23 +76,26 @@ push or open a PR.
 - The reference implementation is xtrmLLMBatchPython's pgcrypto-encrypted
   Postgres credential registry (`get_credential(name)`); reuse that pattern (a
   DB-backed KV is fine) unless a dedicated KV is adopted.
-- **Known deviation to migrate:** this repo currently resolves provider API
-  keys from env — `ModelClient` reads `os.environ.get(agent.api_key_env)` in
-  `contextual_orchestrator/orchestrator.py` (and `CONTEXTUAL_ORCHESTRATOR_*`
-  tokens in `__main__.py`). Move these to KV-backed reads; keep env only as the
-  bootstrap path that seeds the KV.
+- Protected main resolves provider keys through `get_credential`; the legacy
+  `api_key_env` field is only a credential-name compatibility alias. Do not
+  reintroduce request-time environment fallback. Process/bind configuration
+  may still use explicit `CONTEXTUAL_ORCHESTRATOR_*` bootstrap inputs.
 
 ### This repo: the org LLM gateway
 
 - `contextual-orchestrator` is the org's **LLM-communication hub** — the
   OpenAI-compatible front door consumed by **gyeot** and **scopeweave**.
 - **Direction:** grow it toward a **LiteLLM-class multi-provider gateway**. The
   org is open to a **Rust/Python hybrid** to cut overhead.
-- Its `ModelClient` currently reads `os.environ.get(agent.api_key_env)` — this
-  is the KV-principle deviation above. Resolve the API key (including the org
-  `OPENAI_API_KEY`) from the **KV / credential registry**, not env.
-- The **OpenCode review pipeline is separate** and stays on **GitHub Models** —
-  do not change it.
+- Its `ModelClient` resolves the credential name through the **KV / credential
+  registry**, including `OPENAI_API_KEY`; do not add ambient environment
+  fallback at request time.
+- The **OpenCode review pipeline is separate and centrally governed** by
+  `ContextualWisdomLab/.github`. Do not hard-code or replace its provider pool,
+  reviewer identities, or credential chain from this repository. For live model
+  tests and autonomous development work owned by this repository, use
+  `NVIDIA_NIM_API_KEY`; never repurpose `COPILOT_GITHUB_TOKEN` as a model or
+  development-agent credential.
 
 ### This repo's role in the ecosystem
 
@@ -83,15 +106,15 @@ push or open a PR.
   email/PIM that DOM-decomposes emails/files into a persisted knowledge graph).
   Each component below is a **standalone program that must ALSO work as a git
   submodule**, grown separately and together:
-  - **waf-ids-ai-soc** — WAF / IDS / AI SOC / LB / APIM.
+  - **wardnet** — WAF / IDS / AI SOC / LB / APIM.
   - **clearfolio** — document viewer.
   - **pg-erd-cloud** — ERD tool.
   - **contextual-orchestrator** — this repo: LLM cost/perf/upstream-LB gateway
     (beyond LiteLLM).
   - **codec-carver** — STT / omni-modal speech-video codec.
   - **fast-mlsirm** — LLM-as-a-Judge calibration + evaluation-item quality
     (uses aFIPC FIPC + kaefa item-fit).
-  - **feelanet-adfs** — passwordless SSO (OIDC/SCIM/ADFS/LDAP/FIDO2/OAuth2.1,
+  - **keyverse** — passwordless SSO (OIDC/SCIM/ADFS/LDAP/FIDO2/OAuth2.1,
     eliminate passwords).
   - **newsdom-api** — PDF→DOM sidecar.
   - **semantic-data-portal** — upper ontology / catalog / governance plane with
@@ -109,3 +132,22 @@ push or open a PR.
   scheduling (e.g. LLM-cascade / model-routing and queueing/load-balancing
   papers).
 <!-- END cwl-agent-guidance -->
+
+## Canonical product documentation
+
+Start at [`docs/README.md`](docs/README.md). Root `ARCHITECTURE.md`, PRD, TRD,
+ERD, UML, ADRs, threat model, test strategy, operability, incident response,
+traceability, and references are one status-qualified graph. Behavior changes
+must update the affected authority and documentation contract test.
+
+## Execution continuity
+
+- Treat prompt edits, audits, status summaries, and documentation assessments
+  as intermediate work when the request also authorizes repository changes.
+- Continue the safe chain: verify live target state, repair the smallest
+  coherent authority set, run focused and full evidence, publish a reviewable
+  branch/PR, inspect its exact-head state, then take the next non-conflicting
+  authorized task while a control-plane check is pending.
+- Stop only for a real authority choice, destructive ambiguity, permission
+  boundary, or external dependency that blocks every safe continuation. Never
+  turn queued, absent, stale, synthetic, or status-only evidence into success.