docs: reconcile canonical runtime authority with protected develop

AGENTS.md

@@ -1,78 +1,77 @@
 # AGENTS.md
 
-## Project overview
+## Product boundary
 
-- ScopeWeave Planner is a pure HTML/CSS/JavaScript WBS planning web app.
-- Runtime dependencies are forbidden; development-only tooling is allowed.
+ScopeWeave is one product with two independently usable runtime profiles:
 
-## Defaults
+- **Standalone** — static `index.html`/CSS/JavaScript, local-first persistence, no server or runtime package requirement, deployable to GitHub Pages or any static host.
+- **Cloud/SaaS** — the same client with `cloud-sync.js` plus the Node server under `server/`, multi-tenant persistence, authentication, collaboration, analytics and integrations.
 
-- Keep the runtime static-host compatible for GitHub Pages.
-- Preserve the single global `tasks` array as the source of truth.
-- Use a single `renderAll()` integration path for user-visible rerenders.
-- Prefer browser-native APIs only.
+Protected `develop` is the authority for what is shipped. PR bodies, issue text, plans and chat are evidence only. Never describe behavior that exists only on an open PR as shipped.
+
+## Architecture invariants
+
+- Preserve standalone static-host compatibility even when changing cloud behavior.
+- Preserve the client `tasks` array as the canonical in-browser work-item state and `renderAll()` as the user-visible rerender integration path unless an accepted ADR supersedes that contract.
+- `app.js` must remain eval-safe: no top-level `import` or `export`. Optional browser modules bridge through explicit `window.ScopeWeave*` interfaces.
+- Cloud code may use the runtime dependencies already declared in `package.json`; adding or replacing production dependencies requires a bounded justification, supply-chain review and compatible standalone behavior.
+- `server/db.mjs` currently owns SQLite persistence. PostgreSQL is a migration target, not shipped truth until an integrated adapter and migration evidence exist.
+- Cross-service integrations such as Clearfolio and contextual-orchestrator are replaceable adapters. ScopeWeave owns its validation, authorization and failure boundary; it does not duplicate another CWL service's internal authority.
+- Do not silently promote development mocks or deterministic fallbacks to production readiness. When a production boundary is incomplete, document it as a current gap or active PR.
+
+## Database contract
+
+- New owned database objects use descriptive two-or-more-word `snake_case` names.
+- Keep relational designs in third normal form unless a documented, measured exception is accepted.
+- Schema changes require migration, rollback/recovery and populated-database tests; request-time DDL is not a migration strategy.
+- Preserve tenant isolation and optimistic-concurrency semantics across persistence adapters.
 
 ## Verification
 
