agent-skillboard 0.2.3 → 0.2.4

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+## 0.2.4 — 2026-07-03
+
+### Changed
+
+- `skillboard uninstall --purge` now removes the entire `.skillboard/` project
+  state directory, including source caches, rollout logs, variant snapshots, and
+  profiles, while preserving local skill files.
+
 ## 0.2.3 — 2026-07-03
 
 ### Added

package/README.md

@@ -125,8 +125,9 @@ npx --yes --package agent-skillboard skillboard uninstall --dir /path/to/your/pr
 npx --yes --package agent-skillboard skillboard uninstall --dir /path/to/your/project --purge
 ```
 
-`--purge` deletes SkillBoard config, reports, hooks, bridge blocks, and empty
-generated directories while leaving `skills/*/SKILL.md` in place.
+`--purge` deletes SkillBoard config, bridge blocks, and the entire
+`.skillboard/` project state directory while leaving `skills/*/SKILL.md` in
+place.
 
 See [docs/install.md](docs/install.md) for global installs, `--dir`, GitHub
 builds, clone-based development, Hermes bridge setup, refresh, and uninstall.

package/docs/install.md

@@ -319,9 +319,11 @@ skillboard uninstall --dir /path/to/your/project --purge --dry-run
 skillboard uninstall --dir /path/to/your/project --purge
 ```
 
-`--purge` removes SkillBoard config, reports, hooks, bridge blocks, and empty
-generated directories. It preserves local `skills/` files because skills that
-were created or deleted are outside the uninstall scope.
+`--purge` removes SkillBoard config, bridge blocks, and the entire
+`.skillboard/` project state directory, including reports, hooks, source caches,
+rollout logs, variant snapshots, and profiles. It preserves local `skills/`
+files because skills that were created or deleted are outside the uninstall
+scope.
 
 Use `--remove-config` to delete `skillboard.config.yaml` only when it still
 matches the untouched default config. If the config contains scanned skills or
@@ -342,8 +344,9 @@ Add `--remove-hooks` only when a reset should also delete the entire
 `.skillboard/hooks/` directory contents. This is explicit because hook scripts
 may be wired into local agent/runtime configuration. Combine `--reset-config`,
 `--remove-reports`, and `--remove-hooks` for a clean test reset that removes
-SkillBoard-owned lifecycle scaffolding while preserving local `skills/`. The
-equivalent short form is `--purge`.
+the most common SkillBoard-owned lifecycle scaffolding while preserving local
+`skills/`. Use `--purge` instead when no `.skillboard/` project state should
+remain at all.
 
 ## Upper-Layer Control
 

package/docs/user-flow.md

@@ -288,8 +288,6 @@ skillboard init
 Use `--purge` when you want SkillBoard's allow/block/preference influence gone
 from the project while keeping local skill files. It discards the current
 SkillBoard config even if it contains imported skills or workflow edits,
-discards generated dashboard and impact reports, and removes the entire
-`.skillboard/hooks/` directory contents. It is equivalent to
-`--reset-config --remove-reports --remove-hooks`, so `.skillboard/` can
-disappear when no other SkillBoard state remains. Local `skills/` files stay in
-place.
+removes generated dashboard and impact reports, and removes the entire
+`.skillboard/` project state directory, including hooks, source caches, rollout
+logs, variant snapshots, and profiles. Local `skills/` files stay in place.

package/docs/versioning.md

@@ -8,7 +8,7 @@ source profiles, and the generated lockfile.
 
 ## Status
 
-Current package version: `0.2.3`
+Current package version: `0.2.4`
 
 Current config schema version:
 
@@ -59,7 +59,7 @@ must call them out clearly.
 Suggested tags:
 
 - `v0.1.0-alpha`: first public GitHub alpha.
-- `v0.2.3`: one-time runtime source review before manual activation, ask-after
+- `v0.2.4`: one-time runtime source review before manual activation, ask-after
   skill routing, purge uninstall, README benefit-first positioning,
   source inventory refresh, doctor/status, source pin refresh,
   installer/config detection, resilient detector warnings, and richer dry-run
@@ -194,8 +194,8 @@ Before tagging a public release:
   provenance with GitHub Actions OIDC, so keep `permissions.id-token: write`,
   the npm registry URL in `setup-node`, and
   `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` on the publish step.
-- Push a version tag that exactly matches `package.json`, for example `v0.2.3`
-  for package version `0.2.3`.
+- Push a version tag that exactly matches `package.json`, for example `v0.2.4`
+  for package version `0.2.4`.
 - Let `.github/workflows/publish.yml` publish from the tag. The workflow runs
   the full check suite, validates that the tag matches the package version, and
   skips `npm publish` only when that exact version already exists on npm.
@@ -229,6 +229,13 @@ completion notes:
 - update README quick-start to verify the installed version before running
   policy commands.
 
