agent-skillboard 0.1.0

package/docs/plans/20260625-080025-skillboard-mvp-review.md

@@ -0,0 +1,189 @@
+# skillboard-mvp-review
+
+- Skill: tdd-work-continuity
+- Agent: hermes
+- Created: 2026-06-25T08:00:25Z
+- Updated: 2026-06-25T10:05:00Z
+- Workdir: /home/nyxxir/skillboard
+- Status: completed
+
+## Goal
+
+SkillBoard(`skill-control-plane`)의 MVP 기능과 낶부 도메인 설계를 검토하고, **처음 사용자가 skill을 가져다 붙이고 이용 및 삭제하는 불편을 해소하는 방향인지**, **도메인 설계가 적합하고 확장 가능한지**를 평가한다. 이전 대화에서 제안한 4.1~4.3 UX 개선 항목도 포함된 실행 계획을 문서화한다.
+
+## Context
+
+- Repo: `/home/nyxxir/skillboard`
+- Relevant files:
+  - `src/cli.mjs` — CLI 라우터
+  - `src/control.mjs` — skill/workflow/harness/capability CRUD, `can-use`, `guard`, trust/source 분류
+  - `src/domain/rules/*.mjs` — 정책 규칙 엔진
+  - `src/workspace.mjs` — config 파싱, `SKILL.md` frontmatter 파싱
+  - `src/agent-inventory.mjs` — 설치된 agent skill 자동 스캔/병합
+  - `src/brief-cli.mjs`, `src/brief-renderer.mjs`, `src/advisor.mjs` — AI/사용자 브리핑
+  - `src/impact.mjs`, `src/reconcile.mjs` — 영향도/재조정 분석
+  - `src/init.mjs`, `src/uninstall.mjs` — 생명주기
+- Constraints:
+  - MVP 단계, npm publish 전 (`version: 0.1.0`)
+  - Node.js >= 20, ESM, yaml 의존성 하나
+  - cross-platform CI (ubuntu/macOS/windows × node 20/22)
+
+## Findings Summary
+
+### 1. 도메인 설계: 적합하고 확장 가능함 (Score: 8/10)
+
+**핵심 엔티티 5개**가 skill 생태계의 실제 관심사를 잘 반영한다.
+
+| Entity | 역할 | 적합성 |
+|--------|------|--------|
+| `skills` | 선언된 스킬의 상태/호출방식/노출범위 | ✅ 적절. status/invocation/exposure 3중 분리로 정책 표현력 높음 |
+| `capabilities` | 역할 기반 스킬 추상화 | ✅ 적절. canonical/alternatives/default_policy로 교체/대안 추천 가능 |
+| `workflows` | 스킬이 활성화되는 맥락 | ✅ 적절. active_skills/blocked_skills/required_capabilities로 명시적 제어 |
+| `harnesses` | runtime/command 제공자 추적 | ✅ 적절. harness 제거 시 workflow 영향도 파악 가능 |
+| `install_units` | plugin/marketplace/harness 등의 부모 단위 | ✅ 매우 적절. skill 평탄화 문제 해결 |
+
+**확장 가능성**
+- `INSTALL_UNIT_KIND_VALUES`에 `skill`, `plugin`, `marketplace`, `harness`, `mcp-server`, `hook`, `agent`, `lsp`, `custom`을 두어 새로운 runtime primitive 추가가 용이함.
+- `source_classes.mjs`의 우선순위/분류 함수가 데이터 기반으로 되어 있어 새 source class 추가가 쉬움.
+- `source profile` 어댑터 모델이 하드코딩을 피하고 데이터 주도 import를 지향함.
+
+**위험 요소**
+- `src/control.mjs`가 1000줄에 달해 단일 책임 위반. `can-use`, CRUD, trust/source, YAML 쓰기, hook 설치 등이 한 파일에 있어 장기 유지보수 부담.
+- `status` 값이 14개로 많고, `status`와 `invocation` 간의 유효 조합 규칙이 복잡(`SKILL-STATUS-001`). 새로운 상태 추가 시 규칙 행렬이 기하급수적으로 늘어날 수 있음.
+- `capability`가 workflow-scoped `required_capabilities`와 global `capabilities`로 이중 정의됨. 의도는 명확하지만 사용자 입장에서 학습 곡선이 있음.
+
+### 2. 사용자 불편 해소 vs 가중
+
+#### 해소하는 설계
+
+| 기능 | 불편 해소 메커니즘 |
+|------|------------------|
+| `init` 시 자동 스캔 + `active-manual` 연결 | 기존 수동 스킬을 따로 등록하지 않아도 `can-use`/`guard`로 계속 사용 가능 |
+| `deny-by-default` + quarantine | 설치만으로 AI가 스킬을 부르는 것을 원천 차단 |
+| `impact disable` | 스킬 제거 전 영향받는 workflow/capability를 사전에 노출 |
+| 대부분의 mutating 명령에 `--dry-run` | 실수로 config를 망치는 위험 감소 |
+| `brief --json` | 에이전트가 정책을 직접 해석하지 않고 control plane에 질의 |
+| `uninstall`이 사용자 파일 보존 | 도구를 빼도 skill 파일과 사용자 config는 남음 |
+
+#### 가중할 수 있는 설계
+
+| 지점 | 불편 가능성 | 심각도 |
+|------|------------|--------|
+| 매번 `--config skillboard.config.yaml --skills skills` 필요 | 일상 명령이 번거로움 | 중간 |
+| `SKILL.md` frontmatter 누락 시 메시지가 모호함 | 처음 사용자가 문서를 찾아야 함 | 높음 |
+| `doctor` 출력이 길고 `--summary` 부재 | 매일 보기에 피로함 | 중간 |
+| `add workflow` 시 `--harness`를 명시해야 함 | harness 개념을 모르는 사용자에게 진입 장벽 | 중간 |
+| `status`/`invocation`/`exposure`/`trust_level` 용어가 많음 | 정책 도구이므로 불가피하지만, 온볭딩 문서가 중요 | 중간 |
+| `init` 후 생성되는 config가 수십 개 스킬로 즉시 커짐 | 실제로 설치된 게 많으면 압도적 | 낮음~중간 |
+
+**종합 판단**: 보안/통제를 얻는 대가로 적정 수준의 복잡성을 요구한다. 다만 **처음 사용자의 첫 5분**을 더 부드럽게 만들면 Adoption이 크게 올라갈 것이다.
+
+### 3. MVP 기능 검증 결과
+
+| 기능 | 상태 | 비고 |
+|------|------|------|
+| `init` | ✅ 정상 | bridge 파일, config, 디렉토리 생성, 자동 스캔 |
+| `doctor`/`status` | ✅ 정상 | safe-mode, strict 모드, JSON 출력 |
+| `brief` | ✅ 정상 | text/JSON, action cards, unknown workflow 처리 |
+| `add skill/workflow/harness` | ✅ 정상 | dry-run, 자동 status 승격 |
+| `activate`/`block`/`quarantine` | ✅ 정상 | workflow-scoped |
+| `can-use`/`guard` | ✅ 정상 | 정책 위반 시 거부 |
+| `impact disable` | ✅ 정상 | affected workflows/alternatives/risk |
+| `remove skill` | ✅ 정상 | 참조 시 거부, `--force`로 정리 |
+| `uninstall` | ✅ 정상 | 보수적 제거, dry-run |
+| `inventory refresh`/`detect` | ✅ 정상 | runtime component 감지 |
+| `sources refresh`/`audit` | ✅ 정상 | Git source digest pin |
+| `import`/`merge` | ✅ 정상 | built-in profiles |
+| `check` | ✅ 정상 | policy reference/rules |
+| `dashboard` | ✅ 정상 | markdown 보고서 |
+| `hook install` | ✅ 정상 | dry-run preview |
+
+### 4. 핵심 코드 품질 관찰
+
+- **정책 엔진**: `src/domain/rules/*.mjs`가 rule-id 기반으로 깔끔하게 분리되어 있어 새 규칙 추가가 쉬움.
+- **workspace 로딩**: `workspace.mjs`가 config 파싱과 설치 skill discovery를 분리. `SKILL.md` frontmatter 강제는 정합성을 위해 필요하지만, 에러 메시지가 개선되어야 함.
+- **control.mjs**: 거대 파일. CRUD, policy runtime, source classification, hook 설치 등을 분리하면 가독성과 테스트 용이성이 향상.
+- **writeCheckedConfig**: 임시 파일에 쓰고 policy + usability 검증 후 rename하는 방식은 안전함. dry-run과 실제 적용의 경계도 명확.
+- **agent-inventory**: detector 기반 스캔이 확장 가능. 다만 detector matching이 경로 suffix에 의존해 Windows/Linux 경로를 모두 고려한 점은 긍정적.
+
+## Plan
+
+### Phase 1: 첫 5분 UX 다듬기 (4.1)
+
+- [x] `workspace.mjs`의 `parseSkillFrontmatter` 에러 메시지 개선
+  - "SKILL.md is missing YAML frontmatter" → 필요한 frontmatter 예시와 docs/user-flow.md 링크 포함
+  - 예상 영향: `src/workspace.mjs` 1함수, test 1~2개 추가
+- [x] `add workflow`에서 `--harness` 누락 시 usage dump 대신 사용 가능한 harness 목록 제시
+  - 예상 영향: `src/cli.mjs` 또는 `src/control.mjs`의 `addWorkflow`
+- [x] `doctor`에 `--summary` 플래그 추가 (또는 기본 출력에서 1줄 status + 핵심 warnings만)
+  - 예상 영향: `src/doctor.mjs`, `src/report.mjs` 수정
+- [x] CLI 글로벌 defaults 파일/디렉토리 탐지: `--config`, `--skills` 미지정 시 현재 디렉토리의 `skillboard.config.yaml`과 `skills/`를 기본으로 사용하도록 개선
+  - 예상 영향: `src/cli.mjs` option parser, test 보강
+
+### Phase 2: 생태계 연결 및 문서 (4.2)
+
+- [x] `CONTRIBUTING.md` 작성: 개발 환경, 테스트 실행, source profile 추가 방법
+- [x] built-in profile 추가 가이드 문서화 (`docs/adapters.md` 보강 또는 `docs/profiles.md` 신규)
+- [x] README의 install 전/후 명령어 섹션 정리 (`skillboard` vs `node bin/skillboard.mjs` 구분 강조)
+- [x] 본 프로젝트에 `AGENTS.md`/`CLAUDE.md` bridge 적용 검토 (dogfooding)
+
+### Phase 3: 성능 및 구조 (4.3)
+
+- [x] `npm test` 실행 시간 프로파일링
+  - 병목이 되는 CLI 통합 테스트 식별
+  - 가능하다면 독립적인 단위 테스트와 통합 테스트 분리 (`npm run test:unit`, `npm run test:integration`)
+- [x] `src/control.mjs` 분리
+  - `skill-crud.mjs`, `workflow-crud.mjs`, `trust-source.mjs`, `can-use-guard.mjs`, `config-write.mjs` 등으로 쪼개기
+  - 예상 영향: 낶부 구조 개선, 기존 테스트 그대로 통과해야 함
+- [x] `doctor`/`brief`의 중복 workspace 로딩 최소화 (cache 또는 단일 로드 경로)
+
+### Phase 4: 도메인 정제 (선택, 높은 가치)
+
+- [x] `status`/`invocation` 매트릭스 검토: 14×7 조합 중 실제로 사용되는 조합을 문서화하고, 불필요한 조합은 deprecate 또는 명시적 금지
+- [x] `capability`의 global 정의와 workflow-scope `required_capabilities` 관계를 docs에 명확히 시각화
+- [x] `install_unit`의 `trust_level`과 `permission_risk` 조합에 따른 자동 권고 정책을 advisor action cards로 노출
+
+## TDD Notes
+
+- Red: Add failing tests for newly invalid status/invocation combos, capability docs, trust/risk action cards.
+- Green: Implement matrix, docs, and action card logic.
+- Refactor: `control.mjs` split into `src/control/*.mjs` modules; public API preserved.
+
+## Verification
+
+- Commands to run:
+  - `npm run diagnostics`
+  - `npm run test:unit`
+  - `npm run test:integration`
+  - `npm run check`
+  - `node bin/skillboard.mjs brief --config skillboard.config.yaml --skills skills`
+  - `git diff --check`
+- Results:
+  - TypeScript diagnostics: ✅
+  - `npm run test:unit`: 47 passed
+  - `npm run test:integration`: 103 passed
+  - `npm run check`: 161 passed
+  - CLI smoke test: ✅
+  - `git diff --check`: ✅
+
+## Decisions
+
+- **즉시 개선 권장**: 4.1 frontmatter 에러 메시지, `--config/--skills` 기본값, `doctor --summary`
+- **중기 개선 권장**: `control.mjs` 분리, test suite 분리, `CONTRIBUTING.md`
+- **도메인 설계는 유지**: 5개 엔티티 구조와 deny-by-default 정책은 변경하지 않음. 세부 상태/호출 매트릭스만 정제
+- **변경사항은 unstaged로 보관**: 사용자가 직접 커밋 지시 전까지 git index에 추가하지 않음
+
+## Resume State
+
+- Done: Phase 1~4 모두 완료. 모든 테스트 통과. 문서/워크로그 정리 완료.
+- In progress: 없음.
+- Next command: 사용자가 커밋/푸시 지시 또는 추가 개선 항목 제시
+- Open risks:
+  - `.skillboard/`와 `.omo/` 등 untracked artifact는 별도 정리 필요
+  - npm pack 시 포함 여부는 `test/package.test.mjs`에서 검증 완료
+
+## Progress Log
+
+- 2026-06-25T08:00:25Z: Plan created.
+- 2026-06-25T08:45:00Z: Domain audit, friction analysis, and improvement plan written.
+- 2026-06-25T10:05:00Z: Phase 1~4 implementation completed. All 161 tests passing.

