@cleocode/core 2026.8.9 → 2026.9.1

package/templates/CLEO-INJECTION.md

@@ -17,7 +17,7 @@ The ONLY canonical sources of session state are:
 - `cleo briefing` — structured handoff + next tasks + BRAIN context
 - `cleo focus <id>` — **primary orient surface** — single call replacing 8: identity, scope, blockers, ready wave, docs, git activity, brain context (≤ 1 500 tokens)
 - `cleo memory find "<query>"` — BRAIN memory lookup
-- `cleo show <taskId>` — individual task detail (use when you need the raw task record)
+- `cleo show <taskId> --full` — individual task detail. **Use `--full`.** Bare `cleo show` returns an MVI projection that WITHHOLDS `description` and `verification`; withheld fields are named in `_withheld` (field → size), and a record with no `_withheld` key is complete.
 
 If you find yourself reading a markdown file for orientation, STOP. Run `cleo briefing`.
 
@@ -30,7 +30,7 @@ If you find yourself reading a markdown file for orientation, STOP. Run `cleo br
 3. `cleo current` — active task? (~100 tokens)
 4. `cleo next` — what to work on (~300 tokens)
 5. `cleo focus {id}` — **preferred orient call** — single envelope with identity + scope + blockers + ready wave + docs + brain context (≤ 1 500 tokens, replaces 8 calls)
-6. `cleo show {id}` — full task record details when you need the raw record (~400 tokens)
+6. `cleo show {id} --full` — the full task record (~400 tokens). Bare `cleo show {id}` is an MVI projection, NOT the full record — see the `_withheld` note under Task Discovery before you act on a field's absence.
 7. `cleo orchestrate start --epic TXXX` — for epics with ≥ 5 children (~300 tokens, auto-inits LOOM)
 <!-- /CLEO-INJECTION:section=session-start -->
 
@@ -102,7 +102,7 @@ only — dependencies, ordering, cross-reference, evidence, supersession, proven
 |---------|---------|-----|
 | `cleo focus <id>` | ≤ 1 500 | **Primary orient surface** — identity + scope + blockers + ready wave + docs + brain context in ONE call |
 | `cleo find "query"` | 200-400 | Search tasks (default) |
-| `cleo show <id>` | 300-600 | Raw task record (fallback when focus envelope is not sufficient) |
+| `cleo show <id> --full` | 300-600 | Full task record (fallback when focus envelope is not sufficient). Bare `cleo show <id>` WITHHOLDS `description` + `verification` and names them in `_withheld`. **Never read a field's absence as "empty" — check `_withheld` first, or pass `--full`.** A record with no `_withheld` key is complete. |
 | `cleo list --parent <id>` | 1000-5000 | Direct children only |
 <!-- /CLEO-INJECTION:section=task-discovery -->
 
@@ -257,7 +257,7 @@ Path policy: use repo-relative paths inside current repo/worktree — do not att
 <!-- /CLEO-INJECTION:section=documents -->
 <!-- CLEO-INJECTION:section=human-render -->
 ## Human Render Contract (ADR-077)
-Typed `RenderableEnvelope<T>` from `@cleocode/contracts`. `envelope.data.kind` ∈ `tree | table | list | grouped-list | section | single | generic` — agents route on `kind`. Render logic in `packages/core/src/render/`, primitives in `packages/animations/render/`, icon enums in `@cleocode/contracts/render/icon.ts`. Families self-register via `registerRenderer(command, kind, fn)`. Commands: `cleo show T<id>` (typed), `cleo show T<id> --human` (force), `cleo tree T<id>` (generic walk of parent + `groups` edges). Full: `cleo docs fetch adr-077-human-render-contract`.
+Typed `RenderableEnvelope<T>` from `@cleocode/contracts`. `envelope.data.kind` ∈ `tree | table | list | grouped-list | section | single | generic` — agents route on `kind`. Render logic in `packages/core/src/render/`, primitives in `packages/animations/render/`, icon enums in `@cleocode/contracts/render/icon.ts`. Families self-register via `registerRenderer(command, kind, fn)`. Commands: `cleo show T<id>` (typed), `cleo show T<id> --human` (force), `cleo tree T<id>` (generic walk of parent + `groups` edges).
 <!-- /CLEO-INJECTION:section=human-render -->
 
 <!-- CLEO-INJECTION:section=output-contract -->
@@ -267,8 +267,8 @@ Typed `RenderableEnvelope<T>` from `@cleocode/contracts`. `envelope.data.kind`
 
 | Need | Flag | Example |
 |------|------|---------|
-| Scalar extract | `--field <jsonpointer>` | `id=$(cleo add 'X' --acceptance "..." --field /data/created/0)` |
-| ID-only pipeline | `--output id` | `cleo list --parent EPIC --output id \| while read c; do …; done` |
+| Scalar extract | `--field <jsonpointer>` | mutate: `id=$(cleo add 'X' --acceptance "..." --field /data/created/0)` · read: `st=$(cleo show T123 --field /data/task/status)` |
+| ID-only pipeline | `--output id` | `cleo list --parent EPIC --output id --limit 0 \| while read c; do …; done` — **`--limit 0` means EVERY match on BOTH `list` and `find`** (gh#1302, fixed). REQUIRED on `list`, which otherwise stops at 10 silently while `--output count` reports the true total. On `find`, `--all` is the same thing with a name. |
 | Affected count | `--output count` | `cleo list --parent EPIC --status pending --output count` |
 | TSV (no header) | `--output table` | `cleo list --parent EPIC --output table` |
 | Silent (exit-code only) | `--output silent` | `cleo update T123 --status done --output silent` |
@@ -276,7 +276,7 @@ Typed `RenderableEnvelope<T>` from `@cleocode/contracts`. `envelope.data.kind`
 | Suppress stderr | `--quiet` | `cleo add-batch --file f.json --parent T1 --quiet --output id` |
 | Force full record | `--full` | `cleo show T123 --full` |
 
-Mutate ops (`add`, `add-batch`, `update`, `complete`, `delete`) return `{count, created[], updated[], deleted[], ids[]}` by default (T9931). Use contract-backed paths: `/data/created/0` for create/add-batch, `/data/updated/0` for update/complete, `/data/deleted/0` for delete, and `/data/count` for counts. `ids[]` is a deprecated compatibility alias; opt back to full record via `--full`. Anti-patterns (REJECTED): `cleo show … | tail -1 | jq …`, `cleo list … | jq -r '.data.tasks[].id'`, `cleo add 'X' 2>&1 | grep -oE 'T[0-9]+'`. Full contract: `cleo docs fetch adr-086-cli-output-contract-e9`.
+**READ and MUTATE envelopes NEST DIFFERENTLY — the most-guessed-wrong pointer shape.** Mutation envelopes are FLAT (`/data/created/0`); read envelopes nest the record, so `cleo show` needs `/data/task/status`, NEVER `/data/status`. `--field` resolves `description`/`acceptance`/`verification` transparently even under the default projection — no `--full` needed. An unresolvable pointer is a typed `E_FIELD_NOT_FOUND` listing every valid pointer for that op; read it rather than guessing again. `cleo verify`'s own response is SELF-CONFIRMING (it returns the full `verification` object) — do not re-read to check it; if you must, use `--field /data/task/verification`, never `--field /data/task` (MVI-projected, and it made six verified tasks look like no-op writes). Mutate ops (`add`, `add-batch`, `update`, `complete`, `delete`) return `{count, created[], updated[], deleted[], ids[]}` by default (T9931). Use contract-backed paths: `/data/created/0` for create/add-batch, `/data/updated/0` for update/complete, `/data/deleted/0` for delete, and `/data/count` for counts. `ids[]` is a deprecated compatibility alias; opt back to full record via `--full`. Anti-patterns (REJECTED): `cleo show … | tail -1 | jq …`, `cleo list … | jq -r '.data.tasks[].id'`, `cleo add 'X' 2>&1 | grep -oE 'T[0-9]+'`.
 <!-- /CLEO-INJECTION:section=output-contract -->
 
 <!-- CLEO-INJECTION:section=error-handling -->
@@ -298,6 +298,13 @@ Check exit code (`0` = success) and `"success"` in JSON output after every comma
 | — | `E_EVIDENCE_STALE` | Files/commits changed since `verify`; re-verify with updated evidence |
 | — | `E_EVIDENCE_INVALID_DECISION` | `decision:<id>` atom — decision ID not found or not accepted/proposed in BRAIN |
 | — | `E_FLAG_REMOVED` | `cleo complete --force` removed per ADR-051. Use `--evidence` or `CLEO_OWNER_OVERRIDE=1` |
+| — | `E_IDEMPOTENCY_UNSUPPORTED` | That verb ignores `--idempotency-key`; the key was NOT applied. Query before retrying |
+| 143 / 137 | *(killed — no code)* | **A killed write carries NO information about whether it committed** |
+
+### A killed write is not a failed write
+
+A 143/137 exit — or a bare exit with no output — says nothing about whether the mutation landed: the commit is fast, the teardown after it is what hangs, so the row is usually THERE. **Never retry a killed mutation blindly.** Check by id first — `cleo show <id> --full`. A HIT is conclusive even while the writer is still hung (the race can hide a committed row, never invent one); a MISS proves nothing until the writer exits. Searching instead of reading by id needs exact flags, because both read paths hide a row you just wrote (`find` excludes archived; `list` truncates at 10 and new children sort last): `cleo find "<title>" --include-archive --all` and `cleo list --parent <id> --limit 0`. `--idempotency-key` does NOT make a retry safe on `add`/`add-batch`/`update`/`docs add`/`memory observe`/`relates add` — those reject it outright.
+
 <!-- /CLEO-INJECTION:section=error-handling -->
 
 <!-- CLEO-INJECTION:section=pre-complete-gate -->
@@ -307,27 +314,18 @@ MANDATORY before every `cleo complete <id>`. Every gate write MUST be backed by
 
 ### 1. Capture evidence for each gate
 
-```bash
-# implemented — commit + file list (OR decision:<id> for decision-only tasks)
-cleo verify T### --gate implemented \
-  --evidence "commit:<sha>;files:path/a.ts,path/b.ts"
-
-# testsPassed — tool:test (canonical) or test-run:<json>
-cleo verify T### --gate testsPassed --evidence "tool:test"
+Every gate takes `cleo verify T### --gate <gate> --evidence "<atoms>"`:
 
