agent-skillboard 0.2.18 → 0.3.1

package/docs/policy-model.md

@@ -1,303 +1,73 @@
 # Policy Model
 
-SkillBoard separates storage from invocation.
-
-For product and AI-mediated development, read
-[`docs/ai-skill-routing-goal.md`](ai-skill-routing-goal.md) before changing
-routing, brief, bridge, policy, or workflow UX. The policy model should support
-a non-blocking flow where the AI routes and works first when safe, then asks
-afterward only when remembering a usage policy would reduce future ambiguity.
-
-## Skill States
-
-- `installed`: discovered on disk from `SKILL.md`.
-- `declared`: present in `skillboard.config.yaml`.
-- `discovered`: present in actual state but not yet classified.
-- `quarantined`: visible to the control plane but not callable.
-- `active`: allowed in at least one workflow.
-- `active` with `invocation: manual-only`: active only for direct user invocation.
-- `active-manual`: legacy spelling accepted for compatibility.
-- `active-router`: active only through a policy-checked router.
-- `active-auto`: active for workflow-scoped automatic invocation.
-- `candidate`: proposed for one or more workflows, pending approval.
-- `canonical`: the preferred implementation for a capability.
-- `vendor`: kept from an upstream source, but not automatically trusted.
-- `blocked`: never callable.
-- `deprecated`: kept for historical compatibility.
-- `archived`: retained outside normal workflows.
-- `removed`: absent from actual state but retained in history or lock data.
-
-## Skill Exposure
-
-Skill exposure controls whether a skill belongs in central governance or should
-stay inside a workflow or install-unit boundary.
-
-- `exported`: shared or externally visible skill governed by SkillBoard.
-- `global-meta`: intentionally global control skill such as a workflow router,
-  impact analyzer, skill registry, or verification gate.
-- `unit-managed`: skill supplied by a parent plugin/harness install unit.
-- `private`: workflow-internal implementation detail.
-
-Only `global-meta` skills may use `global-auto`. This keeps a user's small set
-of personal control skills globally available while plugin-provided skills remain
-selected through workflows or install units.
-
-Skills can also declare `owner_install_unit`. This points to the source that
-introduced the skill, such as a private skill repository, GitHub marketplace,
-package manager dependency, or harness installer. SkillBoard treats owner drift
-as a policy error:
-
-- `components.skills` entries must reference declared skills.
-- A skill with `owner_install_unit` must be listed in that install unit's
-  `components.skills`.
-- A component skill cannot claim a different owner than the install unit listing
-  it.
-- `unit-managed` skills must declare `owner_install_unit`.
-
-## Invocation Modes
-
-- `manual-only`: direct user invocation only.
-- `router-only`: selected by an approved routing skill or control layer.
-- `workflow-auto`: eligible for model invocation only inside workflows that list
-  the skill.
-- `global-auto`: eligible everywhere. This should be rare.
-- `blocked`: not callable even when installed.
-- `deprecated`: not callable for new workflows.
-
-## Default Policy
-
-SkillBoard assumes:
-
-```yaml
-defaults:
-  invocation_policy: deny-by-default
-  allow_model_invocation: false
-  require_explicit_workflow: true
-```
-
-That means installation alone never implies automatic use.
-
-`require_explicit_workflow: true` means a `workflow-auto` skill must be scoped by
-at least one workflow, either through `active_skills` or a workflow capability
-requirement. `allow_model_invocation: false` is not a blanket ban on
-workflow-scoped automation; it means automatic invocation must come from an
-explicit policy decision rather than installation.
-
-## AI-Mediated Availability
-
-`skillboard brief --json` is the AI-facing availability contract. The user does
-not need to know the command loop: they can ask their AI what skills are
-available, why something is blocked, or whether a reviewed skill can be made
-available for a workflow. Behind the scenes, the AI should read the current
-brief and answer "What your AI can use now" with grouped facts from the control
-plane instead of trusting installed `SKILL.md` text or inventing policy from the
-filesystem.
-
-Human brief text separates reviewable friction from hard blocks: "Needs your
-decision" means the user can make a source/skill/workflow decision once, while
-"Blocked for safety" means policy or provenance must change before the item is
-usable. The brief may include action cards when requested, but an action card is
-only a suggestion. It does not authorize invocation and it does not make
-unreviewed external skills safe for automatic use.
-
-Risk-bearing action cards require user confirmation before apply. Any apply
-that mutates policy, trust, hooks, reset state, or skill references makes the
-previous brief stale, so the agent should use one current action id from the
-current brief and then rerun `skillboard brief --json` before answering another
-availability question or applying another action card. The runtime boundary
-remains `skillboard guard use ...`, run immediately before the actual skill
-invocation. A passing guard is not another user confirmation step: the agent
-should disclose the selected skill before use and mention it again in the
-result. That disclosure is an audit trace, not a permission prompt. CLI examples
-in this model are AI/automation/operator details, not a memorized user workflow.
-
-## Workflow Activation
-
-Workflows own active skill pools:
-
-```yaml
-workflows:
-  codex-night-workflow:
-    harness: codex
-    active_skills:
-      - meerkat.requirement-intake
-      - matt.tdd
-    blocked_skills:
-      - matt.grill-me
-```
-
-The generated lockfile pins install-unit source/cache digests, skill content
-digests, workflow bindings, and policy decisions.
-
-## Skill Conflicts
-
-Skills can declare known overlap or incompatibility with `conflicts_with`:
+SkillBoard v2 keeps one user-level policy and makes two durable decisions per
+skill: enable or disable it, then keep it agent-local or share it across agents.
 
 ```yaml
+version: 2
 skills:
-  meerkat.requirement-intake:
-    path: requirement-intake
-    status: active
-    invocation: router-only
-    exposure: exported
-    category: requirements
-    conflicts_with:
-      - matt.grill-me
-```
-
-The referenced skill must be declared. If both sides of a declared conflict are
-active or capability-selectable in the same workflow, and neither is explicitly
-blocked there, policy fails. `skillboard guard use ...` denies the selected
-skill with a conflict reason, `brief` moves the affected skill into "Blocked for
-safety", and `impact disable <skill-id> --json` reports `conflictingSkills` plus
-`activeConflicts`. This gives the AI a concrete reason to ask for a policy
-change instead of silently choosing between overlapping skills.
-
-## Capabilities
-
-Workflows should depend on capabilities when possible, with skills acting as
-implementations:
-
-```yaml
-capabilities:
-  requirement-clarification:
-    canonical: meerkat.requirement-intake
-    alternatives:
-      - matt.grill-me
-      - matt.grill-with-docs
-    default_policy: router-only
+  test-first:
+    enabled: true
+    shared: false
+  docs-helper:
+    enabled: true
+    shared: true
+  unused-helper:
+    enabled: false
+    shared: false
 ```
 
