llm-cli-gateway 2.14.0 → 2.15.0

package/.agents/skills/retrospective-walk/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: retrospective-walk
+description: Walk a human or agent through a diff, worktree, commit range, gateway job, or episode reference as a structured retrospective. Use after implement-review-fix or multi-LLM review cycles, when reviewing prior jobs or uncommitted work, or when durable evidence is needed for what changed, why it changed, who/when contributed, and captured human or model comments.
+---
+
+# Retrospective Walk
+
+Guide a change review as a narrative with evidence. Prefer this when the user
+needs the story of a change set, not just hunk-level inspection.
+
+## Inputs
+
+Accept these fields when the user supplies them, and infer conservative
+defaults when they do not:
+
+```json
+{
+  "scope": "diff | commit-range | worktree | job-id | episode-ref",
+  "target": "diff text, HEAD~5..HEAD, path, job id, or episode reference",
+  "mode": "guided | agent-driven | summary-only",
+  "capture_comments": true,
+  "models_for_why": [],
+  "include_prior_evidence": true
+}
+```
+
+Default `mode` to `guided` for a human in the loop, `agent-driven` for automated
+review, and `summary-only` only when explicitly requested or when interaction is
+not possible. Default `capture_comments` to true.
+
+## Scope Resolution
+
+Resolve the target into immutable evidence before analysis:
+
+- `diff`: use the supplied diff text. If the target is empty, capture
+  `git diff --no-ext-diff` and `git diff --cached --no-ext-diff`.
+- `commit-range`: capture `git diff --stat <range>`, `git diff --name-status
+  <range>`, and per-commit metadata from `git log --format=fuller <range>`.
+- `worktree`: capture status, dirty file list, staged diff, and unstaged diff.
+  Do not stash, reset, or mutate the target worktree. If deeper model/tool
+  analysis may write files, create a disposable isolated worktree or analyze a
+  read-only evidence packet instead.
+- `job-id`: fetch `llm_job_status` and `llm_job_result`; include `cli`,
+  `correlationId`, `sessionId`, timestamps, exit status, and output digests.
+- `episode-ref`: resolve through the caller's available episode/DAG context. If
+  no episode tool is available, record the unresolved reference and continue
+  from any linked diff, job, receipt, or review artifacts the user supplied.
+
+If `include_prior_evidence` is true, collect linked validation runs, receipts,
+review reports, approval records, job ids, and session/cache state that are
+available through gateway tools or local artifacts. Treat summaries as claims;
+prefer raw diffs, job outputs, receipt ids, commands, and file:line evidence.
+
+## Change Units
+
+Group hunks and files into logical change units before narrating them. Favor
+semantic intent over file boundaries, but keep units small enough to review.
+
+Use these grouping signals:
+
+- Shared feature, bug, invariant, or user-facing behavior.
+- Production code plus its tests and docs.
+- Config/schema/migration changes that must be deployed together.
+- Review-only or evidence-only changes, such as verification reports.
+
+Assign stable ids: `cu_001`, `cu_002`, etc. For each unit, record:
+
+```json
+{
+  "change_unit_id": "cu_001",
+  "title": "Short noun phrase",
+  "files": ["src/example.ts"],
+  "diff_refs": ["commit abc123", "hunk @@ -42,7 +42,9 @@"],
+  "what": "Semantic summary of the delta",
+  "why": "Intent, rationale, alternatives, and unresolved assumptions",
+  "who_when": [
+    {
+      "actor_type": "human | model | agent | git-author | unknown",
+      "identifier": "name, model key, job id, or commit author",
+      "timestamp": "RFC3339 if known",
+      "provenance": "commit, job, session, receipt, or user statement"
+    }
+  ],
+  "evidence": ["file:line", "job id", "validation receipt id", "command digest"],
+  "comments": []
+}
+```
+
+## What, Why, Who
+
+For each change unit:
+
+1. Extract **what** directly from the diff, file reads, tests, and docs.
+2. Derive **why** from commit messages, issue/DAG context, review findings,
+   prior receipts, job prompts/results, and nearby code intent.
+3. Attribute **who / when** using git author/committer metadata, gateway job
+   metadata, session ids, model keys, review outputs, and explicit user
+   statements.
+4. Mark inference boundaries. Use `inferred:` when intent or authorship is
+   reasoned from evidence rather than directly stated.
+5. Surface missing evidence as an open question instead of filling the gap with
+   confidence.
+
+Use `multi-llm-review` or direct gateway model calls only when why-synthesis is
+ambiguous, high stakes, or explicitly requested. Omit `model` unless the user
+requested specific variants; use `approvalStrategy:"mcp_managed"` and async job
+handling from `async-job-orchestration` for longer analysis. Ask models for
+intent/rationale synthesis, not for unverified approval.
+
+## Comment Capture
+
+When `capture_comments` is true, comments are evidence. Capture them at the
+change-unit level and, when possible, at the file/hunk/line location.
+
+In `guided` mode, walk one unit at a time:
+
+1. Present the unit's what/why/who and evidence.
+2. Ask for comments, concerns, approvals, suggestions, or intent corrections.
+3. Normalize each answer into the schema below.
+4. Continue only after comments are captured or the user skips the unit.
+
+In `agent-driven` mode, create agent/model comments only when they add evidence,
+concern, approval, or intent clarification beyond the narrative. In
+`summary-only` mode, do not stop for comments; include an empty comments array
+unless comments were supplied up front.
+
+Comment schema:
+
+```json
+{
+  "comment_id": "cmt_<ulid>",
+  "retrospective_id": "retro_<ulid>",
+  "change_unit_id": "cu_001",
+  "author": {
+    "author_type": "human | model",
+    "identifier": "werner or claude-4-opus",
+    "model_key": "optional; only for model comments"
+  },
+  "timestamp": "RFC3339",
+  "type": "note | concern | approval | suggestion | intent_clarification",
+  "text": "Comment body",
+  "location": {
+    "file": "optional path",
+    "hunk_range": "optional @@ range",
+    "semantic_unit": "optional semantic code-search node or future semantic id",
+    "line_start": 1,
+    "line_end": 2
+  },
+  "linked_receipts": ["validation receipt ids"],
+  "linked_jobs": ["async job ids"],
+  "metadata": {
+    "namespace.key": "freeform extension values"
+  }
+}
+```
+
+Generate ids in a stable, sortable form when the runtime has a ULID helper;
+otherwise use `retro_<timestamp>_<short-hash>` and
+`cmt_<timestamp>_<sequence>`.
+
+## Output Contract
+
+Emit both a readable retrospective and a machine-readable block. Keep the
+machine block fenced as `json` and make it complete enough to persist.
+
+Markdown structure:
+
+```markdown
+# Retrospective Walk: <target>
+
+Retrospective ID: retro_<id>
+Scope: <scope>
+Mode: <mode>
+Evidence baseline: <commands, commits, jobs, receipts>
+
+## Narrative
+<overall story: what happened, why, and remaining uncertainty>
+
+## Change Units
+### cu_001 - <title>
+What: ...
+Why: ...
+Who / when: ...
+Evidence: ...
+Comments: ...
+
+## Open Questions
+- ...
+
+## Evidence Package
+- validation_receipt: <id or unavailable: reason>
+- linked_jobs: [...]
+- linked_receipts: [...]
+```
+
+Machine-readable shape:
+
+```json
+{
+  "retrospective_id": "retro_<id>",
+  "schema_version": "retrospective-walk.v0.1.0",
+  "scope": "commit-range",
+  "target": "HEAD~5..HEAD",
+  "mode": "guided",
+  "created_at": "RFC3339",
+  "provenance_context": {
+    "commands": [],
+    "commits": [],
+    "jobs": [],
+    "receipts": [],
+    "episodes": []
+  },
+  "change_units": [],
+  "comments": [],
+  "narrative": "",
+  "open_questions": [],
+  "validation_receipt": {
+    "status": "minted | linked | unavailable",
+    "validation_id": "optional",
+    "receipt_id": "optional",
+    "reason": "optional"
+  }
+}
+```
+
+## Validation Receipts
+
+Use existing gateway validation receipt machinery when the retrospective is
+backed by a terminal validation run:
+
+- For prior validation ids, call `validation_receipt` and link the receipt.
+- For review or why-synthesis model jobs launched during the retrospective,
+  preserve job ids and retrieve receipts if those jobs are part of a validation
+  run that can mint one.
+- If no receipt-capable validation run exists, set
+  `validation_receipt.status` to `unavailable` and include a reason. Do not
+  claim a receipt was minted when the current gateway surface only produced a
+  retrospective artifact.
+
+## DAG Plan
+
+Use this plan shape when embedding the retrospective in a DAG or episode:
+
+```toml
+[plan]
+name = "retrospective-walk"
+version = "0.1.0"
+description = "Guided retrospective over changes with what/why/who and comment capture as evidence"
+owner = "verivus-oss"
+
+[[node]]
+id = "resolve-scope"
+type = "data"
+outputs = ["change_units", "provenance_context"]
+
+[[node]]
+id = "analyze-changes"
+type = "compute"
+inputs = ["change_units", "provenance_context", "models_for_why"]
+outputs = ["analyzed_units"]
+
+[[node]]
+id = "capture-comments"
+type = "human-or-agent"
+inputs = ["analyzed_units"]
+outputs = ["comments"]
+
+[[node]]
+id = "synthesize-retrospective"
+type = "compute"
+inputs = ["analyzed_units", "comments", "provenance_context"]
+outputs = ["retrospective_markdown", "retrospective_json"]
+
+[[node]]
+id = "emit-evidence"
+type = "side-effect"
+inputs = ["retrospective_json", "comments", "analyzed_units"]
+outputs = ["validation_receipt_id"]
+```
+
+Only update a DAG or episode when the caller provided a parent context and an
+available tool supports that write. Otherwise emit the retrospective and the
+evidence package without side effects.
+
+## Security And Isolation
+
+- Prefer read-only evidence capture. Do not mutate user worktrees while walking
+  changes.
+- Use a disposable isolated git worktree for model/tool operations that may edit
+  files, especially for `scope = worktree`.
+- Keep secrets, local account names, and machine-specific paths out of
+  persisted comments and receipts unless the user explicitly requires them.
+- Treat model-generated comments as model evidence, not human approval.
+- Preserve provenance for every comment, job, receipt, and inferred rationale.

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to the llm-cli-gateway project.
 
 ## [Unreleased]
 
