@cleocode/skills 2026.5.83 → 2026.5.86

package/skills/ct-spec-writer/references/traceability-matrix.md

@@ -0,0 +1,145 @@
+# Traceability Matrix
+
+Every REQ in a CLEO spec MUST be traceable to (a) the source justifying
+its existence and (b) the test that verifies its implementation. The
+traceability matrix is the table that makes those links explicit and
+machine-readable. Without it, specs decay — requirements survive
+implementations they no longer reflect.
+
+## Three-Way Trace
+
+A complete trace links three artifacts:
+
+```
+[Source]  ── justifies ──>  [Requirement]  ── verified by ──>  [Test]
+```
+
+- **Source.** The research finding, ADR, user need, or upstream spec that
+  motivates the requirement.
+- **Requirement.** The REQ-NNN entry in this spec.
+- **Test.** The test file/case that exercises the requirement.
+
+Each link MUST be a stable identifier — not prose. "REQ-007 was discussed
+in a meeting" is not a trace; "REQ-007 derives from ADR-065 §3" is.
+
+## The Matrix Block
+
+Include this block in every spec, immediately before the `## Compliance`
+section.
+
+```markdown
+## Traceability
+
+| REQ | Source | Verification |
+|-----|--------|--------------|
+| REQ-001 | ADR-065 §3 | `packages/cleo/__tests__/release-pipeline.test.ts::cuts-from-main-tip` |
+| REQ-002 | ADR-065 §3 | `packages/cleo/__tests__/release-pipeline.test.ts::refuses-direct-push` |
+| REQ-003 | T9580 acceptance | `packages/cleo/__tests__/release-ship.test.ts::epic-completeness-check` |
+| REQ-004 | RFC 7230 §3.2 | `packages/transport/__tests__/http.test.ts::header-canonicalization` |
+| REQ-005 | (TODO: assign source) | (TODO: write test) |
+```
+
+Rows with `(TODO: ...)` are acceptable in `draft` status, NOT in
+`accepted`. A spec cannot move to `accepted` while any TODO row remains.
+
+## Source Token Conventions
+
+The source column accepts these forms:
+
+| Form | Example | When to use |
+|------|---------|-------------|
+| ADR reference | `ADR-065 §3` | Decision recorded in `.cleo/adrs/` |
+| Spec reference | `Spec-foo v1.2 REQ-007` | Inherited from upstream spec |
+| Task reference | `T9580 acceptance` | Direct from task acceptance criteria |
+| Research reference | `.cleo/agent-outputs/2026-05-19_caching.md §Findings` | From research output |
+| External standard | `RFC 7230 §3.2` | IETF / W3C / ISO standard |
+| BRAIN reference | `D003` or `O-mpd07uma-0` | Stored decision or observation |
+| User mandate | `Owner directive 2026-05-19` | Direct from user/owner |
+
+The form `(meeting notes)` or `(slack thread)` is NOT acceptable — these
+are ephemeral and not citable.
+
+## Verification Token Conventions
+
+The verification column accepts these forms:
+
+| Form | Example | Meaning |
+|------|---------|---------|
+| Test ID | `pkg/__tests__/foo.test.ts::case-name` | Unit/integration test exists |
+| Eval ID | `eval-suite-x::scenario-7` | Agent eval covers this REQ |
+| Manual procedure | `docs/qa/manual-release-checklist.md §A` | Human verification step |
+| Tool gate | `pnpm run typecheck` | Toolchain enforces this REQ |
+| Linter rule | `biome.json::rules.style.X` | Linter rule covers this REQ |
+
+A REQ that cannot be verified is not a requirement — it is a wish.
+Reject any REQ that lacks a verification plan during draft review.
+
+## Bidirectional Index
+
+Large specs (more than 30 REQs) SHOULD include a reverse index from test
+back to REQ, so a failing test can be located against its requirement
+quickly.
+
+```markdown
+## Test → REQ Reverse Index
+
+- `release-pipeline.test.ts::cuts-from-main-tip` → REQ-001
+- `release-pipeline.test.ts::refuses-direct-push` → REQ-002
+- `release-ship.test.ts::epic-completeness-check` → REQ-003
+- `http.test.ts::header-canonicalization` → REQ-004
+```
+
+Generate this manually for small specs; large specs SHOULD include a
+script at `scripts/extract-trace.ts` that produces it from the forward
+matrix.
+
+## Trace Health Metrics
+
+A healthy spec has these properties — `ct-validator` reports on them.
+
+| Metric | Healthy | Warning | Failure |
+|--------|---------|---------|---------|
+| REQs without source | 0 | 1-2 | 3+ |
+| REQs without verification | 0 | 1-2 | 3+ |
+| Tests not linked from any REQ | low | 10-25% | 25%+ |
+| External standard refs | present | (n/a) | (n/a) |
+| TODO rows in accepted spec | 0 | (cannot be) | any |
+
+## Drift Detection
+
+When the implementation evolves, the matrix drifts. Detect drift with:
+
+```bash
+# List tests that exist on disk
+find packages -name "*.test.ts" -exec grep -l "REQ-" {} \;
+
+# Compare to REQs claimed in the matrix
+grep "^| REQ-" docs/specs/*.md
+
+# Diff yields:
+# - tests referencing REQs not in any matrix (orphan tests)
+# - matrix REQs whose tests have disappeared (broken trace)
+```
+
+This SHOULD run in CI on `pull_request` touching `docs/specs/**`. The
+existing CI `skills` job (or a new `spec-trace-check` job) is the right
+home — the workflow MUST fail when broken traces appear in `accepted`
+specs.
+
+## Inheritance When Specs Refactor
+
+When Spec-A is superseded by Spec-B, copy the matrix forward and add a
+`Supersedes` column for the legacy REQ ID. This preserves test trace
+across the rename.
+
+```markdown
+| REQ (new) | Supersedes | Source | Verification |
+|-----------|------------|--------|--------------|
+| REQ-001 | Spec-A REQ-007 | ADR-065 §3 | test::cuts-from-main-tip |
+| REQ-002 | Spec-A REQ-008 | ADR-065 §3 | test::refuses-direct-push |
+| REQ-003 | (new) | T9580 | test::epic-completeness-check |
+```
+
+The legacy spec MUST mark itself `deprecated` and link forward to the
+successor. Never delete the legacy spec until all tests have been
+re-attributed.

