agent-skillboard 0.2.18 → 0.3.0

package/docs/value-proof.md

@@ -1,197 +1,39 @@
 # SkillBoard Value Proof
 
-This is the README-facing proof that SkillBoard gives a user more useful control
-than manually inspecting `/skills` or a raw workflow skill list.
-
-The proof is executable:
-
-```bash
-node --test test/readme-value-proof.test.mjs
-```
-
-The test uses repository fixtures, not a mocked string. It drives the same CLI
-surfaces a user or agent would use.
-
-## GitHub-reader takeaway
-
-The raw list answers inventory questions: which skill declarations are connected
-to this workflow?
-
-SkillBoard answers routing questions: which skills can actually run now, why
-are others blocked, which skill should steer the user's current request when
-several skills overlap, and what approved action changes the next state?
-
-In the tested fixture, the raw list can make the workflow look ready because it
-shows `matt.tdd active workflow-auto`. SkillBoard refuses that unsafe claim and
-reports 0 usable skills, 8 blocked skills, 2 policy errors, and 1 policy warning
-before invocation.
-
-## Case 1: Raw skill list vs SkillBoard brief
-
-Fixture:
-
-```bash
-examples/skillboard.config.yaml
-examples/skills
-```
-
-`examples/skillboard.config.yaml` is an intentional policy-failure fixture. It
-is not the passing starter example; it exists to prove that SkillBoard refuses a
-raw-list availability claim when policy health fails.
-
-Workflow:
-
-```bash
-codex-night-workflow
-```
-
-Raw skill list command:
-
-```bash
-node bin/skillboard.mjs list skills \
-  --config examples/skillboard.config.yaml \
-  --skills examples/skills \
-  --workflow codex-night-workflow
-```
-
-Observed raw-list result:
-
-- Raw skill list: 4 workflow-linked rows.
-- It includes `matt.tdd active workflow-auto`.
-- It does not include policy health.
-
-SkillBoard brief command:
+The executable proof is the v2 contract and integration suite:
 
 ```bash
-node bin/skillboard.mjs brief \
-  --config examples/skillboard.config.yaml \
-  --skills examples/skills \
-  --workflow codex-night-workflow
+node --test test/v2-agent-sharing.test.mjs test/v2-onboarding-behavior.test.mjs test/v2-guard-route.test.mjs test/v2-surface-integration.test.mjs
 ```
 
-Observed brief result:
+## What it proves
 
-- SkillBoard brief: 0 usable skills.
-- 8 blocked skills.
-- Policy errors: 2.
-- Policy warnings: 1.
-- The policy diagnostics identify `matt.grill-with-docs` as a non-callable
-  fallback in `requirement-review`.
+- Setup creates user-level state without project init.
+- Valid discovered skills default to enabled and agent-local.
+- Disabled skills and skills absent from the selected agent are denied.
+- Share and unshare preserve agent-owned originals.
+- Optional preference changes ranking without changing availability.
+- Source and provenance audits do not change guard results.
+- Commands produce the same result from different working directories.
+- Version 1 is read-only until explicit migration.
 
