showdar-skills 0.8.1 → 0.10.0

package/CHANGELOG.md

@@ -4,7 +4,76 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
-## [0.8.1]
+## [Unreleased]
+
+## [0.10.0]
+
+### Added
+
+- `showdar update-pack <path> --dry-run` read-only snapshot preview using the same canonical planning logic as execution; explicit public projection with deterministic ordering, descriptive change categories (`source-only`, `skill-content`, `workflow-definition`, `profile-definition`, `metadata`, `reference`, `ownership`, `installed-drift`), and `executable` status.
+- Canonical internal pack update planning (`src/pack-plan.js`): `planPackUpdate()`, `verifyPlanPreconditions()`, `executePackUpdate()` with same-lifecycle TOCTOU fingerprint protection (source, installed owned files, relevant manifest state, overrides bytes). Stale plans abort with zero mutation.
+- `showdar inspect-pack <path> --checkpoint <file>` checkpoint compatibility explanation against the candidate effective catalog (current project + candidate pack + project overrides). Deterministic semantic reason codes (`workflow-missing`, `workflow-state-compat-unsupported`, `stage-removed`, `selected-stage-invalid`, `required-stage-conflict`, `skip-policy-invalid`, `recorded-skip-invalid`) with fixed precedence; malformed checkpoints report `schema-invalid` / `malformed-checkpoint`.
+- `showdar list --extensions --json` and `showdar doctor --extensions --json` using the common CLI envelope (`schemaVersion: 1`). Doctor reports `checkpointCompatibility: "not-assessed"` without a checkpoint. Diagnostics exit 0 on successful report.
+
+### Changed
+
+- `src/pack-update.js` refactored around canonical planning; v0.9 staged replacement and rollback safety preserved.
+- `list --extensions` human output now shows pack health status and pack profiles.
+- `create-pack` skill scaffold cleaned up (full required sections, substantive guidance, no filler) with validation guidance output.
+- TOCTOU lifecycle clarified: `--dry-run` is a read-only snapshot, not an authorization token. A later `update-pack` re-plans from current state. Stale-plan protection applies within a single execution lifecycle (`planPackUpdate` → `verifyPlanPreconditions` → `executePackUpdate`).
+
+### Fixed
+
+- `inspectCustomWorkflows` read `validateCustomWorkflowDoc` as `{ok, errors}` but the validator returns an error array, so `valid` was always `undefined` and doctor reported every workflow invalid. Now maps `errors.length === 0` to `valid`. Internal helper shape only; public CLI output unchanged.
+- `executePackUpdate` referenced undefined `manifestPath`; now resolves the project manifest path before writing. Covered by real update-path regression test.
+
+### Compatibility / Safety
+
+- v0.9 `validate-pack --json` (`{ok, errors}`) and plain `inspect-pack --json` shapes unchanged; backward-compat fixture tests added.
+- No persisted preview plans or tokens. No manifest v3, no workflow-state schema change, no WorkflowState key change.
+- Phase 6G authority, 15 primitives, 4 workflows, 6 profiles, 10 trace events frozen.
+- Dry-run is a snapshot, not a stored plan. No migration required. No tarball, remote registry, or executable plugins.
+
+## [0.9.0]
+
+### Added
+
+- Pack authoring CLI: `showdar create-pack <path>` scaffolds a minimal valid extension pack with `--vendor`, `--description`, `--with-workflow`, `--with-profile` flags; no interactive wizard.
+- Pack validation CLI: `showdar validate-pack <path> [--json]` performs dry-run validation without installation; deterministic JSON output.
+- Pack inspection CLI: `showdar inspect-pack <path> [--json]` outputs normalized read-only model (source, identity, skills, workflows, profiles, domains, full-tree hash, drift, compatibility, warnings, errors).
+- Pack diagnostics CLI: `showdar doctor --extensions` read-only diagnostics for installed extensions (source drift, ownership, catalog, overrides, profile refs, catalog build failures, collisions).
+- Pack update CLI: `showdar update-pack <local-path>` safe staged replacement with rollback; validates candidate before replacement; preserves overrides/foreign files; refuses unsafe overwrite; no network access.
+- Checkpoint compatibility assessment layer: `assessCheckpointCompatibility(checkpoint, extensionCatalog)` returns ephemeral `{compatible, replanRequired, reason}`; strict deserialization preserved; invalid checkpoints yield `workflow-incompatible` + `replanRequired` without fabricating BLOCKED WorkflowState; malformed checkpoints distinct from policy incompatibility.
+- Structured extension error model: 12 categories (`schema-invalid`, `namespace-invalid`, `collision`, `protected-field`, `unsafe-path`, `source-unavailable`, `source-unsupported`, `ownership-conflict`, `workflow-incompatible`, `profile-reference-invalid`, `override-invalid`, `drift-detected`) with stable codes and human messages; separate from drift.
+- Custom workflow description minimum lowered from 30 to 10 characters.
+- Source drift vs workflow incompatibility separation: source drift (`source-drift`) is hash-based identity change; workflow incompatibility (`workflow-incompatible`) is current-catalog validation failure; never conflated.
+- `showdar doctor --extensions` reports source drift and workflow compatibility separately (`source.drift`, `workflow.compatibility`); `inspect-pack --json` exposes normalized model; `list --extensions` grouped output with drift status.
+- Override precedence inspection: effective value + source (`built-in`/`pack:<name>`/`project-override`) + `protected` flag via `--json` surfaces.
+- Update-pack safety: staged replacement with rollback; validates candidate before replacement; preserves overrides/foreign files; refuses unsafe overwrite; no network access; fails on ownership conflict/missing managed file; workflow removal validation; manifest updated only after successful replacement.
+- Override precedence inspection via `computePrecedence` in `pack-inspect.js`: per-field effective value, source (`built-in`/`pack:<name>`/`project-override`), protected flag.
+- Custom workflow description minimum lowered from 30 to 10 characters (schema + validator).
+- Domain cap remains 8 with improved validation messages; domains remain discovery-only hints.
+- Error model: 12 structured categories with stable machine-readable codes + human messages; `drift-detected` distinct from `workflow-incompatible`.
+
+### Changed
+
+- `showdar doctor --extensions` now supports `--extensions` flag for extension diagnostics.
+- `showdar list --extensions` output improved: grouped PACKS/WORKFLOWS/PROFILES/OVERRIDES with drift status.
+- Custom workflow description minimum lowered 30 → 10 (schema + validator).
+- `validate-pack` uses existing canonical validation path; `--json` for machine-readable output.
+- `inspect-pack` outputs deterministic normalized model (human + `--json`).
+- Source drift (`source-drift`) and workflow incompatibility (`workflow-incompatible`) are distinct concepts with separate reporting.
+- `update-pack` warns on workflow definition changes: "Existing checkpoints referencing changed custom workflows will be revalidated on resume."
+
+### Security
+
+- `update-pack` refuses unsafe overwrite; validates candidate before replacement; staged replacement with atomic finalization; rollback on failure; overrides and foreign files preserved byte-identical; no network access; no lifecycle scripts/hooks; local directory sources only.
+
+### Fixed
+
+- Custom workflow description minimum lowered from 30 to 10 characters.
+- Extension error categories now structured with stable codes and human messages.
+- Source drift and workflow incompatibility are no longer conflated in reporting.
 
 ### Fixed
 