-This lets SkillBoard suggest replacements when a skill is removed and group
-overlapping skills by role instead of by name alone.
-
-Explicit variants use the same capability and workflow fields. For example,
-`skillboard variant add claude.a --from a --capability task-review --workflow
-claude-workflow --path claude/a ...` records the user-approved `a -> claude.a`
-relationship, makes `claude.a` preferred for that workflow, and keeps `a` as a
-fallback. For a reviewed manual adaptation lifecycle, `skillboard variant fork
-<variant-id>` creates draft metadata and raw snapshot records, `skillboard
-variant status <variant-id>` reports `variant.status` plus computed drift, and
-`skillboard variant approve <variant-id>` promotes the reviewed body. Use
-`skillboard variant reset <variant-id>` with `--to-base` or `--to-approved` to
-restore a known snapshot. SkillBoard records workflow policy across agents; it
-does not convert skill bodies, does not rewrite skill bodies, and does not
-guarantee semantic equivalence of skill bodies.
+`enabled: false` is the only disabled state. `shared: false` is the default and
+means SkillBoard does not propagate the skill; it is not isolation or a safety
+judgment. `shared: true` preserves the agent-owned original and creates managed
+compatible copies for other supported agents.
 
-When the reconciler discovers a new non-user skill that already maps to a
-capability, it uses `default_policy` as the recommended invocation mode. The
-status remains `quarantined`, so the recommendation is visible but not
-automatically callable.
+## Optional routing preference
 