-What this proves:
-
-- The raw list can make a workflow look usable because it reports declared
-  state such as `active` and `workflow-auto`.
-- The SkillBoard brief checks policy health before use and refuses the unsafe
-  availability claim.
-
-## Case 2: Approved action-card flow
-
-Fixture:
-
-```bash
-examples/multi-source.config.yaml
-examples/multi-source-skills
-```
-
-The test copies this fixture to a temporary project, including `AGENTS.md` and
-`CLAUDE.md`, then runs:
-
-```bash
-node bin/skillboard.mjs brief ... --include-actions --json
-node bin/skillboard.mjs apply-action activate-skill:anthropic.docx ... --yes --json
-node bin/skillboard.mjs brief ... --json
-```
-
-Observed action-card flow result:
-
-- Before apply, usable skills: 2.
-- The current action list includes `activate-skill:anthropic.docx`.
-- Applying that one approved action returns `changed: true`.
-- After apply, usable skills: 2 -> 3.
-- `anthropic.docx` appears in `manual_allowed`.
-- The final brief has 0 policy errors.
-
-What this proves:
-
-- SkillBoard is not just a catalog. It gives a current action id, applies one
-  approved change, then re-resolves the next availability state.
-- The user does not need to hand-edit YAML or infer enable/disable impact from
-  raw `SKILL.md` files.
-
-## Case 3: AI-mediated approved action proof
-
-The test also simulates the product path without calling an external LLM:
+## Reproduce the user surface
 
 ```bash
-node bin/skillboard.mjs brief ... --include-actions --json
-node bin/skillboard.mjs apply-action <current-action-id> ... --yes --json
-node bin/skillboard.mjs guard use anthropic.docx ... --json
-node bin/skillboard.mjs guard use matt.grill-me ... --json
+node bin/skillboard.mjs setup --yes --agent codex
+node bin/skillboard.mjs brief --agent codex --json
+node bin/skillboard.mjs check --config examples/v2-multi-source.config.yaml --skills examples/multi-source-skills
 ```
 
-Observed AI-mediated result:
-
-- The simulated user asks for `anthropic.docx` to be made available.
-- The AI reads `assistant_guidance.choices` from the current brief.
-- The chosen confirmation maps to the current
-  `activate-skill:anthropic.docx` action id.
-- `apply-action --yes --json` returns a post-apply brief.
-- The returned brief no longer offers the stale activate action and now offers
-  the matching disable action.
-- `guard use anthropic.docx --workflow codex-night-workflow` fails before the
-  approved action and succeeds after it.
-- `guard use matt.grill-me --workflow codex-night-workflow` stays denied
-  because the workflow blocks that skill.
-
-What this proves:
-
-- The proof uses the current `assistant_guidance` action id instead of cached
-  output.
-- SkillBoard keeps the guard as the final boundary before invocation.
-- Blocked skills still produce a non-zero, machine-readable denial.
-
-## Case 4: AI route picks the right allowed skill
+The policy contains only `enabled`, `shared`, and optional preference. Generated
+inventory records `installed_on`. Source and provenance remain optional audit
+metadata and never determine availability. Runtime and action authorization
+remain outside SkillBoard's scope.
 
-The same fixture also proves that SkillBoard can help the AI choose the right
-skill before invocation:
+## Version 1 compatibility proof
 
 ```bash
-node bin/skillboard.mjs route "write tests before implementation" \
-  --config examples/multi-source.config.yaml \
-  --skills examples/multi-source-skills \
-  --workflow codex-night-workflow \
-  --json
+skillboard migrate v2 --config <path> --json
+skillboard migrate v2 --config <path> --yes --json
+skillboard migrate v2 --config <path> --rollback <backup> --json
 ```
-
-Observed route result:
-
-- Matched capability: `test-first-implementation`.
-- Match source: `capability`.
-- Confidence: `high`.
-- Recommended skill: `matt.tdd`.
-- Fallback skill: `private.tdd-work-continuity`.
-- Overlap resolution is exposed in route payloads when several allowed skills
-  match, so agents can explain the deterministic route without hiding the other
-  available skills.
-- Guard command: `skillboard guard use matt.tdd ...`.
-- Guard result for `matt.tdd`: allowed.
-- Start disclosure: `I will use matt.tdd for this request.`
-- Finish disclosure: `I used matt.tdd for this request.`
-
-The proof also checks `brief --intent "write tests before implementation"` so
-the recommendation appears inside `assistant_guidance.route`, not only through
-the standalone `route` command.
-
-For a request outside the workflow's declared capability, such as "ship a
-powerpoint deck", SkillBoard returns no recommended skill and tells the AI to:
-Ask a clarifying question before choosing a skill.
-
-What this proves:
-
-- The AI can ask SkillBoard which skill fits a normal user request instead of
-  guessing from raw `SKILL.md` text.
-- Allowed skill use stays low-friction: the AI discloses use at start and
-  finish instead of asking for redundant approval.
-- No-match results are explicit, so the AI can ask a clarifying question rather
-  than forcing a poor skill choice.

