@passioncode-ai/passioncode 0.1.14 → 0.1.16

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.1.16 - 2026-10-01
+
+### Fixed
+
+- The packed lifecycle release check accepts both npm 11’s array and npm 12’s
+  package-name-keyed JSON output, and rejects ambiguous or malformed pack results.
+- The update probe accepts npm 12’s singleton metadata array while preserving
+  publisher checks and rejecting ambiguous or malformed responses.
+- The 0.1.15 tag and GitHub release remain historical: its release workflow stopped
+  at this check before npm publication. Version 0.1.16 includes the fixes and shared
+  backlog instructions described below.
+
+## 0.1.15 - 2026-10-01
+
+### Fixed
+
+- Restore and uninstall preserve recoverable state, reject unsupported options before changes,
+  and report failed filesystem or plugin operations truthfully. Updates reject inconsistent
+  payloads and stop dependent work after a failed release or marketplace step.
+- Status reports the installed release correctly and retains concurrent probe/configuration
+  updates. Self-update checks reject untrusted or incomplete npm publisher metadata and
+  recover from failed spawns and future timestamps.
+- Node 18 test discovery, release-tag validation and the packed lifecycle smoke now guard
+  the release path. The launcher audit records the regression evidence.
+
+### Changed
+
+- The repository skill and SessionStart reminder direct agents to canonical local backlog
+  sources and the derived workspace backlog, with one owner per task and source-commit checks.
+- Developer documentation now states the CLI, recovery and self-update contracts and checks
+  their local references. Tagged Fabric Agent Adapter 0.5.5 and Observatory Log 0.13.0 stay
+  in the family; this release does not add a new family member.
+
 ## 0.1.14 - 2026-10-01
 
 ### Changed

package/README.md

@@ -24,8 +24,8 @@ out of it, even when they implement Fabric protocols.
 1. **Install** (Node 18 or newer; the Claude Code CLI on `PATH` for the plugins):
    `npx @passioncode-ai/passioncode@latest update`, then restart your agents. Check it with
    `npx @passioncode-ai/passioncode@latest status` (every member `claude: plugin · hub: n/n`) and
-   `claude plugin list` (three plugins `@passioncode`). Always call the scoped package: there is
-   no unscoped `passioncode` package on npm.
+   `claude plugin list` (the plugins listed in `family.json`, under `@passioncode`).
+   Always call the scoped package shown above.
 2. **Configure:** nothing to set, no account and no key. Background updates are on by default;
    `npx @passioncode-ai/passioncode@latest config set update.auto off` turns them off.
 3. **MCP:** none today, and not planned. The launcher installs skills and session hooks and is
@@ -50,26 +50,41 @@ out of it, even when they implement Fabric protocols.
 - **Every other agent** (Cursor, Codex, Gemini, OpenCode, Kiro, Windsurf, Goose, …) gets
   the same skills through `~/.agents/skills`, linked from each channel that exists on
   the machine.
-- Nothing is written to `~/.claude/skills`: a plain copy there shadows the plugin. Such
+- Updates create no skill copies in `~/.claude/skills`: a plain copy there shadows the plugin. Such
   copies, and hub entries that pointed at a repository's working tree, are moved into
   `~/.passioncode/quarantine/` — `npx @passioncode-ai/passioncode@latest restore` puts them back.
 - Each version is an immutable release under `~/.passioncode/releases/<version>`.
 
 ## Staying current
 