package/README.md

@@ -557,7 +557,7 @@ is idempotent, preserves the configured profile, supports `--ai`/`--scope`
 overrides, and refuses to overwrite a foreign same-name skill directory that
 Showdar does not own.
 
-## Extensions (0.8.0)
+## Extensions (0.9.0)
 
 Extension packs are local, static, declarative directories installed from a
 local directory or workspace-relative path. A pack carries `pack.json`
@@ -565,16 +565,65 @@ metadata (name, version, skills, workflows, pack-local profiles), skill
 directories, custom workflow definitions, and docs. Packs contain no
 executable hooks, lifecycle scripts, or remote code.
 
+**Pack authoring & validation**
+
 ```bash
-showdar add-pack ../acme-pack
-showdar list --extensions
-showdar remove-pack acme
+showdar create-pack <path> [--vendor <v>] [--description <text>] [--with-workflow <id>] [--with-profile <name>]
+showdar validate-pack <local-path> [--json]
+showdar inspect-pack <local-path> [--json] [--checkpoint <file>]
+```
+
+**Install & lifecycle**
+
+```bash
+showdar add-pack <local-path>
+showdar list --extensions [--json]
+showdar remove-pack <name>
+showdar update-pack <local-path> [--dry-run] [--json]
+```
+
+**Diagnostics**
+
+```bash
+showdar doctor --extensions [--json]
+```
+
+`update-pack --dry-run` previews changes without mutation: file add/replace/remove
+counts, descriptive change categories (`source-only`, `skill-content`,
+`workflow-definition`, `profile-definition`, `metadata`, `reference`,
+`ownership`, `installed-drift`), ownership conflicts, and whether the update is
+currently executable. Categories are descriptive only and never claim checkpoint
+compatibility. The preview is a read-only snapshot, not an authorization token:
+a later `update-pack` re-plans from current state. Within a single update
+execution, if source, installed files, manifest, or overrides change between
+planning and applying that same plan, execution aborts as a stale plan with
+zero mutation.
+
+`inspect-pack --checkpoint` validates a workflow checkpoint against the candidate
+effective catalog (current project state + candidate pack + project overrides) and
+reports `compatible`, `workflow-incompatible` (with deterministic reason code and
+`replanRequired`), or `malformed`. Malformed checkpoints report `schema-invalid` /
+`malformed-checkpoint`, never `workflow-incompatible`.
+
+`list --extensions --json` and `doctor --extensions --json` use the common CLI
+envelope (`schemaVersion: 1`, `command`, `ok`, `data`, `warnings`, `errors`).
+Existing `validate-pack --json` and plain `inspect-pack --json` shapes are
+unchanged. `doctor` without a checkpoint reports `checkpointCompatibility:
+"not-assessed"`. Diagnostics exit 0 when they successfully report state, even when
+unhealthy; validation and execution failures exit 1.
+
+**Pack metadata**
+
+```bash
+showdar add-workflow <local-path>
+showdar init --pack <local-path>
 ```
 
 Pack skill IDs use the `vendor/skill` namespace (for example,
 `acme/lint`); the `showdar-` prefix is reserved for built-ins. Skill
 `domains` are lowercase kebab-case discovery hints only (at most 8 per
 skill) — they never create capabilities, routes, or authority.