package/docs/variant-lifecycle.md

@@ -1,86 +1,66 @@
 # Skill Variant Lifecycle
 
-SkillBoard treats a skill variant as a reviewed policy relationship plus a file snapshot trail. This is a manual adaptation lifecycle for cases such as `a -> claude.a`, where a human adapts a base skill for a specific agent or workflow and then asks SkillBoard to record, review, approve, or reset that relationship.
+A variant is a manual content adaptation with snapshot and digest history. The
+lifecycle does not authorize availability. A registered variant is usable only
+according to its ordinary v2 `enabled` entry and generated installation
+presence; optional preference ranks it and never changes availability.
 
-Variant lifecycle is policy registration. SkillBoard records metadata, snapshots, digests, and workflow preference changes; it does not convert skill bodies, does not rewrite skill bodies, and does not guarantee semantic equivalence of skill bodies.
+## Current v2 boundary
 
-## Lifecycle commands
+`variant status` remains a read-only advanced operator surface for content and
+inventory lifecycle metadata. Authorization-mutating `fork`, `approve`, and
+`reset` forms remain an explicit v1 compatibility boundary. Legacy capability
+or mode fields are never current availability gates. Runtime/action
+authorization remains with the agent or harness.
 
-All examples use the global `skillboard` command. From a clone, replace `skillboard ` with `node bin/skillboard.mjs `.
+## Content review flow
 
-```bash
-skillboard variant add <variant-id> --from <base-id> --capability <name> --workflow <name> --config <path> --skills <dir> [--path <relative-skill-path>] [--mode manual-only|router-only|workflow-auto] [--category <name>] [--owner-install-unit <unit-id>] [--dry-run] [--json]
-skillboard variant fork <variant-id> --from <base-id> --capability <name> --workflow <name> --path <relative-skill-path> --config <path> --skills <dir> [--adapted-for <label>] [--category <name>] [--owner-install-unit <unit-id>] [--dry-run] [--json]
-skillboard variant status <variant-id> --config <path> --skills <dir> [--json]
-skillboard variant approve <variant-id> --config <path> --skills <dir> [--mode manual-only|router-only|workflow-auto] [--dry-run] [--json]
-skillboard variant reset <variant-id> --to-base|--to-approved --config <path> --skills <dir> [--yes] [--dry-run] [--mode manual-only|router-only|workflow-auto] [--json]
-```
-
-Use `--json` in scripts. Success payloads return the command-specific lifecycle fields such as `message`, `dryRun`, `changed`, `plan`, `filePlan`, `skill`, `variant`, and `warnings`. Errors include `ok: false` with a stable `error.code` and `error.message`. Usage errors exit with code `2` in both plain and JSON modes.
-
-## Recommended review flow
-
-1. Register or fork the variant from a known base:
-
-   ```bash
-   skillboard variant fork claude.a --from a --capability task-review --workflow claude-workflow --path claude/a --config skillboard.config.yaml --skills skills --json
-   ```
-
-   Fork creates a draft relationship and raw snapshot records without promoting the variant for automatic workflow use.
-
-2. Edit the variant `SKILL.md` by hand. This is where the actual adaptation happens.
+1. Fork a variant from a known base.
+2. Edit its `SKILL.md` manually.
+3. Inspect live/base/approved digest drift.
+4. Approve the reviewed snapshot.
+5. Reset to a recorded base or approved snapshot when necessary.
 
-3. Inspect computed drift before approval:
+SkillBoard does not convert or rewrite skill bodies and does not promise semantic
+equivalence between base and variant.
 
-   ```bash
-   skillboard variant status claude.a --config skillboard.config.yaml --skills skills --json
-   ```
+## Read-only inspection
 