+## [2.15.0] - 2026-07-03
+
+### Added
+
+- **Updateable local skill packs.** Gateway startup now loads bundled skills,
+  optional `[skills].paths`, `LLM_GATEWAY_SKILLS_PATH`, and
+  `~/.llm-cli-gateway/skills` with deterministic override precedence. Skill
+  pack roots can include a `skill-pack.json` integrity manifest that pins each
+  loaded `SKILL.md` by SHA-256, allowing operators to update workflow skills
+  outside core gateway npm releases without silent network fetches.
+
+## [2.14.1] - 2026-07-03
+
+### Added
+
+- **`retrospective-walk` workflow skill.** Bundles a guided retrospective skill
+  for walking a human or agent through a diff, worktree, commit range, gateway
+  job, or episode reference with structured what/why/who analysis, comment
+  capture as evidence, machine-readable output, and validation-receipt links
+  when an existing receipt-capable validation run is available.
+
 ## [2.14.0] - 2026-07-03
 
 ### Fixed

package/README.md

@@ -51,7 +51,41 @@ Or use directly with `npx` from an MCP client:
 
 ## Workflow Assets
 
-The repo ships agent-ready workflow skills under [`.agents/skills`](.agents/skills) for async orchestration, session continuity, multi-LLM review, implement-review-fix loops, and secure approval-gated dispatch. Six caller-facing skills are bundled in the published npm package: `async-job-orchestration`, `multi-llm-review`, `session-workflow`, `secure-orchestration`, `implement-review-fix`, and `public-demo-session`. Machine-readable DAG-TOML plans live under [`docs/plans`](docs/plans) and [`setup/install-plan.dag.toml`](setup/install-plan.dag.toml) for workflows that need deterministic sequencing and verification gates.
+The repo ships agent-ready workflow skills under [`.agents/skills`](.agents/skills) for async orchestration, session continuity, multi-LLM review, implement-review-fix loops, retrospective evidence walks, and secure approval-gated dispatch. Seven caller-facing skills are bundled in the published npm package: `async-job-orchestration`, `multi-llm-review`, `session-workflow`, `secure-orchestration`, `implement-review-fix`, `retrospective-walk`, and `public-demo-session`. Machine-readable DAG-TOML plans live under [`docs/plans`](docs/plans) and [`setup/install-plan.dag.toml`](setup/install-plan.dag.toml) for workflows that need deterministic sequencing and verification gates.
+
+Skill packs can be updated outside the core npm release by placing skill
+directories in local, operator-controlled paths. The gateway loads bundled
+skills first, then `[skills].paths`, then `LLM_GATEWAY_SKILLS_PATH`, then
+`~/.llm-cli-gateway/skills` when it exists; later roots override earlier skills
+by name. Each skill is a directory containing `SKILL.md`. A root may also carry
+`skill-pack.json` to pin expected `SKILL.md` hashes:
+
+```toml
+[skills]
+paths = ["/opt/llm-cli-gateway/skills"]
+```
+
+```bash
+export LLM_GATEWAY_SKILLS_PATH="/opt/team-skill-pack:/opt/incident-skill-pack"
+```
+
+```json
+{
+  "name": "team-pack",
+  "version": "1.0.0",
+  "skills": [
+    {
+      "name": "incident-retrospective",
+      "sha256": "<sha256 of incident-retrospective/SKILL.md>"
+    }
+  ]
+}
+```
+
+The loader is intentionally local-only: it never fetches remote Markdown at
+startup. To update a pack, install or replace files through your package manager
+or deployment system, then restart the gateway so the advertised `skills://...`
+resources refresh.
 
 The next documentation focus is provider-specific skill and DAG-TOML pairs for each outbound CLI and API-provider family: Claude, Codex, Gemini/Antigravity, Grok, Mistral Vibe, Devin, Cursor Agent, OpenAI-compatible endpoints, Anthropic Messages, and xAI Responses. The implementation plan is tracked in [`docs/plans/provider-workflow-assets.dag.toml`](docs/plans/provider-workflow-assets.dag.toml), with each provider asset expected to cover install/login checks or token-env checks, session behavior, approval modes, cache/telemetry surfaces, failure modes, and a smoke-test gate.
 