+Custom workflow description minimum is 10 characters.
 
 Custom workflows compose built-in primitive stages under a `vendor-name`
 ID (for example, `acme-release`). Stages, skip rules, and completion
@@ -599,12 +648,23 @@ Showdar computes a full-tree SHA-256 over the validated pack source at
 install and records it in `.showdar.json` (`extensions.packs[].hash`).
 The hash is source-tree identity — a docs-only edit changes it without
 implying any behavior change. Drift means the source tree differs from
-the recorded installation source.
+the recorded installation source. Source drift (`source-drift`) and
+workflow incompatibility (`workflow-incompatible`) are separate concerns.
+
+**Checkpoint compatibility**: Custom workflow checkpoints are revalidated
+against the current explicit extension catalog at resume. A valid checkpoint
+resumes normally. A checkpoint with a skip or stage no longer permitted by
+the current workflow definition yields a `workflow-incompatible` outcome
+with `replanRequired=true` — it is never fabricated into a `BLOCKED`
+WorkflowState. Malformed checkpoints remain distinct from workflow
+incompatibility. No pack hash, workflow fingerprint, or catalog snapshot is
+persisted in checkpoints; `schemaVersion` remains 1.
 
 Extensions cannot create capabilities, grant authority, modify Phase 6G,
 change built-in workflow semantics or profiles, or execute arbitrary
 code. Supported sources are local directories and workspace-relative
