@cleocode/skills 2026.5.83 → 2026.5.86

package/skills/ct-task-executor/references/common-failures.md

@@ -0,0 +1,193 @@
+# Common Failures
+
+The most frequent worker-agent failure modes observed across CLEO
+sessions. Each entry includes a recognition signal, the root cause, and
+the corrected approach. Many of these are recorded in BRAIN observations
+under `O-*` IDs.
+
+## False Success Reports
+
+**Symptom.** Worker returns "Task complete. All tests pass." The
+orchestrator later finds (via `cleo show <id>` showing pending gates,
+or `git log` showing no commits, or `pnpm test` showing failures) that
+the work was not actually done.
+
+**Recognition.** Reported success without (a) a commit SHA in the
+response, (b) the test output excerpt, or (c) a `cleo verify` audit
+trail.
+
+**Root cause.** The worker conflated "I drafted code that should work"
+with "I ran the tests and they passed." Often correlates with model
+fatigue at >70% context utilization.
+
+**Fix.** The worker MUST run the full quality-gate sequence (biome →
+build → typecheck → test) and capture the exit codes / output before
+reporting completion. The spawn prompt's tier-1+ injection contains this
+ritual — re-read it if uncertain.
+
+This failure mode was first formally documented in T1450 PROOF
+(`spawn-capability-gap-2026-04-25.md` — historical context, the
+underlying gap is now resolved but the pattern recurs at the worker
+level).
+
+## Outside-Worktree Edits
+
+**Symptom.** Worker edits files outside its assigned worktree path. The
+git shim usually blocks this, but if it slips through, the change does
+not get into the PR.
+
+**Recognition.** Files appear modified in `/mnt/projects/cleocode/` but
+not in the worktree's branch.
+
+**Root cause.** Worker resolved a relative path against the wrong cwd
+(persistent shell state was not reset between tool calls), or
+deliberately followed an absolute path from a prior session's notes.
+
+**Fix.** The spawn prompt's `FIRST ACTION: cd <path>` MUST be the first
+command. All subsequent paths SHOULD be absolute within the worktree.
+If unsure, prefix with `git rev-parse --show-toplevel` first.
+
+## Cherry-Pick Instead of Merge
+
+**Symptom.** When integrating completed work to main, the worker (or
+overzealous orchestrator) used `git cherry-pick` instead of
+`git merge --no-ff`.
+
+**Recognition.** `git log --grep "<task-id>"` shows different SHAs in
+the task branch vs main. The author email is lost. `cleo find` cannot
+relate commits to the task.
+
+**Root cause.** Following a generalized "cherry-pick is safer" instinct
+without reading ADR-062. The CLEO contract is that workers commit on
+their task branch; the integrator MUST use `git merge --no-ff
+task/<id>` to preserve SHAs, author identity, and the
+`cleo find <task-id> --commits` trace.
+
+**Fix.** Always `git merge --no-ff task/<TID>` for integration. See
+`feedback_cherry_pick_worktrees.md` for the full pattern.
+
+## Hard Reset Disasters
+
+**Symptom.** Multiple worktree-spawn agents working in parallel suddenly
+find their work has vanished from main. The orchestrator's primary
+working dir's branch is on main; an agent or the orchestrator ran
+`git reset --hard origin/main`, wiping local commits that had not yet
+been pushed.
+
+**Recognition.** `git reflog` on the primary working dir shows a
+recent `HEAD@{N}: reset: moving to origin/main`.
+
+**Root cause.** The primary working dir's branch is shared across
+parallel orchestrators. A reset there wipes shared state. Caught in
+T9354 session and recovered via reflog cherry-pick — at the cost of 3
+PRs.
+
+**Fix.** NEVER `git reset --hard` on the orchestrator's primary working
+dir while any worker agents are alive. Apply fixes from inside the
+worker's worktree path, or use `git update-ref` + push to land
+corrections without resetting the local branch.
+
+## ESM Import Path Drift
+
+**Symptom.** Build fails locally with `ERR_MODULE_NOT_FOUND` or CI fails
+with `Cannot find module './foo'` even though the file exists.
+
+**Recognition.** Import line `import { foo } from "./foo";` (no
+`.js` extension).
+
+**Root cause.** The repo's TypeScript config uses pure ESM with explicit
+`.js` extensions on imports. Stripping the extension works at write
+time but fails at runtime under Node's strict ESM resolver.
+
+**Fix.** Always include `.js` in relative imports — even for `.ts`
+sources. The compiled output uses the same extension. Workspace imports
+(`@cleocode/...`) do not need the extension.
+
+## Cross-Package Reach
+
+**Symptom.** Worker imports across package boundaries without declaring
+the dependency in the consumer's `package.json`. Build succeeds locally
+(pnpm hoists) but CI fails on a clean install.
+
+**Recognition.** Import like `import { thing } from "../../core/src/foo.js"`
+inside `packages/cleo/`.
+
+**Root cause.** Took a relative-path shortcut instead of using the
+workspace import `@cleocode/core`. Also bypasses the type contract.
+
+**Fix.** Add the consumer's `package.json` dependency and use the
+workspace import:
+
+```typescript
+import { thing } from "@cleocode/core/foo";
+```
+
+If the function being imported is not exported from the consumer
+package, add an export — do not reach through internals.
+
+## Type Cast Chains
+
+**Symptom.** Code contains `as unknown as SomeType`, `any` types, or
+empty `catch (err: unknown)` blocks. AGENTS.md type-safety rules ban
+all three.
+
+**Recognition.** `pnpm biome check` warnings on `any` / `unknown` usage,
+or grep for `as unknown as`.
+
+**Root cause.** Worker hit a type mismatch and reached for the escape
+hatch instead of fixing the underlying contract.
+
+**Fix.** Inspect the actual types; update or extend the contract in
+`packages/contracts/src/` if necessary. The repo's policy is "find the
+root cause" — type casts hide the cause and accumulate as debt.
+
+## Drive-By Refactors
+
+**Symptom.** PR for T9660 includes unrelated changes to files outside
+the task's scope. Reviewer comments "scope creep" and requests a split.
+
+**Recognition.** `git diff --stat HEAD` shows files modified that do
+not appear in the task's acceptance criteria.
+
+**Root cause.** Worker noticed something to improve while reading
+adjacent code and "fixed it in passing".
+
+**Fix.** Revert unrelated changes; file a new task for them. One task =
+one purpose = one PR. The CLEO contract relies on this for traceability.
+
+## Stale Cache Confusion
+
+**Symptom.** `cleo complete` fails with `E_EVIDENCE_STALE` even though
+the worker is sure they didn't touch the file after verify.
+
+**Recognition.** Error message references a file the worker only read,
+never edited.
+
+**Root cause.** A formatter (biome auto-fix on save, or a sibling
+agent's commit) modified the file between `cleo verify` and
+`cleo complete`. The sha256 no longer matches.
+
+**Fix.** Re-run `cleo verify` for the affected gate(s) before
+`cleo complete`. Treat verify+complete as an atomic pair — minimize the
+time between them.
+
+## Forgotten Memory Observation
+
+**Symptom.** Task completed; the session ends; the next session
+re-discovers a fact that should have been retained.
+
+**Recognition.** `cleo memory find <topic>` after the task returns
+nothing, even though the worker learned something non-trivial.
+
+**Root cause.** Worker skipped the post-complete `cleo memory observe`
+step (CLEO-INJECTION.md trigger row 2: "after non-trivial task
+completion").
+
+**Fix.** After every non-trivial `cleo complete`, run:
+
+```bash
+cleo memory observe "<one-paragraph learning>" --title "<short title>"
+```
+
+Trivial tasks (typo fix, version bump) do not need observations.
+Anything that changed your mental model does.

package/skills/ct-task-executor/references/evidence-and-gates.md

@@ -0,0 +1,179 @@
+# Evidence and Gates
+
+ADR-051 requires every `cleo complete <TASK_ID>` to be backed by
+programmatic evidence. The executor MUST attach evidence atoms to each
+gate before completing; the verify step re-validates them against git,
+the filesystem, and the toolchain. This reference defines atom shapes,
+canonical names, and the failure modes most often hit.
+
+## The Gate Set
+
+Every task carries six standard gates. Optional gates may be added per
+task; the standard set is non-negotiable.
+
+| Gate | Meaning | Evidence kind |
+|------|---------|---------------|
+| implemented | Code change exists | `commit:<sha>` + `files:<list>` |
+| testsPassed | Tests green | `tool:test` or `test-run:<json>` |
+| qaPassed | Lint + typecheck clean | `tool:lint` + `tool:typecheck` |
+| documented | Docs updated | `files:<docs-paths>` |
+| securityPassed | Security scan or waiver | `tool:security-scan` or `note:<rationale>` |
+| cleanupDone | Branch/cleanup summary | `note:<text>` |
+
+Decision-only tasks (no code change; the deliverable is a recorded BRAIN
+decision) use a distinct `implemented` atom shape:
+
+```bash
+cleo verify T### --gate implemented \
+  --evidence "decision:D-arch-001;files:docs/research-note.md"
+```
+
+This shape eliminates the `CLEO_OWNER_OVERRIDE` path on decision-only
+completion (per T1875).
+
+## Atom Kinds
+
+### `commit:<sha>`
+
+The git commit SHA where the work landed. Re-validated for reachability
+from HEAD at complete time. The SHA MUST be a full or short SHA that
+`git rev-parse` resolves.
+
+```bash
+cleo verify T### --gate implemented \
+  --evidence "commit:b8e723d78;files:packages/skills/.../references/triggers.md"
+```
+
+If the worktree's branch has been merged to main since the commit, the
+atom still resolves. If the commit was rebased away, validation fails
+with `E_EVIDENCE_STALE` — re-attach the new SHA.
+
+### `files:<comma-list>`
+
+Paths affected by the work. Re-validated by sha256 against the on-disk
+file at complete time. If the file's contents change between verify
+and complete (e.g. a later edit drifts the hash), validation fails with
+`E_EVIDENCE_STALE`.
+
+```bash
+--evidence "files:packages/cleo/src/commands/release-plan.ts,packages/cleo/__tests__/release-plan.test.ts"
+```
+
+Use forward slashes; absolute or repo-relative paths both work.
+
+### `tool:<name>`
+
+Canonical tool name. CLEO resolves to the project's actual command via
+`.cleo/project-context.json` (`testing.command`, `build.command`) with
+per-`primaryType` fallbacks. Canonical names:
+
+| Canonical | Resolves to (Node) | Fallback |
+|-----------|-------------------|----------|
+| `test` | `pnpm run test` | `cargo test`, `pytest`, `go test` |
+| `build` | `pnpm run build` | `cargo build`, etc. |
+| `lint` | biome / eslint | clippy, ruff |
+| `typecheck` | `tsc -b` | mypy |
+| `audit` | `pnpm audit` | `cargo audit` |
+| `security-scan` | varies | varies |
+
+Legacy aliases still work: `pnpm-test`, `tsc`, `biome`, `cargo-test`,
+`pytest` all map to canonical names.
+
+### `test-run:<json-path>`
+
+Path to a vitest JSON output file. Re-validated by hash. Preferred for
+sharing test evidence across sibling tasks in the same wave.
+
+```bash
+pnpm vitest run --reporter=json --outputFile=/tmp/vitest-out.json
+cleo verify T### --gate testsPassed --evidence "test-run:/tmp/vitest-out.json"
+```
+
+### `decision:<decision-id>`
+
+A BRAIN decision ID (e.g., `D-arch-001`) or an `AGT-*` provenance ID.
+Validated by lookup against the brain.db; status MUST be `proposed` or
+`accepted`. Used for decision-only tasks where the deliverable is the
+decision itself, not code.
+
+### `note:<text>`
+
+Free-form rationale. Always permitted; used when no programmatic atom
+applies. Notes appear in the audit log but do not gate validation —
+they document, they do not prove. Reserve for `cleanupDone`,
+`securityPassed` waivers, and rare edge cases.
+
+## The Ritual
+
+The full per-task ritual, in order:
+
+```bash
+# 1. Implement and verify locally
+pnpm biome check --write .
+pnpm run build && pnpm run typecheck
+pnpm run test
+git add -p && git commit -m "feat(T###): <slug>"
+
+# 2. Capture evidence for each gate (commit SHA from step 1)
+SHA=$(git rev-parse HEAD)
+FILES=$(git diff-tree --no-commit-id --name-only -r HEAD | paste -sd,)
+
+cleo verify T### --gate implemented --evidence "commit:$SHA;files:$FILES"
+cleo verify T### --gate testsPassed --evidence "tool:test"
+cleo verify T### --gate qaPassed --evidence "tool:lint;tool:typecheck"
+cleo verify T### --gate documented --evidence "files:docs/path/to/note.md"
+cleo verify T### --gate securityPassed --evidence "note:no network surface"
+cleo verify T### --gate cleanupDone --evidence "note:branch task/T### ready for merge"
+
+# 3. Complete (CLEO re-validates everything)
+cleo complete T###
+
+# 4. Record learning
+cleo memory observe "..." --title "..."
+```
+
+## Common Failure Modes
+
+| Exit | Code | Cause | Fix |
+|------|------|-------|-----|
+| — | `E_EVIDENCE_MISSING` | Ran `verify --all` without `--evidence` | Re-run per-gate with atoms |
+| — | `E_EVIDENCE_INSUFFICIENT` | Gate atom kind doesn't match required | See gate-atom table above |
+| — | `E_EVIDENCE_TESTS_FAILED` | `tool:test` exit non-zero | Fix failing tests first |
+| — | `E_EVIDENCE_TOOL_FAILED` | Lint/typecheck/etc exit non-zero | Fix source and re-run |
+| — | `E_EVIDENCE_STALE` | Files or commit changed after verify | Re-verify before complete |
+| — | `E_EVIDENCE_INVALID_DECISION` | Decision ID not found in BRAIN | Use `cleo memory decision-find` |
+| — | `E_FLAG_REMOVED` | Tried `cleo complete --force` | `--force` removed per ADR-051 |
+
+## Cache Behavior
+
+Tool-evidence results are cached under `.cleo/cache/evidence/<key>.json`,
+keyed on (canonical, cmd, args, HEAD, dirty-tree fingerprint). Parallel
+verifies against identical state coalesce to one execution via a per-key
+lock. Cross-worktree parallelism is bounded by a machine-wide per-tool
+semaphore at `~/.local/share/cleo/locks/tool-<canonical>/`.
+
+Tune with `CLEO_TOOL_CONCURRENCY_<TOOL>=<n>` (`0` disables). For most
+worker agents this is set-and-forget; the orchestrator handles tuning.
+
+## The Emergency Override
+
+In rare incident-response scenarios, the override exists:
+
+```bash
+CLEO_OWNER_OVERRIDE=1 \
+CLEO_OWNER_OVERRIDE_REASON="incident 1234 hotfix" \
+  cleo verify T### --all --evidence "note:owner-approved"
+```
+
+The override appends to `.cleo/audit/force-bypass.jsonl`. Use only when
+the owner has explicitly authorized — never as a routine shortcut to
+skip gates.
+
+## What NOT to Do
+
+- ❌ Run `cleo complete` without verifying tests actually ran
+- ❌ Run `cleo verify --all` without `--evidence` (REJECTED post-ADR-051)
+- ❌ Use `cleo complete --force` (REMOVED post-ADR-051)
+- ❌ Skip `cleo memory observe` on non-trivial tasks
+- ❌ Self-attest without programmatic proof
+- ❌ Modify files between `verify` and `complete` (caught by staleness check)

package/skills/ct-task-executor/references/implementation-patterns.md

@@ -0,0 +1,160 @@
+# Implementation Patterns
+
+Canonical patterns for executing CLEO tasks. The executor sits at the
+leaf of the orchestrator's pipeline — its job is to take a fully-resolved
+task spec and produce concrete deliverables that pass acceptance criteria.
+This reference codifies the patterns that succeed most consistently.
+
+## Read-Before-Write (Mandatory)
+
+The repository CLAUDE.md and AGENTS.md make this non-negotiable for CLEO:
+"Read first — understand existing code, patterns, and contracts before
+writing." For the executor, this means a concrete sequence.
+
+1. `cleo show <TASK_ID>` — full task body, including hidden acceptance
+   criteria, gate config, and prior manifest summaries.
+2. `cleo memory find "<topic-keyword>"` — prior decisions on the same
+   surface area. The BRAIN may already have answers.
+3. `Grep` for the symbol or feature name in the target package. Most
+   "new" features have a related ancestor that should be extended, not
+   rewritten.
+4. `gitnexus_impact({target: "<symbol>"})` — blast radius before any
+   edit. HIGH/CRITICAL warnings MUST be reported to the orchestrator
+   before proceeding.
+
+Skipping any of these steps produces churn the reviewer will flag.
+
+## Smallest-Change Principle
+
+Match the existing pattern even when you could "improve" it in passing.
+The contract on the executor is to ship the acceptance criteria — not
+to refactor adjacent code. If the existing pattern is genuinely broken,
+file a separate task; do not entangle a fix with the requested feature.
+
+```text
+GOOD: feat(T1234): add wave-rollup verb
+  packages/cleo/src/commands/orchestrate/wave-rollup.ts  (new file)
+
+BAD:  feat(T1234): add wave-rollup verb + clean up unrelated handler
+  packages/cleo/src/commands/orchestrate/wave-rollup.ts  (new file)
+  packages/cleo/src/commands/orchestrate/spawn.ts        (drive-by refactor)
+  packages/cleo/src/dispatch.ts                          (rename in pass)
+```
+
+The drive-by changes belong in their own task with their own acceptance
+criteria. Reviewers cannot meaningfully approve a mixed-purpose diff.
+
+## File-Placement Patterns
+
+Package boundaries are enforced — see AGENTS.md "Package-Boundary Check".
+Use this table when introducing new modules.
+
+| Concern | Package | Why |
+|---------|---------|-----|
+| Runtime primitive, domain logic, store, memory | `packages/core/` | SDK; provider-neutral |
+| CLI command handler, dispatch wiring | `packages/cleo/` | CLI surface only |
+| Shared type, envelope, operation, error | `packages/contracts/` | Cross-package contract |
+| Harness adapter, Pi runtime, claude-code adapter | `packages/cleo-os/` | Harness layer |
+| Studio frontend (SvelteKit) | `packages/studio/` | UI |
+| LAFS envelope spec or validator | `packages/lafs/` | Envelope ground truth |
+| .cant DSL or parser | `packages/cant/` | DSL |
+| Agent manifest packaging | `packages/caamp/` | Packaging |
+
+When in doubt: state runtime concerns go in `core`; CLI handlers stay
+thin and call into `core`. The repo has previously had to do T1015-style
+relocation epics — avoid creating the next one.
+
+## ESM Import Patterns
+
+The repository uses ESM with `.js` extensions on import paths (TypeScript
+strict, kebab-case files). The lint will fail any drift.
+
+```typescript
+// CORRECT
+import { openCleoDb } from "../store/open-cleo-db.js";
+import type { TaskEnvelope } from "@cleocode/contracts";
+
+// WRONG — no .js suffix
+import { openCleoDb } from "../store/open-cleo-db";
+
+// WRONG — CommonJS
+const { openCleoDb } = require("../store/open-cleo-db");
+
+// WRONG — no relative-path crossing of package boundary
+import { something } from "../../../other-package/src/foo.js";
+// (use a workspace import: import { something } from "@cleocode/other-package")
+```
+
+## Test-First When Possible
+
+For new behavior in `packages/core/` or `packages/contracts/`, write the
+test before the implementation. The test file lives alongside the source
+under `__tests__/`.
+
+```text
+packages/core/src/store/open-cleo-db.ts
+packages/core/src/store/__tests__/open-cleo-db.test.ts
+```
+
+For CLI changes where the behavior is integration-heavy (touches the
+dispatcher, the worktree, the store), prefer an end-to-end test in
+`packages/cleo/__tests__/<verb>.test.ts` that exercises the verb via
+`runMain()` rather than a unit test of an internal helper.
+
+## Error Handling Pattern
+
+The repository contracts an LAFS envelope `{ success, data?, error?, meta }`
+for every command output. Internal helpers throw typed errors; the
+dispatcher converts to envelope at the boundary.
+
+```typescript
+// Internal: throw typed error
+import { TaskNotFoundError } from "@cleocode/contracts";
+if (!task) throw new TaskNotFoundError(taskId);
+
+// Boundary: catch and wrap
+try {
+  const data = await handler(input);
+  return { success: true, data, meta: makeMeta() };
+} catch (err) {
+  return formatError(err, makeMeta());
+}
+```
+
+Do not introduce `catch (err: unknown)` — the AGENTS.md type-safety rules
+ban it. Use the contract's error types and let TypeScript narrow.
+
+## Quality Gate Sequence
+
+Run these IN ORDER before completing. The contract is in AGENTS.md;
+shortening this sequence has caused two patch-release hotfixes (v2026.4.67,
+v2026.4.69) in past sessions.
+
+```bash
+pnpm biome check --write .   # 1. format + lint
+pnpm run build               # 2. build (includes typecheck via tsc -b)
+pnpm run typecheck           # 3. typecheck — strict TS project refs
+pnpm run test                # 4. test (zero new failures)
+git diff --stat HEAD         # 5. verify scope matches intent
+```
+
+Note: `pnpm run build` (esbuild) does NOT run the strict TS project-reference
+typecheck. Always run `pnpm run typecheck` separately before tagging or
+marking complete. This was learned the hard way via L-3 in
+`feedback_typecheck_vs_build.md`.
+
+## Worktree Discipline
+
+All executor work happens inside the worktree at the path provided in the
+spawn prompt's `## Worktree Setup` section. Operations to AVOID:
+
+- `git checkout <other-branch>` — the worktree's branch is sticky.
+- `git reset --hard origin/main` — destroys in-flight commits from other
+  worktree-spawn agents (caught in T9354 session: cost 3 PRs of recovery
+  via reflog cherry-pick).
+- Editing files outside the worktree path — the git shim will block
+  most forbidden operations but the policy boundary is the worktree.
+
+When done, the orchestrator integrates via `git merge --no-ff task/<id>`
+per ADR-062 — preserving commit SHAs and task↔commit traceability. The
+executor never touches `main` directly.

package/skills/ct-validator/SKILL.md

@@ -6,6 +6,10 @@ tier: 2
 core: false
 category: recommended
 protocol: validation
+loomStage: validation
+adrRefs:
+  - ADR-051
+  - ADR-023
 dependencies: []
 sharedResources:
   - subagent-protocol-base
@@ -41,6 +45,26 @@ Context injection for compliance validation tasks spawned via cleo-subagent. Pro
 
 ---
 
+## Out of Scope (T9675)
+
+`ct-validator` operates on the **`validation`** LOOM lifecycle stage (stage 7). It performs **static** schema, compliance, and audit checks against artifacts that already exist on disk (specs, ADRs, JSON files, RFC 2119 keyword usage, manifest schemas).
+
+This skill does NOT:
+
+- Run a test suite, framework detection, or iterative IVT loop. Those belong to **`ct-ivt-looper`** at the `testing` stage (stage 8). When dynamic verification is required — e.g. "does the implementation actually pass its tests?" — chain to `ct-ivt-looper` rather than expanding scope here.
+- Modify code or apply fixes. The validator reports; downstream skills remediate.
+
+### Chain handoffs
+
+| Direction | When | Handoff |
+|---|---|---|
+| `ct-validator` → `ct-ivt-looper` | Spec is valid but implementation needs dynamic verification | Emit a manifest entry, then dispatch the `testing` stage |
+| `ct-ivt-looper` → `ct-validator` | IVT loop converged; need to audit the resulting artifacts against schema/compliance | Dispatch the `validation` stage after the test convergence record |
+
+Governance: see **ADR-051** (programmatic gate integrity) which defines the evidence atoms each stage emits and that the other stage may re-validate, and **ADR-023** (protocol validation dispatch) which routes between them.
+
+---
+
 ## Validation Methodology
 
 ### Standard Workflow
@@ -214,3 +238,23 @@ When invoked by orchestrator, expect these context tokens:
 | Vague findings | Unclear remediation | Specific issue + file/line + fix |
 | Missing severity | Can't prioritize | Always classify: critical/warning/suggestion |
 | No remediation | Findings not actionable | Always provide fix for FAIL/PARTIAL |
+
+---
+
+## See also / References
+
+This skill binds to the **validation** LOOM lifecycle stage. Governing ADRs:
+
+- [ADR-051 — programmatic gate integrity](../../../../.cleo/adrs/ADR-051-programmatic-gate-integrity.md) — defines the evidence-atom grammar that the validator emits and re-validates.
+- [ADR-023 — protocol validation dispatch](../../../../.cleo/adrs/ADR-023-protocol-validation-dispatch.md) — defines the protocol-validation routing layer that dispatches to this skill.
+
+LOOM coverage matrix: [docs/skills/loom-coverage-matrix.md](../../../../docs/skills/loom-coverage-matrix.md).
+
+## See references/
+
+Progressive disclosure — load on demand only:
+
+- `references/validation-modes.md` — schema/code/document/protocol modes, selection rubric, composition
+- `references/schema-checking.md` — engine selection, draft selection, pitfalls, bulk validation
+- `references/compliance-reports.md` — canonical scaffold, status calculus, severity, ct-ivt-looper integration
+- `references/anti-patterns.md` — twelve validation failure modes with detection and remediation