@@ -1435,6 +1469,7 @@ await callTool("session_delete", {
   LLM_GATEWAY_OAUTH_REQUIRE_CONSENT=1 LLM_GATEWAY_OAUTH_CONSENT_SECRET='choose-a-strong-code' node dist/index.js
   ```
 - `LLM_GATEWAY_CONFIG`: Path to the gateway TOML config (default: `~/.llm-cli-gateway/config.toml`). See **Persistence configuration** above for the `[persistence]` schema.
+- `LLM_GATEWAY_SKILLS_PATH`: Extra local skill-pack roots to load at startup, separated by the host path delimiter (`:` on Linux/macOS, `;` on Windows). These paths are appended after `[skills].paths`; `~/.llm-cli-gateway/skills` still loads last when present.
 - `LLM_GATEWAY_LOGS_DB`: **Deprecated** — overrides `[persistence].path` and selects `backend = "sqlite"` (or `backend = "none"` when set to `none`). Emits a deprecation warning at startup; migrate to `config.toml`.
   ```bash
   # Custom path

package/dist/config.d.ts

@@ -15,6 +15,13 @@ export interface Config {
     database?: DatabaseConfig;
     sessionTtl: number;
 }
+export interface SkillsConfig {
+    paths: string[];
+    sources: {
+        configFile: string | null;
+        envOverrides: string[];
+    };
+}
 export declare function loadConfig(): Config;
 export declare const PERSISTENCE_BACKENDS: readonly ["sqlite", "postgres", "memory", "none"];
 export type PersistenceBackend = (typeof PERSISTENCE_BACKENDS)[number];
@@ -46,6 +53,7 @@ export interface PersistenceConfigSources {
     envOverrides: string[];
 }
 export declare function defaultGatewayConfigPath(): string;
+export declare function loadSkillsConfig(logger?: Logger): SkillsConfig;
 export declare function loadPersistenceConfig(logger?: Logger): PersistenceConfig;
 export declare const DEFAULT_HTTP_MAX_SESSIONS = 100;
 export declare const DEFAULT_HTTP_SESSION_IDLE_TTL_MS: number;

package/dist/config.js

@@ -14,6 +14,12 @@ const DatabaseUrlSchema = z
     message: "Database URL must start with postgresql:// or postgres://",
 });
 export const DEFAULT_SESSION_TTL_SECONDS = 2592000;