-paths; tarball, URL, Git, and npm/registry sources are rejected in 0.8.
+paths; tarball, URL, Git, and npm/registry sources are rejected.
+Executable plugins/hooks are not supported.
 
 Opt-in custom workflow evaluation (never part of the release gate):
 
@@ -615,6 +675,22 @@ node scripts/custom-workflows-eval.mjs \
   --pack .tmp/custom-eval-fixture/acme-pack/pack.json
 ```
 
+## Diagnostics (0.9.0)
+
+```bash
+showdar doctor --extensions
+```
+
+Read-only diagnostics for installed extension state:
+- manifest entries valid, installed files exist, ownership intact
+- source drift (`source-drift`, `source-unavailable`, `installed-file-drift`, `ownership-conflict`)
+- invalid overrides, duplicate/collision, broken profile references
+- catalog construction failures
+- source drift vs workflow incompatibility reported separately
+
+Byte-for-byte override preservation is enforced; `.showdar/overrides.json` is
+never rewritten by Showdar during any lifecycle operation.
+
 ## Routing
 
 Showdar routes each request through progressive disclosure: the host discovers
@@ -656,6 +732,13 @@ showdar list
 showdar list --extensions
 showdar status [--scope <project|global>]
 showdar doctor [--scope <project|global>]
+showdar doctor --extensions
+showdar validate
+showdar remove [--scope <project|global>]
+showdar create-pack <path> [--vendor <v>] [--description <text>] [--with-workflow <id>] [--with-profile <name>]
+showdar validate-pack <local-path> [--json]
+showdar inspect-pack <local-path> [--json]
+showdar update-pack <local-path>
 showdar validate
 showdar remove [--scope <project|global>]
 ```

package/bin/showdar.js