-- Serve locally with `python3 -m http.server 4173`.
-- Run end-to-end verification with `npm run test:e2e`.
-- Run workflow ownership checks with `python3 -m pytest tests/config`.
-
-## CI / security workflow notes
-
-- OpenCode Review, Strix Security Scan, and PR Review Merge Scheduler are
-  organization-level required workflows from `ContextualWisdomLab/.github`.
-  Do not copy them into this repository.
-- ScopeWeave's repository-local `opencode.jsonc` is development configuration,
-  not a replacement for the organization review workflow. It uses NVIDIA NIM
-  only and reads the process-local `NVIDIA_API_KEY` binding. Organization CI
-  owns secret injection and maps the organization `NVIDIA_NIM_API_KEY` secret
-  into that process binding; do not add a repository-local OpenCode workflow or
-  restore GitHub Models/COPILOT credentials to this configuration.
-- Keep companion SCA workflows development-only; do not add runtime
-  dependencies.
-- If GitHub CLI output emits Projects(classic) deprecation warnings,
-  prefer `gh api` or explicit `--json` field selection over default
-  human-formatted `gh issue view` / `gh pr view` output.
-
-<!-- BEGIN cwl-agent-guidance -->
-## Agent guidance (CWL governance)
-
-Cross-agent conventions for any agent working in this repo (Claude, Codex,
-Cursor, opencode, ...). Distilled from ContextualWisdomLab governance.
-
-### Security & review gate
-
-- Every PR runs a central **Security Scan** required gate: `osv-scan` +
-  `dependency-review` (diff-scoped) and `trivy-fs` (repo-wide, CRITICAL/HIGH,
-  fixable only). It runs against every PR base, **including stacked PRs**.
-- A failing `trivy-fs` is a **REAL finding, not a flake.** Read the job log and
-  the uploaded SARIF/code-scanning results to identify each rule id, severity,
-  file, and line before changing code. SARIF-mode Trivy logs may only show the
-  scanner configuration and exit code, so use code scanning or the SARIF
-  artifact when the log does not enumerate findings. Then **remediate**: bump
-  the offending dependency, fix the misconfig in
-  `Dockerfile` or `infra/k8s/*.yaml`, or add a narrow, documented
-  `.trivyignore` (`.trivyignore.yaml`) entry only for a genuine false positive.
-  Never weaken, skip, or disable the gate.
-- A local scan with a stale DB misses findings. Run
-  `trivy --download-db-only` first, then scan the **merge ref**, not just the PR
-  head, e.g. `trivy fs --severity CRITICAL,HIGH --ignore-unfixed .`.
-- Worked example from the historical PR queue: the misconfig scan flagged
-  **KSV-0020 / KSV-0021** (UID/GID `<= 10000` — `infra/k8s/deployment.yaml`
-  uses `runAsUser/runAsGroup: 101`), **KSV-0110** (no explicit `namespace`, so
-  the manifests land in `default`), and **DS-0026** (no `HEALTHCHECK` in the
-  `Dockerfile`). Fix these in-tree; do not ignore them.
-- The org `code_scanning` ruleset is intentionally **CodeQL-only** (multiple
-  code-scanning tools cannot converge on one PR ref). Gating is by the Security
-  Scan **job result**, not the `code_scanning` rule — do not add tools to that
-  rule.
-
-### Code exploration
-
-- Initialize and sync CodeGraph before review or edits, then keep it current
-  after rebases and source changes. Use CodeGraph (`codegraph status`,
-  `codegraph sync`, `codegraph explore "<query>"`, or the code-review-graph MCP
-  tools) as the first structural map, with ripgrep/find as a fast companion for
-  exact text search.
-<!-- END cwl-agent-guidance -->
+Run the applicable repository-native paths before requesting merge:
+
+```bash
+npm run test:unit
+npm run test:api
+npm run test:coverage
+npm run test:e2e
+npm run test:e2e:cloud
+npm run fuzz
+python3 -m pytest tests/config
+```
+
+`server-tests.yml`, Fuzz, Dependency Review, OSV Scanner and repository security workflows are source evidence only for the exact commit they checked out. Organization-required OpenCode/Noema/Strix/Security/SAST/merge-policy evidence is inherited from `ContextualWisdomLab/.github` and must not be copied into this repository.
+
+## Review and merge discipline
+
+- Refetch the exact PR head and the current protected `develop` tip before every source, docs, ref or PR-state mutation.
+- Verify review findings against the current source. Fix valid findings test-first; resolve only addressed threads.
+- A queued, skipped, cancelled, failed, neutral-required, missing, predecessor-head or stale-base check is not passing evidence.
+- COMMENTED reviews, status checks and model text are not a qualifying formal approval.
+- Never self-approve, manufacture approval, weaken rulesets, force-push, destructively rebase or move a branch to make stale evidence appear current.
+- If a check or reviewer is waiting, rotate to another non-conflicting lane rather than churning a clean head.
+- Compare moved/old branches against protected `develop` for unintended deletion or weakening of already-shipped authentication, session revocation, attachment/Clearfolio boundaries, coverage contracts, persistence and operability behavior.
+
+## Security and privacy
+
+- Treat every external provider response, imported document, persisted identifier and review body as untrusted data.
+- Bound network time, redirects, response bytes, parsing and concurrency at the owning adapter boundary.
+- Keep secrets out of browser responses, logs, metrics labels and model context.
+- PII required for legitimate work is protected with purpose-bound authorization, least privilege, tenant/context isolation, encryption, retention and auditable access rather than indiscriminate masking.
+- A failing security gate is a real blocker until evidence proves a false positive; never disable or weaken a gate to merge.
+- Design for CSAP/SOC 2 evidence readiness without claiming certification.
+
+## LLM and automation
+
+- Model-backed development/tests use `NVIDIA_NIM_API_KEY`, preferably through contextual-orchestrator/OpenCode. Keep development-model execution on the NVIDIA NIM credential path and preserve independent reviewer credentials.
+- ScopeWeave's repository-local `opencode.jsonc` is development configuration, not a replacement for the organization review workflow. It uses NVIDIA NIM only and reads the process-local `NVIDIA_API_KEY` binding; organization CI owns secret injection and maps the organization `NVIDIA_NIM_API_KEY` secret into that process binding. Do not add a repository-local OpenCode workflow or restore GitHub Models/COPILOT credentials to this configuration.
+- Model output is untrusted proposal data. Deterministic authorization, security, merge and release gates remain independent of model judgment.
+- Initialize/sync CodeGraph or code-review-graph when available before structural edits; use exact text search as a companion, not a substitute for source verification.
+
+## Documentation authority
+
+Keep `README.md`, `ARCHITECTURE.md`, `CLAUDE.md`, product/technical requirements, ADRs, security/threat model, test strategy, operability/recovery, traceability and `CHANGELOG.md` aligned with protected code. Clearly label active-PR, planned, research-only and superseded behavior. Documentation is product memory, not proof that implementation exists.
+
+## Release discipline
+
+Version/tag/publish only from one exact integrated protected head after all applicable CI, security, coverage/docstrings, package/build, SBOM/provenance, compatibility, review, migration/rollback/recovery, accessibility and operational acceptance gates pass together.