@cleocode/skills 2026.5.84 → 2026.5.86

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

@@ -249,3 +249,12 @@ This skill binds to the **validation** LOOM lifecycle stage. Governing ADRs:
 - [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

package/skills/ct-validator/references/anti-patterns.md

@@ -0,0 +1,194 @@
+# Anti-Patterns
+
+Common failure modes when running validation tasks. These degrade the
+report's usefulness, break downstream consumers, or mask defects. Avoid
+them by following the detection cue and the remediation.
+
+## 1. The Short-Circuit Validator
+
+**Symptom.** Validator stops on the first failure and reports only that
+one. The report claims "FAIL" but lists only one issue when there are
+several.
+
+**Detection cue.** Issue count is exactly 1 but the underlying tool
+(biome, tsc, jsonschema) has multi-issue output.
+
+**Root cause.** Engine was run without `--all-errors` (AJV),
+`--exhaustive`, or equivalent. Or a try/catch wrapped the validation
+and bailed on first throw.
+
+**Fix.** Always pass the all-errors flag. For Zod, use `safeParse` and
+collect every issue from `result.error.issues`. For TypeScript, use
+`tsc -b --pretty false` and capture every line.
+
+## 2. The Soft Pass
+
+**Symptom.** Report status is `PASS` but the target has known
+unaddressed warnings.
+
+**Detection cue.** Findings table contains entries; status is PASS.
+
+**Root cause.** Status calculus violation — PASS requires zero
+critical AND ≤2 warnings (per `compliance-reports.md`). Warnings
+above threshold demote to PARTIAL.
+
+**Fix.** Apply the status calculus mechanically. PASS only when the
+table is empty (or warnings ≤2). When in doubt, demote.
+
+## 3. The Unreproducible Report
+
+**Symptom.** Six weeks later, someone tries to re-validate the same
+target. The report's claims cannot be verified.
+
+**Detection cue.** Report has no `## Trace` section or the Trace lists
+no reproducer command.
+
+**Root cause.** Reporter forgot to record the command sequence and
+tool versions used.
+
+**Fix.** Always include the reproducer. The Trace section is mandatory
+per the canonical scaffold.
+
+```markdown
+## Trace
+
+- Target: packages/cleo/src/release.ts (at 5608f75cd)
+- Tooling: biome@2.4.11, tsc@5.6.0, pnpm@9.x
+- Reproducer:
+  pnpm biome check packages/cleo/src/release.ts && \
+  pnpm exec tsc -b packages/cleo --pretty false
+```
+
+## 4. The Mode Confusion
+
+**Symptom.** A Document-mode report applies Code-mode rules, or
+vice-versa.
+
+**Detection cue.** Findings about TypeScript strictness in a spec
+review; findings about RFC 2119 in a code lint.
+
+**Root cause.** Mode was not made explicit at the start; the validator
+defaulted to its strongest familiarity.
+
+**Fix.** Declare mode in the report header. The spawn prompt or task
+body MUST set it; if absent, ask the orchestrator to clarify before
+proceeding.
+
+## 5. The Missing Severity
+
+**Symptom.** Findings listed but consumer cannot prioritize.
+
+**Detection cue.** Findings without `Critical | Warning | Suggestion`
+classification.
+
+**Root cause.** Reporter treated all findings as equal.
+
+**Fix.** Every finding MUST carry severity. When unclear, apply the
+"blocks ship?" test: yes → Critical; no → Warning; "nice to have" →
+Suggestion.
+
+## 6. The Vague Remediation
+
+**Symptom.** Issue says "fix this". Reader does not know how.
+
+**Detection cue.** `Fix:` line is missing or contains only "see above"
+/ "obvious from context" / "fix the issue".
+
+**Root cause.** Reporter ran out of energy by the time they got to
+the fix column.
+
+**Fix.** Every finding has a concrete fix step. If the fix requires
+discussion (architectural change), state that — but specifically:
+"file a task to redesign the credential rotation flow; reference
+ADR-XX-NEW once it lands".
+
+## 7. The Phantom Test
+
+**Symptom.** Protocol mode report claims REQ-NNN is verified by
+`test/foo.test.ts::case-name`. The test does not exist.
+
+**Detection cue.** Reproducer command fails with "no such test".
+
+**Root cause.** Reporter copied the spec's traceability matrix without
+re-checking that the named tests still exist (or ever existed).
+
+**Fix.** Re-run each verification command from the traceability
+matrix during validation. Flag REQs whose verification fails to
+resolve as Critical findings — the spec drifted from the implementation.
+
+## 8. The Single-File Tunnel
+
+**Symptom.** Code-mode validation runs only on the file that was
+explicitly named. Misses related files that share the violation.
+
+**Detection cue.** Report has findings in `release.ts` only; the
+same issue exists in 5 sibling files that were not checked.
+
+**Root cause.** Reporter took the task literally instead of the
+useful scope.
+
+**Fix.** Apply the validation to all related files when feasible —
+"the diff" usually means "all files touched by the task branch", not
+"only the one file the orchestrator mentioned".
+
+## 9. The Stale Schema
+
+**Symptom.** Schema-mode validation passes but downstream consumers
+still reject the data.
+
+**Detection cue.** Schema version pinned in the report does not match
+the producer's contract.
+
+**Root cause.** Schema was updated upstream; validator used a cached
+or pinned older version.
+
+**Fix.** Always resolve the schema fresh from the contract source
+(`@cleocode/contracts`). Pin the consumer/producer relationship in
+the schema's `$id` and `version` fields and check both.
+
+## 10. The Disposable Sidecar
+
+**Symptom.** JSON sidecar emitted, but it has different findings than
+the markdown report.
+
+**Detection cue.** `diff <(md-extract-findings report.md)
+<(jq '.findings' report.json)` shows mismatched data.
+
+**Root cause.** Reporter wrote the markdown manually and the JSON
+separately; they drifted.
+
+**Fix.** Generate one from the other. Write the structured data first
+(JSON), then render the markdown from it. A `--render-md` flag on the
+report generator enforces this.
+
+## 11. The Unsourced Rule
+
+**Symptom.** A finding cites a rule that does not exist in any visible
+standard.
+
+**Detection cue.** Rule reference is prose ("naming should be
+consistent") rather than a stable identifier ("AGENTS.md §Package
+Boundary").
+
+**Root cause.** Reporter applied a personal preference and labeled
+it as a rule.
+
+**Fix.** Every rule citation MUST link to a stable source:
+`AGENTS.md §X`, `ADR-NNN`, `biome.json#rules.style.Y`. If the
+preference is real but unwritten, the report SHOULD propose adding
+it to the standard (file a task) rather than enforcing it silently.
+
+## 12. The Pre-Empty Report
+
+**Symptom.** Validator runs against an empty or absent target, reports
+`PASS`.
+
+**Detection cue.** Target file is empty or does not exist; report says
+"100% compliance".
+
+**Root cause.** Engine returned zero violations because there was
+nothing to violate.
+
+**Fix.** Always sanity-check the target exists and has content before
+running validation. Empty/missing target is itself a Critical finding —
+not a clean pass.