@cleocode/skills 2026.5.84 → 2026.5.87

package/skills/ct-task-executor/references/acceptance-criteria-mapping.md

@@ -0,0 +1,163 @@
+# Acceptance Criteria Mapping
+
+Every CLEO task ships with explicit acceptance criteria (ACs) — usually
+3-6 pipe-separated entries on the task's `acceptance` field. The executor's
+job is to map each AC to a verifiable deliverable, exercise it, and report
+the mapping in the manifest. This reference defines the mapping discipline.
+
+## Read the Whole AC Set First
+
+Before touching code, run `cleo show <TASK_ID>` and copy the full `acceptance`
+array into your scratch notes. Do not start with a partial reading — ACs
+interact, and some only make sense in light of others.
+
+Example AC set (from T9660):
+
+```text
+1. packages/skills/skills/ct-research-agent/references/ created with 4 files (...)
+2. each reference doc is >=50 lines of genuine multi-source research guidance (...)
+3. SKILL.md updated to link references via standard 'See references/' resolution pattern
+4. packages/skills/skills/manifest.json references array updated to enumerate all reference files
+5. skill body >=10K bytes per gold standard; load-time token budget verified <=8000
+6. Code placed in packages/skills/ per Package-Boundary Check - verified against AGENTS.md
+```
+
+This task has six ACs — three structural (1, 4, 6), two content-quality
+(2, 5), and one cross-link (3). The implementation must touch all of them.
+
+## Build a Mapping Table
+
+For each AC, identify the deliverable and the verification mechanism.
+Write the table to your scratch first — do not start implementing until
+every AC has a row.
+
+| AC | Deliverable | Verification |
+|----|-------------|--------------|
+| AC1 | 4 .md files under references/ | `ls` + filename match |
+| AC2 | ≥50 lines each, genuine content | `wc -l` + manual review |
+| AC3 | SKILL.md footer with "See references/" | grep for footer block |
+| AC4 | manifest.json `references` array populated | `jq` extract + length |
+| AC5 | Skill body ≥10K bytes | `wc -c packages/.../SKILL.md` |
+| AC6 | Files placed in packages/skills/ | path inspection |
+
+The verification column MUST yield a yes/no answer — not "looks good".
+If an AC cannot be reduced to a mechanical check, push back to the
+orchestrator: "AC-N is not testable; please clarify the success
+condition."
+
+## AC Categories and Standard Verifications
+
+| Category | Signal phrases | Standard verification |
+|----------|----------------|----------------------|
+| Existence | "created", "added", "exists" | `ls`, `stat`, `[ -f path ]` |
+| Count | "with N files", "≥3 entries" | `find -type f | wc -l` |
+| Length/size | "≥50 lines", "≥10K bytes" | `wc -l`, `wc -c` |
+| Linkage | "linked from", "referenced in" | `grep -F` |
+| Tests pass | "all tests pass", "no regressions" | `pnpm run test` |
+| Lint clean | "biome check passes" | `pnpm biome check .` |
+| Build clean | "compiles", "type-checks" | `pnpm run build && pnpm run typecheck` |
+| Spec match | "satisfies REQ-NNN" | manual trace + test |
+| Boundary | "placed in packages/X per Package-Boundary Check" | path inspection |
+| Provenance | "commit message includes task ID" | `git log --grep=<TID>` |
+
+When an AC mentions "Package-Boundary Check", you MUST cite the AGENTS.md
+section by name in the manifest's `key_findings` — the orchestrator
+greps for that compliance phrase.
+
+## Acceptance Criteria Anti-Patterns
+
+These shapes signal that the AC needs refinement before execution.
+
+| Anti-pattern AC | Why it fails | What to ask the orchestrator |
+|-----------------|--------------|------------------------------|
+| "Implementation works as expected" | Not testable | What is the expected behavior? |
+| "User experience improved" | Subjective | Which metric should improve and by how much? |
+| "Performance is good" | No baseline | What's the target latency / throughput? |
+| "Documentation updated" | Which docs? | Specific file paths or section names? |
+| "No regressions" | Whole-suite test or focused? | Which test files must pass? |
+
+When an AC is fuzzy, push back BEFORE starting. The orchestrator can
+refine the AC; rework caused by guessing the AC is much more expensive.
+
+## Pre-Flight: AC → Test Mapping
+
+Before writing implementation code, for each AC that mentions testable
+behavior, identify or create the test that exercises it.
+
+```bash
+# AC-7: "the new release-plan verb errors with E_VALIDATION on missing --epic"
+
+# Find existing test file
+find packages/cleo -path '*/release-plan*' -name '*.test.ts'
+
+# If no test exists yet, create the skeleton
+cat > packages/cleo/__tests__/release-plan.test.ts <<'EOF'
+import { describe, it, expect } from "vitest";
+describe("release-plan", () => {
+  it("errors with E_VALIDATION on missing --epic", () => {
+    // RED — test fails until handler exists
+  });
+});
+EOF
+```
+
+Run the test now — it should fail (the implementation is not there yet).
+This confirms your mapping: the test exercises the right AC.
+
+## During Implementation
+
+Keep the mapping table open in your scratch. After each significant edit,
+re-run the verification for the AC you just touched. Do not let mappings
+drift — if you discover an AC requires a different deliverable than you
+planned, update the table BEFORE making the change.
+
+## Post-Implementation: AC Verification Walkthrough
+
+Before calling `cleo verify` or `cleo complete`, execute every verification
+in the table.
+
+```bash
+# AC1: 4 files exist
+ls packages/skills/skills/ct-research-agent/references/ | wc -l
+# expect: 4
+
+# AC2: each ≥50 lines
+wc -l packages/skills/skills/ct-research-agent/references/*.md
+# expect: each line count >= 50
+
+# AC3: SKILL.md has footer
+grep -q "## See references/" packages/skills/skills/ct-research-agent/SKILL.md
+# expect: exit 0
+
+# AC4: manifest.json references array populated
+jq '.skills[] | select(.name=="ct-research-agent") | .references | length' \
+  packages/skills/skills/manifest.json
+# expect: 4
+
+# AC5: skill body ≥10K bytes
+wc -c packages/skills/skills/ct-research-agent/SKILL.md
+# expect: byte count >= 10000
+
+# AC6: path inspection
+echo "All files under packages/skills/ — confirms Package-Boundary Check"
+```
+
+## Manifest Reporting
+
+The pipeline_manifest entry's `key_findings` MUST report AC outcomes
+concisely. Use this shape:
+
+```json
+{
+  "key_findings": [
+    "AC1-4 met: 4 reference files created (triggers, source, citation, anti-patterns)",
+    "AC2 met: line counts 116/93/140/154 (all >=50)",
+    "AC3-4 met: SKILL.md footer added; manifest references[] populated",
+    "AC5 verified: skill body 11.2KB",
+    "AC6 verified: all files under packages/skills/ per AGENTS.md"
+  ]
+}
+```
+
+If any AC failed or was partial, surface it. Silent partial completion
+breaks the orchestrator's rollup logic.

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

