peaks-loop 4.0.0-beta.10 → 4.0.0-beta.11

package/CHANGELOG.md

@@ -2,20 +2,27 @@
 
 ## [Unreleased]
 
-## 4.0.0-beta.10 — 2026-07-16
+## 4.0.0-beta.11 — 2026-07-16
 
-### Status: PRE-IMPLEMENTATION
+### Status: RELEASED (release of `4.0.0-beta.10` contract; same source tree)
 
-> **This CHANGELOG entry documents the CONTRACT for 4.0.0-beta.10.
-> The 3 slices below are NOT YET IMPLEMENTED in this branch.**
-> See `docs/release/4.0.0-beta.10.md` for the user-facing runbook
-> and `peaks workflow verify-pipeline --rid 2026-07-15-cli-surface-cleanup`
-> for the pre-implementation gate (9/9 gates PASS).
+> **This CHANGELOG entry documents the SHIPPED 4.0.0-beta.11.
+> It is the post-implementation release of the 4.0.0-beta.10 contract
+> documented at `docs/release/4.0.0-beta.10.md` (runbook filename
+> preserved for cross-reference stability).
 >
-> **Ship path**: user implements Slices 1+2+3 per the runbook,
-> runs `pnpm test:full` + manual AC verification, then runs
-> `npm publish --tag beta`. No code change is included in the
-> sediment/version-bump commit that produced this CHANGELOG.
+> The 3 slices (del-minimax-worker, hide-role-skills, on-demand-ecc)
+> all landed PASS in this branch — see `peaks workflow verify-pipeline
+> --rid 2026-07-15-cli-surface-cleanup` and the Slice 1/2/3 sediment
+> memories in `.peaks/memory/`.
+>
+> **Version bump rationale** (D-016): 4.0.0-beta.10 was the pre-impl
+> contract name; 4.0.0-beta.11 is the actual release of that contract.
+> One-line summary: **"CLI surface cleanup + on-demand ECC"**.
+>
+> **Verdict**: 10/12 AC PASS + 2 PASS-WITH-DEFERRED (D-013 wrapper
+> exit-code bug, separate follow-up slice after publish).
+> Ice-cola baseline gate: 27/27 AC functionally pass.
 
 ### Removed — `peaks minimax-worker` (Slice 1)
 

package/dist/cli/cli-helpers.d.ts

@@ -2,8 +2,6 @@ import { Command } from 'commander';
 import { getErrorMessage, ok, redactSensitiveErrorMessage, type ResultEnvelope } from '../shared/result.js';
 import type { ArtifactProvider, GuidedArtifactSetup } from '../services/artifacts/artifact-service.js';
 import type { ConfigLayer } from '../services/config/config-service.js';