-# qaPassed — lint + typecheck
-cleo verify T### --gate qaPassed --evidence "tool:lint;tool:typecheck"
+| gate | evidence that satisfies it |
+|------|----------------------------|
+| `implemented` | `commit:<sha>;files:path/a.ts,path/b.ts` — or `decision:<id>` for decision-only tasks |
+| `testsPassed` | `tool:test` (canonical) or `test-run:<json>` |
+| `qaPassed` | `tool:lint;tool:typecheck` |
+| `documented` | `files:docs/spec.md` |
+| `securityPassed` | `tool:security-scan` |
+| `cleanupDone` | `note:removed dead branches` |
 
-# retroactive PR atom (PR MERGED + CI green) satisfies implemented + testsPassed + qaPassed
-cleo verify T### --gate implemented --evidence "pr:357"
-cleo verify T### --gate testsPassed --evidence "pr:357"
-cleo verify T### --gate qaPassed --evidence "pr:357"
-
-# documented / securityPassed / cleanupDone
-cleo verify T### --gate documented --evidence "files:docs/spec.md"
-cleo verify T### --gate securityPassed --evidence "tool:security-scan"
-cleo verify T### --gate cleanupDone --evidence "note:removed dead branches"
-```
+A retroactive `pr:<number>` atom (PR MERGED + CI green) satisfies `implemented` + `testsPassed` + `qaPassed` at once — record it against each of the three.
 
 ### 2. Then complete
 
@@ -355,11 +353,11 @@ All overrides append a line to `.cleo/audit/force-bypass.jsonl`. Use sparingly.
 
 ### Tool resolution + result cache (ADR-061)
 
-`tool:<name>` evidence resolves via `.cleo/project-context.json` with per-`primaryType` fallbacks. Results cached under `.cleo/cache/evidence/<key>.json`, keyed on `(canonical, cmd, args, HEAD, dirty-tree fingerprint)`. Parallel verifies coalesce; cross-worktree bounded by per-tool semaphore at `~/.local/share/cleo/locks/tool-<canonical>/`. Tune with `CLEO_TOOL_CONCURRENCY_<TOOL>=<n>`. The wall-clock deadline per tool run defaults to 300000 ms; override with `CLEO_TOOL_TIMEOUT_<TOOL>=<ms>` (positive integer; invalid values are rejected with a clear error, never silently ignored).
+`tool:<name>` evidence resolves via `.cleo/project-context.json` with per-`primaryType` fallbacks. Results cached under `.cleo/cache/evidence/<key>.json`, keyed on `(canonical, cmd, args, HEAD, dirty-tree fingerprint)`. Parallel verifies coalesce; cross-worktree bounded by per-tool semaphore at `~/.local/share/cleo/locks/tool-<canonical>/`. Tune with `CLEO_TOOL_CONCURRENCY_<TOOL>=<n>`. The wall-clock deadline per tool run is per-canonical: **1800000 ms (30 min) for `test` and `build`**, 300000 ms (5 min) for everything else — a suite is not a linter, and a 5 min cap below a real suite meant every run was killed and nothing was ever cached (gh#1221). Override with `CLEO_TOOL_TIMEOUT_<TOOL>=<ms>` (positive integer; invalid values are rejected with a clear error naming the default that applies to THAT tool, never silently ignored). A timed-out run caches nothing, so retrying unchanged fails identically after re-running the whole tool — raise the deadline instead.
 
 ### `pr:<number>` retroactive atom (T9764)
 
-Accepts IFF PR `state=MERGED` AND required-workflow checks are `SUCCESS`/`SKIPPED`. Single atom satisfies `implemented` + `testsPassed` + `qaPassed` simultaneously (T9838). Cache under `.cleo/cache/evidence/pr-<num>.json`.
+Accepts IFF PR `state=MERGED` AND required-workflow checks are `SUCCESS`/`SKIPPED`. Single atom satisfies `implemented` + `testsPassed` + `qaPassed` simultaneously (T9838). Cache under `.cleo/cache/evidence/pr-<num>.json`. **`pr:` is INERT in a repo with no required workflows (gh#1224).** If the project has no `.github/workflows/` — or branch protection lists no required checks — every `pr:` atom is refused with "required gates were not found on this PR", because the checks it looks for never ran. This is exactly the situation in which an agent reaches for `pr:`, so check before you rely on it. Either declare the real check names in `.cleo/project-context.json` → `release.prRequiredWorkflows` (an explicit empty array `[]` means "this repo requires none", and then a MERGED PR alone satisfies the atom), or use `CLEO_PR_REQUIRED_WORKFLOWS`. With neither set, CLEO falls back to a built-in list of ITS OWN gate names (`CI`, `Lockfile Check`, `Contracts Dep Lint`) which will not match your project. In a CI-less repo the honest path is `commit:<sha>;note:<why>` for `implemented` plus `tool:test` / `tool:lint` for the rest.
 
 ### Anti-patterns to avoid
 
@@ -382,23 +380,9 @@ Accepts IFF PR `state=MERGED` AND required-workflow checks are `SUCCESS`/`SKIPPE
 | `1` | tier 0 + full **CLEO-INJECTION.md embed** (this document) — **default** |
 | `2` | tier 1 + **ct-cleo** + **ct-orchestrator** skill excerpts + **SUBAGENT-PROTOCOL-BLOCK** + anti-patterns |
 