-At every Claude Code session start the `passioncode` plugin checks npm at most once a
-day and, when a newer set is out **and every npm account that publishes it is in the
+At Claude Code session start the `passioncode` plugin uses a cached npm check for up
+to 24 hours and, when a newer set is out **and every npm account that publishes it is in the
 plugin's `trust.json`**, updates to that exact version in the background — it takes
 effect in the next session. A version published by anyone else is named and not
 installed ([SECURITY.md](SECURITY.md#the-self-update-and-who-it-trusts)).
 `npx @passioncode-ai/passioncode@latest config set update.auto off` makes it only say so.
 
+`status` reads local state without contacting npm. Its npm version is labelled
+`npm latest (cached)` with the saved check timestamp, or `check time unknown`.
+When that stable version is below the installed stable version, the line also says
+`stale: older than installed`. A newer or equal cached version is still a saved
+observation, not a live registry check. With no saved version it says
+`npm latest: not checked`; `--json` retains the raw `latest` and `checkedAt` fields.
+
 ```bash
 npx @passioncode-ai/passioncode@latest status   # the installed release: its members, their channels, shadows
 npx @passioncode-ai/passioncode@latest update --dry-run
 npx @passioncode-ai/passioncode@latest uninstall
 ```
 
+For supported flags, JSON fields, exit codes and partial-failure recovery, read the
+[CLI contract](docs/reference/cli.md). `restore` repairs the latest quarantine batch;
+it is not a release rollback. A successful `uninstall` preserves recovery files and
+turns automatic updates off. Unsupported flags are rejected before mutation.
+
+Repository docs describe the current source. See the [documentation index](docs/README.md)
+and dated handoffs for which changes have actually been published or installed.
+
 ## Release (maintainers)
 
 1. Tag every member at the version to ship; set `ref` to that tag in `family.json`.
@@ -81,7 +96,8 @@ npx @passioncode-ai/passioncode@latest uninstall
 4. Merge, then tag the merge commit `vX.Y.Z` and push the tag. `.github/workflows/release.yml`
    validates, checks the tag against both manifests, creates the GitHub release from the
    CHANGELOG section, vendors every member **from its own repository** at its pinned tag,
-   runs the tests, installs the packed tarball from a clean `HOME`, publishes
+   runs the tests, exercises packed update/status/uninstall with a fake Claude CLI
+   in a temporary home (`node scripts/smoke-pack.mjs`), publishes
    `@passioncode-ai/passioncode` and waits until npm serves it. It runs when the repository
    variables `RELEASE_ENABLED` and `PUBLISH_NPMJS` are `true`; npm auth is trusted publishing
    (OIDC) or the `NPM_TOKEN` secret; a private member needs `MEMBERS_READ_TOKEN`.

package/SECURITY.md

@@ -11,12 +11,18 @@ that replaces it is verified. For a member's old single-member marketplace
 (`legacyMarketplaces` in `family.json`), once that plugin is verified and nothing else
 installed comes from it, it also moves the `extraKnownMarketplaces` entry out of
 `~/.claude/settings.json` (a copy of the file is kept in the quarantine) and runs
-`claude plugin marketplace remove <name>`. It never deletes: every move is listed in
-`~/.passioncode/quarantine/<run>/moved.json` and undone by `passioncode restore`.
+`claude plugin marketplace remove <name>`. Displaced files are moved rather than
+deleted: a recovery record is written before the move in
+`~/.passioncode/quarantine/<run>/moved.json`. `restore` processes the latest batch,
+checkpoints completed entries and refuses to overwrite a conflicting user replacement.
+`uninstall` removes owned links/plugins, clears the active release and disables
+automatic updates; it retains release copies and recovery records. A failed removal
+returns a nonzero exit code. See the [CLI recovery contract](docs/reference/cli.md).
 
 ## The self-update and who it trusts
 
-The SessionStart hook reads `~/.passioncode/state.json` and, at most once a day, starts
+The SessionStart hook reads `~/.passioncode/state.json` and reuses a check for up to
+24 hours. An absent, invalid, future or expired timestamp starts
 `npm view @passioncode-ai/passioncode version maintainers _npmUser --json`, detached, logging to
 `~/.passioncode/logs/`. It records the latest version, the package's npm maintainers
 and the account that published that version.
@@ -24,7 +30,8 @@ and the account that published that version.
 The hook installs a newer version on its own only when all of these hold:
 
 - `update.auto` is on (the default);
-- the recorded maintainers are not empty, and every maintainer **and** the publishing
+- the npm probe exited successfully, the recorded maintainers are non-empty, the
+  publisher is known, and every maintainer **and** the publishing
   account is listed in `trust.json` inside the plugin (`npmPublishers`);
   a release published by this repository's `release.yml` through npm trusted publishing
   appears as `github-actions-oidc` (npm's `npm-oidc-no-reply@github.com` identity, matched
@@ -37,10 +44,19 @@ nothing: a version from an account outside the list is reported in one line nami
 account ("… not a trusted PassionCode publisher — not installing"); a name nobody has
 published (npm E404) is silent; a failed check is shown once.
 
-`trust.json` ships **empty**, so auto-update stays inert until the maintainers name the
-npm account(s) that publish PassionCode. Adding an account there is a release decision:
+The current allowlist lives in [`plugin/passioncode/trust.json`](plugin/passioncode/trust.json).
+A missing or empty allowlist cannot authorize an update. Adding an account there is a release decision:
 it is reviewed like code and ships in the package. A person who wants no background
 updates at all runs `npx @passioncode-ai/passioncode@latest config set update.auto off`.
 
-The published package carries skill text only; the vendor step refuses to build when it
-finds a credential-shaped string, or when the self plugin has no valid `trust.json`.
+The package contains executable launcher code and member plugin hooks as well as
+skill text. The vendor scans supported text-file sizes for credential-shaped strings
+and rejects an invalid self-plugin trust list; that scan is not a proof that all
+possible secrets or malicious code are absent. Review member code at its pinned tag.
+Automatic updates trust the npm registry's attribution and the local cached state;
+they do not independently verify signatures or sandbox the installed code.
+
+Evidence: `update()`, `restore()` and `uninstall()` in `lib/launcher.js`;
+`parseView()` and `decide()` in `plugin/passioncode/hooks/update-check.js`;
+`scanForSecrets()` in `scripts/vendor.mjs`; regression tests in
+`test/launcher.test.js` and `test/self-update.test.js`.

package/bin/passioncode.js

@@ -2,6 +2,21 @@
 'use strict';
 const L = require('../lib/launcher');
 
+function cachedNpmStatus({ latest, checkedAt, installed }) {
+  if (!latest) return 'npm latest: not checked';
+  const checked = typeof checkedAt === 'string' && Number.isFinite(Date.parse(checkedAt))
+    ? `checked ${checkedAt}` : 'check time unknown';
+  let stale = false;
+  // The registry probe accepts stable x.y.z versions only. Do not guess an
+  // ordering for other values that may have been written to the state file.
+  if (/^\d+\.\d+\.\d+$/.test(latest) && /^\d+\.\d+\.\d+$/.test(installed)) {
+    const a = latest.split('.').map(Number), b = installed.split('.').map(Number);
+    const difference = a.findIndex((part, i) => part !== b[i]);
+    stale = difference !== -1 && a[difference] < b[difference];
+  }
+  return `npm latest (cached) ${latest} (${checked}${stale ? '; stale: older than installed' : ''})`;
+}
+
 const HELP = `passioncode — the PassionCode.ai skill set (family.json), for every agent on this machine
 
   npx @passioncode-ai/passioncode@latest update [--dry-run] [--json]     install or update the whole set
@@ -18,6 +33,18 @@ function main(argv) {
   const json = rest.includes('--json');
   const quiet = rest.includes('--quiet');
   const out = (value, text) => process.stdout.write(json ? JSON.stringify(value, null, 2) + '\n' : text + '\n');
+  const options = {
+    update: ['--dry-run', '--json', '--quiet'], install: ['--dry-run', '--json', '--quiet'],
+    status: ['--json'], restore: ['--json'], uninstall: ['--json'], help: [], '--help': [], '-h': [],
+  };
+  const configArgs = rest.filter((arg) => arg !== '--json');
+  const invalid = cmd === 'config'
+    ? configArgs.length !== 3 || configArgs[0] !== 'set'
+    : Object.hasOwn(options, cmd) && rest.some((arg) => !options[cmd].includes(arg));
+  if (invalid) {
+    process.stderr.write(`passioncode: unsupported arguments for ${cmd}; run passioncode help.\n`);
+    return 2;
+  }
   try {
     if (cmd === 'update' || cmd === 'install') {
       const r = L.update({ dryRun: rest.includes('--dry-run') });
@@ -26,8 +53,8 @@ function main(argv) {
         out(r, [
           ...r.steps.map((s) => `${s.outcome.padEnd(8)} ${s.kind.padEnd(11)} ${s.detail}${s.error ? `\n         ${s.error}` : ''}`),
           '',
-          failed.length ? `${failed.length} step(s) failed — the rest were applied. Re-run after fixing, or \`passioncode restore\`.` : rest.includes('--dry-run') ? `Plan for PassionCode.ai ${r.version}: nothing was changed.` : `PassionCode.ai ${r.version}: done. Restart your agent — skills load at session start.`,
-          r.moved.length ? `${r.moved.length} item(s) moved aside, restorable with \`passioncode restore\`.` : '',
+          failed.length ? `${failed.length} step(s) failed. Completed steps remain applied. Fix the cause and retry; use passioncode restore for displaced files.` : rest.includes('--dry-run') ? `Plan for PassionCode.ai ${r.version}: nothing was changed.` : `PassionCode.ai ${r.version}: done. Restart your agent — skills load at session start.`,
+          r.moved.length ? `${r.moved.length} recovery entry(s) saved; use \`passioncode restore\`.` : '',
         ].filter(Boolean).join('\n'));
       }
       return failed.length ? 1 : 0;
