@cleocode/skills 2026.10.12 → 2026.10.13

package/package.json

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

package/skills/ct-cleo/SKILL.md

@@ -2,14 +2,14 @@
 name: ct-cleo
 description: CLEO task management protocol - session, task, and workflow guidance. Use when managing tasks, sessions, or multi-agent workflows with the CLEO CLI protocol.
 metadata:
-  version: 2.24.11
+  version: 2.24.13
   tier: core
   install: harness
   covers:
     - packages/cleo/src/cli/commands/session.ts
     - packages/cleo/src/cli/commands/focus.ts
     - packages/cleo/src/cli/commands/sticky.ts
-  lastReviewed: 2026-10-10
+  lastReviewed: 2026-10-13
   stability: stable
 ---
 
@@ -463,4 +463,4 @@ BRAIN ID going forward.
 
 ## Evidence must prove task criteria
 
-Merged PRs and passing CI are provenance. Implementation requires changed artifacts related to the task; testing and review require their own actual results (`ci:<pr>` once the PR merged and the project sets `evidence.ciSatisfies`; else `tool:test-affected` when `testing.affectedCommand` is configured, otherwise a targeted `test-run:<json>` or `tool:test`; plan with `cleo done <id> --plan`, never run the suite by hand and again via `tool:test`). Run tests, typechecks and builds one at a time through `cleo run --wait --class <test|build|full-build> -- <cmd>` (exit 75: not admitted yet, wait and retry); never wrap `cleo run` or `cleo verify` in another queue or wrapper, and never raise heap or worker counts (`NODE_OPTIONS`, `--maxWorkers`). For tasks with canonical criteria, append explicit links such as `satisfies:T1234#AC1` to each relevant gate's evidence. Fetch the PR merge commit so artifact hashes can be inspected. A changed criterion invalidates its recorded proof. Completing a child preserves an open parent whose own criteria remain unproven; child waivers never transfer to parent criteria.
+Merged PRs and passing CI are provenance. Implementation requires changed artifacts related to the task; testing and review require their own actual results (`ci:<pr>` once the PR merged and the project sets `evidence.ciSatisfies`; else `tool:test-affected` when `testing.affectedCommand` is configured, otherwise a targeted `test-run:<json>` or `tool:test`; after merge a scoped run carries only while the change's files are byte-identical, or when it is a `test-run:` recorded on a main HEAD descending from the merge, on the current tree, covering the change (T13673); plan with `cleo done <id> --plan`, which never plans a whole-suite `tool:test` itself (T13647); never run the suite by hand and again via `tool:test`). Run tests, typechecks and builds one at a time through `cleo run --wait --class <test|build|full-build> -- <cmd>` (exit 75: not admitted yet, wait and retry); never wrap `cleo run` or `cleo verify` in another queue or wrapper, and never raise heap or worker counts (`NODE_OPTIONS`, `--maxWorkers`). For tasks with canonical criteria, append explicit links such as `satisfies:T1234#AC1` to each relevant gate's evidence. Fetch the PR merge commit so artifact hashes can be inspected. A changed criterion invalidates its recorded proof. Completing a child preserves an open parent whose own criteria remain unproven; child waivers never transfer to parent criteria.

package/skills/ct-council/SKILL.md

@@ -2,7 +2,7 @@
 name: ct-council
 description: Convene "The Council" — a 5-advisor, shuffled gate-based peer-review, chairman-synthesis workflow for reviewing a plan, decision, architecture, or piece of work inside the current project. Use when the user says "convene the council" (or "counsel"), "get the council on this", "council review", "run the five advisors", "stress-test this", "get multiple perspectives", or asks for a rigorous multi-angle challenge of a proposal (Contrarian, First Principles, Expansionist, Outsider, Executor → shuffled peer review with pass/fail gates → convergence detector → Chairman verdict). Operates on the current codebase — each advisor grounds their analysis in actual files/commits before opining. Output is validated by scripts/validate.py.
 metadata:
-  version: 1.0.0
+  version: 1.1.1
   tier: on-demand
   install: harness
   stability: stable
@@ -67,6 +67,7 @@ Every run lives under a run directory (`<run-dir>/`, created by `scripts/run_cou
 | `<run-dir>/phase3.md` | **Orchestrator** (or Chairman agent if delegated) | Phase 3 |
 | `<run-dir>/output.md` | **Orchestrator** (assembled from above) | After Phase 3 |
 | `<run-dir>/verdict.md`, `tldr.md` | **Auto-generated** by `run_council.py ingest` | After validate |
+| CleoDocs store doc (slug `council-run-<run_id>`) | **Auto-written** by `run_council.py ingest` via `cleo docs add`/`cleo docs update` | After validate (T13363 AC2) |
 
 The agent file-write contract: each Phase-1 / Phase-2 subagent must use the `Write` tool to save its full output markdown to the path above and return ONLY a one-line confirmation. The orchestrator does NOT include the agent's full output in its return-context — that bloats the orchestrator window unnecessarily.
 
@@ -295,7 +296,7 @@ The `--title` flag is optional; if omitted the title is auto-derived from the qu
 
 ### Validation + auto-generation
 
-`scripts/run_council.py ingest <run-dir>` validates `output.md`, then automatically writes `verdict.md` and `tldr.md` to the same run dir, then appends a telemetry record to `.cleo/council-runs.jsonl`. Direct usage:
+`scripts/run_council.py ingest <run-dir>` validates `output.md`, then automatically writes `verdict.md` and `tldr.md` to the same run dir, then appends a telemetry record to `.cleo/council-runs.jsonl`, then pushes the assembled `output.md` into the CleoDocs store as a sectioned `note` doc. Direct usage:
 
 ```bash
 # Full output (default)
@@ -306,9 +307,30 @@ python3 scripts/validate.py --phase 0 <phase0.md>  # only H1 + evidence pack
 python3 scripts/validate.py --phase 1 <file.md>    # +5 advisor sections
 python3 scripts/validate.py --phase 2 <file.md>    # +5 peer reviews
 
-python3 scripts/run_council.py ingest <run-dir>  # validate + verdict.md + tldr.md + telemetry
+python3 scripts/run_council.py ingest <run-dir>  # validate + verdict.md + tldr.md + telemetry + store doc
 ```
 
+### Store write (T13363 AC2)
+
+`ingest` also pushes the run's output document into the CleoDocs store so the per-phase
+`##` sections land as CRDT-merged sections instead of only loose files:
+
+- **Slug** — `council-run-<run_id>` (stable per run; re-ingesting the same run updates
+  the same doc instead of creating a new one). The slug is stamped into the INDEX entry
+  as `docs_slug` only when the store write succeeded.
+- **Kind** — `note`; owner is `--owner <id>` if passed, else the `CLEO_SESSION_ID`
+  environment variable, else the session the CLI binds to (`cleo session status`; under
+  Claude Code only `CLAUDE_CODE_SESSION_ID` is set and the CLI resolves it). The markdown
+  is piped via `--content -` (stdin), never argv.
+- **Ordered, non-fatal + additive** — the store write runs after the telemetry record and
+  the INDEX entry are written; those and the raw run dir remain the source of truth. Every
+  `cleo` call has a 60 s timeout. If it fails, times out, or no owner is resolvable,
+  ingest logs a warning and continues. `--no-store` skips the write.
+
+Retrieve a run's doc with `cleo docs fetch council-run-<run_id>`; each re-ingest that
+changes the bytes bumps the doc's version (see the `docVersion` field in the update
+envelope).
+
 The validator **auto-detects partial files** when no `--phase` is passed: if no Phase 3 header is present, it validates up to the highest phase the file contains and prints a stderr suggestion. This prevents the "12 missing-section errors" wall of red when you're checking a phase0.md or phase1-*.md mid-flight.
 
 Exit code 0 = structurally valid. Non-zero = fix the violations before surfacing the verdict.

package/skills/ct-council/scripts/run_council.py

@@ -13,14 +13,22 @@ It does NOT spawn agents itself (the orchestrator does that — see SKILL.md
   3. Validator + telemetry hooks: a validated `output.md` is automatically
      appended to .cleo/council-runs.jsonl with optional --tokens / --wall-clock
      stamps.
-  4. A `--scenario` flag that names the shakedown (1..8) for telemetry
+  4. Store write (T13363 AC2): a validated `output.md` is ALSO pushed into the
+     CleoDocs store as a sectioned `note` doc (slug `council-run-<run_id>`)
+     via `cleo docs add` / `cleo docs update` (idempotent re-ingest updates
+     the same doc). The store write is ADDITIVE and NON-FATAL — the raw run
+     dir + JSONL telemetry remain the audit source of truth.
+  5. A `--scenario` flag that names the shakedown (1..8) for telemetry
      filtering and exit-criteria reporting.
 
 Subcommands:
 
   init <question>          create a new run directory + skeleton phase0 prompt
   validate <run-dir>       run validate.py on the assembled output.md
-  ingest <run-dir>         validate + emit telemetry to the JSONL log
+  ingest <run-dir>         validate + emit telemetry to the JSONL log AND push
+                           output.md into the CleoDocs store (slug
+                           council-run-<run_id>; --no-store to skip,
+                           --owner to override the doc owner)
   list                     show all runs under the configured runs dir
 
 Convention: assemble phase outputs into <run-dir>/output.md by hand or by
@@ -39,6 +47,7 @@ import argparse
 import datetime as _dt
 import hashlib
 import json
+import os
 import re
 import subprocess
 import sys
@@ -234,6 +243,136 @@ def cmd_validate(args) -> int:
     return code
 
 
+# ─── CleoDocs store write (T13363 AC2) ──────────────────────────────────────
+#
+# The run's output document (assembled output.md — one `##` phase per agent)
+# is pushed into the CleoDocs store so concurrent multi-agent edits land as
+# CRDT-merged sections instead of loose files. Raw run artifacts under
+# .cleo/council-runs/ stay the telemetry source of truth; the store write is
+# additive and non-fatal (a failure warns and ingest continues).
+
+def docs_slug_for_run(run_id: str) -> str:
+    """Stable per-run store slug: `council-run-<run_id>` (kebab-case, ≤80 chars)."""
+    return f"council-run-{run_id}"
+
+
+# Bound on every `cleo` subprocess: a hung CLI must never block ingest.
+CLEO_TIMEOUT_SEC = 60
+
+
+def _bound_cleo_session() -> str | None:
+    """The CLEO session the CLI itself binds to (CLAUDE_CODE_SESSION_ID, the
+    terminal, …), read from `cleo session status`. None on any failure."""
+    try:
+        r = subprocess.run(
+            ["cleo", "session", "status", "--field", "/data/session/session/id", "--quiet"],
+            capture_output=True, text=True, timeout=CLEO_TIMEOUT_SEC,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+    sid = (r.stdout or "").strip()
+    return sid if r.returncode == 0 and sid.startswith("ses_") else None
+
+
+def resolve_docs_owner(args) -> str | None:
+    """Owner for the store doc: --owner flag, else CLEO_SESSION_ID, else the
+    session the CLI binds to (`cleo session status`; under Claude Code only
+    CLAUDE_CODE_SESSION_ID is set, and the CLI resolves it).
+
+    Returns None when no owner can be determined — the caller then skips the
+    store write (non-fatal).
+    """
+    owner = getattr(args, "owner", None)
+    if owner:
+        return owner
+    return os.environ.get("CLEO_SESSION_ID") or _bound_cleo_session()
+
+
+def _docs_subprocess_env(owner: str) -> dict:
+    env = dict(os.environ)
+    # Attribute the write to the owning session when the owner IS a session.
+    if owner.startswith("ses_"):
+        env["CLEO_SESSION_ID"] = owner
+    return env
+
+
+def _run_cleo_docs(cmd: list, *, content: str, env: dict) -> subprocess.CompletedProcess:
+    # Content flows via stdin (`--content -`): argv never carries the markdown,
+    # so verdicts of any size are safe from shell-quoting limits.
+    return subprocess.run(
+        cmd, input=content, capture_output=True, text=True, env=env,
+        timeout=CLEO_TIMEOUT_SEC,
+    )
+
+
+def push_run_to_docs_store(
+    *,
+    run_dir: Path,
+    meta: dict,
+    content: str,
+    owner: str,
+) -> bool:
+    """Push output.md into the CleoDocs store as a sectioned `note` doc.
+
+    Idempotent: `cleo docs add` first; on E_SLUG_RESERVED (re-ingest of a
+    known run) falls back to `cleo docs update`, which noops when the bytes
+    are unchanged. Returns True when the doc is in the store; on any failure
+    prints a warning and returns False — NEVER raises into ingest.
+    """
+    rid = meta.get("run_id") or run_dir.name
+    slug = docs_slug_for_run(rid)
+    title = (meta.get("title") or f"Council run {rid}")[:DEFAULT_TITLE_MAX_LEN]
+    question = meta.get("question") or ""
+    desc = f"Council run {rid} — {question} (audit trail: {run_dir})".strip()
+    env = _docs_subprocess_env(owner)
+
+    add_cmd = [
+        "cleo", "docs", "add", owner,
+        "--content", "-",
+        "--type", "note",
+        "--slug", slug,
+        f"--title={title}",  # one token: a title starting with "-" is never a flag
+        "--desc", desc,
+        "--attached-by", "council",
+        "--json",
+    ]
+    try:
+        result = _run_cleo_docs(add_cmd, content=content, env=env)
+    except (OSError, subprocess.TimeoutExpired) as e:
+        print(f"⚠️  Store write skipped — could not run `cleo docs add`: {e}", file=sys.stderr)
+        return False
+
+    if result.returncode == 0:
+        print(f"📦 Verdict doc written to store: slug '{slug}' (owner {owner})", file=sys.stderr)
+        return True
+
+    combined = (result.stdout or "") + (result.stderr or "")
+    if "E_SLUG_RESERVED" not in combined:
+        detail = combined.strip().splitlines()[0] if combined.strip() else f"exit {result.returncode}"
+        print(f"⚠️  Store write failed (`cleo docs add` {slug}): {detail}", file=sys.stderr)
+        return False
+
+    # Re-ingest of a known run: update the existing doc instead.
+    update_cmd = [
+        "cleo", "docs", "update", slug,
+        "--content", "-",
+        "--message", f"council re-ingest {rid}",
+        "--json",
+    ]
+    try:
+        result = _run_cleo_docs(update_cmd, content=content, env=env)
+    except (OSError, subprocess.TimeoutExpired) as e:
+        print(f"⚠️  Store update skipped — could not run `cleo docs update`: {e}", file=sys.stderr)
+        return False
+    if result.returncode == 0:
+        print(f"📦 Verdict doc updated in store: slug '{slug}'", file=sys.stderr)
+        return True
+    combined = (result.stdout or "") + (result.stderr or "")
+    detail = combined.strip().splitlines()[0] if combined.strip() else f"exit {result.returncode}"
+    print(f"⚠️  Store update failed (`cleo docs update` {slug}): {detail}", file=sys.stderr)
+    return False
+
+
 def cmd_ingest(args) -> int:
     run_dir = Path(args.run_dir)
     output_path = run_dir / "output.md"
@@ -331,6 +470,20 @@ def cmd_ingest(args) -> int:
             "wall_clock_seconds": args.wall_clock,
         })
         print(f"📋 INDEX.jsonl updated at {_index_path(runs_dir)}", file=sys.stderr)
+
+    # T13363 AC2 — push the run's output document into the CleoDocs store, AFTER
+    # the telemetry record and the INDEX entry exist (the audit source of truth).
+    # Additive + non-fatal; docs_slug is stamped only when the write succeeded.
+    if not getattr(args, "no_store", False):
+        owner = resolve_docs_owner(args)
+        if owner is None:
+            print(
+                "⚠️  Store write skipped — no owner (pass --owner <id>, set CLEO_SESSION_ID, "
+                "or start a cleo session)",
+                file=sys.stderr,
+            )
+        elif push_run_to_docs_store(run_dir=run_dir, meta=meta, content=md, owner=owner) and meta.get("run_id"):
+            _upsert_index(run_dir.parent, meta["run_id"], {"docs_slug": docs_slug_for_run(meta["run_id"])})
     return 0
 
 
@@ -550,6 +703,15 @@ def main():
     p_ing.add_argument("--log", default=str(DEFAULT_LOG_PATH))
     p_ing.add_argument("--tokens", type=int, default=None)
     p_ing.add_argument("--wall-clock", type=float, default=None)
+    p_ing.add_argument(
+        "--owner", default=None,
+        help="Owner id for the CleoDocs store doc (default: CLEO_SESSION_ID, else the "
+             "session `cleo session status` binds to).",
+    )
+    p_ing.add_argument(
+        "--no-store", action="store_true",
+        help="Skip the CleoDocs store write (T13363 AC2) — raw artifacts only.",
+    )
     p_ing.set_defaults(func=cmd_ingest)
 
     p_list = sub.add_parser("list", help="List runs from INDEX.jsonl.")

package/skills/ct-council/scripts/test_docs_store.py

@@ -0,0 +1,235 @@
+"""Tests for the CleoDocs store write in run_council.py (T13363 AC2).
+
+The store push is additive and non-fatal: these tests mock subprocess.run
+(no real `cleo` binary or store is touched) and prove the invocation shape,
+the idempotent add→update fallback, and that failures never raise into
+ingest.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+SCRIPTS_DIR = Path(__file__).resolve().parent
+sys.path.insert(0, str(SCRIPTS_DIR))
+import run_council  # noqa: E402
+
+CONTENT = "# The Council — retry?\n\n## Phase 1 — advisors\n\n...\n"
+META = {
+    "run_id": "abcdef12",
+    "title": "Retry on timeout",
+    "question": "Should we retry on timeout?",
+}
+RUN_DIR = Path(".cleo/council-runs/20261013T000000-abcdef12")
+
+
+def _completed(cmd, returncode=0, stdout="", stderr=""):
+    return subprocess.CompletedProcess(cmd, returncode, stdout=stdout, stderr=stderr)
+
+
+class TestDocsSlug(unittest.TestCase):
+    def test_slug_scheme(self):
+        self.assertEqual(run_council.docs_slug_for_run("abcdef12"), "council-run-abcdef12")
+
+
+class TestResolveOwner(unittest.TestCase):
+    def test_flag_wins(self):
+        args = mock.Mock(owner="T1234", spec=["owner"])
+        self.assertEqual(run_council.resolve_docs_owner(args), "T1234")
+
+    def test_env_fallback(self):
+        args = mock.Mock(owner=None, spec=["owner"])
+        with mock.patch.dict("os.environ", {"CLEO_SESSION_ID": "ses_x"}, clear=True):
+            self.assertEqual(run_council.resolve_docs_owner(args), "ses_x")
+
+    def test_none_when_unset(self):
+        args = mock.Mock(owner=None, spec=["owner"])
+        with mock.patch.dict("os.environ", {}, clear=True), \
+                mock.patch.object(run_council.subprocess, "run", side_effect=OSError("no cleo")):
+            self.assertIsNone(run_council.resolve_docs_owner(args))
+
+    def test_claude_code_session_only_resolves_through_the_cli(self):
+        # T13658: under Claude Code only CLAUDE_CODE_SESSION_ID is set; the CLI
+        # binds it to a cleo session, which becomes the owner.
+        args = mock.Mock(owner=None, spec=["owner"])
+        with mock.patch.dict("os.environ", {"CLAUDE_CODE_SESSION_ID": "cc-123"}, clear=True), \
+                mock.patch.object(run_council.subprocess, "run") as m:
+            m.return_value = _completed([], returncode=0, stdout="ses_bound\n")
+            self.assertEqual(run_council.resolve_docs_owner(args), "ses_bound")
+        (cmd,), kwargs = m.call_args
+        self.assertEqual(cmd[:3], ["cleo", "session", "status"])
+        self.assertIn("timeout", kwargs)
+
+    def test_hung_session_status_is_none(self):
+        args = mock.Mock(owner=None, spec=["owner"])
+        with mock.patch.dict("os.environ", {}, clear=True), \
+                mock.patch.object(run_council.subprocess, "run",
+                                  side_effect=subprocess.TimeoutExpired(["cleo"], 60)):
+            self.assertIsNone(run_council.resolve_docs_owner(args))
+
+
+class TestPushRunToDocsStore(unittest.TestCase):
+    def _push(self, mock_run, **kwargs):
+        defaults = dict(run_dir=RUN_DIR, meta=dict(META), content=CONTENT, owner="ses_x")
+        defaults.update(kwargs)
+        return run_council.push_run_to_docs_store(**defaults)
+
+    def test_add_invocation_shape(self):
+        with mock.patch.object(run_council.subprocess, "run") as m:
+            m.return_value = _completed([], returncode=0, stdout='{"success":true}')
+            ok = self._push(m)
+        self.assertTrue(ok)
+        (cmd,), kwargs = m.call_args
+        self.assertEqual(cmd[:4], ["cleo", "docs", "add", "ses_x"])
+        self.assertIn("--content", cmd)
+        self.assertEqual(cmd[cmd.index("--content") + 1], "-")  # stdin, never argv
+        self.assertEqual(cmd[cmd.index("--type") + 1], "note")
+        self.assertEqual(cmd[cmd.index("--slug") + 1], "council-run-abcdef12")
+        self.assertEqual(kwargs["input"], CONTENT)  # markdown flows via stdin
+        self.assertEqual(kwargs["env"]["CLEO_SESSION_ID"], "ses_x")
+        self.assertEqual(kwargs["timeout"], run_council.CLEO_TIMEOUT_SEC)
+        self.assertIn("--title=Retry on timeout", cmd)
+
+    def test_dash_title_stays_one_token(self):
+        with mock.patch.object(run_council.subprocess, "run") as m:
+            m.return_value = _completed([], returncode=0)
+            self._push(m, meta={**META, "title": "--force everything"})
+        (cmd,), _ = m.call_args
+        self.assertIn("--title=--force everything", cmd)
+        self.assertNotIn("--force everything", cmd)
+
+    def test_hung_cleo_is_non_fatal(self):
+        with mock.patch.object(run_council.subprocess, "run",
+                               side_effect=subprocess.TimeoutExpired(["cleo"], 60)):
+            self.assertFalse(self._push(mock.Mock()))
+
+    def test_session_env_only_for_session_owner(self):
+        with mock.patch.object(run_council.subprocess, "run") as m:
+            m.return_value = _completed([], returncode=0)
+            with mock.patch.dict("os.environ", {"CLEO_SESSION_ID": "ses_other"}, clear=True):
+                ok = self._push(m, owner="T1234")
+        self.assertTrue(ok)
+        (_,), kwargs = m.call_args
+        self.assertEqual(kwargs["env"]["CLEO_SESSION_ID"], "ses_other")
+
+    def test_slug_reserved_falls_back_to_update(self):
+        reserved = _completed([], returncode=1, stdout='{"success":false,"error":{"codeName":"E_SLUG_RESERVED"}}')
+        updated = _completed([], returncode=0, stdout='{"success":true}')
+        with mock.patch.object(run_council.subprocess, "run") as m:
+            m.side_effect = [reserved, updated]
+            ok = self._push(m)
+        self.assertTrue(ok)
+        self.assertEqual(m.call_count, 2)
+        (cmd,), _ = m.call_args
+        self.assertEqual(cmd[:3], ["cleo", "docs", "update"])
+        self.assertEqual(cmd[3], "council-run-abcdef12")
+        self.assertIn("abcdef12", cmd[cmd.index("--message") + 1])
+
+    def test_add_failure_is_non_fatal(self):
+        with mock.patch.object(run_council.subprocess, "run") as m:
+            m.return_value = _completed([], returncode=1, stdout='{"success":false,"error":{"codeName":"E_BOOM"}}')
+            ok = self._push(m)
+        self.assertFalse(ok)
+        self.assertEqual(m.call_count, 1)  # no update fallback on other errors
+
+    def test_missing_binary_is_non_fatal(self):
+        with mock.patch.object(run_council.subprocess, "run") as m:
+            m.side_effect = OSError("No such file or directory: 'cleo'")
+            ok = self._push(m)
+        self.assertFalse(ok)
+
+    def test_update_failure_is_non_fatal(self):
+        reserved = _completed([], returncode=1, stdout="E_SLUG_RESERVED")
+        failed = _completed([], returncode=1, stderr="boom")
+        with mock.patch.object(run_council.subprocess, "run") as m:
+            m.side_effect = [reserved, failed]
+            ok = self._push(m)
+        self.assertFalse(ok)
+
+    def test_fallback_requires_slug_reserved_marker(self):
+        # A non-reserved add failure must NOT attempt an update.
+        with mock.patch.object(run_council.subprocess, "run") as m:
+            m.return_value = _completed([], returncode=1, stderr="E_VALIDATION")
+            ok = self._push(m)
+        self.assertFalse(ok)
+        self.assertEqual(m.call_count, 1)
+
+
+class TestIngestOrdering(unittest.TestCase):
+    """T13659: telemetry + INDEX are written first; docs_slug only on success."""
+
+    REAL_RUN = staticmethod(subprocess.run)
+
+    def setUp(self):
+        self.tmp = Path(tempfile.mkdtemp(prefix="council-ingest-"))
+        self.run_dir = self.tmp / "runs" / "20261013T000000-abcdef12"
+        self.run_dir.mkdir(parents=True)
+        shutil.copy(SCRIPTS_DIR / "fixtures" / "valid.md", self.run_dir / "output.md")
+        (self.run_dir / "run.json").write_text(json.dumps(META))
+        self.log = self.tmp / "council-runs.jsonl"
+
+    def tearDown(self):
+        shutil.rmtree(self.tmp, ignore_errors=True)
+
+    def _ingest(self, cleo_behaviour):
+        def fake_run(cmd, *a, **kw):
+            if cmd and cmd[0] == "cleo":
+                return cleo_behaviour(cmd)
+            return self.REAL_RUN(cmd, *a, **kw)  # real validate.py / telemetry.py
+
+        args = argparse.Namespace(run_dir=str(self.run_dir), log=str(self.log), tokens=None,
+                                  wall_clock=None, owner="ses_x", no_store=False)
+        with mock.patch.object(run_council.subprocess, "run", side_effect=fake_run) as m:
+            code = run_council.cmd_ingest(args)
+        index = [json.loads(line) for line in (self.tmp / "runs" / "INDEX.jsonl").read_text().splitlines()]
+        return code, m, index[0]
+
+    def _assert_records_written(self, code, entry):
+        self.assertEqual(code, 0)
+        self.assertTrue(self.log.read_text().strip(), "telemetry JSONL record missing")
+        self.assertEqual(entry["status"], "ingested")
+
+    def test_hung_cleo_does_not_block_and_records_still_land(self):
+        def hung(cmd):
+            raise subprocess.TimeoutExpired(cmd, run_council.CLEO_TIMEOUT_SEC)
+        code, _, entry = self._ingest(hung)
+        self._assert_records_written(code, entry)
+        self.assertNotIn("docs_slug", entry)
+
+    def test_failed_write_stamps_no_docs_slug(self):
+        code, _, entry = self._ingest(lambda cmd: _completed(cmd, returncode=1, stderr="E_BOOM"))
+        self._assert_records_written(code, entry)
+        self.assertNotIn("docs_slug", entry)
+
+    def test_skipped_write_stamps_no_docs_slug(self):
+        args_owner = mock.patch.object(run_council, "resolve_docs_owner", return_value=None)
+        with args_owner:
+            code, m, entry = self._ingest(lambda cmd: _completed(cmd, returncode=0))
+        self._assert_records_written(code, entry)
+        self.assertNotIn("docs_slug", entry)
+        self.assertFalse(any(c.args[0][0] == "cleo" for c in m.call_args_list))
+
+    def test_successful_write_runs_last_and_stamps_docs_slug(self):
+        order = []
+
+        def ok(cmd):
+            order.append("cleo")
+            self.assertTrue(self.log.read_text().strip(), "store write ran before telemetry")
+            self.assertTrue((self.tmp / "runs" / "INDEX.jsonl").exists(), "store write ran before INDEX")
+            return _completed(cmd, returncode=0)
+        code, _, entry = self._ingest(ok)
+        self._assert_records_written(code, entry)
+        self.assertEqual(order, ["cleo"])
+        self.assertEqual(entry["docs_slug"], "council-run-abcdef12")
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/ct-documentor/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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. Carries the CLEO writing and review guides as references and coordinates 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.20.0
+version: 3.25.1
 protocol: null
 dependencies:
   - ct-spec-writer
@@ -16,13 +16,13 @@ compatibility:
   - gemini-cli
 license: MIT
 metadata:
-  version: 3.20.0
+  version: 3.25.1
   tier: core
   install: harness
   covers:
     - packages/cleo/src/cli/commands/docs.ts
     - packages/contracts/src/docs-taxonomy.ts
-  lastReviewed: 2026-10-12
+  lastReviewed: 2026-10-14
   stability: stable
 ---
 
@@ -59,12 +59,28 @@ T13361 retired the legacy verbs `search`, `find`, `rank` (use `query`),
 `import`; `sync` stays until the T9645 reingest workflow migrates, and
 `status` stays agent-facing per `cleodocs-rearch-design` §6.
 
+`cleo docs stats` (T13363) is a read-only adoption-metrics probe: add:update
+ratio from the docs audit log, loose-markdown count (gitignore-aware scan),
+`docs_wikilinks` edge count, and live `decision_adr_links` count. Use it for
+pilot baseline comparisons — it never writes.
+
 `cleo docs doctor` (T13447) audits the docs store — dangling `local-file`
 pointers, docVersion skew vs the audit log, empty topics/related_tasks,
 `docs_wikilinks` drift, legacy store surfaces, stale drafts — and with
 `--apply` repairs them after creating a backup automatically. Use it for
 store hygiene checks; it never edits doc content.
 
+`cleo docs migrate` (T13360) imports legacy docs + history into the re-keyed
+conduit store inside the migration safety harness (pre-step backup, verified
+rollback, COMMIT only on full verification). It is additive and idempotent:
+every imported history row is labeled `origin: migrated`, authors come from
+the legacy audit log (or the honest `system:migration` attribution — never
+invented), docs whose content pointers dangle are content-captured or
+recorded dangling in `conduit_doc_migration_ledger`, and a re-run is a
+verified no-op. Legacy slugs that already exist natively are counted as
+native-conflict skips, never clobbered. Run it once per project before the
+T13361/T13362 retirement lands; it needs no `--force`.
+
 For discovery (`find`, `search`, `schema`, `list-types`), prefer `cleo docs list`
 first — it returns slug + owner + type without forcing a filesystem walk. Use
 legacy discovery verbs only when `list` is insufficient.
@@ -173,6 +189,7 @@ Before adding a new doc, ALWAYS ask: is this **a new doc**, **a change to an exi
 - **"Fix a typo in ADR-076 saga-first-class"** - `cleo docs update adr-076-saga-first-class --file /tmp/fixed.md --message "fix typo in §2"` (canonical - T10161). NOT a new doc. NOT a supersession. Just patch in place; T10161 squashes patches within a 5-minute window so consecutive typo fixes don't bloat the audit log.
 - **"Accept a spec that review signed off"** - `cleo docs update <slug> --status accepted` (T12654). `--status` alone changes only the lifecycle status (draft, proposed, accepted, superseded, archived, deprecated); the stored bytes are kept, so there is no need to re-supply `--file` or `--content`. Any content edit without `--status` resets the doc to `draft`.
 - **"Replace a doc's body from a pipe"** - `cat new.md | cleo docs update <slug> --content -` (T13564). As in `docs add`, `-` reads stdin; an empty or bare `-` body is refused, never stored.
+- **"Editing a doc another agent may touch"** - `cleo docs fetch <slug>` first, note `metadata.headVersionUid`, then `cleo docs update <slug> --file new.md --base-version-uid <headVersionUid>` (T13674). A stale base merges append edits into the head (`staleBaseMerged: true`) or records `sectionConflicts` — a concurrent writer's edit is never silently dropped; a base that no longer resolves is refused with `E_DOC_BASE_UNKNOWN`. `--file` must be UTF-8 text when a base is given (`E_DOC_BASE_UNSUPPORTED` otherwise). The update result's `headVersionUid` is the base for your next edit, so chained edits need no re-fetch.
 - **"Trace an ADR to the decisions it ratifies"** - `cleo docs link-decision <adr-slug> D####` (T13598): the slug must be an existing doc and the decision a stored one, since a link is permanent. `cleo docs fetch <adr-slug>` then lists them as `linkedDecisions`. `cleo docs unlink-decision <adr-slug> D####` cannot be undone: the revoke is a permanent tombstone, and that pair can never be re-linked.
 
 - **"Replace the entire saga-orchestration model with v2" (ADVANCED)** - `cleo docs add T9999 v2.md --type adr --slug adr-080-saga-orchestration-v2` followed by `cleo docs supersede adr-073-above-epic-naming adr-080-saga-orchestration-v2 --reason "v2 canonicalizes the SG- prefix + 4-tier hierarchy"`. Both rows survive in the attachments table; readers see `lifecycle_status=superseded` on v1 and `supersedes=adr-073` on v2.

package/skills/ct-lean/SKILL.md

@@ -8,12 +8,13 @@ description: >-
   gates, package boundaries, validation, data safety or anything the task asked for.
 license: MIT
 metadata:
-  version: 1.0.0
+  version: 1.1.0
   tier: core
   install: harness
   covers:
     - packages/core/src/orchestration/lean-change.ts
-  lastReviewed: 2026-10-10
+    - packages/cleo/src/cli/commands/lean.ts
+  lastReviewed: 2026-10-13
   stability: stable
   attribution: Adapted from Ponytail 5.1.0 by DietrichGebert (MIT) — https://github.com/DietrichGebert/ponytail
 ---
@@ -24,6 +25,20 @@ The best code is the code never written. Solve the whole task with the least new
 then end the reply with one or two lines: what you skipped or did not check, and any risk
 the owner must know.
 
+## Levels
+
+| Level | What changes |
+|---|---|
+| `lite` | Build what was asked. When a smaller option fully works, name it in one line and let the owner pick. |
+| `full` | The rules below. Default. |
+| `ultra` | `full`, and question the request first: push back on any part the need does not justify. |
+| `off` | No lean rules. |
+
+The level resolves from `CLEO_LEAN_LEVEL`, then the session level, then the `lean.level`
+config key, then `full`. When the owner asks for a level ("go ultra", "lean off"), set it:
+`cleo lean level ultra --session` for this session, `cleo lean level lite` for the project,
+`--global` for every project. `cleo lean level` alone shows the level and its source.
+
 ## Before you write
 
 Read the task (`cleo show <id> --full`) and the code it touches. List every place the
@@ -65,7 +80,10 @@ callers that stop working, stores it would migrate. That is scope. Extra feature
 ## Never cut
 
 - Validation at trust boundaries, error handling that prevents data loss, security,
+  privacy (one user's data never reaches another, e.g. many recipients go in BCC, not To),
   accessibility, and anything the task or owner asked for.
+- A risk your change creates is part of the change: when the fix is small and in scope,
+  make it, then name it in the reply. Only report a risk you cannot fix in scope.
 - CLEO evidence: every gate gets programmatic evidence (`cleo verify`), never self-attested.
 - Type safety: no `any`, no `as unknown as X`; shared types live in `packages/contracts/`.
 - The package boundary and the `cleo check arch` gates; a smaller diff in the wrong package

package/skills/ct-orchestrator/SKILL.md

@@ -2,13 +2,13 @@
 name: ct-orchestrator
 description: "Pipeline-aware orchestration skill for managing complex workflows through subagent delegation. Use when the user asks to \"orchestrate\", \"orchestrator mode\", \"run as orchestrator\", \"delegate to subagents\", \"coordinate agents\", \"spawn subagents\", \"multi-agent workflow\", \"context-protected workflow\", \"agent farm\", \"HITL orchestration\", \"pipeline management\", or needs to manage complex workflows by delegating work to subagents while protecting the main context window. Enforces ORC-001 through ORC-009 constraints. Provider-neutral — works with any AI agent runtime."
 metadata:
-  version: 4.0.13
+  version: 4.0.15
   tier: core
   install: harness
   covers:
     - packages/cleo/src/cli/commands/orchestrate.ts
     - packages/core/src/orchestration/spawn-prompt.ts
-  lastReviewed: 2026-10-11
+  lastReviewed: 2026-10-13
   stability: stable
 ---
 
@@ -148,6 +148,10 @@ cleo orchestrate spawn T1586 --json
 
 Returns: resolved prompt with base protocol + conditional protocol + task context + all `{{TOKEN}}` placeholders filled.
 
+The prompt's `## Lean Change` block follows the effective ct-lean level (T13663):
+`CLEO_LEAN_LEVEL`, then the spawning session's `cleo lean level --session`, then `lean.level`,
+then `full`. At `off` the block is omitted, so set the level before spawning, not after.
+
 The spawn provisions the worker's worktree, and its `pnpm install` is admitted through the heavy queue or deferred to the worker; the envelope's `install.status` says which. `cleo orchestrate spawn T1586 --no-install` provisions without installing, and the envelope names the command the worker runs instead (T13524).
 
 ### Step 2: Execute (Provider-Specific)
@@ -217,6 +221,25 @@ cleo orchestrate start T1575  # Full state: session, pipeline, next task
 4. Present plan to human for approval
 ```
 
+**Stage output documents go to the store (T13363 AC2).** When a stage finishes its
+output document (research findings, consensus record, spec), keep the working copy at
+`.cleo/rcasd/<epic>/<stage>/` AND push the finished document into the CleoDocs store
+so its `##` sections land as versioned, collaboratively-mergeable sections:
+
+```bash
+# First time — owner is the epic task, kind matches the stage
+cleo docs add T1575 .cleo/rcasd/T1575/research/T1575-research.md \
+  --type research --slug t1575-research
+
+# Re-runs / refreshes update the same doc (noop when bytes are unchanged)
+cleo docs update t1575-research --file .cleo/rcasd/T1575/research/T1575-research.md \
+  --message "research stage refresh"
+```
+
+Retrieve with `cleo docs fetch t1575-research`. The raw stage file stays the working
+copy and gate input; the store doc is the durable sectioned record. Skipping the store
+write is not fatal — but a stage is not "published" until the store doc exists.
+
 ### 3. IVTR — Execute the Work
 
 ```

package/skills/manifest.json

@@ -226,7 +226,7 @@
     },
     {
       "name": "ct-cleo",
-      "version": "2.24.11",
+      "version": "2.24.13",
       "description": "CLEO task management protocol - session, task, and workflow guidance. Use when managing tasks, sessions, or multi-agent workflows with the CLEO CLI protocol.",
       "path": "skills/ct-cleo",
       "tier": 0,
@@ -479,7 +479,7 @@
     },
     {
       "name": "ct-council",
-      "version": "1.0.0",
+      "version": "1.1.1",
       "description": "Convene \"The Council\" — a 5-advisor, shuffled gate-based peer-review, chairman-synthesis workflow for reviewing a plan, decision, architecture, or piece of work inside the current project. Use when the user says \"convene the council\" (or \"counsel\"), \"get the council on this\", \"council review\", \"run the five advisors\", \"stress-test this\", \"get multiple perspectives\", or asks for a rigorous multi-angle challenge of a proposal (Contrarian, First Principles, Expansionist, Outsider, Executor → shuffled peer review with pass/fail gates → convergence detector → Chairman verdict). Operates on the current codebase — each advisor grounds their analysis in actual files/commits before opining. Output is validated by scripts/validate.py.",
       "path": "skills/ct-council",
       "tier": 1,
@@ -642,7 +642,7 @@
     },
     {
       "name": "ct-documentor",
-      "version": "3.20.0",
+      "version": "3.25.1",
       "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. Carries the CLEO writing and review guides as references and coordinates 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.",
       "path": "skills/ct-documentor",
       "tier": 0,
@@ -983,7 +983,7 @@
     },
     {
       "name": "ct-lean",
-      "version": "1.0.0",
+      "version": "1.1.0",
       "description": "Lean change discipline for CLEO work: the smallest change that fully solves the task, and a reply a busy owner understands in one read. Use on every coding task (writing, fixing, refactoring, reviewing, choosing dependencies) and when the owner asks for the simplest solution, YAGNI, or complains about over-engineering or bloat. Never trades away evidence gates, package boundaries, validation, data safety or anything the task asked for.",
       "path": "skills/ct-lean",
       "tier": 0,
@@ -1001,7 +1001,7 @@
     },
     {
       "name": "ct-orchestrator",
-      "version": "4.0.13",
+      "version": "4.0.15",
       "description": "Pipeline-aware orchestration skill for managing complex workflows through subagent delegation. Use when the user asks to \\\"orchestrate\\\", \\\"orchestrator mode\\\", \\\"run as orchestrator\\\", \\\"delegate to subagents\\\", \\\"coordinate agents\\\", \\\"spawn subagents\\\", \\\"multi-agent workflow\\\", \\\"context-protected workflow\\\", \\\"agent farm\\\", \\\"HITL orchestration\\\", \\\"pipeline management\\\", or needs to manage complex workflows by delegating work to subagents while protecting the main context window. Enforces ORC-001 through ORC-009 constraints. Provider-neutral — works with any AI agent runtime.",
       "path": "skills/ct-orchestrator",
       "tier": 0,