@ngockhoale/ukit 2.7.13 → 3.0.0

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 All notable changes to UKit are documented here.
 
 
+## 3.0.0 - 2026-09-23
+
+- Same content as 2.8.0 — re-versioned as a major: the UserLayer/ProjectLayer split plus the new `templates/user/` template set is a breaking-scale change and belongs on 3.x. 2.8.0 is deprecated on npm.
+
+## 2.8.0 - 2026-09-23
+
+- **User-Level `.ukit` layer (cycle C46)**: new `~/.ukit/` layer resolved via `os.homedir()` (correct on Windows/Linux/macOS), immutable on `ukit update` (`level: "user"` manifests + `mergeStrategy: skip`).
+  - Canonical API: `src/core/userPaths.js`, `src/core/memory/{recordStore,userMemory}.js`, `src/core/userPlaybooks.js`.
+  - Merge-per-key precedence: project wins config keys, user wins personal data; `loadRuntimeConfig(projectRoot, {homeDir})` deep-merges defaults←user←project; invalid user-only config warns and falls back to defaults.
+  - Install seeds the user layer (`manifests/platform.user.yaml` + `templates/user/`); router + `route-task.mjs` mirror are user-layer aware; new `ukit playbook` CLI; `ukit memory --user`; doctor user-layer section.
+- **v3 pstack-derived specs**: playbook policies, principle index (15 leaf skills), `modelRoles`, typed verdicts + patch-id currency, decision log (`docs/pstack/SPEC-*.md`, `V3_RESHAPE.md`).
+- **M01.1**: additive `ResolvedTaskRoute` v1 behind `routing.routeSchema.stage` (default `off` = byte-identical legacy route).
+
 ## 2.7.13 - 2026-09-22
 
 - Same content as 2.7.12 (npm staged-publish never completed; re-published as 2.7.13).

package/manifests/documentation.yaml

@@ -330,6 +330,17 @@ entries:
     validation: [manual]
     archive_policy: never
     notes: dir entry — covers all files beneath (handoff lane reports, perf findings)
+  - id: docs-pstack
+    path: docs/pstack/
+    class: canonical
+    audience: [agent, maintainer]
+    owner: product
+    source_of_truth: docs/pstack/
+    merge_strategy: none
+    load_policy: task-routed
+    validation: [manual]
+    archive_policy: never
+    notes: dir entry — pstack→UKit v3 integration corpus, specs, and roadmaps
   - id: docs-archive
     path: docs/archive/
     class: archive

package/manifests/platform.full.yaml

@@ -845,6 +845,188 @@ items:
     packs:
       - core
 