+## 0.2.4 Completion Notes
+
+- broaden `skillboard uninstall --purge` from reports/hooks cleanup to removal
+  of the full `.skillboard/` project state directory, covering source caches,
+  rollout logs, variant snapshots, profiles, hooks, and reports while preserving
+  local skill files.
+
 ## 0.2.3 Completion Notes
 
 - add `skillboard uninstall --purge` for users who want SkillBoard's policy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-skillboard",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Let AI agents pick and use allowed skills in each workflow.",
   "keywords": [
     "ai-agent",

package/src/cli.mjs

@@ -1633,8 +1633,8 @@ function uninstallHelpText() {
     "  --keep-empty-dirs   Preserve empty generated directories.",
     "",
     "Purge:",
-    "  Equivalent to --reset-config --remove-reports --remove-hooks.",
-    "  It removes SkillBoard config, reports, hooks, bridge blocks, and empty generated dirs.",
+    "  Removes SkillBoard config, bridge blocks, and the entire .skillboard/ project state directory.",
+    "  This includes reports, hooks, source caches, rollout logs, variant snapshots, and profiles.",
     "  It does not delete local skills under skills/.",
     ""
   ].join("\n");

package/src/lifecycle-cli.mjs

@@ -54,6 +54,7 @@ export async function runUninstallCommand(options, stdout) {
     resetConfig: resetConfig || purge,
     removeReports: options.get("remove-reports") === "true" || purge,
     removeHooks: options.get("remove-hooks") === "true" || purge,
+    removeProjectState: purge,
     removeEmptyDirs: options.get("keep-empty-dirs") !== "true"
   });
   stdout.write(`${result.dryRun ? "Dry run: " : ""}Uninstalled SkillBoard: ${root}\n`);

package/src/uninstall.mjs

@@ -19,14 +19,6 @@ export async function uninstallProject(options) {
     recordFileResult(filename, result, { removed, updated, preserved });
   }
 
-  for (const entry of generatedFiles(root)) {
-    const result = await removeGeneratedFile(entry.path, entry.expected, dryRun);
-    if (result === "removed") {
-      plannedRemovedPaths.add(entry.path);
-    }
-    recordFileResult(entry.label, result, { removed, updated, preserved });
-  }
-
   if (options.resetConfig === true) {
     const path = join(root, "skillboard.config.yaml");
     const result = await removeConfigFile(path, dryRun);
@@ -45,7 +37,24 @@ export async function uninstallProject(options) {
     preserved.push("skillboard.config.yaml");
   }
 
-  if (options.removeReports === true) {
+  if (options.removeProjectState === true) {
+    const path = join(root, ".skillboard");
+    const result = await removeProjectStateDir(path, dryRun);
+    if (result === "removed") {
+      plannedRemovedPaths.add(path);
+    }
+    recordFileResult(".skillboard", result, { removed, updated, preserved });
+  } else {
+    for (const entry of generatedFiles(root)) {
+      const result = await removeGeneratedFile(entry.path, entry.expected, dryRun);
+      if (result === "removed") {
+        plannedRemovedPaths.add(entry.path);
+      }
+      recordFileResult(entry.label, result, { removed, updated, preserved });
+    }
+  }
+
+  if (options.removeReports === true && options.removeProjectState !== true) {
     const path = join(root, ".skillboard", "reports");
     const result = await removeGeneratedDir(path, dryRun);
     if (result === "removed") {
@@ -54,7 +63,7 @@ export async function uninstallProject(options) {
     recordFileResult(".skillboard/reports", result, { removed, updated, preserved });
   }
 
-  if (options.removeHooks === true) {
+  if (options.removeHooks === true && options.removeProjectState !== true) {
     const path = join(root, ".skillboard", "hooks");
     const result = await removeGeneratedDir(path, dryRun);
     if (result === "removed") {
@@ -66,7 +75,8 @@ export async function uninstallProject(options) {
   if (options.removeEmptyDirs !== false) {
     for (const dir of emptyDirs(root, {
       skipReports: options.removeReports === true,
-      skipHooks: options.removeHooks === true
+      skipHooks: options.removeHooks === true,
+      skipSkillboard: options.removeProjectState === true
     })) {
       const result = await removeEmptyDir(dir.path, dryRun, plannedRemovedPaths);
       if (result === "removed") {
@@ -109,6 +119,9 @@ function emptyDirs(root, options = {}) {
     if (options.skipHooks === true && dir.label === ".skillboard/hooks") {
       return false;
     }
+    if (options.skipSkillboard === true && dir.label.startsWith(".skillboard")) {
+      return false;
+    }
     return true;
   });
 }
@@ -210,6 +223,26 @@ async function removeGeneratedDir(path, dryRun) {
   return "removed";
 }
 
+async function removeProjectStateDir(path, dryRun) {
+  const stats = await pathStats(path);
+  if (stats === null) {
+    return "absent";
+  }
+  if (stats.isSymbolicLink()) {
+    if (!dryRun) {
+      await rm(path);
+    }
+    return "removed";
+  }
+  if (!stats.isDirectory()) {
+    return "preserved";
+  }
+  if (!dryRun) {
+    await rm(path, { recursive: true });
+  }
+  return "removed";
+}
+
 async function removeEmptyDir(path, dryRun, plannedRemovedPaths) {
   const stats = await pathStats(path);
   if (stats === null) {