package/docs/plans/README.md

@@ -0,0 +1,20 @@
+# Agent Handoff Plans
+
+This directory contains durable plans that can be picked up by another agent
+(such as Hermes) when the original author is not available.
+
+## Conventions
+
+- Each plan file is named `<timestamp>-<slug>.md`.
+- The `Status:` field in the frontmatter controls the lifecycle:
+  - `pending` — waiting for an agent to pick it up
+  - `assigned` — an agent is currently working on it
+  - `consumed` — the agent has finished the planned work
+- Agents should only pick up files with `Status: pending`.
+- After picking up a plan, change the status to `assigned` and commit.
+- After completing the work, change the status to `consumed` and commit.
+
+## Current Plans
+
+- `20260625-080025-skillboard-mvp-review.md` — SkillBoard MVP feature/domain
+  review and UX improvement plan (Status: completed)

package/docs/policy-model.md

@@ -0,0 +1,251 @@
+# Policy Model
+
+SkillBoard separates storage from invocation.
+
+## 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. It lets an
+agent 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 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.
+
+## 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.
+
+## 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
+```
+
+This lets SkillBoard suggest replacements when a skill is removed and group
+overlapping skills by role instead of by name alone.
+
+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.
+
+## Harness Lifecycle
+
+Harnesses have their own state because removing a harness can break command
+flows even when the skills still exist:
+
+```yaml
+harnesses:
+  lazycodex:
+    status: fallback
+    workflows:
+      - large-refactor-workflow
+    commands:
+      - $ulw-plan
+      - $start-work
+```
+
+The reconciler treats missing configured harnesses as migration events and
+newly detected harnesses as disabled until a workflow opts in.
+
+## Install Units
+
+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.
+
+Supported install unit kinds:
+
+- `skill`
+- `plugin`
+- `marketplace`
+- `package-manager-dependency`
+- `harness`
+- `mcp-server`
+- `hook`
+- `agent`
+- `lsp`
+
+Each unit can record:
+
+- 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.
+
+Example:
+
+```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
+```
+
+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.

package/docs/positioning.md

@@ -0,0 +1,94 @@
+# Positioning
+
+## Problem
+
+AI agent skills are easy to install but hard to govern.
+
+Users lose confidence when they cannot tell:
+
+- 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.
+
+## Product Definition
+
+SkillBoard is a workflow-scoped skill control board with a reconciler.
+
+It is not primarily a skill catalog. It is an operations layer that turns a
+skill repository into a visible, policy-checked system. Users define intent and
+policy; SkillBoard interprets drift between desired state and actual state.
+
+## Adjacent Tools
+
+- `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 skills: group by capability and recommend a canonical
+  implementation.