@cleocode/skills 2026.5.111 → 2026.5.113

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/skills",
-  "version": "2026.5.111",
+  "version": "2026.5.113",
   "description": "CLEO skill definitions - bundled with CLEO monorepo",
   "main": "index.js",
   "types": "index.d.ts",

package/skills/ct-documentor/SKILL.md

@@ -1,11 +1,15 @@
 ---
 name: ct-documentor
 description: Documentation coordinator with CLEO style guide compliance. Routes every canonical-doc write (spec, adr, research, handoff, note, llm-readme) through the docs SSoT via `cleo docs add` / `cleo docs publish` / `cleo docs fetch` — never raw filesystem writes. Coordinates ct-docs-lookup, ct-docs-write, ct-docs-review, ct-spec-writer, and ct-adr-recorder. Use when creating or updating documentation files, consolidating scattered documentation, or validating documentation against style standards. Triggers on documentation tasks, doc update requests, or style guide compliance checks.
-version: 3.5.0
+version: 3.11.0
 tier: 3
 core: false
 category: specialist
 protocol: null
+metadata:
+  version: 3.11.0
+  lastReviewed: 2026-05-24
+  stability: stable
 dependencies:
   - ct-docs-lookup
   - ct-docs-write
@@ -264,6 +268,222 @@ Contract for the docs-add path:
   `data.slug`, `data.attachmentId`, and `data.sha256` — round-trip
   identical to what `cleo changeset add` emits.
 