@@ -35,7 +62,7 @@ function main(argv) {
     if (cmd === 'status') {
       const s = L.status();
       out(s, [
-        `installed ${s.installed || 'nothing'} · package ${s.package || '?'} · latest on npm ${s.latest || 'not checked'}${s.auto ? ' · auto-update on' : ' · auto-update off'}`,
+        `installed ${s.installed || 'nothing'} · package ${s.package || '?'} · ${cachedNpmStatus(s)}${s.auto ? ' · auto-update on' : ' · auto-update off'}`,
         ...s.members.map((m) => `${m.name.padEnd(22)} ${String(m.version).padEnd(8)} claude: ${m.claude}${m.legacy.length ? ` (+ legacy ${m.legacy.join(', ')})` : ''}${m.legacyMarketplaces.length ? ` (+ legacy marketplace ${m.legacyMarketplaces.join(', ')})` : ''} · hub: ${m.hub.filter((h) => h.ok).length}/${m.hub.length}${m.shadows.length ? ` · SHADOW: ${m.shadows.join(', ')}` : ''}`),
       ].join('\n'));
       return 0;
@@ -45,8 +72,8 @@ function main(argv) {
       out(r, r.length ? `Restored:\n  ${r.join('\n  ')}` : 'Nothing to restore.');
       return 0;
     }
-    if (cmd === 'config' && rest[0] === 'set') {
-      out(L.setConfig({ key: rest[1], value: rest[2] }), `update.auto = ${rest[2]}`);
+    if (cmd === 'config' && configArgs[0] === 'set') {
+      out(L.setConfig({ key: configArgs[1], value: configArgs[2] }), `update.auto = ${configArgs[2]}`);
       return 0;
     }
     if (cmd === 'uninstall') {

package/lib/launcher.js

@@ -9,7 +9,7 @@
  * ~/.claude/skills (a plain copy there shadows the plugin and serves its frozen
  * version forever); every other agent reads the hub through its own channel.
  */
-const { execFileSync, spawnSync } = require('child_process');
+const { spawnSync } = require('child_process');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
@@ -49,6 +49,14 @@ function writeJson(file, value) {
 }
 function lstat(p) { try { return fs.lstatSync(p); } catch (_) { return null; } }
 function linkTarget(p) { try { return fs.readlinkSync(p); } catch (_) { return null; } }
+function pointsTo(at, target) { const link = linkTarget(at); return link !== null && path.resolve(path.dirname(at), link) === target; }
+function isDirectory(at) { try { return fs.statSync(at).isDirectory(); } catch (_) { return false; } }
+function readState(file, { tolerant = false } = {}) {
+  try { return readSettings(file).doc; } catch (error) {
+    if (tolerant) return {};
+    throw new Error(`Cannot read state ${file}: ${error.message}. Preserve the file and repair it before retrying.`);
+  }
+}
 
 /** Replace a symlink atomically (create beside it, rename over it). */
 function symlinkAtomic(target, at) {
@@ -62,7 +70,8 @@ function symlinkAtomic(target, at) {
 /** Claude Code's plugin CLI, overridable for tests. */
 function claudeRunner() {
   const bin = process.env.PASSIONCODE_CLAUDE || 'claude';
-  const available = () => spawnSync(bin, ['--version'], { encoding: 'utf8' }).status === 0;
+  let found;
+  const available = () => found ?? (found = spawnSync(bin, ['--version'], { encoding: 'utf8', timeout: 5000 }).status === 0);
   const run = (args, { cwd } = {}) => {
     const r = spawnSync(bin, args, { encoding: 'utf8', timeout: 180000, ...(cwd ? { cwd } : {}) });
     return { code: r.status === null ? 1 : r.status, out: `${r.stdout || ''}${r.stderr || ''}`.trim() };
@@ -93,15 +102,41 @@ function marketplaceAddArg(source) {
 function payloadManifest(dir = PAYLOAD()) {
   const m = readJson(path.join(dir, 'manifest.json'), null);
   if (!m || !Array.isArray(m.members)) throw new Error(`No payload in ${dir}: the package is incomplete (run scripts/vendor.mjs).`);
+  const name = (value) => typeof value === 'string' && /^[a-z0-9][a-z0-9._-]*$/.test(value);
+  const version = (value) => typeof value === 'string' && /^\d+\.\d+\.\d+$/.test(value);
+  const names = new Set(), skills = new Set();
+  if (!version(m.version)) throw new Error(`Invalid payload version in ${dir}.`);
+  for (const member of m.members) {
+    if (!member || !name(member.name) || names.has(member.name) || !version(member.version) || !Array.isArray(member.skills)) {
+      throw new Error(`Invalid or duplicate payload member in ${dir}.`);
+    }
+    names.add(member.name);
+    for (const skill of member.skills) {
+      if (!name(skill) || skills.has(skill)) throw new Error(`Invalid or duplicate skill in ${dir}.`);
+      skills.add(skill);
+    }
+  }
   return m;
 }
 
+function verifyPayload(dir, manifest) {
+  for (const m of manifest.members) {
+    const root = path.join(dir, 'plugins', m.name);
+    const plugin = readJson(path.join(root, '.claude-plugin/plugin.json'), null);
+    if (!plugin || plugin.name !== m.name || plugin.version !== m.version) throw new Error(`Payload plugin mismatch: ${m.name}.`);
+    for (const skill of m.skills) {
+      if (!fs.existsSync(path.join(root, 'skills', skill, 'SKILL.md'))) throw new Error(`Payload skill missing: ${m.name}/${skill}.`);
+    }
+  }
+}
+
 /** Plan and apply an update. Returns the steps with their outcomes. */
 function update({ home, dryRun = false, claude = claudeRunner(), log = () => {} } = {}) {
   const p = paths(home);
   const manifest = payloadManifest();
+  verifyPayload(PAYLOAD(), manifest);
   const version = manifest.version;
-  const state = readJson(p.stateFile, {});
+  const state = readState(p.stateFile);
   const steps = [];
   const step = (kind, detail, fn) => {
     if (dryRun) { steps.push({ kind, detail, outcome: 'planned' }); return true; }
@@ -115,12 +150,19 @@ function update({ home, dryRun = false, claude = claudeRunner(), log = () => {}
     }
   };
   const moved = [];
-  const quarantineDir = path.join(p.quarantine, new Date().toISOString().replace(/[:.]/g, '-'));
-  const quarantine = (target, why) => {
+  const quarantineDir = path.join(p.quarantine, `${new Date().toISOString().replace(/[:.]/g, '-')}-${process.pid}`);
+  const recordMove = (entry) => {
+    writeJson(path.join(quarantineDir, 'moved.json'), [...moved, entry]);
+    const fresh = readState(p.stateFile);
+    fresh.quarantines = [...new Set([...(fresh.quarantines || []), quarantineDir])];
+    writeJson(p.stateFile, fresh);
+    moved.push(entry);
+  };
+  const quarantine = (target, why, replacement = null) => {
     const dest = path.join(quarantineDir, target.replace(/^\//, '').replace(/\//g, '__'));
     fs.mkdirSync(path.dirname(dest), { recursive: true });
+    recordMove({ from: target, to: dest, why, replacement });
     fs.renameSync(target, dest);
-    moved.push({ from: target, to: dest, why });
   };
 
   /** Move a legacy marketplace out of settings.json and the registry, recorded for restore. */
@@ -151,11 +193,13 @@ function update({ home, dryRun = false, claude = claudeRunner(), log = () => {}
         record.settingsBackup = path.join(quarantineDir, `settings.json.before-${name}`);
         fs.copyFileSync(p.claudeSettings, record.settingsBackup);
         record.settingsEntry = declared;
+      }
+      recordMove(record); // durable before settings or the registry changes
+      if (declared !== undefined) {
         const doc = settings.doc;
         delete doc.extraKnownMarketplaces[name];
         writeJson(p.claudeSettings, doc);
       }
-      moved.push(record); // recorded before the CLI runs, so restore can undo a half-finished step
       if (registered) {
         // No --scope: with the user entry already moved it would refuse. From ~/.passioncode
         // "every scope" is the user one — no project's .claude/settings.json is touched.
@@ -168,14 +212,22 @@ function update({ home, dryRun = false, claude = claudeRunner(), log = () => {}
   // 1. The release: an immutable copy of the payload, then `current` points at it.
   const release = path.join(p.releases, version);
   step('release', `install ${version} at ${release}`, () => {
-    if (lstat(path.join(release, 'manifest.json'))) return false;
+    if (lstat(path.join(release, 'manifest.json'))) {
+      const existing = payloadManifest(release);
+      verifyPayload(release, existing);
+      const identity = (m) => JSON.stringify([m.version, m.members.map(({ via, ...member }) => member)]);
+      if (identity(existing) !== identity(manifest)) throw new Error(`Release ${version} has a different manifest; use a new version instead of overwriting an immutable release.`);
+      return false;
+    }
     const tmp = `${release}.${process.pid}.partial`;
     fs.rmSync(tmp, { recursive: true, force: true });
     fs.cpSync(PAYLOAD(), tmp, { recursive: true });
     fs.renameSync(tmp, release);
     return true;
   });
+  if (steps.at(-1).outcome === 'failed') return { version, steps, moved };
   step('current', `point ${p.current} at ${version}`, () => { symlinkAtomic(release, p.current); });
+  if (steps.at(-1).outcome === 'failed') return { version, steps, moved };
 
   // 2. Claude Code: one local marketplace, one plugin per member.
   const hasClaude = claude.available();
@@ -185,16 +237,20 @@ function update({ home, dryRun = false, claude = claudeRunner(), log = () => {}
     steps.push({ kind: 'claude', detail: 'Claude Code CLI not found; its plugins were not installed', outcome: 'skipped' });
   } else {
     const known = readJson(path.join(p.claudePlugins, 'known_marketplaces.json'), {});
-    step('marketplace', known[MARKETPLACE] ? `update the ${MARKETPLACE} marketplace` : `add ${p.current} as the ${MARKETPLACE} marketplace`, () => {
+    const marketplaceReady = step('marketplace', known[MARKETPLACE] ? `update the ${MARKETPLACE} marketplace` : `add ${p.current} as the ${MARKETPLACE} marketplace`, () => {
       const r = known[MARKETPLACE] ? claude.run(['plugin', 'marketplace', 'update', MARKETPLACE]) : claude.run(['plugin', 'marketplace', 'add', p.current]);
       if (r.code !== 0) throw new Error(r.out || 'marketplace command failed');
     });
-    for (const m of manifest.members) {
+    for (const m of marketplaceReady ? manifest.members : []) {
       const id = `${m.name}@${MARKETPLACE}`;
       const present = installedIds().includes(id);
       const ok = step('plugin', `${present ? 'update' : 'install'} ${id} ${m.version}`, () => {
         const r = claude.run(['plugin', present ? 'update' : 'install', id]);
         if (r.code !== 0 && !/already (installed|at the latest)/i.test(r.out)) throw new Error(r.out || `plugin ${present ? 'update' : 'install'} failed`);
+        const entries = readJson(path.join(p.claudePlugins, 'installed_plugins.json'), { plugins: {} }).plugins?.[id];
+        if (!Array.isArray(entries) || !entries.some((entry) => entry.version === m.version)) {
+          throw new Error(`Claude Code did not register ${id} at version ${m.version}; legacy entries were kept.`);
+        }
       });
       if (ok && (dryRun || installedIds().includes(id))) verified.add(m.name);
       // The same plugin from its old single-member marketplace is a second copy of every skill.
@@ -218,7 +274,7 @@ function update({ home, dryRun = false, claude = claudeRunner(), log = () => {}
   }
 
   // 3. Every other agent: hub link → the release, channel link → the hub.
-  const channels = CHANNELS.map((c) => path.join(p.home, c)).filter((c) => lstat(c) && lstat(c).isDirectory());
+  const channels = CHANNELS.map((c) => path.join(p.home, c)).filter(isDirectory);
   for (const m of manifest.members) {
     for (const skill of m.skills) {
       const source = path.join(p.current, 'plugins', m.name, 'skills', skill);
@@ -226,7 +282,7 @@ function update({ home, dryRun = false, claude = claudeRunner(), log = () => {}
       const existing = lstat(hubLink);
       if (!existing || linkTarget(hubLink) !== source) {
         step('hub', `${hubLink} → ${source}`, () => {
-          if (lstat(hubLink)) quarantine(hubLink, existing.isSymbolicLink() ? `pointed at ${linkTarget(hubLink)}` : 'a plain copy');
+          if (lstat(hubLink)) quarantine(hubLink, existing.isSymbolicLink() ? `pointed at ${linkTarget(hubLink)}` : 'a plain copy', source);
           symlinkAtomic(source, hubLink);
         });
       }
@@ -235,7 +291,7 @@ function update({ home, dryRun = false, claude = claudeRunner(), log = () => {}
         const cur = lstat(at);
         if (cur && cur.isSymbolicLink() && (linkTarget(at) === hubLink || path.resolve(channel, linkTarget(at) || '') === hubLink)) continue;
         step('channel', `${at} → ${hubLink}`, () => {
-          if (lstat(at)) quarantine(at, cur.isSymbolicLink() ? `pointed at ${linkTarget(at)}` : 'a plain copy');
+          if (lstat(at)) quarantine(at, cur.isSymbolicLink() ? `pointed at ${linkTarget(at)}` : 'a plain copy', hubLink);
           symlinkAtomic(hubLink, at);
         });
       }
@@ -249,12 +305,15 @@ function update({ home, dryRun = false, claude = claudeRunner(), log = () => {}
 
   if (!dryRun) {
     if (moved.length) writeJson(path.join(quarantineDir, 'moved.json'), moved);
-    state.installed = version;
-    state.installedAt = new Date().toISOString();
-    state.members = manifest.members.map((m) => ({ name: m.name, version: m.version, ref: m.ref, commit: m.commit }));
-    state.quarantines = [...(state.quarantines || []), ...(moved.length ? [quarantineDir] : [])];
-    delete state.updatingSince;
-    writeJson(p.stateFile, state);
+    // A probe or config command may have written while the plugin CLI ran.
+    const fresh = readState(p.stateFile);
+    fresh.installed = version;
+    fresh.installedAt = new Date().toISOString();
+    fresh.members = manifest.members.map((m) => ({ name: m.name, version: m.version, ref: m.ref, commit: m.commit }));
+    fresh.quarantines = [...new Set([...(fresh.quarantines || []), ...(moved.length ? [quarantineDir] : [])])];
+    if (state.legacyRemoved) fresh.legacyRemoved = state.legacyRemoved;
+    delete fresh.updatingSince;
+    writeJson(p.stateFile, fresh);
   }
   log(`${dryRun ? 'Plan' : 'Updated'}: PassionCode.ai ${version}`);
   return { version, steps, moved };
@@ -263,17 +322,36 @@ function update({ home, dryRun = false, claude = claudeRunner(), log = () => {}
 /** Put back everything a run moved aside (newest run first unless one is named). */
 function restore({ home, which, claude = claudeRunner() } = {}) {
   const p = paths(home);
-  const state = readJson(p.stateFile, {});
+  const state = readState(p.stateFile);
   const dirs = which ? [which] : (state.quarantines || []).slice(-1);
   const restored = [];
   for (const dir of dirs) {
-    for (const entry of readJson(path.join(dir, 'moved.json'), []).reverse()) {
-      if (entry.kind === 'marketplace') { restored.push(restoreMarketplace(p, entry, claude)); continue; }
-      if (lstat(entry.from) && lstat(entry.from).isSymbolicLink()) fs.unlinkSync(entry.from);
-      if (lstat(entry.from)) continue;
-      fs.mkdirSync(path.dirname(entry.from), { recursive: true });
-      fs.renameSync(entry.to, entry.from);
-      restored.push(entry.from);
+    const journal = path.join(dir, 'moved.json');
+    const entries = JSON.parse(fs.readFileSync(journal, 'utf8'));
+    for (const entry of [...entries].reverse()) {
+      if (entry.restoredAt) continue;
+      if (entry.kind === 'marketplace') {
+        restored.push(restoreMarketplace(p, entry, claude));
+      } else if (lstat(entry.to)) {
+        if (lstat(entry.from)) {
+          // Old journals did not record the replacement. Only recognise a link
+          // into this launcher's hub/current tree; never erase an arbitrary link.
+          const target = linkTarget(entry.from);
+          const resolved = target === null ? null : path.resolve(path.dirname(entry.from), target);
+          const owned = entry.replacement !== undefined ? resolved === entry.replacement && resolved !== null
+            : resolved && (resolved.startsWith(p.current + path.sep) || resolved.startsWith(p.hub + path.sep));
+          if (!owned) throw new Error(`Restore conflict at ${entry.from}; move the replacement aside and retry.`);
+          fs.unlinkSync(entry.from);
+        }
+        fs.mkdirSync(path.dirname(entry.from), { recursive: true });
+        fs.renameSync(entry.to, entry.from);
+        restored.push(entry.from);
+      } else if (!lstat(entry.from)) {
+        throw new Error(`Restore source missing: ${entry.to}; preserve the quarantine for recovery.`);
+      }
+      // Also recognise already-restored entries from releases with no checkpoint.
+      entry.restoredAt = new Date().toISOString();
+      writeJson(journal, entries);
     }
   }
   return restored;
@@ -303,12 +381,13 @@ function restoreMarketplace(p, entry, claude) {
       notes.push(`settings.json not restored (${error.message}); the original is at ${entry.settingsBackup}`);
     }
   }
-  return `marketplace ${entry.name}${notes.length ? ` (${notes.join('; ')})` : ''}`;
+  if (notes.length) throw new Error(`Could not fully restore marketplace ${entry.name}: ${notes.join('; ')}. Retry restore after fixing it.`);
+  return `marketplace ${entry.name}`;
 }
 
 function status({ home, claude = claudeRunner() } = {}) {
   const p = paths(home);
-  const state = readJson(p.stateFile, {});
+  const state = readState(p.stateFile, { tolerant: true });
   let payload = null;
   try { payload = payloadManifest(); } catch (_) { /* reported as unknown */ }
   // What is installed is the release `current` points at. The payload beside this CLI is
@@ -330,7 +409,7 @@ function status({ home, claude = claudeRunner() } = {}) {
     shadows: m.skills.filter((s) => lstat(path.join(p.claudeSkills, s))),
   }));
   return {
-    installed: state.installed || (release ? release.version : null), latest: state.latest || null, checkedAt: state.checkedAt || null,
+    installed: release ? release.version : (state.installed || null), latest: state.latest || null, checkedAt: state.checkedAt || null,
     package: payload ? payload.version : null, source: release ? 'installed' : (payload ? 'package' : null),
     auto: (state.config || {}).auto !== false, members,
   };
@@ -339,7 +418,7 @@ function status({ home, claude = claudeRunner() } = {}) {
 function setConfig({ home, key, value }) {
   if (key !== 'update.auto' || !['on', 'off'].includes(value)) throw new Error('Only `config set update.auto on|off` is supported.');
   const p = paths(home);
-  const state = readJson(p.stateFile, {});
+  const state = readState(p.stateFile);
   state.config = { ...(state.config || {}), auto: value === 'on' };
   writeJson(p.stateFile, state);
   return state.config;
@@ -347,24 +426,49 @@ function setConfig({ home, key, value }) {
 
 function uninstall({ home, claude = claudeRunner() } = {}) {
   const p = paths(home);
-  let manifest;
-  try { manifest = payloadManifest(p.current); } catch (_) { manifest = { members: [] }; }
+  readState(p.stateFile); // refuse to overwrite a damaged recovery record
+  const manifest = lstat(p.current) ? payloadManifest(p.current) : { members: [] };
   const removed = [];
+  const failures = [];
+  const hasClaude = claude.available();
+  const installedIds = () => Object.keys(readJson(path.join(p.claudePlugins, 'installed_plugins.json'), { plugins: {} }).plugins || {});
   for (const m of manifest.members) {
     for (const skill of m.skills) {
       const hubLink = path.join(p.hub, skill);
-      if (linkTarget(hubLink) === path.join(p.current, 'plugins', m.name, 'skills', skill)) { fs.unlinkSync(hubLink); removed.push(hubLink); }
+      if (pointsTo(hubLink, path.join(p.current, 'plugins', m.name, 'skills', skill))) { fs.unlinkSync(hubLink); removed.push(hubLink); }
       for (const c of CHANNELS) {
         const at = path.join(p.home, c, skill);
-        if (linkTarget(at) === hubLink) { fs.unlinkSync(at); removed.push(at); }
+        if (pointsTo(at, hubLink)) { fs.unlinkSync(at); removed.push(at); }
       }
     }
-    if (claude.available()) {
-      const r = claude.run(['plugin', 'uninstall', `${m.name}@${MARKETPLACE}`]);
-      if (r.code === 0) removed.push(`${m.name}@${MARKETPLACE}`);
+    const id = `${m.name}@${MARKETPLACE}`;
+    if (installedIds().includes(id)) {
+      if (!hasClaude) { failures.push(`${id}: Claude Code CLI not found`); continue; }
+      const r = claude.run(['plugin', 'uninstall', id]);
+      if (r.code === 0 && !installedIds().includes(id)) removed.push(id);
+      else failures.push(`${id}: ${r.out || 'plugin remains registered after uninstall'}`);
     }
   }
-  if (claude.available()) claude.run(['plugin', 'marketplace', 'remove', MARKETPLACE]);
+  const known = readJson(path.join(p.claudePlugins, 'known_marketplaces.json'), {});
+  if (!failures.length && known[MARKETPLACE] && !installedIds().some((id) => id.endsWith(`@${MARKETPLACE}`))) {
+    if (!hasClaude) failures.push('Claude Code CLI not found; marketplace remains registered');
+    else {
+      const r = claude.run(['plugin', 'marketplace', 'remove', MARKETPLACE]);
+      if (r.code !== 0) failures.push(r.out || 'marketplace remove failed');
+    }
+  }
+  if (failures.length) throw new Error(`Uninstall incomplete: ${failures.join('; ')}. Fix the error and retry uninstall.`);
+  if (lstat(p.current)) {
+    if (!lstat(p.current).isSymbolicLink()) throw new Error(`Refusing to remove non-symlink ${p.current}.`);
+    fs.unlinkSync(p.current);
+  }
+  const state = readState(p.stateFile);
+  state.installed = null;
+  state.members = [];
+  state.config = { ...(state.config || {}), auto: false };
+  delete state.installedAt;
+  delete state.updatingSince;
+  writeJson(p.stateFile, state);
   return removed;
 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@passioncode-ai/passioncode",
-  "version": "0.1.14",
-  "description": "The PassionCode.ai agent skill set — Fabric Agent Adapter, Observatory Log and the organisation's working rules — for Claude Code and every other agent on the machine, updated as one set.",
+  "version": "0.1.16",
+  "description": "The PassionCode.ai agent skill set \u2014 Fabric Agent Adapter, Observatory Log and the organisation's working rules \u2014 for Claude Code and every other agent on the machine, updated as one set.",
   "bin": {
     "passioncode": "bin/passioncode.js"
   },
@@ -23,8 +23,8 @@
   "scripts": {
     "vendor": "node scripts/vendor.mjs",
     "vendor:release": "node scripts/vendor.mjs --release",
-    "test": "node --test 'test/*.test.js'",
-    "prepublishOnly": "node scripts/vendor.mjs --release && node --test 'test/*.test.js'"
+    "test": "node scripts/test.mjs",
+    "prepublishOnly": "node scripts/vendor.mjs --release && node scripts/test.mjs"
   },
   "engines": {
     "node": ">=18"

package/payload/.claude-plugin/marketplace.json

@@ -35,7 +35,7 @@
       "name": "passioncode",
       "displayName": "PassionCode.ai",
       "source": "./plugins/passioncode",
-      "version": "0.1.14",
+      "version": "0.1.16",
       "description": "The organisation's working rules for every contributor's agent (working-in-passioncode), and a once-a-day check that keeps the PassionCode.ai set current.",
       "author": {
         "name": "PassionCode.ai",

package/payload/manifest.json

@@ -1,6 +1,6 @@
 {
   "family": "passioncode",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "release": true,
   "members": [
     {
@@ -61,16 +61,16 @@
       "name": "passioncode",
       "displayName": "PassionCode.ai",
       "repo": "passioncode-ai/passioncode",
-      "ref": "v0.1.14",
+      "ref": "v0.1.16",
       "commit": null,
-      "version": "0.1.14",
+      "version": "0.1.16",
       "via": "this repository",
       "skills": [
         "working-in-passioncode"
       ],
       "legacyPluginIds": [],
       "legacyMarketplaces": [],
-      "contentHash": "sha256:a09752a2968ea3bd192898fe28642166548786a6396050f57e02f36ea9fe2742",
+      "contentHash": "sha256:15d7a746ecf165e574f87a28af46bd0ea04255b86cc3351ee0d96778bb741447",
       "description": "The organisation's working rules for every contributor's agent (working-in-passioncode), and a once-a-day check that keeps the PassionCode.ai set current.",
       "author": {
         "name": "PassionCode.ai",

package/payload/plugins/passioncode/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "passioncode",
   "displayName": "PassionCode.ai",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "The organisation's working rules for every contributor's agent (working-in-passioncode), and a once-a-day check at session start that keeps the PassionCode.ai skill set current.",
   "author": {
     "name": "PassionCode.ai",

package/payload/plugins/passioncode/hooks/repo-rules.js

@@ -32,7 +32,7 @@ function originOf(dir) {
 /** The one line to print at session start in `dir`, or null. */
 function rulesLine(dir) {
   if (!orgOf(originOf(dir))) return null;
-  return `[passioncode] passioncode-ai repository: read the knowledge base (${KNOWLEDGE} or ${KNOWLEDGE_WEB}), then this repository's AGENTS.md, before the first edit; after the work, update the knowledge base page that owns any cross-repository fact you changed.`;
+  return `[passioncode] passioncode-ai repository: read the knowledge base (${KNOWLEDGE} or ${KNOWLEDGE_WEB}), then this repository's AGENTS.md, before the first edit; after the work, update the knowledge base page that owns any cross-repository fact you changed; edit each canonical task source declared in docs/backlog-sources.json and publish the derived workspace backlog.`;
 }
 
 module.exports = { KNOWLEDGE, KNOWLEDGE_WEB, orgOf, rulesLine };

package/payload/plugins/passioncode/hooks/session-start.js

@@ -16,24 +16,32 @@ const DIR = process.env.PASSIONCODE_HOME || path.join(os.homedir(), '.passioncod
 const STATE = path.join(DIR, 'state.json');
 const DAY = 24 * 60 * 60 * 1000;
 
-function read(file, fallback) { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (_) { return fallback; } }
+function read(file, fallback) {
+  try { const doc = JSON.parse(fs.readFileSync(file, 'utf8')); return doc && typeof doc === 'object' && !Array.isArray(doc) ? doc : fallback; }
+  catch (_) { return fallback; }
+}
 function detached(cmd, args, logName) {
-  try {
-    fs.mkdirSync(path.join(DIR, 'logs'), { recursive: true });
-    const out = fs.openSync(path.join(DIR, 'logs', logName), 'a');
-    spawn(cmd, args, { detached: true, stdio: ['ignore', out, out], env: process.env }).unref();
-    return true;
-  } catch (_) { return false; /* a missing npm must not break the session */ }
+  return new Promise((resolve) => {
+    let out;
+    try {
+      fs.mkdirSync(path.join(DIR, 'logs'), { recursive: true });
+      out = fs.openSync(path.join(DIR, 'logs', logName), 'a');
+      const child = spawn(cmd, args, { detached: true, stdio: ['ignore', out, out], env: process.env });
+      child.once('error', () => resolve(false));
+      child.once('spawn', () => { child.unref(); resolve(true); });
+    } catch (_) { resolve(false); }
+    finally { if (out !== undefined) fs.closeSync(out); }
+  });
 }
 
-try {
+async function main() {
   const state = read(STATE, {});
   const now = Date.now();
-  if (!state.checkedAt || !(now - Date.parse(state.checkedAt) <= DAY)) {
-    detached(process.execPath, [path.join(__dirname, 'probe.js')], 'probe.log');
+  const age = now - Date.parse(state.checkedAt);
+  if (!Number.isFinite(age) || age < 0 || age > DAY) {
+    await detached(process.execPath, [path.join(__dirname, 'probe.js')], 'probe.log');
   }
   const { lines, spawn: args, stateChanges } = decide(state, loadTrust(), now);
-  if (args && !detached('npx', args, 'update.log')) delete stateChanges.updatingSince;
   if (Object.keys(stateChanges).length) {
     // Re-read: the probe may have written meanwhile; only our own keys change.
     const fresh = { ...read(STATE, {}), ...stateChanges };
@@ -42,10 +50,24 @@ try {
     fs.writeFileSync(tmp, JSON.stringify(fresh, null, 2));
     fs.renameSync(tmp, STATE);
   }
+  // Record the attempt before spawning: a fast update must not finish and then
+  // have this hook put the old "running" marker back.
+  if (args && !await detached('npx', args, 'update.log')) {
+    const fresh = read(STATE, {});
+    if (fresh.updatingSince === stateChanges.updatingSince) {
+      delete fresh.updatingSince;
+      const tmp = `${STATE}.${process.pid}.hook`;
+      fs.writeFileSync(tmp, JSON.stringify(fresh, null, 2));
+      fs.renameSync(tmp, STATE);
+    }
+    lines.pop(); // decide appends the update-start notice last when it returns args
+    lines.push('[passioncode] could not start the background update; check that npx is on PATH and retry next session.');
+  }
   // Claude Code passes the session's directory on stdin; the process cwd is the fallback.
   let cwd = process.cwd();
   try { const input = JSON.parse(fs.readFileSync(0, 'utf8') || '{}'); if (input && typeof input.cwd === 'string') cwd = input.cwd; } catch (_) { /* no stdin */ }
   const rules = rulesLine(cwd);
   if (rules) lines.unshift(rules);
   if (lines.length) process.stdout.write(lines.join('\n') + '\n');
-} catch (_) { /* never fail a session start */ }
+}
+main().catch(() => { /* never fail a session start */ });

package/payload/plugins/passioncode/hooks/update-check.js

@@ -47,10 +47,13 @@ function accountName(entry) {
 function parseView(stdout, error) {
   let doc = null;
   try { doc = JSON.parse(String(stdout || '').trim()); } catch (_) { /* judged below */ }
+  // npm 12 wraps a single-version answer in an array; ambiguous answers stay rejected.
+  if (Array.isArray(doc) && doc.length === 1) doc = doc[0];
   if (doc && typeof doc === 'object' && doc.error) {
     if (doc.error.code === 'E404') return { published: false };
     return { checkError: `${doc.error.code || 'npm error'}: ${oneLine(doc.error.summary || '')}`.trim() };
   }
+  if (error) return { checkError: oneLine(error.message) };
   if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
     return { checkError: error ? oneLine(error.message) : 'npm answered with something that is not the expected JSON' };
   }
@@ -117,16 +120,18 @@ function decide(state, trust, now = Date.now()) {
 
   const latest = typeof state.latest === 'string' && VERSION.test(state.latest) ? state.latest : null;
   if (state.published !== false && latest && state.installed && newer(latest, state.installed)) {
-    const maintainers = Array.isArray(state.maintainers) ? state.maintainers.filter((m) => typeof m === 'string') : [];
+    const maintainers = Array.isArray(state.maintainers) ? state.maintainers : [];
     const trusted = new Set(trust);
     const untrusted = [...maintainers, ...(state.publisher ? [state.publisher] : [])].filter((m) => !trusted.has(m));
-    if (!maintainers.length) {
+    if (!maintainers.length || !maintainers.every((m) => typeof m === 'string' && accountName(m) === m)
+      || typeof state.publisher !== 'string' || !state.publisher || accountName(state.publisher) !== state.publisher) {
       lines.push(`[passioncode] ${PACKAGE}@${latest} is on npm but who published it could not be read — not installing; see SECURITY.md.`);
     } else if (untrusted.length) {
       lines.push(`[passioncode] ${PACKAGE}@${latest} is on npm but published by ${[...new Set(untrusted)].join(', ')}, not a trusted PassionCode publisher — not installing; see SECURITY.md.`);
     } else {
       const auto = (state.config && state.config.auto) !== false;
-      const running = state.updatingSince && now - Date.parse(state.updatingSince) < 10 * 60 * 1000;
+      const runningAge = now - Date.parse(state.updatingSince);
+      const running = Number.isFinite(runningAge) && runningAge >= 0 && runningAge < 10 * 60 * 1000;
       if (auto && !running) {
         spawn = ['--yes', `${PACKAGE}@${latest}`, 'update', '--quiet'];
         stateChanges.updatingSince = new Date(now).toISOString();

package/payload/plugins/passioncode/skills/working-in-passioncode/SKILL.md

@@ -117,7 +117,7 @@ Also, before the first edit:
 - **Ids.** In a repository with `.claude/agent-sync.json`, reserve an id before writing
   it: `agent_sync.py reserve <REGISTER>` (for example `ADR` in fabric). Reading the
   "next free id" line is not reserving it — two agents read the same number.
-- **Leases.** `fabric` and `fabric-agent-contract` guard shared files (their
+- **Leases.** Every enrolled repository guards its declared shared files (its
   `docs/AGENT_SYNC.md` lists them) under a git lease, a ref under
   `refs/agent-sync/leases/` on `origin`, so both machines see it. `acquire` → edit →
   `release`, on every path, failure included.
@@ -128,6 +128,17 @@ Also, before the first edit:
 agent-sync missing: `npx @ssheleg/agent-sync install`. If it cannot be installed, do
 not edit a guarded file — say which file and why you stopped.
 
+### The common backlog
+
+The workspace's `knowledge/backlog.md` owns the aggregation contract. Each repository's
+`docs/backlog-sources.json` declares the canonical local task sources and their vision goals.
+Read those sources before choosing work. Update status only in the owning source under a lease,
+keep stable IDs and closure receipts, and add a new source to the manifest in the same change.
+A cross-repository task has one owner; other repositories link to it instead of copying status.
+The common view at https://wiki.passioncode.ai/backlog is generated from these sources and their
+commit identities. Never edit generated task status. Land the local change, publish through
+Fabric's workspace sync, and check the published source commit before calling it current.
+
 ## 5. Secrets
 
 - Never in Git, a chat message, an issue, a command argument, a URL query string or a
@@ -202,8 +213,8 @@ to a public surface.
   `project-observatory full update --check` and `--apply`.
 - **Launcher** (`passioncode`): members are tagged first, `family.json` refs point at
   those tags, the payload is vendored from tags only.
-- **Contract pins.** `fabric-agent-contract` has no tags, so consumers pin commits, and
-  the pins disagree (org-index `BACKLOG.md` X-4). Move a pin only in a release of the
+- **Contract pins.** `fabric-agent-contract` consumers carry explicit commit pins;
+  compatibility work is tracked in the owning consumer backlog and the derived workspace view. Move a pin only in a release of the
   consumer, and only when its own validation passes against the new commit.
 
 Read [releasing](references/releasing.md) for the step-by-step of each repository's

package/payload/plugins/passioncode/skills/working-in-passioncode/references/releasing.md

@@ -58,7 +58,7 @@ The README section "Validate this repository" is the gate:
 ```bash
 python3 -m unittest discover -s test -v
 python3 test/validate.py
-node --test 'test/*.test.js'
+node --test 'test/*.test.mjs'
 claude plugin validate ./plugins/fabric-agent-adapter --strict
 claude plugin validate . --strict
 ```
@@ -78,16 +78,17 @@ manifests. Trigger and scenario evals change before the instructional prose they
 
 ## Contract pins
 
-- `fabric-agent-contract` publishes no tags; consumers (fabric, the adapter, the
-  Observatory) pin a commit. The pins disagree today — org-index `BACKLOG.md` X-4 tracks
-  it.
+- Consumers declare their own explicit contract pins. Read the actual lock or
+  submodule commit, then the owning consumer backlog and shared workspace view;
+  do not infer compatibility from matching version labels.
 - Moving a pin is a compatibility change of the **consumer**: run the consumer's own
   validation against the new contract commit (for the adapter:
   `adapt_project.py check <bundle> --contract <checkout at the new commit>` for each
   profile), review what changed between the two commits, and ship it as a new consumer
   release. If the validation does not pass, leave the pin and report why.
-- `project-observatory-contract` publishes immutable `rev-N` tags; a schema `$id` change
-  needs a new `rev-N`.
+- `project-observatory-contract` preserves historical immutable `rev-N` tags. Current
+  Project Observatory schemas ship with the engine release and its per-file release pins;
+  the engine publication checker refuses the retired `--stage` and `--publish` operations.
 
 ## After a release