Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript

skillpack: safe whole-skill updates for installed skills (--update-untouched)

garrytanb2510076922b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0f6ee23392..47ee1e92c4 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -25,6 +25,20 @@ Every `gbrain ...` invocation a bundled skill shows now runs through the dispatc
| A SKILL.md grows past its ceiling, or a new one passes 16 KB | passed | fails; raising a ceiling is a reviewer-visible edit |
| `skills-commit-gate.sh` | four checks | also runs the skill health guard and prints `Skill-size:` lines for staged skills |
+**Installed skills you never edited can take gbrain's current version whole, and that update never overwrites a skill you edited.**
+
+`gbrain skillpack reference <name>|--all --update-untouched` replaces a skill only when every one of its files still matches what gbrain installed. Scaffold, sync and harness installs now record the sha256 of each skill file they write, per skills root. A skill with any edited file, a pinned skill (`gbrain skillpack pin`), or a file with no recorded base that matches no released version is skipped whole and its diff is printed. Installs from before bases were recorded can opt in with `--accept-historical` when every file equals a released version listed in the new `skills/skills.lock.history.json`. Every update writes a journal and backups to `~/.gbrain/skillpack-backups/<id>/` before it changes anything, rehashes each file right before replacing it, and runs the conformance, trigger and resolver checks; a failure rolls back only the files that still hold the update's bytes. `gbrain skillpack restore <id>` undoes an update and refuses files you changed since, unless you name them with `--skip`. It never prompts (`--dry-run` is the preview), works the same on a brain with no git repository, and `gbrain upgrade` writes no skill files.
+
+### Skill updates
+
+| Situation | Before | Now |
+|---|---|---|
+| You want gbrain's new version of skills you never touched | `--apply-clean-hunks` applied hunks two-way and could not tell your edits from gbrain's | `--update-untouched` replaces only skills whose every file still matches the install |
+| A skill you edited or pinned | `--apply-clean-hunks` could overwrite it hunk by hunk | skipped with `local_edits` or `pinned` and its diff |
+| An update fails a check or the process dies mid-update | — | rolled back per skill; doctor reports `skillpack_update_incomplete` with the restore command |
+| Exit code of an update | — | 0 nothing failed, 1 with `--fail-on-skipped` when a skill was skipped, 2 on a failure |
+| `~/.gbrain/skillpack-state.json` | schema v1 | schema v2 with per-skill bases and pins; a v1 file still loads |
+
## [0.60.474.0] - 2026-10-27
**A database role that can't read the writer state is now refused instead of let through.**
diff --git a/docs/INSTALL.md b/docs/INSTALL.md
index 940b8e1e25..724b5993bc 100644
--- a/docs/INSTALL.md
+++ b/docs/INSTALL.md
@@ -38,7 +38,7 @@ Connect and verify the intended harness before calling it activated. Entity
capture, recurring jobs and paid enrichment require separate opt-in; none of
the commands above schedules a daily enrichment job.
-Scaffolded skills are first-class files in your agent repo — edit freely. To pull upstream gbrain improvements later, `gbrain skillpack reference <name>` diffs your local copy vs the bundle. If your `RESOLVER.md` / `AGENTS.md` still carries the managed `skillpack install` fence, `gbrain skillpack migrate-fence` strips it once and keeps the routing rows inside it.
+Scaffolded skills are first-class files in your agent repo — edit freely. To pull upstream gbrain improvements later, `gbrain skillpack reference <name>` diffs your local copy vs the bundle, and `gbrain skillpack reference --all --update-untouched` replaces the skills you never edited (`--dry-run` previews). If your `RESOLVER.md` / `AGENTS.md` still carries the managed `skillpack install` fence, `gbrain skillpack migrate-fence` strips it once and keeps the routing rows inside it.
To upgrade later, use the [memory-only upgrade path](#memory-only-upgrades)
unless services and provider work were deliberately configured. Upgrade runs
diff --git a/docs/architecture/key-files/skills.md b/docs/architecture/key-files/skills.md
index 0e4cbe346b..d2b1df7199 100644
--- a/docs/architecture/key-files/skills.md
+++ b/docs/architecture/key-files/skills.md
@@ -31,8 +31,9 @@ Current behavior and load-bearing invariants; history belongs in Git and CHANGEL
- `src/core/skillpack/{init-brain-pack,brain-pack-advisory,brain-resident-locate,nag-state}.ts` — brain-resident skillpacks. `manifest-v1.ts` gains optional `brain_resident` + `schema_pack` (additive). `runInitBrainPack` scaffolds a pack beside brain content (`brain_resident:true`, exact `gbrain_min_version`, 5-section machine-parseable README); `applyWritePlan` is factored out of `init-scaffold.ts` for the shared refuse-overwrite loop. Topology A: `src/commands/sources.ts` `runAdd` prints `brain-pack-advisory` to stderr after `opsAddSource`, fail-open; `nag-state.ts` (`~/.gbrain/skillpack-nag-state.json`) keys declines by `(source-repo brain_id, source_id, pack_name)` with pure `decideNagAction` (first/reminder/version-bump/ceiling) — declines count ONLY on CLI-interactive displays. Topology B: `brain-resident-locate.loadResidentPacksForServer` (source-scoped via `sourceScopeOpts`) backs the `list_brain_skillpack` op; `getResidentSkillDetail` backs `get_skill` `source_id`; `scaffold_spec` is the git source, never a server FS path. Tests: `test/skillpack-{init-brain-pack,nag-state,brain-resident-locate}.test.ts` + the brain-resident cases in `test/skillpack-manifest-v1.test.ts`.
-- `src/core/skillpack/{manifest-v1,tarball,state,remote-source,trust-prompt,bootstrap-display,scaffold-third-party,registry-schema,registry-client,rubric,doctor,init-scaffold,pack-publish,endorse,audit}.ts` + `examples/skillpack-reference/` + `docs/skillpack-anatomy.md` + `scripts/build-skillpack-anatomy.ts` — third-party skillpack ecosystem. `gbrain skillpack scaffold <owner/repo|https-url|./tgz|./local-dir>` resolves the spec via `classifySpec`, fetches through SSRF-hardened `git-remote.ts` (git) or extracts the tarball into `~/.gbrain/skillpack-cache/<host>/<owner>/<repo>/<sha>/`, validates `skillpack.json` (api_version `gbrain-skillpack-v1`), checks `gbrain_min_version`, surfaces a TOFU first-install identity-confirm prompt (author + source + pinned commit + tarball SHA + tier; prompted through interaction.readLine; with no human at the terminal the CLI asks through `requireConsent` (effect `persistent_install`, preapprovals never apply): `--trust` or `--yes` is the user's approval, otherwise nothing is written and it exits 3 with the consent payload), records the pin in machine-owned `~/.gbrain/skillpack-state.json` (schema `gbrain-skillpack-state-v1`, atomic `.tmp + rename`, `isAlreadyTrusted` skips re-prompt on author+pin match), runs through `enumerateScaffoldEntries` → `copyArtifacts` (one-time additive, refuses to overwrite), then DISPLAYS `runbooks/bootstrap.md` WITHOUT executing (deliberately does not auto-execute). Registry catalog at `garrytan/gbrain-skillpack-registry` split into `registry.json` (PR-able, `gbrain-registry-v1`) + `endorsements.json` (maintainer-only overlay, `gbrain-endorsements-v1`); `effectiveTier` merges. `registry-client.ts` fetches both via `If-None-Match` etag with 1h soft-TTL + stale-fallback (origins `fresh_fetch | cache_warm | cache_soft_stale | cache_hard_stale`); hard-fail only on no-cache + no-network. CLI: `gbrain skillpack {search,info,registry,doctor,init,pack,endorse}`. Doctor walks `SKILLPACK_RUBRIC_V1` (10 binary dimensions: 5 required CORE — manifest_valid, skills_have_skill_md, routing_evals_present ≥5 intents, skills_have_unique_triggers MECE, changelog_present_and_current — and 5 quality BADGES — unit_tests_present, e2e_tests_present, llm_eval_present ≥3 cases, bootstrap_runbook_present, license_present); tier eligibility: `endorsed` needs all 10, `community` needs core + ≥3 badges, `experimental` needs core only, `blocked` when any core fails. `--quick` ~5s structural sweep; `--fix --yes` auto-scaffolds `auto_fixable: true` dimensions and refuses to overwrite files whose mtime is newer than `skillpack.json`. `gbrain skillpack init <name>` lands 11 files (skillpack.json, SKILL.md, routing-eval.jsonl, test/example.test.ts, e2e/example.e2e.test.ts, evals/example.judge.json, runbooks/{bootstrap,uninstall,upgrade-template}.md, CHANGELOG, README, LICENSE); freshly-init'd scores 10/10; `--minimal` skips test/e2e/evals. `gbrain skillpack pack` packs a deterministic tarball via GNU tar (`--sort=name --mtime=@0 --owner=0 --group=0 --numeric-owner` + `GZIP=-n` + `TZ=UTC`); refuses on `tier_eligibility === 'blocked'`. Extract caps (5000 files / 100MB total / 1MB per file / 255-char paths / 100:1 compression ratio); rejects symlinks/hardlinks/devices/FIFOs. `gbrain skillpack endorse <name> [--tier ...] [--push] [--dry-run]` runs in a clone of the registry repo: validates the pack in `registry.json`, mutates `endorsements.json` via pure `applyEndorsement`, stable-key-orders the write, commits `endorse: <name> -> <tier>`, optionally pushes. JSONL audit at `~/.gbrain/audit/skillpack-YYYY-Www.jsonl` (ISO-week rotated, honors `GBRAIN_AUDIT_DIR`). `examples/skillpack-reference/` is a 10/10 reference pack pinned by `test/e2e/skillpack-third-party.test.ts`. `docs/skillpack-anatomy.md` auto-generated via `scripts/build-skillpack-anatomy.ts` (`--check` for CI drift). CLI dispatch in `src/commands/skillpack.ts` disambiguates third-party (contains `/`, `://`, `.tgz`) from bundled-skill kebab; kebab routes bundled-first, registry-fallback. Tests: `test/skillpack-{manifest-v1,tarball,state,remote-source,trust-prompt,registry-schema,registry-client,rubric,doctor,init-scaffold,pack-publish,endorse,audit,scaffold-third-party}.test.ts` + `test/e2e/skillpack-third-party.test.ts`. Spec at `docs/designs/SKILLPACK_REGISTRY_V1_SPEC.md`.
+- `src/core/skillpack/{manifest-v1,tarball,state,remote-source,trust-prompt,bootstrap-display,scaffold-third-party,registry-schema,registry-client,rubric,doctor,init-scaffold,pack-publish,endorse,audit}.ts` + `examples/skillpack-reference/` + `docs/skillpack-anatomy.md` + `scripts/build-skillpack-anatomy.ts` — third-party skillpack ecosystem. `gbrain skillpack scaffold <owner/repo|https-url|./tgz|./local-dir>` resolves the spec via `classifySpec`, fetches through SSRF-hardened `git-remote.ts` (git) or extracts the tarball into `~/.gbrain/skillpack-cache/<host>/<owner>/<repo>/<sha>/`, validates `skillpack.json` (api_version `gbrain-skillpack-v1`), checks `gbrain_min_version`, surfaces a TOFU first-install identity-confirm prompt (author + source + pinned commit + tarball SHA + tier; prompted through interaction.readLine; with no human at the terminal the CLI asks through `requireConsent` (effect `persistent_install`, preapprovals never apply): `--trust` or `--yes` is the user's approval, otherwise nothing is written and it exits 3 with the consent payload), records the pin in machine-owned `~/.gbrain/skillpack-state.json` (schema `gbrain-skillpack-state-v2`, which adds per-skills-root install bases and pins and reads a v1 file as v2 with none; atomic unique temp file + rename; read-modify-write callers go through `updateState` under the state lock, `isAlreadyTrusted` skips re-prompt on author+pin match), runs through `enumerateScaffoldEntries` → `copyArtifacts` (one-time additive, refuses to overwrite), then DISPLAYS `runbooks/bootstrap.md` WITHOUT executing (deliberately does not auto-execute). Registry catalog at `garrytan/gbrain-skillpack-registry` split into `registry.json` (PR-able, `gbrain-registry-v1`) + `endorsements.json` (maintainer-only overlay, `gbrain-endorsements-v1`); `effectiveTier` merges. `registry-client.ts` fetches both via `If-None-Match` etag with 1h soft-TTL + stale-fallback (origins `fresh_fetch | cache_warm | cache_soft_stale | cache_hard_stale`); hard-fail only on no-cache + no-network. CLI: `gbrain skillpack {search,info,registry,doctor,init,pack,endorse}`. Doctor walks `SKILLPACK_RUBRIC_V1` (10 binary dimensions: 5 required CORE — manifest_valid, skills_have_skill_md, routing_evals_present ≥5 intents, skills_have_unique_triggers MECE, changelog_present_and_current — and 5 quality BADGES — unit_tests_present, e2e_tests_present, llm_eval_present ≥3 cases, bootstrap_runbook_present, license_present); tier eligibility: `endorsed` needs all 10, `community` needs core + ≥3 badges, `experimental` needs core only, `blocked` when any core fails. `--quick` ~5s structural sweep; `--fix --yes` auto-scaffolds `auto_fixable: true` dimensions and refuses to overwrite files whose mtime is newer than `skillpack.json`. `gbrain skillpack init <name>` lands 11 files (skillpack.json, SKILL.md, routing-eval.jsonl, test/example.test.ts, e2e/example.e2e.test.ts, evals/example.judge.json, runbooks/{bootstrap,uninstall,upgrade-template}.md, CHANGELOG, README, LICENSE); freshly-init'd scores 10/10; `--minimal` skips test/e2e/evals. `gbrain skillpack pack` packs a deterministic tarball via GNU tar (`--sort=name --mtime=@0 --owner=0 --group=0 --numeric-owner` + `GZIP=-n` + `TZ=UTC`); refuses on `tier_eligibility === 'blocked'`. Extract caps (5000 files / 100MB total / 1MB per file / 255-char paths / 100:1 compression ratio); rejects symlinks/hardlinks/devices/FIFOs. `gbrain skillpack endorse <name> [--tier ...] [--push] [--dry-run]` runs in a clone of the registry repo: validates the pack in `registry.json`, mutates `endorsements.json` via pure `applyEndorsement`, stable-key-orders the write, commits `endorse: <name> -> <tier>`, optionally pushes. JSONL audit at `~/.gbrain/audit/skillpack-YYYY-Www.jsonl` (ISO-week rotated, honors `GBRAIN_AUDIT_DIR`). `examples/skillpack-reference/` is a 10/10 reference pack pinned by `test/e2e/skillpack-third-party.test.ts`. `docs/skillpack-anatomy.md` auto-generated via `scripts/build-skillpack-anatomy.ts` (`--check` for CI drift). CLI dispatch in `src/commands/skillpack.ts` disambiguates third-party (contains `/`, `://`, `.tgz`) from bundled-skill kebab; kebab routes bundled-first, registry-fallback. Tests: `test/skillpack-{manifest-v1,tarball,state,remote-source,trust-prompt,registry-schema,registry-client,rubric,doctor,init-scaffold,pack-publish,endorse,audit,scaffold-third-party}.test.ts` + `test/e2e/skillpack-third-party.test.ts`. Spec at `docs/designs/SKILLPACK_REGISTRY_V1_SPEC.md`.
- `src/core/skillpack/{personas,bridge-state,harness-bridge}.ts` + `src/commands/skillpack/{shared,scaffold,reference,harness}.ts` — the harness skill bridge. `src/commands/skillpack.ts` is a peeled FAÇADE (dispatch + HELP_TOP + the install/uninstall removal errors; module-size ratchet); per-subcommand handlers live in `src/commands/skillpack/` and the flag registry scans the dir via the façade's `facadeExpansion` entry — spell foreign CLI flags dash-less in these modules' comments/strings (prose-bleed class). `scaffold --harness <claude-code|openclaw|codex|opencode>` installs a persona-curated set into the harness's native skills dir: personas live in `skills/plugin-lanes.json#personas` (`personas.ts` is the SINGLE validation implementation — `scripts/generate-plugin-tree.ts` imports it; membership ⊆ the plugin lane set, so lane-excluded slugs are refused with their recorded reason); slugs path-resolve via `bundle.ts`'s `universe:'manifest'` (the 8 lane additions are all absent from openclaw.plugin.json#skills). Safety: frontmatter fail-loud gate pre-write (a frontmatterless SKILL.md bricks Codex sessions), target-side confinement in `assertTargetsConfined` (deepest-existing-ancestor realpath — copy.ts confines SOURCES only), refuse-overwrite, and written-only ownership in `bridge-state.ts` (`~/.gbrain/skillpack-bridge-state.json`, schema `gbrain-skillpack-bridge-v1`, fail-open load, install-time sha256 per written file — never touches `skillpack-state.json`, whose loader drops unknown keys). `--stub` renders cold-pull pointers (frontmatter verbatim + `<!-- gbrain-skill-stub v1 -->` marker; ships the shared-dep closure AND sibling aux files — `get_skill` serves only the SKILL.md body) behind a three-check preflight in `src/commands/skillpack/harness.ts` (publish gate dual-plane, per-slug servability via `verifySlugsServable`, best-effort local surface warn — the module deliberately does NOT import `src/mcp/surface.ts`, whose comments would bleed serve flags into the allowlist; `get_skill ∉ STARTER_OPS` is pinned by a contract test). `reference --harness` is a stub-aware three-way lens (`local_edit` vs `upstream_drift` vs `unknown` — no install-time hash, never auto-applied — via the hash ledger; marker fallback survives state loss both directions) + `--apply-clean-hunks` (refuses stub files); `remove --harness` deletes ledger-owned files only; `skillpack status` renders an installed-bridges section from `collectBridgesStatus`. openclaw delegates to `runScaffold({skillSlugs})`; codex/opencode require an explicit dest until observation runs. Claude-code dirs come from `host-specs.ts` (`claudeUserSkillsDir`/`claudeProjectSkillsDir`, HOME-env-first). Tests: `test/skillpack-{personas,bridge-state,harness-bridge,reference-harness,scaffold-harness}.test.ts`. Doc: the harness-bridge section of `docs/guides/skillpacks-as-scaffolding.md`. #5912: `ownedBridgeSlugs(entry)` (harness-bridge.ts) is the one accessor for an install's skill slugs without the reserved `SHARED_DEP_LEDGER_KEY`, used by the no-slug reference lens, bridge status and remove; the scaffold "Update lens" / remove hints repeat the `--dest`, `--scope project` and `--workspace` the user passed.
-- `src/core/skills-integrity.ts` — Tamper-evidence manifest for the bundled `skills/` tree; NOT a signature system. Pure functions over `node:crypto` sha256: `computeSkillsManifest(dir)` (recursive, sorted '/'-relative paths, excludes the manifest itself, skips symlinks), `renderSkillsManifest(dir)` (2-space JSON + trailing newline, deterministic), `verifySkillsManifest(dir, manifest)` → `{modified, missing, extra}`. Committed manifest lives at `skills/skills.lock.json` (`SKILLS_MANIFEST_FILENAME`); regenerate via `bun run scripts/generate-skills-manifest.ts`. Consumers: the warn-only `skills_manifest_integrity` doctor check in `src/commands/doctor/skill-checks.ts` (ok/skip when no manifest is present — user workspaces and compiled-binary installs are not drift) and the CI freshness guard `scripts/check-skills-manifest-fresh.sh` (`bun run check:skills-manifest`, in `bun run verify`). Pinned by `test/skills-integrity.test.ts`.
+- `src/core/skillpack/{safe-update,update-journal,file-lock}.ts` + `src/commands/skillpack/update.ts` — the safe-update lane: `gbrain skillpack reference <name>|--all --update-untouched` (routed from `reference.ts`), `skillpack pin|unpin <name>` and `skillpack restore <id>`. `classifySkill` compares each file of a skill's closure (its bundle dir plus missing shared dependencies; paired sources outside the skills root are reported, never written) with the install's recorded base in `state.ts` `roots` first, then with the released-version history: `unchanged`, `absent`, `untouched`, `historical` (needs `--accept-historical`), `local_edits`, `no_history`. A skill updates whole or not at all; skip reasons are `pinned`, `history_unverified`, `unsafe_target`, `local_edits`, `no_history`, `historical_only`. `runSkillpackUpdate` takes the workspace writer lock then the state lock (`file-lock.ts`, O_EXCL with a release token, mtime-stale reclaim), stages and validates the closure inside the skills root, writes the journal before any change (`update-journal.ts`: `~/.gbrain/skillpack-backups/<id>/`, kept 30 days or the last 10), backs up and rehashes each file right before its rename, then runs conformance, trigger and resolver checks (`defaultValidator`); a failure rolls back only files whose hash still equals what the run wrote. `runSkillpackRestore` restores applied files whose hash still equals the post-update hash and is idempotent. `recordScaffoldBases` records bases on scaffold, sync and harness installs; harness destinations are recorded, not updated. Never prompts (`--dry-run` previews); exit 0 nothing failed, 1 with `--fail-on-skipped` when a skill was skipped, 2 on a failure with the files touched and the restore command. Doctor: `src/commands/doctor/checks/skillpack-update.ts` (`skillpack_update_incomplete`, `skillpack_backups`), filesystem only. Error codes `skillpack_*` in `error-registry.ts`. Tests: `test/skillpack-safe-update.test.ts`. Doc: "Updating installed skills" in `docs/guides/skillpacks-as-scaffolding.md`.
+- `src/core/skills-integrity.ts` — Tamper-evidence manifest for the bundled `skills/` tree; NOT a signature system. Pure functions over `node:crypto` sha256: `computeSkillsManifest(dir)` (recursive, sorted '/'-relative paths, excludes the manifest itself, skips symlinks), `renderSkillsManifest(dir)` (2-space JSON + trailing newline, deterministic), `verifySkillsManifest(dir, manifest)` → `{modified, missing, extra}`. Committed manifest lives at `skills/skills.lock.json` (`SKILLS_MANIFEST_FILENAME`); regenerate via `bun run scripts/generate-skills-manifest.ts`, which first appends the lock's hashes to `skills/skills.lock.history.json` (`gbrain-skills-lock-history-v1`, append-only: every released sha256 per file, the record `--update-untouched` reads through `loadVerifiedSkillsLockHistory`; the lock records the history's own hash). `scripts/check-skills-lock-history.ts` (`bun run check:skills-lock-history`, in `bun run verify`) fails when the history misses a current hash or drops an entry HEAD or the merge-base had. Consumers: the warn-only `skills_manifest_integrity` doctor check in `src/commands/doctor/skill-checks.ts` (ok/skip when no manifest is present — user workspaces and compiled-binary installs are not drift) and the CI freshness guard `scripts/check-skills-manifest-fresh.sh` (`bun run check:skills-manifest`, in `bun run verify`). Pinned by `test/skills-integrity.test.ts`.
diff --git a/docs/guides/error-codes.md b/docs/guides/error-codes.md
index 6eafb98264..6b6e3a0e4f 100644
--- a/docs/guides/error-codes.md
+++ b/docs/guides/error-codes.md
@@ -3999,6 +3999,66 @@ More: [docs/guides/repair.md#setup-owner-conflict](../../docs/guides/repair.md#s
More: [docs/guides/shared-brain-skills.md#troubleshoot-leave-and-recover](../../docs/guides/shared-brain-skills.md#troubleshoot-leave-and-recover)
+### skillpack_backup_corrupt
+
+<a id="skillpack_backup_corrupt"></a>
+
+| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
+|---|---|---|---|---|---|---|
+| A skillpack update backup does not hash to the journal's pre-update hash, so restore will not write it. | Restore only writes bytes it can prove are the file's pre-update content. Side effects: files restored before this one stay restored; this file and the rest are untouched. | Leave the file as it is, or compare it with gbrain skillpack reference <skill> and edit it by hand. Run: gbrain skillpack restore --list --json | agent | `gbrain doctor --json` | 2 | no |
+
+More: [docs/guides/skillpacks-as-scaffolding.md#updating-installed-skills](../../docs/guides/skillpacks-as-scaffolding.md#updating-installed-skills)
+
+### skillpack_journal_not_found
+
+<a id="skillpack_journal_not_found"></a>
+
+| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
+|---|---|---|---|---|---|---|
+| No skillpack update backup has that id. | Backups live under ~/.gbrain/skillpack-backups/<id>/ and are kept 30 days or the newest 10. Side effects: none. | List the backups with gbrain skillpack restore --list. Run: gbrain skillpack restore --list --json | agent | `repeat the read that failed` | 2 | no |
+
+More: [docs/guides/skillpacks-as-scaffolding.md#updating-installed-skills](../../docs/guides/skillpacks-as-scaffolding.md#updating-installed-skills)
+
+### skillpack_restore_conflict
+
+<a id="skillpack_restore_conflict"></a>
+
+| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
+|---|---|---|---|---|---|---|
+| A file changed after the skillpack update it would restore, so restore refused. | Restore never overwrites an edit made after the update. Side effects: nothing was restored (a file that changes mid-restore stops the run; files already restored stay restored and a rerun is a no-op for them). | Keep the later edit and restore the rest: gbrain skillpack restore <id> --skip <file>. Run: gbrain skillpack restore --list --json | agent | `repeat the read that failed` | 2 | no |
+
+More: [docs/guides/skillpacks-as-scaffolding.md#updating-installed-skills](../../docs/guides/skillpacks-as-scaffolding.md#updating-installed-skills)
+
+### skillpack_state_locked
+
+<a id="skillpack_state_locked"></a>
+
+| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
+|---|---|---|---|---|---|---|
+| Another gbrain skillpack command holds the lock on ~/.gbrain/skillpack-state.json. | Scaffold, update, pin and restore read-modify-write the state file one at a time. Side effects: nothing was written by this command. A lock left by a crash is reclaimed after 10 minutes. | Wait for the other command to finish and run this one again. Run: gbrain skillpack restore --list --json | agent | `repeat the read that failed` | 2 | yes |
+
+More: [docs/guides/skillpacks-as-scaffolding.md#updating-installed-skills](../../docs/guides/skillpacks-as-scaffolding.md#updating-installed-skills)
+
+### skillpack_update_incomplete
+
+<a id="skillpack_update_incomplete"></a>
+
+| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
+|---|---|---|---|---|---|---|
+| An earlier skillpack update of this skills root did not finish (a crash left its journal pending), so no new update runs. | Some files of the interrupted skill may hold the new version and others the old. Side effects: nothing was changed by this run; --dry-run still previews. | Run gbrain skillpack restore <id> (named in the message), then update again. Run: gbrain doctor --only skillpack_update_incomplete --json | agent | `repeat the read that failed` | 2 | no |
+
+More: [docs/guides/skillpacks-as-scaffolding.md#updating-installed-skills](../../docs/guides/skillpacks-as-scaffolding.md#updating-installed-skills)
+
+### skillpack_workspace_locked
+
+<a id="skillpack_workspace_locked"></a>
+
+| Meaning | Why | Next step | Who acts · consent | Verify | Exit | Retryable |
+|---|---|---|---|---|---|---|
+| Another gbrain skillpack command holds this workspace's writer lock (.gbrain-skillpack.lock). | One writer per skills root keeps an update and a restore from interleaving. Side effects: nothing was written. A lock left by a crash is reclaimed after 10 minutes. | Wait for the other command to finish and run this one again. Run: gbrain skillpack restore --list --json | agent | `repeat the read that failed` | 2 | yes |
+
+More: [docs/guides/skillpacks-as-scaffolding.md#updating-installed-skills](../../docs/guides/skillpacks-as-scaffolding.md#updating-installed-skills)
+
### slug_page_mismatch
<a id="slug_page_mismatch"></a>
diff --git a/docs/guides/skillpacks-as-scaffolding.md b/docs/guides/skillpacks-as-scaffolding.md
index 62294f743e..44163ce579 100644
--- a/docs/guides/skillpacks-as-scaffolding.md
+++ b/docs/guides/skillpacks-as-scaffolding.md
@@ -76,12 +76,77 @@ gbrain skillpack reference book-mirror
`reference <name> --apply-clean-hunks` is the auto-apply path. It
parses the diff between gbrain's bundle and your local copy, applies
-every hunk whose pre-change context matches uniquely. **Two-way merge
-limitation**: without scaffold-time base tracking (intentionally out of
-scope), this cannot distinguish "gbrain changed X"
-from "you changed X." Applied hunks align everything to gbrain. Use
-`--dry-run` first to preview, or run plain `reference` to inspect the
-diff before letting auto-apply touch anything.
+every hunk whose pre-change context matches uniquely. **It is a
+destructive two-way apply**: it compares only your copy and gbrain's
+current bundle, so it cannot tell "gbrain changed X" from "you changed
+X," and applied hunks align everything to gbrain. Preview with
+`--dry-run` first, or run plain `reference` and merge by hand. For
+skills you never edited, `--update-untouched` (below) is the safe path.
+
+### Updating installed skills
+
+`gbrain skillpack reference <name>|--all --update-untouched [--dry-run] [--json] [--no-diff] [--accept-historical] [--fail-on-skipped]`
+replaces whole skills you never edited with gbrain's current version.
+It never prompts; `--dry-run` is the preview.
+
+- **Base.** `scaffold` (including `--harness` installs, `sync` and the
+ openclaw lane) and every update record the sha256 of each skill file
+ gbrain installed in `~/.gbrain/skillpack-state.json`, per skills root and
+ skill. That recorded base always wins.
+- **Per skill, all or nothing.** A skill's closure is its `SKILL.md`,
+ references, scripts and any shared dependency it lacks. It updates only
+ when every closure file is unchanged, absent, or still equal to its base,
+ and the skill is not pinned. A file that differs from its base is
+ `local_edits` even when it equals a past release.
+- **Installs from before bases were recorded.** A file with no base that
+ equals a released version (listed in `skills/skills.lock.history.json`)
+ is shown separately and needs `--accept-historical`.
+- **Skip reasons:** `local_edits`, `pinned` (`gbrain skillpack pin <skill>`,
+ undo with `unpin`), `no_history`, `historical_only`,
+ `history_unverified` (the history file failed its hash in
+ `skills.lock.json`, so no whole-file update runs) and `unsafe_target` (a
+ symlink or a path outside the skills root). A skipped skill prints its
+ diff: your copy against gbrain's, at most 200 lines per file, with
+ secret-looking values redacted.
+- **Commit protocol.** The closure is staged and checked first, a journal
+ of intent and a backup of each replaced file go to
+ `~/.gbrain/skillpack-backups/<id>/`, each file is rehashed right before
+ its rename, and conformance, the trigger check and the resolver check run
+ on the updated skill. A late change, a crash or a failed check rolls back
+ only the files that still hold the update's bytes. A crash shows up as
+ `skillpack_update_incomplete` in `gbrain doctor` and on the next run.
+- **Restore.** `gbrain skillpack restore <id>` puts back what an update
+ replaced and removes what it added. It refuses a file you changed since
+ the update unless you name it with `--skip <file>`, and running it again
+ is a no-op. `restore --list` lists backups; they are kept 30 days or the
+ newest 10.
+- **Exit codes:** 0 when nothing failed (skips are in the summary and
+ JSON), 1 only with `--fail-on-skipped` when something was skipped, 2 when
+ a skill failed (the files touched and the restore command are printed).
+- **Locks.** The command takes the workspace writer lock
+ (`.gbrain-skillpack.lock` beside the skills dir), then the shared lock on
+ the state file, in that order.
+- **No repository needed.** The state file and backups are files under
+ `GBRAIN_HOME`, so this works the same on a repo-less brain.
+- **Upgrades only announce.** `gbrain upgrade` writes no skill files; its
+ behavior notice names the preview command.
+- **Not covered:** paired source files outside the skills root (reported,
+ never written), shared dependencies you already have (only missing ones
+ are added), harness destination installs (`reference --harness <h>`
+ stays the lens there), and skills shared through a brain. Those update by
+ publishing a revision with `put_skill`; skillpack file-copy commands are
+ not a way around publication. See
+ [shared brain skills](shared-brain-skills.md#update-a-shared-skill).
+
+| You want to | Run |
+|---|---|
+| Read what changed upstream | `gbrain skillpack reference <name>` (or `--all`) |
+| Take upstream on skills you never edited | `gbrain skillpack reference --all --update-untouched --dry-run`, then without `--dry-run` |
+| Keep an edited or deliberately old skill as it is | `gbrain skillpack pin <name>` |
+| Update a skill you edited | read `gbrain skillpack reference <name>` and merge by hand; `--apply-clean-hunks` is a destructive two-way apply (preview with `--dry-run`) |
+| Find which skills need work | `gbrain skillpack health` |
+| Improve a skill's quality against a benchmark | `gbrain skillopt <name>` |
+| Undo an update | `gbrain skillpack restore <id>` (`--list` to find it) |
### `gbrain skillpack migrate-fence [--workspace PATH] [--dry-run]`
@@ -257,7 +322,9 @@ gbrain skillpack remove --harness claude-code --skill query
marketplace)** → `scaffold --harness <h>`
- **Shipping a pack from inside a brain/source repo** → `init-brain-pack`
- **gbrain shipped a new version, want to see what's changed**
- → `reference` (read-only) or `reference --apply-clean-hunks` (auto);
+ → `reference` (read-only), `reference --all --update-untouched` for
+ skills you never edited, or a hand merge for edited ones (see
+ [Updating installed skills](#updating-installed-skills));
for harness installs → `reference --harness <h>`
- **Upgrading from the legacy managed-block model** → `migrate-fence` (one-shot)
- **Cleanup after `migrate-fence`** → `scrub-legacy-fence-rows`
diff --git a/package.json b/package.json
index c562adad28..2a4a2a037c 100644
--- a/package.json
+++ b/package.json
@@ -122,6 +122,7 @@
"check:eval-glossary": "bash scripts/check-eval-glossary-fresh.sh",
"check:tool-catalog": "bash scripts/check-tool-catalog-fresh.sh",
"check:skills-manifest": "bash scripts/check-skills-manifest-fresh.sh",
+ "check:skills-lock-history": "bun scripts/check-skills-lock-history.ts",
"check:test-names": "bash scripts/check-test-real-names.sh",
"check:progress": "bash scripts/check-progress-to-stdout.sh",
"check:no-tracked-symlinks": "bash scripts/check-no-tracked-symlinks.sh",
diff --git a/plugin-variants/gbrain-coding/skills/_AGENT_README.md b/plugin-variants/gbrain-coding/skills/_AGENT_README.md
index 0dab2fef65..3337f53666 100644
--- a/plugin-variants/gbrain-coding/skills/_AGENT_README.md
+++ b/plugin-variants/gbrain-coding/skills/_AGENT_README.md
@@ -143,7 +143,10 @@ gbrain skillpack reference --all
```
That sweeps every bundled skill and reports per-skill `identical / differs /
-missing` counts. For each `differs`:
+missing` counts. Skills the user never edited take gbrain's version whole with
+`gbrain skillpack reference --all --update-untouched` (`--dry-run` previews;
+edited or pinned skills are skipped; `gbrain skillpack restore <id>` undoes it).
+For each remaining `differs`:
```bash
gbrain skillpack reference <slug>
diff --git a/plugin-variants/gbrain-daily/skills/_AGENT_README.md b/plugin-variants/gbrain-daily/skills/_AGENT_README.md
index 0dab2fef65..3337f53666 100644
--- a/plugin-variants/gbrain-daily/skills/_AGENT_README.md
+++ b/plugin-variants/gbrain-daily/skills/_AGENT_README.md
@@ -143,7 +143,10 @@ gbrain skillpack reference --all
```
That sweeps every bundled skill and reports per-skill `identical / differs /
-missing` counts. For each `differs`:
+missing` counts. Skills the user never edited take gbrain's version whole with
+`gbrain skillpack reference --all --update-untouched` (`--dry-run` previews;
+edited or pinned skills are skipped; `gbrain skillpack restore <id>` undoes it).
+For each remaining `differs`:
```bash
gbrain skillpack reference <slug>
diff --git a/plugin/skills/_AGENT_README.md b/plugin/skills/_AGENT_README.md
index 0dab2fef65..3337f53666 100644
--- a/plugin/skills/_AGENT_README.md
+++ b/plugin/skills/_AGENT_README.md
@@ -143,7 +143,10 @@ gbrain skillpack reference --all
```
That sweeps every bundled skill and reports per-skill `identical / differs /
-missing` counts. For each `differs`:
+missing` counts. Skills the user never edited take gbrain's version whole with
+`gbrain skillpack reference --all --update-untouched` (`--dry-run` previews;
+edited or pinned skills are skipped; `gbrain skillpack restore <id>` undoes it).
+For each remaining `differs`:
```bash
gbrain skillpack reference <slug>
diff --git a/scripts/check-skills-lock-history.ts b/scripts/check-skills-lock-history.ts
new file mode 100644
index 0000000000..9f813e141d
--- /dev/null
+++ b/scripts/check-skills-lock-history.ts
@@ -0,0 +1,71 @@
+#!/usr/bin/env bun
+/**
+ * CI guard for skills/skills.lock.history.json, the append-only record of
+ * every released sha256 of each bundled skill file that
+ * `gbrain skillpack reference --update-untouched` reads.
+ *
+ * Fails when:
+ * 1. the history does not parse, or misses a hash the current lock lists
+ * (run `bun run scripts/generate-skills-manifest.ts`);
+ * 2. the history dropped a (path, hash) the previous committed copy had.
+ * "Previous" is HEAD's copy and the merge-base with the default branch
+ * (`GBRAIN_SKILLS_HISTORY_BASE` overrides the base ref); a ref that has no
+ * copy, or no git at all, skips that comparison.
+ *
+ * The lock's own hash of the history is checked by check-skills-manifest-fresh.sh.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import {
+ SKILLS_LOCK_HISTORY_FILENAME,
+ computeSkillsManifest,
+ droppedHistoryEntries,
+ mergeSkillsLockHistory,
+ parseSkillsLockHistory,
+ type SkillsLockHistory,
+} from '../src/core/skills-integrity.ts';
+
+const root = process.env.GBRAIN_GUARD_ROOT ?? join(dirname(fileURLToPath(import.meta.url)), '..');
+const rel = `skills/${SKILLS_LOCK_HISTORY_FILENAME}`;
+const path = join(root, rel);
+const fail = (lines: string[]): never => {
+ for (const line of lines) console.error(line);
+ process.exit(1);
+};
+
+if (!existsSync(path)) fail([`ERROR: ${rel} not found.`, 'Run: bun run scripts/generate-skills-manifest.ts']);
+let current: SkillsLockHistory;
+try {
+ current = parseSkillsLockHistory(readFileSync(path, 'utf-8'));
+} catch (err) {
+ fail([`ERROR: ${(err as Error).message}`]);
+}
+const missing = droppedHistoryEntries(mergeSkillsLockHistory(null, computeSkillsManifest(join(root, 'skills'))), current!);
+if (missing.length) {
+ fail([`ERROR: ${rel} is missing ${missing.length} hash(es) the current skills.lock.json lists:`, ...missing.slice(0, 20).map(m => ` ${m}`),
+ 'Run: bun run scripts/generate-skills-manifest.ts']);
+}
+
+const git = (args: string[]) => spawnSync('git', ['-C', root, ...args], { encoding: 'utf-8' });
+const refs = new Set<string>(['HEAD']);
+const base = process.env.GBRAIN_SKILLS_HISTORY_BASE
+ ?? ['origin/master', 'origin/main'].map(ref => git(['merge-base', 'HEAD', ref])).find(r => r.status === 0)?.stdout.trim();
+if (base) refs.add(base);
+for (const ref of refs) {
+ const shown = git(['show', `${ref}:${rel}`]);
+ if (shown.status !== 0) continue;
+ let previous: SkillsLockHistory;
+ try {
+ previous = parseSkillsLockHistory(shown.stdout);
+ } catch {
+ continue;
+ }
+ const dropped = droppedHistoryEntries(previous, current!);
+ if (dropped.length) {
+ fail([`ERROR: ${rel} dropped ${dropped.length} entr${dropped.length === 1 ? 'y' : 'ies'} that ${ref} has (the file is append-only):`,
+ ...dropped.slice(0, 20).map(d => ` ${d}`), `Re-add them from git show ${ref}:${rel}, then run bun run scripts/generate-skills-manifest.ts.`]);
+ }
+}
+console.log(`✓ ${rel} covers the lock and keeps every committed entry`);
diff --git a/scripts/generate-skills-manifest.ts b/scripts/generate-skills-manifest.ts
index 2510292f4a..68b20b7f8c 100644
--- a/scripts/generate-skills-manifest.ts
+++ b/scripts/generate-skills-manifest.ts
@@ -6,19 +6,33 @@
* warns (never fails) on drift; scripts/check-skills-manifest-fresh.sh keeps
* the committed manifest in sync in CI.
*
+ * It first appends the current hashes to skills/skills.lock.history.json (the
+ * append-only record of every released version of each bundled file, read by
+ * `gbrain skillpack reference --update-untouched`), then writes the lock, so
+ * the lock records the history's own hash. scripts/check-skills-lock-history.ts
+ * fails CI when the history drops an entry.
+ *
* Run after any change under skills/:
* bun run scripts/generate-skills-manifest.ts
*/
-import { writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import {
+ SKILLS_LOCK_HISTORY_FILENAME,
SKILLS_MANIFEST_FILENAME,
+ computeSkillsManifest,
+ mergeSkillsLockHistory,
+ parseSkillsLockHistory,
+ renderSkillsLockHistory,
renderSkillsManifest,
} from '../src/core/skills-integrity.ts';
const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
const skillsDir = join(repoRoot, 'skills');
+const historyPath = join(skillsDir, SKILLS_LOCK_HISTORY_FILENAME);
+const previous = existsSync(historyPath) ? parseSkillsLockHistory(readFileSync(historyPath, 'utf-8')) : null;
+writeFileSync(historyPath, renderSkillsLockHistory(mergeSkillsLockHistory(previous, computeSkillsManifest(skillsDir))));
const outPath = join(skillsDir, SKILLS_MANIFEST_FILENAME);
writeFileSync(outPath, renderSkillsManifest(skillsDir));
-console.log(`Wrote ${outPath}`);
+console.log(`Wrote ${historyPath}\nWrote ${outPath}`);
diff --git a/scripts/guards-manifest.tsv b/scripts/guards-manifest.tsv
index f58c1079aa..dea7e84a76 100644
--- a/scripts/guards-manifest.tsv
+++ b/scripts/guards-manifest.tsv
@@ -58,6 +58,7 @@ check-fuzz-purity.sh buildfresh exempt executes fuzz corpus
check-image-decoders-embedded.sh buildfresh exempt binary embed check; in verify CHECKS (check:image-decoders); its smoketest compile bundles a handful of modules (~0.6s)
check-pglite-embedded.sh buildfresh exempt binary embed check
check-skills-manifest-fresh.sh buildfresh exempt regenerates + diffs
+check-skills-lock-history.ts repostate exempt GBRA-225: skills/skills.lock.history.json lists every hash the lock lists and keeps every entry of HEAD and the merge-base copy (append-only); compares committed file state, no scanned fixtures
check-tool-catalog-fresh.sh buildfresh exempt regenerates + diffs
check-wasm-embedded.sh buildfresh exempt binary embed check
check-bootstrap-tag.sh repostate exempt VERSION stamp drift check
diff --git a/scripts/module-size-limits.tsv b/scripts/module-size-limits.tsv
index bfa01bceb3..f851e4affe 100644
--- a/scripts/module-size-limits.tsv
+++ b/scripts/module-size-limits.tsv
@@ -47,4 +47,4 @@ src/commands/doctor/checks/extraction-sync.ts 1500 ratchet +7 GBRA-130 A-1: link
src/core/search/evidence-delivery.ts 1733 ratchet +5 W5: EvidencePlan.rankCut resolved with the plan (logic in search/page-rank-cut.ts); +20 W5 whole_pages: wholeCost prices a block as delivery would emit it whole (needs the private Block/enrichBlock internals) and the cut is wired before allocate (cutWholePages lives in search/page-rank-cut.ts); new row: crossed the 1500 unlisted cap at the #6367 merge (master 1479, its explicit-budget cap) by the C1 date header threaded through every block path, cap included; pagePlanHits (search/page-plan-hits.ts) and the header loader (evidence-date.ts blockDateHeaders) were peeled first; peel candidate: allocateCapped; +8 at the #6396 merge: page evidence text cut through the fence-chunk trust overlay and the caller minTrust floor (re-summed: our 1504 + master +8); +119 Cat 40 next wave F2: the search.long_page_unit policy (withLongPagePolicy, selectLongPages size preflight with page/byte/deadline limits) and the long-page fetch and fallback in deliverEvidence, kept in the shared seam the plan names (gbrain-evals docs/plans/2026-10-11-cat40-next-wave, F2); +17 F2 rework to the frozen-comparison policy: search.long_page_min_chars (rendered-body characters, default 20,000) read in withLongPagePolicy, a character count in the preflight, the rendered-body confirmation in deliverEvidence, and the long-page row exemption in capDeliveredSnippets (re-summed at the 0.60.225.0 merge: master 1537 + F2 136); +39 Wave B PR 2 lane 2b: planSegmentedBlock joins the windows search/segmented-evidence.ts reads around a segmented page's hits into one run-marked document (needs the private Doc/Piece/buildDoc/locateAnchor internals), planBlock's unit cut split into blockFromDoc for both, sections bounded by their run, selectionCost counts a gap between runs, and the fetch skips the whole-body fence overlay for a segmented page; +4 segmented pages read at once before planning (segmentedReads; the read is search/segmented-evidence.ts, the statements page-body/read-range.ts); +17 GBRA-156: tail trim plan flag, DeliverOptions.query, DeliveryMeta.tail_trim, the trim call and the frozen-hit score/query library fields (logic in search/evidence-tail-trim.ts; interface fields cannot move)
src/commands/config.ts 1524 ratchet new row: crossed the 1500 unlisted cap in wave 15 P7.4 #5461: set-time validation of think.pages_budget_chars / think.excerpt_ceiling_chars (range + parser live in core/think/pages-budget.ts), mirroring the cycle.consolidate.cluster_threshold hook; +1 wave 16 G5.1 (#6495): set-time refusal hook for search.keyword_statement_timeout_ms (check lives in commands/config/keyword-timeout-value.ts); +1 wave 18b lane 5 (#5012 item 6): search.contextual_retrieval prints the existing-pages hint after the write (text lives in commands/config/contextual-mode-hint.ts); +1 #6712 PR 2: retired/rollback sync key dispatch line (logic in core/sync-config-keys.ts handleSyncKeyConfig); +1 #6865: sync.slug_conflicts.auto_remove boolean validation at set time (refusal text in repair/slug-autoheal.ts); +1 #6948: sync.origin_twins.auto_resolve boolean validation at set time (refusal text in repair/origin-twins-heal.ts); +2 #6795: config set chat_model/expansion_model help line and the model-pin import (shadow report and file-pin unset live in commands/config/model-pin-shadow.ts); +1 #6712 PR 4b: sync.admission set-time hook (value logic in commands/config/sync-admission-value.ts); +4 #7130: set-time refusal hook for sync.max_deletes / sync.max_delete_ratio (and .source.<id>) / purge.retention_hours (check lives in core/sync-reconcile.ts deleteSafetyConfigRefusal); +1 GBRA-150: sync.metafile_pages set-time route (body in config/sync-metafile-pages-value.ts); re-summed at the v0.60.330.0 merge (1520 measured); +2 #7242 minions.terminal_hook file-plane key and its set branch (logic in minions/terminal-hook.ts); +1 GBRA-161: generations.* set-time route (refusal in commands/config/generations-values.ts); +1 GBRA-207 #7630: sync.repo_path set-time refusal hook (refusal in core/sync-config-keys.ts syncRepoPathRefusal)
src/commands/mcp-expose.ts 1512 ratchet hosted_option: Session carries the gbrain.io coaching notice on the first-receipt run and Tailscale/service friction exits (copy, refs and gating live in core/onboard/hosted-option.ts)
-src/core/behavior-change-notice.ts 1518 ratchet the BEHAVIOR_CHANGES table grows by one row per disclosed change: +2 strict door planned-state row (#7705, re-summed at the 0.60.470.0 merge: master 1514 + 2), +2 Bun floor 1.4.4 row (#7644), the GBRA-95 RLS backfill row (+2), +3 rows for #7596 pass_interrupted, #7599 read-only serve and the --access=read-only ceiling, +1 G5 lane C trust_release row, +1 #7619 cli_flag_equals, +3 GBRA-207 #7630 relative-anchor and stalled-write rows, +2 the #7632 function search_path disclosure row and +2 the #7679 orphaned worktree refresh row (re-summed at the 0.60.471.0 merge: master 1516 + 2); the behavior-change table split (#7607) retires this row
+src/core/behavior-change-notice.ts 1520 ratchet the BEHAVIOR_CHANGES table grows by one row per disclosed change: +2 GBRA-225 skillpack_update_untouched row, +2 strict door planned-state row (#7705, re-summed at the 0.60.470.0 merge: master 1514 + 2), +2 Bun floor 1.4.4 row (#7644), the GBRA-95 RLS backfill row (+2), +3 rows for #7596 pass_interrupted, #7599 read-only serve and the --access=read-only ceiling, +1 G5 lane C trust_release row, +1 #7619 cli_flag_equals, +3 GBRA-207 #7630 relative-anchor and stalled-write rows, +2 the #7632 function search_path disclosure row and +2 the #7679 orphaned worktree refresh row (re-summed at the 0.60.471.0 merge: master 1516 + 2); the behavior-change table split (#7607) retires this row
diff --git a/scripts/run-verify-parallel.sh b/scripts/run-verify-parallel.sh
index c67b23519d..0e78559a65 100755
--- a/scripts/run-verify-parallel.sh
+++ b/scripts/run-verify-parallel.sh
@@ -136,6 +136,8 @@ CHECKS=(
"check:eval-glossary"
"check:tool-catalog"
"check:skills-manifest"
+ # GBRA-225: skills.lock.history.json covers the lock and only grows.
+ "check:skills-lock-history"
"check:no-pii-agent-voice"
"check:synthetic-corpus-privacy"
"check:operations-filter-bypass"
diff --git a/skills/_AGENT_README.md b/skills/_AGENT_README.md
index 0dab2fef65..3337f53666 100644
--- a/skills/_AGENT_README.md
+++ b/skills/_AGENT_README.md
@@ -143,7 +143,10 @@ gbrain skillpack reference --all
```
That sweeps every bundled skill and reports per-skill `identical / differs /
-missing` counts. For each `differs`:
+missing` counts. Skills the user never edited take gbrain's version whole with
+`gbrain skillpack reference --all --update-untouched` (`--dry-run` previews;
+edited or pinned skills are skipped; `gbrain skillpack restore <id>` undoes it).
+For each remaining `differs`:
```bash
gbrain skillpack reference <slug>
diff --git a/skills/skills.lock.history.json b/skills/skills.lock.history.json
new file mode 100644
index 0000000000..856bbd48d9
--- /dev/null
+++ b/skills/skills.lock.history.json
@@ -0,0 +1,1143 @@
+{
+ "schema_version": "gbrain-skills-lock-history-v1",
+ "files": {
+ "RESOLVER.md": [
+ "032fcc8131d8a7458dcc47c4a3f521eaa753ef6cf8734e5b66d699f3599903b7",
+ "36b43c65a41e6fce894b9559db2bce0a53f06a99450410e498323c12e12e92bb",
+ "3d32ec5cd8c15d83b18469277a5efc269bb6b60e67f4542de5a28a76760c36cd",
+ "3dcbc1eb9f25a7a5ba7c8fe24b58b4e2274373a06e6e4b100ec7a15ca603e5b5",
+ "5939d2a22bd2a6658bff105e8902170b46907fd6e930e24e2a8ecc24776930cf",
+ "5c41607c9829f23885a303133fc86634c37c7f6108223e186597685e1c843a7b",
+ "7387d5d7da701ffae26f13752b3551fbd6c3cf048085ba7064da6159a617a601",
+ "77aeac731ac52a4949a9a94618cd3c09be72c94259ff7568c57eb1124c225db8",
+ "791d5c90a7f9ae1aaacfe45a975c6855027c82600c95f6b2526b7cd0f0802bb5",
+ "8564931d50c6f2bd2d92d41821f5e156e26de899018d0d40fce9c78760092025",
+ "8b048e1e8834095bb1b5ace4cefff95e94e3994994f1120102b83121282e3290",
+ "8e54195c109c764d2954186ee92a30a62cd91e961233be53f828db5a25ebe710",
+ "9c55394405c5cf5f477e3f8a0357e6afed8d58562e70ffe35a4f0bddce2ef24f",
+ "ad9f85d0f953ad0ec80c70091cb31c7227a89e4a08c924454be1d61d4df5b65c",
+ "b02ad7ab53d3435d3027307951e684d4aa81e5dae3d732ebd1f6039fbf517103",
+ "b9195259a8bd0a54d9c5ad2284446bd97a6ae4a23e280a94d6dcad666243dbb8",
+ "d4a01e2475db5b7efe87d5a789947085c446d249fe90cdb87ff929117986f537",
+ "d788b96fae6731a9bad8586074e40d6b22d360f5b5a7f7a85cea0ef3bb46cf2d",
+ "e110522e362dfad7e5d025c148c99850ecffbb684a830da9df9c7b5a3f86b9c6",
+ "e16588f3197cc9b8b62c95494dd4a85b8bfb143add215cde696a9079664d1ba0",
+ "e4e3823847a9f1d856b10dd411c7916c7b88b87820a6d99fef7220318d1182bf",
+ "eec4c7e973c5a6a4b1e4e96e631f338def986ec99290c62f65ffe158447772a1"
+ ],
+ "_AGENT_README.md": [
+ "0b755aa945df0da0f27cb3323904f54b99b3dfaf8065033e6cf9108ac4be38bb",
+ "19bfd2e33f627dfaeb6545eaf8b26a0d4f9844e3c7b95905f0d005f9fe91d8b6",
+ "26ad1732f466a89f41d6fdb7702ace4c4966866ad854e290929f391bbc4809d3",
+ "3dd82df125ceb87bdbc1ad16be4306fb3ca6e3a491c70122f6c7724a862f0b21",
+ "62613f7f1e061576b6c1b18844f59bd35f2df96ca5c45c8c41fae0772b9ce4d3",
+ "ab51e36e9a0b53f4d0609294b0556444399147834932d9c1acfdc7aa367c70b8",
+ "cd61adb06fcd93928e4b565e14430b88cfe6879c57536ff6d15c3cad2f27a92f",
+ "ce694f4d952cd4ac1377b4f68a63b93f616d2fce745d76a399f1633805c83244",
+ "d9b3bca4e427b707bd3b6058b74e09feeb869b732ac363b5580fc3012a87ec67"
+ ],
+ "_brain-filing-rules.json": [
+ "4e6ecee2d94867d146583d60bf98dccdd9205bb70793af56fe1397a2b258ae0d",
+ "cf850df6a7425464c6d63b3ace71991cc93497fa0cc8cd21acd31883e17939c6"
+ ],
+ "_brain-filing-rules.md": [
+ "23f5d08d705eb975b69611dbfbe878b7e4f3d0eec2470a52160372df8b462ad1",
+ "2d2d75b7c76081c56f41b2c0a5a978c355ce957300f9b0a5575dc4079ef1f877",
+ "5a5792a290e7f48e0123744e3460ea02514d7a514113827a9dde462935565d17",
+ "b8f6844fd7ab6fbe4a4e7a95e7089466b37d63127730040c766927f55b1ad138",
+ "ff42b331bce542d708f97ff0a73ff0fb5664b46ee9b1862a5478b15dc637487e"
+ ],
+ "_friction-protocol.md": [
+ "1b6e7cfa58725a6a5dc2dc787242141bc33f5fde524540d85b14ec22266140f7",
+ "51353207240142024ff1facc25f225712275ecdb4a034ffffdd83740c8d328e3"
+ ],
+ "_output-rules.md": [
+ "0722ec2ecea7f9fa2f065cf12dfe1347956a9709d29898bf9fe95e875c64b800",
+ "239022bd9003b4d45870fea2ddb177a132f0684d898ed5075dc5dcb90cc56ab7"
+ ],
+ "academic-verify/SKILL.md": [
+ "1c19e27e75249d869da428ce8d060075feef8fbbfe146af58b305d11a260ebbc",
+ "485839f3f35ddebeb99dacc901deed4b5c7c6c7f7c8367a444b8a427530e75a5",
+ "d8a395ed8df706c6da888f81f518c2fd6607f78c2bc66134b9bc40530fdb08b5"
+ ],
+ "academic-verify/routing-eval.jsonl": [
+ "90d894a9829d9936e6ac7a6507e4de67ad26e46a1fe13b7a34e7dec1c0d887dd"
+ ],
+ "archive-crawler/SKILL.md": [
+ "10c529797e1cba75da5bdb13bdd3609ae5f962f7dcc429c3b85d51c0032d9a26",
+ "67790bc80c2c0473d8f7ed318e79a3cb4d22c71817ca871aff45032341ed614b",
+ "d93174bfc276ce78c1d6283c213b7c7006978075603d7d333c7e345fd63da979"
+ ],
+ "archive-crawler/routing-eval.jsonl": [
+ "a90c607d69737adf58771d1b986c5a7d9d11f5303df7de4c7def74aa2c86a2f5"
+ ],
+ "article-enrichment/SKILL.md": [
+ "3aceaf44fd4c1ed21b6256c1d09912f1d6b973c7b99f890c52de2f5d2fd46ec1",
+ "84b2a3792c5e7e2ccf8b6fd32b2c850a8514f5ed5459a5664ba0780720f5ce09",
+ "fcdbce0f250aa2c38b86299dae510b8dc7f1e1cd854961cb8520c61642309549"
+ ],
+ "article-enrichment/routing-eval.jsonl": [
+ "408fa8cc80caf1a2208afeb049e5ada69beb378f22d6b7114828201a4657e6e3"
+ ],
+ "ask-user/SKILL.md": [
+ "3eb82b0aeb87f195798940e91ac49560c3f31eb6f95e8ba21767663e4f5f8e1e",
+ "a40f484721e548a3a14d4b33a4636111d92f99619ecc4e4ea54c3da3a15f8331",
+ "bbf43870cb9f1e491e8ba72e7e0d3ecee8c33c0139d66f7cc28bb5b83a8e73ff",
+ "ffa15b80a286180d79642bf1d96be860ad2801ad8ba5c2923750a7adafd260ae"
+ ],
+ "blog-ingest/SKILL.md": [
+ "8fad548e780b56a8e79dd08f0bc7a79eb84aa03447798983acef949e4abefd3f",
+ "cf33e480a78b85c1d466bdc568d0a494e3e051ed9fbe45bac3b5b23b167664f6",
+ "fce5c07ea7b0864d701b946f5737d321b5e3133244b2a79dbc73512dabc232bb"
+ ],
+ "blog-ingest/routing-eval.jsonl": [
+ "aa3172ee83f29bee62ef19027975359dcb356c4e57a551eff1f7a187e6562b49"
+ ],
+ "book-mirror/SKILL.md": [
+ "214ba954958e1eaf07caebbdcd9ca4de21091e79f2384183d89342e6d75ff6b6",
+ "2f69ef47fff79a9a06d9a723c725173c6ffb308c9378f8fc52ba451c2309f709",
+ "a173777133e85483f6e41eb7c5b64bac0ba5a872aba5664dbdd535b658b2c5bf",
+ "e8b8cc7a6eba4ecd302a840446b48c0e1aecc245e8f240e233c738daa8dff78a"
+ ],
+ "book-mirror/routing-eval.jsonl": [
+ "79fd23642cfa37b1255a799907e71bb2904585cf79dd6a596e3a2f019787e54c"
+ ],
+ "brain-ingest-gate/SKILL.md": [
+ "0c382dc55df9b7b991fd6b8ad367fc9b7ac17ebe5e8610c0740ff32234fdc82b",
+ "61a47001723d9b44998114ca5c3edee306606077d097061663bae22e86926cb7",
+ "d1afe95ca4c7c3ec1522252bb2c1aaf20907c956d979491fa427c3da26464d34"
+ ],
+ "brain-ingest-gate/routing-eval.jsonl": [
+ "281e94affbb8631ef7ff44203884cce1c03c468b27f893829da1e6e439401a33"
+ ],
+ "brain-link-discipline/SKILL.md": [
+ "4606cffb3d219aa9b89e71d1770ad9a916f07a28dece9a8a4ce700392f1262ca",
+ "489268f71a01abb6213df8a8bb5f4d16d587b09dd670ac3c47876a8ed808b5ae",
+ "b08219281f283ea17ca7b14fe61d19fa227a5c6b8a2212a155f9e6c41b6898ee",
+ "db2a77319475dd8eb370e9a3bb0eafe81d3b19d2de126113b30df7454dd9a069"
+ ],
+ "brain-link-discipline/routing-eval.jsonl": [
+ "0adea4c6d72fdb849c12fe2cad718568b9ab704299b00b093c40c2284faf684c"
+ ],
+ "brain-ops/SKILL.md": [
+ "075666e81df0b5f8ab23493d4972ef5ba42bc789ae213d3bc03e5d3b9c38a3bf",
+ "10dc45cea79792457ea457c05e2cfe50654b7de497ff60fd6399a74765e56d45",
+ "2f79c8699ca1316d113fe7c20f21791310f1884e1e276051e26c753510877b05",
+ "373a08c1d1228c134403876f1716ca9ac3c78e29cb39cee50f9f540dce6f8581",
+ "40553ad3bf0f27fc8363b69bec3ef89ae0ea0d9290de8d1efbaa0c532c2a9590",
+ "4953e2d9d516957b7d9bd349a3e0bae89b1424eb070f68d943a1a078b254ac21",
+ "4e29e5b6ea5b43998fec84a01ec1f1e737b41443d733b1054737b42de207cf37",
+ "566dcf7f12f18fab09967c5ab4f77ce949f1a2151dc707f678c0a9e3b835b3df",
+ "56bdac549eb45849668a7d1b911f758c793ea17ff224779dd32afc035f7ef87b",
+ "5f221e3de45845b050b90fac935ac70c55ed5148649fb47c4a30989c1d42c40a",
+ "6586d82a135f312dc330a3e7dc71f753285b639eb997740344e9521336cab109",
+ "8e9a6997e94c4474ffff3c4fff95ec90925cb5be1fe65dcbbd1618bcd991b734",
+ "a76ee75dba71c4aa534f252e35e355ae0a7530f961d43ffe7243a285f142adfc",
+ "c5112434c5d430bc3400f60d39417aebb4380cfe53cab987b7b8cecf6688549c",
+ "dbbf2e5b36c5329e8f5e58a5aa9772bf2808cba888181d68fbb60e33f94fe0cb",
+ "e4bc71357893b9268048ce53d72e04db123b877f85fe0242bddaaa5bb6d344f2"
+ ],
+ "brain-pdf/SKILL.md": [
+ "13c3e3162763a4503685db0a10663475d3687c4874b5f04d539af83a990f643e",
+ "14dd2bc5adc9926bb4ec4269bcd47763091d965f83a667e92739b989256f5e5e",
+ "2dfffd2373f00b5f11c1e4b39a75be48e90870201b4c11979d520bd5975dcae4",
+ "68eb85679718afe504179be780ced483b1fe5916b7b294bd202dceca2d9c9398",
+ "c24727ade7c222606249bbf690ddede1bebe218122c9cf9060a2baa6b63d3bc8"
+ ],
+ "brain-pdf/routing-eval.jsonl": [
+ "119e4fa113ea45783cee4499e63a729fdeecb4d9a45d47497754b4f5b21d0734"
+ ],
+ "brain-taxonomist/SKILL.md": [
+ "418fd4cdac3355551c42a70fea4d76e3d9255fe04698358b2c1e89dc666bf11d",
+ "50815ba642c942d28c73b5231f3b163315779de6e3be1acd36a4105ae51a6bd3",
+ "bedf3b71487ee998603cabb61bca102691c73b192537f4521cf7b5b795cd1695",
+ "dea4557b540868ec2c56bf43ee7f63c5d03a22d4047cd0dfbeaf19adef334f60"
+ ],
+ "brain-taxonomist/routing-eval.jsonl": [
+ "8b485b3d735aace60be703854f0f2e9d97c52d52564efdaf7334a0c39e8d20ae"
+ ],
+ "briefing/SKILL.md": [
+ "01d897b6e5b9f6f4facfbecab7038d33e6b85e35a076c5a42f72139c7f5dd1f9",
+ "551c2f308c27b8a0823e2dfbbcdf7e8ace78ff6498afaa3ac21da852c7cf0d16",
+ "7ff51d8cc9ebbeb5145c414d2767726d25ec8718a90e26bf0c14ac3e452eeaeb",
+ "9c99cee1e3e6177bfcbaabdc84aab0d9d786db4075b4875ec2e70b80570608bb",
+ "a661804c3eb2ce5bd4eb6f3e7106283046913945d9dba0b967bdc8483a58dd66",
+ "bbab7deb7bd59056bd98b3c2fac543efd6cdfe3d68cafdc02e24e5f8d3e245b5",
+ "f86ad2238104de20433436dcc8f2cc5534e7df8dad4e4845252f85b8290cde53"
+ ],
+ "briefing/routing-eval.jsonl": [
+ "c056fea88f673e324d6a72cb70438cd6fcdbd09ec2cd036d44eb31a9ea6bf33d"
+ ],
+ "bulk-ingestion/MANIFEST-PATTERN.md": [
+ "0df53fdf8b59bf14601761f6c1cce413bb494f0d5ebc3e6fa96feccfda7e5737",
+ "6180f09d2dc8d9af5749149f2b3c34c40213f5d6b262b69484e864adbb652b47",
+ "deb3abad5d8026822a663810abb1f39d60df8bb797a42587ffa6d44eefa15a0b"
+ ],
+ "bulk-ingestion/SKILL.md": [
+ "18000b3c78fd95fffbe075722cf968b860dde2b0d1b601ef7e7085cde8a24225",
+ "48c10ec94fc23cd6f1ecfa4ec7254cc1cb3f5ea8cc43daf2fbe109c59ce1cda4",
+ "8149c1ff02b320b80c3850d5f837cbebbdc8e088b24da7da9a78046f919ba9aa",
+ "bf23978d710d53884252b15f647212c7f59e7ca081b05aa2fb5a93941893f546",
+ "cfc2cc3c4683c935bea4be9757306dd0edb6b93695c44fb64ae81f2013f80e08"
+ ],
+ "bulk-ingestion/routing-eval.jsonl": [
+ "2bf8ffaf90b8ef761fa3cef54bf3af2eb8cc3ef736d054b5bf8b9361f6448d5a"
+ ],
+ "capture/SKILL.md": [
+ "11434d995ae4d2d40211f3593f75fa48b3b0e6b6c5445547476462510f63da7f",
+ "98568ac96331f57397ea072749641d9748b1ce31e8b09d512b8db25c8fcda65f",
+ "c5fbc5c70874174860e6f8fe09bcfe0f070dfa3d3ed37cf9d3c1725f73ba2ec8",
+ "d250388b92eebb5e6a4672f34e8e537fe592129244585a8a921e0c5b29ddc960"
+ ],
+ "chat-connectors/SKILL.md": [
+ "44b63309c779b5394c0be8ec6cabff8381099cfb8c0944143a859c48594ddf01",
+ "6a1bd2afef4670ddc656bb69bb38a8b294194535b34c07f1b3ede670ce78119f",
+ "f0218cab53f7e82d1543ba8c6f574b39821ecae780219aa5d408586a00de8062"
+ ],
+ "chat-connectors/routing-eval.jsonl": [
+ "688b6bab2020a9628535fb739019f1ac54098e17327e6b1c8828c0d0c4a58be6"
+ ],
+ "citation-fixer/SKILL.md": [
+ "22dde60db9d5df0a859e131e7e2d7347d5205a3d20ea1ed0d9c4eb373fb11cc9",
+ "843dce1f65cb65474c3188def18cf8b543b94648914841cabaa1110a39765a82",
+ "abdadbf0740a529b9c4f86f05bba416417624503fdcbc6054402d5546afd08b4"
+ ],
+ "citation-fixer/routing-eval.jsonl": [
+ "52b23b71e66fdc18aee67d0576099b0c83997d648cf4ecf8fe7753b91b6c9c53"
+ ],
+ "citation-graph-ingest/SKILL.md": [
+ "3c8c4abea96769458e9781ce2f5f305c75118fcb5f68cc62b5e1ed7774259035",
+ "6510856cc14a653dcade510702890343bc0527de14bc2f1ed0d2524f248c798c",
+ "849b0cdc64b7ff14d0e6771bde15f0edc3c2fc29af08be015753a5f88a03205f",
+ "f2ddb27ed6a1867a101607e3f37a1deaf3608e2940ae62e4db9d42cf926347df"
+ ],
+ "citation-graph-ingest/routing-eval.jsonl": [
+ "a1ba605d35e736b741b9e8aac1e7d50b61a7cbcada893d67099b55bf5a0d2635"
+ ],
+ "cold-start/SKILL.md": [
+ "02d9931f5c3bc4ab1be023dd3a2743be947dbe76bd843236b2593354fbb834f1",
+ "20be3d1b637621fd9fbd268072f6647533a23f596e30cb593523b051708aaddd",
+ "36ffea23af6fde97ff6b70d6a12e547bf2097a66d4f8b8146ffea9ead6144cf3",
+ "57d09cff758c48965cb25b2ec2cf317dcf014c22d9610bee83cfe581cf1a9f76",
+ "a2c42dd7c4eceb7d3ce6449a414b417d55195aa445e723e6c798d90906cbf4e6",
+ "c6df9884aaa71a418ef92fba3ff405b2cc577c846eb9fddf423c7c593553aacc",
+ "d5ba53bb2fe96eeca661885548bcacc697d41c7071af296570d6cdba2417b48e",
+ "eb10547b5f2fba3edffd47c5023cd3f28335e1ee3b599f98f298c1ccd07090eb"
+ ],
+ "company-brainify/SKILL.md": [
+ "2c058b39f5364b8ceb5c53b4525cce8645734f16cc3c229a490b005d58a78311",
+ "59a19560fe935ce4666ac5b8321e5891bb4e19e078ff751f48bbc5561613b0e9",
+ "6f39e2ae59e6722f4afac9134ce7041e584637cf08f387861bf6013306c3bd51",
+ "89e8cae702d468628d110119e325cece897cd15066c7cc7d27e990021904fc04",
+ "ae48372512645f532820e43faaf18a8fa768a691b2144973dfc89465f84d84c6",
+ "bed846efe1a89271faac6aa1f7fef57b08dbdbe35a418a21102e738b8add2458",
+ "f82a78337021f3cc87ad3e3674b3fbc94698193aff772e458375a3eb144ddf11"
+ ],
+ "company-brainify/routing-eval.jsonl": [
+ "6f27f835eda9ae77a2b694534c78a043a871349820e8c638c3d8bbba6d3aa17b"
+ ],
+ "concept-synthesis/SKILL.md": [
+ "2bc060ae6d706c4e8e7d784cbe3e577b85e211a21c68cba094a1754d3f34436b",
+ "a5c67f981c5d0a0ef4f13134ed8602e08b0bfbe289456213b8cd465a7a009220",
+ "df7f46dce41a034f8a7d89449dd14585f1c3ee118c1609b0c95a82b033379610",
+ "ed02d2e385143b16a1e69ee5934288fb4d0b755f68c4312faff663e6b2d7c4ed"
+ ],
+ "concept-synthesis/routing-eval.jsonl": [
+ "51d1da894158503ce18b892a34edd203f40732e79ac1c0e85141fd37e0b9922f",
+ "96dbd7d9c1b606e9e06262d0c06282399741e2bccb8eeb7b9ca88c20f44cda0e"
+ ],
+ "context-audit/SKILL.md": [
+ "450c7529b6d1eee7fbd7c87b8d24e88b58c32a097e79ef7e598d4c94a98a5b5c",
+ "6c811783349f740f039078bef991077bdc85007b2f730897465266e4c31b66da",
+ "6d786629d40544ddaab4f4e6e333569d270bcb8b581589dc16fb9f8bcb4f6207",
+ "9db7a31e99859d2532597f93d5b07daf3e316b58c59d191d05198d7994ff468c"
+ ],
+ "context-audit/routing-eval.jsonl": [
+ "fb1832e24cc1b04163a74c5cde72bca53050a66246ca902e1a5f40303f52b5ab"
+ ],
+ "conventions/agent-operator-protocol.md": [
+ "28b1a2e422e1886a32199c67047bfed544216852268731b0f79d3c77f2a7b0f6",
+ "2ef1e6ec2cdacfd6d666bf93b5f06c6d0d8bb7112a5cde49cc83ff43ff6b7a9a",
+ "4331a4ec8d3d58c54a1dd0c50f1b15e4e1d1fdf3273849ac1694df61d6bc0f2b",
+ "57b71aac90727684d3f66ed9d252c2fe357f6bb469549e3eb4480b0bf31cdd45",
+ "a6ce48d76cd13080a5f0414d3cf03506e7e3d64fbc25fa3e97cb2492b6dfb7aa",
+ "abc15628a2f357af5e689a418ed1f15fa009939425b971da0a2fbce31f6aeb73",
+ "b42b19223aa9dffbe783ce7c5c681d762377c740f3c609cbc555b9a60a035235",
+ "c9865fa1b903edfdf445c0723c2f9c62d91aa9d0f9b21264788f02ae6b42967c",
+ "d22b616c90d84d7035cf2c56ed2c59d361b06a0499f548ae21e81bd23823efce",
+ "d7cfc7e4c84f61392658cbe969058b1e8237b7d44c3ebdeec352569ffddbe001",
+ "e54e9d63da45c852b2897303a97e37a5e67ecba749c45311703059e51524331a"
+ ],
+ "conventions/brain-first.md": [
+ "14370d89209c7d7e2673c6a4d4e7545fd3330f0744ab598170865a41ae20210b",
+ "29d020470d0168f8f0b29dde0350a485a9b0472f7ac9962e34948f4897455590",
+ "987223ce443b3e8cdcd22975aafabce778016f238deddf544c346238dbde1bd9",
+ "b98dc24e086a35f136f74ca4abd856949d8b282e1298a47a250b2d18f69e0927",
+ "d9b18321150830d38586f5bd23ce9de735f08ac3b54d7ac63bc3184a61e17ef1",
+ "e0e4d7c4b760213325dffd286baf934720816a0b6aac5338538a0463e8fe77d2"
+ ],
+ "conventions/brain-routing.md": [
+ "392998d9a109b330c9225af4ca5c8798b0ff02eba4d441c93fdb7c263687d0c6",
+ "a8035f7dbadff0ea68b8babb8314b3d044cafbed8242dce5b931fa08b028fc45",
+ "cfdc22cb4becebf11deafe6c9a6802d2481e90473aaf36e307d1dd83a048fc3b"
+ ],
+ "conventions/calibration.md": [
+ "500dc26bd7c8400f50dc4c16fd83f1a588f3e7e68c59050a21fd8a0f69e4d198",
+ "dc357891a86987fbc39e06a21a190119b9900e03a2460af64b278307af1b4289",
+ "eda7ca76f80c8a17ae546110484389f805c5b21fc0a57f951bbe8b6abba26e03"
+ ],
+ "conventions/cron-via-minions.md": [
+ "badb1cd6cd825d6f1ac0b6b28cc47e5d80facc783a3e59a14146ae901ee0f933"
+ ],
+ "conventions/cross-modal.yaml": [
+ "c012c3d72614a87b1ee698173dce2a0fb0d057a54df7aab87993c4b07fff6280"
+ ],
+ "conventions/exec-output.md": [
+ "2bf371ac3ec4987eff7cc13cd3ea8cc97c46bd43f588eec024ff27f3171bc58f",
+ "75f3abbc4041413bd4ee38af44fe82e91657b2c84525e6b92f627400e0abab47"
+ ],
+ "conventions/line-grammar.md": [
+ "9d00254359153064e9fc0959d8c15743b5ff860890ed556178185bee32c7aeb1"
+ ],
+ "conventions/model-routing.md": [
+ "8b28aa706436e7b68493ec481e12be6309b0af1a553930e8b1029d675fa4b3ad",
+ "a8d2010b3cf59d45812e9e744470cfc4426b8928ddae1ce312443e352b976685",
+ "c0d5031e4372c108d7e94346dc2958c21389f3b67544524578bbc9ea32d53c34",
+ "c1aba7a5c34454d6913edadb52ec7b53a3741f318c47fab6a26d5214479a8532",
+ "fb7ae8746a578500d6789b68ff40049037aa4d337b65b42f7c1745ae7080c2db"
+ ],
+ "conventions/path-discipline.md": [
+ "8af5415721bd115e6979c96688bcf542a32675809ada9aaedbb6706a40926954"
+ ],
+ "conventions/quality.md": [
+ "8aa681001114689d34268ccadaf0e2ff07b8f68aa5987c093a8c4a7a744f12a6"
+ ],
+ "conventions/regex-discipline.md": [
+ "d96a9baa6f27184e165889a9c655607366a739d851684d9f41cdec294f99edac"
+ ],
+ "conventions/salience-and-recency.md": [
+ "0ee7f0216f36a5e321673740d148cb0f1113268df19301bb2473a48a728a500b",
+ "62b0b303bf48bef10adcf08d3b51f23d3b1f1187b3850476a4b5532c2ee88926"
+ ],
+ "conventions/schema-evolution.md": [
+ "24028e39facb22fd9abbfeea047e2a2538470d0681461b69d3ed64fe59341233",
+ "b5cdd5a17e43b4f2d0546ebf8c421cc0378cbcf74cb2fe97199e115ccb05f9c2"
+ ],
+ "conventions/search-modes.md": [
+ "2862364874115d75816ba5d0e10f9073043a5fdaa44e9c7f530afc6c492e4a24",
+ "2a920225d1c95ea978fb1c77c5170f6a598377ab86fc0024b70962d5a84d54d0",
+ "550a94923e483e0b61e3d9eb6242f13a08e0a37a1eb1b95d4111bfa6ecc7658d",
+ "aa000be5550a43d720425b8634eee62cbf2479bce9a29b8e964aaad446c6cd20"
+ ],
+ "conventions/subagent-routing.md": [
+ "59afd362ff0cbaf3a63586e97c53f68feb837a258a2bd43f9177af4e57d2b20e",
+ "8b8830b815a9a8581a12b489f966c0b0a39eb9b5f66e905a691a03653eef348d"
+ ],
+ "conventions/test-before-bulk.md": [
+ "5073e5b93d570445f72f3c10ed3e6ec10c1fee7574ad73c2e2695993c850eca5",
+ "6b2c52cda9e2cd5f04c15152b3d92aeb7187ab193a15082be0f8a3991a6a5725"
+ ],
+ "conventions/untrusted-content.md": [
+ "259384d490892cd0e1e8e054decf752d7354f516c83aee57b332c1a96aac6a6e"
+ ],
+ "conversation-archive/SKILL.md": [
+ "0d27c637f56fc10f8d27c1f0a02aedf70e2bac4355436e9f67f81b0bc120e3ba",
+ "3c1d342c58444a8b2c7fd961dee1ff8c08bfa3487877f877699abd4d0582b003",
+ "4e1dea00f5e1e16e749a42f295fdccf556199d4400a2ba1b891aa91839e37214",
+ "867d3a202ce500027ed2ab85edd9d3359d677aa7a180105f2b7db12ad3492701",
+ "895b63ecc46ab7bd173ba9bb8d0cb740f355fbfaf429584b74842823edf68a42",
+ "90bbc9f5b3e8dd915e3bcda6e0a49fdfbaa3d1ba16e61040a21e3d5b665dd7c9",
+ "a59d3dc7076871b8605b5be0cd48fb0b7ae5c0d97bc65447233d2addc2680ac4",
+ "d156d71460b91d8b4f878b26fb5f2cf129ccbe2083b2b2dcdd8ed1d2b86162dc",
+ "de2b44da329c4601da8c77536a627b094e52a93c8f45032335571b29b311d736",
+ "df603c367ef604b9b0a326b04d1c91a67dca87418431080f21f1122ed94b9960",
+ "ebea1a74ef2a5557666b0fdab39720d5699eb4309acd5cd31b37182279d48fb4"
+ ],
+ "conversation-archive/routing-eval.jsonl": [
+ "ae087a84b1fd5b108b7cdab8d035a09b3ccecd8aad53ba5f71e463059108cfca"
+ ],
+ "correction-pipeline/SKILL.md": [
+ "04b4aee06d7fcdd75db314da432ed7c08b5fbc20f117f18062c64aaf795bc564",
+ "b27ca66e2c27c6ebdca58abc1b7191722307170f7356f24fe90d348e2a1f128b",
+ "c19869aa60ac00e15fc97ca016dd84dd63338fdf3d7b39990b33900eb7dcc703",
+ "caf1264b7afec46569d30f6d92b07f37ae375e3f4e6aeddd58866aec327053de"
+ ],
+ "correction-pipeline/routing-eval.jsonl": [
+ "7f8d96606a8d7bed3d79fdcee6904764c8abb9fa0b506adb414b5c4805b69d0b"
+ ],
+ "cron-scheduler/SKILL.md": [
+ "2d22d71ae746c2d7bbd76ff0a26c093f40d380823fc6ff6d5c763d258ff91a70",
+ "70a7b08eb0b3269150f472f6b8a65611afe7c70370767320413529dd4b07b443",
+ "a35d24206d7a309b3630f0492048676c75c6f3d6f8b58518cc9afe8dbcae533b",
+ "a89bfeb058034d5033c42d56b35297e5f33e28a6dac01860d5e033a10262b3a5",
+ "bda1d4a55053a20b379187082c72876ab452877d49ff4607d4009ac533989717",
+ "e3f9745c4f8e2dacba5b055f408b1ffe541b450aee6bbfe4773f7b424d90e04c"
+ ],
+ "cross-modal-review/SKILL.md": [
+ "18ffb01ce6e84ffd9ee2c0c345b8db3aa82ae0c33b3183bdd7bad5070ffa5b26",
+ "685233b1afd477e96697562c502233eea22eda5db8df116b81dd2fa78f01f80c",
+ "fc00a04e2ff9f498bee9b0b636bceba9dcfdc869c35d9a983109f408170f0807"
+ ],
+ "daily-task-manager/SKILL.md": [
+ "a0e019eb2b0c8aff5bf97889f30a3f13e61c0052289a79d00effd7b84177f4b0",
+ "cbec93c0d90829a9c3772722d69056616d3eddf13db6216f21f5b43c57282f40",
+ "e616f74a6befffc7bb64c0e29b2d2caa37c51bc470bca96df70101c772429d83",
+ "e93264a83b5fd0a19b2f06a322b3a4ad92d418f6a968c1cd51f4bea79cbca4d9"
+ ],
+ "daily-task-manager/routing-eval.jsonl": [
+ "e98b2592e65c26952242436a960d8b2061e375b269004a18c230cbcf1d692ff9"
+ ],
+ "daily-task-prep/SKILL.md": [
+ "37758d345cfec37e7d8cf36dd876e8292110e3b85cef93e3dcf4c566014b5a9d",
+ "5ea839012b48761ed8d7a9bab056a2566587d6f7fe044e3907d77b20f8eec5ac",
+ "9fe89f85fae139adac25c3bdc6f23bbf64239f3738a9e679c447e686175516f0",
+ "b2340d2819b5d33df9077335889450d22456e5cc7ef8fc9ef9e87d6e367224c1"
+ ],
+ "data-loss-gate/SKILL.md": [
+ "6cddc796a128ddeea8c622de79dde1ec1e6c214203bce51ea5e751719e291d46",
+ "790407f6a91dba74d6ca1f482bb2eaa28977e79a5cf9a8e642f71691cab69652",
+ "95ed4cf41deec4df50a56a1d28efb43738f0d76792392693d1b0956c93bcb3e7",
+ "c1736e0985121e60ffeba993b68b5c722c9285220057b5ef72059f111aabcb18"
+ ],
+ "data-loss-gate/routing-eval.jsonl": [
+ "825358a5600641061a02b25097cd84c1c28bb0359a7608a10b9f25f661bd88f9"
+ ],
+ "data-research/SKILL.md": [
+ "1dc6161088475e1e6d0b0ce7890e4ea1371a321b45adfe877cd312d7ee275e36",
+ "2b1d7a70772ff8c202604867ed02e08cff473b2da808974f3f0a18b78b112116",
+ "39f9648a21a7074d6ad7db789e93e6d7085449a6cdaffacf8b1660eb68636b9d",
+ "990ccec01a23d3e46c7b5abbd2650ac5507480b50f7ec4de8b466863b3b61cb6"
+ ],
+ "db-repair/SKILL.md": [
+ "0cd6b3f9fd57b9c7f7bfeb041cb2bec7c4469cb8abcb850839d307e95b78b300",
+ "0ff994ad468234c9020e8005ec2d8f40c27382ab00fb6f4ea1482cec76f507e5",
+ "3427b25dd58d5183881a31ccdd47f2150ae7778526acaf8d18ab122e277ecacb",
+ "87a34fe18812f3b6ec37381ae69c205e30747300098ebe3fe41f8460d0ba8346"
+ ],
+ "db-repair/routing-eval.jsonl": [
+ "45791b0bf2cb9f98b8e58d82e95288ff17ad44cab484ab570cfc2ccb14583935"
+ ],
+ "draft-in-voice/SKILL.md": [
+ "0634fce165700cc8f9a4433e02229ef9b98f52d1ac88848cc7529f9bc43496a7",
+ "237ce9c0701d8d2161b118ea41050958e5623a7e507bdbb674ffdd7db96d0061",
+ "8bf8a3c622d454f760d675eb883ff823e300b7f5dcd5b2329d523413e0a516d9"
+ ],
+ "draft-in-voice/routing-eval.jsonl": [
+ "590fc16277ed7c3338776e7fac6daf1270b91058941f8101079bb295d2d8f787"
+ ],
+ "eiirp/SKILL.md": [
+ "507249ce40746c0f3d5ae2a374164797798c6ebbc6209b312e3404a2f4902e6c",
+ "9d42d6a5f61bba30cb47400db58927c501cd89e5cc3241b5218d7962d1a68804",
+ "d2437a9704230375fb8e57a4a34587ac9059ed1e11dd7b0cfc49572ee1bdff47",
+ "d58464cd02a6e5a21d2ad23cf946fbe97ab197de029cfc29e437265ce4c74eb2",
+ "d588d55c91a190c4517fab4ea13e592b87334ce7d6cfca293e09076b63b26017",
+ "ea32eab52c2aef7c704b6608fe3431702dc42459bd3c2ee4a2eb65e7cc498ec8",
+ "f0c41e8d9c3e2857622ec1e795ae2802c8de1c69a1048d78adfc0349f8be8db9"
+ ],
+ "eiirp/routing-eval.jsonl": [
+ "416459ff68da2e5f5eb216a0c24368c8eebdf4edbbc540a28fe730ceeb4c9700",
+ "d0000eec8154ba48488eed07e8f1a6a0ccb66d0b39e41f29d279a875c1673227"
+ ],
+ "enrich/SKILL.md": [
+ "7f281eb60dc5f1fe2225c5d6fca1c3e2a0312418b8fb7df9fd7a192be00c614c",
+ "9988168348f6c3391d3aeec6621f9c99c8d75d1e1bfdd6c44d48e4c1067ab775",
+ "a876b1f89ab0b492bcf3ebbe3447f682ecbcf4f83d213d3ca854c3922f2b3fb5",
+ "cbe6068373f4cd5006a6171a1795c3e619cfc82009ec4b3d86174b8ee2bcee2e"
+ ],
+ "fact-check/SKILL.md": [
+ "21a28e6cf6c5494e7c3e97dfa6bf6139b97c735fc229c974bbad89db4a2ff4a9",
+ "49f0d356eee44541eddbc9cd501dc36707d417d84ca10446c0d315321f259674",
+ "75c439f721a6c33fd3a9350b3430086b6dba974e245ec603d01125ec3b00a682"
+ ],
+ "fact-check/routing-eval.jsonl": [
+ "7519c6eada244813264b0df34ed67613e2d4404cfdf3cb209051b461749f5662"
+ ],
+ "frontmatter-guard/SKILL.md": [
+ "0a4ad3487f74de99fda50776bddc6a904f9b0e16f6384f48d3e664bea1db65fc",
+ "1ade7903bba96faab03acc21db0ea15507256ed3bf81153e60526ff63aa26665",
+ "5142ab53f5428ebc084ded78f1fb7eb4bfa386d276ee034bf4d57273256570c6",
+ "5d8dd7aac288063b10b586879d33cbc5ff7794f7841deac9c5bab25f7b4a10ce",
+ "706202b2000e239d20894f52e81a416a8b5d216cca18ed1bb5153e75d1f287d1",
+ "9d341bc1e02aa09528718e020b092102490d3de06701b18e319d31fb72e6d4d2",
+ "a0112906c2dd7f021faa913da864fa11a25fc416962d992347a3b9c3236dbd60",
+ "a20fed7da1aecc38818f2b649df0ac3c8a218a742efbe2a774d3cea34a728e7d"
+ ],
+ "frontmatter-guard/routing-eval.jsonl": [
+ "243c28b04b557bac5360318c0f47bb6f1dd56d2f720aad3763b93fc0b2ea081e"
+ ],
+ "functional-area-resolver/SKILL.md": [
+ "1d2dd3826999a6f0a86fcbd699bafb7e4d74ed3d34cc8c6ffc23b224926717d6",
+ "52df04bc4f8e678f931c3b2078b2126524e6d2d72676ad46b6b710d13271b46c",
+ "fe6e35fbb34dffec7af9ce4a6cc9c0b0eaa8345f97f33262a2abe0983431b421"
+ ],
+ "functional-area-resolver/routing-eval.jsonl": [
+ "f80674d915acdfe229046737a5b171da834be15ac6524b5a3fd18048e9b37028"
+ ],
+ "gbrain-advisor/SKILL.md": [
+ "7202baab08775048529f131e694e4fbaa85b1c8ae79e4fa7997fe4fe5ffbfa3d",
+ "976b3c5c3798f9fec764fa5bacd1567f751875bd837fe188a0c6df041805ed51",
+ "b4186ce45ba1b5b90b62aee2cc39a72f56edf148f27507219afaeeeee87b22f6",
+ "c15c7a88bee2c96733d718a168dd9afcb123b7b6b2c0014c5260d37c72e8736a"
+ ],
+ "gbrain-upgrade/SKILL.md": [
+ "3acd674fd78af095b3a40fb4b437475552c166b6dd57014d7db6ce6ea94ce9c0",
+ "4cd6d42c6ac57b66ab5d9066d83ec8209a47b35363ce2c0722eb6515ace7b17d",
+ "62735c599c12863a7f1bd2193021d72136cb1210b11592fa95d3ce6aded99cff",
+ "70ca370073aca86de8ca365778141e14d56f6dff7bd1424a88ef2865ef0db4cd",
+ "7b069a21f0354b04f370a817cb265632af0fe62f8ca7903f0b4f2783305fe685",
+ "7cd05f43027fa20d56ed651f696288f9e4814b7bdf7b396f132fde7c96dac620",
+ "c68187b205ed2f5d097c62cb05b0a80ec70a2cdbd9fe3ca09fc6bc3cc73d4d34",
+ "dcd1ee1d12d500fc1f56d1545c3f05fc305619f295dba53ea1843ae9d820ae1e"
+ ],
+ "google-loops/SKILL.md": [
+ "20955fac0a94bbe9298a8aa7416e851cac86eb145bc551ed0fc556d2f583fa5e",
+ "29a68dc8c1433722632574b1568e914229420ea2ab5e1c71e521578969f4d55e",
+ "5ccdf9ac291cbf5b96d6c10c18476bd39c79bed8c192bfdc789fd4b70bde0138",
+ "a535cf208c0615cdc1077c695b22405ae0fe03b097252678c2cef563208ba6a8",
+ "b571b31c2e6c0675d6c710db8801492590a8d5aa9a1e8b90f0f0c33d4470e8c9"
+ ],
+ "idea-ingest/SKILL.md": [
+ "01ef449b7d5df52553cfd7c05d1365085058eda32de4fad3e67a22311ccd49f5",
+ "38a809a9073c7d8f71306240dbd764c94e6f39123ccbac1ecf0db46fbfbb0805",
+ "863be3660ead12a45d3b86309d73df0ffda6c5db6ca69873cce1810680df79b4",
+ "b3810543f92cd37cb8488ff30990c60bcedde58dc404a3f60d43ac97016d6e33",
+ "e118bc32d5044a4a6fba4fed1911b8be50210ade14957e6cfe8e7ed26ff95298"
+ ],
+ "idea-lineage/SKILL.md": [
+ "3432a9cca1626c7876eb12d7ec0d6cc37feeb8f3c18cf99f08028ef3174ae0e0",
+ "8cb36179dbf94abc17065613b8e773b1bb2b22670742aa77347b91ac885a05c5",
+ "bbf37781d93b71ddc7909ecc5ab635872c874fb8591995dbf88b45ffeac6b1de"
+ ],
+ "idea-lineage/routing-eval.jsonl": [
+ "ee2e00704b9accb7dd58bb8f126a3bc04a2c40be499180fa505dbf6d5061cd41"
+ ],
+ "ingest/SKILL.md": [
+ "1acc220ce6e9e65876fa2ccede6ce11f9c75457feb6695ef904955f8debecaae",
+ "31df4c7c8eb1054bbe61c459042ed535733da802640f7a0bf89ec4699680239e",
+ "887d1dc43d1dd4d541172b40ce64385090813132ef80fc05c4616b5c32087448",
+ "c11d2a032932bbbe1122be9bbeaea0bf32be3a44cb28164fcb22011a7ed55e0f",
+ "dc40ecc0072806fb8c7bb6ab9cf1f103842e05653eb55d67632d7e3ffc4dd7d2"
+ ],
+ "maintain/SKILL.md": [
+ "1bd23d13dd9804b97fbc75e13161f1a654fb2dde98d17a10e73bf3170cf8034e",
+ "2a1d99b68a58a6f67ee88c871bb1185f4f73b99d26a7ed38ac56b2e12a21e5ce",
+ "33e48e31baf89b6b257ad863cdb9de444777bc1272f5ed8c2b28be3a54cbaa14",
+ "3c3ae93af3b224b1f4e2fce313a45b5306809e13eeae3908ba19eacfac7d9d5f",
+ "401e68260f047bfe2cc7bfab358f492f4b216bf36ff3acb92cc7922dd0babdc1",
+ "5613fa8339d8760613851ae3c2b5d09cb96102177b0aa22cc147749b330f22a8",
+ "59da3f0227a2b41ed9c3beb334322f1ef1dbd80af733a587c0a4687a707b9815",
+ "5fb4c010230fc8f1d58e0bd5a76033f960829f9dd1895ba6de9b728931c55063",
+ "619762cf3bc4553d1d73dbcf7fa9629dd335ed61012057df2587f15cf9672fde",
+ "74244af50a4faf3d3b2f16250cae0d01c2911fa50d2fca1a02f936f9dc2a21d6",
+ "74e1249bac87b7ae6492bd3dbfd6a4d1ef630b199d3747f438f8e161f56e9b76",
+ "762e20ce7e064709a31a843704600679fd39e6734c9f14a67a98fb8c081b7513",
+ "89ace6ae686284fd4423416a3b80d8ad940fbcf5313523f690684afe52779788",
+ "92111d9203e940a6f068f9b3abe7516e7831de9a7e77d234bb6da6125c3d663a",
+ "964165253b5f7919ba0807c43c092318faad1539605316c49137c5ac8726fc34",
+ "987b470e34a6cad2c3c12f9b4a77183fdeee0dcb918f792b7545e6f552fd4aa1",
+ "cb45aba2ea4075195ed244f28571457cec8cb42f70fe209b570c29528d857b9e",
+ "de3d9a6ce414470ce4bd406b28d9c8ab80ee90a56d51ff1bc5136cae9fead00d",
+ "e0bfe8769b2fe19a28c22a36f3e24f5df83201fba0d08050824ff8b913cdf74d",
+ "e80cf5bb170c979b773a67a18e0d880c086e0b983db9a576a207074b0112c4f8",
+ "fd08497f175ede76befe530a6a56adeed39ac37f9ea0ee19f2b9757488e36731"
+ ],
+ "manifest.json": [
+ "03471868cce05fa38af6f793da54e2fc11f77ef778271a596d75bc29f9ec4c73",
+ "093745b702e2d06b8307dc12438019992aaf2057263e251db5525ceb3dde27a3",
+ "32ec742721aa89c814edcdf17809c73a30dda0c20c4399e1239db10e8504c1c0",
+ "357aa185d380f0a357cb15cd513317e290cbc5fcf5ca4e3860b0e829fdcbf1e4",
+ "52b970cfc3ed340ee4f25323b6fadeb5d125741b02d1d2dc2f85c39f0c701258",
+ "8fbdd5fd3c5c8f9b4ebf4c5af18f2396af6f3f638bf180e8ca0b0c35584dc6dd",
+ "b75f4583dc52fe6c4749d899a54079609c1b2118af42ca585e6ee322262abb96",
+ "baaf776f2edc1fad7b10da5cab520650b2097f533d37b1da1f499d0d9c060f43",
+ "c7fb80201fea7eafb815d1e242002c5838f3c853f857fd203ef34ee84dd2f057"
+ ],
+ "mcp-access/SKILL.md": [
+ "1bc16338b89f476aa8c24ffec79c989fa60716793998af264d357f7886d2bc96",
+ "77f67fb2c07e891e945a5466ae075a3f9d488ef31e86150a99ed5341a782f73f",
+ "c2ff223b4461ba5817c6c0e7b50a1006866204b6c1d4bd905e52809350ecd092",
+ "d308714208f457a9853fec4e83fe035dcd911bc8e506cefec817bd218f3340df",
+ "d96d0720d3f15f442e2f87803354206795f04ae114869a2cf608aa5c9955585d"
+ ],
+ "measure-before-you-fix/SKILL.md": [
+ "11906da29a1a31976b13d4796b686d9a9981825737846a85f32d88bf431b9b36",
+ "1fd3b40ab65cbd08f50dea16107701859165469be3c85c57d779c7b4bbf92db8",
+ "ec55bac9b8b052b854c828a4b60ec37108ecc21c8d2dcede266181026b191c2d"
+ ],
+ "measure-before-you-fix/routing-eval.jsonl": [
+ "0661df9974a9cfe31216d574b1db0ef341945c2eb844ebf4ab6920fcbbc90d6c"
+ ],
+ "media-ingest/SKILL.md": [
+ "33db12830ed31a4ff4a6a58c4f126bf2596ee28d54cee0027680c83fee648a20",
+ "4cb0dee1011dce0d5a65dfa4610820511ed6e2da005c7ba15500c79f0b9bcb2f",
+ "d1f46ebcd4977166e3b8953c540f5f33445be02fb071a85e2143b1f416859a16",
+ "d70374d3df21397380203f541ebdcc90c0bc6bc7207234349594a081e98f2719"
+ ],
+ "meeting-ingestion/SKILL.md": [
+ "0b4498d822b94bbe292aa98cd73a684473b29ed08365c43fb885b0f7955e2733",
+ "58dcf670fad8790f91b33c9c268b97fd60a2ea82707022a037c31e0269932306",
+ "5b5fb201b6e7eda5b38ada1c3f8f2b101560c23ffa72012e97f408e35db7d180",
+ "7767334c63ff3bd8e60cd4d7cd1d1b44f0d6b0a7e0ac411529a1d59cc0a7781b",
+ "898ac27fd540641f946168095e494b115b924298f1512858aa813d0d2aa49918",
+ "949a491b98e7dabe51e3d1640f49a7dbfacb543703d22619a1aed36611eb383b",
+ "b9e4a86e7892f12a690c3f6b3f78764473739243b525f0a4de2be1a7238ac3cf",
+ "ee30ec5813080d6bb3b5d487389ba2887dd119e7dde28feda65db149568ffb7d"
+ ],
+ "meeting-ingestion/routing-eval.jsonl": [
+ "1995dc75eff09fd2e5fb403a10c81dc71b4c12035d48c77e57da0134c81f731a"
+ ],
+ "migrate/SKILL.md": [
+ "012ac9d709183b9d8502e91b2adf345a44901951ff41343d6473f396d2d1a58f",
+ "442c117cfe50026a142ff4f934e489c56ee226d454b639d20bba3b111a86d8fd",
+ "97a6c0e8120b2198cc73e27cdccaec06f8636aeb8e87aabffb539df2e9df944e",
+ "ab7d7874bdd6cf1ef34538c2888b93b0a416f49bf04bd608dc5eccf9af9a5936"
+ ],
+ "migrations/.gitkeep": [
+ "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+ ],
+ "migrations/v0.10.3.md": [
+ "1e12db6fdb88d21df479659e236bad111a041a205d47aa0894afde2f04903124"
+ ],
+ "migrations/v0.11.0.md": [
+ "2a45f374a24a19c90416745e97e21e48148c1c45ace9b59e1f2beef27da49786",
+ "ac45c6144eeee5033f2b24308a5063ceced2be7831b04e48154aa0b6f8ff55d8"
+ ],
+ "migrations/v0.12.0.md": [
+ "f30b452caed5ce2679cbd60dc2d0b9e60449bab20c3a3e0c895e6cd167644f44"
+ ],
+ "migrations/v0.12.1.md": [
+ "a461d8fcd6b19dabe3a0ce849a54e3c577667ae2af41870c6f456c6195e76064"
+ ],
+ "migrations/v0.13.0.md": [
+ "3bf61eb1da933e6c3c35d67d0ea6d9dada5d5f878bbd14020616d4e1fe48feb2",
+ "9725da5d889b488de14c312fadaa81800e5167e0ecf6adc5a083d721a329e5ba"
+ ],
+ "migrations/v0.14.0.md": [
+ "1025395f033b91480451aad6a98dc10f2c18bfacd1b1a4e2a9fb4dc99f8fb571",
+ "47a1326810af07c322740757740438f4d90f03bf2a8b1aea061535bff5ea8e1d"
+ ],
+ "migrations/v0.15.2.md": [
+ "468a58e8a9f0f5c5867e0ed8eb9dd1bd60dbc8d66111647997ebd8d9d2119915"
+ ],
+ "migrations/v0.17.0.md": [
+ "761dda3b6090bfe20c9b4354aff5248d5a9b6a79a24702ecc2b29873d4f5b413"
+ ],
+ "migrations/v0.18.0.md": [
+ "94efc1d571070600a78aca13c2735866a987e6a8f188210b7062f81b54839986"
+ ],
+ "migrations/v0.19.0.md": [
+ "c47584e8306680f21ddc7f21a4a89f2184da522acb177f0dd73a09f1cd77ae57"
+ ],
+ "migrations/v0.21.0.md": [
+ "83569ce6fb2843f81964833affe5eae72c94a2983eba265c836aa05be7876957",
+ "b2c9e3e2fb91f6220a5af284d777f145e9994401f85e2b2a5418158ebb6b6f48"
+ ],
+ "migrations/v0.22.14.md": [
+ "8898c109716fbc48c058a44c606f50fb7c02be599541d367380aa2e63bffea9e"
+ ],
+ "migrations/v0.22.4.md": [
+ "5f9b2ed86cb64d92416448e744ca6c4984b89728895cd4e363f9c76a860074d9"
+ ],
+ "migrations/v0.23.0.md": [
+ "f0363274e5071fa35d0c60e3981c4caee0494c43adb254d65acf6b743d4762d5"
+ ],
+ "migrations/v0.25.1.md": [
+ "981ef49abadf19a891cb68b655b9f35ee67d9f4ac232ceb29d83dfc3b1c9982e"
+ ],
+ "migrations/v0.27.1.md": [
+ "719dd4ebcc7ac81413ee79af20f80de5141577e3860e5049a49fc8f6d09ddf89"
+ ],
+ "migrations/v0.28.0.md": [
+ "21929a392af2e1f454272e80aade6c58c5f6ccd7253d24344d08c6b53bcdf4f9",
+ "58a98cfd5fed4e2aa41a53b51efa04a8f632e61dcf595df7eb8619c760593a27",
+ "5d13a3c233765feea6e6b1ff4fc346f8e43826e50af8235377693d53adeb69a5"
+ ],
+ "migrations/v0.29.1.md": [
+ "7b85373a62a8500ee8c4238ffc9878318b44ee62543adb8b2462049c6c0cd1f8"
+ ],
+ "migrations/v0.32.2.md": [
+ "101623fa48f946242d7edc8f126967822563c3fb30a6ad50d029894f5fe3499d",
+ "7dc1198c02ab37534e04604c93c7e9a854ca9f04872af2a7c1fd4c0c8b78fbeb",
+ "88069b6ede3933aacb0555480bb730f75ca67602a5ae953f9f2a95a2bf6418a2",
+ "c11acb9488ecc51bf06e9b61170a9f264916094dedd23a30f62edcfb63fa6134",
+ "e32e60cba9179fb2429a1cec38ee91abd66937baf4ab393ab008660e59aaf12a"
+ ],
+ "migrations/v0.32.6.md": [
+ "e9438a910afe8a1f7861c5222fd7db04a0f8d8b8283778476b07b7c3d539d3f0"
+ ],
+ "migrations/v0.33.0.md": [
+ "11710cb11d6eb7dc3ea54b764e3c4a25f8679cf76590acd330f97bfa1c684945",
+ "79febbe39b9518837acd1adc86c989a75b196f9fa5c7a217e64dc2eadc23ea01"
+ ],
+ "migrations/v0.33.3.0.md": [
+ "188a03ca86a97a9aa697cbbc83cc8ca37843fab24db2bd82f1383c400173d5bd",
+ "3747f72d050bf0d269227af2bf5636238d959fa0508f80470bad4874c725d96e"
+ ],
+ "migrations/v0.34.0.0.md": [
+ "d421c5ecff0765ac1de3592d3175734db7df52e8658ec101567779c7c56c2db2",
+ "eb98a3c702c4a0b606fae68c8b559a5e665ba7290c838d306c4d019aa1ef6706"
+ ],
+ "migrations/v0.35.0.0.md": [
+ "0fc21dc0b098f87fff1ac79a669b00a3d69ab1510ebfc5eac4a66f5c6d783809",
+ "1f4083b6447ae694776f35b70ec6c259b03987cb35a8ee4376c8f51db6bb06ce",
+ "a87d0f04f5d1d275c2f283c3736f0208bb9e24a540b0ffb79ec9d4c0de90e01f",
+ "b4cbc07fffaf4e291fcc035283d976498c5288da9b10ac7fc97947747acea150"
+ ],
+ "migrations/v0.35.7.0.md": [
+ "c6d4454bd39e2aa243b3b3d9bc72fe5a4fd25d097be7be2bb14b25604b5c2cc5"
+ ],
+ "migrations/v0.36.2.0.md": [
+ "18f72475a0c0de1489c518219128d331d8ed6b0cdcacfb329e18fbcc643d9c6e",
+ "1b59328240ae19c5e7e8d3eafda245809cca1fea27146607334dbee53cbeb270",
+ "2b3b4cc0dc2e9611b0df9aea0a9cd4281433011c2d88433f768e762b28d56320",
+ "becedef44dc377cf95c83ddc479c9ab19f15a984f716fc0b041ba7cde6886f14"
+ ],
+ "migrations/v0.36.5.0.md": [
+ "889f42508c28835c99242ec20b610ab002f20cda821cb99039589a212cac2ce0",
+ "a01a722202dfc3c799693596750c8bee611fe4dafe3cb662f6b4cd0b635cb429"
+ ],
+ "migrations/v0.40.3.0.md": [
+ "5f500f8c543c2b6f41778b0bd3beedada68f7284f7933ad8b769322b433a8fe9",
+ "ec6c3a7c1c2c1d1e78115fb43b35b293134da9405763b56016b55e9ea5da1121"
+ ],
+ "migrations/v0.40.5.md": [
+ "92f0fce78502356c0ac5b50d043070b4002455026237004dd3ef7f05584e95b6",
+ "b9837d52a030517698dfb31c439f562cde60a1015ae488dab09be2c16ff182e5",
+ "f66047f1b6ef18b5b5e35445d61c0a1fe44e3c0f9e1c7a51c6b2342c67a0d92f"
+ ],
+ "migrations/v0.41.11.0.md": [
+ "5c6873ab969d14def4a450d792f070f1259d08b3aca43bc7825d0a9114b2b36b",
+ "75c9741617de4c163052609e64734b4696a1105d3d015ed451097eaf6ea1eb3c"
+ ],
+ "migrations/v0.46.3.0.md": [
+ "0438f52f423b8f99832d0098fde94188af38eff603a956c67014e5e9bb8572f6",
+ "7762212509ea3f954b31ae4ebb9ee8fc1e497ac021c633fa95631f03a2eaaecc",
+ "82e0ce4cf96700332235f4d4307697651fe7376af5b5c1e88331ccbdbd3abc86",
+ "9885b8ecf42c7388cda459f402f4b057cdf7ae7a0ee8ceb296784e6344575dc0",
+ "add5bdace741f8f0a75a114e354aa8ea3bcadf4cb54e1823338fdc69a5ae3f5d",
+ "e00cb0609d4bee53749c6cbf4d7f17606649b99688c4a452e5054e8e7b67c00a"
+ ],
+ "migrations/v0.46.35.0.md": [
+ "145c841d89c4b6b6f7089126354fae272df7db6ceaf9cfcec2797d3301cdab57",
+ "4f492de8a7d4902010794e4f24b57e48116c6d746387a978edac6013387cd642"
+ ],
+ "migrations/v0.48.3.0.md": [
+ "1d9a23b6078164717944c94791b18effc7af630b716e8fde2680d6b6de47ce81"
+ ],
+ "migrations/v0.49.0.0.md": [
+ "adf719246c3d6bcc7a1e5d24badb9968fe636651183a75c18d534e16aaa33ee8"
+ ],
+ "migrations/v0.5.0.md": [
+ "5e0dabc451595295c4d971e19bcb33c258a127223d25859d8321cb7e1ce60711"
+ ],
+ "migrations/v0.50.0.0.md": [
+ "2f655acb9c7be9f10568024f89e77a75e6093ec3c7e5cb00d7ef8dd19a8d70ae",
+ "f221a6c907437a7500d2ad8ee9fdc5e14821514d4c1e72164b7aafac0bd5d89b"
+ ],
+ "migrations/v0.50.2.0.md": [
+ "ff1aab621479eeda5f210e026169ba584a1c402536cabddc7c387a617934b6f1"
+ ],
+ "migrations/v0.51.0.0.md": [
+ "c07ea78c4887791425358cf3eed5681f867e8d30caf4d639773f08d70578d4cf",
+ "c1f1f6ddcea71cdcfb4d9a85200564b59cc64e7d2ec29fda8c98335a8a7afdd5"
+ ],
+ "migrations/v0.51.7.0.md": [
+ "c34621712c4fc8597e193c7fc44b588cab8622584204a2b6f59ffd24b9d3624c"
+ ],
+ "migrations/v0.51.8.0.md": [
+ "16af7c14f4ee12029b87ee2f07446a6355216ddf6109f54c2fcc0adbd558b09a"
+ ],
+ "migrations/v0.52.1.0.md": [
+ "7b54ff2e4e881658020d725aa1709f10b34e118974e1899c4c46aca3712409a1"
+ ],
+ "migrations/v0.52.2.0.md": [
+ "07568b099264e56f909f46eb417c4a512788e893e8ae6080423ad6ae06918076"
+ ],
+ "migrations/v0.53.0.0.md": [
+ "117461f687ea33e0ba2a952aecd00b9d2085a2a0562d2b1b50145dad0a5a4728",
+ "1358cc16c075fad50bd527abe3ff93f39a42eb6b6c282f5a1192f6e3c9df6f16",
+ "14440e9aa189d2f751fcd7aa0077b95156d85b145ba04111520d69bf4b9f76e4"
+ ],
+ "migrations/v0.54.1.0.md": [
+ "ceee87cfc7bb28036e9cadb5b70b7ec9eabcce6d445e259f3ee410a95fe69603"
+ ],
+ "migrations/v0.56.2.0.md": [
+ "e88f04a5deaef82ebb8bd194aec931f26e69e87687098eb64b94666931b5e319"
+ ],
+ "migrations/v0.58.0.0.md": [
+ "a6ee3d3125ff1be612df776c7b8d6dfcaeb57ca073255793a67dff78a23c51cc"
+ ],
+ "migrations/v0.59.0.0.md": [
+ "7903e547e79ad3429a393d9102a610e2674388bfaa71607431b1cd857b4af939"
+ ],
+ "migrations/v0.59.10.0.md": [
+ "e0268a05ab184d5518f88747313e772629b2af91db59eacbba728f2ebd9db3cd"
+ ],
+ "migrations/v0.59.2.0.md": [
+ "b6d61af8ef48c154a26e8d427dd6f6570e99efb82b891728426046eea493247b"
+ ],
+ "migrations/v0.60.100.0.md": [
+ "63583a73e957c5421bb826f2be48ac1aafaaa994392c1a05f26d1516b48c8573"
+ ],
+ "migrations/v0.60.102.0.md": [
+ "be46986da0334071931b5a285a532335af92e50dee6559899ea07bb9cd03615e"
+ ],
+ "migrations/v0.60.11.0.md": [
+ "1e503113f591c5cd142b78ab4472bbdbceb890c6cbac2fbdf8aa61cd087200b8",
+ "ad3086df4eceff272f08bf16d674be404b97963292729b280f44268c583f77c5"
+ ],
+ "migrations/v0.60.20.0.md": [
+ "9266863a9f76164c64a72b1be17b8ddb3bb97e1c3c5db9f666b69ebc7a228fdd"
+ ],
+ "migrations/v0.60.26.0.md": [
+ "30d761ef5a2361bad66053f97b7b659304a591274be33e281f4f6df0d7d5566e"
+ ],
+ "migrations/v0.60.266.0.md": [
+ "570f58cd3ff0ba759fc034362d3eadcbeaaeb909e34c881145a8fb1dbf881b53"
+ ],
+ "migrations/v0.60.269.0.md": [
+ "9e14518ac62612b01082f8fd92d87f4a93752afa0424790bd6568339dc130f4f"
+ ],
+ "migrations/v0.60.27.0.md": [
+ "1c3ac6a23ccfce8ad299457799b02958f7d21fcd967c471634f73bdb66f2b603"
+ ],
+ "migrations/v0.60.276.0.md": [
+ "de2b4d6fdfe887985ffc1d7ac2e796218ea8fd3bc424a4c80f66f693d7be36d9"
+ ],
+ "migrations/v0.60.28.0.md": [
+ "f7fa936066fb188f6f3f54bb6c720f57743792e4371d0b98dd3cb5a57d1bd9c9"
+ ],
+ "migrations/v0.60.284.0.md": [
+ "f42776fd15f0b8da1132646d671b45e110289e75261b44841f788775d1028ec9"
+ ],
+ "migrations/v0.60.30.0.md": [
+ "2dd24bb319cad80ae15c52fb163c704fc3adfc1182d44ab563f636f07434a9e0"
+ ],
+ "migrations/v0.60.31.0.md": [
+ "0c3f3790ac9d86e4ab7c2373eea7e929ba98800e404191ba2c5bbc1480b6e8ca",
+ "fb8c0a98451a6f7826413ee7463421612511986252f6b803d91a26da94d378bf"
+ ],
+ "migrations/v0.60.36.0.md": [
+ "8ce9aba221d24dec7f354b41c04d59fcbe947e9302a038e87e0ba807086c7ed7"
+ ],
+ "migrations/v0.60.37.0.md": [
+ "e0e9d8ab0adb14cfb55d67f821614f25e0ab2f6281a1a1bfc10faefc95312015"
+ ],
+ "migrations/v0.60.44.0.md": [
+ "415d05b4587e49c7bdad40b55878b0b50f5330915a5e49065638fb6680ced3fe"
+ ],
+ "migrations/v0.60.45.0.md": [
+ "ed92f7b642f1e84e6381ef9e7e855db1ac7d20abd9b79a7bb359c707a04b8b9d"
+ ],
+ "migrations/v0.60.468.0.md": [
+ "ef05fd2ed02b1f1868ba47638dbb142dbb91b2f4253dcc08737bfba6a24440d5"
+ ],
+ "migrations/v0.60.47.0.md": [
+ "91a6015e3b85c6f2c8048680ee5873895ae2b1948bad8ba6cebce679c3ec7085"
+ ],
+ "migrations/v0.60.5.0.md": [
+ "0d3ee19359a2740de08ac9ec388ddc15e7c72d663afe33832e1e54170528acab"
+ ],
+ "migrations/v0.60.52.0.md": [
+ "ae49b2f51ba6288e4883d8bfda9f494f821e160e227164aa065a645d4e9ae87b"
+ ],
+ "migrations/v0.60.53.0.md": [
+ "0c43dffb7926703d024b4dbe6ed84a87b630b587c84b42c84f931f13f9c089cf"
+ ],
+ "migrations/v0.60.57.0.md": [
+ "b97afe1df069b14446a31b41bfd1f24fc76877c13bd2bf55bf6f6371a87e579c"
+ ],
+ "migrations/v0.60.6.0.md": [
+ "1cbfca2c899e1348acbd61f0baa4c8e723b5283ff868c710c74e116c0cb6726e"
+ ],
+ "migrations/v0.60.61.0.md": [
+ "7071a52b954f42d18bcf73e115926ba77025e0fc35640ba84d2eb5d048105af7"
+ ],
+ "migrations/v0.60.62.0.md": [
+ "e91c9b8caee58f6cfa519177ba2b0625b73cf26756a28a451003d78646a5eacf"
+ ],
+ "migrations/v0.60.63.0.md": [
+ "cdc9f862a719bdb76140b5069fb659987978bc2d90498d808bc5d766dbf16891"
+ ],
+ "migrations/v0.60.74.0.md": [
+ "cfd0e9fe6e7d506d60b3673cdb077b52ce292c12e74a81e8cb71c407cc926009"
+ ],
+ "migrations/v0.60.77.0.md": [
+ "3a588974cea1db36a9f063ed056fae155adc5cb54fb606d49f69625e94e15c9d"
+ ],
+ "migrations/v0.60.98.0.md": [
+ "006598c5fc107e1a61510a54e029059183d4f4c0879c2c86640a2988f0b2d33c"
+ ],
+ "migrations/v0.60.99.0.md": [
+ "f56aeec78556eed9cc789ba5cca12c0953c1888368fee0b462cb72581dd8c5a8"
+ ],
+ "migrations/v0.7.0.md": [
+ "97c2740445a10b1c5c7123c17dbd625fa27a94095b85d27c2b278da756c4c59a"
+ ],
+ "migrations/v0.8.0.md": [
+ "1919ff8b8f3680612ff888e7cfcc0d86ece5d5304ae19af4497bdf40b050561a"
+ ],
+ "migrations/v0.8.1.md": [
+ "fad7341cfb5e02545fb8a23221d12ab395fc3d8db15d1d8ee8a18844aea6563a"
+ ],
+ "migrations/v0.9.0.md": [
+ "773fab0a8d7f330576265a3f510c1f318f47789b6136c46d43e08121acbc20eb"
+ ],
+ "migrations/v0.9.1.md": [
+ "75761bad6c0ad37b69ec8197c6a678bb6a1484f9a76e4b70f2d1e86dc80102b3"
+ ],
+ "minion-orchestrator/SKILL.md": [
+ "0b6799dbe6bccc83984371545db0d1d6216d152578d035bb869471cca7ab9b69",
+ "10686e03951d793cbdadfa9111325f05fabf27a4fa0c18894f4857288203dbaa",
+ "5ddeff9bde80ef7fe4990c97220338ffc9ba0d2126eceaed7b4b6a3eb8b0fa18",
+ "63e7ead284ae03f039e5789e1479d9e49d8897cb2cedf1663746c727d86fd3be",
+ "669e23f485561cf6fef16d445dfb8a6d05f76127d0ebf9feb17534af8843df5f",
+ "a0319963481eae87466871b423757d6a82561d241578304de55ed765cb970356",
+ "c6b2dcdb88b31d10242d4d05298d23adbf559bd2c463bbefd9c5a1c87ef928a5",
+ "d770fc3bd3628f536205ca065710b1837d2032a1f50dc5e7b54e1d5f99df5b00"
+ ],
+ "minion-orchestrator/routing-eval.jsonl": [
+ "501ed2e19cb16847ff8425219d246b7a774de1accd42cb28fd44edbb64204992"
+ ],
+ "perplexity-research/SKILL.md": [
+ "1d6cf9f752b4a1618a04789a2f24a7f18d6feaa4ada578515842860bd5869997",
+ "514c4af0ebedec52881f820b5073c52930c63731639f2bb9f0a48b0b9e2cbeee",
+ "800e28faa44abad9c70dc1aff336b8ae1df48645d9ba4a1b210e59750ab244fa",
+ "c25f5c471cbe3c6e0f975d8397e8382b00a85f8aa75302231d53c52855369e97"
+ ],
+ "perplexity-research/routing-eval.jsonl": [
+ "f1a40d87e710d5d2acd602a372d83f46c95da022b6e635228fffeaacb3bb2b27"
+ ],
+ "plugin-exclusions.json": [
+ "585486aaaf9a87ec4b13bea5d03f5e9af34a9ac64283c878c234ba094126f793",
+ "72b1aa20994cab46c5df4837e4b6703ca8fdc94d59ee3ee0e663cf87a19a5554",
+ "797782fd0647e06763febcbe6b8cb6715c717504628af84185cc345804087d35",
+ "e8070da59bb4444304eb354c7421f0998383454d96d5e66e38484aae792c4775"
+ ],
+ "plugin-lanes.json": [
+ "1ee1d2b71e0cabeb859b5018f0235d317cd2532f8d555fc910c6b66a4f8a6958",
+ "2f6b1f232090a3263450254478536007befc04017f7a2253d54479803d29df3e",
+ "40a37629bee4eee7d9836d26417c295846fc4b61b43d4173f11817f1cc0f6563",
+ "52dc5ac59547d4d9993da3d74796bd3e27a3b09752f97ec25451d2fd8a3f71f7",
+ "69281b544e48f55119abd6d89bc32d13ad094b3120e6ed9ef2d13f81f8feccb8",
+ "b3a58f29b033909b982f83173a9044480c344d8132e123225f22c2c108750209",
+ "ec7fc44821c6a9b40c582db9b39026c84677d3fdd94657d983b7c5ea6216124e",
+ "f8285df0d027c6bb9df6922b4cfaef5ad0b217d8850229883c5d7b4639707d4e"
+ ],
+ "postgres-adopt/SKILL.md": [
+ "1b4399fb449e33c24f898ac7ce928a146b9fcc017f5a424475daa9c259c1b961",
+ "44b7d29a135c23184794c82a2330a230fd45ae593d1cd519a75c90de8ad0e2b0",
+ "4c402527bd0d98aa4e7f1a341a25ac0d1bba5e98b3dd55bcc5e30ed2858fa0e0",
+ "8cf801e2e0d29da525a8c4ba275b91e6caffc8aae8e648cbcc8bceaab865c890"
+ ],
+ "postgres-adopt/routing-eval.jsonl": [
+ "db91c1fae408a45082979c402c11eff413277ace6cf746297cc86009dcaefe06"
+ ],
+ "publish/SKILL.md": [
+ "271bd9ba87279429cd934509071dd032b859d59264038c38829c9af46f15c13b",
+ "df87df3ab6c0e799f5dc88edaec7f6b4049c49bbee5525874fe24f1765c3028c",
+ "e06b609db780a3cc93a1755a87b30ff08ffdc0fdbc834c1422b2ad2489b57497"
+ ],
+ "query/SKILL.md": [
+ "1a57297d525f3aa30c7b4aa89d840b2dfad8b7e8ec366761f4338c09d51f056a",
+ "7a5857b4898f2e20cfa2d69c4d24e071978ab38a7471a12d9652da4093f202c1",
+ "7c2eea23d789eeac82afe37ab85557cd92f7be3a409e8cceadc8ce03f448f73d",
+ "8672fb9c9315f01274b1a7d3ad35f903df9705b2e806e2fa4c6add027ecef96f",
+ "8905796d90cae85873cbb9fa6aacba47e51bb0f6037edb72d733981c47f83d3b",
+ "afe2a88394bb78bb651ebd5434415dfa1a96cbc3c52848e134be16b3e8d36f08",
+ "b12aae4e86b893038b1d9e97a977bd6a7939db9f5c57dde12c11d8d7451e0762",
+ "c0259deb9c7402218820c0e7e00b455b804aa93d93c872a31c8468b8397ff12c",
+ "c754d882e7c851d02a221075eda6868987f3a52509eab4c84211dd5472b86da7",
+ "e155a08049984c524b838988ba456d16ccedf162442160f6ba66bfd97cd5208e"
+ ],
+ "query/routing-eval.jsonl": [
+ "74f5a91e52fabc54e0e9403fa17db87ee26bb7ebb8ae8005148c51142abc62fe"
+ ],
+ "remote-mcp/SKILL.md": [
+ "3021054e2b21fa589310181d5140bc6caae5a4d75e3f3aa2cdbddac272cd4873",
+ "753d4df2c6b8c837d00a9c0593028220bdceb1a83b08b29a1d9b973242b789c5",
+ "8eaa2d6511d2eb086e9b66ab252ee60f61aad493f4714b32c6d80b109a488cfd",
+ "d5b7401dba8076a817bc6fcb5c70000638b09b57452b0021feb5e669f0fdf5e2"
+ ],
+ "remote-mcp/routing-eval.jsonl": [
+ "7287693135c9fe2d6495d81d22746ddf41b116254db4b6e683dbdee251e08f8e"
+ ],
+ "repo-architecture/SKILL.md": [
+ "4ec2b8f45d168aaa55f17ecd1ed404ab04217a75c2317f0710c71705846f5394",
+ "9b16948d5d0a953a4446aa03e40014f19da0903990da6fa53a7ea1702b44c4a0",
+ "c57c629d31676ef02f4f42f6dd55dd432e02e0d3a6397aacbbd1037138493763"
+ ],
+ "reports/SKILL.md": [
+ "02b67964afa4543050ea42631ed0a4a0f2946c73541e766bdf6370b6471192d2",
+ "3d3ad45a4ebe82251244f74c98c29f633c1b4b98745ad88fdbc01bd6e43b6dec",
+ "5dc190a0c3a2ee518254e8b596418dbe19ff389ea5ec8c8d30fcb0dfef4d0ed5",
+ "69d39aad7c4b118347c48732d3866883a68903ae57c682d0b46f4dc8ffc74e98",
+ "cdd1e67b264a9b9605291053b24013d3f72f1ca4738e92e4bb8d8226192b7602"
+ ],
+ "reports/routing-eval.jsonl": [
+ "233f891eb8057fc6bb300d914d154300e6a6baf55fe455aba8854d6daa082f2c"
+ ],
+ "research-compendium/SKILL.md": [
+ "3394628692d6722bb73d3c019051f7c6d3f8cf2e8b42ecdfa4c36d2a7e8dbad5",
+ "70abf5032d1554820a913fd5e17f8ddd02148c7a52476d5a2f799c806a27fcb6",
+ "9bc9773a0c559f2cdfbb8cee08ca7d4409a913a60455b2b5dda23d24efa2ad71"
+ ],
+ "research-compendium/routing-eval.jsonl": [
+ "7446cdcaf9c43fe2e20aaf129a705f13a7743f5f14455a7a21c663572def9078"
+ ],
+ "resolve-before-asking/SKILL.md": [
+ "1882c45b2e603bbb1e251d388cc2682270ee7eae99211d5a5322430f4667fb39",
+ "b10843c358069155d42a3e24a5b1893c1ebf7e744d803a6f32edf0e8efb4a482",
+ "ba5aa2ce7bf45116052625eb14fe90f0cc807b4b1490a4646b1cee11b888e897"
+ ],
+ "resolve-before-asking/routing-eval.jsonl": [
+ "bac1bcf30337f5255ef4ce1a2a8a2b38d58ebcd576503c483190c79ec6e69489"
+ ],
+ "schema-author/SKILL.md": [
+ "09d69ee45970191bb2592a764685f67196cabf350db40b4c0c5ffc19ea9e2df3",
+ "1a4ba83bfcd4739e801977deabe1a677980011a51c13d802731bdd76090d6d59",
+ "1dd11a44dabcb7d57244be4cf5f4903feb9d146bcbb4363fc150daefc01d04ce",
+ "38efb8b48399a2dc526d7084579aa265b2ab232882605bc2f86f6ba2869619f5",
+ "4ac1c8fd08800f3728ec55cdc98e97a5aa618a26b753a0fb38c0df9624b66e06",
+ "4da9a472c966f8e4fb43d97a3a3608c67ec3d43da6b8c626ee0c30a4e70da26f",
+ "549d7d14ae3efd3f9a6189850bf30ecc9911f61a92d2d8e9ff1d52a99dc765fa",
+ "dac2243d9075818f3b03fa4cd8836e57e75f329852a3d9a7369e77a3b1bd3973"
+ ],
+ "schema-unify/SKILL.md": [
+ "03585d2155f43eedcf5f6e006785ee9f0142a8ae1a088c5e6456ecac675dc24d",
+ "14ddc0f8bc7d8b11eb03dc4eb35621d140fba71bd35779835d85e297acfb0177",
+ "2a34bd8c85c378531e0aa637d37fd971c67a2377b8e36d7a65c969376615d951",
+ "31227b5a9d90e0f1482b52cfd6d23a71575cdbc36f2edcfa8f0170bfb7b95467",
+ "36259f1510fd693253535bd203e32db1bfa24aaae7278c7a2e8b7d6859022708",
+ "e1d50a54a6ff29434d38a841a572e815d236a8167d459609ae697e548770f500",
+ "e9ac84018d673d35f749a1f74380d635512308fa50951995a7cb339ab4c85fa6"
+ ],
+ "setup/SKILL.md": [
+ "03216a34292ccc44984bca614d5dcf5f2afd1d762a0222c603dd2bc67f047a22",
+ "322faf7099afd71f9add0f6dbe4d2bf9686df54c521a29e018f4ab25608e3dc0",
+ "4a47a5f6ee99ac8a2649a304abb261fd34810cf6185fd7d6a53e1b6c4cbc0764",
+ "4e8830f839472359a72a65fbd2a8b53f7c7fdc3823ad0049c5201a6f6480b006",
+ "68dde0de48bb4c93b13d9e19c3a20ff82155985ad09f509669aff8ece0a6f4fb",
+ "7f11b70ed89d4bff87096aa7e7bb0d41191eb46682066f3b2cffa7a326b56330",
+ "90494ad4128b975867e33b419fe3d512eef775bfbb011590b55b20106372aba4",
+ "a0f9d72565b489c4a60f6546b89218ea9efc307b397ac5ea22f3ed4c737f73f1",
+ "b73d9f9c93d419d812b39e47160790f8510bcd8564910b9f02aee51e673ad41f",
+ "c82b1e1b97e058991bc52287c24a26628d7d66bed409642023a20457e7f15f05",
+ "d6b82f858e60699ff8c5ee82d61c94a98c2fbc7a852b5f74571e7ab3f0921139",
+ "f014513080eb81e90f0cc0203ca944698fdff250059be0267f0498c5b69c5416"
+ ],
+ "signal-detector/SKILL.md": [
+ "0ffa92ceee026f8ce1fa6fbea45dc8ebe9689a36d13683ec102c33402a50898a",
+ "3f13bfe7e041804b5225763ff667ca406bcbe58deff26d299cf0670fa44ad5f7",
+ "426a8a3b01a007dd25638e61adef510c18c3d9ce6f1c18ba3d77fdfcd3281d60",
+ "64e4547f5a8624c53d875001b423d240ec73ee9fd026a96c7b799d287c5fb6e4",
+ "c85772f129b3a5b5b0edfa191e11b1048942e52b7472bbaea224e7188f8af75a",
+ "ea090be2fedeb528c3b3a4b3c649abd3ff07b3ecdc6266bf2930364537683489"
+ ],
+ "skill-autobench/SKILL.md": [
+ "144572ec76f3784a97645dfde587ab13d77e804f50b00dc7fbe678204de6ff21",
+ "29f5760dcfd823c5f7d4fb50a3cf4e36601b1b8125e57d6bf83645a41f97f613",
+ "87126caac05eaae32c360ae304eb6e8e27bf9160935fe44c1951c99621ec28bc"
+ ],
+ "skill-autobench/routing-eval.jsonl": [
+ "8d961ed6403b7e2f690948e4c18529d40f26f6f21064befc56d465966b1a9ec0"
+ ],
+ "skill-budgets.tsv": [
+ "917ac319b38596369396c3cf98d75c8eed1d6fb2d339bb3cc1084e61cac1ffe0"
+ ],
+ "skill-creator/SKILL.md": [
+ "06fa8391d3be4fed2da7344677bd798786dda114fbdf8c676f0b77f4f0756f38",
+ "4a11f8935d4214b21b4664a5c0c03149733731020ec0d5d09dc9fd8c40bd92f6",
+ "6e3674adc864661b356f624ed0886a773205cfac25cdb111684581d2db0b56be",
+ "ae8119e6a28faacdc48b13a51c89ff752e9d1b698a4ed0b49f380eb1de16e322"
+ ],
+ "skill-optimizer/SKILL.md": [
+ "1dea9a5257a60fb29a4c7701c92bce428025fb2321e950533f1367edfca1b8b0",
+ "ba3028c7351dec3e644a7114e08e59cae7c60dc367dc4fd10560265a162baa90",
+ "bc5b4c7058728d7826e2241b4f2cd441f274dfa1dfb5232ac220305939081bb9",
+ "cbff060823adc0b820c05c50de6701ba2ff201403f602e97a3fb18fe4e1529af"
+ ],
+ "skill-optimizer/routing-eval.jsonl": [
+ "48f7fc04414b194ee8674577c3e58e03ebd7f74d836766bd16cb5abfd4effb76"
+ ],
+ "skill-optimizer/skillopt-benchmark.jsonl": [
+ "5552457d6eaa32486b79796d12fcbe2c078b0c53d7fbdaf582f0fd1a17e9a381"
+ ],
+ "skillify/SKILL.md": [
+ "3c7e87e80b5dd472e27ff89ec19b5919efb3d378a70e401451d8ca2510e6907f",
+ "42ac7de06791b8a21ae590a2b6a166fec6be4ff0b60cd9ab38f48134e8405486",
+ "6fa84bd744b1082d6550def977b49ecaac7ada0abf1a04180a8e3b0d432fb20e",
+ "a154e43409458136e1e1cea084aa973e4cf46cd8450c6be8e9891a4a3ddf6146",
+ "d7cf802c7291642dacf922f3557f7e4c258f471c6dcf8feea1460710539ea263",
+ "dca5c9d56bc81a5358e1c372939793033f77d5fed49d9572cbea83fe95d4d833"
+ ],
+ "skillify/routing-eval.jsonl": [
+ "c0a55ee371bb7a797c76d58cf211407a667930673e34e945e09047470cdfd2f4"
+ ],
+ "skillpack-check/SKILL.md": [
+ "3f347ec8b498530a662be212d05f4cd06b205bce5795c2231b6a4cecef149ea0",
+ "69ca2fecdbc60330569fa5d6eea794cd4a9d351155f8dad5588d992dea3a6dae",
+ "bcb96d0d231827c9fcd47865f63aaef70c9b9f7a7402464594f24f5fe1eeff8c",
+ "cb045e20a60b22774578e86f57872181a3cda73e5861add7e5750dc4de65c1fb",
+ "cca107c50e5271ae48496172067fb604e03a7e01769cc638fa04550b0e87df10"
+ ],
+ "skillpack-harvest/SKILL.md": [
+ "0f86314b58d25b5511809f567c04aedc3fba6fe35ed642ac52d8216ae365b6eb",
+ "3c4c591b33f03a5ccf11ca0ddde56b54fba541efef0d590b6d435687733182d7",
+ "56949a545120d68fe9cc31f6212282f95d73139cd6d95654aaf6bc6abd6b9964",
+ "775133021077f49e6b9da0cf1eafa8df87a9f311b946063db572273effb6dd15"
+ ],
+ "skillpack-harvest/routing-eval.jsonl": [
+ "cb4783288e95af3132b32ecb40a54cffc095f57b36240f96a25c2d2adf5e68c6"
+ ],
+ "smoke-test/SKILL.md": [
+ "09b288a47cff1fc749e430f3d29cbe71d3de31c2184974d04d4fb7151c45b674",
+ "3e1b0c180d405703da4945ff5a6cb357e1d46e2e6f7a6773a1d85bfbf773f69b",
+ "918333adb19f0fb1369a16e2d746c51a500392e95158538aa729106c720aef54",
+ "be2ff40493d5c9c518eb6ba3ab5cfb7803348ea17fff1d27bde29a0b78c68634",
+ "f2f2172d41e63e288095451132a0c56848ccc34101d265b330b6cf00e5769f5d",
+ "f5099e1d2ab9dc6827096249e68414f7ae357c29b39fb069a54bb7fb74f414a5"
+ ],
+ "soul-audit/SKILL.md": [
+ "14d29a78f958f341313a4b957c2a8d124a9b92fbd140d3618709a0c7122f48e0",
+ "2788c112775be2d69c94004da88db709b775057c640b68204887719d48424e4c",
+ "5a1d17b3190f75e85c6a8e4afe696a0ae8a3116bb60ad36ca2e350f1598b53d7",
+ "7a48e180849f7502d332878c443397f90a3756f45caa94f76bcfcc7c997469c8",
+ "7f162dddcc511e97a24db3a46136295fcbda76023019ad8994546744d7b8eb0a"
+ ],
+ "strategic-reading/SKILL.md": [
+ "5be656c39c830153ec7c2f328dc8bdeac05c1412b01b3415de6b5b008926e7a2",
+ "ab2cd3adc79289374cfbc5cb3d5ee17f962fd8f7f3c997a1da708da0ed67797c",
+ "befb563bbf07d8ea8c0070fef2cf0b50b9a994f49b47ffaf56d2c6aa36c4b60e"
+ ],
+ "strategic-reading/routing-eval.jsonl": [
+ "eb0fc239c93aac53cf7d856190967bb65eaf970b4fe8bd0aad1c87495fbb8ccd"
+ ],
+ "testing/SKILL.md": [
+ "c69fe3456aa981bbcfe06c7633042eabf68617c69e9c26c00e47a0848fd90fb3",
+ "f1846ba7c35076d910744a6b867c9ee850c1895f75a104a319c9b7d18b1d5e90",
+ "fdf7d9c2d9dedfdf3581d82dd377fddb7c61a54aa0328cf26b529ab2eb76fff3"
+ ],
+ "two-tier-extraction/SKILL.md": [
+ "238e622580e0aa33523325ce2914ca5313b9d85bcbee73d00fb01357702ce884",
+ "811950a44897cc8db369609ac35059121800d106c6942e9f934c89a530431299",
+ "b1cf8000cb587a0f3dc9d17f42c83f9a038a7be8065ee628c81e75a3e597d043"
+ ],
+ "two-tier-extraction/routing-eval.jsonl": [
+ "b6af30ccd4ad20b60c229d3d63b50445f659d98f67b680e6d473a1e1ca020d90"
+ ],
+ "voice-note-ingest/SKILL.md": [
+ "145c02e636430abba5648e026aef77606d6ba2594285fbfee4f4dd4253cf833a",
+ "57087b58b514225a7c9ef58bfc69439022dadb01c6b2c778b042d5ddb568c738",
+ "da09a82cdea92e8407a9dff946f2e25bb3ccbd433d767ea38f275e087457086d"
+ ],
+ "voice-note-ingest/routing-eval.jsonl": [
+ "374aaec16fbde336d1e376edce89e51adc4ecaa93c13fb4a69b967ba299b8742"
+ ],
+ "webhook-transforms/SKILL.md": [
+ "39d3f4e21de6a899652a26fd051ae19d55cc70a8c868f251834f5fa6a8322a74",
+ "b774293297af4d513c7efa92a79cf65b8438a714adafc16802b492613e679d17",
+ "b847f14f3674b29d3e1a4e3792926829e17f0e2f01fbc53a52ad3869f856b310"
+ ]
+ }
+}
diff --git a/skills/skills.lock.json b/skills/skills.lock.json
index 071beda08b..d44117b912 100644
--- a/skills/skills.lock.json
+++ b/skills/skills.lock.json
@@ -1,6 +1,6 @@
{
"RESOLVER.md": "d788b96fae6731a9bad8586074e40d6b22d360f5b5a7f7a85cea0ef3bb46cf2d",
- "_AGENT_README.md": "ab51e36e9a0b53f4d0609294b0556444399147834932d9c1acfdc7aa367c70b8",
+ "_AGENT_README.md": "ce694f4d952cd4ac1377b4f68a63b93f616d2fce745d76a399f1633805c83244",
"_brain-filing-rules.json": "4e6ecee2d94867d146583d60bf98dccdd9205bb70793af56fe1397a2b258ae0d",
"_brain-filing-rules.md": "ff42b331bce542d708f97ff0a73ff0fb5664b46ee9b1862a5478b15dc637487e",
"_friction-protocol.md": "51353207240142024ff1facc25f225712275ecdb4a034ffffdd83740c8d328e3",
@@ -225,6 +225,7 @@
"skillpack-check/SKILL.md": "bcb96d0d231827c9fcd47865f63aaef70c9b9f7a7402464594f24f5fe1eeff8c",
"skillpack-harvest/SKILL.md": "0f86314b58d25b5511809f567c04aedc3fba6fe35ed642ac52d8216ae365b6eb",
"skillpack-harvest/routing-eval.jsonl": "cb4783288e95af3132b32ecb40a54cffc095f57b36240f96a25c2d2adf5e68c6",
+ "skills.lock.history.json": "ffc3adac7c32b2538686487a79bbc537dbe1a01b7fbb0a1dbfee0d84e1dbdd10",
"smoke-test/SKILL.md": "f5099e1d2ab9dc6827096249e68414f7ae357c29b39fb069a54bb7fb74f414a5",
"soul-audit/SKILL.md": "7a48e180849f7502d332878c443397f90a3756f45caa94f76bcfcc7c997469c8",
"strategic-reading/SKILL.md": "ab2cd3adc79289374cfbc5cb3d5ee17f962fd8f7f3c997a1da708da0ed67797c",
diff --git a/src/cli/flag-equals.ts b/src/cli/flag-equals.ts
index 5bc6513770..ccae097ed9 100644
--- a/src/cli/flag-equals.ts
+++ b/src/cli/flag-equals.ts
@@ -190,7 +190,7 @@ export const EQUALS_READERS: Readonly<Record<string, readonly string[]>> = {
'skillpack diff': ['--workspace', '--skills-dir'],
// skillpack/scaffold.ts:36 lane select + :73 --workspace=; harness lane skillpack/harness.ts:91-158 parseHarnessArgs (:364).
'skillpack scaffold': ['--workspace', '--harness', '--persona', '--skill', '--dest', '--scope', '--skills'],
- // skillpack/reference.ts:44 harness lane (strict-args.ts:102 makes the non-harness lane STRICT); harness.ts:542.
+ // skillpack/reference.ts:44 harness lane (strict-args.ts:102 makes the non-harness lane STRICT); harness.ts:542; skillpack/update.ts readValue (--update-untouched lane).
'skillpack reference': ['--harness', '--persona', '--skill', '--dest', '--scope', '--workspace', '--skills'],
// core/bounded-listing-cli.ts:15 via sources.ts:1213 runStatus (+ :1214 paged regex).
'sources status': ['--limit', '--cursor'],
diff --git a/src/cli/strict-args.ts b/src/cli/strict-args.ts
index 0e4e82de9d..c771fcd2cc 100644
--- a/src/cli/strict-args.ts
+++ b/src/cli/strict-args.ts
@@ -96,7 +96,7 @@ export const STRICT_SUBCOMMANDS: Readonly<Record<string, StrictSpec>> = {
*/
export const STRICT_SELF_HELP_SUBCOMMANDS: Readonly<Record<string, StrictSpec>> = {
'skillpack reference': {
- flags: ['--all', '--apply-clean-hunks', '--dry-run', '--json'],
+ flags: ['--all', '--apply-clean-hunks', '--dry-run', '--json', '--update-untouched', '--no-diff', '--accept-historical', '--fail-on-skipped'],
values: { '--workspace': null, '--since': null },
maxPositionals: 1,
when: args => !args.some(a => a === '--harness' || a.startsWith('--harness=')),
diff --git a/src/commands/doctor/checks/skillpack-update.ts b/src/commands/doctor/checks/skillpack-update.ts
new file mode 100644
index 0000000000..675f643424
--- /dev/null
+++ b/src/commands/doctor/checks/skillpack-update.ts
@@ -0,0 +1,65 @@
+/**
+ * Skillpack update journals (`gbrain skillpack reference --update-untouched`):
+ * - skillpack_update_incomplete (warn): a journal a crash left `pending`,
+ * with the restore command. A pending journal whose workspace writer lock
+ * is fresh belongs to a run still going and is not reported.
+ * - skillpack_backups (ok): how many update backups are kept.
+ * Filesystem only (~/.gbrain/skillpack-backups), so it runs with or without
+ * an engine and on brains with no git repository. Emits nothing when there
+ * are no backups.
+ */
+import { statSync } from 'fs';
+
+import { workspaceLockPath } from '../../../core/skillpack/file-lock.ts';
+import { JOURNAL_KEEP_DAYS, JOURNAL_KEEP_LAST, listJournals, type Journal } from '../../../core/skillpack/update-journal.ts';
+import type { Check } from '../../doctor.ts';
+import { agentFix } from '../check-fix.ts';
+import type { DoctorContext, DoctorEntry } from '../context.ts';
+
+const LIVE_LOCK_MS = 10 * 60 * 1000;
+
+function runIsLive(skillsRoot: string): boolean {
+ try {
+ return Date.now() - statSync(workspaceLockPath(skillsRoot)).mtimeMs < LIVE_LOCK_MS;
+ } catch {
+ return false;
+ }
+}
+
+/** `backups` overrides ~/.gbrain/skillpack-backups (tests). */
+export async function runSkillpackUpdateChecks(_ctx?: DoctorContext, backups?: string): Promise<Check[]> {
+ const checks: Check[] = [];
+ let journals: Journal[];
+ try {
+ journals = listJournals(backups);
+ } catch (err) {
+ checks.push({ name: 'skillpack_update_incomplete', status: 'warn', message: `Skillpack update backups could not be read: ${(err as Error).message}. Health is unknown.` });
+ return checks;
+ }
+ if (journals.length === 0) return checks;
+ const pending = journals.filter(j => j.status === 'pending' && !runIsLive(j.skills_root));
+ if (pending.length) {
+ checks.push({
+ name: 'skillpack_update_incomplete',
+ status: 'warn',
+ message: `${pending.length} skillpack update(s) did not finish (a crash left the journal pending): `
+ + pending.map(j => `${j.id} (${j.skills_root}; mid-apply: ${j.skills.filter(s => s.status === 'applying').map(s => s.slug).join(', ') || 'none'})`).join('; ')
+ + `. New updates of that skills root refuse until it is restored: gbrain skillpack restore ${pending[0]!.id}.`,
+ fix: agentFix(['gbrain', 'skillpack', 'restore', '--list', '--json'],
+ 'Lists the pending journal and the files each skill touched; changes nothing. The restore itself refuses files changed since the update.', 'skillpack_update_incomplete'),
+ details: { pending: pending.map(j => ({ id: j.id, skills_root: j.skills_root, restore: `gbrain skillpack restore ${j.id}` })) },
+ });
+ }
+ checks.push({
+ name: 'skillpack_backups',
+ status: 'ok',
+ message: `${journals.length} skillpack update backup(s) kept (oldest ${journals[journals.length - 1]!.id}); each is kept ${JOURNAL_KEEP_DAYS} days or while among the newest ${JOURNAL_KEEP_LAST}. List them with gbrain skillpack restore --list.`,
+ });
+ return checks;
+}
+
+export const skillpackUpdateEntry: DoctorEntry = {
+ name: 'skillpack_update_incomplete',
+ emits: ['skillpack_update_incomplete', 'skillpack_backups'],
+ run: runSkillpackUpdateChecks,
+};
diff --git a/src/commands/doctor/registry.ts b/src/commands/doctor/registry.ts
index 9cda613b88..642b62f8eb 100644
--- a/src/commands/doctor/registry.ts
+++ b/src/commands/doctor/registry.ts
@@ -27,6 +27,7 @@ import {
minionsMigrationEntry,
} from './checks/local-runtime.ts';
import { supervisorEntry } from './checks/supervisor-health.ts';
+import { skillpackUpdateEntry } from './checks/skillpack-update.ts';
import {
stubGuardEntry,
extractionBacklogsEntry,
@@ -169,6 +170,7 @@ export const DOCTOR_CHECK_REGISTRY: readonly DoctorEntry[] = [
resolverHealthEntry,
retrievalReflexEntry,
skillConformanceEntry,
+ skillpackUpdateEntry,
bootstrapChecksEntry,
memorableRelayEntry,
connectorsEntry,
diff --git a/src/commands/skillpack.ts b/src/commands/skillpack.ts
index b0ef6e65ff..440b8f6bb0 100644
--- a/src/commands/skillpack.ts
+++ b/src/commands/skillpack.ts
@@ -33,6 +33,7 @@ import { parsePrecondition, type Precondition } from '../core/skillpack/precondi
import { resolveAbs, findGbrainOrDie, resolveWorkspace } from './skillpack/shared.ts';
import { cmdScaffold } from './skillpack/scaffold.ts';
import { cmdReference } from './skillpack/reference.ts';
+import { recordScaffoldBases, type ScaffoldedFile } from '../core/skillpack/safe-update.ts';
const HELP_TOP = `gbrain skillpack <subcommand> [options]
@@ -55,6 +56,11 @@ Subcommands:
Two-way diff, auto-apply non-conflicting hunks.
reference --harness <h> Diff a harness install (stub-aware; splits
local_edit vs upstream_drift).
+ reference <n>|--all --update-untouched
+ Replace whole skills you never edited with
+ gbrain's version (journaled; --dry-run previews).
+ pin <name> / unpin <name> Keep a skill out of --update-untouched.
+ restore <id> | --list Undo an --update-untouched run.
remove --harness <h> Remove files the harness bridge wrote (ledger-
owned only — never your own files).
@@ -124,6 +130,17 @@ export async function runSkillpack(args: string[]): Promise<void> {
case 'reference':
await cmdReference(rest);
return;
+ case 'pin':
+ case 'unpin': {
+ const { cmdPin } = await import('./skillpack/update.ts');
+ await cmdPin(rest, sub === 'pin');
+ return;
+ }
+ case 'restore': {
+ const { cmdRestore } = await import('./skillpack/update.ts');
+ await cmdRestore(rest);
+ return;
+ }
case 'status':
await cmdStatus(rest);
return;
@@ -396,12 +413,15 @@ async function cmdSync(args: string[]): Promise<void> {
// file by design, so drifted/current files are never touched — the
// ownership model. In --dry-run nothing is written.
const scaffolded: string[] = [];
+ const scaffoldedFiles: ScaffoldedFile[] = [];
for (const slug of newSlugs) {
- runScaffold({ gbrainRoot, targetWorkspace, skillSlug: slug, dryRun });
+ scaffoldedFiles.push(...runScaffold({ gbrainRoot, targetWorkspace, skillSlug: slug, dryRun }).files);
scaffolded.push(slug);
}
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- targetWorkspace is the local operator's --workspace argument or the auto-detected workspace root, the same root runScaffold just wrote under.
const registered = dryRun ? [] : registerManifestEntries(join(targetWorkspace, 'skills'), scaffolded);
+ // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- the same operator workspace root runScaffold just wrote under.
+ if (!dryRun) await recordScaffoldBases(join(targetWorkspace, 'skills'), scaffoldedFiles);
if (json) {
console.log(JSON.stringify({ scaffolded, registered, drifted: driftedSlugs, dryRun }, null, 2));
diff --git a/src/commands/skillpack/harness.ts b/src/commands/skillpack/harness.ts
index f80dc4940a..d8db14ecbb 100644
--- a/src/commands/skillpack/harness.ts
+++ b/src/commands/skillpack/harness.ts
@@ -21,6 +21,7 @@ import { join } from 'path';
import type { BrainEngine } from '../../core/engine.ts';
import { loadConfig } from '../../core/config.ts';
import { VERSION } from '../../version.ts';
+import { recordScaffoldBases } from '../../core/skillpack/safe-update.ts';
import { autoDetectSkillsDir } from '../../core/repo-root.ts';
import {
claudeProjectSkillsDir,
@@ -416,6 +417,8 @@ export async function cmdScaffoldHarness(args: string[]): Promise<void> {
...(useFullBundle ? {} : { skillSlugs: deliverable }),
dryRun: a.dryRun,
});
+ // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- the operator's own workspace root, where runScaffold just wrote.
+ if (!a.dryRun) await recordScaffoldBases(join(targetWorkspace, 'skills'), result.files);
if (a.json) {
console.log(
JSON.stringify(
@@ -461,6 +464,7 @@ export async function cmdScaffoldHarness(args: string[]): Promise<void> {
dryRun: a.dryRun,
nowIso: new Date().toISOString(),
});
+ if (!result.dryRun) await recordScaffoldBases(dest, result.files.filter(file => file.slug !== null));
// Coexistence: these same skills may also load from the gbrain plugin
// snapshot (marketplace install) — duplicate names in one session.
diff --git a/src/commands/skillpack/reference.ts b/src/commands/skillpack/reference.ts
index 159fe587eb..34257beda3 100644
--- a/src/commands/skillpack/reference.ts
+++ b/src/commands/skillpack/reference.ts
@@ -19,8 +19,11 @@ import { exitCliError } from '../../cli/cli-error.ts';
const REFERENCE_HELP =
'gbrain skillpack reference <name> [--workspace PATH] [--apply-clean-hunks [--dry-run]] [--json]\n' +
- 'gbrain skillpack reference --all [--workspace PATH] [--since <version>] [--json]\n\n' +
+ 'gbrain skillpack reference --all [--workspace PATH] [--since <version>] [--json]\n' +
+ 'gbrain skillpack reference <name>|--all --update-untouched [--dry-run] ... (see --update-untouched --help)\n\n' +
' <name> Read-only diff of gbrain\'s bundle against your local copy.\n' +
+ ' --update-untouched Replace whole skills you never edited with gbrain\'s version,\n' +
+ ' journaled and restorable (gbrain skillpack restore <id>).\n' +
' --apply-clean-hunks Two-way merge: align non-conflicting hunks of ONE skill to\n' +
' gbrain. Local edits in those hunks are overwritten; pass the\n' +
' exact --dry-run flag to preview without writing.\n' +
@@ -39,6 +42,12 @@ const ALL_APPLY_REFUSAL =
' 3. gbrain skillpack reference <name> --apply-clean-hunks (add --dry-run to preview first)';
export async function cmdReference(args: string[]): Promise<void> {
+ // Safe whole-skill update of untouched installs (its own help, flags and exit codes).
+ if (args.includes('--update-untouched')) {
+ const { cmdUpdateUntouched } = await import('./update.ts');
+ await cmdUpdateUntouched(args);
+ return;
+ }
// Harness lane (cathedral-7): diff a harness install (stub-aware,
// three-way local_edit vs upstream_drift) instead of a workspace.
if (args.some(a => a === '--harness' || a.startsWith('--harness='))) {
diff --git a/src/commands/skillpack/scaffold.ts b/src/commands/skillpack/scaffold.ts
index 4fdba5409d..a4407b2a3a 100644
--- a/src/commands/skillpack/scaffold.ts
+++ b/src/commands/skillpack/scaffold.ts
@@ -16,6 +16,7 @@ import {
BundleError,
} from '../../core/skillpack/bundle.ts';
import { runScaffold, ScaffoldError } from '../../core/skillpack/scaffold.ts';
+import { recordScaffoldBases } from '../../core/skillpack/safe-update.ts';
import {
RemoteSourceError,
classifySpec,
@@ -137,6 +138,8 @@ export async function cmdScaffold(args: string[]): Promise<void> {
skillSlug: all ? null : name!,
dryRun,
});
+ // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- targetWorkspace is the local operator's own workspace root, the same root runScaffold just wrote under.
+ if (!dryRun) await recordScaffoldBases(join(targetWorkspace, 'skills'), result.files);
if (json) {
console.log(JSON.stringify({ ok: true, dryRun: result.dryRun, summary: result.summary, files: result.files }, null, 2));
} else {
diff --git a/src/commands/skillpack/update.ts b/src/commands/skillpack/update.ts
new file mode 100644
index 0000000000..e640632a45
--- /dev/null
+++ b/src/commands/skillpack/update.ts
@@ -0,0 +1,208 @@
+/**
+ * `gbrain skillpack reference <name>|--all --update-untouched`, `skillpack pin|unpin`
+ * and `skillpack restore` — the safe-update lane (core: src/core/skillpack/safe-update.ts).
+ *
+ * Never prompts: `--dry-run` is the preview. Exit 0 when nothing failed
+ * (skips are in the summary and JSON), 1 only with --fail-on-skipped when
+ * something was skipped, 2 on a failure (files touched and the restore
+ * command are printed). Flag-registry note: this file is scanned for
+ * skillpack's flag allowlist — spell foreign CLI flags without dashes here.
+ */
+import { join } from 'path';
+
+import { BundleError, bundledSkillSlugs, loadBundleManifest } from '../../core/skillpack/bundle.ts';
+import { acquireFileLock, workspaceLockPath, type FileLock } from '../../core/skillpack/file-lock.ts';
+import {
+ runSkillpackRestore, runSkillpackUpdate, setSkillPinned, skillsRootKey, type UpdateResult,
+} from '../../core/skillpack/safe-update.ts';
+import { listJournals, readJournal } from '../../core/skillpack/update-journal.ts';
+import { exitCliError } from '../../cli/cli-error.ts';
+import { findGbrainOrDie, resolveWorkspace } from './shared.ts';
+
+export const UPDATE_HELP =
+ 'gbrain skillpack reference <name>|--all --update-untouched [--workspace PATH] [--dry-run] [--json]\n' +
+ ' [--no-diff] [--accept-historical] [--fail-on-skipped]\n\n' +
+ 'Take gbrain\'s current version of installed skills you never edited, one whole\n' +
+ 'skill at a time. A skill updates only when every file still matches the hash\n' +
+ 'recorded at install (or, with --accept-historical, a released version when\n' +
+ 'no hash was recorded) and the skill is not pinned. Anything else\n' +
+ 'is skipped with a reason and a diff. Never prompts; --dry-run is the preview.\n' +
+ 'Every update is journaled under ~/.gbrain/skillpack-backups/<id>/ and can be\n' +
+ 'undone with gbrain skillpack restore <id>.\n\n' +
+ 'Exit: 0 nothing failed; 1 with --fail-on-skipped when a skill was skipped;\n' +
+ '2 a skill failed and was rolled back (files touched and restore command printed).';
+
+function workspaceSkillsRoot(workspace: string | null): string {
+ return skillsRootKey(join(resolveWorkspace({ workspace }), 'skills'));
+}
+
+function readValue(args: string[], flag: string): string | null {
+ for (let i = 0; i < args.length; i++) {
+ if (args[i] === flag) return args[i + 1] ?? null;
+ if (args[i]?.startsWith(`${flag}=`)) return args[i]!.slice(flag.length + 1) || null;
+ }
+ return null;
+}
+
+function positionals(args: string[], valueFlags: string[]): string[] {
+ const out: string[] = [];
+ for (let i = 0; i < args.length; i++) {
+ const a = args[i]!;
+ if (valueFlags.includes(a)) i++;
+ else if (!a.startsWith('-')) out.push(a);
+ }
+ return out;
+}
+
+function printUpdate(result: UpdateResult): void {
+ const verb = result.dry_run ? 'skillpack update-untouched (dry run)' : 'skillpack update-untouched';
+ console.log(`${verb}: ${result.skills_root}`);
+ if (!result.history.verified) console.log(` history UNVERIFIED (${result.history.reason}): whole-file updates are disabled (history_unverified)`);
+ for (const id of result.pending_journals) console.log(` an earlier update did not finish: gbrain skillpack restore ${id}`);
+ for (const s of result.skills) {
+ if (s.result === 'current' || s.result === 'not_installed') continue;
+ const detail = s.result === 'skipped' ? s.reason : s.result === 'failed' ? s.failure : `${s.changes.length} file(s)`;
+ console.log(` ${s.result.padEnd(13)} ${s.slug.padEnd(32)} ${detail}`);
+ for (const note of s.notes) console.log(` note: ${note}`);
+ }
+ const c = result.summary;
+ console.log(`updated: ${c.updated} would update: ${c.would_update} skipped: ${c.skipped} failed: ${c.failed} current: ${c.current} not installed: ${c.not_installed}`);
+ const historical = result.skills.filter(s => s.historical.length > 0);
+ if (historical.length) {
+ console.log('\nMatch only a released version (no recorded base; take them with --accept-historical):');
+ for (const s of historical) console.log(` ${s.slug}: ${s.historical.join(', ')}`);
+ }
+ const diffs = result.skills.filter(s => s.diffs?.length);
+ if (diffs.length) {
+ console.log('\nSkipped skills, your copy (a/) against gbrain\'s (b/); first 200 lines per file, secret-looking values redacted.');
+ console.log('Merge by hand what you want; gbrain skillpack reference <name> shows the full diff.');
+ for (const s of diffs) for (const d of s.diffs!) console.log(`\n${d.diff}`);
+ }
+ const failed = result.skills.filter(s => s.result === 'failed');
+ if (failed.length) {
+ console.log('\nFailed (rolled back):');
+ for (const s of failed) {
+ console.log(` ${s.slug}: ${s.failure}`);
+ if (s.touched?.length) console.log(` files touched: ${s.touched.join(', ')}`);
+ if (s.rollback_skipped?.length) console.log(` left as changed since the update: ${s.rollback_skipped.join(', ')}`);
+ }
+ console.log(`Undo everything this run applied: ${result.restore_command}`);
+ }
+}
+
+export async function cmdUpdateUntouched(args: string[]): Promise<void> {
+ if (args.includes('--help') || args.includes('-h')) {
+ console.log(UPDATE_HELP);
+ process.exit(0);
+ }
+ for (const bad of ['--apply-clean-hunks', '--since', '--harness']) {
+ if (args.some(a => a === bad || a.startsWith(`${bad}=`))) {
+ console.error(`Error: --update-untouched does not combine with ${bad}. Run gbrain skillpack reference --help for the read-only lens.`);
+ process.exit(2);
+ }
+ }
+ const all = args.includes('--all');
+ const names = positionals(args, ['--workspace']);
+ if (all === names.length > 0) {
+ console.error('Error: pass one skill name or --all.');
+ process.exit(2);
+ }
+ const json = args.includes('--json');
+ const gbrainRoot = findGbrainOrDie();
+ const skillsRoot = workspaceSkillsRoot(readValue(args, '--workspace'));
+ let lock: FileLock | null = null;
+ let result: UpdateResult;
+ try {
+ lock = await acquireFileLock(workspaceLockPath(skillsRoot), { code: 'skillpack_workspace_locked' });
+ result = await runSkillpackUpdate({
+ gbrainRoot, skillsRoot, slugs: all ? null : names,
+ dryRun: args.includes('--dry-run'), acceptHistorical: args.includes('--accept-historical'), noDiff: args.includes('--no-diff'),
+ });
+ } catch (err) {
+ lock?.release();
+ if (err instanceof BundleError) {
+ console.error(`skillpack reference --update-untouched: ${err.message}`);
+ process.exit(2);
+ }
+ exitCliError(err, 'skillpack');
+ }
+ lock!.release();
+ if (json) console.log(JSON.stringify({ ...result!, skills: result!.skills.map(({ files: _files, ...s }) => s) }, null, 2));
+ else printUpdate(result!);
+ if (result!.summary.failed > 0) process.exit(2);
+ process.exit(args.includes('--fail-on-skipped') && result!.summary.skipped > 0 ? 1 : 0);
+}
+
+export async function cmdPin(args: string[], pinned: boolean): Promise<void> {
+ const sub = pinned ? 'pin' : 'unpin';
+ if (args.includes('--help') || args.includes('-h')) {
+ console.log(`gbrain skillpack ${sub} <skill> [--workspace PATH] [--json]\n\n` +
+ (pinned ? 'Pin an installed skill: --update-untouched never updates it.' : 'Unpin a skill so --update-untouched may update it again.'));
+ process.exit(0);
+ }
+ const [slug, extra] = positionals(args, ['--workspace']);
+ if (!slug || extra) {
+ console.error(`Error: gbrain skillpack ${sub} takes exactly one skill name.`);
+ process.exit(2);
+ }
+ const gbrainRoot = findGbrainOrDie();
+ if (!bundledSkillSlugs(loadBundleManifest(gbrainRoot)).includes(slug)) {
+ console.error(`Error: '${slug}' is not a bundled skill (gbrain skillpack list shows them).`);
+ process.exit(2);
+ }
+ const skillsRoot = workspaceSkillsRoot(readValue(args, '--workspace'));
+ let changed: boolean;
+ try {
+ changed = await setSkillPinned(skillsRoot, slug, pinned);
+ } catch (err) {
+ exitCliError(err, 'skillpack');
+ }
+ if (args.includes('--json')) console.log(JSON.stringify({ ok: true, skill: slug, skills_root: skillsRoot, pinned, changed: changed! }, null, 2));
+ else console.log(`${slug} ${changed! ? (pinned ? 'pinned' : 'unpinned') : (pinned ? 'was already pinned' : 'was not pinned')} under ${skillsRoot}`);
+ process.exit(0);
+}
+
+export async function cmdRestore(args: string[]): Promise<void> {
+ if (args.includes('--help') || args.includes('-h')) {
+ console.log('gbrain skillpack restore <id> [--skip <file>]... [--json]\ngbrain skillpack restore --list [--json]\n\n' +
+ 'Undo a --update-untouched run: put back each file it replaced, and remove each file it\n' +
+ 'added, when the file still holds the update\'s bytes. A file you changed since the update\n' +
+ 'refuses the whole restore unless you name it with --skip <file> (path under the skills\n' +
+ 'root). Running it again is a no-op. Backups are kept 30 days or the newest 10.');
+ process.exit(0);
+ }
+ const json = args.includes('--json');
+ if (args.includes('--list')) {
+ const journals = listJournals().map(j => ({
+ id: j.id, status: j.status, skills_root: j.skills_root, created_at: j.created_at,
+ skills: j.skills.map(s => ({ slug: s.slug, status: s.status, files: s.files.length })),
+ }));
+ if (json) console.log(JSON.stringify({ journals }, null, 2));
+ else if (!journals.length) console.log('No skillpack update backups.');
+ else for (const j of journals) console.log(`${j.id} ${j.status.padEnd(8)} ${j.skills.map(s => `${s.slug}:${s.status}`).join(', ')} (${j.skills_root})`);
+ process.exit(0);
+ }
+ const skip: string[] = [];
+ for (let i = 0; i < args.length; i++) if (args[i] === '--skip' && args[i + 1]) skip.push(args[++i]!);
+ const [id, extra] = positionals(args, ['--skip']);
+ if (!id || extra) {
+ console.error('Error: gbrain skillpack restore takes one backup id (gbrain skillpack restore --list).');
+ process.exit(2);
+ }
+ let lock: FileLock | null = null;
+ try {
+ const journal = readJournal(id);
+ lock = await acquireFileLock(workspaceLockPath(journal.skills_root), { code: 'skillpack_workspace_locked' });
+ const result = await runSkillpackRestore({ id, skip });
+ if (json) console.log(JSON.stringify({ ok: true, ...result }, null, 2));
+ else {
+ console.log(`skillpack restore ${id}: ${result.skills_root}`);
+ for (const f of result.files) console.log(` ${f.action.padEnd(16)} ${f.rel}`);
+ }
+ } catch (err) {
+ lock?.release();
+ exitCliError(err, 'skillpack');
+ }
+ lock!.release();
+ process.exit(0);
+}
diff --git a/src/core/behavior-change-notice.ts b/src/core/behavior-change-notice.ts
index 59b8c1aa07..81dbd4e315 100644
--- a/src/core/behavior-change-notice.ts
+++ b/src/core/behavior-change-notice.ts
@@ -1320,6 +1320,8 @@ export const BEHAVIOR_CHANGES: ReadonlyArray<{ since: string; text: ChangeText;
{ since: '0.60.471.0', id: 'door_planned_state', text: 'On a source with `canonical: git`, a page write now commits exactly the bytes it published, or nothing. A file edited on disk while the write was publishing refuses `git_target_changed`: nothing is committed, the edit stays on disk and the source\'s writes pause until `gbrain repair stuck-recovery` resolves it (before, Git committed the edit while the database recorded the write\'s content). A staged change of the page\'s file refuses `git_index_conflict`, with the index untouched; commit or unstage it, then retry (before, the write replaced the staged change in the index). When the index still holds the version from before an earlier gbrain commit whose index update failed, the next write restores it and says so with a `git_index_restored` notice.' },
// #7679 / #7685 orphaned worktree refresh. `since` is stamped at the merge slot.
{ since: '0.60.472.0', id: 'refresh_orphan_7679', text: 'A managed `gbrain sources refresh` whose process died (for example a container replaced mid-refresh) no longer wedges the checkout: the next plain `gbrain sources refresh` on the owner host finishes the orphaned refresh through the `--resume` path before its own refresh and reports it as `recovered`, and the owner completes an orphaned `syncing` refresh once every member has synced to its target. A refresh whose holder is still running, or is recorded on another host, is never taken over. `gbrain sources writer status` and `gbrain sync status` now name the holder and its `liveness` (`live`, `orphaned`, `unknown`) with a fix naming `--resume`. With `--json`, a refusal that carries a structured fix (`refresh_in_progress`, `refresh_diverged`, a git read failure) now prints `fix` as an object (argv, actor, next) instead of a string; the prose stays in `suggestion`, so read that when a script needs text. A plain refresh of a checkout whose interrupted refresh needs a reset decision now refuses `refresh_recovery_required` (it refused `refresh_in_progress`).' },
+ // GBRA-225 PR 3 (safe skillpack updates). `since` is stamped at the merge slot.
+ { since: 'TBD', id: 'skillpack_update_untouched', text: 'Installed skills can now take gbrain\'s current version whole when you never edited them. `gbrain skillpack scaffold` (including `--harness` installs) and every update record the sha256 of each skill file it installed in `~/.gbrain/skillpack-state.json` (schema `gbrain-skillpack-state-v2`; an older gbrain refuses that file instead of dropping its records). Preview what would change with `gbrain skillpack reference --all --update-untouched --dry-run`; a skill with any edited file, a pinned skill (`gbrain skillpack pin <skill>`) or one with no recorded hash is skipped with a reason and a diff. Every update is journaled under `~/.gbrain/skillpack-backups/` and undone with `gbrain skillpack restore <id>`. `gbrain upgrade` writes no skill files; nothing runs on upgrade.' },
];
/** The newest disclosed change's release: the notice id moves only when a release adds rows. */
diff --git a/src/core/cli-flag-registry.generated.ts b/src/core/cli-flag-registry.generated.ts
index b441be94f8..17d1fc2c46 100644
--- a/src/core/cli-flag-registry.generated.ts
+++ b/src/core/cli-flag-registry.generated.ts
@@ -50,7 +50,7 @@ export const CLI_FLAG_REGISTRY: Record<string, readonly string[]> = {
'db-repair': ['--accept-pending', '--apply', '--apply-rewrites', '--background', '--brain', '--break-lock', '--db-url', '--dry-run', '--explain', '--filter', '--follow', '--force', '--force-retry', '--format', '--help', '--http', '--json', '--legacy-lock', '--locks', '--name', '--no-accept-pending', '--path', '--prefer-postgres', '--probe', '--progress-interval', '--progress-json', '--quiet', '--remediate', '--restart', '--skip-verify', '--source', '--statement-timeout', '--supabase', '--timeout', '--timings', '--undo-last-rewrite', '--url', '--version', '--wait', '--yes'],
'decide': ['--accept-all', '--all', '--all-from', '--apply', '--brain', '--call-site', '--dataset', '--dry-run', '--egress', '--embedding-dimensions', '--embedding-model', '--expect', '--from', '--help', '--include-withdrawals', '--input', '--items-out', '--json', '--kind', '--limit', '--max-cost', '--max-usd', '--min', '--non-interactive', '--out', '--provenance', '--provider', '--query', '--rate', '--reason', '--reason-family', '--recommended', '--remove', '--shadow', '--since', '--slot', '--source', '--status', '--suite', '--target', '--threshold', '--trust', '--undo', '--uri-prefix', '--version', '--what-if-threshold', '--yes'],
'diag': ['--access', '--add', '--all', '--allowed-operations', '--apply', '--asof', '--body', '--bound-slug-prefixes', '--brain', '--budget-ms', '--client', '--count', '--cursor', '--date', '--dated-since', '--days', '--detach', '--entities', '--expect', '--expected-revision', '--federated-read', '--format', '--from-index', '--full', '--fuzzy', '--group-by', '--held', '--help', '--http', '--id', '--include-ambiguous', '--include-deleted', '--json', '--kind', '--limit', '--max-usd', '--model', '--multimodal', '--no-autopilot-install', '--no-pull', '--no-walk', '--only', '--page', '--params', '--path', '--phase', '--prefer', '--preview', '--purge', '--query', '--recent', '--refresh-operations', '--replace', '--restart-only', '--reverse', '--row', '--scopes', '--session', '--side', '--since', '--slug', '--slugs', '--source', '--source-id', '--sources', '--stale', '--state', '--surface', '--to', '--updated-after', '--url', '--yes'],
- 'doctor': ['--abandon', '--abbrev-ref', '--accept-pending', '--access', '--account', '--acknowledge-managed', '--add', '--admin-intent', '--adopt', '--adopt-columns', '--adopt-permissions', '--after', '--aggressive', '--aliases', '--all', '--all-drifted', '--all-from', '--allow-old-serve', '--allow-outside-source-root', '--allow-shell-jobs', '--allow-unverified-remote', '--allowed-operations', '--applied', '--apply', '--apply-rewrites', '--assign-corpus', '--audit', '--auto', '--auto-additive', '--auto-fix', '--autostash', '--background', '--batch', '--batch-check', '--bound-brain', '--bound-max-concurrent', '--bound-slug-prefixes', '--bound-source', '--bound-tools', '--brain', '--branch', '--break-lock', '--budget-ms', '--budget-policy', '--budget-tokens', '--budget-usd', '--by-mention', '--cached', '--cacheinfo', '--call-site', '--catch-up', '--channel', '--check', '--cherry-mark', '--class', '--clear', '--clear-never-installed', '--cli-socket', '--client', '--close', '--concurrency', '--confidence', '--confirm', '--confirm-quiesced', '--confirm-relocated-root', '--conflicts', '--contacts-dir', '--content-audit', '--content-root', '--continue', '--conversation', '--count', '--cursor', '--dataset', '--day', '--db-url', '--deadline', '--delegated-namespace', '--delegated-slug-prefixes', '--delete-brain', '--dest', '--detach', '--detail', '--diff-filter', '--dim', '--dimensions', '--dir', '--disable', '--drain', '--drain-timeout', '--dry-run', '--egress', '--embedding-dimensions', '--embedding-model', '--enable', '--enable-dcr', '--end-of-options', '--entity', '--env', '--error-unmatch', '--exclude', '--exclude-standard', '--exit-code', '--expand', '--expect', '--expect-local', '--expect-remote', '--expect-upstream', '--expected-epoch', '--expected-revision', '--expected-state', '--explain', '--facts', '--fast', '--federated', '--federated-read', '--fetch-timeout-ms', '--ff-only', '--file', '--first-parent', '--fix', '--follow', '--force', '--force-break-lock', '--force-rechunk', '--force-remove', '--force-retry', '--force-schema', '--format', '--fresh', '--fresh-token', '--from', '--from-meetings', '--from-pages', '--full', '--full-tree', '--fuzzy', '--generation', '--get', '--get-all', '--get-url', '--git-common-dir', '--git-dir', '--git-path', '--grammar', '--group', '--group-by', '--hard', '--hard-deadline', '--harness', '--held', '--help', '--hold-state', '--holds', '--home', '--http', '--id', '--if-version', '--ignore-env-override', '--images', '--include-ambiguous', '--include-cross-entity', '--include-deleted', '--include-failures', '--include-flagged', '--include-frontmatter', '--include-gitignored', '--include-hidden', '--include-pseudo', '--include-repairs', '--include-withdrawals', '--index-audit', '--index-info', '--infer-dates', '--init', '--input', '--install', '--is-ancestor', '--is-inside-work-tree', '--items-out', '--job-isolation', '--jq', '--json', '--keep', '--keep-checkout', '--key', '--kind', '--lanes', '--lang', '--left-right', '--legacy-lock', '--limit', '--link-source', '--link-type', '--list', '--literal-pathspecs', '--local', '--local-env-vars', '--locks', '--log-noop', '--manifest', '--markdown', '--max-cost', '--max-cost-usd', '--max-count', '--max-facts', '--max-jobs', '--max-requests', '--max-rss', '--max-runtime', '--max-usd', '--max-waiting', '--mcp-only', '--merge-base', '--migrate-legacy', '--migrate-only', '--migration', '--min', '--min-n', '--mode', '--model', '--multimodal', '--name', '--name-only', '--name-status', '--nice', '--no-accept-pending', '--no-autopilot-install', '--no-autostash', '--no-capture', '--no-commit-id', '--no-confirm', '--no-cron', '--no-delegate', '--no-edit', '--no-embed', '--no-embed-cache', '--no-embedding', '--no-expand', '--no-extract', '--no-federated', '--no-filters', '--no-gpg-sign', '--no-hooks', '--no-lanes', '--no-llm', '--no-merges', '--no-migrate', '--no-probe', '--no-pull', '--no-renames', '--no-repair', '--no-restart', '--no-schema-pack', '--no-seat', '--no-tags', '--no-verify', '--no-walk', '--no-write-fetch-head', '--non-interactive', '--not', '--now', '--older-than', '--once', '--only', '--operation', '--operations', '--others', '--out', '--output', '--oversized', '--overwrite', '--page', '--parallel', '--params', '--parents', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--path-format', '--pending', '--pglite', '--phase', '--pid-file', '--plan', '--porcelain', '--port', '--prefer', '--prefer-postgres', '--preset', '--preview', '--probe', '--probe-pglite', '--profile', '--progress-interval', '--progress-json', '--project', '--provenance', '--provider', '--providers', '--prune-orphans', '--public-url', '--pull', '--pure', '--purge', '--push', '--push-only', '--query', '--question', '--queue', '--quiet', '--rate', '--reader-mode', '--reauth', '--rebase', '--rebuild', '--recommended', '--redact-paths', '--reference-date', '--refresh', '--refresh-operations', '--refresh-skills', '--regenerate', '--reissue', '--relative', '--relower', '--remediate', '--remediation-plan', '--remove', '--remove-core', '--repair', '--repair-unknown-markers', '--replace', '--repo', '--request', '--request-id', '--require-clean', '--reranker', '--reset', '--reset-checkpoint', '--reset-default', '--resolve', '--restart-only', '--restore-only', '--resume', '--retry-failed', '--retry-global', '--retry-held', '--retry-parked', '--reverse', '--review-lower', '--revision', '--right-only', '--rollback-to-source', '--root', '--run', '--sample', '--save', '--scope', '--scopes', '--search-mode', '--seat', '--section', '--segmented', '--select', '--self-transfer', '--semantic', '--session', '--session-id', '--set', '--set-upstream-to', '--shadow', '--short', '--show-current', '--show-object-format', '--show-prefix', '--show-token', '--show-toplevel', '--side', '--since', '--since-last-run', '--skills-dir', '--skip', '--skip-bare-tweet', '--skip-failed', '--skip-urls', '--skip-verify', '--slot', '--slot-a-model', '--slot-b-model', '--slot-c-model', '--slug', '--slugs', '--source', '--source-id', '--sources', '--src-subpath', '--staged', '--stale', '--stat', '--state', '--statement-timeout', '--status', '--stdin', '--stop-mcp', '--strategy', '--strict', '--suite', '--supabase', '--surface', '--swap-only', '--symbol-kind', '--symbolic-full-name', '--takes-holders', '--target', '--target-score', '--threshold', '--tier', '--timeout', '--timings', '--to', '--token', '--token-ttl', '--top-k', '--topo-order', '--trust', '--type', '--unindexed', '--uninstall', '--unsafe-bypass-dream-guard', '--unset-all', '--untracked-files', '--url', '--url-env', '--user', '--vacuum', '--vectors', '--verbose', '--verify', '--version', '--wait', '--wait-drain', '--warn-only', '--watch', '--what-if-threshold', '--window', '--workers', '--working-tree', '--workspace', '--write-tree', '--yes'],
+ 'doctor': ['--abandon', '--abbrev-ref', '--accept-pending', '--access', '--account', '--acknowledge-managed', '--add', '--admin-intent', '--adopt', '--adopt-columns', '--adopt-permissions', '--after', '--aggressive', '--aliases', '--all', '--all-drifted', '--all-from', '--allow-old-serve', '--allow-outside-source-root', '--allow-shell-jobs', '--allow-unverified-remote', '--allowed-operations', '--applied', '--apply', '--apply-rewrites', '--assign-corpus', '--audit', '--auto', '--auto-additive', '--auto-fix', '--autostash', '--background', '--batch', '--batch-check', '--bound-brain', '--bound-max-concurrent', '--bound-slug-prefixes', '--bound-source', '--bound-tools', '--brain', '--branch', '--break-lock', '--budget-ms', '--budget-policy', '--budget-tokens', '--budget-usd', '--by-mention', '--cached', '--cacheinfo', '--call-site', '--catch-up', '--channel', '--check', '--cherry-mark', '--class', '--clear', '--clear-never-installed', '--cli-socket', '--client', '--close', '--concurrency', '--confidence', '--confirm', '--confirm-quiesced', '--confirm-relocated-root', '--conflicts', '--contacts-dir', '--content-audit', '--content-root', '--continue', '--conversation', '--count', '--cursor', '--dataset', '--day', '--db-url', '--deadline', '--delegated-namespace', '--delegated-slug-prefixes', '--delete-brain', '--dest', '--detach', '--detail', '--diff-filter', '--dim', '--dimensions', '--dir', '--disable', '--drain', '--drain-timeout', '--dry-run', '--egress', '--embedding-dimensions', '--embedding-model', '--enable', '--enable-dcr', '--end-of-options', '--entity', '--env', '--error-unmatch', '--exclude', '--exclude-standard', '--exit-code', '--expand', '--expect', '--expect-local', '--expect-remote', '--expect-upstream', '--expected-epoch', '--expected-revision', '--expected-state', '--explain', '--facts', '--fast', '--federated', '--federated-read', '--fetch-timeout-ms', '--ff-only', '--file', '--first-parent', '--fix', '--follow', '--force', '--force-break-lock', '--force-rechunk', '--force-remove', '--force-retry', '--force-schema', '--format', '--fresh', '--fresh-token', '--from', '--from-meetings', '--from-pages', '--full', '--full-tree', '--fuzzy', '--generation', '--get', '--get-all', '--get-url', '--git-common-dir', '--git-dir', '--git-path', '--grammar', '--group', '--group-by', '--hard', '--hard-deadline', '--harness', '--held', '--help', '--hold-state', '--holds', '--home', '--http', '--id', '--if-version', '--ignore-env-override', '--images', '--include-ambiguous', '--include-cross-entity', '--include-deleted', '--include-failures', '--include-flagged', '--include-frontmatter', '--include-gitignored', '--include-hidden', '--include-pseudo', '--include-repairs', '--include-withdrawals', '--index-audit', '--index-info', '--infer-dates', '--init', '--input', '--install', '--is-ancestor', '--is-inside-work-tree', '--items-out', '--job-isolation', '--jq', '--json', '--keep', '--keep-checkout', '--key', '--kind', '--lanes', '--lang', '--left-right', '--legacy-lock', '--limit', '--link-source', '--link-type', '--list', '--literal-pathspecs', '--local', '--local-env-vars', '--locks', '--log-noop', '--manifest', '--markdown', '--max-cost', '--max-cost-usd', '--max-count', '--max-facts', '--max-jobs', '--max-requests', '--max-rss', '--max-runtime', '--max-usd', '--max-waiting', '--mcp-only', '--merge-base', '--migrate-legacy', '--migrate-only', '--migration', '--min', '--min-n', '--mode', '--model', '--multimodal', '--name', '--name-only', '--name-status', '--nice', '--no-accept-pending', '--no-autopilot-install', '--no-autostash', '--no-capture', '--no-commit-id', '--no-confirm', '--no-cron', '--no-delegate', '--no-edit', '--no-embed', '--no-embed-cache', '--no-embedding', '--no-expand', '--no-extract', '--no-federated', '--no-filters', '--no-gpg-sign', '--no-hooks', '--no-lanes', '--no-llm', '--no-merges', '--no-migrate', '--no-probe', '--no-pull', '--no-renames', '--no-repair', '--no-restart', '--no-schema-pack', '--no-seat', '--no-tags', '--no-verify', '--no-walk', '--no-write-fetch-head', '--non-interactive', '--not', '--now', '--older-than', '--once', '--only', '--operation', '--operations', '--others', '--out', '--output', '--oversized', '--overwrite', '--page', '--parallel', '--params', '--parents', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--path-format', '--pending', '--pglite', '--phase', '--pid-file', '--plan', '--porcelain', '--port', '--prefer', '--prefer-postgres', '--preset', '--preview', '--probe', '--probe-pglite', '--profile', '--progress-interval', '--progress-json', '--project', '--provenance', '--provider', '--providers', '--prune-orphans', '--public-url', '--pull', '--pure', '--purge', '--push', '--push-only', '--query', '--question', '--queue', '--quiet', '--rate', '--reader-mode', '--reauth', '--rebase', '--rebuild', '--recommended', '--redact-paths', '--reference-date', '--refresh', '--refresh-operations', '--refresh-skills', '--regenerate', '--reissue', '--relative', '--relower', '--remediate', '--remediation-plan', '--remove', '--remove-core', '--repair', '--repair-unknown-markers', '--replace', '--repo', '--request', '--request-id', '--require-clean', '--reranker', '--reset', '--reset-checkpoint', '--reset-default', '--resolve', '--restart-only', '--restore-only', '--resume', '--retry-failed', '--retry-global', '--retry-held', '--retry-parked', '--reverse', '--review-lower', '--revision', '--right-only', '--rollback-to-source', '--root', '--run', '--sample', '--save', '--scope', '--scopes', '--search-mode', '--seat', '--section', '--segmented', '--select', '--self-transfer', '--semantic', '--session', '--session-id', '--set', '--set-upstream-to', '--shadow', '--short', '--show-current', '--show-object-format', '--show-prefix', '--show-token', '--show-toplevel', '--side', '--since', '--since-last-run', '--skills-dir', '--skip', '--skip-bare-tweet', '--skip-failed', '--skip-urls', '--skip-verify', '--slot', '--slot-a-model', '--slot-b-model', '--slot-c-model', '--slug', '--slugs', '--source', '--source-id', '--sources', '--src-subpath', '--staged', '--stale', '--stat', '--state', '--statement-timeout', '--status', '--stdin', '--stop-mcp', '--strategy', '--strict', '--suite', '--supabase', '--surface', '--swap-only', '--symbol-kind', '--symbolic-full-name', '--takes-holders', '--target', '--target-score', '--threshold', '--tier', '--timeout', '--timings', '--to', '--token', '--token-ttl', '--top-k', '--topo-order', '--trust', '--type', '--unindexed', '--uninstall', '--unsafe-bypass-dream-guard', '--unset-all', '--untracked-files', '--update-untouched', '--url', '--url-env', '--user', '--vacuum', '--vectors', '--verbose', '--verify', '--version', '--wait', '--wait-drain', '--warn-only', '--watch', '--what-if-threshold', '--window', '--workers', '--working-tree', '--workspace', '--write-tree', '--yes'],
'dream': ['--audit-rejects', '--brain', '--cancel-unmatched', '--date', '--dir', '--drain', '--dry-run', '--eval-run', '--force', '--from', '--help', '--input', '--install', '--json', '--limit', '--list', '--max-usd', '--once', '--phase', '--probe', '--pull', '--reconcile-queue', '--since', '--source', '--source-id', '--threshold', '--to', '--unsafe-bypass-dream-guard', '--window', '--yes'],
'edge-proposals': ['--access', '--add', '--all', '--all-applied', '--all-held', '--allowed-operations', '--asof', '--body', '--bound-slug-prefixes', '--brain', '--client', '--cursor', '--date', '--dated-since', '--days', '--entities', '--federated-read', '--from-index', '--full', '--fuzzy', '--group-by', '--help', '--http', '--id', '--include-deleted', '--json', '--kind', '--limit', '--max-usd', '--model', '--multimodal', '--no-autopilot-install', '--page', '--params', '--path', '--phase', '--prefer', '--purge', '--recent', '--refresh-operations', '--row', '--scopes', '--session', '--since', '--slugs', '--source', '--sources', '--stale', '--status', '--surface', '--to', '--updated-after', '--url', '--yes'],
'edges-backfill': ['--all-sources', '--brain', '--concurrency', '--help', '--json', '--max-chunks', '--source', '--workers'],
@@ -76,7 +76,7 @@ export const CLI_FLAG_REGISTRY: Record<string, readonly string[]> = {
'graph-query': ['--brain', '--depth', '--direction', '--help', '--hop', '--include-foreign', '--json', '--mcp-only', '--request-id', '--source', '--type'],
'hook': ['--allow-unverified-remote', '--auto', '--batch-check', '--brain', '--branch', '--cached', '--count', '--diff-filter', '--enable', '--end-of-options', '--env', '--get', '--harness', '--help', '--jq', '--json', '--limit', '--name-only', '--others', '--pat-file', '--path', '--porcelain', '--pure', '--quiet', '--remove', '--seat', '--session', '--show-current', '--show-toplevel', '--since', '--source', '--yes'],
'import': ['--accept-pending', '--admin-intent', '--allow-empty', '--allow-noncanonical-root', '--apply', '--background', '--batch-check', '--brain', '--cached', '--confirm-relocated-root', '--diff-filter', '--dim', '--embedding-dimensions', '--embedding-model', '--empty', '--exclude', '--exclude-standard', '--expected-epoch', '--expected-state', '--explain', '--follow', '--force', '--force-rechunk', '--format', '--fresh', '--help', '--include-gitignored', '--is-shallow-repository', '--json', '--literal-pathspecs', '--log-noop', '--manifest', '--name-only', '--no-accept-pending', '--no-embed', '--no-embedding', '--no-gpg-sign', '--no-pull', '--no-renames', '--no-verify', '--only', '--others', '--path', '--probe', '--progress-interval', '--progress-json', '--quiet', '--self-transfer', '--show-toplevel', '--skip-failed', '--slugs', '--source', '--source-id', '--stale', '--status', '--supabase', '--timeout', '--timings', '--to', '--url', '--verify', '--wait', '--workers'],
- 'init': ['--access', '--acknowledge-managed', '--adopt', '--after', '--aliases', '--all', '--all-drifted', '--allow-create-db', '--allow-docker', '--allow-outside-source-root', '--applied', '--apply', '--assign-corpus', '--audit', '--auto', '--auto-additive', '--background', '--batch', '--bound-slug-prefixes', '--brain', '--branch', '--break-lock', '--budget-ms', '--budget-policy', '--budget-tokens', '--budget-usd', '--by-mention', '--catch-up', '--channel', '--chat-model', '--check', '--class', '--clear', '--clear-never-installed', '--cli-socket', '--client', '--close', '--confirm-relocated-root', '--conflicts', '--content-root', '--continue', '--conversation', '--cursor', '--db-only', '--deadline', '--dest', '--detach', '--detail', '--dim', '--disable', '--drain', '--embedding-dimensions', '--embedding-model', '--enable', '--entity', '--exclude', '--expand', '--expansion-model', '--expect', '--expect-local', '--expect-remote', '--expect-upstream', '--explain', '--facts', '--fast', '--federated', '--file', '--fix', '--force', '--force-retry', '--format', '--fresh-token', '--from', '--from-meetings', '--full', '--git', '--grammar', '--grant-types', '--group-by', '--harness', '--held', '--help', '--hold-state', '--holds', '--http', '--id', '--images', '--include-ambiguous', '--include-cross-entity', '--include-frontmatter', '--include-gitignored', '--include-hidden', '--infer-dates', '--input', '--install', '--issuer-url', '--job-isolation', '--json', '--keep', '--keep-checkout', '--key', '--kind', '--lanes', '--legacy-lock', '--limit', '--list', '--local-postgres', '--markdown', '--max-cost-usd', '--max-facts', '--max-requests', '--max-rss', '--max-usd', '--mcp-only', '--mcp-url', '--migrate-only', '--migration', '--min-n', '--mode', '--model', '--no-autopilot-install', '--no-autostash', '--no-delegate', '--no-embed', '--no-embedding', '--no-expand', '--no-extract', '--no-federated', '--no-filters', '--no-git', '--no-lanes', '--no-llm', '--no-probe', '--no-pull', '--no-renames', '--no-repair', '--no-restart', '--no-schema-pack', '--no-verify', '--non-interactive', '--oauth-client-id', '--oauth-client-secret', '--older-than', '--once', '--only', '--operation', '--output', '--oversized', '--page', '--params', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--pending', '--pglite', '--phase', '--plan', '--prefer', '--prefer-postgres', '--preview', '--probe', '--profile', '--provenance', '--providers', '--pull', '--purge', '--push-only', '--query', '--question', '--quiet', '--rebase', '--rebuild', '--redact-paths', '--reference-date', '--remediate', '--remove', '--repair', '--repair-unknown-markers', '--repo', '--request', '--request-id', '--require-clean', '--reset', '--resolve', '--restart-only', '--resume', '--retry-failed', '--retry-parked', '--save', '--schema-pack', '--scope', '--scopes', '--search-mode', '--section', '--segmented', '--self-transfer', '--semantic', '--session', '--session-id', '--show-toplevel', '--side', '--since', '--since-last-run', '--skip', '--skip-embed-check', '--skip-failed', '--slug', '--slugs', '--source', '--source-id', '--sources', '--src-subpath', '--stale', '--state', '--status', '--stdin', '--stop-mcp', '--strategy', '--supabase', '--surface', '--swap-only', '--tier', '--timeout', '--to', '--token', '--touchpoint', '--type', '--url', '--url-env', '--user', '--vacuum', '--verbose', '--version', '--wait', '--warn-only', '--watch', '--working-tree', '--workspace', '--yes'],
+ 'init': ['--access', '--acknowledge-managed', '--adopt', '--after', '--aliases', '--all', '--all-drifted', '--allow-create-db', '--allow-docker', '--allow-outside-source-root', '--applied', '--apply', '--assign-corpus', '--audit', '--auto', '--auto-additive', '--background', '--batch', '--bound-slug-prefixes', '--brain', '--branch', '--break-lock', '--budget-ms', '--budget-policy', '--budget-tokens', '--budget-usd', '--by-mention', '--catch-up', '--channel', '--chat-model', '--check', '--class', '--clear', '--clear-never-installed', '--cli-socket', '--client', '--close', '--confirm-relocated-root', '--conflicts', '--content-root', '--continue', '--conversation', '--cursor', '--db-only', '--deadline', '--dest', '--detach', '--detail', '--dim', '--disable', '--drain', '--embedding-dimensions', '--embedding-model', '--enable', '--entity', '--exclude', '--expand', '--expansion-model', '--expect', '--expect-local', '--expect-remote', '--expect-upstream', '--explain', '--facts', '--fast', '--federated', '--file', '--fix', '--force', '--force-retry', '--format', '--fresh-token', '--from', '--from-meetings', '--full', '--git', '--grammar', '--grant-types', '--group-by', '--harness', '--held', '--help', '--hold-state', '--holds', '--http', '--id', '--images', '--include-ambiguous', '--include-cross-entity', '--include-frontmatter', '--include-gitignored', '--include-hidden', '--infer-dates', '--input', '--install', '--issuer-url', '--job-isolation', '--json', '--keep', '--keep-checkout', '--key', '--kind', '--lanes', '--legacy-lock', '--limit', '--list', '--local-postgres', '--markdown', '--max-cost-usd', '--max-facts', '--max-requests', '--max-rss', '--max-usd', '--mcp-only', '--mcp-url', '--migrate-only', '--migration', '--min-n', '--mode', '--model', '--no-autopilot-install', '--no-autostash', '--no-delegate', '--no-embed', '--no-embedding', '--no-expand', '--no-extract', '--no-federated', '--no-filters', '--no-git', '--no-lanes', '--no-llm', '--no-probe', '--no-pull', '--no-renames', '--no-repair', '--no-restart', '--no-schema-pack', '--no-verify', '--non-interactive', '--oauth-client-id', '--oauth-client-secret', '--older-than', '--once', '--only', '--operation', '--output', '--oversized', '--page', '--params', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--pending', '--pglite', '--phase', '--plan', '--prefer', '--prefer-postgres', '--preview', '--probe', '--profile', '--provenance', '--providers', '--pull', '--purge', '--push-only', '--query', '--question', '--quiet', '--rebase', '--rebuild', '--redact-paths', '--reference-date', '--remediate', '--remove', '--repair', '--repair-unknown-markers', '--repo', '--request', '--request-id', '--require-clean', '--reset', '--resolve', '--restart-only', '--resume', '--retry-failed', '--retry-parked', '--save', '--schema-pack', '--scope', '--scopes', '--search-mode', '--section', '--segmented', '--self-transfer', '--semantic', '--session', '--session-id', '--show-toplevel', '--side', '--since', '--since-last-run', '--skip', '--skip-embed-check', '--skip-failed', '--slug', '--slugs', '--source', '--source-id', '--sources', '--src-subpath', '--stale', '--state', '--status', '--stdin', '--stop-mcp', '--strategy', '--supabase', '--surface', '--swap-only', '--tier', '--timeout', '--to', '--token', '--touchpoint', '--type', '--update-untouched', '--url', '--url-env', '--user', '--vacuum', '--verbose', '--version', '--wait', '--warn-only', '--watch', '--working-tree', '--workspace', '--yes'],
'integrations': ['--auto', '--brain', '--dry-run', '--help', '--json', '--overwrite', '--refresh', '--source', '--target'],
'integrity': ['--accept-pending', '--auto', '--backend', '--background', '--body', '--brain', '--check', '--confidence', '--cost', '--dry-run', '--explain', '--follow', '--fresh', '--help', '--json', '--limit', '--no-accept-pending', '--progress-interval', '--progress-json', '--quiet', '--review-lower', '--skip-bare-tweet', '--skip-urls', '--source', '--timeout', '--timings', '--type', '--wait'],
'jobs': ['--abbrev-ref', '--access', '--account', '--acknowledge-managed', '--add', '--admin-intent', '--adopt-slug-path', '--aliases', '--all', '--all-sources', '--allow-empty', '--allow-shell-jobs', '--allowed-operations', '--apply', '--asof', '--auto', '--background', '--backoff-delay', '--backoff-jitter', '--backoff-type', '--batch-size', '--body', '--bound-slug-prefixes', '--brain', '--break-lock', '--budget-ms', '--by-mention', '--cached', '--catch-up', '--channel', '--check', '--clear', '--cli-path', '--client', '--close', '--cluster-errors', '--concurrency', '--confidence', '--confirm-destructive', '--confirm-relocated-root', '--cost-estimate', '--cursor', '--date', '--dated-since', '--days', '--delay', '--detach', '--detail', '--diff-filter', '--dir', '--drain', '--drain-timeout', '--dry-run', '--embedding-dimensions', '--embedding-model', '--empty', '--enable', '--entities', '--exclude', '--exclude-standard', '--expect', '--expect-local', '--expect-upstream', '--expected-state', '--explain', '--facts', '--federated-read', '--ff-only', '--file', '--filters', '--finished-since', '--fix', '--follow', '--force', '--force-break-lock', '--force-retry', '--format', '--fresh', '--from-index', '--from-meetings', '--full', '--full-history', '--fuzzy', '--git', '--grammar', '--grammar-diagnostics', '--group', '--group-by', '--hard-deadline', '--health-interval', '--held', '--help', '--hold-state', '--http', '--id', '--idempotency-key', '--ids', '--images', '--include-ambiguous', '--include-deleted', '--include-frontmatter', '--include-gitignored', '--include-hidden', '--include-null-signature', '--infer-dates', '--inject-bootstrap', '--inline', '--input', '--install', '--interval', '--is-ancestor', '--is-shallow-repository', '--job-id', '--job-isolation', '--json', '--keep', '--kind', '--lanes', '--legacy-lock', '--limit', '--list', '--local', '--lock-duration-ms', '--log-noop', '--markdown', '--max-age', '--max-attempts', '--max-cost', '--max-cost-usd', '--max-crashes', '--max-rss', '--max-sources', '--max-stalled', '--max-usd', '--max-waiting', '--mcp-only', '--migration', '--min-context', '--missing-path', '--mode', '--model', '--multimodal', '--name', '--name-only', '--ner', '--nice', '--no-auto-embed', '--no-autopilot-install', '--no-bulk', '--no-confirm', '--no-delegate', '--no-embed', '--no-embedding', '--no-extract', '--no-gpg-sign', '--no-hard-deadline', '--no-inject', '--no-lanes', '--no-llm', '--no-pull', '--no-renames', '--no-repair', '--no-restart', '--no-schema-pack', '--no-verify', '--no-worker', '--non-interactive', '--now', '--older-than', '--once', '--only', '--order', '--others', '--output', '--override-disabled', '--oversized', '--pace', '--pace-max-concurrency', '--pack', '--page', '--parallel', '--params', '--parked-code', '--pat-file', '--path', '--pause', '--pglite', '--phase', '--pid-file', '--plan', '--port', '--prefer', '--preview', '--priority', '--probe', '--prune-orphans', '--pull', '--purge', '--question', '--queue', '--queue-only', '--quiet', '--rate', '--reason', '--rebuild', '--recent', '--record', '--redact-paths', '--redact-secrets', '--reenrich-after', '--refresh-ms', '--refresh-operations', '--remediate', '--repo', '--request-id', '--reset-checkpoint', '--restart-only', '--resume', '--retry-failed', '--retry-global', '--retry-held', '--retry-parked', '--review-lower', '--row', '--scope', '--scopes', '--section', '--segment-limit', '--segmented', '--select', '--self-transfer', '--serial', '--session', '--show-toplevel', '--side', '--sigkill-rescue', '--since', '--skip', '--skip-bare-tweet', '--skip-failed', '--skip-urls', '--sleep', '--slug', '--slugs', '--source', '--source-guard', '--source-id', '--sources', '--src-subpath', '--staged', '--stale', '--state', '--statement-timeout', '--status', '--stop-mcp', '--strategy', '--suites', '--surface', '--swap-only', '--target', '--thin', '--thin-threshold', '--tier', '--timeout', '--timeout-ms', '--to', '--token', '--trust', '--type', '--types', '--uninstall', '--updated-after', '--url', '--user', '--vectors', '--verbose', '--verify', '--version', '--watch', '--wedge-rescue', '--workers', '--working-tree', '--yes'],
@@ -124,7 +124,7 @@ export const CLI_FLAG_REGISTRY: Record<string, readonly string[]> = {
'setup': ['--auto', '--bearer-token-env-var', '--brain', '--break-lock', '--capture', '--dry-run', '--env', '--gbrain-bin', '--harness', '--header', '--help', '--http', '--install', '--issuer-url', '--json', '--legacy-lock', '--mcp-only', '--mcp-url', '--name', '--no-capture', '--no-embedding', '--no-hooks', '--no-providers', '--oauth-client-id', '--oauth-client-secret', '--only', '--path', '--pglite', '--probe', '--providers', '--pure', '--remove', '--save', '--scope', '--source', '--surface', '--token', '--url', '--yes'],
'skillify': ['--brain', '--description', '--dry-run', '--force', '--help', '--json', '--mutating', '--recent', '--skills-dir', '--source', '--strict', '--triggers', '--writes-pages', '--writes-to'],
'skillopt': ['--all', '--allow-mutate-bundled', '--background', '--batch-size', '--benchmark', '--bootstrap-from-routing', '--bootstrap-from-skill', '--bootstrap-reviewed', '--bootstrap-tasks', '--brain', '--brain-wide-max-cost-usd', '--dry-run', '--epochs', '--follow', '--force', '--held-out', '--help', '--json', '--judge-model', '--lr', '--lr-schedule', '--max-cost-usd', '--max-runtime-min', '--max-usd', '--models-strict', '--no-max-cost', '--no-mutate', '--optimizer-model', '--patch', '--reflect-max-tokens', '--resume', '--rewrite', '--skills-dir', '--source', '--split', '--status', '--target-model', '--target-models'],
- 'skillpack': ['--all', '--apply-clean-hunks', '--author', '--auto', '--brain', '--dest', '--dry-run', '--env', '--exit-code', '--fast', '--fix', '--force-unlock', '--format', '--from', '--full', '--harness', '--help', '--homepage', '--json', '--license', '--list', '--minimal', '--name-only', '--no-cache', '--no-lint', '--note', '--out', '--overwrite-local', '--persona', '--probe', '--pure', '--push', '--quick', '--quiet', '--refresh', '--repo', '--schema-pack', '--scope', '--short', '--since', '--skill', '--skills', '--skills-dir', '--skip-doctor', '--source', '--strict', '--stub', '--supabase', '--target', '--tier', '--trust', '--url', '--verify', '--version', '--workspace', '--yes'],
+ 'skillpack': ['--accept-historical', '--all', '--apply-clean-hunks', '--author', '--auto', '--brain', '--dest', '--dry-run', '--env', '--exit-code', '--fail-on-skipped', '--fast', '--fix', '--force-unlock', '--format', '--from', '--full', '--harness', '--help', '--homepage', '--json', '--license', '--list', '--minimal', '--name-only', '--no-cache', '--no-diff', '--no-lint', '--note', '--out', '--overwrite-local', '--persona', '--probe', '--pure', '--push', '--quick', '--quiet', '--refresh', '--repo', '--schema-pack', '--scope', '--short', '--since', '--skill', '--skills', '--skills-dir', '--skip', '--skip-doctor', '--source', '--strict', '--stub', '--supabase', '--target', '--tier', '--trust', '--update-untouched', '--url', '--verify', '--version', '--workspace', '--yes'],
'skillpack-check': ['--accept-pending', '--background', '--brain', '--explain', '--fast', '--follow', '--help', '--json', '--list', '--no-accept-pending', '--progress-interval', '--progress-json', '--quiet', '--source', '--strict', '--timeout', '--timings', '--wait', '--yes'],
'smoke-test': ['--brain', '--help', '--json', '--source'],
'sources': ['--abandon', '--abbrev-ref', '--abort', '--accept-pending', '--accept-suggested', '--access', '--account', '--add', '--admin-intent', '--adopt-columns', '--adopt-permissions', '--adopt-slug-path', '--after', '--all', '--all-new', '--allow-unverified-remote', '--allowed-operations', '--app-id', '--app-install', '--app-pem', '--apply', '--audit', '--auto-additive', '--autostash', '--background', '--backups', '--batch-check', '--before', '--bound-brain', '--bound-max-concurrent', '--bound-slug-prefixes', '--bound-source', '--bound-tools', '--brain', '--branch', '--break-lock', '--budget-usd-per-day', '--cached', '--calendar-id', '--category', '--classify', '--cleanup-dead-local-locks', '--clear', '--client', '--clone-dir', '--code', '--confirm-destructive', '--confirm-quiesced', '--confirm-relocated-root', '--conflicts', '--contacts-dir', '--count', '--cursor', '--days', '--db-url', '--decisions', '--delegated-namespace', '--delegated-slug-prefixes', '--depth', '--detect', '--diff-filter', '--dir', '--disable', '--dry-run', '--enable', '--error-unmatch', '--exclude', '--expect', '--expect-local', '--expect-remote', '--expect-upstream', '--expected-epoch', '--expected-incarnation', '--expected-state', '--explain', '--federated', '--federated-read', '--fetch-timeout-ms', '--ff-only', '--file', '--fix', '--follow', '--force', '--format', '--from', '--from-git', '--full', '--future-days', '--get', '--get-all', '--git-dir', '--git-path', '--github-repo', '--grant-types', '--group-by', '--hard', '--help', '--history-days', '--holds', '--http', '--id', '--if-version', '--include', '--include-warns', '--is-ancestor', '--is-inside-work-tree', '--json', '--keep', '--keep-checkout', '--keep-storage', '--kind', '--lanes', '--legacy-lock', '--limit', '--local', '--local-env-vars', '--loops-exclude-labels', '--manifest', '--max-cost-usd', '--message', '--migrate-legacy', '--migration', '--min-trust', '--name', '--name-only', '--no-accept-pending', '--no-autostash', '--no-cron', '--no-embed', '--no-extract', '--no-federate', '--no-federated', '--no-harden', '--no-lanes', '--no-pull', '--no-tags', '--no-verify', '--not', '--only', '--operation', '--operations', '--origin', '--others', '--out', '--params', '--parked-code', '--parked-pushes', '--pat-file', '--path', '--path-format', '--plan', '--porcelain', '--preview', '--probe', '--profile', '--progress-interval', '--progress-json', '--pull', '--push-only', '--push-remote', '--quiet', '--read-sources', '--rebase', '--redirect-uri', '--refresh-operations', '--remove-backup', '--repair', '--replace', '--repos', '--request-id', '--require-clean', '--reset-checkpoint', '--reset-default', '--resolve', '--resume', '--retry-failed', '--sample', '--scope', '--scopes', '--secret', '--self-transfer', '--services', '--set', '--set-upstream-to', '--shared-skills', '--short', '--show-toplevel', '--since', '--slug-prefixes', '--source', '--source-id', '--source-ids', '--sources', '--stale', '--state', '--status', '--stdin', '--surface', '--symbolic-full-name', '--takes-holders', '--timeout', '--timings', '--to', '--token', '--token-command', '--token-endpoint-auth-method', '--token-env', '--token-ttl', '--unindexed', '--unset-all', '--untracked-files', '--url', '--usage', '--verify', '--wait', '--wait-drain', '--warn-only', '--window', '--yes'],
diff --git a/src/core/doctor-categories.ts b/src/core/doctor-categories.ts
index 71ffac93f4..0f6c251256 100644
--- a/src/core/doctor-categories.ts
+++ b/src/core/doctor-categories.ts
@@ -271,6 +271,9 @@ export const SKILL_CHECK_NAMES: ReadonlySet<string> = new Set([
'skills_manifest_integrity',
'skill_currency',
'skill_preconditions',
+ // Skillpack update journals (crash-pending updates, kept backups).
+ 'skillpack_update_incomplete',
+ 'skillpack_backups',
'whoknows_health',
]);
diff --git a/src/core/error-registry.ts b/src/core/error-registry.ts
index c4d30ed271..af5309f6b4 100644
--- a/src/core/error-registry.ts
+++ b/src/core/error-registry.ts
@@ -653,6 +653,12 @@ export const CODES = {
skill_not_found: { class: 'caller', summary: "No authorized published skill matches this key." },
skill_retention_capacity: { class: 'caller', summary: "Retained skill revisions exceed this source storage budget." },
skill_unavailable: { class: 'caller', summary: "The qualified shared skill is not in this installation's current authorized view.", docs: 'docs/guides/shared-brain-skills.md#troubleshoot-leave-and-recover' },
+ skillpack_backup_corrupt: { class: 'server', exit: 2, summary: "A skillpack update backup does not hash to the journal's pre-update hash, so restore will not write it.", why: "Restore only writes bytes it can prove are the file's pre-update content. Side effects: files restored before this one stay restored; this file and the rest are untouched.", suggestion: 'Leave the file as it is, or compare it with gbrain skillpack reference <skill> and edit it by hand.', docs: 'docs/guides/skillpacks-as-scaffolding.md#updating-installed-skills', fix: { argv: ['gbrain', 'skillpack', 'restore', '--list', '--json'], consent: [], actor: 'agent', why: 'Lists every skillpack update backup, its status and its skills; changes nothing.', requires_exclusive: false } },
+ skillpack_journal_not_found: { class: 'caller', exit: 2, summary: "No skillpack update backup has that id.", why: "Backups live under ~/.gbrain/skillpack-backups/<id>/ and are kept 30 days or the newest 10. Side effects: none.", suggestion: 'List the backups with gbrain skillpack restore --list.', docs: 'docs/guides/skillpacks-as-scaffolding.md#updating-installed-skills', fix: { argv: ['gbrain', 'skillpack', 'restore', '--list', '--json'], consent: [], actor: 'agent', why: 'Lists every skillpack update backup, its status and its skills; changes nothing.', requires_exclusive: false } },
+ skillpack_restore_conflict: { class: 'caller', exit: 2, summary: "A file changed after the skillpack update it would restore, so restore refused.", why: "Restore never overwrites an edit made after the update. Side effects: nothing was restored (a file that changes mid-restore stops the run; files already restored stay restored and a rerun is a no-op for them).", suggestion: 'Keep the later edit and restore the rest: gbrain skillpack restore <id> --skip <file>.', docs: 'docs/guides/skillpacks-as-scaffolding.md#updating-installed-skills', fix: { argv: ['gbrain', 'skillpack', 'restore', '--list', '--json'], consent: [], actor: 'agent', why: 'Lists every skillpack update backup, its status and its skills; changes nothing.', requires_exclusive: false } },
+ skillpack_state_locked: { class: 'retryable', exit: 2, summary: "Another gbrain skillpack command holds the lock on ~/.gbrain/skillpack-state.json.", why: "Scaffold, update, pin and restore read-modify-write the state file one at a time. Side effects: nothing was written by this command. A lock left by a crash is reclaimed after 10 minutes.", suggestion: 'Wait for the other command to finish and run this one again.', docs: 'docs/guides/skillpacks-as-scaffolding.md#updating-installed-skills', fix: { argv: ['gbrain', 'skillpack', 'restore', '--list', '--json'], consent: [], actor: 'agent', why: 'Lists every skillpack update backup, its status and its skills; changes nothing.', requires_exclusive: false } },
+ skillpack_update_incomplete: { class: 'caller', exit: 2, summary: "An earlier skillpack update of this skills root did not finish (a crash left its journal pending), so no new update runs.", why: "Some files of the interrupted skill may hold the new version and others the old. Side effects: nothing was changed by this run; --dry-run still previews.", suggestion: 'Run gbrain skillpack restore <id> (named in the message), then update again.', docs: 'docs/guides/skillpacks-as-scaffolding.md#updating-installed-skills', fix: { argv: ['gbrain', 'doctor', '--only', 'skillpack_update_incomplete', '--json'], consent: [], actor: 'agent', why: 'Reports skillpack updates a crash left unfinished and the restore command for each; changes nothing.', requires_exclusive: false } },
+ skillpack_workspace_locked: { class: 'retryable', exit: 2, summary: "Another gbrain skillpack command holds this workspace's writer lock (.gbrain-skillpack.lock).", why: "One writer per skills root keeps an update and a restore from interleaving. Side effects: nothing was written. A lock left by a crash is reclaimed after 10 minutes.", suggestion: 'Wait for the other command to finish and run this one again.', docs: 'docs/guides/skillpacks-as-scaffolding.md#updating-installed-skills', fix: { argv: ['gbrain', 'skillpack', 'restore', '--list', '--json'], consent: [], actor: 'agent', why: 'Lists every skillpack update backup, its status and its skills; changes nothing.', requires_exclusive: false } },
slug_page_mismatch: { class: 'caller', retryable: false, actor: 'agent',
summary: "Managed sync files a held file as a page whose slug the file does not carry as written, so removing its frontmatter `slug:` line would not clear the `frontmatter_slug_conflict` hold; nothing was written.",
why: "The content-repair lane judges a held file with the screen managed sync froze it with (#6696). Sync keys a file to the page that records it as its origin (or its path-derived slug) and accepts a `slug:` line only when it equals the path-derived slug or that page's slug as written. When the page's slug differs from the path-derived slug (an older import that honored the line, or a source in a subdirectory of its Git repository), or the line reaches the page only through an alias, neither removing the line nor keeping it imports the file, so the lane records `slug_page_mismatch` with both slugs instead of a generic `still_invalid`.",
diff --git a/src/core/skill-drift.ts b/src/core/skill-drift.ts
index dc5839c3df..4d62fa3680 100644
--- a/src/core/skill-drift.ts
+++ b/src/core/skill-drift.ts
@@ -49,7 +49,7 @@ export interface DriftReport {
const SHELL_FENCES = new Set(['', 'bash', 'sh', 'shell', 'zsh', 'console']);
const IGNORE_MARKER = '<!-- skill-drift-ok';
-const GBRAIN_AT = /(?:^|[|&;(]|\$\()\s*(?:[A-Z_][A-Z0-9_]*=\S*\s+)*(?:(?:nohup|exec|time)\s+)?gbrain\s+/g;
+const INVOCATION_AT = /(?:^|[|&;(]|\$\()\s*(?:[A-Z_][A-Z0-9_]*=\S*\s+)*(?:(?:nohup|exec|time)\s+)?gbrain\s+/g;
const HOST_TOOLS = new Set(['web_fetch', 'web_search']);
function splitShell(text: string): { words: string[]; rest: string } {
@@ -90,7 +90,7 @@ function splitShell(text: string): { words: string[]; rest: string } {
const isPlaceholder = (t: string) => /[<>{}]|\.\.\.|…/.test(t);
function invocationsIn(text: string, line: number, out: Invocation[]): void {
- for (const m of text.matchAll(GBRAIN_AT)) {
+ for (const m of text.matchAll(INVOCATION_AT)) {
const start = m.index! + m[0].length;
const { words } = splitShell(text.slice(start));
if (!words.length || isPlaceholder(words[0]!)) continue;
diff --git a/src/core/skillpack/file-lock.ts b/src/core/skillpack/file-lock.ts
new file mode 100644
index 0000000000..9ab455eea7
--- /dev/null
+++ b/src/core/skillpack/file-lock.ts
@@ -0,0 +1,76 @@
+/**
+ * skillpack/file-lock.ts — exclusive lock files for the skillpack writers.
+ *
+ * Two locks, always taken in this order when both are needed:
+ * 1. the workspace writer lock, `.gbrain-skillpack.lock` in the directory
+ * that holds the skills root (the same file `installer.ts` takes), and
+ * 2. the shared state lock, `skillpack-state.json.lock` beside
+ * `~/.gbrain/skillpack-state.json`.
+ *
+ * Mutual exclusion comes from an O_EXCL create. Line 1 is the pid (what the
+ * installer's reader parses), line 2 a per-acquire token that release() checks,
+ * so a process never removes a lock it does not hold. A lock file older than
+ * `staleMs` is reclaimed: the holder died (the commands that take these locks
+ * finish in seconds). Liveness is mtime only, never pid, for the reason
+ * page-lock.ts gives.
+ */
+import { mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+
+import { OperationError } from '../ops/contract.ts';
+
+export const WORKSPACE_LOCK_FILENAME = '.gbrain-skillpack.lock';
+const DEFAULT_STALE_MS = 10 * 60 * 1000;
+
+export interface FileLock {
+ path: string;
+ release(): void;
+}
+
+export function workspaceLockPath(skillsRoot: string): string {
+ return join(dirname(skillsRoot), WORKSPACE_LOCK_FILENAME);
+}
+
+function tryAcquire(path: string, staleMs: number): FileLock | null {
+ mkdirSync(dirname(path), { recursive: true });
+ try {
+ if (Date.now() - statSync(path).mtimeMs >= staleMs) unlinkSync(path);
+ } catch { /* absent, or released between the stat and the unlink */ }
+ const token = randomUUID();
+ try {
+ writeFileSync(path, `${process.pid}\n${token}\n`, { flag: 'wx' });
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code === 'EEXIST') return null;
+ throw err;
+ }
+ return {
+ path,
+ release: () => {
+ try {
+ if (readFileSync(path, 'utf-8').split('\n')[1] === token) unlinkSync(path);
+ } catch { /* already gone */ }
+ },
+ };
+}
+
+/**
+ * Take the lock at `path`, polling until `timeoutMs` elapses. Throws
+ * `code` (an OperationError) naming the lock file when it stays held.
+ */
+export async function acquireFileLock(
+ path: string,
+ opts: { code: 'skillpack_workspace_locked' | 'skillpack_state_locked'; timeoutMs?: number; staleMs?: number },
+): Promise<FileLock> {
+ const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
+ const deadline = Date.now() + (opts.timeoutMs ?? 30_000);
+ for (;;) {
+ const lock = tryAcquire(path, staleMs);
+ if (lock) return lock;
+ if (Date.now() >= deadline) {
+ throw new OperationError(opts.code, `Another gbrain skillpack command holds ${path}.`,
+ `Wait for it to finish and run the command again. If no gbrain skillpack command is running, the lock is left from a crash and is reclaimed after ${Math.round(staleMs / 60000)} minutes.`);
+ }
+ await new Promise(resolve => setTimeout(resolve, 50));
+ }
+}
diff --git a/src/core/skillpack/safe-update.ts b/src/core/skillpack/safe-update.ts
new file mode 100644
index 0000000000..81e9439b9b
--- /dev/null
+++ b/src/core/skillpack/safe-update.ts
@@ -0,0 +1,481 @@
+/**
+ * skillpack/safe-update.ts — `gbrain skillpack reference <name>|--all --update-untouched`.
+ *
+ * Takes upstream on installed skills the user never edited, one whole skill
+ * at a time. A skill's closure is every file under its bundle dir plus any
+ * shared dependency it lacks; paired sources outside the skills root are
+ * never written (they are reported).
+ *
+ * Classification, per file (the install's recorded base always wins):
+ * unchanged already equals the bundle
+ * absent missing and gbrain never recorded it (a new file)
+ * untouched equals its recorded base
+ * local_edits differs from its recorded base (even when it equals a past
+ * release), or has no base and matches no released version,
+ * or was deleted after gbrain recorded it
+ * historical no base, equals a released version (needs --accept-historical)
+ * no_history no base, and the released-version history has no entry
+ * A skill is updatable only when it is not pinned, the history verified,
+ * and every changed file is absent, untouched, or historical with
+ * --accept-historical. Anything else skips the whole skill with a reason.
+ *
+ * Commit protocol: stage the closure in the skills root and validate it,
+ * write the journal (update-journal.ts), back up each file, rehash it right
+ * before its rename (abandon the skill on any change since classification),
+ * then run conformance, the trigger check and the resolver check. A conflict,
+ * an error or a failed check rolls back the files already renamed that still
+ * hold the update's bytes. Bases are recorded only after a skill commits.
+ * The caller holds the workspace writer lock; state writes take the shared
+ * state lock (state.ts updateState), so the order is always workspace, state.
+ */
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'fs';
+import { basename, dirname, join, relative, resolve, sep } from 'path';
+
+import { bundledSkillSlugs, enumerateScaffoldEntries, loadBundleManifest, type BundleManifest } from './bundle.ts';
+import { loadVerifiedSkillsLockHistory, type VerifiedSkillsLockHistory } from '../skills-integrity.ts';
+import { loadState, updateState, withSkillBases, type InstalledSkillRecord } from './state.ts';
+import { unifiedDiff } from './diff-text.ts';
+import { redactFindings } from '../secret-scan.ts';
+import { parseSkillFrontmatter } from '../skill-frontmatter.ts';
+import { loadSkillTriggerIndex } from '../skill-trigger-index.ts';
+import { checkResolvable, type ResolvableIssue } from '../check-resolvable.ts';
+import { OperationError } from '../ops/contract.ts';
+import { confinedSkillChildWrite } from './writer-guard.ts';
+import {
+ backupFile, backupsRoot, hashTarget, newJournalId, pendingJournals, planRestore, pruneJournals, readJournal, sha256, undoFile, writeJournal,
+ type Journal, type JournalFile, type JournalSkill, type RestorePlanFile,
+} from './update-journal.ts';
+
+export const DIFF_LINE_CAP = 200;
+const STAGE_PREFIX = '.gbrain-skillpack-stage-';
+
+export type FileState = 'unchanged' | 'absent' | 'untouched' | 'historical' | 'local_edits' | 'no_history';
+export type SkipReason = 'pinned' | 'history_unverified' | 'unsafe_target' | 'local_edits' | 'no_history' | 'historical_only';
+
+export interface ClassifiedFile {
+ rel: string;
+ source: string;
+ post: string;
+ pre: string | null;
+ base: string | null;
+ sharedDep: boolean;
+ state: FileState;
+}
+
+export interface SkillOutcome {
+ slug: string;
+ result: 'updated' | 'would_update' | 'current' | 'skipped' | 'failed' | 'not_installed';
+ reason?: SkipReason;
+ pinned: boolean;
+ /** Files the update writes (or would write). */
+ changes: string[];
+ /** Files with no base that match only a released version. */
+ historical: string[];
+ notes: string[];
+ diffs?: Array<{ rel: string; diff: string; truncated: boolean }>;
+ /** On failure: files this run renamed, and those it could not roll back because they changed again. */
+ touched?: string[];
+ rollback_skipped?: string[];
+ failure?: string;
+ files: ClassifiedFile[];
+}
+
+export interface UpdateResult {
+ dry_run: boolean;
+ skills_root: string;
+ history: { verified: boolean; reason?: string };
+ journal: string | null;
+ pending_journals: string[];
+ summary: Record<SkillOutcome['result'], number>;
+ skills: SkillOutcome[];
+ restore_command: string | null;
+}
+
+export interface UpdateOptions {
+ gbrainRoot: string;
+ /** Absolute skills root (see skillsRootKey). */
+ skillsRoot: string;
+ /** Skill slugs, or null for every bundled skill. */
+ slugs: string[] | null;
+ dryRun?: boolean;
+ acceptHistorical?: boolean;
+ noDiff?: boolean;
+ statePath?: string;
+ backups?: string;
+ /** Post-rename checks; returns problems (empty = pass). Defaults to conformance + triggers + resolver. */
+ validate?: (skillsRoot: string, slug: string) => string[];
+ hooks?: { beforeRename?: (rel: string) => void; afterRename?: (rel: string) => void };
+}
+
+/** The key a skills root (or a file under it) is recorded under: the realpath of its deepest existing ancestor plus the rest. */
+export function skillsRootKey(dir: string): string {
+ const missing: string[] = [];
+ let current = resolve(dir);
+ for (;;) {
+ try {
+ return join(realpathSync(current), ...missing.reverse());
+ } catch {
+ const parent = dirname(current);
+ if (parent === current) return resolve(dir);
+ missing.push(basename(current));
+ current = parent;
+ }
+ }
+}
+
+function fileState(pre: string | null, post: string, base: string | null, history: VerifiedSkillsLockHistory, rel: string): FileState {
+ if (pre === post) return 'unchanged';
+ if (base !== null) return pre === base ? 'untouched' : 'local_edits';
+ if (pre === null) return 'absent';
+ const released = history.ok ? history.history.files[rel] : undefined;
+ if (!released?.length) return 'no_history';
+ return released.includes(pre) ? 'historical' : 'local_edits';
+}
+
+function boundedRedactedDiff(local: Buffer, bundle: Buffer, rel: string): { diff: string; truncated: boolean } {
+ if (local.includes(0) || bundle.includes(0)) return { diff: `Binary file ${rel} differs (local ${local.length} B, bundle ${bundle.length} B).\n`, truncated: false };
+ const text = redactFindings(unifiedDiff(local.toString('utf-8'), bundle.toString('utf-8'), { oldPath: `a/${rel}`, newPath: `b/${rel}` })).text;
+ const lines = text.split('\n');
+ if (lines.length <= DIFF_LINE_CAP) return { diff: text, truncated: false };
+ return { diff: lines.slice(0, DIFF_LINE_CAP).join('\n') + `\n... ${lines.length - DIFF_LINE_CAP} more line(s)\n`, truncated: true };
+}
+
+export interface ClassifyContext {
+ gbrainRoot: string;
+ skillsRoot: string;
+ manifest: BundleManifest;
+ history: VerifiedSkillsLockHistory;
+ records: Record<string, InstalledSkillRecord>;
+ acceptHistorical: boolean;
+ noDiff: boolean;
+}
+
+export function classifySkill(ctx: ClassifyContext, slug: string): SkillOutcome {
+ const record = ctx.records[slug];
+ const files: ClassifiedFile[] = [];
+ const notes: string[] = [];
+ let unsafe: string | null = null;
+ for (const entry of enumerateScaffoldEntries({ gbrainRoot: ctx.gbrainRoot, skillSlug: slug, manifest: ctx.manifest })) {
+ if (entry.pairedSource) {
+ notes.push(`paired source ${entry.relWorkspaceTarget} lives outside the skills root and is never written here; compare it with gbrain skillpack reference ${slug}`);
+ continue;
+ }
+ const rel = entry.relWorkspaceTarget.replace(/^skills\//, '');
+ let pre: string | null;
+ try {
+ pre = hashTarget(confinedSkillChildWrite(ctx.skillsRoot, rel, { dryRun: true }));
+ } catch (err) {
+ unsafe = `${rel}: ${(err as Error).message}`;
+ continue;
+ }
+ if (entry.sharedDep && pre !== null) continue;
+ const post = sha256(readFileSync(entry.source));
+ const base = record?.files[rel] ?? null;
+ files.push({ rel, source: entry.source, post, pre, base, sharedDep: entry.sharedDep, state: fileState(pre, post, base, ctx.history, rel) });
+ }
+ if (unsafe) notes.push(unsafe);
+ const outcome: SkillOutcome = {
+ slug, result: 'current', pinned: record?.pinned === true, changes: [], historical: files.filter(f => f.state === 'historical').map(f => f.rel), notes, files,
+ };
+ const skillMd = files.find(f => f.rel === `${slug}/SKILL.md`);
+ if (!record && skillMd?.pre === null) return { ...outcome, result: 'not_installed', historical: [] };
+ const changed = files.filter(f => f.state !== 'unchanged');
+ outcome.changes = changed.map(f => f.rel);
+ if (changed.length === 0 && !unsafe) return outcome;
+ const reason: SkipReason | undefined = outcome.pinned ? 'pinned'
+ : !ctx.history.ok ? 'history_unverified'
+ : unsafe ? 'unsafe_target'
+ : changed.some(f => f.state === 'local_edits') ? 'local_edits'
+ : changed.some(f => f.state === 'no_history') ? 'no_history'
+ : outcome.historical.length && !ctx.acceptHistorical ? 'historical_only'
+ : undefined;
+ if (!reason) return { ...outcome, result: 'would_update' };
+ outcome.result = 'skipped';
+ outcome.reason = reason;
+ if (!ctx.noDiff && reason !== 'pinned') {
+ outcome.diffs = changed.filter(f => f.pre !== null).map(f => ({
+ rel: f.rel, ...boundedRedactedDiff(readFileSync(join(ctx.skillsRoot, f.rel)), readFileSync(f.source), f.rel),
+ }));
+ }
+ return outcome;
+}
+
+function issueKey(issue: ResolvableIssue): string {
+ return `${issue.type}|${issue.skill}|${issue.message}`;
+}
+
+function mentionsSkill(issue: ResolvableIssue, slug: string): boolean {
+ return issue.skill === slug || issue.skill.includes(`${slug}/`) || issue.skill.split(/,\s*/).includes(slug);
+}
+
+/**
+ * Conformance, trigger and resolver checks. Built before the first rename:
+ * resolver errors present then are the baseline and do not count against a
+ * skill (a resolver that cannot run at all is not checked).
+ */
+export function defaultValidator(skillsRoot: string): (root: string, slug: string) => string[] {
+ let baseline: Set<string> | null;
+ try {
+ baseline = new Set(checkResolvable(skillsRoot).errors.map(issueKey));
+ } catch {
+ baseline = null;
+ }
+ return (root, slug) => {
+ const problems: string[] = [];
+ const content = readFileSync(join(root, slug, 'SKILL.md'), 'utf-8');
+ const fm = content.startsWith('---') ? parseSkillFrontmatter(content) : null;
+ if (!fm?.name) problems.push(`conformance: ${slug}/SKILL.md has no frontmatter with a name`);
+ if (fm?.triggers?.length && !loadSkillTriggerIndex(root).some(e => e.skillPath === `${slug}/SKILL.md` || e.skillPath.endsWith(`/${slug}/SKILL.md`))) {
+ problems.push(`trigger check: ${slug} declares triggers but the trigger index does not route to it`);
+ }
+ if (baseline !== null) {
+ try {
+ for (const issue of checkResolvable(root).errors) {
+ if (mentionsSkill(issue, slug) && !baseline!.has(issueKey(issue))) problems.push(`resolver check: ${issue.message}`);
+ }
+ } catch (err) {
+ problems.push(`resolver check failed: ${(err as Error).message}`);
+ }
+ }
+ return problems;
+ };
+}
+
+function removeStaleStages(skillsRoot: string): void {
+ if (!existsSync(skillsRoot)) return;
+ for (const name of readdirSync(skillsRoot)) {
+ if (name.startsWith(STAGE_PREFIX)) rmSync(join(skillsRoot, name), { recursive: true, force: true });
+ }
+}
+
+interface ApplyContext {
+ opts: UpdateOptions;
+ journal: Journal;
+ backups: string;
+ validate: (root: string, slug: string) => string[];
+}
+
+function rollback(ctx: ApplyContext, renamed: JournalFile[]): string[] {
+ const left: string[] = [];
+ for (const file of [...renamed].reverse()) {
+ try {
+ if (!undoFile(ctx.journal.id, ctx.opts.skillsRoot, file, ctx.backups)) left.push(file.rel);
+ } catch {
+ left.push(file.rel);
+ }
+ }
+ return left;
+}
+
+async function applySkill(ctx: ApplyContext, outcome: SkillOutcome, js: JournalSkill): Promise<SkillOutcome> {
+ const { skillsRoot } = ctx.opts;
+ const changed = outcome.files.filter(f => f.state !== 'unchanged');
+ const fail = (failure: string, status: JournalSkill['status'], renamed: JournalFile[] = []): SkillOutcome => {
+ const rollbackSkipped = renamed.length ? rollback(ctx, renamed) : [];
+ js.status = status;
+ js.reason = failure;
+ writeJournal(ctx.journal, ctx.backups);
+ return { ...outcome, result: 'failed', failure, touched: renamed.map(f => f.rel), rollback_skipped: rollbackSkipped };
+ };
+ mkdirSync(skillsRoot, { recursive: true });
+ const stage = mkdtempSync(join(skillsRoot, STAGE_PREFIX));
+ try {
+ const staged: string[] = [];
+ for (const [i, f] of changed.entries()) {
+ const bytes = readFileSync(f.source);
+ if (sha256(bytes) !== f.post) return fail(`bundle file ${f.rel} changed during the run`, 'abandoned');
+ if (f.rel === `${outcome.slug}/SKILL.md` && !parseSkillFrontmatter(bytes.toString('utf-8'))?.name) {
+ return fail(`staged ${f.rel} has no frontmatter with a name`, 'abandoned');
+ }
+ const path = join(stage, String(i));
+ writeFileSync(path, bytes);
+ staged.push(path);
+ }
+ const fresh = loadState({ statePath: ctx.opts.statePath }).roots?.[skillsRoot]?.[outcome.slug];
+ if (fresh?.pinned || changed.some(f => (fresh?.files[f.rel] ?? null) !== f.base)) {
+ return fail('the skill was pinned or its recorded base changed since classification', 'abandoned');
+ }
+ js.status = 'applying';
+ writeJournal(ctx.journal, ctx.backups);
+ try {
+ for (const file of js.files) {
+ if (file.pre !== null) file.backup = backupFile(ctx.journal.id, file.rel, join(skillsRoot, file.rel), file.pre, ctx.backups);
+ }
+ } catch (err) {
+ return fail(`changed since classification: ${(err as Error).message}`, 'abandoned');
+ }
+ writeJournal(ctx.journal, ctx.backups);
+ const renamed: JournalFile[] = [];
+ try {
+ for (const [i, file] of js.files.entries()) {
+ ctx.opts.hooks?.beforeRename?.(file.rel);
+ const target = confinedSkillChildWrite(skillsRoot, file.rel);
+ if (hashTarget(target) !== file.pre) return fail(`${file.rel} changed since classification`, 'rolled_back', renamed);
+ mkdirSync(dirname(target), { recursive: true });
+ renameSync(staged[i]!, target);
+ renamed.push(file);
+ ctx.opts.hooks?.afterRename?.(file.rel);
+ }
+ const problems = ctx.validate(skillsRoot, outcome.slug);
+ if (problems.length) return fail(problems.join('; '), 'rolled_back', renamed);
+ } catch (err) {
+ return fail((err as Error).message, 'rolled_back', renamed);
+ }
+ js.status = 'committed';
+ writeJournal(ctx.journal, ctx.backups);
+ const bases = Object.fromEntries(outcome.files.filter(f => !f.sharedDep).map(f => [f.rel, f.post]));
+ await updateState(state => ({ state: withSkillBases(state, skillsRoot, { [outcome.slug]: bases }), result: null }), { statePath: ctx.opts.statePath });
+ return { ...outcome, result: 'updated' };
+ } finally {
+ rmSync(stage, { recursive: true, force: true });
+ }
+}
+
+function summarize(skills: SkillOutcome[]): UpdateResult['summary'] {
+ const summary = { updated: 0, would_update: 0, current: 0, skipped: 0, failed: 0, not_installed: 0 };
+ for (const s of skills) summary[s.result]++;
+ return summary;
+}
+
+/** Run the update (or, with dryRun, the preview). The caller holds the workspace writer lock for opts.skillsRoot. */
+export async function runSkillpackUpdate(opts: UpdateOptions): Promise<UpdateResult> {
+ const backups = opts.backups ?? backupsRoot();
+ const manifest = loadBundleManifest(opts.gbrainRoot);
+ const slugs = opts.slugs ?? bundledSkillSlugs(manifest);
+ const history = loadVerifiedSkillsLockHistory(join(opts.gbrainRoot, 'skills'));
+ const pending = pendingJournals({ root: backups, skillsRoot: opts.skillsRoot }).map(j => j.id);
+ if (pending.length && !opts.dryRun) {
+ throw new OperationError('skillpack_update_incomplete',
+ `An earlier skillpack update of ${opts.skillsRoot} did not finish (backup ${pending[0]}); nothing was changed now.`,
+ `Put the interrupted skills back with gbrain skillpack restore ${pending[0]} (it refuses files you changed since; name them with --skip), then run the update again.`);
+ }
+ const ctx: ClassifyContext = {
+ gbrainRoot: opts.gbrainRoot, skillsRoot: opts.skillsRoot, manifest, history,
+ records: loadState({ statePath: opts.statePath }).roots?.[opts.skillsRoot] ?? {},
+ acceptHistorical: opts.acceptHistorical === true, noDiff: opts.noDiff === true,
+ };
+ const outcomes = slugs.map(slug => classifySkill(ctx, slug));
+ const base = {
+ dry_run: opts.dryRun === true, skills_root: opts.skillsRoot,
+ history: history.ok ? { verified: true } : { verified: false, reason: history.reason },
+ pending_journals: pending,
+ };
+ const updatable = outcomes.filter(o => o.result === 'would_update');
+ if (opts.dryRun || updatable.length === 0) {
+ return { ...base, journal: null, summary: summarize(outcomes), skills: outcomes, restore_command: null };
+ }
+ removeStaleStages(opts.skillsRoot);
+ const journal: Journal = {
+ schema_version: 'gbrain-skillpack-journal-v1', id: newJournalId(), status: 'pending', skills_root: opts.skillsRoot,
+ created_at: new Date().toISOString(), pid: process.pid,
+ skills: updatable.map(o => ({
+ slug: o.slug, status: 'planned',
+ files: o.files.filter(f => f.state !== 'unchanged').map(f => ({ rel: f.rel, pre: f.pre, post: f.post, base_before: f.base, backup: null })),
+ })),
+ };
+ writeJournal(journal, backups);
+ const apply: ApplyContext = { opts, journal, backups, validate: opts.validate ?? defaultValidator(opts.skillsRoot) };
+ const results: SkillOutcome[] = [];
+ for (const outcome of outcomes) {
+ const js = journal.skills.find(s => s.slug === outcome.slug);
+ results.push(js ? await applySkill(apply, outcome, js) : outcome);
+ }
+ journal.status = 'complete';
+ writeJournal(journal, backups);
+ pruneJournals(backups);
+ const failed = results.some(r => r.result === 'failed');
+ return { ...base, journal: journal.id, summary: summarize(results), skills: results, restore_command: failed ? `gbrain skillpack restore ${journal.id}` : null };
+}
+
+export interface RestoreResult {
+ id: string;
+ skills_root: string;
+ files: RestorePlanFile[];
+}
+
+/** Put back every applied file of journal `id` that still holds the update's bytes. The caller holds the workspace lock for the journal's root. */
+export async function runSkillpackRestore(opts: { id: string; skip?: string[]; statePath?: string; backups?: string }): Promise<RestoreResult> {
+ const backups = opts.backups ?? backupsRoot();
+ const journal = readJournal(opts.id, backups);
+ const plan = planRestore(journal, new Set(opts.skip ?? []));
+ const conflicts = plan.filter(f => f.action === 'conflict').map(f => f.rel);
+ if (conflicts.length) {
+ throw new OperationError('skillpack_restore_conflict',
+ `Refusing to restore ${opts.id}: ${conflicts.length} file(s) changed after the update: ${conflicts.join(', ')}. Nothing was restored.`,
+ `Keep your later edits and restore the rest with gbrain skillpack restore ${opts.id} ${conflicts.map(c => `--skip ${c}`).join(' ')}.`);
+ }
+ const byRel = new Map(journal.skills.flatMap(s => s.files.map(f => [f.rel, f] as const)));
+ for (const item of plan) {
+ if (item.action !== 'restore' && item.action !== 'remove') continue;
+ if (!undoFile(journal.id, journal.skills_root, byRel.get(item.rel)!, backups)) {
+ throw new OperationError('skillpack_restore_conflict', `${item.rel} changed while it was being restored.`,
+ `Run gbrain skillpack restore ${opts.id} again, adding --skip ${item.rel} to keep the newer edit.`);
+ }
+ }
+ const putBack = new Set(plan.filter(f => f.action !== 'skipped').map(f => `${f.slug}\u0000${f.rel}`));
+ await updateState(state => {
+ const root = { ...(state.roots?.[journal.skills_root] ?? {}) };
+ for (const skill of journal.skills) {
+ const record = root[skill.slug];
+ if (!record) continue;
+ const files = { ...record.files };
+ for (const file of skill.files) {
+ if (!putBack.has(`${skill.slug}\u0000${file.rel}`)) continue;
+ if (file.base_before === null) delete files[file.rel];
+ else files[file.rel] = file.base_before;
+ }
+ root[skill.slug] = { ...record, files };
+ }
+ return { state: { ...state, roots: { ...state.roots, [journal.skills_root]: root } }, result: null };
+ }, { statePath: opts.statePath });
+ for (const skill of journal.skills) if (skill.status === 'applying' || skill.status === 'committed') skill.status = 'restored';
+ journal.status = 'restored';
+ writeJournal(journal, backups);
+ removeStaleStages(journal.skills_root);
+ pruneJournals(backups);
+ return { id: journal.id, skills_root: journal.skills_root, files: plan };
+}
+
+/** Pin or unpin `slug` under `skillsRoot`. A pinned skill is never updated by --update-untouched. Returns whether anything changed. */
+export async function setSkillPinned(skillsRoot: string, slug: string, pinned: boolean, opts: { statePath?: string } = {}): Promise<boolean> {
+ return updateState(state => {
+ const root = { ...(state.roots?.[skillsRoot] ?? {}) };
+ const record = root[slug];
+ if ((record?.pinned === true) === pinned) return { state: null, result: false };
+ const { pinned: _old, ...rest } = record ?? { files: {}, recorded_at: new Date().toISOString() };
+ root[slug] = pinned ? { ...rest, pinned: true } : rest;
+ return { state: { ...state, roots: { ...state.roots, [skillsRoot]: root } }, result: true };
+ }, { statePath: opts.statePath });
+}
+
+/** A file a scaffold considered: written now, or already present. */
+export interface ScaffoldedFile {
+ source?: string;
+ target: string;
+ outcome: 'wrote_new' | 'skipped_existing';
+ sharedDep: boolean;
+ pairedSource?: boolean;
+}
+
+/**
+ * Record the install's base for each skill file a scaffold wrote, or found
+ * byte-identical to the bundle. Shared dependencies, paired sources and
+ * pre-existing files that differ are not recorded (they are not gbrain's
+ * install). Without a `source` (the harness bridge's rendered files), the
+ * written bytes on disk are the base.
+ */
+export async function recordScaffoldBases(skillsRoot: string, files: readonly ScaffoldedFile[], opts: { statePath?: string } = {}): Promise<void> {
+ const root = skillsRootKey(skillsRoot);
+ const bases: Record<string, Record<string, string>> = {};
+ for (const f of files) {
+ if (f.sharedDep || f.pairedSource || (!f.source && f.outcome !== 'wrote_new')) continue;
+ const rel = relative(root, skillsRootKey(f.target)).split(sep).join('/');
+ if (!rel || rel.startsWith('..') || !rel.includes('/')) continue;
+ const current = hashTarget(f.target);
+ const expected = f.source ? sha256(readFileSync(f.source)) : current;
+ if (current === null || current !== expected) continue;
+ (bases[rel.split('/')[0]!] ??= {})[rel] = current;
+ }
+ if (Object.keys(bases).length === 0) return;
+ await updateState(state => ({ state: withSkillBases(state, root, bases), result: null }), opts);
+}
diff --git a/src/core/skillpack/scaffold-third-party.ts b/src/core/skillpack/scaffold-third-party.ts
index 4335978b30..db382314ff 100644
--- a/src/core/skillpack/scaffold-third-party.ts
+++ b/src/core/skillpack/scaffold-third-party.ts
@@ -4,7 +4,7 @@
*
* Composes the foundation pieces:
* resolveSource → loadSkillpackManifest → askTrust → enumerateScaffoldEntries
- * → copyArtifacts → saveState (~/.gbrain/skillpack-state.json) → buildBootstrapDisplay
+ * → copyArtifacts → updateState (~/.gbrain/skillpack-state.json, under its lock) → buildBootstrapDisplay
*
* Mirrors the contracts of v0.36's `runScaffold` (no managed-block writes,
* refuses to overwrite, partial-state policy via enumerateScaffoldEntries +
@@ -24,7 +24,7 @@ import { enumerateScaffoldEntries, type ScaffoldEntry } from './bundle.ts';
import {
defaultStatePath,
loadState,
- saveState,
+ updateState,
upsertEntry,
type SkillpackState,
type SkillpackStateEntry,
@@ -194,8 +194,10 @@ export async function runScaffoldThirdParty(
workspace: opts.targetWorkspace,
skill_slugs: skillSlugs,
};
- newState = upsertEntry(state, entry);
- saveState(newState, { statePath: opts.statePath });
+ newState = await updateState((current) => {
+ const next = upsertEntry(current, entry);
+ return { state: next, result: next };
+ }, { statePath: opts.statePath });
}
const status: ScaffoldThirdPartyStatus = opts.dryRun
diff --git a/src/core/skillpack/state.ts b/src/core/skillpack/state.ts
index b826bd9187..2d71505473 100644
--- a/src/core/skillpack/state.ts
+++ b/src/core/skillpack/state.ts
@@ -11,19 +11,29 @@
* source of truth for "what third-party scaffolds happened, when,
* from where, with what verified hash."
*
- * Atomic update via `.tmp` + `rename()`. Schema-versioned. Pure
- * function over the parsed JSON; the calling commands wrap it with
- * read/write helpers.
+ * v2 adds `roots`: per skills root (a workspace's `skills/` dir or a
+ * harness skills dir, absolute) and skill, the sha256 of each file as gbrain
+ * installed it (the install's base) and whether the skill is pinned.
+ * `gbrain skillpack reference --update-untouched` updates a skill only when
+ * every file still matches its base. A v1 file loads as v2 with no roots.
+ *
+ * Atomic update via a unique temp file + `rename()`. Schema-versioned.
+ * Writers that read-modify-write go through `updateState`, which holds the
+ * shared state lock (file-lock.ts) across the load and the save.
*/
import { assertLegacySkillFilesystemWrite } from './writer-guard.ts';
import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
-import { dirname, join } from 'path';
+import { randomUUID } from 'crypto';
+import { dirname } from 'path';
+
+import { acquireFileLock } from './file-lock.ts';
import { gbrainPath } from '../config.ts';
/** Schema version stamped on every state file. */
-export const SKILLPACK_STATE_SCHEMA_VERSION = 'gbrain-skillpack-state-v1' as const;
+export const SKILLPACK_STATE_SCHEMA_VERSION = 'gbrain-skillpack-state-v2' as const;
+const SKILLPACK_STATE_SCHEMA_V1 = 'gbrain-skillpack-state-v1';
/** Per-pack scaffold record. */
export interface SkillpackStateEntry {
@@ -51,9 +61,21 @@ export interface SkillpackStateEntry {
skill_slugs: string[];
}
+/** One installed skill's base under a skills root. */
+export interface InstalledSkillRecord {
+ /** Path relative to the skills root (posix) → sha256 of the bytes gbrain wrote. */
+ files: Record<string, string>;
+ /** Pinned skills are never updated by --update-untouched. */
+ pinned?: boolean;
+ /** ISO 8601 UTC of the last base write. */
+ recorded_at: string;
+}
+
export interface SkillpackState {
schema_version: typeof SKILLPACK_STATE_SCHEMA_VERSION;
packs: SkillpackStateEntry[];
+ /** Absolute skills root → skill slug → base record. loadState always fills it. */
+ roots?: Record<string, Record<string, InstalledSkillRecord>>;
}
export type SkillpackStateErrorCode =
@@ -71,10 +93,7 @@ export class SkillpackStateError extends Error {
}
}
-const EMPTY_STATE: SkillpackState = {
- schema_version: SKILLPACK_STATE_SCHEMA_VERSION,
- packs: [],
-};
+
/** Default state file path. Override via `opts.statePath` in calling code. */
export function defaultStatePath(): string {
@@ -88,7 +107,7 @@ export function defaultStatePath(): string {
*/
export function loadState(opts: { statePath?: string } = {}): SkillpackState {
const path = opts.statePath ?? defaultStatePath();
- if (!existsSync(path)) return { ...EMPTY_STATE, packs: [] };
+ if (!existsSync(path)) return { schema_version: SKILLPACK_STATE_SCHEMA_VERSION, packs: [], roots: {} };
let raw: unknown;
try {
@@ -108,7 +127,7 @@ export function loadState(opts: { statePath?: string } = {}): SkillpackState {
}
const obj = raw as Record<string, unknown>;
- if (obj.schema_version !== SKILLPACK_STATE_SCHEMA_VERSION) {
+ if (obj.schema_version !== SKILLPACK_STATE_SCHEMA_VERSION && obj.schema_version !== SKILLPACK_STATE_SCHEMA_V1) {
throw new SkillpackStateError(
`skillpack-state.json has unknown schema_version ${JSON.stringify(obj.schema_version)}; expected ${SKILLPACK_STATE_SCHEMA_VERSION}`,
'state_schema_unknown',
@@ -122,7 +141,15 @@ export function loadState(opts: { statePath?: string } = {}): SkillpackState {
);
}
- return { schema_version: SKILLPACK_STATE_SCHEMA_VERSION, packs: obj.packs as SkillpackStateEntry[] };
+ const roots = obj.schema_version === SKILLPACK_STATE_SCHEMA_V1 ? {} : (obj.roots ?? {});
+ if (typeof roots !== 'object' || roots === null || Array.isArray(roots)) {
+ throw new SkillpackStateError(`skillpack-state.json.roots must be an object`, 'state_malformed_json');
+ }
+ return {
+ schema_version: SKILLPACK_STATE_SCHEMA_VERSION,
+ packs: obj.packs as SkillpackStateEntry[],
+ roots: roots as NonNullable<SkillpackState['roots']>,
+ };
}
/**
@@ -134,7 +161,7 @@ export function saveState(state: SkillpackState, opts: { statePath?: string } =
const path = opts.statePath ?? defaultStatePath();
assertLegacySkillFilesystemWrite(path);
mkdirSync(dirname(path), { recursive: true });
- const tmp = path + '.tmp';
+ const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
assertLegacySkillFilesystemWrite(tmp);
try {
writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n', { mode: 0o644 });
@@ -163,15 +190,12 @@ export function findEntry(state: SkillpackState, name: string): SkillpackStateEn
*/
export function upsertEntry(state: SkillpackState, entry: SkillpackStateEntry): SkillpackState {
const others = state.packs.filter((p) => p.name !== entry.name);
- return { schema_version: SKILLPACK_STATE_SCHEMA_VERSION, packs: [...others, entry] };
+ return { ...state, packs: [...others, entry] };
}
/** Remove a pack entry by name. Returns a new state value. */
export function removeEntry(state: SkillpackState, name: string): SkillpackState {
- return {
- schema_version: SKILLPACK_STATE_SCHEMA_VERSION,
- packs: state.packs.filter((p) => p.name !== name),
- };
+ return { ...state, packs: state.packs.filter((p) => p.name !== name) };
}
/**
@@ -197,3 +221,39 @@ export function isAlreadyTrusted(
// Local-path source — no identity to pin; treat as untrusted (always re-confirm).
return false;
}
+
+/**
+ * Read-modify-write under the shared state lock. `fn` receives the current
+ * state and returns the state to save (or null to save nothing). Callers that
+ * also hold a workspace lock take it first.
+ */
+export async function updateState<T>(
+ fn: (state: SkillpackState) => { state: SkillpackState | null; result: T },
+ opts: { statePath?: string; timeoutMs?: number } = {},
+): Promise<T> {
+ const path = opts.statePath ?? defaultStatePath();
+ const lock = await acquireFileLock(`${path}.lock`, { code: 'skillpack_state_locked', timeoutMs: opts.timeoutMs });
+ try {
+ const { state, result } = fn(loadState({ statePath: path }));
+ if (state) saveState(state, { statePath: path });
+ return result;
+ } finally {
+ lock.release();
+ }
+}
+
+/** Record each file's base hash per skill under `skillsRoot` (merged over any existing record; pins are kept). */
+export function withSkillBases(
+ state: SkillpackState,
+ skillsRoot: string,
+ bases: Record<string, Record<string, string>>,
+ now = new Date().toISOString(),
+): SkillpackState {
+ const root = { ...(state.roots?.[skillsRoot] ?? {}) };
+ for (const [slug, files] of Object.entries(bases)) {
+ if (Object.keys(files).length === 0) continue;
+ const existing = root[slug];
+ root[slug] = { ...existing, files: { ...(existing?.files ?? {}), ...files }, recorded_at: now };
+ }
+ return { ...state, roots: { ...state.roots, [skillsRoot]: root } };
+}
diff --git a/src/core/skillpack/update-journal.ts b/src/core/skillpack/update-journal.ts
new file mode 100644
index 0000000000..a64b0847ee
--- /dev/null
+++ b/src/core/skillpack/update-journal.ts
@@ -0,0 +1,216 @@
+/**
+ * skillpack/update-journal.ts — the journal and backups behind
+ * `gbrain skillpack reference --update-untouched` and `gbrain skillpack restore`.
+ *
+ * Layout: `~/.gbrain/skillpack-backups/<id>/journal.json` plus
+ * `files/<rel>`, the bytes each replaced file had before the update. Plain
+ * files under GBRAIN_HOME, so it works the same with or without a brain
+ * repository.
+ *
+ * Journal lifecycle: a run writes the journal (status `pending`, every
+ * skill `planned`) before it changes anything. Each skill moves to
+ * `applying` before its first backup, then to `committed`, `rolled_back`
+ * or `abandoned`. The run ends `complete`. A journal still `pending`
+ * when no run holds the workspace lock is a crash (`skillpack_update_incomplete`).
+ * `restore` puts back each applied file whose current hash equals the
+ * journal's post-update hash and marks the journal `restored`.
+ */
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'fs';
+import { createHash, randomBytes, randomUUID } from 'crypto';
+import { dirname, join } from 'path';
+
+import { gbrainPath } from '../config.ts';
+import { OperationError } from '../ops/contract.ts';
+import { assertLegacySkillFilesystemWrite, confinedSkillChildWrite } from './writer-guard.ts';
+
+export const JOURNAL_SCHEMA = 'gbrain-skillpack-journal-v1' as const;
+export const JOURNAL_KEEP_DAYS = 30;
+export const JOURNAL_KEEP_LAST = 10;
+
+export type JournalSkillStatus = 'planned' | 'applying' | 'committed' | 'rolled_back' | 'abandoned' | 'restored';
+
+export interface JournalFile {
+ /** Path relative to the skills root (posix). */
+ rel: string;
+ /** sha256 before the update; null when the file did not exist. */
+ pre: string | null;
+ /** sha256 the update writes. */
+ post: string;
+ /** The base recorded for this file before the update (restore puts it back). */
+ base_before: string | null;
+ /** Backup path relative to the journal dir; null when `pre` is null. */
+ backup: string | null;
+}
+
+export interface JournalSkill {
+ slug: string;
+ status: JournalSkillStatus;
+ reason?: string;
+ files: JournalFile[];
+}
+
+export interface Journal {
+ schema_version: typeof JOURNAL_SCHEMA;
+ id: string;
+ status: 'pending' | 'complete' | 'restored';
+ skills_root: string;
+ created_at: string;
+ pid: number;
+ skills: JournalSkill[];
+}
+
+export function backupsRoot(): string {
+ return gbrainPath('skillpack-backups');
+}
+
+export function sha256(bytes: Buffer | string): string {
+ return createHash('sha256').update(bytes).digest('hex');
+}
+
+/** sha256 of a regular file, null when absent. A symlink (or anything not a regular file) throws `target_escape`. */
+export function hashTarget(path: string): string | null {
+ let stat;
+ try {
+ stat = lstatSync(path);
+ } catch (err) {
+ if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+ throw err;
+ }
+ if (!stat.isFile()) {
+ throw new OperationError('target_escape', `${path} is not a regular file (symlinks are refused).`,
+ 'Replace it with a regular file, or pin the skill with gbrain skillpack pin <skill>.');
+ }
+ return sha256(readFileSync(path));
+}
+
+export function newJournalId(now = new Date()): string {
+ return `${now.toISOString().replace(/[:.]/g, '-')}-${randomBytes(3).toString('hex')}`;
+}
+
+export function journalDir(id: string, root = backupsRoot()): string {
+ if (!/^[0-9TZ-]+-[0-9a-f]{6}$/.test(id)) {
+ throw new OperationError('skillpack_journal_not_found', `'${id}' is not a skillpack backup id.`,
+ 'List the backups with gbrain skillpack restore --list.');
+ }
+ return join(root, id);
+}
+
+export function writeJournal(journal: Journal, root = backupsRoot()): void {
+ const dir = journalDir(journal.id, root);
+ mkdirSync(dir, { recursive: true });
+ const path = join(dir, 'journal.json');
+ const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
+ writeFileSync(tmp, JSON.stringify(journal, null, 2) + '\n', { mode: 0o600 });
+ renameSync(tmp, path);
+}
+
+export function readJournal(id: string, root = backupsRoot()): Journal {
+ const path = join(journalDir(id, root), 'journal.json');
+ if (!existsSync(path)) {
+ throw new OperationError('skillpack_journal_not_found', `No skillpack backup '${id}' under ${root}.`,
+ 'List the backups with gbrain skillpack restore --list.');
+ }
+ const journal = JSON.parse(readFileSync(path, 'utf-8')) as Journal;
+ if (journal.schema_version !== JOURNAL_SCHEMA) {
+ throw new OperationError('skillpack_journal_not_found', `${path} is not a ${JOURNAL_SCHEMA} journal.`,
+ 'List the backups with gbrain skillpack restore --list.');
+ }
+ return journal;
+}
+
+/** Every readable journal, newest first. Unreadable entries are skipped. */
+export function listJournals(root = backupsRoot()): Journal[] {
+ if (!existsSync(root)) return [];
+ const out: Journal[] = [];
+ for (const id of readdirSync(root).sort().reverse()) {
+ try {
+ out.push(readJournal(id, root));
+ } catch { /* not a journal dir */ }
+ }
+ return out;
+}
+
+/** Journals a crash left `pending`, optionally only for one skills root. */
+export function pendingJournals(opts: { root?: string; skillsRoot?: string } = {}): Journal[] {
+ return listJournals(opts.root).filter(j => j.status === 'pending' && (!opts.skillsRoot || j.skills_root === opts.skillsRoot));
+}
+
+/** Keep journals younger than JOURNAL_KEEP_DAYS, the newest JOURNAL_KEEP_LAST, and every pending one. Returns the pruned ids. */
+export function pruneJournals(root = backupsRoot(), now = Date.now()): string[] {
+ const pruned: string[] = [];
+ listJournals(root).forEach((journal, index) => {
+ const age = now - Date.parse(journal.created_at);
+ if (journal.status === 'pending' || index < JOURNAL_KEEP_LAST || age < JOURNAL_KEEP_DAYS * 86_400_000) return;
+ rmSync(journalDir(journal.id, root), { recursive: true, force: true });
+ pruned.push(journal.id);
+ });
+ return pruned;
+}
+
+/** Copy `target` into the journal's backup tree and verify the copy hashes to `expected`. */
+export function backupFile(journalId: string, rel: string, target: string, expected: string, root = backupsRoot()): string {
+ const backupRel = `files/${rel}`;
+ const dest = join(journalDir(journalId, root), backupRel);
+ mkdirSync(dirname(dest), { recursive: true });
+ copyFileSync(target, dest);
+ if (sha256(readFileSync(dest)) !== expected) throw new Error(`${rel} changed while it was being backed up`);
+ return backupRel;
+}
+
+/** Atomically put `bytes` at `target` (temp file in the same directory, then rename). */
+export function replaceFile(target: string, bytes: Buffer): void {
+ assertLegacySkillFilesystemWrite(target);
+ mkdirSync(dirname(target), { recursive: true });
+ const tmp = join(dirname(target), `.gbrain-skillpack-${process.pid}-${randomUUID()}.tmp`);
+ writeFileSync(tmp, bytes);
+ try {
+ renameSync(tmp, target);
+ } catch (err) {
+ rmSync(tmp, { force: true });
+ throw err;
+ }
+}
+
+/**
+ * Undo one applied file if it still holds the update's bytes: restore the
+ * backup, or remove a file the update created. Returns false (and leaves the
+ * file) when it changed since the update.
+ */
+export function undoFile(journalId: string, skillsRoot: string, file: JournalFile, root = backupsRoot()): boolean {
+ const target = confinedSkillChildWrite(skillsRoot, file.rel);
+ if (hashTarget(target) !== file.post) return false;
+ if (file.pre === null || file.backup === null) {
+ unlinkSync(target);
+ return true;
+ }
+ const bytes = readFileSync(join(journalDir(journalId, root), file.backup));
+ if (sha256(bytes) !== file.pre) {
+ throw new OperationError('skillpack_backup_corrupt', `The backup of ${file.rel} in ${journalId} does not hash to the journal's pre-update hash.`,
+ `Leave ${file.rel} as it is, or compare it with the bundle using gbrain skillpack reference <skill>.`);
+ }
+ replaceFile(target, bytes);
+ return true;
+}
+
+export interface RestorePlanFile {
+ slug: string;
+ rel: string;
+ action: 'restore' | 'remove' | 'already_restored' | 'skipped' | 'conflict';
+}
+
+/** What restore would do with each applied file. Pure read. */
+export function planRestore(journal: Journal, skip: ReadonlySet<string>): RestorePlanFile[] {
+ const out: RestorePlanFile[] = [];
+ for (const skill of journal.skills) {
+ if (skill.status !== 'applying' && skill.status !== 'committed' && skill.status !== 'restored') continue;
+ for (const file of skill.files) {
+ const current = hashTarget(confinedSkillChildWrite(journal.skills_root, file.rel, { dryRun: true }));
+ const action: RestorePlanFile['action'] = current === file.pre ? 'already_restored'
+ : skip.has(file.rel) ? 'skipped'
+ : current === file.post ? (file.pre === null ? 'remove' : 'restore')
+ : 'conflict';
+ out.push({ slug: skill.slug, rel: file.rel, action });
+ }
+ }
+ return out;
+}
diff --git a/src/core/skills-integrity.ts b/src/core/skills-integrity.ts
index 7db42ce3df..3b9582eb1f 100644
--- a/src/core/skills-integrity.ts
+++ b/src/core/skills-integrity.ts
@@ -72,3 +72,82 @@ export function verifySkillsManifest(dir: string, manifest: SkillsManifest): Ski
const extra = Object.keys(actual).filter((p) => !(p in manifest));
return { modified, missing, extra };
}
+
+/** Append-only record of every released hash of each bundled file; lives beside the lock, which records its hash. */
+export const SKILLS_LOCK_HISTORY_FILENAME = 'skills.lock.history.json';
+export const SKILLS_LOCK_HISTORY_SCHEMA = 'gbrain-skills-lock-history-v1';
+
+export interface SkillsLockHistory {
+ schema_version: typeof SKILLS_LOCK_HISTORY_SCHEMA;
+ /** Skills-relative posix path → every released sha256 of that file, sorted. */
+ files: Record<string, string[]>;
+}
+
+export function parseSkillsLockHistory(text: string): SkillsLockHistory {
+ const raw = JSON.parse(text) as Partial<SkillsLockHistory>;
+ if (raw?.schema_version !== SKILLS_LOCK_HISTORY_SCHEMA || typeof raw.files !== 'object' || raw.files === null || Array.isArray(raw.files)) {
+ throw new Error(`${SKILLS_LOCK_HISTORY_FILENAME} is not a ${SKILLS_LOCK_HISTORY_SCHEMA} document`);
+ }
+ for (const [path, hashes] of Object.entries(raw.files)) {
+ if (!Array.isArray(hashes) || !hashes.every(h => typeof h === 'string' && /^[0-9a-f]{64}$/.test(h))) {
+ throw new Error(`${SKILLS_LOCK_HISTORY_FILENAME}: ${path} must list sha256 hex digests`);
+ }
+ }
+ return { schema_version: SKILLS_LOCK_HISTORY_SCHEMA, files: raw.files as Record<string, string[]> };
+}
+
+/** Union of `history` and the lock's hashes (the lock's own entry for the history file is skipped). Sorted, deterministic. */
+export function mergeSkillsLockHistory(history: SkillsLockHistory | null, lock: SkillsManifest): SkillsLockHistory {
+ const merged = new Map<string, Set<string>>();
+ for (const [path, hashes] of Object.entries(history?.files ?? {})) merged.set(path, new Set(hashes));
+ for (const [path, hash] of Object.entries(lock)) {
+ if (path === SKILLS_LOCK_HISTORY_FILENAME) continue;
+ (merged.get(path) ?? merged.set(path, new Set()).get(path)!).add(hash);
+ }
+ const files: Record<string, string[]> = {};
+ for (const path of [...merged.keys()].sort()) files[path] = [...merged.get(path)!].sort();
+ return { schema_version: SKILLS_LOCK_HISTORY_SCHEMA, files };
+}
+
+export function renderSkillsLockHistory(history: SkillsLockHistory): string {
+ return JSON.stringify(history, null, 2) + '\n';
+}
+
+/** Every (path, hash) in `previous` that `current` dropped: the append-only contract's violations. */
+export function droppedHistoryEntries(previous: SkillsLockHistory, current: SkillsLockHistory): string[] {
+ const dropped: string[] = [];
+ for (const [path, hashes] of Object.entries(previous.files)) {
+ const kept = new Set(current.files[path] ?? []);
+ for (const hash of hashes) if (!kept.has(hash)) dropped.push(`${path} ${hash}`);
+ }
+ return dropped;
+}
+
+export type VerifiedSkillsLockHistory =
+ | { ok: true; history: SkillsLockHistory }
+ | { ok: false; reason: string };
+
+/**
+ * Read the history beside `skillsDir`'s lock and verify its sha256 against
+ * the lock's entry for it. Corruption detection only: a missing lock, a
+ * missing history, a hash mismatch or an unparseable file is `ok: false`.
+ */
+export function loadVerifiedSkillsLockHistory(skillsDir: string): VerifiedSkillsLockHistory {
+ let lock: SkillsManifest;
+ let bytes: Buffer;
+ try {
+ lock = JSON.parse(readFileSync(join(skillsDir, SKILLS_MANIFEST_FILENAME), 'utf-8')) as SkillsManifest;
+ bytes = readFileSync(join(skillsDir, SKILLS_LOCK_HISTORY_FILENAME));
+ } catch (err) {
+ return { ok: false, reason: `cannot read ${SKILLS_MANIFEST_FILENAME} or ${SKILLS_LOCK_HISTORY_FILENAME}: ${(err as Error).message}` };
+ }
+ const expected = lock[SKILLS_LOCK_HISTORY_FILENAME];
+ const actual = createHash('sha256').update(bytes).digest('hex');
+ if (!expected) return { ok: false, reason: `${SKILLS_MANIFEST_FILENAME} records no hash for ${SKILLS_LOCK_HISTORY_FILENAME}` };
+ if (expected !== actual) return { ok: false, reason: `${SKILLS_LOCK_HISTORY_FILENAME} sha256 ${actual.slice(0, 12)} does not match the lock's ${expected.slice(0, 12)}` };
+ try {
+ return { ok: true, history: parseSkillsLockHistory(bytes.toString('utf-8')) };
+ } catch (err) {
+ return { ok: false, reason: (err as Error).message };
+ }
+}
diff --git a/test/cli-flag-equals.test.ts b/test/cli-flag-equals.test.ts
index 8e1f4c413b..a51221ff5c 100644
--- a/test/cli-flag-equals.test.ts
+++ b/test/cli-flag-equals.test.ts
@@ -324,6 +324,7 @@ describe('#7619 split rules', () => {
'src/commands/skillpack.ts': ['skillpack status', 'skillpack sync', 'skillpack migrate-fence', 'skillpack scrub-legacy-fence-rows', 'skillpack harvest', 'skillpack diff'],
'src/commands/skillpack/harness.ts': ['skillpack scaffold', 'skillpack reference'], // also the OWN parser of skillpack remove
'src/commands/skillpack/reference.ts': ['skillpack reference'],
+ 'src/commands/skillpack/update.ts': ['skillpack reference'],
'src/commands/skillpack/scaffold.ts': ['skillpack scaffold'],
'src/commands/sources-harden.ts': ['sources harden', 'sources pull'], // *
'src/commands/sources.ts': ['sources status'], // * (paged regex :1214)
diff --git a/test/fixtures/goldens/doctor/registry-build-checks.json b/test/fixtures/goldens/doctor/registry-build-checks.json
index 62f403be06..656887b24c 100644
--- a/test/fixtures/goldens/doctor/registry-build-checks.json
+++ b/test/fixtures/goldens/doctor/registry-build-checks.json
@@ -37,6 +37,14 @@
"category": "skill",
"name": "skill_preconditions"
},
+ {
+ "category": "skill",
+ "name": "skillpack_update_incomplete"
+ },
+ {
+ "category": "skill",
+ "name": "skillpack_backups"
+ },
{
"category": "ops",
"name": "plugin_lane_collision"
diff --git a/test/fixtures/goldens/exports/types.json b/test/fixtures/goldens/exports/types.json
index 2e3df1bd62..45b50c410a 100644
--- a/test/fixtures/goldens/exports/types.json
+++ b/test/fixtures/goldens/exports/types.json
@@ -6478,7 +6478,7 @@
{
"kind": "class",
"members": [
- "canonical?: \"unknown\" | \"keyword_candidates_incomplete\" | \"projection_pending\" | \"timeout\" | \"rate_limited\" | \"embedding_disabled\" | \"writer_lock_unavailable\" | \"writer_pool_capacity\" | \"owner_unavailable\" | \"recovery_required\" | \"queue_capacity\" | \"write_quota_exhausted\" | \"write_quota_insufficient\" | \"write_capacity_backpressure\" | \"revision_required\" | \"revision_conflict\" | \"idempotency_conflict\" | \"source_changed\" | \"write_pending\" | \"storage_error\" | \"cancelled\" | \"permission_denied\" | \"scope_denied\" | \"invalid_params\" | \"not_found\" | \"page_not_found\" | \"page_identity_changed\" | \"write_claim_lost\" | \"request_too_large\" | \"response_too_large\" | \"writer_registration_required\" | \"writer_identity_invalid\" | \"writer_not_initialized\" | \"writer_coordinator_required\" | \"fact_already_expired\" | \"source_writeback_required\" | \"unsupported_mutation_protocol\" | \"writer_upgrade_required\" | \"writer_not_quiesced\" | \"skill_bundle_required\" | \"take_row_collision\" | \"invalid_source_uri\" | \"writer_admin_locked\" | \"connector_account_changed\" | \"connector_intent_outdated\" | \"checkpoint_validation_timeout\" | \"invalid_connector_text\" | \"connector_holds_exhausted\" | \"connector_fence_below_timeline\" | \"core_budget_exceeded\" | \"core_mark_owner_only\" | \"core_remote_edit_refused\" | \"core_delete_owner_only\" | \"timeline_rows_would_be_removed\" | \"purged_content\" | \"preparation_stalled\" | \"fence_unrenderable\" | \"page_body_segmented\" | \"revision_changed\" | \"tail_changed\" | \"write_outcome_unknown\" | \"write_interrupted\" | \"connection_inherited_read_only\" | \"embedding_failed\" | \"bucket_not_found\" | \"database_error\" | \"unknown_transport\" | \"extraction_failed\" | \"fact_not_found\" | \"provenance_required\" | \"unavailable\" | \"budget_unsatisfiable\" | \"embedding_budget_below_worst_case\" | \"absent_from_worktree\" | \"access_command_failed\" | \"access_denied_test_user\" | \"access_env_missing\" | \"acknowledgment_unavailable\" | \"admin_policy_enforced\" | \"admission_paused\" | \"ambient_capture_off\" | \"ambiguous_id\" | \"ambiguous_ref\" | \"ambiguous_skill\" | \"answer_not_yours\" | \"answer_pending\" | \"answer_unavailable\" | \"api_not_enabled\" | \"approval_required\" | \"atom_drain_incomplete\" | \"atom_drain_no_progress\" | \"atom_drain_provider_failure\" | \"autopilot_job_owned_by_other_brain\" | \"body_staging_expired\" | \"budget_below_recent_runtime\" | \"backup_dump_failed\" | \"backup_too_large\" | \"belief_coverage_required\" | \"belief_stale_preparation\" | \"benchmark_duplicate_task_id\" | \"benchmark_empty\" | \"benchmark_exists\" | \"benchmark_judge_llm_no_rubric\" | \"benchmark_judge_qrels_no_expected\" | \"benchmark_judge_rule_no_checks\" | \"benchmark_judge_unknown_kind\" | \"benchmark_malformed\" | \"benchmark_missing_judge\" | \"benchmark_missing_task\" | \"benchmark_missing_task_id\" | \"benchmark_not_found\" | \"benchmark_rule_check_bad_arg\" | \"benchmark_rule_check_malformed\" | \"benchmark_rule_check_unknown_op\" | \"bootstrap_cleanup_pending\" | \"bootstrap_empty\" | \"bootstrap_pending_review\" | \"bridge_ownership_conflict\" | \"coverage_from\" | \"coverage_gap\" | \"clock_mismatch\" | \"extract_write_lost\" | \"item_failures_systemic\" | \"known_as_of_unproven\" | \"cache_quota_exceeded\" | \"calendar_unreadable\" | \"capacity_paused\" | \"catalog_capacity_exceeded\" | \"catalog_unavailable\" | \"changed_since_preview\" | \"chronicle_skipped\" | \"no_pricing\" | \"checkpoint_missing\" | \"claim_already_used\" | \"client_json_unreadable\" | \"client_json_wrong_type\" | \"client_not_found\" | \"client_shape_invalid\" | \"code_callees_requires_symbol\" | \"code_callers_requires_symbol\" | \"code_def_requires_symbol\" | \"code_refs_requires_symbol\" | \"code_reused\" | \"colon_slug_windows_write_through\" | \"command_failed\" | \"commit_lock_busy\" | \"commit_paths_invalid\" | \"commit_prestaged_paths\" | \"commit_outside_source_root\" | \"concurrent_write\" | \"config_error\" | \"confirmation_required\" | \"conflicting_source_scope\" | \"connection_lost\" | \"chunkless_pages_healable\" | \"consent_required\" | \"consent_timeout\" | \"consumers_without_heartbeat\" | \"content_repair_needs_human\" | \"content_null_bytes\" | \"content_rejected\" | \"continuation_unproven\" | \"corpus_chat_unavailable\" | \"corpus_window_backoff\" | \"corpus_window_dead_lettered\" | \"convergence_read_failed\" | \"cost_cap_exceeded\" | \"cost_preview_requires_yes\" | \"cursor_incarnation_retired\" | \"cycle_failed\" | \"d_sel_too_small\" | \"delta_cursor_upgrade_required\" | \"deleted_page_chunks_overdue\" | \"demo_graph_failed\" | \"demo_import_failed\" | \"demo_verification_failed\" | \"derived_cap_exhausted\" | \"destination_not_ready\" | \"drain_holder_stalled\" | \"drain_stalled\" | \"managed_sync_not_moving\" | \"dream_breaker_tripped\" | \"dirty_tree\" | \"doctor_tier_unavailable\" | \"effect_not_failed\" | \"embed_backfill_stalled\" | \"embedding_auth_failed\" | \"embedding_configuration\" | \"embedding_identity_unqualified\" | \"embedding_model_mismatch\" | \"embedding_plane_split\" | \"embedding_state_unknown\" | \"embedding_storage_unavailable\" | \"embedding_unavailable\" | \"embedding_unconfigured\" | \"embedding_width_mismatch\" | \"engine_graduated\" | \"entity_types_unavailable\" | \"eval_suite_unwired\" | \"export_limit\" | \"extractor_identity_mismatch\" | \"fact_withdrawn\" | \"fact_rows_collide\" | \"fence_row_changed\" | \"facts_absorb_write_refused\" | \"facts_backstop_skipped\" | \"facts_drain_deferred\" | \"facts_drain_job_failed\" | \"facts_payload_expired\" | \"feedback_disabled\" | \"feedback_not_authorized\" | \"fetch_failed\" | \"file_database_drift\" | \"fix_not_writable\" | \"file_drift\" | \"file_drift_mixed_selection\" | \"file_drift_state_required\" | \"file_removed_during_scan\" | \"file_unreadable\" | \"file_too_large\" | \"follow_approval_required\" | \"forget_requires_owner\" | \"reserved_frontmatter_key\" | \"generation_fenced\" | \"generation_held\" | \"generation_live_conflict\" | \"frontmatter_slug_conflict\" | \"full_resync_required\" | \"gate_failed\" | \"ghost_mass_delete_refused\" | \"notifier_stalled\" | \"origin_twin_mass_merge_refused\" | \"ghost_storage_unknown\" | \"git_branch_unborn\" | \"git_durability_not_enabled\" | \"git_checkout_required\" | \"git_worktree_link_broken\" | \"hosted_repo_refused\" | \"git_detached_head\" | \"git_index_conflict\" | \"git_index_locked\" | \"git_index_stale\" | \"git_target_pending\" | \"git_operation_in_progress\" | \"git_push_unavailable\" | \"git_target_changed\" | \"git_target_ignored\" | \"git_target_unsafe\" | \"git_unavailable\" | \"git_object_missing\" | \"git_conversion_blocked\" | \"git_conversion_incomplete\" | \"git_home_required\" | \"git_private_commit_refused\" | \"git_protocol_required\" | \"git_lfs_not_enabled\" | \"gitlink_not_followed\" | \"graduation_drain_timeout\" | \"graduation_embedding_dimension_mismatch\" | \"graduation_foreign_host_binding\" | \"graduation_in_progress\" | \"graduation_interrupted\" | \"graduation_rollback_writes_lost\" | \"graduation_source_writer_held\" | \"graduation_split_brain\" | \"graduation_target_auth_failed\" | \"graduation_target_ddl_unreachable\" | \"graduation_target_not_empty\" | \"graduation_target_unsupported\" | \"graduation_unclassified_table\" | \"graduation_unsupported_platform\" | \"graduation_verify_failed\" | \"grant_scope\" | \"graph_incomplete\" | \"host_identity_mismatch\" | \"harness_hook_duplicates\" | \"harness_hook_unowned\" | \"head_blocked\" | \"held_failed\" | \"held_out_overlaps_benchmark\" | \"held_out_required_for_bundled\" | \"independent_principal_required\" | \"insufficient_scope\" | \"integrate_conflict\" | \"internal\" | \"internal_error\" | \"interrupted\" | \"invalid_acknowledgment\" | \"invalid_client\" | \"invalid_fence\" | \"unclosed_ambiguous_tail\" | \"tail_exposure_approval\" | \"sync_in_progress\" | \"invalid_frontmatter\" | \"invalid_grant_clock_skew\" | \"invalid_grant_revoked\" | \"invalid_grant_testing_expiry\" | \"invalid_rating\" | \"invalid_receipt\" | \"invalid_receipt_transition\" | \"invalid_request\" | \"invalid_source\" | \"invalid_source_pin\" | \"invalid_token\" | \"invalid_write_wait\" | \"ipc_path_too_long\" | \"legacy_twin_mass_merge_refused\" | \"legacy_twins_storage_unknown\" | \"legacy_job_selection_invalid\" | \"legacy_jobs_active\" | \"legacy_lock_removal_refused\" | \"link_cursor_invalid\" | \"local_conflict\" | \"lock_busy\" | \"loops_extraction_skipped\" | \"maintenance_backpressure\" | \"maintenance_lock_busy\" | \"managed_failure_unsettled\" | \"managed_remedy_unavailable\" | \"merge_recommended\" | \"movement_unknown\" | \"managed_sync_flag_refused\" | \"managed_pull_skipped\" | \"manual_only_skipped\" | \"membership_inactive\" | \"membership_not_found\" | \"method_not_allowed\" | \"migration_lease_lost\" | \"migration_declined\" | \"migration_failed\" | \"migration_host_work_pending\" | \"migrations_pending\" | \"migrations_running\" | \"missing_source_scope\" | \"missing_source_value\" | \"models_strict_violation\" | \"no_context_ceiling\" | \"no_refresh_token\" | \"no_routing_eval\" | \"no_skill_md\" | \"no_worker\" | \"no_worker_surface\" | \"not_a_git_repo\" | \"not_converged\" | \"not_owner_host\" | \"not_connected\" | \"no_brain\" | \"overlapping_path\" | \"page_projection_conflict\" | \"page_body_rows_unreadable\" | \"page_projection_stale\" | \"page_shrink_refused\" | \"page_too_large_for_inline\" | \"parse_error\" | \"part_splits_code_point\" | \"part_too_large\" | \"frontmatter_alias_limit\" | \"parser_regression\" | \"pasted_wrong_url\" | \"payload_too_large\" | \"path_not_utf8\" | \"pattern_claims_pending\" | \"patterns_min_interval\" | \"pending_verify\" | \"pending_writes\" | \"persistence_restart_required\" | \"pool_inflight_over_budget\" | \"deep_health_probe_failed\" | \"refresh_required\" | \"serve_self_exit_suppressed\" | \"serve_unhealthy_exit\" | \"persistence_write_stall\" | \"push_unconfirmed\" | \"schema_lock_blocked\" | \"pg_connection_recovery_failed\" | \"pg_connection_stuck\" | \"pg_pool_stalled\" | \"pg_statement_build_failed\" | \"pglite_busy\" | \"pglite_vector_index_too_large\" | \"plan_output_failed\" | \"plan_stale\" | \"port_in_use\" | \"preview_changed\" | \"profile_incompatible\" | \"projection_owner_resident\" | \"knock_on_exhausted\" | \"keyword_skipped_after_timeout\" | \"publication_pending\" | \"pull_blocked_local_changes\" | \"purge_blocked_pending_recovery\" | \"purge_lookup_timeout\" | \"purge_mirror_unwritable\" | \"question_not_found\" | \"question_owner_only\" | \"rank_entities_timeout\" | \"read_budget_exhausted\" | \"receipt_conflict\" | \"receipt_fence_changed\" | \"receipt_fence_required\" | \"receipt_identity_mismatch\" | \"pat_file_unreadable\" | \"reconcile_host_required\" | \"reconcile_read_incomplete\" | \"recovery_prior_stage_unavailable\" | \"recovery_version_unsupported\" | \"redirect_uri_mismatch\" | \"ref_not_in_answer\" | \"refresh_dirty\" | \"refresh_diverged\" | \"refresh_drain_timeout\" | \"refresh_no_upstream\" | \"refresh_not_managed\" | \"refresh_not_owner\" | \"refresh_source_changed\" | \"relay_disabled\" | \"relay_session_expired\" | \"relay_unreachable\" | \"rename_held\" | \"rename_identity_unreadable\" | \"rename_reconcile_failed\" | \"request_already_submitted\" | \"requirements_changed\" | \"requires_local_engine\" | \"restart_refused\" | \"restart_unverified\" | \"runtime_build_skew\" | \"reset_upstream_refused\" | \"resume_spec_mismatch\" | \"result_too_large\" | \"revision_unavailable\" | \"schema_owner_required\" | \"scope_missing\" | \"search_cursor_requires_keyword\" | \"search_mode_local_only\" | \"scorecard_group_by_local_only\" | \"search_offset_over_cap\" | \"segmented_mirror_writer_gate\" | \"serve_build_drift\" | \"serve_port_in_use\" | \"serve_status_only\" | \"settle_mismatch\" | \"setup_harness_unsupported\" | \"setup_hosted_connection\" | \"setup_owner_conflict\" | \"shared_skills_unavailable\" | \"shared_skills_unsupported\" | \"skill_asset_not_found\" | \"skill_candidate_invalid\" | \"skill_not_found\" | \"skill_retention_capacity\" | \"skill_unavailable\" | \"slug_page_mismatch\" | \"slug_root_mode_mismatch\" | \"source_binding_required\" | \"source_id_taken\" | \"source_mismatch\" | \"source_not_ready\" | \"source_profile_no_backfill\" | \"source_referenced\" | \"source_root_conflict\" | \"split_bad_ratio\" | \"split_unparseable\" | \"stable_channel_unresolved\" | \"stale_unavailable\" | \"state_mismatch\" | \"strict_requires_managed\" | \"sync_anchor_relative\" | \"sync_not_applicable\" | \"sync_admission_restricted\" | \"sync_deadline_stalled\" | \"sync_drain_lease_held\" | \"content_receipt_stale\" | \"sync_first_run_in_progress\" | \"sync_no_successful_sync\" | \"sync_cursor_replaced\" | \"sync_pass_superseded\" | \"sync_parser_regression\" | \"target_escape\" | \"timeline_comment_markup\" | \"topology_change_required\" | \"transcript_secret_exposure\" | \"triage_unreliable_backoff\" | \"trust_raise_refused\" | \"two_consumers_on_host\" | \"trusted_local_only\" | \"unexpected_file_bytes\" | \"unexpected_staging_bytes\" | \"unknown_command\" | \"unknown_flag\" | \"unknown_method\" | \"unknown_source\" | \"unknown_tool\" | \"unpriced_model\" | \"unmanaged_database_path\" | \"unmanaged_path\" | \"unsupported_export_data\" | \"unsupported_path\" | \"upload_expired\" | \"upload_not_found\" | \"upload_protected_content\" | \"upload_too_many_parts\" | \"upstream\" | \"upstream_diverged\" | \"upstream_rewritten\" | \"upstream_unknown\" | \"vector_prewarm_extension_missing\" | \"vector_prewarm_unsupported_engine\" | \"vector_prewarm_wont_fit\" | \"verification_failed\" | \"withdrawal_capacity\" | \"withdrawal_mirror_failed\" | \"withdrawal_mirror_pending\" | \"withdrawal_provenance\" | \"write_capacity_low\" | \"write_gate_rejected\" | \"write_held\" | \"worktree_dirty\" | \"writer_admin_intent_required\" | \"writer_admin_state_changed\" | \"writer_busy\" | \"writer_identity_publish_failed\" | \"writer_manifest_mismatch\" | \"writer_manifest_rescope_required\" | \"writer_manifest_unsafe\" | \"writer_regrant_required\" | \"writer_transfer_conflict\" | \"writer_transfer_required\" | \"wrong_account_consented\" | \"schema_pack_too_large\" | \"schema_pack_emit_mismatch\" | undefined",
+ "canonical?: \"unknown\" | \"keyword_candidates_incomplete\" | \"projection_pending\" | \"timeout\" | \"rate_limited\" | \"embedding_disabled\" | \"writer_lock_unavailable\" | \"writer_pool_capacity\" | \"owner_unavailable\" | \"recovery_required\" | \"queue_capacity\" | \"write_quota_exhausted\" | \"write_quota_insufficient\" | \"write_capacity_backpressure\" | \"revision_required\" | \"revision_conflict\" | \"idempotency_conflict\" | \"source_changed\" | \"write_pending\" | \"storage_error\" | \"cancelled\" | \"permission_denied\" | \"scope_denied\" | \"invalid_params\" | \"not_found\" | \"page_not_found\" | \"page_identity_changed\" | \"write_claim_lost\" | \"request_too_large\" | \"response_too_large\" | \"writer_registration_required\" | \"writer_identity_invalid\" | \"writer_not_initialized\" | \"writer_coordinator_required\" | \"fact_already_expired\" | \"source_writeback_required\" | \"unsupported_mutation_protocol\" | \"writer_upgrade_required\" | \"writer_not_quiesced\" | \"skill_bundle_required\" | \"take_row_collision\" | \"invalid_source_uri\" | \"writer_admin_locked\" | \"connector_account_changed\" | \"connector_intent_outdated\" | \"checkpoint_validation_timeout\" | \"invalid_connector_text\" | \"connector_holds_exhausted\" | \"connector_fence_below_timeline\" | \"core_budget_exceeded\" | \"core_mark_owner_only\" | \"core_remote_edit_refused\" | \"core_delete_owner_only\" | \"timeline_rows_would_be_removed\" | \"purged_content\" | \"preparation_stalled\" | \"fence_unrenderable\" | \"page_body_segmented\" | \"revision_changed\" | \"tail_changed\" | \"write_outcome_unknown\" | \"write_interrupted\" | \"connection_inherited_read_only\" | \"embedding_failed\" | \"bucket_not_found\" | \"database_error\" | \"unknown_transport\" | \"extraction_failed\" | \"fact_not_found\" | \"provenance_required\" | \"unavailable\" | \"budget_unsatisfiable\" | \"embedding_budget_below_worst_case\" | \"absent_from_worktree\" | \"access_command_failed\" | \"access_denied_test_user\" | \"access_env_missing\" | \"acknowledgment_unavailable\" | \"admin_policy_enforced\" | \"admission_paused\" | \"ambient_capture_off\" | \"ambiguous_id\" | \"ambiguous_ref\" | \"ambiguous_skill\" | \"answer_not_yours\" | \"answer_pending\" | \"answer_unavailable\" | \"api_not_enabled\" | \"approval_required\" | \"atom_drain_incomplete\" | \"atom_drain_no_progress\" | \"atom_drain_provider_failure\" | \"autopilot_job_owned_by_other_brain\" | \"body_staging_expired\" | \"budget_below_recent_runtime\" | \"backup_dump_failed\" | \"backup_too_large\" | \"belief_coverage_required\" | \"belief_stale_preparation\" | \"benchmark_duplicate_task_id\" | \"benchmark_empty\" | \"benchmark_exists\" | \"benchmark_judge_llm_no_rubric\" | \"benchmark_judge_qrels_no_expected\" | \"benchmark_judge_rule_no_checks\" | \"benchmark_judge_unknown_kind\" | \"benchmark_malformed\" | \"benchmark_missing_judge\" | \"benchmark_missing_task\" | \"benchmark_missing_task_id\" | \"benchmark_not_found\" | \"benchmark_rule_check_bad_arg\" | \"benchmark_rule_check_malformed\" | \"benchmark_rule_check_unknown_op\" | \"bootstrap_cleanup_pending\" | \"bootstrap_empty\" | \"bootstrap_pending_review\" | \"bridge_ownership_conflict\" | \"coverage_from\" | \"coverage_gap\" | \"clock_mismatch\" | \"extract_write_lost\" | \"item_failures_systemic\" | \"known_as_of_unproven\" | \"cache_quota_exceeded\" | \"calendar_unreadable\" | \"capacity_paused\" | \"catalog_capacity_exceeded\" | \"catalog_unavailable\" | \"changed_since_preview\" | \"chronicle_skipped\" | \"no_pricing\" | \"checkpoint_missing\" | \"claim_already_used\" | \"client_json_unreadable\" | \"client_json_wrong_type\" | \"client_not_found\" | \"client_shape_invalid\" | \"code_callees_requires_symbol\" | \"code_callers_requires_symbol\" | \"code_def_requires_symbol\" | \"code_refs_requires_symbol\" | \"code_reused\" | \"colon_slug_windows_write_through\" | \"command_failed\" | \"commit_lock_busy\" | \"commit_paths_invalid\" | \"commit_prestaged_paths\" | \"commit_outside_source_root\" | \"concurrent_write\" | \"config_error\" | \"confirmation_required\" | \"conflicting_source_scope\" | \"connection_lost\" | \"chunkless_pages_healable\" | \"consent_required\" | \"consent_timeout\" | \"consumers_without_heartbeat\" | \"content_repair_needs_human\" | \"content_null_bytes\" | \"content_rejected\" | \"continuation_unproven\" | \"corpus_chat_unavailable\" | \"corpus_window_backoff\" | \"corpus_window_dead_lettered\" | \"convergence_read_failed\" | \"cost_cap_exceeded\" | \"cost_preview_requires_yes\" | \"cursor_incarnation_retired\" | \"cycle_failed\" | \"d_sel_too_small\" | \"delta_cursor_upgrade_required\" | \"deleted_page_chunks_overdue\" | \"demo_graph_failed\" | \"demo_import_failed\" | \"demo_verification_failed\" | \"derived_cap_exhausted\" | \"destination_not_ready\" | \"drain_holder_stalled\" | \"drain_stalled\" | \"managed_sync_not_moving\" | \"dream_breaker_tripped\" | \"dirty_tree\" | \"doctor_tier_unavailable\" | \"effect_not_failed\" | \"embed_backfill_stalled\" | \"embedding_auth_failed\" | \"embedding_configuration\" | \"embedding_identity_unqualified\" | \"embedding_model_mismatch\" | \"embedding_plane_split\" | \"embedding_state_unknown\" | \"embedding_storage_unavailable\" | \"embedding_unavailable\" | \"embedding_unconfigured\" | \"embedding_width_mismatch\" | \"engine_graduated\" | \"entity_types_unavailable\" | \"eval_suite_unwired\" | \"export_limit\" | \"extractor_identity_mismatch\" | \"fact_withdrawn\" | \"fact_rows_collide\" | \"fence_row_changed\" | \"facts_absorb_write_refused\" | \"facts_backstop_skipped\" | \"facts_drain_deferred\" | \"facts_drain_job_failed\" | \"facts_payload_expired\" | \"feedback_disabled\" | \"feedback_not_authorized\" | \"fetch_failed\" | \"file_database_drift\" | \"fix_not_writable\" | \"file_drift\" | \"file_drift_mixed_selection\" | \"file_drift_state_required\" | \"file_removed_during_scan\" | \"file_unreadable\" | \"file_too_large\" | \"follow_approval_required\" | \"forget_requires_owner\" | \"reserved_frontmatter_key\" | \"generation_fenced\" | \"generation_held\" | \"generation_live_conflict\" | \"frontmatter_slug_conflict\" | \"full_resync_required\" | \"gate_failed\" | \"ghost_mass_delete_refused\" | \"notifier_stalled\" | \"origin_twin_mass_merge_refused\" | \"ghost_storage_unknown\" | \"git_branch_unborn\" | \"git_durability_not_enabled\" | \"git_checkout_required\" | \"git_worktree_link_broken\" | \"hosted_repo_refused\" | \"git_detached_head\" | \"git_index_conflict\" | \"git_index_locked\" | \"git_index_stale\" | \"git_target_pending\" | \"git_operation_in_progress\" | \"git_push_unavailable\" | \"git_target_changed\" | \"git_target_ignored\" | \"git_target_unsafe\" | \"git_unavailable\" | \"git_object_missing\" | \"git_conversion_blocked\" | \"git_conversion_incomplete\" | \"git_home_required\" | \"git_private_commit_refused\" | \"git_protocol_required\" | \"git_lfs_not_enabled\" | \"gitlink_not_followed\" | \"graduation_drain_timeout\" | \"graduation_embedding_dimension_mismatch\" | \"graduation_foreign_host_binding\" | \"graduation_in_progress\" | \"graduation_interrupted\" | \"graduation_rollback_writes_lost\" | \"graduation_source_writer_held\" | \"graduation_split_brain\" | \"graduation_target_auth_failed\" | \"graduation_target_ddl_unreachable\" | \"graduation_target_not_empty\" | \"graduation_target_unsupported\" | \"graduation_unclassified_table\" | \"graduation_unsupported_platform\" | \"graduation_verify_failed\" | \"grant_scope\" | \"graph_incomplete\" | \"host_identity_mismatch\" | \"harness_hook_duplicates\" | \"harness_hook_unowned\" | \"head_blocked\" | \"held_failed\" | \"held_out_overlaps_benchmark\" | \"held_out_required_for_bundled\" | \"independent_principal_required\" | \"insufficient_scope\" | \"integrate_conflict\" | \"internal\" | \"internal_error\" | \"interrupted\" | \"invalid_acknowledgment\" | \"invalid_client\" | \"invalid_fence\" | \"unclosed_ambiguous_tail\" | \"tail_exposure_approval\" | \"sync_in_progress\" | \"invalid_frontmatter\" | \"invalid_grant_clock_skew\" | \"invalid_grant_revoked\" | \"invalid_grant_testing_expiry\" | \"invalid_rating\" | \"invalid_receipt\" | \"invalid_receipt_transition\" | \"invalid_request\" | \"invalid_source\" | \"invalid_source_pin\" | \"invalid_token\" | \"invalid_write_wait\" | \"ipc_path_too_long\" | \"legacy_twin_mass_merge_refused\" | \"legacy_twins_storage_unknown\" | \"legacy_job_selection_invalid\" | \"legacy_jobs_active\" | \"legacy_lock_removal_refused\" | \"link_cursor_invalid\" | \"local_conflict\" | \"lock_busy\" | \"loops_extraction_skipped\" | \"maintenance_backpressure\" | \"maintenance_lock_busy\" | \"managed_failure_unsettled\" | \"managed_remedy_unavailable\" | \"merge_recommended\" | \"movement_unknown\" | \"managed_sync_flag_refused\" | \"managed_pull_skipped\" | \"manual_only_skipped\" | \"membership_inactive\" | \"membership_not_found\" | \"method_not_allowed\" | \"migration_lease_lost\" | \"migration_declined\" | \"migration_failed\" | \"migration_host_work_pending\" | \"migrations_pending\" | \"migrations_running\" | \"missing_source_scope\" | \"missing_source_value\" | \"models_strict_violation\" | \"no_context_ceiling\" | \"no_refresh_token\" | \"no_routing_eval\" | \"no_skill_md\" | \"no_worker\" | \"no_worker_surface\" | \"not_a_git_repo\" | \"not_converged\" | \"not_owner_host\" | \"not_connected\" | \"no_brain\" | \"overlapping_path\" | \"page_projection_conflict\" | \"page_body_rows_unreadable\" | \"page_projection_stale\" | \"page_shrink_refused\" | \"page_too_large_for_inline\" | \"parse_error\" | \"part_splits_code_point\" | \"part_too_large\" | \"frontmatter_alias_limit\" | \"parser_regression\" | \"pasted_wrong_url\" | \"payload_too_large\" | \"path_not_utf8\" | \"pattern_claims_pending\" | \"patterns_min_interval\" | \"pending_verify\" | \"pending_writes\" | \"persistence_restart_required\" | \"pool_inflight_over_budget\" | \"deep_health_probe_failed\" | \"refresh_required\" | \"serve_self_exit_suppressed\" | \"serve_unhealthy_exit\" | \"persistence_write_stall\" | \"push_unconfirmed\" | \"schema_lock_blocked\" | \"pg_connection_recovery_failed\" | \"pg_connection_stuck\" | \"pg_pool_stalled\" | \"pg_statement_build_failed\" | \"pglite_busy\" | \"pglite_vector_index_too_large\" | \"plan_output_failed\" | \"plan_stale\" | \"port_in_use\" | \"preview_changed\" | \"profile_incompatible\" | \"projection_owner_resident\" | \"knock_on_exhausted\" | \"keyword_skipped_after_timeout\" | \"publication_pending\" | \"pull_blocked_local_changes\" | \"purge_blocked_pending_recovery\" | \"purge_lookup_timeout\" | \"purge_mirror_unwritable\" | \"question_not_found\" | \"question_owner_only\" | \"rank_entities_timeout\" | \"read_budget_exhausted\" | \"receipt_conflict\" | \"receipt_fence_changed\" | \"receipt_fence_required\" | \"receipt_identity_mismatch\" | \"pat_file_unreadable\" | \"reconcile_host_required\" | \"reconcile_read_incomplete\" | \"recovery_prior_stage_unavailable\" | \"recovery_version_unsupported\" | \"redirect_uri_mismatch\" | \"ref_not_in_answer\" | \"refresh_dirty\" | \"refresh_diverged\" | \"refresh_drain_timeout\" | \"refresh_no_upstream\" | \"refresh_not_managed\" | \"refresh_not_owner\" | \"refresh_source_changed\" | \"relay_disabled\" | \"relay_session_expired\" | \"relay_unreachable\" | \"rename_held\" | \"rename_identity_unreadable\" | \"rename_reconcile_failed\" | \"request_already_submitted\" | \"requirements_changed\" | \"requires_local_engine\" | \"restart_refused\" | \"restart_unverified\" | \"runtime_build_skew\" | \"reset_upstream_refused\" | \"resume_spec_mismatch\" | \"result_too_large\" | \"revision_unavailable\" | \"schema_owner_required\" | \"scope_missing\" | \"search_cursor_requires_keyword\" | \"search_mode_local_only\" | \"scorecard_group_by_local_only\" | \"search_offset_over_cap\" | \"segmented_mirror_writer_gate\" | \"serve_build_drift\" | \"serve_port_in_use\" | \"serve_status_only\" | \"settle_mismatch\" | \"setup_harness_unsupported\" | \"setup_hosted_connection\" | \"setup_owner_conflict\" | \"shared_skills_unavailable\" | \"shared_skills_unsupported\" | \"skill_asset_not_found\" | \"skill_candidate_invalid\" | \"skill_not_found\" | \"skill_retention_capacity\" | \"skill_unavailable\" | \"skillpack_backup_corrupt\" | \"skillpack_journal_not_found\" | \"skillpack_restore_conflict\" | \"skillpack_state_locked\" | \"skillpack_update_incomplete\" | \"skillpack_workspace_locked\" | \"slug_page_mismatch\" | \"slug_root_mode_mismatch\" | \"source_binding_required\" | \"source_id_taken\" | \"source_mismatch\" | \"source_not_ready\" | \"source_profile_no_backfill\" | \"source_referenced\" | \"source_root_conflict\" | \"split_bad_ratio\" | \"split_unparseable\" | \"stable_channel_unresolved\" | \"stale_unavailable\" | \"state_mismatch\" | \"strict_requires_managed\" | \"sync_anchor_relative\" | \"sync_not_applicable\" | \"sync_admission_restricted\" | \"sync_deadline_stalled\" | \"sync_drain_lease_held\" | \"content_receipt_stale\" | \"sync_first_run_in_progress\" | \"sync_no_successful_sync\" | \"sync_cursor_replaced\" | \"sync_pass_superseded\" | \"sync_parser_regression\" | \"target_escape\" | \"timeline_comment_markup\" | \"topology_change_required\" | \"transcript_secret_exposure\" | \"triage_unreliable_backoff\" | \"trust_raise_refused\" | \"two_consumers_on_host\" | \"trusted_local_only\" | \"unexpected_file_bytes\" | \"unexpected_staging_bytes\" | \"unknown_command\" | \"unknown_flag\" | \"unknown_method\" | \"unknown_source\" | \"unknown_tool\" | \"unpriced_model\" | \"unmanaged_database_path\" | \"unmanaged_path\" | \"unsupported_export_data\" | \"unsupported_path\" | \"upload_expired\" | \"upload_not_found\" | \"upload_protected_content\" | \"upload_too_many_parts\" | \"upstream\" | \"upstream_diverged\" | \"upstream_rewritten\" | \"upstream_unknown\" | \"vector_prewarm_extension_missing\" | \"vector_prewarm_unsupported_engine\" | \"vector_prewarm_wont_fit\" | \"verification_failed\" | \"withdrawal_capacity\" | \"withdrawal_mirror_failed\" | \"withdrawal_mirror_pending\" | \"withdrawal_provenance\" | \"write_capacity_low\" | \"write_gate_rejected\" | \"write_held\" | \"worktree_dirty\" | \"writer_admin_intent_required\" | \"writer_admin_state_changed\" | \"writer_busy\" | \"writer_identity_publish_failed\" | \"writer_manifest_mismatch\" | \"writer_manifest_rescope_required\" | \"writer_manifest_unsafe\" | \"writer_regrant_required\" | \"writer_transfer_conflict\" | \"writer_transfer_required\" | \"wrong_account_consented\" | \"schema_pack_too_large\" | \"schema_pack_emit_mismatch\" | undefined",
"canonicalCode: string",
"cause?: unknown",
"code: ErrorCode",
diff --git a/test/skillpack-safe-update.test.ts b/test/skillpack-safe-update.test.ts
new file mode 100644
index 0000000000..8204e23e62
--- /dev/null
+++ b/test/skillpack-safe-update.test.ts
@@ -0,0 +1,428 @@
+/**
+ * Safe whole-skill updates of installed skillpacks (GBRA-225 PR 3):
+ * src/core/skillpack/{safe-update,update-journal,state,file-lock}.ts, the
+ * `skillpack_update_incomplete` doctor check and the CLI exit-code contract.
+ *
+ * Every case runs on real files in temp dirs outside any git repository
+ * (repo-less brains are first class), with its own state file and backups
+ * dir (or an isolated GBRAIN_HOME for the spawned CLI).
+ */
+import { afterEach, describe, expect, test } from 'bun:test';
+import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { tmpdir } from 'os';
+import { spawn, spawnSync } from 'child_process';
+
+import { runScaffold } from '../src/core/skillpack/scaffold.ts';
+import {
+ DIFF_LINE_CAP, recordScaffoldBases, runSkillpackRestore, runSkillpackUpdate, setSkillPinned, skillsRootKey, type UpdateOptions,
+} from '../src/core/skillpack/safe-update.ts';
+import { listJournals, sha256 } from '../src/core/skillpack/update-journal.ts';
+import { loadState, saveState } from '../src/core/skillpack/state.ts';
+import {
+ SKILLS_LOCK_HISTORY_FILENAME, SKILLS_MANIFEST_FILENAME, computeSkillsManifest, droppedHistoryEntries, loadVerifiedSkillsLockHistory,
+ mergeSkillsLockHistory, parseSkillsLockHistory, renderSkillsLockHistory, renderSkillsManifest,
+} from '../src/core/skills-integrity.ts';
+import { runSkillpackUpdateChecks } from '../src/commands/doctor/checks/skillpack-update.ts';
+
+const REPO = join(import.meta.dir, '..');
+const created: string[] = [];
+afterEach(() => {
+ while (created.length) rmSync(created.pop()!, { recursive: true, force: true });
+});
+
+function tmp(prefix: string): string {
+ const dir = mkdtempSync(join(tmpdir(), prefix));
+ created.push(dir);
+ return dir;
+}
+
+const skill = (name: string, body: string) => `---\nname: ${name}\ntriggers:\n - run the ${name} flow\n---\n# ${name}\n\n${body}\n`;
+const V1 = { 'demo/SKILL.md': skill('demo', 'v1'), 'demo/references/notes.md': 'notes v1\n', 'other/SKILL.md': skill('other', 'v1') };
+const V2 = { 'demo/SKILL.md': skill('demo', 'v2'), 'demo/references/notes.md': 'notes v2\n', 'other/SKILL.md': skill('other', 'v2') };
+const V3 = { 'demo/SKILL.md': skill('demo', 'v3'), 'demo/references/notes.md': 'notes v3\n', 'other/SKILL.md': skill('other', 'v3') };
+
+/** Write a bundle release: files, then the history (append-only) and the lock, as scripts/generate-skills-manifest.ts does. */
+function release(gbrainRoot: string, files: Record<string, string>): void {
+ const skillsDir = join(gbrainRoot, 'skills');
+ for (const [rel, body] of Object.entries(files)) {
+ mkdirSync(dirname(join(skillsDir, rel)), { recursive: true });
+ writeFileSync(join(skillsDir, rel), body);
+ }
+ const historyPath = join(skillsDir, SKILLS_LOCK_HISTORY_FILENAME);
+ const previous = existsSync(historyPath) ? parseSkillsLockHistory(readFileSync(historyPath, 'utf-8')) : null;
+ writeFileSync(historyPath, renderSkillsLockHistory(mergeSkillsLockHistory(previous, computeSkillsManifest(skillsDir))));
+ writeFileSync(join(skillsDir, SKILLS_MANIFEST_FILENAME), renderSkillsManifest(skillsDir));
+}
+
+interface Env { gbrainRoot: string; ws: string; home: string; statePath: string; backups: string; skillsRoot: string }
+
+function setup(): Env {
+ const gbrainRoot = tmp('sp-safe-gbrain-');
+ mkdirSync(join(gbrainRoot, 'src'), { recursive: true });
+ writeFileSync(join(gbrainRoot, 'src', 'cli.ts'), '// stub\n');
+ writeFileSync(join(gbrainRoot, 'openclaw.plugin.json'), JSON.stringify({ name: 'gbrain-test', version: '0.0.1', skills: ['skills/demo', 'skills/other'], shared_deps: [] }));
+ release(gbrainRoot, V1);
+ const ws = tmp('sp-safe-ws-');
+ const home = tmp('sp-safe-home-');
+ const gb = join(home, '.gbrain');
+ return { gbrainRoot, ws, home, statePath: join(gb, 'skillpack-state.json'), backups: join(gb, 'skillpack-backups'), skillsRoot: skillsRootKey(join(ws, 'skills')) };
+}
+
+async function scaffold(env: Env, opts: { record?: boolean } = {}): Promise<void> {
+ const result = runScaffold({ gbrainRoot: env.gbrainRoot, targetWorkspace: env.ws, skillSlug: null });
+ if (opts.record !== false) await recordScaffoldBases(join(env.ws, 'skills'), result.files, { statePath: env.statePath });
+}
+
+function update(env: Env, extra: Partial<UpdateOptions> = {}) {
+ return runSkillpackUpdate({ gbrainRoot: env.gbrainRoot, skillsRoot: env.skillsRoot, slugs: null, statePath: env.statePath, backups: env.backups, validate: () => [], ...extra });
+}
+
+const read = (env: Env, rel: string) => readFileSync(join(env.ws, 'skills', rel), 'utf-8');
+const write = (env: Env, rel: string, body: string) => writeFileSync(join(env.ws, 'skills', rel), body);
+const outcome = (result: Awaited<ReturnType<typeof update>>, slug: string) => result.skills.find(s => s.slug === slug)!;
+
+describe('base recording and whole-skill update', () => {
+ test('scaffold records bases; an untouched skill updates whole, journaled; a second run is a no-op (repo-less)', async () => {
+ const env = setup();
+ expect(spawnSync('git', ['-C', env.ws, 'rev-parse', '--git-dir']).status).not.toBe(0);
+ await scaffold(env);
+ const record = loadState({ statePath: env.statePath }).roots![env.skillsRoot]!.demo!;
+ expect(record.files['demo/SKILL.md']).toBe(sha256(V1['demo/SKILL.md']));
+ release(env.gbrainRoot, V2);
+
+ const preview = await update(env, { dryRun: true });
+ expect(outcome(preview, 'demo').result).toBe('would_update');
+ expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
+ expect(existsSync(env.backups)).toBe(false);
+
+ const result = await update(env);
+ expect(result.summary).toMatchObject({ updated: 2, failed: 0, skipped: 0 });
+ expect(read(env, 'demo/references/notes.md')).toBe(V2['demo/references/notes.md']);
+ const [journal] = listJournals(env.backups);
+ expect(journal!.status).toBe('complete');
+ expect(journal!.skills.every(s => s.status === 'committed')).toBe(true);
+ expect(loadState({ statePath: env.statePath }).roots![env.skillsRoot]!.demo!.files['demo/SKILL.md']).toBe(sha256(V2['demo/SKILL.md']));
+ expect(readdirNames(env.skillsRoot).filter(n => n.startsWith('.gbrain-skillpack'))).toEqual([]);
+
+ const again = await update(env);
+ expect(again.summary.current).toBe(2);
+ expect(again.journal).toBeNull();
+ });
+
+ test('base precedence: a file that differs from its base is local_edits even when it equals a released version', async () => {
+ const env = setup();
+ release(env.gbrainRoot, V2);
+ await scaffold(env); // base = v2
+ write(env, 'demo/SKILL.md', V1['demo/SKILL.md']); // a past release, not the base
+ release(env.gbrainRoot, V3);
+ const result = await update(env, { acceptHistorical: true });
+ expect(outcome(result, 'demo')).toMatchObject({ result: 'skipped', reason: 'local_edits' });
+ expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
+ expect(read(env, 'demo/references/notes.md')).toBe(V2['demo/references/notes.md']);
+ expect(outcome(result, 'other').result).toBe('updated');
+ });
+
+ test('a file with no base that matches only a released version needs --accept-historical', async () => {
+ const env = setup();
+ await scaffold(env, { record: false }); // an install from before bases were recorded
+ release(env.gbrainRoot, V2);
+ const without = await update(env);
+ expect(outcome(without, 'demo')).toMatchObject({ result: 'skipped', reason: 'historical_only' });
+ expect(outcome(without, 'demo').historical.sort()).toEqual(['demo/SKILL.md', 'demo/references/notes.md']);
+ expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
+
+ const withFlag = await update(env, { acceptHistorical: true });
+ expect(outcome(withFlag, 'demo').result).toBe('updated');
+ expect(read(env, 'demo/SKILL.md')).toBe(V2['demo/SKILL.md']);
+ expect(loadState({ statePath: env.statePath }).roots![env.skillsRoot]!.demo!.files['demo/SKILL.md']).toBe(sha256(V2['demo/SKILL.md']));
+ });
+
+ test('a history that fails its lock hash disables whole-file updates (history_unverified)', async () => {
+ const env = setup();
+ await scaffold(env);
+ release(env.gbrainRoot, V2);
+ appendFileSync(join(env.gbrainRoot, 'skills', SKILLS_LOCK_HISTORY_FILENAME), ' ');
+ const result = await update(env);
+ expect(result.history.verified).toBe(false);
+ expect(outcome(result, 'demo')).toMatchObject({ result: 'skipped', reason: 'history_unverified' });
+ expect(result.summary.updated).toBe(0);
+ expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
+ });
+
+ test('a pinned skill is skipped until unpinned', async () => {
+ const env = setup();
+ await scaffold(env);
+ release(env.gbrainRoot, V2);
+ expect(await setSkillPinned(env.skillsRoot, 'demo', true, { statePath: env.statePath })).toBe(true);
+ const pinned = await update(env);
+ expect(outcome(pinned, 'demo')).toMatchObject({ result: 'skipped', reason: 'pinned' });
+ expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
+ await setSkillPinned(env.skillsRoot, 'demo', false, { statePath: env.statePath });
+ expect(outcome(await update(env), 'demo').result).toBe('updated');
+ });
+
+ test('a symlinked file in the closure is refused, not followed', async () => {
+ const env = setup();
+ await scaffold(env);
+ const outside = join(tmp('sp-safe-outside-'), 'x.md');
+ writeFileSync(outside, 'outside\n');
+ rmSync(join(env.ws, 'skills', 'demo/references/notes.md'));
+ symlinkSync(outside, join(env.ws, 'skills', 'demo/references/notes.md'));
+ release(env.gbrainRoot, V2);
+ const result = await update(env);
+ expect(outcome(result, 'demo')).toMatchObject({ result: 'skipped', reason: 'unsafe_target' });
+ expect(readFileSync(outside, 'utf-8')).toBe('outside\n');
+ });
+
+ test('diffs for skipped skills are bounded to 200 lines per file and redact secret-looking values', async () => {
+ const env = setup();
+ await scaffold(env);
+ const secret = `ghp_${'Zq7Lm2Np9Rt4Vx8Bc3Df6Gh1Jk5'.slice(0, 36).padEnd(36, 'x')}`;
+ write(env, 'demo/references/notes.md', `token: ${secret}\n` + Array.from({ length: 400 }, (_, i) => `local line ${i}`).join('\n') + '\n');
+ release(env.gbrainRoot, V2);
+ const result = await update(env);
+ const diff = outcome(result, 'demo').diffs!.find(d => d.rel === 'demo/references/notes.md')!;
+ expect(diff.truncated).toBe(true);
+ expect(diff.diff.split('\n').length).toBeLessThanOrEqual(DIFF_LINE_CAP + 2);
+ expect(diff.diff).not.toContain(secret);
+ expect(diff.diff).toContain('REDACTED');
+ expect((await update(env, { noDiff: true })).skills.every(s => s.diffs === undefined)).toBe(true);
+ });
+});
+
+describe('commit protocol', () => {
+ test('a file changed between classification and its rename aborts the skill and rolls back only files untouched since', async () => {
+ const env = setup();
+ await scaffold(env);
+ release(env.gbrainRoot, V2);
+ let renames = 0;
+ let first = '';
+ const result = await update(env, {
+ slugs: ['demo'],
+ hooks: {
+ afterRename: rel => { if (renames++ === 0) first = rel; },
+ beforeRename: rel => { if (renames === 1) writeFileSync(join(env.ws, 'skills', rel), 'edited mid-update\n'); },
+ },
+ });
+ const demo = outcome(result, 'demo');
+ expect(demo.result).toBe('failed');
+ expect(demo.touched).toEqual([first]);
+ expect(demo.rollback_skipped).toEqual([]);
+ expect(read(env, first)).toBe(V1[first as keyof typeof V1]);
+ const second = first === 'demo/SKILL.md' ? 'demo/references/notes.md' : 'demo/SKILL.md';
+ expect(read(env, second)).toBe('edited mid-update\n');
+ expect(listJournals(env.backups)[0]!.skills[0]!.status).toBe('rolled_back');
+ expect(result.restore_command).toContain('gbrain skillpack restore');
+ expect(loadState({ statePath: env.statePath }).roots![env.skillsRoot]!.demo!.files[first]).toBe(sha256(V1[first as keyof typeof V1]));
+ });
+
+ test('rollback leaves a renamed file that was edited again after the rename', async () => {
+ const env = setup();
+ await scaffold(env);
+ release(env.gbrainRoot, V2);
+ let renames = 0;
+ let first = '';
+ const result = await update(env, {
+ slugs: ['demo'],
+ hooks: {
+ afterRename: rel => {
+ if (renames++ > 0) return;
+ first = rel;
+ writeFileSync(join(env.ws, 'skills', rel), 'edited after rename\n');
+ },
+ beforeRename: rel => { if (renames === 1) writeFileSync(join(env.ws, 'skills', rel), 'edited mid-update\n'); },
+ },
+ });
+ expect(outcome(result, 'demo').rollback_skipped).toEqual([first]);
+ expect(read(env, first)).toBe('edited after rename\n');
+ });
+
+ test('a failed post-update check rolls the skill back', async () => {
+ const env = setup();
+ await scaffold(env);
+ release(env.gbrainRoot, V2);
+ const result = await update(env, { slugs: ['demo'], validate: () => ['forced failure'] });
+ expect(outcome(result, 'demo')).toMatchObject({ result: 'failed', failure: 'forced failure' });
+ expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
+ expect(read(env, 'demo/references/notes.md')).toBe(V1['demo/references/notes.md']);
+ });
+
+ test('the default checks pass a real update (conformance, triggers, resolver)', async () => {
+ const env = setup();
+ await scaffold(env);
+ release(env.gbrainRoot, V2);
+ const result = await update(env, { validate: undefined });
+ expect(result.summary).toMatchObject({ updated: 2, failed: 0 });
+ });
+
+ test('a crash leaves a pending journal: doctor reports it, the next run refuses, restore recovers', async () => {
+ const env = setup();
+ await scaffold(env);
+ release(env.gbrainRoot, V2);
+ const script = join(tmp('sp-safe-script-'), 'crash.ts');
+ writeFileSync(script, `import { runSkillpackUpdate } from ${JSON.stringify(join(REPO, 'src/core/skillpack/safe-update.ts'))};
+await runSkillpackUpdate({ gbrainRoot: ${JSON.stringify(env.gbrainRoot)}, skillsRoot: ${JSON.stringify(env.skillsRoot)}, slugs: ['demo'],
+ statePath: ${JSON.stringify(env.statePath)}, backups: ${JSON.stringify(env.backups)}, validate: () => [], hooks: { afterRename: () => process.exit(9) } });
+`);
+ expect(spawnSync('bun', [script], { stdio: 'ignore', timeout: 60_000 }).status).toBe(9);
+
+ const [incomplete] = (await runSkillpackUpdateChecks(undefined, env.backups));
+ expect(incomplete).toMatchObject({ name: 'skillpack_update_incomplete', status: 'warn' });
+ const id = listJournals(env.backups)[0]!.id;
+ expect(incomplete!.message).toContain(`gbrain skillpack restore ${id}`);
+ await expect(update(env)).rejects.toMatchObject({ code: 'skillpack_update_incomplete' });
+ expect((await update(env, { dryRun: true })).pending_journals).toEqual([id]);
+
+ await runSkillpackRestore({ id, statePath: env.statePath, backups: env.backups });
+ expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
+ expect(read(env, 'demo/references/notes.md')).toBe(V1['demo/references/notes.md']);
+ expect((await runSkillpackUpdateChecks(undefined, env.backups)).map(c => c.name)).toEqual(['skillpack_backups']);
+ expect(outcome(await update(env), 'demo').result).toBe('updated');
+ }, 90_000);
+});
+
+describe('restore', () => {
+ test('refuses a file changed after the update unless it is named in --skip', async () => {
+ const env = setup();
+ await scaffold(env);
+ release(env.gbrainRoot, V2);
+ const { journal } = await update(env, { slugs: ['demo'] });
+ write(env, 'demo/references/notes.md', 'my later edit\n');
+ await expect(runSkillpackRestore({ id: journal!, statePath: env.statePath, backups: env.backups })).rejects.toMatchObject({ code: 'skillpack_restore_conflict' });
+ expect(read(env, 'demo/SKILL.md')).toBe(V2['demo/SKILL.md']);
+
+ await runSkillpackRestore({ id: journal!, skip: ['demo/references/notes.md'], statePath: env.statePath, backups: env.backups });
+ expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
+ expect(read(env, 'demo/references/notes.md')).toBe('my later edit\n');
+ const record = loadState({ statePath: env.statePath }).roots![env.skillsRoot]!.demo!;
+ expect(record.files['demo/SKILL.md']).toBe(sha256(V1['demo/SKILL.md']));
+ });
+
+ test('is idempotent', async () => {
+ const env = setup();
+ await scaffold(env);
+ release(env.gbrainRoot, V2);
+ const { journal } = await update(env);
+ const first = await runSkillpackRestore({ id: journal!, statePath: env.statePath, backups: env.backups });
+ expect(first.files.every(f => f.action === 'restore')).toBe(true);
+ const snapshot = [read(env, 'demo/SKILL.md'), read(env, 'demo/references/notes.md'), read(env, 'other/SKILL.md')];
+ const second = await runSkillpackRestore({ id: journal!, statePath: env.statePath, backups: env.backups });
+ expect(second.files.every(f => f.action === 'already_restored')).toBe(true);
+ expect([read(env, 'demo/SKILL.md'), read(env, 'demo/references/notes.md'), read(env, 'other/SKILL.md')]).toEqual(snapshot);
+ expect(snapshot[0]).toBe(V1['demo/SKILL.md']);
+ });
+});
+
+describe('shared state lock', () => {
+ test('concurrent scaffold, update and pin across two workspaces lose no state records', async () => {
+ const a = setup();
+ const b: Env = { ...a, ws: tmp('sp-safe-ws-b-') };
+ b.skillsRoot = skillsRootKey(join(b.ws, 'skills'));
+ await scaffold(b);
+ release(a.gbrainRoot, V2);
+ const dir = tmp('sp-safe-script-');
+ const startAt = Date.now() + 1500;
+ const mod = (name: string) => JSON.stringify(join(REPO, 'src/core/skillpack', name));
+ const scripts = {
+ a: `import { runScaffold } from ${mod('scaffold.ts')};
+import { recordScaffoldBases, setSkillPinned } from ${mod('safe-update.ts')};
+while (Date.now() < ${startAt}) await Bun.sleep(5);
+const r = runScaffold({ gbrainRoot: ${JSON.stringify(a.gbrainRoot)}, targetWorkspace: ${JSON.stringify(a.ws)}, skillSlug: null });
+await recordScaffoldBases(${JSON.stringify(join(a.ws, 'skills'))}, r.files, { statePath: ${JSON.stringify(a.statePath)} });
+for (let i = 0; i < 150; i++) await setSkillPinned(${JSON.stringify(skillsRootKey(join(a.ws, 'skills')))}, 'p' + i, true, { statePath: ${JSON.stringify(a.statePath)} });
+`,
+ b: `import { runSkillpackUpdate, setSkillPinned } from ${mod('safe-update.ts')};
+while (Date.now() < ${startAt}) await Bun.sleep(5);
+const r = await runSkillpackUpdate({ gbrainRoot: ${JSON.stringify(b.gbrainRoot)}, skillsRoot: ${JSON.stringify(b.skillsRoot)}, slugs: null, statePath: ${JSON.stringify(b.statePath)}, backups: ${JSON.stringify(b.backups)}, validate: () => [] });
+if (r.summary.updated !== 2) process.exit(3);
+for (let i = 0; i < 150; i++) await setSkillPinned(${JSON.stringify(b.skillsRoot)}, 'q' + i, true, { statePath: ${JSON.stringify(b.statePath)} });
+`,
+ };
+ const run = (body: string, name: string) => new Promise<number | null>(resolve => {
+ const path = join(dir, `${name}.ts`);
+ writeFileSync(path, body);
+ spawn('bun', [path], { stdio: 'ignore' }).on('exit', code => resolve(code));
+ });
+ expect(await Promise.all([run(scripts.a, 'a'), run(scripts.b, 'b')])).toEqual([0, 0]);
+ const roots = loadState({ statePath: a.statePath }).roots!;
+ const rootA = roots[skillsRootKey(join(a.ws, 'skills'))]!;
+ expect(rootA.demo!.files['demo/SKILL.md']).toBe(sha256(V2['demo/SKILL.md']));
+ expect(Object.keys(rootA).filter(k => rootA[k]!.pinned).length).toBe(150);
+ const rootB = roots[b.skillsRoot]!;
+ expect(rootB.demo!.files['demo/SKILL.md']).toBe(sha256(V2['demo/SKILL.md']));
+ expect(Object.keys(rootB).filter(k => rootB[k]!.pinned).length).toBe(150);
+ }, 90_000);
+});
+
+describe('CLI contract', () => {
+ const cli = (env: Env, args: string[]) => spawnSync('bun', [join(REPO, 'src/cli.ts'), 'skillpack', ...args], {
+ cwd: env.gbrainRoot, env: { ...process.env, GBRAIN_HOME: env.home }, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8', timeout: 60_000,
+ });
+
+ test('exit 0 with skips, 1 only with --fail-on-skipped, 2 on failure; never prompts with stdin closed', () => {
+ const env = setup();
+ expect(cli(env, ['scaffold', '--all', '--workspace', env.ws]).status).toBe(0);
+ expect(loadState({ statePath: env.statePath }).roots![env.skillsRoot]!.other!.files['other/SKILL.md']).toBe(sha256(V1['other/SKILL.md']));
+ write(env, 'other/SKILL.md', skill('other', 'my edit'));
+ release(env.gbrainRoot, V2);
+
+ const preview = cli(env, ['reference', '--all', '--update-untouched', '--dry-run', '--workspace', env.ws]);
+ expect(preview.status).toBe(0);
+ expect(preview.stdout).toContain('would update');
+ expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
+
+ const ok = cli(env, ['reference', '--all', '--update-untouched', '--json', '--workspace', env.ws]);
+ expect(ok.status).toBe(0);
+ const okJson = JSON.parse(ok.stdout);
+ expect(okJson.summary).toMatchObject({ updated: 1, skipped: 1, failed: 0 });
+ expect(okJson.skills.find((s: { slug: string }) => s.slug === 'other').reason).toBe('local_edits');
+
+ release(env.gbrainRoot, V3);
+ const strict = cli(env, ['reference', '--all', '--update-untouched', '--fail-on-skipped', '--no-diff', '--workspace', env.ws]);
+ expect(strict.status).toBe(1);
+ expect(read(env, 'demo/SKILL.md')).toBe(V3['demo/SKILL.md']);
+
+ release(env.gbrainRoot, { 'demo/SKILL.md': '# demo v4 without frontmatter\n' });
+ const failed = cli(env, ['reference', 'demo', '--update-untouched', '--workspace', env.ws]);
+ expect(failed.status).toBe(2);
+ expect(failed.stdout).toMatch(/gbrain skillpack restore \S+/);
+ expect(read(env, 'demo/SKILL.md')).toBe(V3['demo/SKILL.md']);
+
+ expect(cli(env, ['pin', 'demo', '--workspace', env.ws]).status).toBe(0);
+ expect(loadState({ statePath: env.statePath }).roots![env.skillsRoot]!.demo!.pinned).toBe(true);
+ expect(cli(env, ['restore', '--list', '--json']).status).toBe(0);
+ }, 120_000);
+});
+
+describe('state file and history', () => {
+ test('a v1 state file loads with its packs and saves as v2', () => {
+ const dir = tmp('sp-safe-state-');
+ const statePath = join(dir, 'skillpack-state.json');
+ const pack = { name: 'acme-example', version: '1.0.0', author: 'alice-example', source: './pack', source_kind: 'local', pinned_commit: null, tarball_sha256: null, tier: 'local', scaffolded_at: '2026-01-01T00:00:00.000Z', workspace: dir, skill_slugs: ['x'] };
+ writeFileSync(statePath, JSON.stringify({ schema_version: 'gbrain-skillpack-state-v1', packs: [pack] }));
+ const state = loadState({ statePath });
+ expect(state.packs).toEqual([pack] as never);
+ expect(state.roots).toEqual({});
+ saveState(state, { statePath });
+ expect(JSON.parse(readFileSync(statePath, 'utf-8')).schema_version).toBe('gbrain-skillpack-state-v2');
+ });
+
+ test('history merge is append-only and its lock hash is verified', () => {
+ const env = setup();
+ const skillsDir = join(env.gbrainRoot, 'skills');
+ const v1 = parseSkillsLockHistory(readFileSync(join(skillsDir, SKILLS_LOCK_HISTORY_FILENAME), 'utf-8'));
+ release(env.gbrainRoot, V2);
+ const v2 = parseSkillsLockHistory(readFileSync(join(skillsDir, SKILLS_LOCK_HISTORY_FILENAME), 'utf-8'));
+ expect(droppedHistoryEntries(v1, v2)).toEqual([]);
+ expect(v2.files['demo/SKILL.md']).toEqual([sha256(V1['demo/SKILL.md']), sha256(V2['demo/SKILL.md'])].sort());
+ expect(droppedHistoryEntries(v2, v1).length).toBeGreaterThan(0);
+ expect(loadVerifiedSkillsLockHistory(skillsDir).ok).toBe(true);
+ appendFileSync(join(skillsDir, SKILLS_LOCK_HISTORY_FILENAME), '\n');
+ expect(loadVerifiedSkillsLockHistory(skillsDir)).toMatchObject({ ok: false });
+ });
+});
+
+function readdirNames(dir: string): string[] {
+ return require('fs').readdirSync(dir) as string[];
+}