-## Harness Lifecycle
-
-Harnesses have their own state because removing a harness can break command
-flows even when the skills still exist:
+Preference ranks enabled skills installed for the current agent. It never
+changes availability and never shares files.
 
 ```yaml
-harnesses:
-  lazycodex:
-    status: fallback
-    workflows:
-      - large-refactor-workflow
-    commands:
-      - $ulw-plan
-      - $start-work
+  test-first:
+    enabled: true
+    shared: false
+    preference:
+      intents:
+        - implementation
+        - testing
+      priority: 100
 ```
 
-The reconciler treats missing configured harnesses as migration events and
-newly detected harnesses as disabled until a workflow opts in.
+An explicit user selection wins when the guard allows it. A high priority cannot
+enable a disabled skill or make a skill appear on an agent where it is absent.
 
-## Install Units
+## Generated inventory
 
-SkillBoard models packaged agent runtime changes as install units. This keeps a
-plugin bundle or opinionated harness installer from being flattened into a list
-of unrelated skills.
+`~/.skillboard/inventory.json` is generated observation data. Its `installed_on`
+list tells routing and guard which supported agents can see each skill. Users do
+not maintain an agent matrix in policy.
 
-Supported install unit kinds:
+Source, provenance, install-unit, path, digest, alias, and risk observations are
+optional audit metadata and never determine availability. Runtime and action
+authorization are outside SkillBoard's scope and remain with the agent or
+harness.
 
-- `skill`
-- `plugin`
-- `marketplace`
-- `package-manager-dependency`
-- `harness`
-- `mcp-server`
-- `hook`
-- `agent`
-- `lsp`
+## Installation default
 
-Each unit can record:
+A newly discovered valid skill receives `enabled: true` and `shared: false`.
+Inventory refresh preserves existing user policy. After the owning installer
+permanently removes a skill, `skillboard skill forget <skill-id>` explicitly
+removes its stale unshared policy; it never deletes skill files.
 
-- source command or package origin;
-- install scope such as user-global, project, local, or admin;
-- manifest and cache paths;
-- provided components;
-- modified config files;
-- auto-update and enable/disable state;
-- workflow dependencies;
-- permission risk;
-- rollback shape.
+## Version 1 migration reference
 
-Example:
+Version 1 is accepted only as read-only migration input during the v0.3.x
+window:
 