-import type { MiniMaxProviderSmokeResult } from '../services/providers/minimax-provider-service.js';
-import type { MiniMaxWorkerResult } from '../services/providers/minimax-worker-service.js';
 import type { RecommendationWorkflow } from '../services/recommendations/recommendation-service.js';
 export type ProgramIO = {
     stdout: (text: string) => void;
@@ -34,10 +32,7 @@ export declare function isRecommendationWorkflow(value: string): value is Recomm
 export declare function isArtifactProvider(value: string): value is ArtifactProvider;
 export declare function isArtifactSetupStep(value: string): value is GuidedArtifactSetup['step'];
 export declare function isArtifactRepoSegment(value: string): boolean;
-export declare function isMiniMaxHttpsUrl(value: string): boolean;
 export declare function parseConfigLayer(value: string | undefined): ConfigLayer | undefined | null;
 export declare function printInvalidConfigLayer(io: ProgramIO, command: string, asJson?: boolean): void;
 export declare function multipleOption(value: string, previous: string[]): string[];
-export declare function summarizeMiniMaxSmokeResult(result: MiniMaxProviderSmokeResult): MiniMaxProviderSmokeResult;
-export declare function summarizeMiniMaxWorkerResult(result: MiniMaxWorkerResult): MiniMaxWorkerResult;
 export { getErrorMessage, ok, redactSensitiveErrorMessage };

package/dist/cli/cli-helpers.js

@@ -1,5 +1,4 @@
 import { fail, getErrorMessage, ok, redactSensitiveErrorMessage } from '../shared/result.js';
-const MINIMAX_API_HOST = 'api.minimaxi.com';
 export function printResult(io, result, asJson = false) {
     if (asJson) {
         io.stdout(JSON.stringify(result, null, 2));
@@ -47,15 +46,6 @@ export function isArtifactSetupStep(value) {
 export function isArtifactRepoSegment(value) {
     return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value) && !value.includes('..') && !value.endsWith('.');
 }
-export function isMiniMaxHttpsUrl(value) {
-    try {
-        const url = new URL(value);
-        return url.protocol === 'https:' && url.hostname === MINIMAX_API_HOST && url.username.length === 0 && url.password.length === 0 && url.search.length === 0 && url.hash.length === 0;
-    }
-    catch {
-        return false;
-    }
-}
 export function parseConfigLayer(value) {
     if (value === undefined) {
         return undefined;
@@ -69,18 +59,4 @@ export function printInvalidConfigLayer(io, command, asJson) {
 export function multipleOption(value, previous) {
     return [...(previous || []), value];
 }
-export function summarizeMiniMaxSmokeResult(result) {
-    return { ...result, responseText: null, summary: null };
-}
-export function summarizeMiniMaxWorkerResult(result) {
-    const provider = summarizeMiniMaxSmokeResult(result.provider);
-    return {
-        ...result,
-        provider,
-        reviewHandoff: {
-            model: result.reviewHandoff.model,
-            prompt: '[redacted]'
-        }
-    };
-}
 export { getErrorMessage, ok, redactSensitiveErrorMessage };

package/dist/cli/commands/audit-commands.js

@@ -49,7 +49,7 @@ function validateProjectRoot(projectArg) {
 }
 export function registerAuditCommands(program, io) {
     const audit = program
-        .command('audit')
+        .command('audit', { hidden: true })
         .description('Audit a project for compliance with peaks-loop red lines (P0 / P1 / P2 tiers)');
     addJsonOption(audit
         .command('red-lines')

package/dist/cli/commands/capability-worker-config-sc-commands.js

@@ -1,10 +1,8 @@
 import { registerCapabilityCommands } from './capability-commands.js';
 import { registerConfigCommands } from './config-commands.js';
 import { registerSCCommands } from './sc-commands.js';
-import { registerWorkerCommands } from './worker-commands.js';
 export function registerCapabilityWorkerConfigAndSCCommands(program, io) {
     registerCapabilityCommands(program, io);
-    registerWorkerCommands(program, io);
     registerConfigCommands(program, io);
     registerSCCommands(program, io);
 }

package/dist/cli/commands/code-commands.js

@@ -108,7 +108,7 @@ export async function runCodeFast(opts) {
  */
 export function registerCodeCommands(program, io) {
     const code = program
-        .command('code')
+        .command('code', { hidden: true })
         .description('peaks-code LLM-side workflow planner (slice 2 fast mode)');
     code
         .command('plan')

package/dist/cli/commands/code-review-commands.js

@@ -4,7 +4,7 @@ import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { fail, ok } from '../../shared/result.js';
 export function registerCodeReviewCommands(program, io) {
     const codeReview = program
-        .command('code-review')
+        .command('code-review', { hidden: true })
         .description('Code-review primitives for peaks-rd Gate B3. Wraps the soft-optional `@alibaba-group/open-code-review` (ocr) tool when it is installed + configured; peaks-rd uses the structured JSON output as a second-opinion review alongside its own LLM review. ocr is a peerDependency of peaks-loop 2.8.2+ (was briefly promoted to a hard dependency in 2.0.1/2.0.2, then demoted to optionalDependencies 2.0.3+ — peer in 2.8.2 because its postinstall downloads a Go binary via HTTPS and would otherwise slow `npm i -g peaks-loop` in restricted environments). Install manually with `npm i -g @alibaba-group/open-code-review` if you want second-opinion reviews. LLM endpoint config lives under `peaksConfig.ocr.llm` in the user config — run `peaks code-review config-template` to see the JSON snippet to paste.');
     addJsonOption(codeReview
         .command('detect-ocr')

package/dist/cli/commands/config-commands.js

@@ -1,15 +1,13 @@
 import { executeMigration, planMigration } from '../../services/config/config-migration.js';
-import { getConfig, getMiniMaxProviderConfig, getMiniMaxProviderStatus, isSensitiveConfigPath, redactConfigSecrets, setConfig, setMiniMaxProviderConfig } from '../../services/config/config-service.js';
+import { getConfig, isSensitiveConfigPath, redactConfigSecrets, setConfig } from '../../services/config/config-service.js';
 import { listAvailableFields, restoreField } from '../../services/config/config-restore.js';
 import { executeRollback, planRollback } from '../../services/config/config-rollback.js';
-import { testMiniMaxProvider } from '../../services/providers/minimax-provider-service.js';
 import { fail, ok } from '../../shared/result.js';
-import { addJsonOption, getErrorMessage, isMiniMaxHttpsUrl, parseConfigLayer, printInvalidConfigLayer, printResult, redactSensitiveErrorMessage, summarizeMiniMaxSmokeResult } from '../cli-helpers.js';
+import { addJsonOption, getErrorMessage, parseConfigLayer, printInvalidConfigLayer, printResult } from '../cli-helpers.js';
 export function registerConfigCommands(program, io) {
     const config = program.command('config').description('Manage Peaks configuration');
     registerConfigGetSetCommands(config, io);
     registerConfigMigrationCommands(config, io);
-    registerMiniMaxProviderCommands(config, io);
 }
 function registerConfigGetSetCommands(config, io) {
     addJsonOption(config.command('get').description('Get current config or a specific key').option('--key <path>', 'dot-notation key path').option('--layer <layer>', 'user or project')).action((options) => {
@@ -137,7 +135,7 @@ function registerConfigMigrationCommands(config, io) {
 function printConfigSetError(io, error, asJson) {
     const message = getErrorMessage(error);
     if (message === 'Sensitive config keys must be stored in the user config layer') {
-        printResult(io, fail('config.set', 'SECRET_CONFIG_REQUIRES_USER_LAYER', message, {}, ['Use --layer user or peaks config provider minimax set']), asJson);
+        printResult(io, fail('config.set', 'SECRET_CONFIG_REQUIRES_USER_LAYER', message, {}, ['Use --layer user for sensitive config keys']), asJson);
         process.exitCode = 1;
         return;
     }
@@ -146,75 +144,6 @@ function printConfigSetError(io, error, asJson) {
         process.exitCode = 1;
         return;
     }
-    if (message === 'MiniMax base URL must be the MiniMax HTTPS endpoint without embedded credentials') {
-        printResult(io, fail('config.set', 'INVALID_MINIMAX_BASE_URL', message, {}, ['Use a MiniMax Anthropic-compatible HTTPS endpoint']), asJson);
-        process.exitCode = 1;
-        return;
-    }
     printResult(io, fail('config.set', 'CONFIG_SET_FAILED', message, {}, ['Check the config key and layer, then retry']), asJson);
     process.exitCode = 1;
 }
-function registerMiniMaxProviderCommands(config, io) {
-    const minimaxProvider = config.command('provider').description('Manage model provider settings').command('minimax').description('Manage MiniMax provider settings');
-    addJsonOption(minimaxProvider.command('set').description('Set MiniMax provider settings in user config').option('--base-url <url>', 'MiniMax Anthropic-compatible base URL')).action((options) => {
-        const baseUrl = options.baseUrl?.trim();
-        const apiKey = process.env.MINIMAX_API_KEY?.trim();
-        if (!baseUrl && !apiKey) {
-            printResult(io, fail('config.provider.minimax.set', 'MINIMAX_PROVIDER_NO_VALUES', 'Provide --base-url and set MINIMAX_API_KEY', {}, ['Export MINIMAX_API_KEY and rerun peaks config provider minimax set --base-url <url>']), options.json);
-            process.exitCode = 1;
-            return;
-        }
-        if (baseUrl && !isMiniMaxHttpsUrl(baseUrl)) {
-            printResult(io, fail('config.provider.minimax.set', 'INVALID_MINIMAX_BASE_URL', 'MiniMax base URL must be the MiniMax HTTPS endpoint without embedded credentials', {}, ['Use a MiniMax Anthropic-compatible HTTPS endpoint']), options.json);
-            process.exitCode = 1;
-            return;
-        }
-        try {
-            const input = {};
-            if (baseUrl)
-                input.baseUrl = baseUrl;
-            if (apiKey)
-                input.apiKey = apiKey;
-            const status = setMiniMaxProviderConfig(input);
-            printResult(io, ok('config.provider.minimax.set', status), options.json);
-        }
-        catch (error) {
-            printMiniMaxProviderSetError(io, error, options.json);
-        }
-    });
-    addJsonOption(minimaxProvider.command('get').description('Show redacted MiniMax provider settings')).action((options) => {
-        const configValue = getMiniMaxProviderConfig();
-        const status = getMiniMaxProviderStatus();
-        printResult(io, ok('config.provider.minimax.get', { ...redactConfigSecrets(configValue, 'providers.minimax'), ...status }), options.json);
-    });
-    addJsonOption(minimaxProvider.command('status').description('Show MiniMax provider configuration status')).action((options) => {
-        printResult(io, ok('config.provider.minimax.status', getMiniMaxProviderStatus()), options.json);
-    });
-    addJsonOption(minimaxProvider.command('test').description('Run a redacted MiniMax provider smoke test').option('--model <model>', 'model name for the smoke test', 'MiniMax-M2.7')).action(async (options) => {
-        try {
-            const result = await testMiniMaxProvider(getMiniMaxProviderConfig(), { model: options.model });
-            const safeResult = summarizeMiniMaxSmokeResult(result);
-            if (!result.configured) {
-                printResult(io, fail('config.provider.minimax.test', 'MINIMAX_PROVIDER_NOT_CONFIGURED', 'MiniMax provider requires baseUrl and apiKey in user config', safeResult, ['Export MINIMAX_API_KEY or set MINIMAX_API_KEY']), options.json);
-                process.exitCode = 1;
-                return;
-            }
-            printResult(io, result.ok ? ok('config.provider.minimax.test', safeResult) : fail('config.provider.minimax.test', 'MINIMAX_PROVIDER_TEST_FAILED', 'MiniMax provider smoke test failed', safeResult, ['Check the MiniMax base URL, API key, and model name']), options.json);
-            if (!result.ok)
-                process.exitCode = 1;
-        }
-        catch (error) {
-            printResult(io, fail('config.provider.minimax.test', 'MINIMAX_PROVIDER_TEST_FAILED', redactSensitiveErrorMessage(getErrorMessage(error)), {}, ['Check network connectivity and MiniMax provider settings']), options.json);
-            process.exitCode = 1;
-        }
-    });
-}
-function printMiniMaxProviderSetError(io, error, asJson) {
-    if (getErrorMessage(error) === 'MiniMax base URL must be the MiniMax HTTPS endpoint without embedded credentials') {
-        printResult(io, fail('config.provider.minimax.set', 'INVALID_MINIMAX_BASE_URL', 'MiniMax base URL must be the MiniMax HTTPS endpoint without embedded credentials', {}, ['Use a MiniMax Anthropic-compatible HTTPS endpoint']), asJson);
-        process.exitCode = 1;
-        return;
-    }
-    printResult(io, fail('config.provider.minimax.set', 'MINIMAX_PROVIDER_SET_FAILED', getErrorMessage(error), {}, ['Check MiniMax provider settings and retry']), asJson);
-    process.exitCode = 1;
-}

package/dist/cli/commands/core/skill-command.js

@@ -20,8 +20,11 @@ import { addJsonOption, getErrorMessage, printResult } from '../../cli-helpers.j
 import { registerSkillSearchCommand } from '../skill-search-commands.js';
 export function registerSkillCommand(program, io) {
     const skill = program.command('skill').description('Manage Peaks skills');
-    addJsonOption(skill.command('list').description('List skills derived from skills/*/SKILL.md')).action(async (options) => {
-        const skills = await listSkills();
+    addJsonOption(skill.command('list').description('List skills derived from skills/*/SKILL.md').option('--include-internal', 'include skills with visibility: internal (default: hide them)')).action(async (options) => {
+        let skills = await listSkills();
+        if (options.includeInternal !== true) {
+            skills = skills.filter((s) => s.visibility !== 'internal');
+        }
         if (options.json === true) {
             printResult(io, ok('skill.list', { skills }), true);
         }

package/dist/cli/commands/dispatch-commands.js

@@ -78,6 +78,20 @@ export function registerDispatchCommand(parent, io) {
             process.exitCode = 1;
             return;
         }
+        // Slice 3 (on-demand-ecc) D-012: the `agent` role was removed in
+        // 4.0.0-beta.11 — there is no longer a subprocess path for it
+        // (the upstream ECC v2.0.0 ships no `ecc` binary). This guard
+        // sits AFTER role validation but BEFORE the missing-prompt
+        // check so an action-path dispatch with a valid prompt still
+        // returns a clear ROLE_REMOVED envelope + exit 1. Note that
+        // Commander short-circuits `--help` BEFORE `.action()` fires,
+        // so `peaks sub-agent dispatch agent --help` continues to
+        // exit 0 with the help text — that is intentional, not a bug.
+        if (role === 'agent') {
+            printResult(io, fail('sub-agent.dispatch', 'ROLE_REMOVED', 'The agent role was removed in Slice 3', { role, reason: 'role-removed-in-slice-3', toolCall: null, dispatchRecordPath: null }, []), asJson);
+            process.exitCode = 1;
+            return;
+        }
         if (!options.prompt || options.prompt.length === 0) {
             printResult(io, fail('sub-agent.dispatch', 'MISSING_PROMPT', '--prompt is required when --from-dag is not provided', { role, toolCall: null, dispatchRecordPath: null }, [
                 'Re-run with either:',

package/dist/cli/commands/ecc-commands.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `peaks ecc install|status|ls|show` — Slice 3 of 4.0.0-beta.11.
+ *
+ * Drop-in replacement for the deleted `peaks agent run|list`
+ * surface. The pre-Slice-3 implementation shelled out to
+ * `npx ecc agent run ...`, but the upstream `affaan-m/everything-claude-code`
+ * v2.0.0 release has NO `ecc` binary — the repo is `agents/*.md`
+ * flat files plus SKILL.md descriptors.
+ *
+ * The new flow:
+ *   - `peaks ecc install [--ref <tag>]` downloads the ECC tarball
+ *     into `~/.peaks/cache/ecc-<sha>/agents/` (selective extract,
+ *     agents/*.md only).
+ *   - `peaks ecc status` reports the cache manifest state.
+ *   - `peaks ecc ls` lists cached agents from `<cache>/agents/*.md`,
+ *     parsing YAML frontmatter (with D-009 fallback to filename +
+ *     first body line when frontmatter is malformed).
+ *   - `peaks ecc show <name> [--section H] [--max-lines N]` prints
+ *     the SKILL.md body to stdout — this is the Skill-first path
+ *     the LLM consumes directly.
+ *
+ * The `--section` filter extracts a single H1 (`# heading`)
+ * through the next H1 — useful when the SKILL.md is large.
+ *
+ * Per the "Enhancement, not new AI CLI" tenet: this command is a
+ * download + read-only access layer. There is no `peaks ecc run`.
+ */
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerEccCommands(program: Command, io: ProgramIO): void;

package/dist/cli/commands/ecc-commands.js

@@ -0,0 +1,119 @@
+import { downloadToCache, listCachedAgents, readAgentSkill, readCacheManifest, } from '../../services/agent/ecc-cache-service.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from '../../shared/result.js';
+export function registerEccCommands(program, io) {
+    const ecc = program
+        .command('ecc')
+        .description('affaan-m/everything-claude-code cache: download + read-only access for the LLM (no subprocess; no peaks agent run).');
+    addJsonOption(ecc
+        .command('install')
+        .description('Download affaan-m/ECC to ~/.peaks/cache/ecc-<sha>/ (selective extract: agents/ subtree only).')
+        .option('--ref <tag>', 'release tag (default: latest)')).action(async (options) => {
+        const asJson = options.json === true;
+        try {
+            const result = await downloadToCache(options.ref !== undefined && options.ref.length > 0 ? { ref: options.ref } : {});
+            const envelope = ok('ecc.install', result, [], [
+                `Cache landed at ~/.peaks/cache/ecc-${result.sha}/agents/`,
+                `Inspect with: peaks ecc ls`,
+                `Consume one agent with: peaks ecc show <name>`,
+            ]);
+            printResult(io, envelope, asJson);
+        }
+        catch (error) {
+            const message = getErrorMessage(error);
+            printResult(io, fail('ecc.install', 'FETCH_FAILED', message, { ref: options.ref ?? 'latest' }, [
+                'Network failure during ECC download. Manual fallback:',
+                '  git clone https://github.com/affaan-m/everything-claude-code.git',
+                '  Copy <repo>/agents/*.md into ~/.peaks/cache/ecc-<sha>/agents/.',
+                '  Drop a minimal ecc-installed.json manifest into ~/.peaks/cache/.',
+            ]), asJson);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(ecc
+        .command('status')
+        .description('Show ECC cache state (version, sha, fetchedAt, agent count).')).action((options) => {
+        const asJson = options.json === true;
+        const manifest = readCacheManifest();
+        if (manifest === null) {
+            printResult(io, fail('ecc.status', 'NO_CACHE', 'No ECC cache found. Run `peaks ecc install` first.', { installed: false }, ['Run `peaks ecc install [--ref <tag>]` to populate ~/.peaks/cache/ecc-<sha>/agents/.']), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        printResult(io, ok('ecc.status', manifest, [], [
+            `Inspect agents with: peaks ecc ls`,
+            `Print one agent with: peaks ecc show <name>`,
+        ]), asJson);
+    });
+    addJsonOption(ecc
+        .command('ls')
+        .description('List cached agents from <cache>/agents/*.md with parsed frontmatter.')).action((options) => {
+        const asJson = options.json === true;
+        const agents = listCachedAgents();
+        printResult(io, ok('ecc.ls', { agents }, [], [
+            'Print one with: `peaks ecc show <name>`',
+        ]), asJson);
+    });
+    addJsonOption(ecc
+        .command('show <name>')
+        .description('Print agent SKILL.md to stdout (LLM-consumable; Skill-first path).')
+        .option('--section <heading>', 'extract only the named H1 section (# <heading> through next # )')
+        .option('--max-lines <n>', 'cap stdout at N lines (default: unlimited)')).action((name, options) => {
+        const asJson = options.json === true;
+        if (!/^[a-z][a-z0-9-]*$/.test(name)) {
+            printResult(io, fail('ecc.show', 'INVALID_NAME', `agent name must match ^[a-z][a-z0-9-]*$ (got "${name}")`, { name }, [
+                'Run `peaks ecc ls` to see valid agent names.',
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        const body = readAgentSkill(name);
+        if (body === null) {
+            printResult(io, fail('ecc.show', 'NOT_FOUND', `agent "${name}" is not in the cache`, { name }, [
+                'Run `peaks ecc ls` to see available agents.',
+                'Or run `peaks ecc install` to (re-)populate the cache.',
+            ]), asJson);
+            process.exitCode = 1;
+            return;
+        }
+        let filtered = body;
+        if (typeof options.section === 'string' && options.section.length > 0) {
+            const heading = options.section.trim();
+            const lines = body.split(/\r?\n/);
+            const startIdx = lines.findIndex((line) => new RegExp(`^#\\s+${escapeRegExp(heading)}\\s*$`).test(line));
+            if (startIdx === -1) {
+                printResult(io, fail('ecc.show', 'SECTION_NOT_FOUND', `section "# ${heading}" not found in ${name}.md`, { name, section: heading }, [
+                    'Open the file directly to see section names.',
+                ]), asJson);
+                process.exitCode = 1;
+                return;
+            }
+            let endIdx = lines.length;
+            for (let i = startIdx + 1; i < lines.length; i += 1) {
+                const line = lines[i] ?? '';
+                if (/^#\s+/.test(line)) {
+                    endIdx = i;
+                    break;
+                }
+            }
+            filtered = lines.slice(startIdx, endIdx).join('\n');
+        }
+        if (typeof options.maxLines === 'string' && options.maxLines.length > 0) {
+            const cap = Number.parseInt(options.maxLines, 10);
+            if (Number.isInteger(cap) && cap > 0) {
+                const lines = filtered.split(/\r?\n/);
+                if (lines.length > cap)
+                    filtered = lines.slice(0, cap).join('\n');
+            }
+        }
+        if (asJson) {
+            printResult(io, ok('ecc.show', { name, body: filtered }, [], []), asJson);
+            return;
+        }
+        // Human-readable path: raw SKILL.md body to stdout (LLM-consumable).
+        io.stdout(filtered);
+    });
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/dist/cli/commands/perf-audit-commands.js

@@ -36,7 +36,7 @@ function readStdinSync() {
 }
 export function registerPerfAuditCommands(program, io) {
     const perfAudit = program
-        .command('perf-audit')
+        .command('perf-audit', { hidden: true })
         .description('Independent performance audit skill driver. Reads the immutable peaks-prd handoff (sha256-locked) + the project-level perf-template.md, then writes a structured perf-<rid>.md artifact. Decoupled from peaks-rd 5-way fan-out per slice v2.12.0 (Group A, Tier 3). See skills/bee/peaks-perf-audit/SKILL.md for the full workflow.');
     addJsonOption(perfAudit
         .command('detect')

package/dist/cli/commands/prd-commands.js

@@ -37,7 +37,9 @@ async function resolveBody(bodyArg) {
     return bodyArg;
 }
 export function registerPrdCommands(program, io) {
-    const prd = program.command('prd').description('peaks-prd role: artifact + handoff primitives');
+    const prd = program
+        .command('prd', { hidden: true })
+        .description('peaks-prd role: artifact + handoff primitives');
     const handoff = prd.command('handoff').description('Write / verify / show the immutable PRD handoff (sha256-locked, schemaVersion: 2)');
     // peaks prd handoff init
     addJsonOption(handoff

package/dist/cli/commands/qa-commands.js

@@ -200,7 +200,7 @@ export function readQaRunOptions(options) {
 }
 export function registerQaCommands(program, io) {
     const qa = program
-        .command('qa')
+        .command('qa', { hidden: true })
         .description('peaks-qa slice: run QA gates (functional / security / browser E2E / mutation) for the active project');
     addJsonOption(qa
         .command('run')

package/dist/cli/commands/sc-commands.js

@@ -2,7 +2,9 @@ import { createArtifactRetentionReport, createChangeImpact, getChangeTraceabilit
 import { ok } from '../../shared/result.js';
 import { addJsonOption, multipleOption, printResult } from '../cli-helpers.js';
 export function registerSCCommands(program, io) {
-    const sc = program.command('sc').description('Source control and change traceability (peaks-sc integration)');
+    const sc = program
+        .command('sc', { hidden: true })
+        .description('Source control and change traceability (peaks-sc integration)');
     registerSCStatusCommands(sc, io);
     registerSCArtifactCommands(sc, io);
 }

package/dist/cli/commands/security-audit-commands.js

@@ -36,7 +36,7 @@ function readStdinSync() {
 }
 export function registerSecurityAuditCommands(program, io) {
     const securityAudit = program
-        .command('security-audit')
+        .command('security-audit', { hidden: true })
         .description('Independent security audit skill driver. Reads the immutable peaks-prd handoff (sha256-locked) + the project-level security-template.md, then writes a structured security-<rid>.md artifact. Decoupled from peaks-rd 5-way fan-out per slice v2.12.0 (Group A, Tier 2). See skills/bee/peaks-security-audit/SKILL.md for the full workflow.');
     addJsonOption(securityAudit
         .command('detect')

package/dist/cli/commands/skill-search-commands.js

@@ -28,6 +28,7 @@ export function registerSkillSearchCommand(program, io) {
         .option('-t, --tag <tag>', 'exact match on metadata.tags (e.g. "orchestrator", "loop-engineering")')
         .option('-d, --domain <domain>', 'exact match on metadata.domain (locked enum: code | content | doctor | research | triage | sop | audit | final-review | resume | status | test | ide | slice-decompose | issue-fix-orchestrator | perf-audit | security-audit | reviewer)')
         .option('-l, --limit <n>', 'max results returned (1..100, default 20)', (v) => Number.parseInt(v, 10))
+        .option('--include-internal', 'include skills with visibility: internal (default: hide them)')
         .action(async (options) => {
         // 1) Coerce + validate input via the service's Zod schema.
         //    The schema's refine rejects empty input — that is the
@@ -41,6 +42,8 @@ export function registerSkillSearchCommand(program, io) {
             raw['domain'] = options.domain;
         if (options.limit !== undefined)
             raw['limit'] = options.limit;
+        if (options.includeInternal === true)
+            raw['includeInternal'] = true;
         const parsed = SkillSearchInputSchema.safeParse(raw);
         if (!parsed.success) {
             // Exit code 1 = invalid args. Emit a human-readable message

package/dist/cli/commands/upgrade-commands.js

@@ -7,7 +7,7 @@ import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { fail, ok } from '../../shared/result.js';
 export function registerUpgradeCommands(program, io) {
     addJsonOption(program
-        .command('upgrade')
+        .command('upgrade', { hidden: true })
         .description('Upgrade a peaks-loop 1.x project to 2.0. Umbrella that orquestrates 7 sub-commands: config-migrate / standards-migrate / memory-extract / hooks-install / skill-sync / audit-verify + write-upgrade-record. Per the "one-key completion" tenet, prefer letting `npm i -g peaks-loop@2.0` postinstall run this for you. Use `--detect-1x` for a read-only probe (no file writes) that the peaks-code skill uses to gate the 1.x → 2.0 AskUserQuestion.')
         .option('--to <version>', 'target version (only "2.0" supported)', '2.0')
         .option('--project <path>', 'project root to upgrade (default: cwd)')

package/dist/cli/program.js

@@ -58,7 +58,7 @@ import { registerWorkflowEvalCommands } from './commands/loop-eval-commands.js';
 import { registerEvolutionCommands } from './commands/evolution-commands.js';
 import { registerAssetCommands } from './commands/asset-commands.js';
 import { registerBeeCommands } from './commands/bee-commands.js';
-import { registerAgentCommands } from './commands/agent-commands.js';
+import { registerEccCommands } from './commands/ecc-commands.js';
 import { registerUpgradeCommands } from './commands/upgrade-commands.js';
 import { registerCodeReviewCommands } from './commands/code-review-commands.js';
 import { registerSecurityAuditCommands } from './commands/security-audit-commands.js';
@@ -99,7 +99,7 @@ import { registerAdapterS2ACommands } from './commands/adapter-commands-s2a.js';
 // Slice RD-2 S2-b: `peaks polyrepo *` (init / status / dispatch).
 import { registerPolyrepoCommands } from './commands/polyrepo-commands.js';
 import { registerSkillVisibilityCommand } from './commands/skill-visibility.js';
-import { applyRetention } from '../services/log/retention.js';
+import { applyRetention, cleanupEccCache } from '../services/log/retention.js';
 import { writeLogEntry, maybeWriteStderr } from '../services/log/logger.js';
 export { printResult } from './cli-helpers.js';
 /**
@@ -120,6 +120,13 @@ function bootstrapLogger(verbose) {
     catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
         /* best-effort retention sweep; never block the CLI */
     }
+    // Slice 3 (on-demand-ecc): 7-day TTL sweep over ecc-<sha>/ cache dirs.
+    try {
+        cleanupEccCache({ retentionDays: 7, nowMs: Date.now() });
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        /* best-effort ECC retention sweep; never block the CLI */
+    }
     const dateOverride = process.env.PEAKS_LOG_DATE_OVERRIDE;
     const entry = {
         ts: new Date().toISOString(),
@@ -329,8 +336,9 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     // M7 (2026-07-07 spec §7A.2 / §10 RL-9): `peaks bee export|import`
     // — cross-user share surface for bee_release rows.
     registerBeeCommands(program, io);
-    // Slice: ECC 64 agents soft-optional (per spec §7.2 line 818).
-    registerAgentCommands(program, io);
+    // Slice 3 (on-demand-ecc): `peaks ecc install|status|ls|show` replaces the
+    // deleted `peaks agent run|list` subprocess surface.
+    registerEccCommands(program, io);
     // Slice: 1.x → 2.0 umbrella (per "one-key completion" + "minimal-user-operation" tenets).
     registerUpgradeCommands(program, io);
     // Slice: ocr soft-optional integration (peaks-rd Gate B3 augmentation).