+#### CI gate — DocKind Writer Uniqueness (T10369)
+
+`scripts/lint-dockind-writer-uniqueness.mjs` (CI job:
+`DocKind Writer Uniqueness (T10369)`) enforces the
+WriterRegistry invariants at PR-time. It refuses to merge a PR that:
+
+1. Adds a new entry to `BUILTIN_DOC_KINDS` (in
+   `packages/contracts/src/docs-taxonomy.ts`) without a matching
+   descriptor in `writer-registry.ts` (`dockind-coverage-missing`).
+2. Declares more than one descriptor for the same DocKind
+   (`dockind-coverage-collision` — the registry itself throws at module
+   load too, this gate surfaces it earlier in CI).
+3. Has a `mode: 'ssot-first'` descriptor that does NOT match
+   `.cleo/canon.yml`'s `canonicalHome` for the same kind, or vice versa
+   (`canon-yml-ssot-first-drift`).
+4. Adds a NEW raw `writeFileSync(path.md, …)` / `writeFile(path.md, …)`
+   call inside `packages/core/src/**` that is not in
+   `.lint-dockind-writer-baseline.json` (`unregistered-md-write`).
+
+Schema-parity rules (#1-#3) are ALWAYS strict — there is no baseline.
+The unregistered-md-write rule runs in baseline mode by default; count
+decreases always pass, count increases fail. The two legitimate
+non-DocKind `.md` writers (`packages/core/src/sessions/handoff-markdown.ts`
+for session snapshots and `packages/core/src/changesets/writer.ts` for
+the canonical `changeset` DocKind) are allowlisted in the script.
+
+Per-line opt-out (use sparingly): append
+`// dockind-writer-allowed: <reason>` on the writeFile line.
+
+#### Audit complement — manual-write sweep (T10372)
+
+`scripts/sweep-manual-doc-writes.mjs` (CI job:
+`Manual Write Sweep (T10372)`) is the read-only audit counterpart to
+the writer-uniqueness lint. Where T10369 prevents *new* raw `.md`
+writers from landing in `packages/core/src/**`, this sweep walks every
+`*.md` file *already* added under `.cleo/canon.yml`'s `rawMdPaths`
+directories since the T9791 docs-import cutoff (commit `251814e86`)
+and classifies each one against the docs SSoT:
+
+| Remediation | Meaning | Fix |
+|---|---|---|
+| `in-sync` | File SHA matches a blob already in the SSoT — bytes are tracked. | None. |
+| `drift` | Slug exists in SSoT but the on-disk content has changed. | Re-publish via `cleo docs publish` or re-add as a new version. |
+| `orphan` | Neither SHA nor slug resolves — the file is a raw fs write that bypassed `cleo docs add`. | Migrate via `cleo docs add <ownerId> <file> --type <kind> --slug <slug>`. |
+| `deleted` | File was added since the cutoff but no longer exists on disk. | Informational only — does not count toward `unresolved`. |
+
+Each run writes a timestamped report to
+`audit/manual-write-sweep-<date>.json` and prints the summary block to
+stdout. The CI job uploads the report as a workflow artefact on every
+run and is wired with `continue-on-error: true` initially so the
+existing orphan corpus does not break PRs. Saga T10288 / Epic T10293
+E5.3 closes the orphan migration; the gate flips strict after that
+lands.
+
+```bash
+# Local invocation — uses the globally-installed `cleo` on PATH.
+node scripts/sweep-manual-doc-writes.mjs
+
+# CI / monorepo build — point at the just-built local CLI bundle.
+node scripts/sweep-manual-doc-writes.mjs \
+  --cleo-bin "node packages/cleo/dist/cli/index.js" \
+  --allow-unresolved
+```
+
+Exit codes: `0` (clean OR `--allow-unresolved`), `1` (at least one
+`orphan` or `drift` entry), `2` (canon.yml parse failure, git not
+available, SSoT query failed).
+
+### T10179 + T10203 manual-write migration (T10371)
+
+Saga T10176's two known raw-write workarounds are normalised:
+
+| Original file | SSoT slug | Type | Notes |
+|---|---|---|---|
+| `docs/research/t10179-executor-probe-result.md` | `t10179-executor-probe` | research | in-sync via earlier T9791 import — verified by SHA. |
+| `.changeset/t10179-executor-probe.md` (consumed v5.108) | `t10179-changeset-archive` | note | bytes preserved verbatim from git `cc48ca10e`; archived because the pnpm/changesets `"@cleocode/cleo": patch` frontmatter does not satisfy the `changeset` DocKind schema. |
+| `.changeset/t10203-napi-step-exports.md` (consumed v5.108) | `t10203-napi-step-exports` | changeset | in-sync via the `cleo changeset add` dual-write at PR-time. |
+
+Round-trip parity is regression-locked by
+`packages/core/src/docs/__tests__/manual-write-migration.test.ts`. The
+test embeds the canonical bytes inline and asserts that
+`createAttachmentStore().put(...) → findBySlug(...)` returns the same
+SHA-256 it started with. Any future migration that silently rewrites or
+recompresses these blobs fails the test.
+
+### Sweep-driven remediation loop (T10373)
+
+T10371 only covers the *known* manual-write set declared in the original
+Saga T10176 disposition. The T10372 sweep surfaces *every* orphan
+remaining under `rawMdPaths` at the moment it runs. T10373 closes the
+loop by consuming the sweep report and migrating each orphan into the
+SSoT using the same `cleo docs add --slug` pattern T10371 established.
+
+The recurring pattern (use this any time the sweep flags fresh
+orphans):
+
+1. Run the sweep: `node scripts/sweep-manual-doc-writes.mjs`. The
+   report lands at `audit/manual-write-sweep-<date>.json`.
+2. For each `orphan` entry, derive the migration tuple:
+   - `--type` from the file's parent directory (`.cleo/adrs/` → `adr`,
+     `.cleo/research/` → `research`, `.cleo/agent-outputs/` →
+     `handoff` or `note` based on content, `.cleo/rcasd/` → `rcasd`).
+   - `--slug` from the filename — lowercase, kebab-case, no
+     extension (e.g. `ADR-085-cross-db-invariants.md` →
+     `adr-085-cross-db-invariants`).
+   - `<owner-id>` from the file's frontmatter `task:` field if
+     present, otherwise from `cleo find "<filename-keyword>"`.
+3. Run `cleo docs add <ownerId> <file> --type <kind> --slug <slug>
+   --desc "<sweep-remediation context>"`. The `--desc` should
+   reference the originating task ID so future operators can trace
+   the migration.
+4. Verify via `cleo docs fetch <slug>` and re-run the sweep — the
+   `orphan` count MUST drop by the number of files migrated.
+5. Add the new (slug, sha256, type, ownerId) row to a
+   round-trip parity test alongside the T10371 set. The canonical
+   example lives at
+   `packages/core/src/docs/__tests__/sweep-remediation.test.ts`.
+
+T10373 migrated five orphans this way: `ADR-083`, `ADR-085`,
+`T10268-saga-closeout`, `t10292-e4-cli-verb-matrix`, and
+`t10292-e4-sdk-import-edges`. The last two were direct fallout from
+the pre-T10389 worktree-unreachable bug — T10353 and T10354 workers
+fell back to raw filesystem writes because `cleo docs add` rejected
+inside their spawned worktrees. Re-publishing the bytes via the SSoT
+proves the round-trip and closes the loop the bug opened.
+
+If a sweep run surfaces a file that should genuinely stay as raw
+markdown (e.g. an audit log not meant for SSoT propagation), add an
+entry to `audit/sweep-exemptions.yml` rather than migrating it. The
+sweep script honours exemptions and does not flag them as orphans.
+
+### Stuck-saga closure via `cleo saga reconcile` (T10374 · Saga T10288 / Epic T10293)
+
+When a Saga's docs-related closeout was completed under the saga's
+member Epics — every Epic flipped to `status='done'` — but the parent
+Saga row itself is still `pending`, the recovery verb is
+`cleo saga reconcile <sagaId>`. This is the cron-safe T10121 path
+that the ADR-076 / T10113 auto-close path delivers; sagas that pre-date
+the auto-close path (T9625 is the canonical example) need an explicit
+nudge.
+
+The recipe — use this any time a docs-canon Saga is observably stuck
+even though its members have all shipped via `cleo docs add` /
+`cleo docs publish`:
+
+1. Verify member-Epic terminality:
+   `for E in <memberIds>; do cleo show $E | jq '.data.task.status'; done`.
+   Every member must be `done`, `cancelled`, or `archived` before
+   reconcile will close the parent. If any member is genuinely stuck,
+   close THAT one first (evidence-based per ADR-051) — do NOT cancel
+   a member just to satisfy the gate.
+2. Verify the SSoT fetch-gate the Saga's acceptance gates on (typically
+   a research plan or closure note):
+   `cleo docs fetch <slug>` — must return `success: true` with the
+   expected bytes.
+3. Reconcile: `cleo saga reconcile <sagaId>`. The verb is idempotent
+   (re-runs return `action: 'no-op'`) and never modifies member rows.
+4. Confirm: `cleo show <sagaId>` — `status` must be `done` and
+   `completedAt` populated. The action is appended to
+   `.cleo/audit/saga-reconcile.jsonl` for audit.
+5. Write a closure-evidence handoff via
+   `cleo docs add <taskId> <file> --type handoff --slug <saga>-closure-evidence`
+   capturing: member statuses (table), reconcile envelope output,
+   sibling-saga sanity check (no cross-saga side effects), and
+   ADR-076 + T10113 path validation. The slug `t9625-closure-evidence`
+   is the canonical reference.
+
+Regression coverage for this path lives at
+`packages/core/src/sagas/__tests__/t9625-closure.test.ts` and locks
+three invariants: stuck-saga closure (AC1), sibling-saga isolation
+(AC2), and idempotency (AC3). Add a new case there whenever you close
+another stuck docs-canon Saga so the recovery pattern stays under
+test.
+
+### Docs->memory auto-emit (T9976 · regression-tested by T10375)
+
+Every successful `cleo docs add` fires a fire-and-forget memory observation
+into `brain_observations`. The CLI never blocks on this write — a BRAIN
+failure cannot fail `docs add` — but the observation is the bridge that
+makes `cleo memory find '<slug>'` surface attached docs.
+
+**Title shape**: `"Doc attached: <slug>"` (or `"Doc attached: <attachmentId>"`
+when no slug is provided). This is what the FTS index matches on, so the
+slug is also a memory-discovery key — not just a docs-lookup key.
+
+**Narrative payload** (the {@link DocAttachmentObservationPayload} contract):
+
+```jsonc
+{
+  "kind": "doc-attachment",        // discriminator
+  "attachmentId": "<id>",          // assigned by the docs store
+  "ownerId": "<T#### | SG-#### | …>",
+  "slug": "<kebab-slug>",          // omitted only when --slug not passed
+  "type": "<docKind>",             // omitted only when --type not passed
+  "addedAt": "<ISO 8601 timestamp>"
+}
+```
+
+The payload is consumed by `cleo memory verify <observationId>` for
+round-trip checks against the docs store — see AC3 of the original T9976
+suite at `packages/cleo/src/dispatch/domains/__tests__/docs-memory-observation.test.ts`.
+
+**Retroactive sweeps**: when migrating manual `Write`-based docs back into
+the SSoT (the T10371 + T10373 pattern), the auto-emit fires uniformly for
+the kebab-case slugs the sweep uses (`t<num>-<kebab>`, `adr-<num>-<kebab>`).
+Regression coverage lives at
+`packages/cleo/src/dispatch/domains/__tests__/docs-memory-observation-retroactive.test.ts`
+(T10375). Add a new case to that table whenever you discover a slug shape
+not yet under test.
+
+**Anti-pattern**: do NOT write a `cleo memory observe` manually after a
+`cleo docs add` — the auto-emit already happened, and the duplicate
+observation pollutes the FTS index. Use `cleo memory backfill-docs` (AC4
+of T9976) only to repair attachments that pre-date the auto-emit feature
+or were written outside the SSoT.
+
 ### Slug similarity warn (T10361 · closes T10167)
 
 `cleo docs add` runs a fuzzy-match check against existing slugs for the