-Invoke with an explicit tier:
-
-```bash
-cleo orchestrate spawn T1234 --tier 0   # minimal (quick workers)
-cleo orchestrate spawn T1234            # tier 1 (default)
-cleo orchestrate spawn T1234 --tier 2   # full (autonomous workers)
-```
-
-Every spawn prompt contains these required sections — orchestrators can programmatically assert their presence before dispatching a subagent:
+Invoke with `cleo orchestrate spawn T1234 --tier 0|1|2` — tier 0 for quick workers, tier 2 for autonomous ones; omitting `--tier` gives tier 1.
 
-- `## Task Identity`
-- `## File Paths (absolute — do not guess)`
-- `## Session Linkage`
-- `## Stage-Specific Guidance`
-- `## Evidence-Based Gate Ritual (MANDATORY · ADR-051 · T832)`
-- `## Quality Gates`
-- `## Return Format Contract (MANDATORY)`
+Every spawn prompt contains these required sections, so an orchestrator can programmatically assert their presence before dispatching: `## Task Identity` · `## File Paths (absolute — do not guess)` · `## Session Linkage` · `## Stage-Specific Guidance` · `## Evidence-Based Gate Ritual (MANDATORY · ADR-051 · T832)` · `## Quality Gates` · `## Return Format Contract (MANDATORY)`.
 <!-- /CLEO-INJECTION:section=spawn-tiers -->
 
 <!-- CLEO-INJECTION:section=rules -->

