@cleocode/skills 2026.9.20 → 2026.9.21

package/package.json

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

package/skills/_shared/task-system-integration.md

@@ -120,7 +120,7 @@ When the task system is CLEO, these additional commands are available:
 |---------|---------|
 | `cleo current` | Show current task |
 | `cleo session start` | Begin work session |
-| `cleo session end` | End work session |
+| `cleo session end` | End THIS terminal's session (elsewhere: `--session <id>`; unbound → `E_SESSION_UNBOUND`) |
 | `cleo analyze` | Task triage with scoring |
 | `cleo deps show {{TASK_ID}}` | Check task dependencies |
 | `cleo tree {{EPIC_ID}}` | Visualize hierarchy rooted at epic |

package/skills/ct-adr-recorder/SKILL.md

@@ -6,6 +6,11 @@ loomStage: architecture_decision
 adrRefs:
   - ADR-053
   - ADR-070
+metadata:
+  version: 1.0.0
+  tier: on-demand
+  install: harness
+  stability: stable
 ---
 
 # ADR Recorder

package/skills/ct-artifact-publisher/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: ct-artifact-publisher
 description: "Builds and publishes artifacts to registries (npm, PyPI, cargo, docker, GitHub releases, generic tarballs) following the validate, then dry-run, then build, then publish, then record-provenance pipeline. Invoked by ct-release-orchestrator as a sub-skill when a release has artifact config. Never stores credentials in output or manifest (ARTP-008), always dry-runs first (ARTP-002), halts and attempts rollback on failure (ARTP-009). Triggers when a release config has at least one enabled artifact handler."
+metadata:
+  version: 1.0.0
+  tier: on-demand
+  install: harness
+  stability: stable
 ---
 
 # Artifact Publisher

package/skills/ct-cleo/SKILL.md

@@ -2,8 +2,10 @@
 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.20.6
-  lastReviewed: 2026-09-24
+  version: 2.21.0
+  tier: core
+  install: harness
+  lastReviewed: 2026-09-28
   stability: stable
 ---
 
@@ -25,6 +27,43 @@ Provider reference delivery must be verified or embedded self-contained; static
 instruction checks do not establish live Codex, Claude, or Kimi behavior.
 
 