-```yaml
-install_units:
-  lazycodex.omo:
-    kind: harness
-    source: npx lazycodex-ai install
-    scope: user-global
-    manifest_path: ~/.codex/plugins/cache/sisyphuslabs/omo/plugin.json
-    cache_path: ~/.codex/plugins/cache/sisyphuslabs/omo
-    provided_components:
-      - skills
-      - commands
-      - mcp-server
-      - hook
-    components:
-      skills:
-        - lazycodex.ulw-plan
-      commands:
-        - $ulw-plan
-        - $start-work
-      hooks:
-        - post-tool-use
-      mcp_servers:
-        - omo-docs
-    modified_config_files:
-      - ~/.codex/config.toml
-      - ~/.local/bin
-    auto_update: false
-    enabled: true
-    workflow_dependencies:
-      - large-refactor-workflow
-    permission_risk: high
-    rollback: manual
+```bash
+skillboard migrate v2 --config <path> --json
+skillboard migrate v2 --config <path> --yes --json
+skillboard migrate v2 --config <path> --rollback <backup> --json
 ```
 
-The `examples/multi-source.config.yaml` fixture models a private skill source
-plus `mattpocock/skills`, `code-yeongyu/oh-my-openagent`,
-`anthropics/skills`, `wshobson/agents`, and
-`VoltAgent/awesome-agent-skills` in one workspace. It is intentionally a
-reproducible policy fixture, not a network installer.
-
-## Reconciliation
-
-SkillBoard compares desired state with actual state:
-
-- Desired state: config, workflows, capabilities, harnesses, and policy.
-- Actual state: discovered `SKILL.md` files and detected harnesses.
-- Reconcile plan: automatic safe actions plus decisions requiring approval.
-
-Safe automatic defaults:
-
-- Trusted user-local skills become `status: active` with
-  `invocation: manual-only` only when SkillBoard has no existing workflow
-  metadata and can create a local manual workflow.
-- Trusted user-local skills discovered after workflows exist become
-  `candidate` / `manual-only` with a review note instead of being attached to an
-  arbitrary workflow.
-- Runtime-supplied, external, system, or unreviewed skills are quarantined from
-  automatic use and surfaced as decisions when a safe review path exists.
-- New harnesses detected by reconciliation are disabled until workflows opt in.
-- Removed skills and harnesses produce impact reports before config changes.
-- Capability matches are surfaced as recommendations, not auto-activation.
+v0.4.0 removes the v1 reader.

package/docs/positioning.md

@@ -1,96 +1,29 @@
 # Positioning
 
-## Problem
+SkillBoard solves overlap routing for people who use different skill sets in
+multiple AI agents.
 
-AI agent skills are easy to install but hard to route consistently once several
-similar skills are broadly available.
+Its durable policy answers two questions:
 
-Users lose confidence when they cannot tell:
+1. Is this skill enabled?
+2. Should this one skill remain agent-local or be shared across agents?
 
-- which installed skills are active,
-- which skills may be invoked automatically,
-- which workflows depend on a skill,
-- which similar skills compete silently,
-- whether removing a skill breaks a hidden workflow.
-- what to do after new skills or harnesses appear.
-- how to migrate workflows when a harness disappears.
-- which plugin, marketplace, package, or installer introduced a component.
+Optional preference ranks enabled skills installed for the current agent and
+never changes availability.
 
-## Product Definition
+## Difference from distribution tools
 
-SkillBoard is a workflow-scoped skill routing board with a reconciler.
+A pure distribution tool copies a selected set everywhere. SkillBoard observes
+agent-local installations, routes among what the current agent can actually use,
+and promotes only explicitly selected skills into managed sharing. Users do not
+need to flatten every agent into one global skill set.
 
-It is not primarily a skill catalog or a deny-first permission wall. It is an
-operations layer that keeps skills broadly usable, turns overlap into a visible
-route, and still checks policy before invocation. Users define intent and
-policy; SkillBoard interprets drift between desired state and actual state.
+Source scanners and permission systems remain separate. Source and provenance
+observations are audit metadata and never determine availability.
+Runtime and action authorization are outside SkillBoard's policy scope.
 
-## Adjacent Tools
+## Product promise
 
-- `skillshare`: syncs skills across many agent targets.
-- Microsoft APM: reproduces agent context from `apm.yml` and lockfiles.
-- SkillGate/SkillGuard/SkillScope-style tools: scan, permissions, and security
-  risk.
-- SkillPilot/skill routers: pick relevant skills before inference.
-
-SkillBoard complements those tools by making invocation state, workflow impact,
-and migration decisions explicit.
-
-## Runtime Primitive Model
-
-SkillBoard should not depend on one installer shape. The likely ecosystem
-direction is manifest plus scope plus bundle plus cache plus enable/disable plus
-lockfile plus audit. That means the control plane needs a parent abstraction for
-the thing that was installed.
-
-The parent is an install unit. Skills and harnesses can then be child components
-of a `plugin`, `marketplace`, `package-manager-dependency`, `harness`,
-`mcp-server`, `hook`, `agent`, or `lsp` unit. LazyCodex-style installers should
-therefore show up as user-global harness/plugin bundles that provide commands,
-skills, MCP integrations, hooks, and config changes, not as loose skills mixed
-into the skill list.
-
-Users should be able to plug in workflow/harness bundles, then add only a small
-number of personal global meta skills. Those global meta skills are for control
-tasks such as routing, impact analysis, registry maintenance, and verification.
-Everything else should remain scoped to a workflow or owned by its parent install
-unit. This is how SkillBoard keeps skill count growth from becoming routing
-complexity.
-
-The multi-source fixture exercises this product claim with one private skill
-source plus five external repositories: a personal skill folder, a workflow skill
-pack, a harness bundle, a standard Agent Skills repository, a multi-harness
-plugin marketplace, and a catalog-style marketplace.
-
-Import adapters should follow the same principle. Popular repositories can have
-bundled source profiles, but the import logic should not branch on repository
-names. The stable contract is the normalized install-unit model, not a hardcoded
-adapter per source.
-
-## Wedge
-
-The first useful wedge is:
-
-1. read an existing skill folder,
-2. read a strong workflow policy config,
-3. quarantine newly discovered skills,
-4. show active/manual/blocked state,
-5. fail CI when policy references drift,
-6. show disable impact before cleanup,
-7. produce a reconcile plan when skills or harnesses change.
-8. show the install unit that introduced a skill, harness, hook, MCP server, or
-   command.
-
-That is enough to make adding and removing skills feel safer.
-
-## Reconciler Promise
-
-Control should not mean constant manual work. The reconciler should handle the
-obvious safe defaults and only ask for important decisions:
-
-- new skills: quarantine, map likely capability, ask whether to approve;
-- removed skills: show affected workflows and fallback capabilities;
-- changed harnesses: show missing commands and migration hints;
-- new harnesses: disable by default until explicitly assigned;
-- duplicate or overlapping skills: group by capability, keep allowed skills
-  available, and recommend a canonical route for the current workflow.
+Installing a valid skill makes it enabled and agent-local. Ordinary use never
+waits for quarantine or source review. Users intervene only to disable it,
+share or unshare that skill, or remember a routing preference.

package/docs/profiles.md

@@ -1,166 +1,34 @@
 # Source Profiles
 
-SkillBoard imports skill repositories through **source profiles**. A profile is a YAML file that tells SkillBoard how to find `SKILL.md` files in a source tree and how to classify the skills it finds, without writing repository-specific code.
+Source profiles teach inventory discovery where a skill pack stores skills and
+how paths map to stable ids. They do not authorize availability.
 
-## Why Profiles Exist
+## Profile YAML structure
 
-Agent skill repositories come in many layouts:
-
-- `skills/<category>/<skill>/SKILL.md`
-- `<skill>/SKILL.md`
-- deprecated or in-progress folders with special rules
-- namespaces such as `matt.tdd` or `anthropic.requirement-intake`
-
-Instead of hardcoding `if (repo === "mattpocock/skills")` branches, SkillBoard reads a declarative profile. The same importer code works for every source.
-
-## Profile Location
-
-Built-in profiles ship with the CLI under `profiles/`:
-
-- `profiles/mattpocock-skills.yaml`
-- `profiles/anthropics-skills.yaml`
-- `profiles/oh-my-openagent.yaml`
-- `profiles/wshobson-agents.yaml`
-- `profiles/voltagent-awesome-agent-skills.yaml`
-
-Project-specific profiles can live under `.skillboard/profiles/`:
-
-```bash
-skillboard import --profile .skillboard/profiles/my-team.yaml --source-root /path/to/repo
-```
-
-## Profile YAML Structure
-
-```yaml
-id: github.mattpocock.skills
-source: mattpocock/skills
-kind: marketplace
-namespace: matt
-target_path_prefix: matt
-scope: user-global
-default_status: vendor
-default_invocation: manual-only
-default_exposure: exported
-default_category: uncategorized
-category_path_segment: 1
-skill_paths:
-  - "skills/**/SKILL.md"
-  - "*/SKILL.md"
-path_rules:
-  - pattern: "skills/deprecated/**/SKILL.md"
-    status: deprecated
-    invocation: deprecated
-    category: deprecated
-  - pattern: "skills/in-progress/**/SKILL.md"
-    status: candidate
-    category: in-progress
-provided_components:
-  - skills
-permission_risk: medium
-rollback: reinstall
-```
-
-### Fields
-
-| Field | Required | Description |
-|-------|----------|-------------|
-| `id` | yes | Unique install-unit id used in `skillboard.config.yaml`. |
-| `source` | no | Human-readable source identifier, e.g. `owner/repo` or install command. |
-| `kind` | yes | One of the install-unit kinds: `skill`, `plugin`, `marketplace`, `harness`, `mcp-server`, `hook`, `agent`, `lsp`. |
-| `namespace` | no | Prefix added to every generated skill id. Empty means use the bare slug. |
-| `target_path_prefix` | no | Prefix added to every generated skill `path`. |
-| `scope` | no | Install scope: `user-global`, `project`, `local`, `admin`. |
-| `default_status` | no | Default skill `status`: `discovered`, `vendor`, `candidate`, `active`, `quarantined`, `blocked`, `deprecated`, etc. |
-| `default_invocation` | no | Default `invocation`: `manual-only`, `router-only`, `workflow-auto`, `blocked`, `deprecated`. `global-auto` is downgraded to `blocked`. |
-| `default_exposure` | no | Default `exposure`: `exported`, `global-meta`, `unit-managed`, `private`. |
-| `default_category` | no | Fallback category when no path rule or segment applies. |
-| `category_path_segment` | no | Reads a path segment from the matched `SKILL.md` path as category. `skills/engineering/tdd/SKILL.md` with segment `1` becomes `engineering`. |
-| `skill_paths` | yes | Glob patterns that identify `SKILL.md` files to import. |
-| `path_rules` | no | First-match overrides for paths such as `deprecated/**` or `in-progress/**`. |
-| `provided_components` | no | Components supplied by the install unit: `skills`, `commands`, `hooks`, `mcp_servers`. |
-| `permission_risk` | no | `low`, `medium`, `high`. |
-| `rollback` | no | Rollback strategy hint. |
-
-## How to Add a Built-In Profile
-
-1. **Create `profiles/<short-name>.yaml`.**
-
-   Pick a short, descriptive file name. The `id` field should be a stable dotted identifier.
-
-2. **Choose defaults that keep imported skills inactive.**
-
-   New external skills should default to `vendor` or `candidate` with `manual-only` or `router-only` invocation. Do not use `global-auto` for external repositories.
-
-3. **Add `path_rules` for repository conventions.**
-
-   If the repo has `deprecated/`, `in-progress/`, or `archive/` folders, override status and invocation there.
-
-4. **Test the profile against a real or fixture source.**
-
-   ```bash
-   skillboard import \
-     --profile github.myorg.skills \
-     --source-root /path/to/myorg-skills \
-     --out .skillboard/reports/myorg-import.yaml
-   ```
-
-   Review the emitted fragment before merging.
-
-5. **Add an integration test.**
-
-   Put a minimal fixture under `test/fixtures/` or `examples/` and add a test in `test/source-profiles.test.mjs` or `test/multi-source-integration.test.mjs`.
-
-6. **Update `package.json` `files` if needed.**
-
-   Profiles are already included via `"files": [..., "profiles", ...]`.
-
-## Example Walkthrough
-
-Given this repository layout:
-
-```
-myorg-skills/
-  engineering/
-    tdd/
-      SKILL.md
-    review/
-      SKILL.md
-  deprecated/
-    old-linter/
-      SKILL.md
-```
-
-and this profile:
+Profiles describe `skill_paths`, `path_rules`, source class, and optional
+install-unit observations. Import emits inventory/audit metadata and v2 policy
+entries for valid discovered skills. New entries default to enabled and agent-local;
+existing user policy is preserved.
 
 ```yaml
-id: github.myorg.skills
-source: myorg/skills
-kind: marketplace
-namespace: myorg
-target_path_prefix: myorg
-scope: user-global
-default_status: vendor
-default_invocation: manual-only
-default_exposure: exported
-category_path_segment: 0
+id: example-pack
 skill_paths:
-  - "**/SKILL.md"
+  - skills/*/SKILL.md
 path_rules:
-  - pattern: "deprecated/**/SKILL.md"
-    status: deprecated
-    invocation: deprecated
-    category: deprecated
-provided_components:
-  - skills
-permission_risk: medium
+  strip_prefix: skills/
+  strip_suffix: /SKILL.md
 ```
 
-SkillBoard produces:
+Source, provenance, trust observations, digests, and install-unit fields are
+optional audit metadata and never determine availability. Runtime and action
+authorization remain outside SkillBoard.
 
-- `myorg.tdd` → path `myorg/tdd`, category `engineering`, status `vendor`, invocation `manual-only`
-- `myorg.review` → path `myorg/review`, category `engineering`
-- `myorg.old-linter` → path `myorg/old-linter`, category `deprecated`, status `deprecated`, invocation `deprecated`
+## How to add a built-in profile
 
-## When to Use a Detector Instead
+1. Add the YAML under `profiles/`.
+2. Add a fixture with representative paths.
+3. Test deterministic ids and inventory output.
+4. Test that discovery creates enabled, agent-local policy without overwriting
+   an existing disabled or shared entry.
 
-Profiles cover most repository layouts. If a source mutates config files, exposes components only through command output, or requires parsing a non-YAML manifest, use `skillboard inventory detect` or write a small detector. See [adapters.md](adapters.md) for the adapter/detector model.
+Use a detector instead when an installation has no stable filesystem pattern.