peaks-loop 4.0.0-beta.9 → 4.0.3

package/dist/services/release/version-precheck-service.js

@@ -0,0 +1,257 @@
+/**
+ * rid-010 — peaks release precheck (Phase 4 slice 1).
+ *
+ * Module path: src/services/release/version-precheck-service.ts
+ * Mirror of publish.yml gate-cli-version step §(A). The §(B) tarball-content gate
+ * (Layer 5 of the 5-layer root cause) stays CI-only — AC-7 grep test pins
+ * publish.yml so §(B) cannot drift silently.
+ *
+ * 4-layer version precheck mirroring publish.yml gate-cli-version step. Designed
+ * to run BEFORE `peaks release canary` so developers catch CLI_VERSION lag /
+ * tag collision / changeset staged / workspace drift without waiting for CI.
+ *
+ * Mirrors the §(A) on-disk gate from publish.yml. The §(B) tarball-content gate
+ * (Layer 5 of the 5-layer root cause) stays CI-only — AC-7 grep test pins
+ * publish.yml so §(B) cannot drift silently.
+ *
+ * Design contract:
+ *   - Pure functions. NO `process.exitCode` mutation here (cli-helpers owns it).
+ *   - All I/O parameterized via `projectRoot`.
+ *   - Layer A and B are blockers by default; C and D are warnings (--strict
+ *     upgrades them to blockers; hotfix path uses default warning).
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function upgrade(result, strict) {
+    if (strict === true && result.status === 'warning') {
+        return {
+            ...result,
+            status: 'blocker',
+            remediation: `${result.remediation} (strict mode: warning promoted to blocker)`
+        };
+    }
+    return result;
+}
+function readRootVersion(projectRoot) {
+    const pkg = JSON.parse(readFileSync(join(projectRoot, 'package.json'), 'utf8'));
+    if (typeof pkg.version !== 'string' || !SEMVER_RE.test(pkg.version)) {
+        throw new Error(`invalid root package.json#version: ${JSON.stringify(pkg.version)}`);
+    }
+    return pkg.version;
+}
+function rollup(layers, strict) {
+    const statuses = Object.values(layers).map((l) => l.status);
+    if (statuses.includes('blocker')) {
+        return { ok: false, overall: 'blocker' };
+    }
+    if (statuses.includes('warning')) {
+        return { ok: true, overall: 'warning' };
+    }
+    return { ok: true, overall: 'ok' };
+}
+// ---------------------------------------------------------------------------
+// Layer A — rootVsShared (mirrors publish.yml §(A) on-disk gate only)
+// ---------------------------------------------------------------------------
+export function runRootVsShared(opts) {
+    const rootVersion = readRootVersion(opts.projectRoot);
+    const sharedDist = join(opts.projectRoot, 'packages', 'peaks-loop-shared', 'dist', 'version.js');
+    let sharedVersion = null;
+    let distExists = false;
+    try {
+        const raw = readFileSync(sharedDist, 'utf8');
+        const match = raw.match(/CLI_VERSION\s*=\s*"([^"]+)"/);
+        if (match && match[1] !== undefined) {
+            sharedVersion = match[1];
+        }
+        distExists = true;
+    }
+    catch {
+        distExists = false;
+    }
+    if (!distExists) {
+        return {
+            status: 'blocker',
+            message: `peaks-loop-shared/dist/version.js is missing at ${sharedDist}`,
+            remediation: 'run `pnpm --filter peaks-loop-shared build` to regenerate dist/version.js; ' +
+                'then re-run `peaks release precheck`',
+            observed: { rootVersion, sharedVersion: null }
+        };
+    }
+    if (sharedVersion === null) {
+        return {
+            status: 'blocker',
+            message: `peaks-loop-shared/dist/version.js does not contain a parseable CLI_VERSION`,
+            remediation: 'inspect packages/peaks-loop-shared/dist/version.js; ensure CLI_VERSION = "<semver>" is exported',
+            observed: { rootVersion, sharedVersion: null }
+        };
+    }
+    if (sharedVersion !== rootVersion) {
+        return {
+            status: 'blocker',
+            message: `peaks-loop root version (${rootVersion}) does not match peaks-loop-shared/dist/version.js CLI_VERSION (${sharedVersion})`,
+            remediation: 'bump packages/peaks-loop-shared/package.json#version to match root package.json#version, ' +
+                'commit peaks-loop-shared@' +
+                rootVersion +
+                ', then re-run `peaks release precheck`',
+            observed: { rootVersion, sharedVersion }
+        };
+    }
+    return {
+        status: 'ok',
+        message: `peaks-loop root version matches peaks-loop-shared/dist/version.js CLI_VERSION`,
+        remediation: '',
+        observed: { rootVersion, sharedVersion }
+    };
+}
+// ---------------------------------------------------------------------------
+// Layer B — tagCollision (CLI-only; not in publish.yml today)
+// ---------------------------------------------------------------------------
+export function runTagCollision(opts) {
+    const rootVersion = readRootVersion(opts.projectRoot);
+    const tagName = `v${rootVersion}`;
+    // Windows shell wrapping convention: 5 prior occurrences in tests/unit/release/.
+    const res = spawnSync('git', ['-C', opts.projectRoot, 'tag', '--list', tagName], {
+        shell: process.platform === 'win32',
+        encoding: 'utf8',
+        timeout: 5_000
+    });
+    if (res.error !== null && res.error !== undefined) {
+        return {
+            status: 'warning',
+            message: `git invocation failed; tag-collision layer skipped (${res.error.message})`,
+            remediation: 'ensure `git` is on PATH (Git Bash ships git at C:\\Program Files\\Git\\bin\\git.exe)',
+            observed: { tagName }
+        };
+    }
+    if (res.status !== 0) {
+        return {
+            status: 'warning',
+            message: `git tag --list exited with code ${res.status}; tag-collision layer skipped`,
+            remediation: 'inspect git configuration; precheck will defer to publish.yml gate for tag collision',
+            observed: { tagName, stderr: res.stderr }
+        };
+    }
+    const tagOutput = (res.stdout ?? '').trim();
+    if (tagOutput.includes(tagName)) {
+        return {
+            status: 'blocker',
+            message: `git tag ${tagName} already exists locally — publishing this version would fail at the registry step`,
+            remediation: `delete the existing tag: \`git tag -d ${tagName}\` (or use \`peaks release hotfix <next-version>\` for an out-of-band release)`,
+            observed: { tagName }
+        };
+    }
+    return {
+        status: 'ok',
+        message: `git tag ${tagName} does not exist; safe to publish`,
+        remediation: '',
+        observed: { tagName }
+    };
+}
+// ---------------------------------------------------------------------------
+// Layer C — changesetStaged (mirrors publish.yml gate-changeset step)
+// ---------------------------------------------------------------------------
+export function runChangesetStaged(opts) {
+    const changesetDir = join(opts.projectRoot, '.changeset');
+    let files = [];
+    try {
+        files = readdirSync(changesetDir);
+    }
+    catch {
+        return {
+            status: 'ok',
+            message: '.changeset/ directory is absent — no changeset is staged',
+            remediation: '',
+            observed: { stagedFiles: [] }
+        };
+    }
+    const staged = files.filter((f) => f.endsWith('.md') && f !== 'README.md');
+    if (staged.length === 0) {
+        return {
+            status: 'ok',
+            message: '.changeset/ has no staged *.md files',
+            remediation: '',
+            observed: { stagedFiles: [] }
+        };
+    }
+    return {
+        status: 'warning',
+        message: `.changeset/ has ${staged.length} staged change(s): ${staged.join(', ')}`,
+        remediation: 'publish.yml gate-changeset will BLOCK publish with these staged files. ' +
+            'Either: (a) run `peaks changeset publish` to drain the staged changesets, ' +
+            '(b) move them out of .changeset/, or (c) re-run with --strict to enforce blocker exit here.',
+        observed: { stagedFiles: staged }
+    };
+}
+// ---------------------------------------------------------------------------
+// Layer D — workspaceLockstep (CLI-only; not in publish.yml today)
+// ---------------------------------------------------------------------------
+export function runWorkspaceLockstep(opts) {
+    const rootPkgRaw = readFileSync(join(opts.projectRoot, 'package.json'), 'utf8');
+    const rootPkg = JSON.parse(rootPkgRaw);
+    const allDeps = {
+        ...(rootPkg.dependencies ?? {}),
+        ...(rootPkg.devDependencies ?? {})
+    };
+    const sharedDep = allDeps['peaks-loop-shared'];
+    if (sharedDep === undefined) {
+        return {
+            status: 'blocker',
+            message: 'peaks-loop-shared is not declared in root dependencies',
+            remediation: 'add `"peaks-loop-shared": "workspace:*"` to root package.json#dependencies',
+            observed: { sharedDep: null }
+        };
+    }
+    if (sharedDep !== 'workspace:*') {
+        return {
+            status: 'warning',
+            message: `peaks-loop-shared is pinned to "${sharedDep}" instead of "workspace:*"`,
+            remediation: 'restore `"peaks-loop-shared": "workspace:*"` in root package.json to ensure ' +
+                'the local dev link is preserved; published semver-pin regressions cause the CLI_VERSION drift class.',
+            observed: { sharedDep }
+        };
+    }
+    const sharedPkgRaw = readFileSync(join(opts.projectRoot, 'packages', 'peaks-loop-shared', 'package.json'), 'utf8');
+    const sharedPkg = JSON.parse(sharedPkgRaw);
+    const sharedVersion = sharedPkg.version ?? '';
+    if (!SEMVER_RE.test(sharedVersion)) {
+        return {
+            status: 'blocker',
+            message: `peaks-loop-shared package.json#version is not a clean semver: "${sharedVersion}"`,
+            remediation: 'set packages/peaks-loop-shared/package.json#version to a clean semver (e.g. 0.0.18)',
+            observed: { sharedVersion }
+        };
+    }
+    return {
+        status: 'ok',
+        message: `peaks-loop-shared is workspace-linked; shared version "${sharedVersion}" is clean semver`,
+        remediation: '',
+        observed: { sharedDep, sharedVersion }
+    };
+}
+// ---------------------------------------------------------------------------
+// runAllLayers — orchestrator
+// ---------------------------------------------------------------------------
+export function runAllLayers(opts) {
+    const rootVersion = readRootVersion(opts.projectRoot);
+    const strict = opts.strict === true;
+    const layers = {
+        rootVsShared: upgrade(runRootVsShared(opts), strict),
+        tagCollision: upgrade(runTagCollision(opts), strict),
+        changesetStaged: upgrade(runChangesetStaged(opts), strict),
+        workspaceLockstep: upgrade(runWorkspaceLockstep(opts), strict)
+    };
+    const rolled = rollup(layers, strict);
+    return {
+        ok: rolled.ok,
+        overall: rolled.overall,
+        rootVersion,
+        strict,
+        snapshotAt: new Date().toISOString(),
+        layers
+    };
+}

package/dist/services/scan/acceptance-coverage-service.js

@@ -1,5 +1,5 @@
 import { join } from 'node:path';
-import { pathExists, readText } from '../../shared/fs.js';
+import { pathExists, readText } from 'peaks-loop-shared/fs';
 import { showRequestArtifact } from '../artifacts/request-artifact-service.js';
 const ACCEPTANCE_SECTION_PATTERN = /^##\s+(?:Acceptance criteria|验收标准|Acceptance Criteria)\s*$/m;
 function extractAcceptanceItems(prdBody) {

package/dist/services/scan/archetype-service.js

@@ -1,6 +1,6 @@
 import { readdir, stat } from 'node:fs/promises';
 import { join } from 'node:path';
-import { isDirectory, pathExists, readText } from '../../shared/fs.js';
+import { isDirectory, pathExists, readText } from 'peaks-loop-shared/fs';
 const BACKEND_DEP_NAMES = [
     'express',
     'koa',

package/dist/services/scan/existing-system-service.js

@@ -1,6 +1,6 @@
 import { readdir, stat } from 'node:fs/promises';
 import { basename, join, relative } from 'node:path';
-import { isDirectory, pathExists, readText } from '../../shared/fs.js';
+import { isDirectory, pathExists, readText } from 'peaks-loop-shared/fs';
 import { scanArchetype } from './archetype-service.js';
 const DEFAULT_MAX_TOKENS = 40;
 const DEFAULT_SAMPLES = 5;

package/dist/services/scan/libraries-service.js

@@ -1,6 +1,6 @@
 import { readdir } from 'node:fs/promises';
 import { join, sep } from 'node:path';
-import { isDirectory, pathExists, readText } from '../../shared/fs.js';
+import { isDirectory, pathExists, readText } from 'peaks-loop-shared/fs';
 const SCOPES = [
     'dependencies',
     'devDependencies',

package/dist/services/sediment/json-schema.d.ts

@@ -68,22 +68,22 @@ export declare const BeeManifestSchema: z.ZodEffects<z.ZodObject<{
             kind: z.ZodEnum<["file", "dir", "script"]>;
         }, "strip", z.ZodTypeAny, {
             path: string;
-            kind: "file" | "script" | "dir";
+            kind: "file" | "dir" | "script";
         }, {
             path: string;
-            kind: "file" | "script" | "dir";
+            kind: "file" | "dir" | "script";
         }>, "many">;
     }, "strip", z.ZodTypeAny, {
         preamble: string;
         refs: {
             path: string;
-            kind: "file" | "script" | "dir";
+            kind: "file" | "dir" | "script";
         }[];
     }, {
         preamble: string;
         refs: {
             path: string;
-            kind: "file" | "script" | "dir";
+            kind: "file" | "dir" | "script";
         }[];
     }>;
     promotion: z.ZodObject<{
@@ -106,15 +106,7 @@ export declare const BeeManifestSchema: z.ZodEffects<z.ZodObject<{
     lastTouchedAt: z.ZodString;
 }, "strip", z.ZodTypeAny, {
     name: string;
-    source: "user" | "system";
     description: string;
-    schemaVersion: "peaks.bee/1";
-    promotion: {
-        minCycles: number;
-        requiresHumanApproval: boolean;
-        requiresSmokeTest: boolean;
-        retireOnMissesInRow?: number | undefined;
-    };
     segments: {
         name: string;
         outputs: {
@@ -129,27 +121,27 @@ export declare const BeeManifestSchema: z.ZodEffects<z.ZodObject<{
         }[];
         sideEffects: string[];
     }[];
+    promotion: {
+        minCycles: number;
+        requiresHumanApproval: boolean;
+        requiresSmokeTest: boolean;
+        retireOnMissesInRow?: number | undefined;
+    };
+    source: "user" | "system";
+    schemaVersion: "peaks.bee/1";
     promotion_status: "candidate" | "stable" | "retired" | "system-stable";
     entrypoint: {
         preamble: string;
         refs: {
             path: string;
-            kind: "file" | "script" | "dir";
+            kind: "file" | "dir" | "script";
         }[];
     };
     createdBy: "llm" | "human";
     lastTouchedAt: string;
 }, {
     name: string;
-    source: "user" | "system";
     description: string;
-    schemaVersion: "peaks.bee/1";
-    promotion: {
-        minCycles: number;
-        requiresHumanApproval: boolean;
-        requiresSmokeTest: boolean;
-        retireOnMissesInRow?: number | undefined;
-    };
     segments: {
         name: string;
         outputs: {
@@ -164,27 +156,27 @@ export declare const BeeManifestSchema: z.ZodEffects<z.ZodObject<{
         }[];
         sideEffects: string[];
     }[];
+    promotion: {
+        minCycles: number;
+        requiresHumanApproval: boolean;
+        requiresSmokeTest: boolean;
+        retireOnMissesInRow?: number | undefined;
+    };
+    source: "user" | "system";
+    schemaVersion: "peaks.bee/1";
     promotion_status: "candidate" | "stable" | "retired" | "system-stable";
     entrypoint: {
         preamble: string;
         refs: {
             path: string;
-            kind: "file" | "script" | "dir";
+            kind: "file" | "dir" | "script";
         }[];
     };
     createdBy: "llm" | "human";
     lastTouchedAt: string;
 }>, {
     name: string;
-    source: "user" | "system";
     description: string;
-    schemaVersion: "peaks.bee/1";
-    promotion: {
-        minCycles: number;
-        requiresHumanApproval: boolean;
-        requiresSmokeTest: boolean;
-        retireOnMissesInRow?: number | undefined;
-    };
     segments: {
         name: string;
         outputs: {
@@ -199,27 +191,27 @@ export declare const BeeManifestSchema: z.ZodEffects<z.ZodObject<{
         }[];
         sideEffects: string[];
     }[];
+    promotion: {
+        minCycles: number;
+        requiresHumanApproval: boolean;
+        requiresSmokeTest: boolean;
+        retireOnMissesInRow?: number | undefined;
+    };
+    source: "user" | "system";
+    schemaVersion: "peaks.bee/1";
     promotion_status: "candidate" | "stable" | "retired" | "system-stable";
     entrypoint: {
         preamble: string;
         refs: {
             path: string;
-            kind: "file" | "script" | "dir";
+            kind: "file" | "dir" | "script";
         }[];
     };
     createdBy: "llm" | "human";
     lastTouchedAt: string;
 }, {
     name: string;
-    source: "user" | "system";
     description: string;
-    schemaVersion: "peaks.bee/1";
-    promotion: {
-        minCycles: number;
-        requiresHumanApproval: boolean;
-        requiresSmokeTest: boolean;
-        retireOnMissesInRow?: number | undefined;
-    };
     segments: {
         name: string;
         outputs: {
@@ -234,12 +226,20 @@ export declare const BeeManifestSchema: z.ZodEffects<z.ZodObject<{
         }[];
         sideEffects: string[];
     }[];
+    promotion: {
+        minCycles: number;
+        requiresHumanApproval: boolean;
+        requiresSmokeTest: boolean;
+        retireOnMissesInRow?: number | undefined;
+    };
+    source: "user" | "system";
+    schemaVersion: "peaks.bee/1";
     promotion_status: "candidate" | "stable" | "retired" | "system-stable";
     entrypoint: {
         preamble: string;
         refs: {
             path: string;
-            kind: "file" | "script" | "dir";
+            kind: "file" | "dir" | "script";
         }[];
     };
     createdBy: "llm" | "human";

package/dist/services/share/bundle-types.d.ts

@@ -106,13 +106,13 @@ export declare const SchemaVersionsMappingSchema: z.ZodObject<{
     loop_bee_relation: z.ZodLiteral<"peaks.loop-bee-relation/1">;
     crystallization: z.ZodLiteral<"peaks.crystallization/1">;
 }, "strict", z.ZodTypeAny, {
-    bee: "peaks.bee/1";
     loop: "peaks.loop/1";
+    bee: "peaks.bee/1";
     loop_bee_relation: "peaks.loop-bee-relation/1";
     crystallization: "peaks.crystallization/1";
 }, {
-    bee: "peaks.bee/1";
     loop: "peaks.loop/1";
+    bee: "peaks.bee/1";
     loop_bee_relation: "peaks.loop-bee-relation/1";
     crystallization: "peaks.crystallization/1";
 }>;
@@ -189,13 +189,13 @@ export declare const BundleManifestSchema: z.ZodEffects<z.ZodObject<{
         loop_bee_relation: z.ZodLiteral<"peaks.loop-bee-relation/1">;
         crystallization: z.ZodLiteral<"peaks.crystallization/1">;
     }, "strict", z.ZodTypeAny, {
-        bee: "peaks.bee/1";
         loop: "peaks.loop/1";
+        bee: "peaks.bee/1";
         loop_bee_relation: "peaks.loop-bee-relation/1";
         crystallization: "peaks.crystallization/1";
     }, {
-        bee: "peaks.bee/1";
         loop: "peaks.loop/1";
+        bee: "peaks.bee/1";
         loop_bee_relation: "peaks.loop-bee-relation/1";
         crystallization: "peaks.crystallization/1";
     }>;
@@ -253,13 +253,13 @@ export declare const BundleManifestSchema: z.ZodEffects<z.ZodObject<{
         state_db_rows: "excluded";
     }>;
 }, "strict", z.ZodTypeAny, {
-    kind: "bee" | "loop";
+    kind: "loop" | "bee";
     format_constant: "peaks.bundle/1";
     format_version_major: 1;
     format_version_minor: number;
     schema_versions: {
-        bee: "peaks.bee/1";
         loop: "peaks.loop/1";
+        bee: "peaks.bee/1";
         loop_bee_relation: "peaks.loop-bee-relation/1";
         crystallization: "peaks.crystallization/1";
     };
@@ -274,12 +274,12 @@ export declare const BundleManifestSchema: z.ZodEffects<z.ZodObject<{
     loop_release?: unknown;
     bee_release?: unknown;
 }, {
-    kind: "bee" | "loop";
+    kind: "loop" | "bee";
     format_constant: "peaks.bundle/1";
     format_version_major: 1;
     schema_versions: {
-        bee: "peaks.bee/1";
         loop: "peaks.loop/1";
+        bee: "peaks.bee/1";
         loop_bee_relation: "peaks.loop-bee-relation/1";
         crystallization: "peaks.crystallization/1";
     };
@@ -295,13 +295,13 @@ export declare const BundleManifestSchema: z.ZodEffects<z.ZodObject<{
     loop_bee_relations?: unknown[] | undefined;
     evidence_briefs?: unknown[] | undefined;
 }>, {
-    kind: "bee" | "loop";
+    kind: "loop" | "bee";
     format_constant: "peaks.bundle/1";
     format_version_major: 1;
     format_version_minor: number;
     schema_versions: {
-        bee: "peaks.bee/1";
         loop: "peaks.loop/1";
+        bee: "peaks.bee/1";
         loop_bee_relation: "peaks.loop-bee-relation/1";
         crystallization: "peaks.crystallization/1";
     };
@@ -316,12 +316,12 @@ export declare const BundleManifestSchema: z.ZodEffects<z.ZodObject<{
     loop_release?: unknown;
     bee_release?: unknown;
 }, {
-    kind: "bee" | "loop";
+    kind: "loop" | "bee";
     format_constant: "peaks.bundle/1";
     format_version_major: 1;
     schema_versions: {
-        bee: "peaks.bee/1";
         loop: "peaks.loop/1";
+        bee: "peaks.bee/1";
         loop_bee_relation: "peaks.loop-bee-relation/1";
         crystallization: "peaks.crystallization/1";
     };

package/dist/services/share/run-state-contract.d.ts

@@ -75,7 +75,7 @@ export declare const RunStateContractSchema: z.ZodObject<{
     /** NL summary of the latest user choice (or null when none). */
     last_user_choice: z.ZodNullable<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