-   `variant.status` is the stored lifecycle state. `computedStatus` is derived from the live digest, the base digest, and the approved digest. A changed live file that differs from the base snapshot and has no matching approved snapshot is a draft candidate.
-
-4. Approve the reviewed variant:
-
-   ```bash
-   skillboard variant approve claude.a --config skillboard.config.yaml --skills skills --mode router-only --json
-   ```
-
-   Approval writes an approved snapshot, records the live digest, updates the skill metadata, and promotes the workflow preference/fallback policy for the chosen capability.
+```bash
+skillboard variant status <variant-id> --config <path> --skills <dir> --json
+```
 
-5. Reset deliberately when needed:
+The `variant status` read-only payload reports stored content and inventory
+lifecycle metadata plus computed digest drift.
+Snapshots live under `.skillboard/variant-snapshots/<encoded-skill-id>/` and are
+created lazily. Path containment checks protect live and snapshot files.
 
-   ```bash
-   skillboard variant reset claude.a --to-base --config skillboard.config.yaml --skills skills --yes --json
-   skillboard variant reset claude.a --to-approved --config skillboard.config.yaml --skills skills --yes --json
-   ```
+## Version 1 compatibility reference
 
-   `--to-base` restores the base draft file and demotes workflow preference back to the base skill. `--to-approved` restores the approved snapshot and policy. Without `--yes`, mutating reset is rejected; use `--dry-run --json` to inspect the plan first.
+Historical v1 commands accepted capability, workflow, owner-install-unit, and
+mode values such as `manual-only`, `router-only`, and `workflow-auto`. Those
+arguments describe the v1 migration/compatibility surface only; they do not
+authorize v2 availability.
 
-## Metadata and snapshots
+```text
+skillboard variant fork <variant-id> --from <base-id> --capability <name> --workflow <name> --path <path> ...
+skillboard variant approve <variant-id> ...
+skillboard variant reset <variant-id> --to-base|--to-approved ...
+```
 
-Variant metadata lives with the skill declaration in `skillboard.config.yaml`:
+Before using a migrated variant, set its v2 policy explicitly:
 
 ```yaml
+version: 2
 skills:
-  claude.a:
-    variant:
-      of: a
-      capability: task-review
-      workflow: claude-workflow
-      status: approved
-      adapted_for: claude
-      base:
-        content_digest: sha256:...
-        snapshot: .skillboard/variant-snapshots/claude.a/base.md
-      approved:
-        content_digest: sha256:...
-        snapshot: .skillboard/variant-snapshots/claude.a/approved.md
+  claude-review:
+    enabled: true
+    shared: false
+    preference:
+      intents:
+        - review
+      priority: 100
 ```
 
-Snapshots are raw file records under `.skillboard/variant-snapshots/<encoded-skill-id>/`. That directory is created lazily by lifecycle commands such as `variant fork` and `variant approve`; `skillboard init` does not need to pre-create snapshot directories. A reset can restore the base or approved content safely from those records. The lifecycle helpers verify that snapshot and live paths stay inside the configured workspace before writing files.
-
-## Safety boundaries
-
-- `variant fork` and `variant add` create policy metadata; they do not make a newly edited skill equivalent to the base.
-- `variant approve` should happen only after human review of the live `SKILL.md` body and the `variant status` digest output.
-- `variant reset` writes files only through the safe replacement helper and refuses ambiguous reset targets.
-- A variant is still governed by normal capability, workflow, exposure, install-unit, and invocation checks.
+These authorization-mutating compatibility commands do not change v2 policy.
+Use the ordinary v2 enable/disable/share/unshare commands for policy changes.

package/docs/versioning.md

@@ -1,278 +1,45 @@
 # Versioning
 
-SkillBoard has several versioned surfaces. They should not all move at the same
-pace, and not every skill file belongs in central version control.
+SkillBoard is public alpha. Package releases follow semantic versioning; policy
+schema versions are explicit inside `skillboard.config.yaml`.
 
-This document defines the public alpha policy for releases, config compatibility,
-source profiles, and the generated lockfile.
+## Policy schema timeline
 
-## Status
+- v0.3.0 introduces policy schema v2; later v0.3.x releases continue to write it.
+- v0.3.x provides a one-release read-only window for policy schema v1.
+- v0.4.0 removes the v1 reader and v1 compatibility projection.
+- v1 mutation is never supported after v2 ships; migrate first.
 