+## Asking the owner (HITL ask tool)
+
+Whenever you need the owner to answer, decide, approve or choose ANYTHING, use the
+ask tool (`AskUserQuestion` in Claude Code, or the provider equivalent listed in
+CAAMP's `PROVIDER_ASK_TOOLS`) with concrete, detailed, selectable options. Never
+ask inside a response, and never bury a question or decision in prose. Each option
+states what happens and its trade-offs; put the recommended option first. Do not
+send routine status chatter: report only when done or when a decision is needed.
+
+- **Subagents never ask the human.** Return the question with its options to your
+  orchestrator (`blocked` plus `{question, options[{label, description}], recommended}`
+  in the manifest); the orchestrator asks via its ask tool.
+- **No ask tool in the harness:** emit one LAFS `hitl.request` envelope
+  `{question, options[{label, description}], recommended}` and stop.
+
+## Project identity and moving between devices
+
+A project is identified by its portable `project_id` in `.cleo/project-id`
+(tracked, write-once; ADR-094). A path is only a per-device hint, so a moved or
+restored checkout keeps its identity. After a new device, restore or migration,
+or when a known repo reports "Not inside a CLEO project", registry paths are
+unreachable, or nexus hits `ENOENT` on an old path, run and report:
+
+1. `cleo doctor projects` — machine-wide: moved, missing, split and temp rows with
+   remedies. Dry-run by default; `--apply` rebinds only on nonce proof and writes a
+   receipt; `--rollback <id>` restores.
+2. `cleo doctor project-identity` — missing, conflicting or uncommitted id.
+3. `cleo doctor --all-projects` — unreachable registered projects.
+4. `cleo nexus projects clean --orphans --dry-run` — NEVER without `--dry-run`;
+   it deletes rows for projects that merely moved.
+5. `cleo doctor credentials` — credentials still keyed by an old path.
+6. `cleo doctor global-delivery` — `~/.cleo`, the global hub reference and every
+   harness CLEO skill install must resolve (a `~/.cleo` link carried by dotfiles from
+   Linux dangles on macOS and silences all of them). `--repair` relinks with a receipt.
+
+Never delete registry rows for projects that may have moved.
+
 ## Guarded knowledge repair
 
 Use `cleo doctor knowledge --dry-run` to inspect findings and sourced proposals.
@@ -60,13 +99,14 @@ applies reviewed input through the same lifecycle; `--fix --actor AGENT` handles
 confirmed stubs. `cleo doctor repair` retains its separate database-recovery semantics.
 
 <!-- thin-pointer: full protocol is in CLEO-INJECTION.md (T9148) -->
-Full protocol content lives in `~/.cleo/templates/CLEO-INJECTION.md`.
-Emit any section with: `cleo briefing inject --section <name>`
+The always-loaded core is `~/.cleo/templates/CLEO-INJECTION.md`; reference sections ship in the
+package's `CLEO-REFERENCE.md` (T12580). Emit any section with: `cleo briefing inject --section <name>`
 
-Supported sections: `session-start` · `work-loop` · `triggers` · `task-creation`
-· `task-discovery` · `task-relationships` · `session-commands` · `memory` · `nexus`
-· `orchestration` · `playbooks` · `documents` · `error-handling` · `pre-complete-gate`
-· `spawn-tiers` · `rules` · `memory-jit` · `escalation`
+Core: `session-start` · `work-loop` · `triggers` · `session-commands` · `output-contract`
+· `error-handling` · `pre-complete-gate` · `rules` · `escalation`. On demand: `task-creation`
+· `task-discovery` · `task-relationships` · `memory` · `memory-jit` · `data-location` · `nexus`
+· `orchestration` · `playbooks` · `documents` · `human-render` · `spawn-tiers` · `evidence`
+· `projection` · `knowledge-repair`
 
 Task find defaults to lexical query terms. Fuzzy character-subsequence matching requires `--fuzzy`; inspect per-row `match.kind` and `match.fields` before inferring related work. `--in` restricts the source field. Matching mode and fuzzy field explanations survive scalar/human output on stderr. Semantic retrieval remains separately identified.
 
@@ -78,11 +118,35 @@ Use `cleo backup inspect <snapshot> --record-id <id>` for read-only historical e
 
 Code-graph answers (`cleo nexus impact`, `context`, `full-context`, `why`, `search-code`, `task-symbols`, `clusters`, `flows`) carry `meta._nexus.freshness`: stale file count and sample, whether the queried symbol's own file is stale, and the refresh command with an estimated cost. A query refreshes up to 25 stale files inline within a 60 s budget (`nexus.autoRefresh.maxFiles`/`budgetMs`/`enabled`) and discloses it in `freshness.autoRefresh`; beyond that it answers from the stale index with `W_NEXUS_INDEX_STALE`. `unknown` freshness is never fresh. `cleo nexus analyze` re-parses only changed files, re-resolves every file, and reports `mode`, `reason` and per-phase cost; it falls back to a full parse (and says why) when there is no parse cache, the extractor build changed, or over 30% of files changed. `--full` forces a rebuild.
 
+## Sessions are terminal-bound (T12500)
+
+`cleo session start` binds the calling agent process (`CLAUDE_CODE_SESSION_ID`,
+`CODEX_THREAD_ID`, …), pane (`TMUX_PANE`, …) or tab (`TERM_SESSION_ID`, …). Session
+mutations from an unbound caller fail with `E_SESSION_UNBOUND` instead of
+guessing the newest session; bind with `cleo session start`, `cleo session resume
+<id>` or `CLEO_SESSION_ID=<id>`, or name the target with `--session <id>`. CI and
+multi-step scripts must export `CLEO_SESSION_ID`. Unattributed mutations warn on
+stderr; `session status` / `briefing` label a guessed session `unbound: true`.
+
+- A session a human started in a tab is adopted by Claude Code in that tab
+  (also after a Claude restart). An adopter works in it but cannot end it without
+  `--session <id>`, and starting its own session never takes over the tab. A
+  session Claude started can be ended from the tab.
+- Two Claude instances that each start a session stay isolated; a sibling tmux
+  pane never sees another pane's session.
+- Agent-tool subagents inherit the parent's `CLAUDE_CODE_SESSION_ID` and act in
+  the parent's session; `cleo orchestrate spawn` gives workers their own.
+
+## Typed decisions (`cleo decide`, T12491)
+
+`decide` answers typed questions (yes/no, choice, score) through a swappable Jev-wire provider and falls back to local heuristics when unconfigured or failing. It needs two settings, an API URL and a key: `printf %s "$KEY" | cleo decide config --url <u> --key-stdin` (optional `--model`; `--clear` removes them). The key is kept in a 0600 file and never printed. `cleo decide status` probes reachability and `cleo decide ask --state <text> --noul <q>` runs one debug question.
+
 ## Quick Reference
 
 | Need | Command |
 |------|---------|
 | Start session | `cleo session status` → `cleo briefing` |
+| End session (from another terminal) | `cleo session end --session <id>` |
 | Find work | `cleo next` → `cleo focus <id>` |
 | Search tasks | `cleo find "query"` |
 | Complete task | `cleo verify T### --gate ... --evidence "..."` → `cleo complete T###` |
@@ -161,7 +225,7 @@ This internal budget contract does not add a `--token-budget` flag to add/update
 
 ## Skill-Specific Extensions
 
-- Task hierarchy, Saga commands, add-batch decomposition, docs policy, and CLI output details live in CLEO-INJECTION.md; emit `task-creation`, `documents`, and `pre-complete-gate` when needed.
+- Task hierarchy, Saga commands, add-batch decomposition, docs policy, and evidence detail live in the on-demand reference; emit `task-creation`, `documents`, and `evidence` when needed.
 - For add-batch input, The top-level JSON MUST be an array of task objects, not an object wrapper like `{ "tasks": [...] }`.
 - Dry-run count semantics: `/data/count` and `/data/wouldCreate` predict writes; `/data/insertedCount` must be `0` for dry-run.
 - Mutation output paths: use `/data/created/0`, `/data/updated/0`, and `/data/deleted/0`; never parse legacy full records. `--output id` emits affected IDs once in created/updated/deleted order from these canonical arrays.

package/skills/ct-cleo/__tests__/injection-content.test.ts

@@ -41,13 +41,55 @@ const injectionPath = resolve(
 /** Read once — all assertions operate on this string */
 const injectionContent = readFileSync(injectionPath, 'utf-8');
 
+/**
+ * T12580: CLEO-INJECTION.md is the always-loaded core; reference sections
+ * moved to CLEO-REFERENCE.md and are printed on demand with
+ * `cleo briefing inject --section <name>`. Content that moved is asserted
+ * where it now lives AND through the core's pointer table, so the test still
+ * proves an agent can reach it.
+ */
+const referenceContent = readFileSync(
+  resolve(thisDir, '../../../../core/templates/CLEO-REFERENCE.md'),
+  'utf-8',
+);
+
+/** Body of one on-demand section in the reference, or '' when absent. */
+function referenceSection(name: string): string {
+  const open = `<!-- CLEO-INJECTION:section=${name} -->`;
+  const start = referenceContent.indexOf(open);
+  if (start === -1) return '';
+  const end = referenceContent.indexOf(`<!-- /CLEO-INJECTION:section=${name} -->`, start);
+  return end === -1 ? '' : referenceContent.slice(start + open.length, end);
+}
+
+/** Section names the core's "On-demand reference" table points at (first column). */
+function corePointers(): Set<string> {
+  const table = injectionContent.slice(injectionContent.indexOf('## On-demand reference'));
+  const rows = table.slice(0, table.indexOf('\n## ', 5)).split('\n');
+  return new Set(
+    rows
+      .filter((line) => line.startsWith('| `'))
+      .flatMap((line) => [...(line.split('|')[1] ?? '').matchAll(/`([a-z][a-z0-9-]+)`/g)])
+      .map((m) => m[1] as string),
+  );
+}
+
+/** Assert `name` is pointed at by the core AND declared in the reference; return its body. */
+function onDemand(name: string): string {
+  expect(injectionContent).toContain('cleo briefing inject --section <name>');
+  expect(corePointers()).toContain(name);
+  const body = referenceSection(name);
+  expect(body, `reference section ${name}`).not.toBe('');
+  return body;
+}
+
 // ---------------------------------------------------------------------------
 // Required section markers
 // ---------------------------------------------------------------------------
 
 describe('CLEO-INJECTION.md — required section markers', () => {
-  it('contains "Memory Protocol (JIT)" H2 section', () => {
-    expect(injectionContent).toMatch(/^## Memory Protocol \(JIT\)/m);
+  it('delivers "Memory Protocol (JIT)" on demand (core pointer → reference section)', () => {
+    expect(onDemand('memory-jit')).toMatch(/^## Memory Protocol \(JIT\)/m);
   });
 
   it('contains "Escalation" H2 section', () => {
@@ -63,8 +105,10 @@ describe('CLEO-INJECTION.md — required section markers', () => {
     expect(injectionContent).toMatch(/^## Work Loop/m);
   });
 
-  it('contains "Task Discovery" H2 section', () => {
-    expect(injectionContent).toMatch(/^## Task Discovery/m);
+  it('delivers "Task Discovery" on demand, with the discovery quick form in the core', () => {
+    expect(onDemand('task-discovery')).toMatch(/^## Task Discovery/m);
+    expect(injectionContent).toContain('cleo find "query"');
+    expect(injectionContent).toContain('cleo list --parent <id>');
   });
 });
 
@@ -111,17 +155,22 @@ describe('CLEO-INJECTION.md — command correctness', () => {
     expect(injectionContent).toContain('cleo find');
   });
 
-  it('documents add-batch array input and dry-run count fields', () => {
-    expect(injectionContent).toContain('top-level JSON array of task objects');
-    expect(injectionContent).toContain('/data/wouldCreate');
-    expect(injectionContent).toContain('/data/insertedCount');
+  it('documents add-batch array input and dry-run count fields (task-creation, on demand)', () => {
+    const section = onDemand('task-creation');
+    expect(section).toContain('top-level JSON array of task objects');
+    expect(section).toContain('/data/wouldCreate');
+    expect(section).toContain('/data/insertedCount');
   });
 
-  it('documents docs path policy, strict preflight, and runtime doc kinds', () => {
-    expect(injectionContent).toContain('repo-relative paths');
-    expect(injectionContent).toContain('arbitrary external absolute paths');
-    expect(injectionContent).toContain('cleo docs list-types');
-    expect(injectionContent).toContain('DocKindRegistry');
+  it('documents docs path policy, strict preflight, and runtime doc kinds (documents, on demand)', () => {
+    const section = onDemand('documents');
+    expect(section).toContain('repo-relative paths');
+    expect(section).toContain('arbitrary external absolute paths');
+    expect(section).toContain('cleo docs list-types');
+    expect(section).toContain('DocKindRegistry');
+    // The canonical-doc write/read triggers stay in the core.
+    expect(injectionContent).toContain('cleo docs add --type <kind> --slug <kebab-handle>');
+    expect(injectionContent).toContain('cleo docs fetch <slug>');
   });
 
   it('uses contract-backed mutate field paths', () => {

package/skills/ct-cleo/references/session-protocol.md

@@ -38,9 +38,14 @@ ct start T006                  # Start next task
 ```bash
 ct complete <id>               # Complete current
 ct archive                     # Clean up done tasks
-ct session end --note "Progress"
+ct session end --note "Progress"   # this terminal's session; elsewhere: --session <id>
 ```
 
+Sessions are terminal-bound: from a terminal that did not start/resume the
+session, `session end` fails with `E_SESSION_UNBOUND` rather than ending the
+newest session. Bind (`cleo session resume <id>`, `CLEO_SESSION_ID=<id>`) or pass
+`--session <id>`. Scripts and CI must export `CLEO_SESSION_ID`.
+
 ## Research & Manifest Operations
 
 ### Output Requirements

package/skills/ct-codebase-mapper/SKILL.md

@@ -3,7 +3,6 @@ name: ct-codebase-mapper
 version: 1.0.0
 description: Codebase analysis and mapping for autonomous agent understanding. Builds structured maps of project stack, architecture, conventions, testing, integrations, and concerns.
 category: recommended
-tier: 1
 protocol: null
 dependencies: []
 compatibility:
@@ -17,6 +16,11 @@ triggers:
   - understand project
   - brownfield analysis
   - project structure
+metadata:
+  version: 1.0.0
+  tier: on-demand
+  install: harness
+  stability: stable
 ---
 
 # Codebase Mapper

package/skills/ct-consensus-voter/SKILL.md

@@ -6,6 +6,11 @@ loomStage: consensus
 adrRefs:
   - ADR-015
   - ADR-023
+metadata:
+  version: 1.0.0
+  tier: on-demand
+  install: harness
+  stability: stable
 ---
 
 # Consensus Voter

package/skills/ct-contribution/SKILL.md

@@ -7,7 +7,6 @@ description: >-
   "contribution start", "contribution submit", "detect conflicts",
   "weighted consensus", "decision tracking", "conflict resolution".
 version: 1.0.0
-tier: 3
 core: false
 category: meta
 protocol: contribution
@@ -24,6 +23,11 @@ compatibility:
   - windsurf
   - gemini-cli
 license: MIT
+metadata:
+  version: 1.0.0
+  tier: on-demand
+  install: harness
+  stability: stable
 ---
 
 # Contribution Protocol Skill

package/skills/ct-council/SKILL.md

@@ -1,6 +1,11 @@
 ---
 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
+  tier: on-demand
+  install: harness
+  stability: stable
 ---
 
 # The Council

package/skills/ct-dev-workflow/SKILL.md

@@ -2,7 +2,6 @@
 name: ct-dev-workflow
 description: Development workflow orchestration for task-driven development with atomic commits, conventional commit messages, and systematic release processes. Enforces task traceability, branch discipline, smart test scope selection, and GitHub Actions integration. Use when committing code, creating releases, managing branches, or following contribution protocols. Triggers on commit operations, release preparation, or workflow compliance needs.
 version: 3.1.0
-tier: 2
 core: false
 category: specialist
 protocol: contribution
@@ -18,6 +17,8 @@ compatibility:
 license: MIT
 metadata:
   version: 3.1.0
+  tier: core
+  install: harness
   lastReviewed: 2026-09-18
   stability: stable
 ---

package/skills/ct-docs-lookup/SKILL.md

@@ -2,7 +2,6 @@
 name: ct-docs-lookup
 description: This skill should be used when the user asks "how do I configure [library]", "write code using [framework]", "what are the [library] methods", "show me [framework] examples", or mentions libraries like React, Vue, Next.js, Prisma, Supabase, Express, Tailwind, Drizzle, Svelte. Triggers for library setup, configuration, API references, framework code examples, or version-specific docs ("React 19", "Next.js 15").
 version: 1.0.0
-tier: 3
 core: false
 category: composition
 protocol: null
@@ -14,6 +13,11 @@ compatibility:
   - windsurf
   - gemini-cli
 license: MIT
+metadata:
+  version: 1.0.0
+  tier: on-demand
+  install: harness
+  stability: deprecated
 ---
 
 When the user asks about libraries, frameworks, or needs code examples, use Context7 to fetch current documentation instead of relying on training data.

package/skills/ct-docs-review/SKILL.md

@@ -2,7 +2,6 @@
 name: ct-docs-review
 description: This skill should be used when the user asks to "review documentation", "check docs style", "review this markdown file", "check style guide compliance", "review PR documentation", or needs documentation reviewed against the CLEO writing style guide. Supports both local file review and GitHub PR review modes with inline comments.
 version: 1.0.0
-tier: 3
 core: false
 category: composition
 protocol: null
@@ -14,6 +13,11 @@ compatibility:
   - windsurf
   - gemini-cli
 license: MIT
+metadata:
+  version: 1.0.0
+  tier: on-demand
+  install: harness
+  stability: deprecated
 ---
 
 # Documentation Review Skill

package/skills/ct-docs-write/SKILL.md

@@ -2,7 +2,6 @@
 name: ct-docs-write
 description: This skill should be used when creating, editing, or reviewing documentation files (markdown, MDX, README, guides). Use when the user asks to "write docs", "create documentation", "edit the README", "improve doc clarity", "make docs more readable", "follow the style guide", or "write user-facing content". Applies CLEO's conversational, clear, and user-focused writing style.
 version: 1.2.0
-tier: 3
 core: false
 category: composition
 protocol: null
@@ -14,6 +13,11 @@ compatibility:
   - windsurf
   - gemini-cli
 license: MIT
+metadata:
+  version: 1.2.0
+  tier: on-demand
+  install: harness
+  stability: deprecated
 ---
 
 # Documentation Writing Skill

package/skills/ct-documentor/SKILL.md

@@ -1,15 +1,10 @@
 ---
 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.16.0
-tier: 3
+version: 3.16.1
 core: false
 category: specialist
 protocol: null
-metadata:
-  version: 3.16.0
-  lastReviewed: 2026-09-19
-  stability: stable
 dependencies:
   - ct-docs-lookup
   - ct-docs-write
@@ -25,6 +20,12 @@ compatibility:
   - windsurf
   - gemini-cli
 license: MIT
+metadata:
+  version: 3.16.1
+  tier: core
+  install: harness
+  lastReviewed: 2026-09-27
+  stability: stable
 ---
 
 # Documentation Specialist Context Injection
@@ -398,8 +399,10 @@ Per-line opt-out (use sparingly): append
 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:
+directories since the T9791 docs-import cutoff — the commit that
+imported the legacy corpus and committed its manifests under
+`.cleo/audit/imports/`, which is how the sweep locates it — and
+classifies each one against the docs SSoT:
 
 | Remediation | Meaning | Fix |
 |---|---|---|

package/skills/ct-epic-architect/SKILL.md

@@ -2,7 +2,6 @@
 name: ct-epic-architect
 description: Epic planning and task decomposition for breaking down large initiatives into atomic, executable tasks. Provides dependency analysis, wave-based parallel execution planning, hierarchy management, and research linking. Use when creating epics, decomposing initiatives into task trees, planning parallel workflows, or analyzing task dependencies. Triggers on epic creation, task decomposition requests, or planning phase work.
 version: 3.0.0
-tier: 1
 core: false
 category: recommended
 protocol: decomposition
@@ -20,6 +19,11 @@ compatibility:
   - windsurf
   - gemini-cli
 license: MIT
+metadata:
+  version: 3.0.0
+  tier: on-demand
+  install: harness
+  stability: stable
 ---
 
 # Epic Architect Context Injection

package/skills/ct-grade/SKILL.md

@@ -16,7 +16,6 @@ description: >-
 version: 2.1.0
 argument-hint: "[mode=scenario|ab|blind] [scenario=s1-s5|all] [runs=N] [session-id=<id>]"
 allowed-tools: ["Bash(python *)", "Bash(cleo-dev *)", "Bash(cleo *)", "Bash(kill *)", "Bash(lsof *)", "Agent", "Read", "Write", "Glob"]
-tier: 2
 core: false
 category: quality
 protocol: null
@@ -28,6 +27,11 @@ compatibility:
   - windsurf
   - gemini-cli
 license: MIT
+metadata:
+  version: 2.1.0
+  tier: internal
+  install: internal
+  stability: stable
 ---
 
 # Session Grading Guide

package/skills/ct-ivt-looper/SKILL.md

@@ -6,6 +6,11 @@ loomStage: testing
 adrRefs:
   - ADR-051
   - ADR-061
+metadata:
+  version: 1.0.0
+  tier: on-demand
+  install: harness
+  stability: stable
 ---
 
 # IVT Looper

package/skills/ct-lead/SKILL.md

@@ -1,6 +1,11 @@
 ---
 name: ct-lead
 description: "Phase Lead orchestration playbook for spawning and supervising a parallel worker swarm in one wave. Use when spawned by ct-orchestrator with role=orchestrator to fan out N leaf workers via delegate_task, drain the epic-<TID>.wave-<n> conduit topic plus pipeline_manifest, await rollupWaveStatus convergence, and return ONE rolled-up contract string to the parent Orchestrator. Triggers: 'phase lead', 'wave lead', 'supervise wave', 'fan out workers', 'aggregate worker results', 'rollup wave', any task with role=orchestrator that is itself a child of another orchestrator. Implements ADR-070 hierarchical orchestration."
+metadata:
+  version: 1.0.0
+  tier: core
+  install: harness
+  stability: stable
 ---
 
 # Phase Lead Protocol (ct-lead)

package/skills/ct-master-tac/SKILL.md

@@ -11,7 +11,6 @@ description: >-
   "install master tac", "bootstrap protocols", "tools.skill.install ct-master-tac",
   "verify protocol bundle", "repair protocol files", "fresh CleoOS install".
 version: 1.0.0
-tier: 1
 core: false
 category: meta
 protocol: null
@@ -28,6 +27,11 @@ compatibility:
   - gemini-cli
 license: MIT
 install-hook: "tools.skill.install ct-master-tac"
+metadata:
+  version: 1.0.0
+  tier: internal
+  install: internal
+  stability: deprecated
 ---
 
 # ct-master-tac — Master Tactical Bundle

package/skills/ct-master-tac/__tests__/install.test.ts

@@ -49,6 +49,23 @@ function parseFrontmatterKeys(fm: string): Record<string, string> {
   return result;
 }
 
+/**
+ * Read the nested `metadata:` map the way scripts/skills/lib/skill-frontmatter.mjs
+ * does: the indented `key: value` lines directly under a top-level `metadata:`.
+ */
+function parseFrontmatterMetadata(fm: string): Record<string, string> {
+  const result: Record<string, string> = {};
+  const lines = fm.split('\n');
+  const start = lines.findIndex((l) => l.trimEnd() === 'metadata:');
+  if (start === -1) return result;
+  for (const line of lines.slice(start + 1)) {
+    const m = /^\s+([A-Za-z][\w-]*):\s*(.*)$/.exec(line.trimEnd());
+    if (!m) break;
+    result[m[1]] = m[2].replace(/^["']|["']$/g, '');
+  }
+  return result;
+}
+
 // ---------------------------------------------------------------------------
 // Mock install helper for idempotency test
 // ---------------------------------------------------------------------------
@@ -98,15 +115,19 @@ describe('ct-master-tac plugin (T431)', () => {
       expect(fm).not.toBeNull();
     });
 
-    it('frontmatter has required fields: name, description, version, tier', () => {
+    it('frontmatter has required fields: name, description, metadata.version, metadata.tier', () => {
       const content = readFileSync(skillMdPath, 'utf-8');
       const fm = extractFrontmatter(content);
       expect(fm).not.toBeNull();
       const keys = parseFrontmatterKeys(fm!);
       expect(keys['name']).toBe('ct-master-tac');
-      expect(keys['description'] ?? keys['description']).toBeTruthy();
-      expect(keys['version']).toBeTruthy();
-      expect(keys['tier']).toBeTruthy();
+      expect(keys['description']).toBeTruthy();
+      // T12648: version and tier live under `metadata:` (skills SSoT, D11157).
+      const metadata = parseFrontmatterMetadata(fm!);
+      expect(metadata['version']).toMatch(/^\d+\.\d+\.\d+$/);
+      expect(['core', 'on-demand', 'internal']).toContain(metadata['tier']);
+      expect(keys['tier']).toBeUndefined();
+      if (keys['version'] !== undefined) expect(keys['version']).toBe(metadata['version']);
     });
   });
 

package/skills/ct-memory/SKILL.md

@@ -8,6 +8,11 @@ triggers:
   - recall
   - remember
   - anti-hallucination
+metadata:
+  version: 1.0.0
+  tier: internal
+  install: internal
+  stability: deprecated
 ---
 
 # ct-memory -- Brain Memory Protocol