@@ -4,7 +4,9 @@ import { homedir } from 'node:os';
 import { readFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { AI_TARGETS, PRIMITIVE_COUNT, PROFILE_ALIASES, PROFILES, SKILLS, TOTAL_COUNT, WORKFLOW_COUNT, canonicalProfile, isDeprecatedProfile, resolveProfile } from '../src/catalog.js';
-import { addPack, addSkill, addWorkflow, globalManifestPath, initGlobal, initProject, inspectGlobal, inspectProject, listExtensions, removeGlobal, removePack, removeProject } from '../src/project.js';
+import { addPack, addSkill, addWorkflow, globalManifestPath, initGlobal, initProject, inspectGlobal, inspectProject, listExtensions, listExtensionsDetailed, removeGlobal, removePack, removeProject, validatePackSource, createPack, inspectPack, doctor, updatePack, readProjectOverrides } from '../src/project.js';
+import { formatPlanPreviewHuman, projectPackUpdatePreview } from '../src/pack-plan.js';
+import { assessCheckpointAgainstCandidate } from '../src/pack-inspect.js';
 import { validateRepository } from '../src/validate.js';
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -43,7 +45,7 @@ function printHelp(version, command = null) {
     console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n\nExamples:\n  showdar add debug\n  showdar add showdar-security\n  showdar add test --ai cursor\n  showdar add review --scope global --ai claude\n\nDefault scope: project. Default AI target: universal, or the configured .showdar.json value when present.`);
     return;
   }
-  console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>] [--pack <local-path>]\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n  showdar add-pack <local-path>\n  showdar remove-pack <name>\n  showdar add-workflow <local-path>\n  showdar status ${scopeUsage}\n  showdar doctor ${scopeUsage}\n  showdar validate\n  showdar list [--extensions]\n  showdar remove ${scopeUsage}\n\nExtension packs accept local directories/workspace paths only; tarball, URL, Git, and registry sources are rejected.\n\nDefaults: scope project, profile full, AI target universal.\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
+  console.log(`Showdar Skills ${version}\n\nUsage:\n  showdar init ${scopeUsage} [--profile <name>] [--ai <universal|codex|opencode|cursor|claude|all>] [--pack <local-path>]\n  showdar add <skill> [--ai <universal|codex|opencode|cursor|claude>] [--scope <project|global>]\n  showdar add-pack <local-path>\n  showdar remove-pack <name>\n  showdar add-workflow <local-path>\n  showdar status ${scopeUsage}\n  showdar doctor ${scopeUsage}\n  showdar validate\n  showdar list [--extensions]\n  showdar remove ${scopeUsage}\n  showdar create-pack <path> [--vendor <vendor>] [--description <text>] [--with-workflow <id>] [--with-profile <name>]\n  showdar validate-pack <local-path> [--json]\n  showdar inspect-pack <local-path> [--json] [--checkpoint <file>]\n  showdar doctor ${scopeUsage} [--extensions] [--json]\n  showdar update-pack <local-path> [--dry-run] [--json]\n  showdar validate\n  showdar list [--extensions] [--json]\n  showdar remove ${scopeUsage}\n\nExtension packs accept local directories/workspace paths only; tarball, URL, Git, and registry sources are rejected.\n\nDefaults: scope project, profile full, AI target universal.\nProfiles: ${Object.keys(PROFILES).join(', ')}\nDeprecated aliases: ${Object.entries(PROFILE_ALIASES).map(([alias, target]) => `${alias} -> ${target}`).join(', ')}\nAI targets: ${AI_TARGETS.join(', ')}`);
 }
 
 async function main() {
@@ -63,11 +65,20 @@ async function main() {
 
   if (command === 'list') {
     if (args.includes('--extensions')) {
-      const result = await listExtensions({ cwd: projectRoot });
+      const isJson = args.includes('--json');
+      const result = await listExtensionsDetailed({ cwd: projectRoot });
+      if (isJson) {
+        console.log(JSON.stringify({ schemaVersion: 1, command: 'list', ok: true, data: result, warnings: [], errors: [] }, null, 2));
+        return;
+      }
       console.log('Packs:');
-      for (const pack of result.packs) console.log(`  ${pack.name}@${pack.version}  ${pack.hash}`);
+      for (const pack of result.packs) console.log(`  ${pack.name}@${pack.version}  ${pack.status ?? 'healthy'}  ${pack.hash}`);
       console.log('Custom workflows:');
       for (const workflow of result.customWorkflows) console.log(`  ${workflow.id}  [${workflow.source}]  ${workflow.path}`);
+      if (result.profiles?.length) {
+        console.log('Pack profiles:');
+        for (const profile of result.profiles) console.log(`  ${profile.name}  [${profile.source}]  members: ${(profile.members ?? []).join(', ')}`);
+      }
       console.log(`Project overrides: ${result.overrides.present ? result.overrides.status : 'absent'}`);
       return;
     }
@@ -140,6 +151,31 @@ async function main() {
   }
 
   if (command === 'status' || command === 'doctor') {
+    if (command === 'doctor' && args.includes('--extensions')) {
+      const isJson = args.includes('--json');
+      const result = await doctor({ cwd: projectRoot });
+      if (isJson) {
+        console.log(JSON.stringify({
+          schemaVersion: 1,
+          command: 'doctor',
+          ok: true,
+          data: { ...result, checkpointCompatibility: 'not-assessed' },
+          warnings: result.warnings ?? [],
+          errors: [],
+        }, null, 2));
+        return;
+      }
+      console.log(`Extension diagnostics\nHealth: ${result.healthy ? 'OK' : 'BROKEN'}`);
+      for (const pack of result.packs) console.log(`  ${pack.name}@${pack.version}  ${pack.drift}`);
+      for (const wf of result.customWorkflows) console.log(`  workflow ${wf.id}: ${wf.valid ? 'valid' : 'invalid'}`);
+      for (const issue of result.issues) console.log(`- ${issue}`);
+      for (const warning of result.warnings ?? []) console.log(`warning: ${warning}`);
+      if (!result.healthy) {
+        console.log(`Checkpoint compatibility: not-assessed (supply a checkpoint via inspect-pack --checkpoint)`);
+        if (result.customWorkflows.length) console.log(`Note: checkpoints referencing changed workflow definitions will be revalidated on resume.`);
+      }
+      return;
+    }
     const result = scope === 'global' ? await inspectGlobal() : await inspectProject(projectRoot);
     if (!result.installed) {
       console.log(`Showdar Skills is not installed in the ${scope} scope.`);
@@ -180,7 +216,129 @@ async function main() {
     return;
   }
 
-  throw new Error(`Unknown command "${command}". Run "showdar --help".`);
+  if (command === 'create-pack') {
+    const packPath = args[1];
+    if (!packPath) throw new Error('Pack path is required. Usage: showdar create-pack <path> [--vendor <vendor>] [--description <text>] [--with-workflow <id>] [--with-profile <name>]');
+    const vendor = valueAfter(args, '--vendor', 'custom');
+    const description = valueAfter(args, '--description', null);
+    const withWorkflow = valueAfter(args, '--with-workflow', null);
+    const withProfile = valueAfter(args, '--with-profile', null);
+    const result = await createPack({ cwd: projectRoot, path: packPath, vendor, description, withWorkflow, withProfile });
+    console.log(`Showdar pack scaffolded.\nPack: ${result.manifest.name}\nVersion: ${result.manifest.version}\nSkill: ${result.skillId}${result.workflowId ? `\nWorkflow: ${result.workflowId}` : ''}${result.profileName ? `\nProfile: ${result.profileName}` : ''}\nPath: ${result.packDir}`);
+    return;
+  }
+
+  if (command === 'validate-pack') {
+    const packPath = args[1];
+    if (!packPath) throw new Error('Pack path is required. Usage: showdar validate-pack <local-path> [--json]');
+    const isJson = args.includes('--json');
+    const result = await validatePackSource({ cwd: projectRoot, source: packPath });
+    if (isJson) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      if (result.ok) {
+        console.log(`Pack validation OK`);
+      } else {
+        console.log(`Pack validation FAILED (${result.errors.length} errors).`);
+        for (const error of result.errors) console.log(`- ${error}`);
+        process.exitCode = 1;
+      }
+    }
+    return;
+  }
+
+  if (command === 'inspect-pack') {
+    const packPath = args[1];
+    if (!packPath) throw new Error('Pack path is required. Usage: showdar inspect-pack <local-path> [--json] [--checkpoint <file>]');
+    const isJson = args.includes('--json');
+    const checkpointIdx = args.indexOf('--checkpoint');
+    const checkpointFile = checkpointIdx === -1 ? null : args[checkpointIdx + 1];
+    if (checkpointIdx !== -1 && (!checkpointFile || checkpointFile.startsWith('--'))) {
+      throw new Error('--checkpoint requires a file path');
+    }
+    if (checkpointFile) {
+      const { readFile } = await import('node:fs/promises');
+      const checkpoint = await readFile(path.resolve(projectRoot, checkpointFile), 'utf8');
+      const assessment = await assessCheckpointAgainstCandidate({ cwd: projectRoot, candidatePath: path.resolve(projectRoot, packPath), checkpoint });
+      if (isJson) {
+        console.log(JSON.stringify({ schemaVersion: 1, command: 'inspect-pack', ok: true, data: { checkpoint: assessment }, warnings: [], errors: [] }, null, 2));
+        return;
+      }
+      if (assessment.compatible) {
+        console.log(`Checkpoint compatibility: compatible\nReplan required: no`);
+        return;
+      }
+      console.log(`Checkpoint compatibility: ${assessment.category === 'schema-invalid' ? 'malformed' : 'workflow-incompatible'}\nReplan required: ${assessment.replanRequired ? 'yes' : 'no'}\nCategory: ${assessment.category}\nReason: ${assessment.reason}\nDetail: ${assessment.detail}`);
+      if (assessment.affectedWorkflow) console.log(`Affected workflow: ${assessment.affectedWorkflow}`);
+      if (assessment.affectedStage) console.log(`Affected stage: ${assessment.affectedStage}`);
+      console.log(`\nRun \`showdar update-pack <path> --dry-run\` to preview update.`);
+      return;
+    }
+    const result = await inspectPack({ cwd: projectRoot, source: packPath });
+    if (isJson) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      if (result.ok) {
+        console.log(`Pack: ${result.name}@${result.version}`);
+        console.log(`Description: ${result.description}`);
+        console.log(`Source: ${result.source}`);
+        console.log(`Full-tree hash: ${result.fullTreeHash}`);
+        console.log(`Skills: ${result.skills.length}`);
+        console.log(`Workflows: ${result.workflows.length}`);
+        console.log(`Profiles: ${Object.keys(result.profiles).length}`);
+        if (result.errors.length > 0) {
+          console.log(`Errors: ${result.errors.length}`);
+          for (const error of result.errors) console.log(`  - ${error}`);
+        }
+        if (result.warnings.length > 0) {
+          console.log(`Warnings: ${result.warnings.length}`);
+          for (const warning of result.warnings) console.log(`  - ${warning}`);
+        }
+      } else {
+        console.log(`Inspection FAILED (${result.errors.length} errors).`);
+        for (const error of result.errors) console.log(`- ${error}`);
+        process.exitCode = 1;
+      }
+    }
+    return;
+  }
+
+  if (command === 'update-pack') {
+    const packSource = args[1];
+    if (!packSource) throw new Error('Pack source is required. Usage: showdar update-pack <local-path> [--dry-run] [--json]');
+    const dryRun = args.includes('--dry-run');
+    const isJson = args.includes('--json');
+    if (dryRun) {
+      const { planPackUpdate } = await import('../src/pack-plan.js');
+      const plan = await planPackUpdate({ cwd: projectRoot, source: packSource });
+      if (isJson) {
+        console.log(JSON.stringify(projectPackUpdatePreview(plan), null, 2));
+        if (!plan.ok || !plan.executable) process.exitCode = 1;
+        return;
+      }
+      console.log(formatPlanPreviewHuman(plan));
+      if (!plan.ok || !plan.executable) process.exitCode = 1;
+      return;
+    }
+    if (isJson) {
+      try {
+        const result = await updatePack({ cwd: projectRoot, source: packSource });
+        console.log(JSON.stringify({ schemaVersion: 1, command: 'update-pack', ok: true, data: result, warnings: result.plan?.warnings ?? [], errors: [] }, null, 2));
+      } catch (error) {
+        console.log(JSON.stringify({ schemaVersion: 1, command: 'update-pack', ok: false, data: null, warnings: [], errors: [{ category: 'drift-detected', code: 'DRIFT_DETECTED', message: error.message }] }, null, 2));
+        process.exitCode = 1;
+      }
+      return;
+    }
+    try {
+      const result = await updatePack({ cwd: projectRoot, source: packSource });
+      console.log(`Showdar pack ${result.status}.\nPack: ${result.pack}\nVersion: ${result.version}${result.oldHash ? `\nOld hash: ${result.oldHash}\nNew hash: ${result.newHash}` : ''}\nFiles: ${result.files}`);
+    } catch (error) {
+      console.error(`showdar: ${error.message}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
 }
 
 main().catch((error) => {

package/config/custom-workflow.schema.json

@@ -7,7 +7,7 @@
   "additionalProperties": false,
   "properties": {
     "id": { "type": "string", "pattern": "^[a-z][a-z0-9]*-[a-z][a-z0-9-]*$" },
-    "description": { "type": "string", "minLength": 30 },
+    "description": { "type": "string", "minLength": 10 },
     "stages": {
       "type": "array",
       "minItems": 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "showdar-skills",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Production-grade software engineering lifecycle skills for coding agents.",
   "type": "module",
   "bin": { "showdar": "./bin/showdar.js" },

package/src/extension-errors.js

@@ -0,0 +1,90 @@
+const EXTENSION_ERROR_CATEGORIES = {
+  SCHEMA_INVALID: 'schema-invalid',
+  NAMESPACE_INVALID: 'namespace-invalid',
+  COLLISION: 'collision',
+  PROTECTED_FIELD: 'protected-field',
+  UNSAFE_PATH: 'unsafe-path',
+  SOURCE_UNAVAILABLE: 'source-unavailable',
+  SOURCE_UNSUPPORTED: 'source-unsupported',
+  OWNERSHIP_CONFLICT: 'ownership-conflict',
+  WORKFLOW_INCOMPATIBLE: 'workflow-incompatible',
+  PROFILE_REFERENCE_INVALID: 'profile-reference-invalid',
+  OVERRIDE_INVALID: 'override-invalid',
+  DRIFT_DETECTED: 'drift-detected',
+};
+
+const ERROR_MESSAGES = {
+  [EXTENSION_ERROR_CATEGORIES.SCHEMA_INVALID]: 'Schema validation failed',
+  [EXTENSION_ERROR_CATEGORIES.NAMESPACE_INVALID]: 'Invalid namespace/identifier',
+  [EXTENSION_ERROR_CATEGORIES.COLLISION]: 'Identifier collision detected',
+  [EXTENSION_ERROR_CATEGORIES.PROTECTED_FIELD]: 'Protected field modification not allowed',
+  [EXTENSION_ERROR_CATEGORIES.UNSAFE_PATH]: 'Unsafe path detected',
+  [EXTENSION_ERROR_CATEGORIES.SOURCE_UNAVAILABLE]: 'Source path unavailable',
+  [EXTENSION_ERROR_CATEGORIES.SOURCE_UNSUPPORTED]: 'Source type not supported',
+  [EXTENSION_ERROR_CATEGORIES.OWNERSHIP_CONFLICT]: 'Ownership conflict with existing managed files',
+  [EXTENSION_ERROR_CATEGORIES.WORKFLOW_INCOMPATIBLE]: 'Workflow definition incompatible with checkpoint',
+  [EXTENSION_ERROR_CATEGORIES.PROFILE_REFERENCE_INVALID]: 'Invalid profile reference',
+  [EXTENSION_ERROR_CATEGORIES.OVERRIDE_INVALID]: 'Invalid project override',
+  [EXTENSION_ERROR_CATEGORIES.DRIFT_DETECTED]: 'Source drift detected',
+};
+
+export class ExtensionError extends Error {
+  constructor(category, message, details = {}) {
+    super(message);
+    this.name = 'ExtensionError';
+    this.category = category;
+    this.code = category.toUpperCase().replace(/-/g, '_');
+    this.details = details;
+  }
+}
+
+export function createExtensionError(category, details = {}) {
+  const message = details.message ?? ERROR_MESSAGES[category] ?? 'Extension error';
+  return new ExtensionError(category, message, details);
+}
+
+export function isExtensionError(error) {
+  return error instanceof ExtensionError;
+}
+
+export function formatErrorForCli(error, verbose = false) {
+  if (isExtensionError(error)) {
+    const lines = [`[${error.category}] ${error.message}`];
+    if (verbose && Object.keys(error.details).length > 0) {
+      lines.push('Details:', JSON.stringify(error.details, null, 2));
+    }
+    return lines.join('\n');
+  }
+  return error.message;
+}
+
+export function formatErrorForJson(error) {
+  if (isExtensionError(error)) {
+    return {
+      category: error.category,
+      code: error.code,
+      message: error.message,
+      details: error.details,
+    };
+  }
+  return {
+    category: 'unknown',
+    code: 'UNKNOWN',
+    message: error.message,
+    details: {},
+  };
+}
+
+export { EXTENSION_ERROR_CATEGORIES, ERROR_MESSAGES };
+
+export const extensionErrorsAPI = {
+  ExtensionError,
+  createExtensionError,
+  isExtensionError,
+  formatErrorForCli,
+  formatErrorForJson,
+  categories: EXTENSION_ERROR_CATEGORIES,
+  messages: ERROR_MESSAGES,
+};
+
+export default extensionErrorsAPI;