-Current package version: `0.2.18`
-
-Current config schema version:
-
-```yaml
-version: 1
-```
-
-The project is a public alpha. Breaking changes are allowed before `1.0.0`, but
-they must be documented in release notes and should include a migration note when
-they affect user config.
-
-## Versioned Surfaces
-
-SkillBoard versions these surfaces deliberately:
-
-- CLI package version: the npm package and command behavior.
-- Config schema version: the top-level `version` field in
-  `skillboard.config.yaml`.
-- Source profile format: YAML files under `profiles/` and project-specific
-  `.skillboard/profiles/`.
-- Workflow contracts: workflow names, required capabilities, active skill pools,
-  required outputs, and harness choices.
-- Capability contracts: canonical skill, alternatives, and default policy for a
-  capability.
-- Exported skill entries: shared or vendor skills governed by SkillBoard.
-- Install-unit entries: plugin, marketplace, package, harness, MCP, hook, agent,
-  and LSP sources.
-- Lockfile data: pinned source/cache digest, skill content digests, policy, and
-  compatible harnesses.
-
-SkillBoard does not try to centrally version every prompt or helper skill. A
-workflow-internal private skill can remain inside that workflow package until it
-becomes shared, auto-invokable, vendor-provided, or cross-workflow.
-
-## Release Versioning
-
-The package follows SemVer with a stricter alpha convention:
-
-- Patch: bug fixes, docs, new tests, safer validation, and non-breaking profile
-  additions.
-- Minor: new commands, new config fields with safe defaults, new report sections,
-  new built-in source profiles, and new policy checks that are warnings first.
-- Major: post-`1.0.0` breaking CLI, config, or policy behavior.
-
-Before `1.0.0`, breaking changes may happen in minor releases, but the changelog
-must call them out clearly.
-
-Suggested tags:
-
-- `v0.1.0-alpha`: first public GitHub alpha.
-- `v0.2.7`: one-time runtime source review before manual activation, ask-after
-  skill routing, purge uninstall, README benefit-first positioning,
-  source inventory refresh, doctor/status, source pin refresh,
-  installer/config detection, resilient detector warnings, and richer dry-run
-  plans.
-- `v0.3.0-alpha`: signed remote source verification hardening and migration
-  workflow.
-- `v1.0.0`: config schema and core CLI behavior are stable enough for external
-  workflows to rely on.
-
-## Config Schema Version
-
-The top-level `version` field is the schema version, not the package version.
-
-Rules:
-
-- `version: 1` is the only supported schema today.
-- Missing `version` is treated as `1` for early compatibility.
-- Unsupported future versions must fail fast rather than silently parsing with
-  older semantics.
-- New fields should default to the safest behavior.
-- New automatic invocation behavior must be opt-in.
-- New policy checks should start as warnings unless they protect an important
-  safety boundary.
-
-Breaking schema changes need a migration note. A future `skillboard migrate`
-command can automate those changes, but it is not implemented yet.
-
-## Source Profile Versioning
-
-Source profiles are data, not hardcoded adapter branches. Built-in profiles live
-under `profiles/`; project profiles can live under `.skillboard/profiles/`.
-
-Profile compatibility rules:
-
-- Adding a new built-in profile is a patch or minor change.
-- Changing a built-in profile's namespace, target path prefix, default status,
-  default invocation, or default exposure is a breaking profile behavior change.
-- External profiles should not grant `global-auto` unless they also mark the
-  imported skills as `global-meta`.
-- External repository skills should normally import as `vendor`, `candidate`, or
-  `quarantined`, with `manual-only` or `router-only` invocation.
-- Harness/plugin bundle profiles should use `unit-managed` for child skills when
-  the parent bundle owns commands, hooks, MCP servers, or config mutation.
-
-Profile imports can be reviewed as fragments or merged directly:
+Exact migration commands:
 
 ```bash
-skillboard import \
-  --profile github.mattpocock.skills \
-  --source-root /path/to/source \
-  --out .skillboard/reports/import-fragment.yaml
+skillboard migrate v2 --config <path> --json
+skillboard migrate v2 --config <path> --yes --json
+skillboard migrate v2 --config <path> --rollback <backup> --json
 ```
 