package/skills/ct-task-executor/SKILL.md

@@ -6,6 +6,10 @@ tier: 2
 core: true
 category: core
 protocol: implementation
+loomStage: implementation
+adrRefs:
+  - ADR-070
+  - ADR-062
 dependencies: []
 sharedResources:
   - subagent-protocol-base
@@ -294,3 +298,24 @@ cleo session gc --include-active
 | Partial deliverables | Missing outputs | Complete all or report partial |
 | Undocumented changes | Lost context | Write detailed output file |
 | Silent failures | Orchestrator unaware | Report via manifest status |
+
+---
+
+## See also / References
+
+This skill binds to the **implementation** LOOM lifecycle stage. Governing ADRs:
+
+- [ADR-070 — three-tier orchestration](../../../../.cleo/adrs/ADR-070-three-tier-orchestration.md) — defines the Worker tier that ct-task-executor occupies.
+- [ADR-062 — worktree merge, not cherry-pick](../../../../.cleo/adrs/ADR-062-worktree-merge-not-cherry-pick.md) — defines the integration path that preserves the executor's commit SHAs end-to-end.
+
+LOOM coverage matrix: [docs/skills/loom-coverage-matrix.md](../../../../docs/skills/loom-coverage-matrix.md).
+
+## See references/
+
+Progressive disclosure — load on demand only:
+
+- `references/implementation-patterns.md` — read-before-write, file-placement, ESM imports, quality-gate sequence
+- `references/acceptance-criteria-mapping.md` — mapping table, AC categories, verification commands
+- `references/evidence-and-gates.md` — ADR-051 atom shape, gate ritual, tool resolution + cache
+- `references/common-failures.md` — twelve observed worker failure modes with corrected approach
+- `references/anti-patterns.md` — instant-rejection patterns from AGENTS.md

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.