agent-skillboard 0.2.18 → 0.3.1

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.