-```bash
-skillboard import \
-  --profile github.mattpocock.skills \
-  --source-root /path/to/source \
-  --config skillboard.config.yaml \
-  --merge \
-  --dry-run
-```
-
-`--merge` is append-only by default. `--replace` is required to overwrite
-existing skill or install-unit ids. Drop `--dry-run` only after reviewing the
-reported text and YAML semantic change plan.
-
-## Workflow And Capability Versioning
-
-The primary unit of compatibility is the workflow, not an individual skill.
-
-Version these centrally:
-
-- workflow name and intent;
-- harness and fallback harness assumptions;
-- required capabilities;
-- active, blocked, and manual-only skill pools;
-- required outputs;
-- exported skill contracts used by more than one workflow;
-- policy decisions that allow automatic invocation.
-
-Avoid central versioning for:
-
-- one-off prompts;
-- workflow-internal helper skills;
-- private skills used by only one workflow;
-- temporary templates that are not auto-invokable;
-- implementation details inside a harness bundle.
-
-When a workflow changes its required outputs, required capabilities, or
-workflow-auto skill set, treat it as a compatibility change even if no file paths
-changed.
-
-## Lockfile Policy
-
-`skillboard lock write` generates `skillboard.lock.yaml` from the current
-workspace.
-
-The lockfile pins:
-
-- config schema version;
-- install-unit source, cache path, verified path, digest, and trust status;
-- skill id, path, and content hash;
-- workflow/capability bindings;
-- generated timestamp.
-
-The lockfile should represent a verified working set, not a desired-state file.
-Users should edit `skillboard.config.yaml`; tools should generate the lockfile.
-Local `source` and `cache_path` entries are digest-verified by `skillboard audit
-sources --verify`. Remote or command-based sources need a configured
-`source_digest` and, when signatures are used, a matching `public_key`.
-Fetchable Git sources can be materialized and pinned with `skillboard sources
-refresh`, which updates `cache_path`, `source_digest`, and `verified_at` in the
-config after cloning into `.skillboard/sources/`.
-Relative local paths are resolved from the config directory first and then from
-the current working directory, so bundled examples can use project-root-relative
-paths while project configs can still keep config-local paths.
-`skillboard lock write` refuses to write when verification has errors unless
-`--allow-unverified` is passed explicitly for investigation artifacts.
-
-## Release Checklist
-
-Before tagging a public release:
-
-- Run `npm run check`.
-- Run `node --check` across `src`, `test`, and `bin`.
-- Run `npm pack --dry-run --json` and confirm internal artifacts are excluded.
-- Run at least one CLI smoke test through the public surface.
-- Confirm docs mention any breaking config, profile, or CLI changes.
-- Update package version and release notes.
-- Confirm the repository `NPM_TOKEN` secret can publish `agent-skillboard`.
-  The publish job uses that token for npm authentication and requests
-  provenance with GitHub Actions OIDC, so keep `permissions.id-token: write`,
-  the npm registry URL in `setup-node`, and
-  `NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}` on the publish step.
-- Push a version tag that exactly matches `package.json`, for example `v0.2.7`
-  for package version `0.2.7`.
-- Let `.github/workflows/publish.yml` publish from the tag. The workflow runs
-  the full check suite, validates that the tag matches the package version, and
-  skips `npm publish` only when that exact version already exists on npm.
-
-For alpha releases, include a short "completion notes" section. Current
-completion notes:
-
-- source inventory refresh covers known local agent skill roots, plugin-cache
-  manifests, and user-supplied scan roots;
-- `sources refresh` covers Git-compatible remote sources and digest pin refresh;
-- `inventory detect` covers installer output and explicit mutated config files
-  for commands, hooks, MCP servers, and modified config paths;
-- dry-run plans report a capped YAML semantic change list rather than full patch
-  hunks;
-- unusual YAML trivia may still be normalized during structured config writes.
-
-## 0.1.1 Completion Notes
-
-- duplicate installed skill IDs are consolidated into one canonical skill entry
-  with duplicate source locations preserved as metadata;
-- canonical duplicate skills can be shared by Codex and Hermes local workflows
-  without generating user-visible `-2` suffixes;
-- README and install docs include a Hermes system prompt bridge for profiles
-  that do not automatically read `AGENTS.md` or `CLAUDE.md`.
-
-## 0.1.2 Completion Notes
-
-- add `--version` and `-v` flags to the CLI for fast version verification in
-  npm, global, source-tree, and tarball installs;
-- add a dedicated test for the version flags;
-- update README quick-start to verify the installed version before running
-  policy commands.
-
-## 0.2.7 Completion Notes
-
-- reject direct `skillboard activate` and `skillboard prefer` attempts for
-  reviewed runtime/plugin skills that remain `status: blocked`, while
-  preserving reviewed quarantined manual-only activation.
-
-## 0.2.6 Completion Notes
-
-- keep reviewed `status: blocked` runtime/plugin skills non-activatable while
-  preserving the reviewed quarantined runtime/plugin manual activation path.
-
-## 0.2.5 Completion Notes
-
-- align reset-cleanup action-card preview and apply internals with the full
-  `.skillboard/` purge semantics used by `skillboard uninstall --purge`.
-
-## 0.2.4 Completion Notes
+Preview is non-mutating, apply creates an adjacent byte-for-byte backup, and
+rollback restores the selected backup. Old action ids, hooks, and lock
+projections are invalid after migration.
 