-    status: "done" | "failed" | "blocked" | "running" | "paused";
+    status: "blocked" | "failed" | "running" | "done" | "paused";
     bee_id: string;
     current_step: string;
     started_at: string;
@@ -83,7 +83,7 @@ export declare const RunStateContractSchema: z.ZodObject<{
     last_evaluator_verdict: string | null;
     last_user_choice: string | null;
 }, {
-    status: "done" | "failed" | "blocked" | "running" | "paused";
+    status: "blocked" | "failed" | "running" | "done" | "paused";
     bee_id: string;
     current_step: string;
     started_at: string;

package/dist/services/skill/skill-search-service.d.ts

@@ -23,32 +23,37 @@
  * matching, ML-based ranking, pagination, i18n, caching.
  */
 import { z } from 'zod';
-import { skillsDir } from '../../shared/paths.js';
+import { skillsDir } from 'peaks-loop-shared/paths';
 export declare const SkillSearchInputSchema: z.ZodEffects<z.ZodObject<{
     query: z.ZodOptional<z.ZodString>;
     tag: z.ZodOptional<z.ZodString>;
     domain: z.ZodOptional<z.ZodEnum<["code", "content", "doctor", "research", "triage", "sop", "audit", "final-review", "resume", "status", "test", "ide", "slice-decompose", "issue-fix-orchestrator", "perf-audit", "security-audit", "reviewer"]>>;
     limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    includeInternal: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 }, "strip", z.ZodTypeAny, {
     limit: number;
+    includeInternal: boolean;
     query?: string | undefined;
     tag?: string | undefined;
-    domain?: "code" | "status" | "content" | "test" | "doctor" | "resume" | "ide" | "research" | "triage" | "sop" | "audit" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+    domain?: "code" | "status" | "resume" | "audit" | "content" | "test" | "ide" | "research" | "doctor" | "triage" | "sop" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
 }, {
-    limit?: number | undefined;
     query?: string | undefined;
+    limit?: number | undefined;
     tag?: string | undefined;
-    domain?: "code" | "status" | "content" | "test" | "doctor" | "resume" | "ide" | "research" | "triage" | "sop" | "audit" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+    domain?: "code" | "status" | "resume" | "audit" | "content" | "test" | "ide" | "research" | "doctor" | "triage" | "sop" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+    includeInternal?: boolean | undefined;
 }>, {
     limit: number;
+    includeInternal: boolean;
     query?: string | undefined;
     tag?: string | undefined;
-    domain?: "code" | "status" | "content" | "test" | "doctor" | "resume" | "ide" | "research" | "triage" | "sop" | "audit" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+    domain?: "code" | "status" | "resume" | "audit" | "content" | "test" | "ide" | "research" | "doctor" | "triage" | "sop" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
 }, {
-    limit?: number | undefined;
     query?: string | undefined;
+    limit?: number | undefined;
     tag?: string | undefined;
-    domain?: "code" | "status" | "content" | "test" | "doctor" | "resume" | "ide" | "research" | "triage" | "sop" | "audit" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+    domain?: "code" | "status" | "resume" | "audit" | "content" | "test" | "ide" | "research" | "doctor" | "triage" | "sop" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+    includeInternal?: boolean | undefined;
 }>;
 export type SkillSearchInput = z.input<typeof SkillSearchInputSchema>;
 export declare const SkillSearchResultSchema: z.ZodObject<{

package/dist/services/skill/skill-search-service.js

@@ -25,8 +25,8 @@
 import { z } from 'zod';
 import { listSkills } from '../skills/skill-registry.js';
 import { parseFrontmatter } from '../../shared/frontmatter.js';
-import { readText } from '../../shared/fs.js';
-import { skillsDir } from '../../shared/paths.js';
+import { readText } from 'peaks-loop-shared/fs';
+import { skillsDir } from 'peaks-loop-shared/paths';
 const SKILL_DOMAINS = [
     'code',
     'content',
@@ -51,7 +51,8 @@ export const SkillSearchInputSchema = z
     query: z.string().min(1).max(500).optional(),
     tag: z.string().min(1).max(100).optional(),
     domain: z.enum(SKILL_DOMAINS).optional(),
-    limit: z.number().int().min(1).max(100).optional().default(20)
+    limit: z.number().int().min(1).max(100).optional().default(20),
+    includeInternal: z.boolean().optional().default(false)
 })
     .refine((v) => v.query !== undefined || v.tag !== undefined || v.domain !== undefined, { message: 'At least one of --query / --tag / --domain is required' });
 export const SkillSearchResultSchema = z.object({
@@ -130,7 +131,8 @@ async function loadEnrichedSkills() {
             triggers: extractTriggers(s.description),
             tags: meta.tags,
             domain: meta.domain,
-            skillPath: s.skillPath
+            skillPath: s.skillPath,
+            ...(s.visibility !== undefined ? { visibility: s.visibility } : {})
         };
     }));
 }
@@ -187,6 +189,8 @@ export async function searchSkills(rawInput) {
     const input = SkillSearchInputSchema.parse(rawInput);
     const skills = await loadEnrichedSkills();
     const filtered = skills.filter((skill) => {
+        if (!input.includeInternal && skill.visibility === 'internal')
+            return false;
         if (input.tag !== undefined) {
             const wanted = input.tag.toLowerCase();
             const has = skill.tags.some((t) => t.toLowerCase() === wanted);