+  # SPEC-principle-index §2.2: 15 principle leaf skills — reference material only
+  # (disable-model-invocation), lazy-loaded by name from the emitted principle index.
+  - id: principle-laziness-protocol-skill
+    type: skill
+    sourceTemplate: .claude/skills/principle-laziness-protocol/SKILL.md
+    targetPath: .claude/skills/principle-laziness-protocol/SKILL.md
+    requires:
+      - core-skill-delivery
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: principle-foundational-thinking-skill
+    type: skill
+    sourceTemplate: .claude/skills/principle-foundational-thinking/SKILL.md
+    targetPath: .claude/skills/principle-foundational-thinking/SKILL.md
+    requires:
+      - core-skill-delivery
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: principle-subtract-before-you-add-skill
+    type: skill
+    sourceTemplate: .claude/skills/principle-subtract-before-you-add/SKILL.md
+    targetPath: .claude/skills/principle-subtract-before-you-add/SKILL.md
+    requires:
+      - core-skill-delivery
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: principle-minimize-reader-load-skill
+    type: skill
+    sourceTemplate: .claude/skills/principle-minimize-reader-load/SKILL.md
+    targetPath: .claude/skills/principle-minimize-reader-load/SKILL.md
+    requires:
+      - core-skill-delivery
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: principle-attack-the-premise-skill
+    type: skill
+    sourceTemplate: .claude/skills/principle-attack-the-premise/SKILL.md
+    targetPath: .claude/skills/principle-attack-the-premise/SKILL.md
+    requires:
+      - core-skill-delivery
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: principle-model-the-domain-skill
+    type: skill
+    sourceTemplate: .claude/skills/principle-model-the-domain/SKILL.md
+    targetPath: .claude/skills/principle-model-the-domain/SKILL.md
+    requires:
+      - core-skill-delivery
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: principle-boundary-discipline-skill
+    type: skill
+    sourceTemplate: .claude/skills/principle-boundary-discipline/SKILL.md
+    targetPath: .claude/skills/principle-boundary-discipline/SKILL.md
+    requires:
+      - core-skill-delivery
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: principle-migrate-callers-then-delete-legacy-apis-skill
+    type: skill
+    sourceTemplate: .claude/skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md
+    targetPath: .claude/skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md
+    requires:
+      - core-skill-delivery
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: principle-prove-it-works-skill
+    type: skill
+    sourceTemplate: .claude/skills/principle-prove-it-works/SKILL.md
+    targetPath: .claude/skills/principle-prove-it-works/SKILL.md
+    requires:
+      - core-skill-delivery
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: principle-fix-root-causes-skill
+    type: skill
+    sourceTemplate: .claude/skills/principle-fix-root-causes/SKILL.md
+    targetPath: .claude/skills/principle-fix-root-causes/SKILL.md
+    requires:
+      - core-skill-delivery
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: principle-sequence-verifiable-units-skill
+    type: skill
+    sourceTemplate: .claude/skills/principle-sequence-verifiable-units/SKILL.md
+    targetPath: .claude/skills/principle-sequence-verifiable-units/SKILL.md
+    requires:
+      - core-skill-delivery
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: principle-test-behavior-not-implementation-skill
+    type: skill
+    sourceTemplate: .claude/skills/principle-test-behavior-not-implementation/SKILL.md
+    targetPath: .claude/skills/principle-test-behavior-not-implementation/SKILL.md
+    requires:
+      - core-skill-delivery
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: principle-guard-the-context-window-skill
+    type: skill
+    sourceTemplate: .claude/skills/principle-guard-the-context-window/SKILL.md
+    targetPath: .claude/skills/principle-guard-the-context-window/SKILL.md
+    requires:
+      - core-skill-delivery
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: principle-never-block-on-the-human-skill
+    type: skill
+    sourceTemplate: .claude/skills/principle-never-block-on-the-human/SKILL.md
+    targetPath: .claude/skills/principle-never-block-on-the-human/SKILL.md
+    requires:
+      - core-skill-delivery
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: principle-encode-lessons-in-structure-skill
+    type: skill
+    sourceTemplate: .claude/skills/principle-encode-lessons-in-structure/SKILL.md
+    targetPath: .claude/skills/principle-encode-lessons-in-structure/SKILL.md
+    requires:
+      - core-skill-delivery
+    mergeStrategy: overwrite_with_backup
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
   - id: agent-handoff-planner
     type: agent
     sourceTemplate: .claude/agents/handoff-planner.md

package/manifests/platform.user.yaml

@@ -0,0 +1,53 @@
+version: 1
+name: ukit-user-layer
+level: user
+autoDiscoverTemplates: false
+description: >
+  UKit user-level manifest. Seeds ~/.ukit/ (resolved via os.homedir()) with personal
+  defaults: ownership README, minimal config, and playbook seeds. Every item is
+  mergeStrategy: skip — seed-once semantics; UKit never overwrites user files.
+
+items:
+  - id: user-readme
+    type: config
+    sourceTemplate: user/README.md
+    targetPath: README.md
+    requires: []
+    mergeStrategy: skip
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: user-config
+    type: config
+    sourceTemplate: user/storage/config.json
+    targetPath: storage/config.json
+    requires: []
+    mergeStrategy: skip
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: user-playbook-bugfix
+    type: config
+    sourceTemplate: user/playbooks/bug-fix.md
+    targetPath: playbooks/bug-fix.md
+    requires: []
+    mergeStrategy: skip
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core
+
+  - id: user-playbook-issue
+    type: config
+    sourceTemplate: user/playbooks/issue-implementation.md
+    targetPath: playbooks/issue-implementation.md
+    requires: []
+    mergeStrategy: skip
+    variables: []
+    enabledByDefault: true
+    packs:
+      - core

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "2.7.13",
+  "version": "3.0.0",
   "description": "Install/update an index-first AI workspace for Claude Code, OpenAI Codex and omp (Oh My Pi).",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,8 @@
     "src/",
     "scripts/",
     "templates/",