-- broaden `skillboard uninstall --purge` from reports/hooks cleanup to removal
-  of the full `.skillboard/` project state directory, covering source caches,
-  rollout logs, variant snapshots, profiles, hooks, and reports while preserving
-  local skill files.
+## Versioned v2 contract
 
-## 0.2.3 Completion Notes
+Policy availability requires `enabled: true` and generated installation presence
+for the selected agent. `shared` controls only explicit managed propagation.
+Preference ranks only. Source and provenance observations are informational and
+cannot change availability. Runtime and action authorization remain outside the
+schema.
 
-- add `skillboard uninstall --purge` for users who want SkillBoard's policy
-  influence and generated footprint removed while preserving local skill files;
-- document the lifecycle split between conservative bridge cleanup and full
-  SkillBoard policy-footprint removal;
-- show purge in cleanup action cards so users do not need to remember the
-  older `--reset-config --remove-reports --remove-hooks` sequence.
+## Release checklist
 
-## 0.2.2 Completion Notes
+1. Run `npm run check`.
+2. Run `npm pack --dry-run --json` and inspect public contents.
+3. Confirm `CHANGELOG.md` includes the package version.
+4. Create a matching `vX.Y.Z` tag.
+5. `.github/workflows/publish.yml` verifies the tag exactly matches
+   `package.json`, configures the registry URL in `setup-node`, then runs
+   `npm publish` with provenance.
 
-- recommend one-time review, not default blocking, for high-risk runtime/plugin
-  install units;
-- after source review, allow quarantined runtime/plugin skills to be activated
-  as `manual-only` workflow skills before any ask-after preference is recorded;
-- add ask-after route policy suggestions for safe ambiguous workflow skill
-  matches while preserving the public route JSON contract;
-- carry route candidate guard and capability roles into AI-facing brief
-  guidance;
-- keep no-match and guard-denied routes free of use disclosures or post-use
-  policy suggestions;
-- update README positioning around user benefit, no-global-install usage,
-  read-only normal checks, explicit approval for policy changes, and
-  conservative previewable cleanup.
+Publishing uses `NPM_TOKEN` through `NODE_AUTH_TOKEN`. Prefer npm trusted
+publishing with OIDC when available. Release automation skips `npm publish`
+only when that exact version already exists on npm.