docs: add CLAUDE.md guidance for AI assistants

CLAUDE.md

@@ -0,0 +1,120 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Read first
+
+`AGENTS.md` is the canonical agent entry point. Per its instructions, before any work read
+[`docs/CWL-MASTER-CONTEXT.md`](docs/CWL-MASTER-CONTEXT.md) (mission, ecosystem UML, cross-cutting
+disciplines CP-1..CP-5/G6/SEAM, binding engineering conventions in §7, roadmap), the live
+[GitHub Project #1](https://github.com/orgs/ContextualWisdomLab/projects/1) (work/roadmap source of
+truth), and operate the Project per [`docs/agent-github-project-protocol.md`](docs/agent-github-project-protocol.md).
+The repo/Project — not private agent memory — is the source of truth. This file complements those
+documents; it does not replace them.
+
+## What this repository is
+
+This is the ContextualWisdomLab **organization-wide `.github` special repository**. It has three roles:
+
+1. **Org profile page** — `profile/README.md` (Korean/English lab introduction, DIKW checkpoints,
+   project catalog) is what GitHub renders at https://github.com/ContextualWisdomLab. Assets live in
+   `profile/assets/`. Org-wide defaults `SECURITY.md`, `.github/CODEOWNERS`, and
+   `.github/dependabot.yml` also live here.
+2. **Central PR governance and CI hub** — the workflows in `.github/workflows/` are the canonical
+   implementation of PR review, security scanning, and merge automation for **every sibling repo**.
+   An organization required-workflow ruleset (`CWL Central required workflows`, id `18156473`) runs
+   Strix, OpenCode Review, and the PR Review Merge Scheduler from this repo in each target
+   repository's context. Repository-local copies of these workflows are drift sources, not
+   repo-specific contracts. See `README.md` (policy summary) and `PR_GOVERNANCE_AUDIT.md`
+   (live audit + per-repo DX/UX transfer decisions).
+3. **Infrastructure as code** — `infra/cloudflare/` manages the org's DNS zones and Cloudflare Pages
+   hosting declaratively (`zones.json` + `reconcile.sh`, curl + jq only; dry-run by default, writes
+   only on explicit manual `mode = apply`).
+
+## Governance model in one paragraph
+
+**OpenCode judges PRs; GitHub Actions performs mechanical updates and merges.** OpenCode approval is
+evidence-gated (changed files, CodeGraph evidence, Change Flow DAG, test/coverage/docstring evidence,
+an actually-executed PoC via `scripts/ci/sandboxed_verify.py` or `scripts/ci/sandboxed_web_e2e.py`,
+split `Developer experience:` / `User experience:` sections). The scheduler updates a PR branch only
+when the latest review is approved, no current-head check has failed, and GitHub reports the PR as
+behind; `DIRTY`/`CONFLICTING` PRs get repair guidance, never a synthesized fix. Old approvals and old
+checks are not merge evidence after the head SHA changes. Details: `README.md` and
+`PR_GOVERNANCE_AUDIT.md`.
+
+## Structure
+
+- `.github/workflows/` — the central workflows. `pull_request_target`-triggered required workflows
+  (`opencode-review.yml`, `noema-review.yml`, `pr-review-merge-scheduler.yml`, `strix.yml`,
+  `close-empty-pr.yml`, …), security gates (`python-security.yml` bandit + pip-audit,
+  `security-scan.yml`, `sast-semgrep.yml`, `secret-scan.yml`, `codeql-pr.yml`, `osv-scanner-pr.yml`,
+  `scorecard-*.yml`, SBOM workflows), and reusable `workflow_call` workflows sibling repos call
+  (`deploy-pages.yml`, `pr-review-fix-scheduler.yml`).
+- `scripts/ci/` — Python/bash helpers the workflows execute (schedulers, review normalization and
+  gates, sandboxed verification, prompt template rendering). `tests/` covers them.
+- `opencode.jsonc` + `ci-review-prompt.md` + `code-reviewer-prompt.md` — the OpenCode reviewer
+  configuration (GitHub Models provider, CodeGraph/DeepWiki/Context7/web-search MCP). All reviewer
+  agents have `"edit": "deny"`: they are reviewers, never implementers. Keep it that way.
+- `requirements-{bandit,pip-audit,strix,opencode-review}-ci.txt` + `*-hashes.txt` — pinned CI
+  dependency sets (see below).
+- `fuzz/` + `.clusterfuzzlite/` — Atheris fuzz targets for the review-output normalizer and the
+  ClusterFuzzLite discovery marker.
+- `docs/` — master context, Project protocol, `org-required-workflow-rollout.md`,
+  `scorecard-governance.md`, SBOM inventory.
+- `.jules/` — recorded performance (`bolt.md`) and security (`sentinel.md`) learnings from past work
+  on `scripts/ci/`; worth scanning before optimizing or hardening those scripts.
+
+## Commands
+
+Run from the repo root. CI installs the exact toolchain with:
+
+```bash
+python3 -m pip install --require-hashes --only-binary=:all: -r requirements-opencode-review-ci-hashes.txt
+```
+
+Tests, coverage, and docstring gates (`pyproject.toml` sets `pythonpath = ["."]`, coverage source
+`scripts/ci` with `fail_under = 100`, and interrogate `fail-under = 100` excluding `tests`):
+
+```bash
+coverage run -m pytest tests && coverage report --show-missing
+interrogate
+```
+
+## Hash-pinned requirements discipline
+
+CI installs Python tools only with `pip install --require-hashes` from the `*-hashes.txt` files.
+Never hand-edit a `-hashes.txt` file: edit the top-level `requirements-<tool>-ci.txt` input, then
+regenerate with the exact `uv pip compile` command recorded in the hashes file's header comment,
+e.g.:
+
+```bash
+uv pip compile --generate-hashes --python-version 3.12 --python-platform x86_64-manylinux_2_28 requirements-bandit-ci.txt -o requirements-bandit-ci-hashes.txt
+uv pip compile --generate-hashes --python-version 3.12 --python-platform x86_64-manylinux_2_28 requirements-pip-audit-ci.txt -o requirements-pip-audit-ci-hashes.txt
+uv pip compile --generate-hashes --python-version 3.13 --python-platform x86_64-manylinux_2_28 --output-file requirements-strix-ci-hashes.txt requirements-strix-ci.txt
+```
+
+Note the per-file Python versions differ (bandit/pip-audit: 3.12; strix: 3.13).
+
+## Conventions and gotchas specific to this repo
+
+- **Contract tests pin workflows AND prose.** `tests/` asserts exact strings and structure of
+  `PR_GOVERNANCE_AUDIT.md`, `docs/org-required-workflow-rollout.md`, `opencode.jsonc`, and several
+  workflow files (e.g. `test_pr_governance_audit_contract.py`, `test_codeql_pr_workflow_contract.py`,
+  `test_opencode_workflow_shell_syntax.py`, `test_opencode_agent_contract.py`). Editing those files
+  without running the test suite will break CI.
+- **100% coverage and 100% docstrings on `scripts/ci/`** are hard gates, not aspirations. New helper
+  code needs matching tests and docstrings.
+- **`pull_request_target` trust boundary.** The required review workflows run the *base branch's*
+  trusted scripts. A PR that edits the trusted review workflows can fail its own checks until the
+  base branch catches up; a same-head manual `workflow_dispatch` Strix run may supply review evidence
+  but does not replace required PR checks. Do not widen a `pull_request_target` job token to
+  repository-write permission.
+- **Review output must go through the Python normalizer** (`scripts/ci/opencode_review_normalize_output.py`)
+  — it escapes `<`, `>`, `&` when embedding JSON in HTML comments to prevent Markdown-comment
+  breakout. Do not reintroduce bash fast-path extraction.
+- **Cloudflare changes are dry-run by default**; nothing is deleted unless `prune = true` is set
+  explicitly. PRs never see the Cloudflare API token.
+- **Org-wide binding conventions** (permissive licenses only — verify SPDX before adding anything;
+  cross-repo references as `owner/repo#num` or full URLs; durable knowledge in the repo/Project, not
+  private memory; one roadmap phase at a time) are defined in `docs/CWL-MASTER-CONTEXT.md` §7 and
+  apply here.