package/dist/backfill/adr-backfill-walker.d.ts

@@ -1,57 +0,0 @@
-/**
- * ADR Backfill Walker — T1829
- *
- * One-time idempotent script that parses every `.cleo/adrs/*.md` (and the 9
- * unique ADRs in `docs/adr/`) and creates a `brain_decisions` row for each one.
- *
- * ## Usage
- *
- * ```bash
- * # Dry-run (no writes):
- * node packages/core/dist/tools/adr-backfill-walker.js --dry-run
- *
- * # Apply (writes to brain.db):
- * node packages/core/dist/tools/adr-backfill-walker.js --apply
- * ```
- *
- * ## Idempotency
- *
- * Rows are skipped when an existing `brain_decisions` row already has
- * `adrNumber` populated for that ADR number.  The check is transactional:
- * `SELECT … WHERE adr_number = ?`.
- *
- * ## Collisions (ADR-051..054)
- *
- * The four ADR numbers 051–054 each have two conflicting files in two
- * different directories. This walker uses `.cleo/adrs/` as the canonical
- * SSoT (per Epsilon audit decision) and SKIPS the `docs/adr/` versions.
- * A note is written to the report for each skipped collision.
- *
- * ## Duplicates (ADR-031/033, ADR-032/034)
- *
- * ADR-033 duplicates ADR-031 and ADR-034 duplicates ADR-032. The first
- * number is kept as canonical; the second is inserted with
- * `supersededBy = <first>` and `confirmationState = 'superseded'`.
- *
- * @task T1829
- * @epic T1824
- */
-interface WalkerResult {
-    adrNumber: number;
-    filename: string;
-    filePath: string;
-    action: 'inserted' | 'skipped-exists' | 'skipped-collision' | 'skipped-error';
-    note?: string;
-    decisionId?: string;
-    supersedureTo?: string;
-}
-/**
- * Main walker function.
- *
- * @param projectRoot - Absolute path to the project root.
- * @param dryRun      - When true, no writes are performed.
- * @returns Array of results per ADR file processed.
- */
-export declare function runAdrBackfillWalker(projectRoot: string, dryRun: boolean): Promise<WalkerResult[]>;
-export {};
-//# sourceMappingURL=adr-backfill-walker.d.ts.map

package/dist/backfill/adr-backfill-walker.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"adr-backfill-walker.d.ts","sourceRoot":"","sources":["../../src/backfill/adr-backfill-walker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AA4SH,UAAU,YAAY;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,UAAU,GAAG,gBAAgB,GAAG,mBAAmB,GAAG,eAAe,CAAC;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,OAAO,GACd,OAAO,CAAC,YAAY,EAAE,CAAC,CAmLzB"}