+    "!templates/**/.smbdelete*",
+    "!templates/.smbdelete*",
     "CHANGELOG.md",
     "LICENSE",
     "templates/CLAUDE.md",

package/src/cli/commands/diff.js

@@ -36,8 +36,10 @@ export async function runDiff({ packageRoot, projectRoot, packageVersion, argv =
   console.log(`[UKit] Detected packs: ${result.stackContext.detectedPacks.join(', ')}`);
 
   for (const row of result.rows) {
-    const relPath = path.relative(projectRoot, row.targetPath);
-    console.log(`- [${row.action}] ${row.id} -> ${relPath}`);
+    // User-layer rows live under ~/.ukit — outside projectRoot — so a relative
+    // path would be a noisy ../../… chain; print the absolute target instead.
+    const displayPath = row.layer === 'user' ? row.targetPath : path.relative(projectRoot, row.targetPath);
+    console.log(`- [${row.action}] ${row.id} -> ${displayPath}`);
   }
 
   console.log(

package/src/cli/commands/doctor.js

@@ -27,6 +27,9 @@ import { inspectUnattendedMode } from '../../core/unattendedDoctor.js';
 import { inspectPermissions } from '../../core/permissionDoctor.js';
 import { inspectHookChainHealth } from '../../core/hookChainDoctor.js';
 import { findOpencodeArtifacts, opencodeSteerMessage } from '../../core/opencodeSteer.js';
+import { buildUserPaths } from '../../core/userPaths.js';
+import { loadPlaybooks } from '../../core/userPlaybooks.js';
+import { userMemoryStats } from '../../core/memory/userMemory.js';
 
 export const DOCTOR_HELP_FLAGS = new Set(['--help', '-h']);
 const KNOWN_FLAGS = new Set([...DOCTOR_HELP_FLAGS, '--skills', '--gateway', '--docs', '--permissions', '--json']);
@@ -94,7 +97,7 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
   const stack = await detectStack(projectRoot);
   const providers = await detectProviders(projectRoot);
   const installMeta = await readJsonIfExists(pathConfig.installMetaPath);
-  const runtimeConfigInspection = await inspectRuntimeConfig(projectRoot);
+  const runtimeConfigInspection = await inspectRuntimeConfig(projectRoot, { homeDir });
 
   const trackedPaths = Array.isArray(installMeta?.files)
     ? installMeta.files
@@ -288,6 +291,24 @@ export async function runDoctor({ packageRoot, projectRoot, argv = [], homeDir =
   }
   console.log(`[UKit]   ${ok(checks.allProvidersConfigured)}  All providers configured`);
 
+  // FR-011 — user-layer health (~/.ukit). Advisory only: a missing or broken
+  // user layer never fails the project report.
+  const userPaths = buildUserPaths({ homeDir });
+  if (!(await pathExists(userPaths.userRoot))) {
+    console.log('[UKit] User layer: not seeded (run ukit install)');
+  } else {
+    const userConfigState = !runtimeConfigInspection.user.exists
+      ? 'absent'
+      : runtimeConfigInspection.user.parseError
+        ? 'invalid'
+        : 'ok';
+    const userPlaybooks = await loadPlaybooks(userPaths.playbooksDir);
+    const userStats = await userMemoryStats({ homeDir });
+    console.log(
+      `[UKit] User layer: present (${userPaths.userRoot}) | config: ${userConfigState} | playbooks: ${userPlaybooks.size} | memory records: ${userStats.total}`,
+    );
+  }
+
   console.log('[UKit] Project rules checks:');
   for (const check of projectChecks) {
     if (check.applicable === false) continue;

package/src/cli/commands/install.js

@@ -284,6 +284,16 @@ export async function runInstall({ packageRoot, projectRoot, packageVersion, arg
     );
   }
 
+  if (result.userLayer) {
+    if (result.userLayer.error) {
+      console.warn(`[UKit] Warning: user-layer seeding skipped — ${result.userLayer.error}`);
+    } else {
+      console.log(
+        `[UKit] User layer: seeded=${result.userLayer.seeded} kept=${result.userLayer.kept} (${result.userLayer.userRoot})`,
+      );
+    }
+  }
+
   const providerNames = Object.keys(result.providerContext.providers);
   const providerStatus = providerNames
     .map((name) => `${name}=${result.providerContext.providers[name]?.supported ?? 'unknown'}`)

package/src/cli/commands/memory.js

@@ -15,6 +15,15 @@ import {
   stats as v2Stats,
   updateRecord,
 } from '../../core/memory/storeV2.js';
+import {
+  addUserRecord,
+  getUserRecord,
+  loadUserRecords,
+  queryUserRecords,
+  saveUserRecords,
+  updateUserRecord,
+  userMemoryStats,
+} from '../../core/memory/userMemory.js';
 import { runMigration } from '../../core/memory/migrate.js';
 import { getContextInjection, search } from '../../core/memory/retrieval.js';
 import { inspectRuntimeConfig } from '../../core/runtimeConfig.js';
@@ -23,6 +32,7 @@ import { pathExists } from '../../core/fileOps.js';
 import { detectProjectContext } from '../../context/detectProjectContext.js';
 import { listLedgerFiles, LEDGER_DIR_REL } from '../../diagnostics/ledgerFiles.js';
 import fs from 'node:fs/promises';
+import os from 'node:os';
 import path from 'node:path';
 
 const HELP_FLAGS = new Set(['--help', '-h', 'help']);
@@ -180,6 +190,122 @@ async function runMemoryV2(projectRoot, args) {
   throw new Error(`Unknown memory v2 op: ${op}. Expected list|show|promote|stale|migrate.`);
 }
 
+// ---- `ukit memory --user` — user-level store at ~/.ukit (FR-011) ----
+// Same v2 record document, no v1→v2 migration (the user layer starts at v2).
+// Ops: list|add|get|update|forget|stats; an optional `v2` token is accepted so
+// `memory --user v2 add` and `memory --user add` are equivalent. Any other
+// subcommand under --user is a misuse error — v1 lanes stay project-level.
+
+const USER_MEMORY_OPS = new Set(['list', 'add', 'get', 'update', 'forget', 'stats']);
+
+async function runUserMemory(homeDir, args) {
+  const rest = (args[0] ?? '').toLowerCase() === 'v2' ? args.slice(1) : args;
+  const op = (rest[0] ?? 'list').toLowerCase();
+  const opArgs = rest.slice(1);
+
+  if (!USER_MEMORY_OPS.has(op)) {
+    throw new Error(
+      `--user only supports v2 ops (list|add|get|update|forget|stats); got "${op}".`,
+    );
+  }
+
+  if (op === 'list') {
+    const typeFlag = extractFlag(opArgs, '--type');
+    const scopeFlag = extractFlag(typeFlag.rest, '--scope');
+    const statusFlag = extractFlag(scopeFlag.rest, '--status');
+    const records = await queryUserRecords({
+      type: typeFlag.value ?? undefined,
+      scope: scopeFlag.value ?? undefined,
+      status: statusFlag.value ?? undefined,
+    }, { homeDir });
+    if (records.length === 0) {
+      console.log('[UKit] No user memory records found.');
+      return;
+    }
+    for (const record of records) {
+      const scopeLabel = record.project_id ?? record.scope;
+      console.log(`${record.id} [${record.type}/${scopeLabel}/${record.status}] — ${record.text}`);
+    }
+    return;
+  }
+
+  if (op === 'add') {
+    const typeFlag = extractFlag(opArgs, '--type');
+    const scopeFlag = extractFlag(typeFlag.rest, '--scope');
+    const provenanceFlag = extractFlag(scopeFlag.rest, '--provenance');
+    const text = provenanceFlag.rest.join(' ').trim();
+    if (!text) {
+      throw new Error('Missing record text. Usage: ukit memory --user add [--type <type>] [--scope <scope>] <text>');
+    }
+    const record = await addUserRecord({
+      type: typeFlag.value ?? 'derived_fact',
+      scope: scopeFlag.value ?? 'user',
+      text,
+      provenance: provenanceFlag.value ?? 'cli',
+      createdBy: 'cli',
+    }, { homeDir });
+    console.log(`[UKit] Added user record ${record.id}.`);
+    return;
+  }
+
+  if (op === 'get') {
+    const id = opArgs.join(' ').trim();
+    if (!id) {
+      throw new Error('Missing record id. Usage: ukit memory --user get <id>');
+    }
+    const record = await getUserRecord(id, { homeDir });
+    if (!record) {
+      throw new Error(`User memory record not found: ${id}`);
+    }
+    console.log(JSON.stringify(record, null, 2));
+    return;
+  }
+
+  if (op === 'update') {
+    const id = opArgs[0];
+    if (!id) {
+      throw new Error('Missing record id. Usage: ukit memory --user update <id> [--status <s>] [--type <t>] [--scope <s>] [text]');
+    }
+    const statusFlag = extractFlag(opArgs.slice(1), '--status');
+    const typeFlag = extractFlag(statusFlag.rest, '--type');
+    const scopeFlag = extractFlag(typeFlag.rest, '--scope');
+    const text = scopeFlag.rest.join(' ').trim();
+    const patch = {};
+    if (statusFlag.value != null) patch.status = statusFlag.value;
+    if (typeFlag.value != null) patch.type = typeFlag.value;
+    if (scopeFlag.value != null) patch.scope = scopeFlag.value;
+    if (text) patch.text = text;
+    if (Object.keys(patch).length === 0) {
+      throw new Error('Nothing to update. Pass --status/--type/--scope or new text.');
+    }
+    const updated = await updateUserRecord(id, patch, { homeDir });
+    if (!updated) {
+      throw new Error(`User memory record not found: ${id}`);
+    }
+    console.log(`[UKit] Updated user record ${updated.id}.`);
+    return;
+  }
+
+  if (op === 'forget') {
+    const id = opArgs.join(' ').trim();
+    if (!id) {
+      throw new Error('Missing record id. Usage: ukit memory --user forget <id>');
+    }
+    const records = await loadUserRecords({ homeDir });
+    const remaining = records.filter((r) => r.id !== id);
+    if (remaining.length === records.length) {
+      throw new Error(`User memory record not found: ${id}`);
+    }
+    await saveUserRecords(remaining, { homeDir });
+    console.log(`[UKit] Forgot user record ${id}.`);
+    return;
+  }
+
+  // op === 'stats'
+  const stats = await userMemoryStats({ homeDir });
+  console.log(`[UKit] User memory: total=${stats.total} byType=${JSON.stringify(stats.byType)} byStatus=${JSON.stringify(stats.byStatus)} invalidSkipped=${stats.invalidSkipped}`);
+}
+
 // ---- `ukit memory promote` — MEMORY.md `## ukit-learned` lane (SPEC §7a) ----
 
 const LEARNED_START = '<!-- ukit-learned:start -->';
@@ -366,13 +492,19 @@ async function runMemoryEpisode(projectRoot, args) {
   console.log(`[UKit] episode: recorded ${record.id} for session ${sessionId}`);
 }
 
-export async function runMemory({ projectRoot, argv = [] }) {
+export async function runMemory({ projectRoot, homeDir = os.homedir(), argv = [] }) {
+  const userFlagIndex = argv.indexOf('--user');
+  const isUser = userFlagIndex >= 0;
   const runtimePaths = buildRuntimePaths(projectRoot);
-  if (!(await pathExists(runtimePaths.runtimeRoot))) {
+  // --user operates on ~/.ukit and does not require the project runtime.
+  if (!isUser && !(await pathExists(runtimePaths.runtimeRoot))) {
     throw new Error('Shared UKit runtime not found. Run `ukit install` first.');
   }
 
-  const [subcommandRaw, ...rest] = argv;
+  const argvRest = isUser
+    ? [...argv.slice(0, userFlagIndex), ...argv.slice(userFlagIndex + 1)]
+    : argv;
+  const [subcommandRaw, ...rest] = argvRest;
   const subcommand = (subcommandRaw ?? 'list').toLowerCase();
 
   if (HELP_FLAGS.has(subcommand)) {
@@ -380,6 +512,11 @@ export async function runMemory({ projectRoot, argv = [] }) {
     return;
   }
 
+  if (isUser) {
+    await runUserMemory(homeDir, argvRest);
+    return;
+  }
+
   if (subcommand === 'v2') {
     await runMemoryV2(projectRoot, rest);
     return;
@@ -615,4 +752,6 @@ export function printMemoryHelp() {
   console.log('  promote [--dry-run]   Render approved rules/procedures into the ## ukit-learned block in docs/MEMORY.md');
   console.log('  episode [--dry-run] [--session <id>]  Write a session episode record from the exec-ledger');
   console.log('  hygiene [--project <id>]  Run decision-conflict resolution + session archiving now');
+  console.log('  v2 <list|show|promote|stale|migrate>  Operate on the project v2 record store');
+  console.log('  --user [v2] <list|add|get|update|forget|stats>  Operate on the user-level store at ~/.ukit/storage/memory/v2/records.json');
 }

package/src/cli/commands/playbook.js

@@ -0,0 +1,53 @@
+import { listPlaybooks, resolvePlaybook } from '../../core/userPlaybooks.js';
+
+const HELP_FLAGS = new Set(['--help', '-h', 'help']);
+
+export function printPlaybookHelp() {
+  console.log('UKit Playbook Commands');
+  console.log('Usage: ukit playbook <list|show> [args]');
+  console.log('');
+  console.log('Subcommands:');
+  console.log('  list               List resolved playbooks (id | source | lanes)');
+  console.log('  show <id>          Print the resolved playbook body and its source level');
+  console.log('');
+  console.log('Resolution precedence: project (.ukit/playbooks) > user (~/.ukit/playbooks) > builtin.');
+}
+
+export async function runPlaybook({ projectRoot, homeDir, argv = [], builtins } = {}) {
+  const [subcommandRaw, ...rest] = argv;
+  const subcommand = (subcommandRaw ?? 'list').toLowerCase();
+
+  if (HELP_FLAGS.has(subcommand)) {
+    printPlaybookHelp();
+    return;
+  }
+
+  if (subcommand === 'list') {
+    const rows = await listPlaybooks({ projectRoot, homeDir, builtins });
+    if (rows.length === 0) {
+      console.log('No playbooks found (built-ins: bug-fix, issue-implementation)');
+      return;
+    }
+    console.log('id | source | lanes');
+    for (const row of rows) {
+      console.log(`${row.id} | ${row.source} | ${row.lanes.join(', ') || '-'}`);
+    }
+    return;
+  }
+
+  if (subcommand === 'show') {
+    const id = rest[0];
+    if (!id) {
+      throw new Error('Missing playbook id. Usage: ukit playbook show <id>');
+    }
+    const playbook = await resolvePlaybook(id, { projectRoot, homeDir, builtins });
+    if (playbook === null) {
+      throw new Error(`Unknown playbook: ${id}`);
+    }
+    console.log(`source: ${playbook.source}`);
+    console.log(playbook.body);
+    return;
+  }
+
+  throw new Error(`Unknown playbook subcommand: ${subcommand}. Run ukit playbook --help for usage.`);
+}

package/src/cli/index.js

@@ -9,6 +9,7 @@ import { runUpdate } from './commands/update.js';
 import { runCode } from './commands/code.js';
 import { runMetrics } from './commands/metrics.js';
 import { runFeedback } from './commands/feedback.js';
+import { runPlaybook } from './commands/playbook.js';
 
 const GLOBAL_FLAGS = new Set(['--help', '-h', '--version', '-v']);
 
@@ -67,6 +68,11 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     return;
   }
 
+  if (command === 'playbook') {
+    await runPlaybook({ projectRoot, argv: commandArgv });
+    return;
+  }
+
   if (command === 'metrics') {
     await runMetrics({ projectRoot, argv: commandArgv });
     return;
@@ -110,6 +116,7 @@ export async function runCli({ argv, packageRoot, projectRoot, packageVersion })
     console.log('  code               Context compiler surface (peek/search/context/impact)');
     console.log('  status             Show UKit runtime status');
     console.log('  memory             Inspect shared UKit memory');
+    console.log('  playbook           List/show playbooks (project > user > builtin)');
     console.log('  metrics            Telemetry roll-up (route outcomes, failure patterns, memory)');
     console.log('  feedback           Record or list wrong-route feedback labels');
     console.log('  update             Upgrade the global UKit CLI to the latest version');