+const SkillsSchema = z
+    .object({
+    paths: z.array(z.string().min(1)).default([]),
+})
+    .strict()
+    .default({ paths: [] });
 export function loadConfig() {
     const databaseUrl = process.env.DATABASE_URL;
     const rawSessionTtl = parseInt(process.env.SESSION_TTL || String(DEFAULT_SESSION_TTL_SECONDS), 10);
@@ -89,6 +95,32 @@ function defaultPersistenceConfigPath() {
 export function defaultGatewayConfigPath() {
     return defaultPersistenceConfigPath();
 }
+export function loadSkillsConfig(logger = noopLogger) {
+    const configPath = defaultGatewayConfigPath();
+    const { parsed, sourcePath } = readGatewayTomlFile(configPath, logger, "skills");
+    const rawSkills = parsed?.skills ?? {};
+    const sources = {
+        configFile: sourcePath,
+        envOverrides: [],
+    };
+    let skillsParsed;
+    try {
+        skillsParsed = SkillsSchema.parse(rawSkills);
+    }
+    catch (err) {
+        throw new Error(`Invalid [skills] config: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const paths = [...skillsParsed.paths];
+    const envPaths = process.env.LLM_GATEWAY_SKILLS_PATH;
+    if (envPaths !== undefined && envPaths.trim().length > 0) {
+        paths.push(...envPaths
+            .split(path.delimiter)
+            .map(part => part.trim())
+            .filter(Boolean));
+        sources.envOverrides.push("LLM_GATEWAY_SKILLS_PATH");
+    }
+    return { paths, sources };
+}
 function readPersistenceFile(configPath, logger) {
     if (!existsSync(configPath)) {
         return { raw: undefined, sourcePath: null };

package/dist/index.js

@@ -3,7 +3,7 @@ import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mc
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { randomUUID } from "crypto";
 import { createRequire } from "module";
-import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync, chmodSync, } from "fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, chmodSync, } from "fs";
 import { basename, dirname, isAbsolute, join, relative } from "path";
 import { fileURLToPath } from "url";
 import { z } from "zod/v3";
@@ -21,7 +21,8 @@ import { ResourceProvider } from "./resources.js";
 import { generateResourceDescriptors, generateProviderAcpDescriptors, } from "./provider-surface-generator.js";
 import { PerformanceMetrics } from "./metrics.js";
 import { estimateTokens, optimizePrompt as optimizePromptText, optimizeResponse as optimizeResponseText, } from "./optimizer.js";
-import { loadConfig, loadPersistenceConfig, loadCacheAwarenessConfig, loadProvidersConfig, loadAcpConfig, loadAdminConfig, loadLimitsConfig, defaultGatewayConfigPath, isXaiProviderEnabled, enabledApiProviders, minStableTokensForModel, } from "./config.js";
+import { loadConfig, loadPersistenceConfig, loadCacheAwarenessConfig, loadProvidersConfig, loadAcpConfig, loadAdminConfig, loadLimitsConfig, loadSkillsConfig, defaultGatewayConfigPath, isXaiProviderEnabled, enabledApiProviders, minStableTokensForModel, } from "./config.js";
+import { loadGatewaySkills } from "./skill-loader.js";
 import { runAcpRequest } from "./acp/runtime.js";
 import { isAcpError } from "./acp/errors.js";
 import { redactSecrets } from "./secret-redaction.js";
@@ -184,27 +185,13 @@ function packageVersion() {
     }
     return "unknown";
 }
-function loadSkills() {
-    const skills = [];
-    try {
-        const dirs = readdirSync(SKILLS_DIR, { withFileTypes: true }).filter(d => d.isDirectory());
-        for (const dir of dirs) {
-            const skillPath = join(SKILLS_DIR, dir.name, "SKILL.md");
-            try {
-                const content = readFileSync(skillPath, "utf-8");
-                const descMatch = content.match(/^---[\s\S]*?description:\s*(.+?)$/m);
-                const description = descMatch?.[1]?.trim() || dir.name;
-                skills.push({ name: dir.name, content, description });
-            }
-            catch {
-            }
-        }
-    }
-    catch {
-    }
-    return skills;
-}
-const loadedSkills = loadSkills();
+const skillsConfig = loadSkillsConfig(logger);
+const loadedSkills = loadGatewaySkills({
+    bundledSkillsDir: SKILLS_DIR,
+    configuredPaths: skillsConfig.paths,
+    envSkillsPath: undefined,
+    logger,
+});
 export function buildServerInstructions(asyncJobsEnabled, grokApiToolsEnabled = false) {
     const asyncToolsNote = asyncJobsEnabled ? " | *_request_async (async)" : "";
     const apiToolsNote = grokApiToolsEnabled ? ", grok_api_request" : "";

package/dist/skill-loader.d.ts

@@ -0,0 +1,24 @@
+import type { Logger } from "./logger.js";
+export interface SkillEntry {
+    name: string;
+    content: string;
+    description: string;
+    source: "bundled" | "external";
+    path: string;
+    pack: {
+        name: string;
+        version: string;
+        manifestPath: string;
+        verified: boolean;
+    } | null;
+}
+export interface LoadGatewaySkillsOptions {
+    bundledSkillsDir: string;
+    configuredPaths?: string[];
+    envSkillsPath?: string | undefined;
+    userSkillsDir?: string;
+    logger?: Logger;
+}
+export declare function defaultUserSkillsDir(): string;
+export declare function parseSkillPathList(raw: string | undefined): string[];
+export declare function loadGatewaySkills(options: LoadGatewaySkillsOptions): SkillEntry[];

package/dist/skill-loader.js

@@ -0,0 +1,201 @@
+import { createHash } from "crypto";
+import { existsSync, readFileSync, readdirSync, statSync } from "fs";
+import { homedir } from "os";
+import path from "path";
+import { z } from "zod/v3";
+import { logWarn, noopLogger } from "./logger.js";
+const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
+const SkillPackManifestSchema = z
+    .object({
+    name: z.string().regex(SKILL_NAME_PATTERN),
+    version: z.string().min(1),
+    skills: z
+        .array(z
+        .object({
+        name: z.string().regex(SKILL_NAME_PATTERN),
+        sha256: z.string().regex(/^[a-f0-9]{64}$/i),
+    })
+        .strict())
+        .default([]),
+})
+    .strict();
+export function defaultUserSkillsDir() {
+    return path.join(homedir(), ".llm-cli-gateway", "skills");
+}
+export function parseSkillPathList(raw) {
+    if (!raw)
+        return [];
+    return raw
+        .split(path.delimiter)
+        .map(part => part.trim())
+        .filter(Boolean);
+}
+export function loadGatewaySkills(options) {
+    const logger = options.logger ?? noopLogger;
+    const roots = [
+        { path: options.bundledSkillsDir, source: "bundled", label: "bundled" },
+        ...normalizeExternalRoots(options.configuredPaths ?? [], "configured"),
+        ...normalizeExternalRoots(parseSkillPathList(options.envSkillsPath), "LLM_GATEWAY_SKILLS_PATH"),
+    ];
+    const userSkillsDir = options.userSkillsDir ?? defaultUserSkillsDir();
+    if (existsSync(userSkillsDir)) {
+        roots.push({ path: userSkillsDir, source: "external", label: "user" });
+    }
+    const byName = new Map();
+    for (const root of roots) {
+        for (const skill of readSkillRoot(root, logger)) {
+            const prior = byName.get(skill.name);
+            if (prior) {
+                logWarn(logger, `Skill '${skill.name}' from ${skill.path} overrides ${prior.source} skill at ${prior.path}`);
+            }
+            byName.set(skill.name, skill);
+        }
+    }
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+function normalizeExternalRoots(paths, label) {
+    return paths.map(p => ({
+        path: expandHome(p),
+        source: "external",
+        label,
+    }));
+}
+function expandHome(p) {
+    return p === "~" ? homedir() : p.startsWith("~/") ? path.join(homedir(), p.slice(2)) : p;
+}
+function readSkillRoot(root, logger) {
+    if (!existsSync(root.path)) {
+        if (root.source === "external") {
+            logWarn(logger, `Configured skill path does not exist; skipping: ${root.path}`);
+        }
+        return [];
+    }
+    let stat;
+    try {
+        stat = statSync(root.path);
+    }
+    catch (err) {
+        logWarn(logger, `Cannot stat skill path; skipping: ${root.path}`, err);
+        return [];
+    }
+    if (!stat.isDirectory()) {
+        logWarn(logger, `Skill path is not a directory; skipping: ${root.path}`);
+        return [];
+    }
+    const manifest = readManifest(root, logger);
+    if (manifest === "invalid")
+        return [];
+    if (existsSync(path.join(root.path, "SKILL.md"))) {
+        const skill = readSkillDir(root.path, root, manifest, logger);
+        return skill ? [skill] : [];
+    }
+    let entries;
+    try {
+        entries = readdirSync(root.path, { withFileTypes: true });
+    }
+    catch (err) {
+        logWarn(logger, `Cannot read skill path; skipping: ${root.path}`, err);
+        return [];
+    }
+    const skills = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory())
+            continue;
+        const skill = readSkillDir(path.join(root.path, entry.name), root, manifest, logger);
+        if (skill)
+            skills.push(skill);
+    }
+    if (manifest && manifest.skills.length > 0) {
+        const loaded = new Set(skills.map(skill => skill.name));
+        for (const expected of manifest.skills) {
+            if (!loaded.has(expected.name)) {
+                logWarn(logger, `Skill pack '${manifest.name}' declares '${expected.name}', but no verified SKILL.md was loaded`);
+            }
+        }
+    }
+    return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
+function readManifest(root, logger) {
+    const manifestPath = path.join(root.path, "skill-pack.json");
+    if (!existsSync(manifestPath))
+        return null;
+    try {
+        const raw = JSON.parse(readFileSync(manifestPath, "utf8"));
+        return SkillPackManifestSchema.parse(raw);
+    }
+    catch (err) {
+        logWarn(logger, `Invalid skill-pack.json at ${manifestPath}; skipping skill pack`, err);
+        return "invalid";
+    }
+}
+function readSkillDir(skillDir, root, manifest, logger) {
+    const skillPath = path.join(skillDir, "SKILL.md");
+    if (!existsSync(skillPath))
+        return null;
+    let content;
+    try {
+        content = readFileSync(skillPath, "utf8");
+    }
+    catch (err) {
+        logWarn(logger, `Cannot read skill file; skipping: ${skillPath}`, err);
+        return null;
+    }
+    const frontmatter = parseSkillFrontmatter(content);
+    const dirName = path.basename(skillDir);
+    const name = frontmatter.name || dirName;
+    if (!SKILL_NAME_PATTERN.test(name)) {
+        logWarn(logger, `Invalid skill name '${name}' in ${skillPath}; skipping`);
+        return null;
+    }
+    if (frontmatter.name && frontmatter.name !== dirName) {
+        logWarn(logger, `Skill frontmatter name '${frontmatter.name}' does not match directory '${dirName}'; skipping ${skillPath}`);
+        return null;
+    }
+    const packInfo = verifyManifestEntry(name, content, skillPath, root, manifest, logger);
+    if (packInfo === "skip")
+        return null;
+    return {
+        name,
+        content,
+        description: frontmatter.description || name,
+        source: root.source,
+        path: skillPath,
+        pack: packInfo,
+    };
+}
+function verifyManifestEntry(name, content, skillPath, root, manifest, logger) {
+    if (!manifest)
+        return null;
+    const expected = manifest.skills.find(skill => skill.name === name);
+    if (!expected) {
+        logWarn(logger, `Skill pack '${manifest.name}' does not list '${name}' in skill-pack.json; skipping ${skillPath}`);
+        return "skip";
+    }
+    const actual = createHash("sha256").update(content, "utf8").digest("hex");
+    if (actual.toLowerCase() !== expected.sha256.toLowerCase()) {
+        logWarn(logger, `Skill pack '${manifest.name}' hash mismatch for '${name}'; skipping ${skillPath}`);
+        return "skip";
+    }
+    return {
+        name: manifest.name,
+        version: manifest.version,
+        manifestPath: path.join(root.path, "skill-pack.json"),
+        verified: true,
+    };
+}
+function parseSkillFrontmatter(content) {
+    const match = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!match)
+        return { name: null, description: null };
+    return {
+        name: scalarFrontmatterValue(match[1], "name"),
+        description: scalarFrontmatterValue(match[1], "description"),
+    };
+}
+function scalarFrontmatterValue(frontmatter, key) {
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const match = frontmatter.match(new RegExp(`^${escapedKey}:\\s*(.+?)\\s*$`, "m"));
+    if (!match)
+        return null;
+    return match[1].replace(/^["']|["']$/g, "").trim();
+}

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "llm-cli-gateway",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "llm-cli-gateway",
-      "version": "2.14.0",
+      "version": "2.15.0",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.29.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-cli-gateway",
-  "version": "2.14.0",
+  "version": "2.15.0",
   "mcpName": "io.github.verivus-oss/llm-cli-gateway",
   "description": "Local-first MCP gateway for cross-model review across native coding-agent CLIs and API-token LLMs with sessions, durable jobs, and validation receipts.",
   "license": "MIT",
@@ -58,6 +58,7 @@
     ".agents/skills/session-workflow/SKILL.md",
     ".agents/skills/secure-orchestration/SKILL.md",
     ".agents/skills/implement-review-fix/SKILL.md",
+    ".agents/skills/retrospective-walk/SKILL.md",
     ".agents/skills/public-demo-session/SKILL.md"
   ],
   "scripts": {