@canonical/pragma-cli 0.33.0 → 0.35.0

package/src/capabilities/sources/index.ts

@@ -1,10 +1,10 @@
 /**
  * The `sources` capability barrel — `status` (storeless read) and `update`
- * (the resolve/build/lock Task).
+ * (the resolve/build/point Task).
  */
 
 import { asVerb } from "../../kernel/spec/asVerb.js";
-import type { CapabilityModule } from "../../kernel/spec/types.js";
+import type { CapabilityModule } from "../../kernel/spec/index.js";
 import { statusVerb } from "./status.verb.js";
 import { updateVerb } from "./update.verb.js";
 

package/src/capabilities/sources/installSkills.ts

@@ -4,33 +4,57 @@
  * Design-system packages ship a top-level `skills/<name>/SKILL.md`, but skill
  * discovery only scans the project root and the installed-skills root — never a
  * resolved package's clone/dir. So `sources update` INSTALLS each package's
- * skills into the installed-skills root (`$XDG_DATA_HOME/pragma/skills`) as
+ * skills into the installed-skills root (`$XDG_DATA_HOME/<bin>/skills`) as
  * symlinks, exactly the root `discoverSkills` already reads. Precedence is
- * preserved (a project `.pragma/skills` entry still wins — it is discovered
+ * preserved (a project `.<bin>/skills` entry still wins — it is discovered
  * first), and the update Task stays reversible (each created link carries an
  * unlink undo).
  *
+ * Installing alone leaks, because planning walks the PACKAGES and so only ever
+ * visits a skill that still exists. When a package DROPS one (a `0.1.2` that
+ * shipped `component-specifier` upgrading to a `0.2.0` that does not), the link
+ * the previous update installed is never revisited and is left dangling at a
+ * target that no longer exists — which reads as a broken install rather than the
+ * intentional removal it is, and which `skill` commands can still list or try to
+ * open. So planning ALSO walks the installed root and prunes those, under a
+ * deliberately narrow rule: an entry is removed only when this run did not plan
+ * it AND it is a symlink whose target is gone. A real directory is a
+ * manually-installed skill and a still-resolving symlink is someone's own link;
+ * neither is this update's to delete.
+ *
  * Decisions run against REAL fs here so the update's `--dry-run` plan is
  * accurate; the composed Task performs only the symlink/delete effects.
  */
 
 import { existsSync, lstatSync, readdirSync, readlinkSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
-import type { ResolvedPackage } from "../../kernel/runtime/refs/resolve.js";
+import type { ResolvedPackage } from "../../kernel/runtime/refs/index.js";
 import { installedSkillsDir } from "../skill/discover.js";
 
 /** One planned skill symlink into the installed-skills root. */
 export interface SkillLinkAction {
-  /** The package's skill folder — the symlink target. */
+  /**
+   * The symlink target: the package's skill folder for an install, or — on a
+   * `pruned` entry — the missing target the stale link still points at, kept so
+   * the prune's undo can put the link back exactly as it was.
+   */
   readonly target: string;
   /** `<installedSkillsDir>/<folderName>` — where the symlink is created. */
   readonly linkPath: string;
-  /** created (absent), skipped (already correct / a real dir), or replaced. */
-  readonly action: "created" | "skipped" | "replaced";
+  /**
+   * created (absent), skipped (already correct / a real dir), replaced, or
+   * pruned (an unplanned link whose target is gone — deleted, not re-created).
+   */
+  readonly action: "created" | "skipped" | "replaced" | "pruned";
   /** The skill folder name (the discovery key). */
   readonly folderName: string;
-  /** The package the skill came from. */
-  readonly packageName: string;
+  /**
+   * The package the skill came from. Absent on a `pruned` entry: a stale link
+   * records only a target path, and the package that installed it is precisely
+   * the one that no longer provides the skill — there is nothing honest left to
+   * attribute it to.
+   */
+  readonly packageName?: string;
 }
 
 /** What currently occupies a candidate link path. */
@@ -80,9 +104,58 @@ function packageSkillDirs(root: string): string[] {
   return out;
 }
 
+/**
+ * Plan the removal of the links a package has since dropped.
+ *
+ * The install pass walks the packages, so it can only ever visit a skill that
+ * still exists; this pass walks the installed root, which is the ONLY place a
+ * dropped skill still shows up. An entry is pruned only when both hold: this run
+ * did not plan it, and it is a symlink whose target is gone. Both halves matter —
+ *
+ * - a real (non-symlink) entry is a manually-installed skill, which the install
+ *   pass already refuses to clobber (`skipped`) and which this pass must refuse
+ *   just as firmly: "unplanned" is exactly what a hand-placed skill looks like;
+ * - a symlink whose target still resolves is someone's own link into a checkout
+ *   this command knows nothing about. Unplanned does not make it garbage, and an
+ *   update that silently ate it would be a worse bug than the dangling link.
+ *
+ * A broken target, by contrast, cannot be anything but debris: nothing can read
+ * it, and re-creating it is a matter of re-running the update that installed it
+ * (which is also what this prune's undo does).
+ *
+ * @param dest - The installed-skills root.
+ * @param planned - Every folder name the install pass planned, whatever action.
+ * @returns One `pruned` action per stale link, for the plan and its preview.
+ * @note Impure — reads the installed root and stats each entry's target.
+ */
+function planStaleLinkPrunes(
+  dest: string,
+  planned: ReadonlySet<string>,
+): SkillLinkAction[] {
+  let names: string[];
+  try {
+    names = readdirSync(dest);
+  } catch {
+    return []; // No installed root — nothing was ever installed to go stale.
+  }
+  const out: SkillLinkAction[] = [];
+  for (const folderName of names) {
+    if (planned.has(folderName)) continue;
+    const linkPath = resolve(dest, folderName);
+    const state = linkState(linkPath);
+    if (state.kind !== "symlink") continue;
+    // A relative target is stored relative to the link's OWN directory, which
+    // for an entry of the installed root is that root itself.
+    if (existsSync(resolve(dest, state.target))) continue;
+    out.push({ target: state.target, linkPath, action: "pruned", folderName });
+  }
+  return out;
+}
+
 /**
  * Plan the symlink actions that install each resolved package's `skills/*` into
- * the installed-skills discovery root. First-seen wins on a folder-name clash
+ * the installed-skills discovery root, then the removals that retire the links
+ * a package has since dropped. First-seen wins on a folder-name clash
  * across packages. A real (non-symlink) entry at the link path is left untouched
  * (`skipped`) so a manually-installed skill is never clobbered.
  *
@@ -120,5 +193,9 @@ export function planSkillInstall(
       });
     }
   }
+  // `seen` is every folder name this run planned — the `skipped` ones included,
+  // so a name a package still provides is never a prune candidate even when the
+  // install pass decided to leave its entry alone.
+  actions.push(...planStaleLinkPrunes(dest, seen));
   return actions;
 }

package/src/capabilities/sources/runUpdate.ts

@@ -5,18 +5,19 @@
  *
  * - Preview (CLI `--dry-run`, or MCP without `confirm`): NETWORK-FREE. It reads
  *   only the config, then hands back a plan-only Task listing the refs it would
- *   resolve+build and the lock it would write — no git fetch, no compile, no
+ *   resolve+build and the pointer it would write — no git fetch, no compile, no
  *   cache write. This is what a dry-run / agent "preview" must be: side-effect
  *   free and offline-safe.
- * - Real execution: the heavy work — resolve every configured package (git
+ * - Real execution: the heavy work — resolve every configured pack (git
  *   clone/fetch, file verify, npm resolve), then build the ONE combined
  *   content-addressed pack — runs eagerly (it is not expressible as a task
  *   effect: the effect set is fs + exec, and the in-process compile is not an
- *   effect at all). The returned Task models the one project mutation, the
- *   `pragma.lock.json` write, with an undo that restores (or removes) the prior
- *   lock. Under `--frozen` each package re-resolves to the lock's pinned
- *   revision and keeps its `resolvedAt`, so an unchanged update rewrites a
- *   byte-identical lock.
+ *   effect at all). The returned Task models the mutations: the active-pack
+ *   pointer write (undo restores or removes the prior pointer) and the package
+ *   skill symlinks.
+ *
+ * Pinning a revision is the ref's job, not a flag's: put a SHA in the source
+ * (`git+https://…#<sha>`) and every update resolves to exactly that commit.
  */
 
 import {
@@ -29,29 +30,25 @@ import {
   type Task,
   writeFile,
 } from "@canonical/task";
-import { RECOVERY_CLI_PREFIX, VERSION } from "../../constants.js";
-import type { PackageEntry } from "../../kernel/config/types.js";
-import { PragmaError } from "../../kernel/error/PragmaError.js";
-import { cliRecovery } from "../../kernel/error/recovery.js";
+import { VERSION } from "../../constants.js";
+import { cliRecovery, PragmaError } from "../../kernel/error/index.js";
+// DIRECT LEAF IMPORT, not `graphpack/index.js`. The barrel re-exports
+// `embedded.ts`, which statically imports the ~1.9 MB generated pack — and
+// with per-file `tsc` output ESM evaluates that re-export when this module
+// loads. `sources update` builds a USER pack; it must not pay the embedded
+// pack's cost to do it.
 import { buildPack } from "../../kernel/runtime/graphpack/build.js";
-import {
-  type PragmaLock,
-  readLock,
-  serializeLock,
-} from "../../kernel/runtime/lock.js";
-import { LOCK_BASENAME, lockPath } from "../../kernel/runtime/paths.js";
-import type { PackageRef } from "../../kernel/runtime/refs/parseRef.js";
-import {
-  parsePackageEntry,
-  redactUrl,
-} from "../../kernel/runtime/refs/parseRef.js";
+import type { PragmaRuntime } from "../../kernel/runtime/index.js";
+import { activePackPath, readActivePack } from "../../kernel/runtime/paths.js";
+import type { PackageRef } from "../../kernel/runtime/refs/index.js";
 import {
   detectPrefixClashes,
   harvestPrefixes,
+  parsePackDeclaration,
   type ResolvedPackage,
+  redactUrl,
   resolvePackage,
-} from "../../kernel/runtime/refs/resolve.js";
-import type { PragmaRuntime } from "../../kernel/runtime/types.js";
+} from "../../kernel/runtime/refs/index.js";
 import { installedSkillsDir } from "../skill/discover.js";
 import { planSkillInstall } from "./installSkills.js";
 import type { SourcesUpdateData } from "./types.js";
@@ -67,17 +64,43 @@ const CORE_PREFIXES: Readonly<Record<string, string>> = {
   dcterms: "http://purl.org/dc/terms/",
 };
 
-const entryName = (entry: PackageEntry): string =>
-  typeof entry === "string" ? entry : entry.name;
+/**
+ * The prefix map a pack is built with: core < the packs' own `@prefix` < config.
+ *
+ * A resolved package's own declarations are harvested from its TTL (ke does not
+ * fold parsed-Turtle prefixes into `store.prefixes`) and merged beneath config
+ * so the index compacts pack URIs to `pfx:Local` — the FROZEN `{name,type}`
+ * token contract — while config still wins any clash. The merged map is
+ * persisted in the manifest, so boot reads the same names.
+ *
+ * Exported because the bundler (`scripts/bundle.ts`) compiles the embedded pack
+ * through this exact precedence. If the two pipelines computed prefixes
+ * separately, the embed could compact entities differently from what the SAME
+ * config produces on a user's machine — a silent divergence in entity names.
+ *
+ * @param inputs - The resolved packages' labelled RDF sources.
+ * @param configPrefixes - The config layer's `prefixes`, if any.
+ * @returns The merged prefix map to build with.
+ */
+export function buildPackPrefixes(
+  inputs: readonly { readonly content: string }[],
+  configPrefixes: Readonly<Record<string, string>> | undefined,
+): Record<string, string> {
+  return {
+    ...CORE_PREFIXES,
+    ...harvestPrefixes(inputs),
+    ...(configPrefixes ?? {}),
+  };
+}
 
 /**
  * Build the NETWORK-FREE preview plan for `sources update`.
  *
  * A plan-only Task: it reads the config to list the refs a real update would
- * resolve and build, then models the single project mutation (the lock write)
- * as effects the dry-run interpreter can describe WITHOUT running them. No git,
- * no compile, no cache write — so `--dry-run` and an MCP plan-first call are
- * offline-safe. Config refs are parsed (a cheap, offline validity check) but
+ * resolve and build, then models the project mutation (the active-pack pointer
+ * write) as effects the dry-run interpreter can describe WITHOUT running them.
+ * No git, no compile, no cache write — so `--dry-run` and an MCP plan-first call
+ * are offline-safe. Config refs are parsed (a cheap, offline validity check) but
  * never resolved.
  *
  * @param runtime - The per-invocation runtime.
@@ -87,57 +110,51 @@ async function buildUpdatePlan(
   runtime: PragmaRuntime,
 ): Promise<Task<SourcesUpdateData>> {
   const layers = await runtime.loadConfig();
-  const entries = layers.config.packages ?? [];
-  const refs = entries.map(parsePackageEntry);
-  const path = lockPath(runtime.cwd);
+  const entries = layers.config.packs ?? [];
+  const refs = entries.map(parsePackDeclaration);
 
   const data: SourcesUpdateData = {
     contentHash: "",
     reused: false,
-    lockPath: path,
-    packs: refs.map((ref) => ({ name: ref.pkg, resolved: "", sourceCount: 0 })),
-  };
-  // A representative (never-written) lock, so the previewed write shows a
-  // plausible shape/size. Placeholders make clear nothing was resolved.
-  const previewLock: PragmaLock = {
-    version: 1,
-    contentHash: "(resolved on execute)",
     packs: refs.map((ref) => ({
       name: ref.pkg,
-      source: ref.source,
-      resolved: "(resolved on execute)",
-      resolvedAt: "(resolved on execute)",
+      resolved: "",
+      sourceCount: 0,
+      storyCount: 0,
     })),
   };
-  const previewContent = serializeLock(previewLock);
 
   return gen(function* () {
     yield* $(
       info(
         refs.length > 0
-          ? `Resolve and build ${refs.length} package(s): ${refs.map((ref) => ref.source).join(", ")}`
-          : "No packages configured — the embedded pack answers store reads",
+          ? `Resolve and build ${refs.length} pack(s): ${refs.map((ref) => ref.source).join(", ")}`
+          : "No packs configured — the embedded pack answers store reads",
       ),
     );
-    // The one project mutation, previewed (dry-run never executes it).
-    yield* $(writeFile(path, previewContent));
+    // The project mutation, previewed (dry-run never executes it). The content
+    // is a placeholder: the real hash only exists once the build has run.
+    yield* $(
+      writeFile(activePackPath(runtime.cwd), "(the pack hash, on execute)"),
+    );
     return data;
   });
 }
 
 /**
- * Resolve, build, and produce the lock-writing Task — or, for a preview, the
+ * Resolve, build, and produce the pointer-writing Task — or, for a preview, the
  * network-free plan.
  *
  * @param runtime - The per-invocation runtime.
- * @param frozen - When true, re-resolve to the lock's pinned revisions only.
- * @returns A Task that writes `pragma.lock.json` and returns the update result.
+ * @param skipInvalid - Drop sources that fail to parse (warning about each)
+ *   rather than failing the whole update.
+ * @returns A Task that points the project at the built pack and returns the
+ *   update result.
  * @note Impure — resolves packages (may hit git) and builds the pack eagerly,
  *   UNLESS `runtime.mutation.preview` is set, in which case it stays offline.
  */
 export async function buildUpdateTask(
   runtime: PragmaRuntime,
-  frozen: boolean,
   skipInvalid = false,
 ): Promise<Task<SourcesUpdateData>> {
   if (runtime.mutation?.preview) return buildUpdatePlan(runtime);
@@ -149,75 +166,80 @@ export async function buildUpdateTask(
   const verbose = runtime.globalFlags.verbose;
 
   const layers = await runtime.loadConfig();
-  const entries = layers.config.packages ?? [];
-  const existing = readLock(runtime.cwd);
-  const priorContent = existing ? serializeLock(existing) : undefined;
+  const entries = layers.config.packs ?? [];
+  const priorHash = readActivePack(runtime.cwd);
 
-  const resolved: ResolvedPackage[] = [];
+  const resolved: (ResolvedPackage & { readonly kind: PackageRef["kind"] })[] =
+    [];
   for (const entry of entries) {
-    const ref = parsePackageEntry(entry);
+    const ref = parsePackDeclaration(entry);
     report?.(resolveProgress(ref));
-    const pinned = existing?.packs.find((pack) => pack.name === ref.pkg);
-    resolved.push(
-      await resolvePackage(ref, {
-        cwd: runtime.cwd,
-        frozen,
-        pinned: pinned?.resolved,
-      }),
-    );
+    resolved.push({
+      kind: ref.kind,
+      ...(await resolvePackage(ref, { cwd: runtime.cwd })),
+    });
   }
 
-  // Prefix precedence: core < pack < config. A resolved package's own
-  // `@prefix` declarations are harvested from its TTL and merged beneath config
-  // so the index compacts pack URIs to `pfx:Local` (the FROZEN {name,type}
-  // token contract); config still wins any clash. The merged map is persisted
-  // in the manifest, so boot reads the same names.
   const inputs = resolved.flatMap((pkg) => pkg.sources);
+  // The packages' own `stories/*.json`, carried into the pack verbatim (see
+  // graphpack/types.STORIES_FILE). Raw text: nothing interprets them here.
+  const stories = resolved.flatMap((pkg) => pkg.stories);
 
-  // Refuse to lock an empty store (A4). A package that ships no `.ttl` (or no
-  // configured packages at all) would build a 0-triple pack whose empty
+  // Refuse to build an empty store (A4). A package that ships no `.ttl` (or no
+  // configured packs at all) would build a 0-triple pack whose empty
   // `data.nq` fails the completeness gate — so the "successful" update boots to
   // a PERMANENT `STORE_UNAVAILABLE` loop. Fail loudly here, leaving the embedded
-  // fallback (or the prior lock) intact, instead of writing that broken lock.
+  // pack (or the prior build) answering reads, instead of pointing at that one.
   if (inputs.length === 0) {
     throw PragmaError.configError(
       entries.length === 0
-        ? "No packages are configured, so there are no sources to build a store from. The embedded sample pack answers reads until you add a package."
-        : `The ${entries.length} configured package(s) resolved 0 RDF sources (no definitions/**.ttl or data/**.ttl). Refusing to write a lock for an empty store.`,
+        ? "No packs are configured, so there are no sources to build a store from. The embedded pack answers reads until you add a pack."
+        : `The ${entries.length} configured pack(s) resolved 0 RDF sources (no definitions/**.ttl or data/**.ttl). Refusing to build an empty store.`,
       {
         recovery: cliRecovery(
-          `${RECOVERY_CLI_PREFIX}sources update --verbose`,
-          "Add a package that ships `.ttl` under definitions/ or data/, then re-run.",
+          "sources update --verbose",
+          "Add a pack that ships `.ttl` under definitions/ or data/, then re-run.",
         ),
       },
     );
   }
 
-  const prefixes = {
-    ...CORE_PREFIXES,
-    ...harvestPrefixes(inputs),
-    ...(layers.config.prefixes ?? {}),
-  };
+  const prefixes = buildPackPrefixes(inputs, layers.config.prefixes);
 
   // Warn on conflicting `@prefix` declarations across packages (A5): last-wins
   // is silent otherwise, compacting the losing package's URIs to the wrong
   // prefix. Display-only, so a warning (not a hard failure) is the right call.
   for (const clash of detectPrefixClashes(inputs)) {
     report?.(
-      `Prefix "${clash.label}:" is declared with conflicting IRIs across packages (${clash.iris.join(" vs ")}); last wins, so some entities may compact to the wrong prefix.`,
+      `Prefix "${clash.label}:" is declared with conflicting IRIs across packs (${clash.iris.join(" vs ")}); last wins, so some entities may compact to the wrong prefix.`,
     );
   }
 
   report?.(`Building store from ${inputs.length} source(s)`);
   if (verbose) for (const input of inputs) report?.(`  parse ${input.path}`);
+  if (stories.length > 0)
+    report?.(`Carrying ${stories.length} pack read story file(s)`);
 
   // Build the pack. On a parse/build failure, classify it as a NAMED data error
-  // (U6) — not INTERNAL_ERROR's "please report this issue" — identifying the
+  // (U6) — not INTERNAL_ERROR's "report this issue" — identifying the
   // offending package source, since ke's parser error carries only line/column.
   // With `--skip-invalid`, drop the unparseable sources (warning LOUDLY about
   // each — never a silent partial graph) and build from the rest instead of
   // failing the whole update.
-  const sourceRef = entries.map(entryName).join(",") || "embedded";
+  // `<name>@<kind>:<resolved>` — the SAME provenance label the bundler writes
+  // for the embed, so the manifest field means one thing whoever built the pack,
+  // and `sources status` / `doctor` can still answer "which revision is my store
+  // built from?" now that no lock records it. A `file:` pack resolves to a local
+  // PATH rather than a revision, so it contributes its name alone: a machine
+  // path is not provenance, and `sources status` already lists the ref.
+  const sourceRef =
+    resolved
+      .map((pkg) =>
+        pkg.kind === "file"
+          ? pkg.name
+          : `${pkg.name}@${pkg.kind}:${pkg.resolved}`,
+      )
+      .join(", ") || "embedded";
   let built: Awaited<ReturnType<typeof buildPack>>;
   try {
     built = await buildPack(inputs, {
@@ -225,6 +247,7 @@ export async function buildUpdateTask(
       version: VERSION,
       sourceRef,
       prefixes,
+      stories,
     });
   } catch (error) {
     if (!skipInvalid) throw await classifySourceBuildError(error, inputs);
@@ -241,10 +264,10 @@ export async function buildUpdateTask(
     );
     if (usableInputs.length === 0)
       throw PragmaError.configError(
-        `All ${inputs.length} configured source(s) failed to parse — nothing to build.`,
+        `None of the ${inputs.length} configured source(s) can be parsed — nothing to build.`,
         {
           recovery: cliRecovery(
-            `${RECOVERY_CLI_PREFIX}sources update --verbose`,
+            "sources update --verbose",
             "Fix the reported sources, then re-run.",
           ),
         },
@@ -256,11 +279,8 @@ export async function buildUpdateTask(
         sourceRef,
         // Re-harvest prefixes from only the sources that survived, so a dropped
         // file's declarations don't skew compaction.
-        prefixes: {
-          ...CORE_PREFIXES,
-          ...harvestPrefixes(usableInputs),
-          ...(layers.config.prefixes ?? {}),
-        },
+        prefixes: buildPackPrefixes(usableInputs, layers.config.prefixes),
+        stories,
       });
     } catch (rebuildError) {
       throw await classifySourceBuildError(rebuildError, usableInputs);
@@ -270,78 +290,62 @@ export async function buildUpdateTask(
     `${built.reused ? "Reused" : "Built"} store ${built.contentHash.slice(0, 12)}`,
   );
 
-  // Refuse to lock a 0-triple build (A4): non-empty sources can still parse to
-  // no triples (e.g. comment-only TTL, or a file of only `@prefix` lines). A
-  // locked empty pack boots to the same `STORE_UNAVAILABLE` loop, so treat it
-  // as a data error rather than a silent "success". (A manifest predating the
-  // triple count is left alone — `undefined` never trips this.)
+  // Refuse a 0-triple build (A4): non-empty sources can still parse to no
+  // triples (e.g. comment-only TTL, or a file of only `@prefix` lines). Pointing
+  // the project at an empty pack boots to the same `STORE_UNAVAILABLE` loop, so
+  // treat it as a data error rather than a silent "success". (A manifest
+  // predating the triple count is left alone — `undefined` never trips this.)
   if (built.manifest.tripleCount === 0) {
     throw PragmaError.configError(
-      `The configured sources parsed to 0 RDF triples, so the store would be empty. Refusing to write a lock for an empty store.`,
+      `The configured sources parsed to 0 RDF triples, so the store would be empty. Refusing to build an empty store.`,
       {
         recovery: cliRecovery(
-          `${RECOVERY_CLI_PREFIX}sources update --verbose`,
-          "Check that the package sources actually contain RDF triples, then re-run.",
+          "sources update --verbose",
+          "Check that the pack sources actually contain RDF triples, then re-run.",
         ),
       },
     );
   }
 
-  const now = new Date().toISOString();
-  const lock: PragmaLock = {
-    version: 1,
-    contentHash: built.contentHash,
-    packs: resolved.map((pkg) => {
-      const prev = existing?.packs.find((entry) => entry.name === pkg.name);
-      // Preserve the prior `resolvedAt` when nothing actually changed — under
-      // --frozen (re-pinned to the same revision) AND on a plain re-run that
-      // resolves the IDENTICAL revision from the same source. Otherwise every
-      // `sources update` stamped a fresh timestamp and rewrote the lock, dirtying
-      // the git tree on a no-op run (L1). A moved revision still restamps.
-      const reproducible =
-        prev !== undefined &&
-        (frozen ||
-          (prev.resolved === pkg.resolved && prev.source === pkg.source));
-      return {
-        name: pkg.name,
-        source: pkg.source,
-        resolved: pkg.resolved,
-        resolvedAt: reproducible && prev ? prev.resolvedAt : now,
-      };
-    }),
-  };
-  const newContent = serializeLock(lock);
-  const path = lockPath(runtime.cwd);
-
+  const path = activePackPath(runtime.cwd);
   const data: SourcesUpdateData = {
     contentHash: built.contentHash,
     reused: built.reused,
-    lockPath: path,
     packs: resolved.map((pkg) => ({
       name: pkg.name,
       resolved: pkg.resolved,
       sourceCount: pkg.sources.length,
+      storyCount: pkg.stories.length,
     })),
   };
 
   const undo =
-    priorContent !== undefined
-      ? writeFile(path, priorContent)
-      : deleteFile(path);
+    priorHash !== undefined ? writeFile(path, priorHash) : deleteFile(path);
 
   // Install package-provided skills (U10): symlink each resolved package's
   // `skills/*` into the installed-skills root, so `skill list` / `setup skills`
-  // see them after an update. Kept in this Task (reversible: created links carry
-  // an unlink undo) so `sources update --undo` also removes them.
-  const skillLinks = planSkillInstall(resolved).filter(
-    (link) => link.action !== "skipped",
+  // see them after an update — and RETIRE the links of skills those packages
+  // have since dropped, which the same plan reports as `pruned`. Kept in this
+  // Task (reversible: a created link carries an unlink undo, a pruned one a
+  // re-link undo) so `sources update --undo` restores the root as it was.
+  //
+  // The two are split, not counted together: a prune is a deletion, so folding
+  // it into "Installing N skill(s)" would report a removal as an install.
+  const skillPlan = planSkillInstall(resolved);
+  const skillLinks = skillPlan.filter(
+    (link) => link.action === "created" || link.action === "replaced",
   );
+  const staleLinks = skillPlan.filter((link) => link.action === "pruned");
   if (skillLinks.length > 0)
     report?.(`Installing ${skillLinks.length} skill(s)`);
+  if (staleLinks.length > 0)
+    report?.(
+      `Removing ${staleLinks.length} skill link(s) no longer provided by any package`,
+    );
 
-  report?.(`Writing ${LOCK_BASENAME}`);
+  report?.(`Pointing ${runtime.cwd} at pack ${built.contentHash.slice(0, 12)}`);
   return gen(function* () {
-    yield* $(writeFile(path, newContent, { undo }));
+    yield* $(writeFile(path, built.contentHash, { undo }));
     if (skillLinks.length > 0) {
       yield* $(mkdir(installedSkillsDir(), true));
       for (const link of skillLinks) {
@@ -353,6 +357,25 @@ export async function buildUpdateTask(
         );
       }
     }
+    // No `mkdir` guard here: a stale link can only have been enumerated FROM
+    // the installed root, so the root necessarily exists.
+    //
+    // The undo re-creates the link exactly as found — dangling target and all —
+    // because undo's job is to restore the prior state, not to improve on it. It
+    // clears the path first because the undo interpreter MOCKS forward effects
+    // when collecting: the delete above may never have run, and `fs.symlink`
+    // refuses a path that already exists. Same delete-then-link shape the
+    // `replaced` branch above uses, for the same reason.
+    for (const stale of staleLinks) {
+      yield* $(
+        deleteFile(stale.linkPath, {
+          undo: gen(function* () {
+            yield* $(deleteFile(stale.linkPath));
+            yield* $(symlink(stale.target, stale.linkPath));
+          }),
+        }),
+      );
+    }
     return data;
   });
 }
@@ -394,12 +417,12 @@ export async function classifySourceBuildError(
   const culprit = await isolateBadSource(inputs);
   const detail = culprit?.message ?? parserMessage;
   const where = culprit
-    ? `Package source "${culprit.path}" could not be parsed`
-    : "The configured package sources could not be built into a store";
+    ? `Pack source "${culprit.path}" cannot be parsed`
+    : "The configured packs cannot be built into a store";
   return PragmaError.configError(`${where}: ${detail}`, {
     recovery: cliRecovery(
-      `${RECOVERY_CLI_PREFIX}sources update --verbose`,
-      "Re-run with --verbose to see each file as it parses. If a package ships malformed RDF, report it to that package's maintainer.",
+      "sources update --verbose",
+      "Re-run with --verbose to see each file as it parses. If a pack ships malformed RDF, report it to that pack's maintainer.",
     ),
   });
 }