@@ -0,0 +1,201 @@
+# Anti-Patterns
+
+The instant-rejection list for executor work — from AGENTS.md
+"Anti-Patterns (INSTANT REJECTION)" plus session-observed additions.
+Each anti-pattern is testable by the orchestrator's reviewer; do not
+ship work that contains any of these.
+
+## 1. Test Theater
+
+**Anti-pattern.** Claiming "tests pass" without actually running
+`pnpm run test`.
+
+**Detection.** Manifest reports `testsPassed: true` but no
+`tool:test` evidence atom; or evidence atom references a stale cache
+key.
+
+**Cost.** Reviewer must reject and re-spawn the work, doubling the
+token spend on the task.
+
+**Correct pattern.** Always run tests, capture the exit code, and pass
+`--evidence "tool:test"` to `cleo verify`. The cache will skip re-running
+if state is unchanged; running it is free.
+
+## 2. Workaround Over Root Cause
+
+**Anti-pattern.** Adding `// @ts-ignore`, `eslint-disable-next-line`, or
+`as unknown as X` chains to suppress an error rather than fixing it.
+
+**Detection.** Suppression comments or escape-hatch casts in the diff.
+
+**Cost.** Technical debt accumulates; the actual contract violation
+remains; the next worker encounters the same problem.
+
+**Correct pattern.** Diagnose the type/lint failure; update the
+contract in `packages/contracts/` or fix the source. Suppression is
+permitted only with an inline TODO referencing a follow-up task ID,
+e.g., `// @ts-ignore — TODO(T9999): legacy adapter pending refactor`.
+
+## 3. Skipped Lint/Format
+
+**Anti-pattern.** Committing without `pnpm biome check --write .`,
+producing a diff with unrelated whitespace or import-order churn that
+biome would normalize.
+
+**Detection.** Reviewer's `pnpm biome check .` (in CI) reports
+violations on lines the worker did not intentionally touch.
+
+**Cost.** Biome's auto-fix produces large drive-by diffs in the next
+PR; review noise drowns the actual change.
+
+**Correct pattern.** Run `pnpm biome check --write .` BEFORE every
+commit. Make biome's output part of the commit, not a follow-up cleanup.
+
+## 4. New File Where Existing Suffices
+
+**Anti-pattern.** Creating a new helper file when the existing utility
+module could be extended.
+
+**Detection.** Diff contains a new file in `src/` that exports a single
+function which logically belongs alongside existing functions in a
+sibling file.
+
+**Cost.** Code duplication; future maintainers do not find the helper
+because the search lands on the older file.
+
+**Correct pattern.** Before creating any new file, run
+`Grep "<related-keyword>" packages/<pkg>/src/` and add to the most
+related existing module. NEVER create files unless they are absolutely
+necessary.
+
+## 5. `catch (err: unknown)`
+
+**Anti-pattern.** Wrapping a function body in `try { ... } catch (err:
+unknown) { ... }` and then casting `err` to read its `.message`.
+
+**Detection.** Grep for `catch (err: unknown)` or `catch (e: unknown)`.
+
+**Cost.** Defeats type narrowing; hides real error types; AGENTS.md
+explicitly bans this.
+
+**Correct pattern.** Use the contract's typed error classes from
+`packages/contracts/src/errors.ts`. Throw and catch by class, not by
+the generic `Error` shape.
+
+```typescript
+import { TaskNotFoundError, ValidationError } from "@cleocode/contracts";
+try {
+  ...
+} catch (err) {
+  if (err instanceof TaskNotFoundError) { ... }
+  if (err instanceof ValidationError) { ... }
+  throw err; // re-throw unknown
+}
+```
+
+## 6. console.log in Production Code
+
+**Anti-pattern.** Leftover `console.log("debug:", x)` after debugging.
+
+**Detection.** `pnpm biome check .` flags it; grep for `console.log`
+in `src/` (test files may legitimately log).
+
+**Cost.** Spam in user-facing CLI output; potential PII leakage.
+
+**Correct pattern.** Remove debug logs before commit. For genuine
+operational logging, use the project's logger (LAFS envelope meta
+field, or `packages/core/src/log/` if present).
+
+## 7. Import Without Boundary Check
+
+**Anti-pattern.** Adding an import that creates a circular dependency
+or crosses a package boundary the consumer does not declare.
+
+**Detection.** `pnpm run build` fails with module-resolution error, or
+the build succeeds locally but CI's clean install fails.
+
+**Cost.** CI-only failure; PR cannot land.
+
+**Correct pattern.** Before adding an import: (a) check if the source
+package is in the consumer's `package.json` dependencies; (b) if it's
+a relative import within the same package, check for cycles by reading
+the source's imports too.
+
+## 8. Test Expectation Modification
+
+**Anti-pattern.** A test fails; instead of fixing the implementation,
+the worker modifies the test's expected value to match the actual
+output.
+
+**Detection.** Diff modifies `expect(x).toBe(...)` or `toMatchSnapshot()`
+inputs in a test file without corresponding implementation changes.
+
+**Cost.** Test no longer guards the original contract; the regression
+ships silently.
+
+**Correct pattern.** Determine which is wrong — the test or the
+implementation. If the test was wrong (spec changed, contract updated),
+update the test AND the source AND the spec. Never change the test
+alone.
+
+## 9. Worktree Boundary Violation
+
+**Anti-pattern.** Editing files outside the worktree path the spawn
+prompt assigned.
+
+**Detection.** The git shim blocks most operations; if it slips
+through, the change does not land in the PR.
+
+**Cost.** Lost work; integration confusion; potential corruption of
+sibling worker's branch.
+
+**Correct pattern.** First action is `cd <worktree-path>`. All
+subsequent paths SHOULD be absolute within the worktree. Use
+`git rev-parse --show-toplevel` to confirm cwd if uncertain.
+
+## 10. Self-Attestation Without Proof
+
+**Anti-pattern.** "I completed the task" returned to the orchestrator
+without `cleo verify` evidence atoms.
+
+**Detection.** Manifest entry lacks evidence; `cleo show <id>` shows
+gates pending; orchestrator cannot programmatically confirm completion.
+
+**Cost.** Orchestrator must re-verify manually; if the work was not
+actually done, the rollback is much more expensive.
+
+**Correct pattern.** ADR-051 ritual. Every gate gets evidence; verify
+re-validates programmatically. Self-attestation without atoms is
+rejected by the post-ADR-051 system.
+
+## 11. Skipped Memory Observation
+
+**Anti-pattern.** Non-trivial task completed; session ends; nothing
+new in BRAIN.
+
+**Detection.** `cleo memory find <task-topic>` returns no new
+observations from this session.
+
+**Cost.** The next session relearns the same lesson; institutional
+knowledge does not accumulate.
+
+**Correct pattern.** After every non-trivial complete:
+
+```bash
+cleo memory observe "<learning, 1-2 sentences>" --title "<short title>"
+```
+
+The CLEO-INJECTION.md trigger row says this explicitly. Honor it.
+
+## 12. Premature `cleo complete`
+
+**Anti-pattern.** Calling `cleo complete` before all gates have been
+verified, on the theory that the worker can verify in parallel.
+
+**Detection.** Exit code 80 (`E_LIFECYCLE_GATE_FAILED`) or
+`E_EVIDENCE_MISSING`.
+
+**Cost.** Failed complete; worker must back out, re-verify, re-complete.
+
+**Correct pattern.** Verify all six gates first; complete last. The
+verify steps are fast (cached) and idempotent. No reason to skip.

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.