@skill-map/spec 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,96 @@
+# Spec changelog
+
+## 0.1.0
+
+### Minor Changes
+
+- 5b3829a: Add conformance case `kernel-empty-boot`:
+
+  - New file: `spec/conformance/cases/kernel-empty-boot.json`.
+  - Exercises the boot invariant from `architecture.md`: with every adapter, detector, and rule disabled, scanning an empty scope MUST return a valid `ScanResult` with `schemaVersion: 1` and zero-filled stats.
+  - Referenced in `conformance/README.md` (§"Cases explicitly referenced elsewhere in the spec"). Entry moved from "pending" to "current" in the case inventory.
+  - Registered in `spec/index.json` and the integrity block (SHA256 regenerated).
+
+  The second pending case, `preamble-bitwise-match`, is deferred to Step 9 (requires `sm job preview` from the job subsystem).
+
+- 4e0aec4: Initial public spec surface (`v0.1.0`):
+
+  - 21 JSON Schemas (draft 2020-12): 10 top-level, 6 frontmatter, 5 summaries.
+  - 7 prose contracts (architecture, cli-contract, dispatch-lifecycle, job-events, prompt-preamble, db-schema, plugin-kv-api).
+  - 1 interface doc (security-scanner).
+  - Conformance stub: `basic-scan` case, `minimal-claude` fixture, verbatim `preamble-v1.txt`.
+  - Machine-readable `index.json` with integrity hashes per file.
+
+  This is the first tagged release of the skill-map specification.
+
+Changelog for the **skill-map specification**, tracked independently from the reference CLI. See `versioning.md` for the policy that governs what constitutes a patch / minor / major change.
+
+Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html) as refined in `versioning.md`.
+
+Each entry classifies changes into four sections:
+
+- **Added** — new optional fields, schemas, or contracts.
+- **Changed** — modifications to existing normative content. Breaking changes are called out explicitly.
+- **Deprecated** — features scheduled for removal in a future major.
+- **Removed** — features removed in a major bump.
+
+Tag convention: `spec-vX.Y.Z` (distinct from CLI tags `cli-vX.Y.Z`).
+
+---
+
+## [Unreleased]
+
+Initial public spec bootstrap (Step 0a phases 1–3).
+
+### Added
+
+- Foundation:
+  - `README.md` — human-readable introduction and repo layout.
+  - `versioning.md` — evolution policy, stability tags, 3-minor deprecation window.
+  - `CHANGELOG.md` — this file.
+- JSON Schemas (21 files, all draft 2020-12, camelCase keys):
+  - Top-level (10): `node`, `link`, `issue`, `scan-result`, `execution-record`, `project-config`, `plugins-registry`, `job`, `report-base`, `conformance-case`.
+  - Frontmatter (6): `base` + per-kind `skill` / `agent` / `command` / `hook` / `note`. Per-kind schemas extend `base` via `allOf`.
+  - Summaries (5): per-kind `skill` / `agent` / `command` / `hook` / `note`. All extend `report-base` via `allOf`.
+- Prose contracts:
+  - `architecture.md` — hexagonal ports & adapters; 5 ports (`StoragePort`, `FilesystemPort`, `PluginLoaderPort`, `RunnerPort`, `ProgressEmitterPort`); 6 extension kinds (Adapter, Detector, Rule, Action, Audit, Renderer); kernel boundary + forbidden/permitted imports.
+  - `cli-contract.md` — CLI surface: global flags, env vars, 30+ verbs (`sm init`, `sm scan`, `sm list`, `sm show`, `sm check`, `sm findings`, `sm graph`, `sm export`, `sm job *`, `sm record`, `sm history`, `sm plugins *`, `sm audit *`, `sm db *`, `sm serve`, `sm help`), exit codes (0–5 defined, 6–15 reserved), `--json` output rules, `--format json|md|human` introspection.
+  - `dispatch-lifecycle.md` — job state machine (queued → running → completed | failed), atomic claim (`UPDATE ... RETURNING id`), duplicate prevention via `contentHash`, TTL with auto-reap, nonce authentication for `sm record`, sequential concurrency for MVP, retention and GC.
+  - `job-events.md` — canonical event stream: envelope (`type`, `timestamp`, `runId`, `jobId`, `data`), 10 event types (`run.started`, `run.reap.started`, `run.reap.completed`, `job.claimed`, `job.skipped`, `job.spawning`, `model.delta`, `job.callback.received`, `job.completed`, `job.failed`, `run.summary`), three output adapters (`pretty`, `stream-output`, `json`), ordering rules.
+  - `prompt-preamble.md` — verbatim normative preamble text that the kernel prepends to every rendered job file; `<user-content id="...">` delimiter contract with zero-width-space escaping; `safety` + `confidence` contract on model output; conformance fixture at `conformance/fixtures/preamble-v1.txt`.
+  - `db-schema.md` — engine-agnostic table catalog: three zones (`scan_*`, `state_*`, `config_*`), naming conventions (snake*case, zone prefix, `_at` / `_ms` / `_hash` / `_json` / `_count` suffixes, `is*`/`has\_` prefixes), kernel table list per zone, migration rules (`.sql`files,`NNN_snake_case.sql`, up-only, auto-backup), plugin storage modes.
+  - `plugin-kv-api.md` — `ctx.store` contract for mode A (`KvStore.get/set/delete/list`, plugin-scoped, optional node-scoped), mode B dedicated-tables rules (prefix injection, DDL validation, scoped Database wrapper), typed errors (`KvKeyInvalidError`, `KvValueNotSerializableError`, `KvValueTooLargeError`, `KvOperationFailedError`, `ScopedDbViolationError`). Mixing modes in a plugin is forbidden.
+- Interfaces:
+  - `interfaces/security-scanner.md` — convention over the Action kind (id prefix `security-`) for third-party security scanners (Snyk, Socket, custom). Defines `SecurityReport` shape extending `report-base.schema.json`, normative finding categories, deduplication rules, aggregation via `sm findings --security`. Marked `Stability: experimental` through v0.x.
+
+### Conventions locked (normative)
+
+- JSON Schema dialect: draft 2020-12.
+- Casing: camelCase for all JSON keys (domain, configs, manifests, reports); kebab-case for filenames.
+- `$id` scheme: `https://skill-map.dev/spec/v<major>/<path>.schema.json`. `v0` throughout pre-1.0; bumps to `v1` at the first stable cut.
+- Identity: `node.path` (relative to scope root) is the canonical node identifier in v0. Future UUID-based `node.id` lands with write-back.
+- Required frontmatter: `name`, `description`, `metadata`, `metadata.version`.
+- Frontmatter: `additionalProperties: true` (rules handle unknown fields). Summaries: `additionalProperties: false` (strict).
+- Id prefixes: job `d-`, execution record `e-`, run `r-` (all `PREFIX-YYYYMMDD-HHMMSS-XXXX`).
+- Exit codes: 0 ok / 1 issues / 2 error / 3 duplicate / 4 nonce-mismatch / 5 not-found.
+- Deprecation window: 3 minor releases between `stable → deprecated` and removal.
+- Storage modes: a plugin declares exactly one (`kv` or `dedicated`). Mixing forbidden.
+
+### Conformance (stub)
+
+- `conformance/README.md` — suite layout, case format, assertion types (`exit-code`, `json-path`, `file-exists`, `file-contains-verbatim`, `file-matches-schema`, `stderr-matches`), runner pseudocode.
+- `conformance/fixtures/minimal-claude/` — 5 MDs (one per kind: skill, agent, command, hook, note) used as the first controlled corpus.
+- `conformance/fixtures/preamble-v1.txt` — verbatim extraction of the preamble from `prompt-preamble.md`, checked byte-for-byte by the future `preamble-bitwise-match` case.
+- `conformance/cases/basic-scan.json` — first declarative case. Scans the `minimal-claude` fixture; asserts `schemaVersion: 1`, 5 nodes, 0 issues.
+
+### Packaging
+
+- `package.json` at the spec root. Name: `@skill-map/spec`. Version `0.0.1` (first release line; spec versioning is strict pre-1.0 per `versioning.md`). `exports` surfaces `.` → `index.json`, plus every `./schemas/*.json`.
+- `index.json` at the spec root. Machine-readable manifest of schemas, prose, interfaces, and conformance. Carries an `integrity` block with a sha256 per shipped file, deterministically regenerated by `scripts/build-spec-index.mjs`. CI blocks drift via `npm run spec:check`.
+- `schemas/conformance-case.schema.json` — formal schema for entries under `conformance/cases/*.json`. Defines the `invoke` object and the six assertion types (`exit-code`, `json-path`, `file-exists`, `file-contains-verbatim`, `file-matches-schema`, `stderr-matches`) as a discriminated union via `oneOf`.
+
+### Notes
+
+- Pending for `spec-v0.1.0`: cases `kernel-empty-boot` and `preamble-bitwise-match` (referenced normatively in `architecture.md` and `prompt-preamble.md`). Land alongside Step 0b when the reference implementation exists to run them against.
+- No tagged spec release yet. First tag (`spec-v0.1.0`) lands after Step 0b CI validates the implementation against this stub.
+- Release pipeline: `@skill-map/spec` is published via [changesets](https://github.com/changesets/changesets). Every PR that touches `spec/` includes a `.changeset/*.md` declaring the bump; merging to `main` opens a "Version Packages" PR; merging that PR publishes to npm and tags the release. See `CONTRIBUTING.md`.

package/README.md

@@ -0,0 +1,105 @@
+# skill-map spec
+
+The **skill-map specification** defines a vendor-neutral standard for mapping, inspecting, and managing collections of interrelated Markdown files — skills, agents, commands, hooks, and notes that compose AI-agent ecosystems (Claude Code, Codex, Gemini, Obsidian vaults, docs sites, and any future platform).
+
+This document is the **source of truth**. The reference implementation under `../src/` conforms to this spec. Third parties can build alternative implementations (any language, any UI, any CLI) using only `spec/`, without reading the reference source.
+
+## What this spec defines
+
+- The **domain model**: nodes, links, issues, scan results.
+- The **extension contract**: six extension kinds (detector, adapter, rule, action, audit, renderer) with their input/output shapes.
+- The **CLI contract**: verb set, flags, exit codes, JSON introspection.
+- The **persistence contract**: table catalog owned by the kernel, plugin key-value API.
+- The **job contract**: lifecycle states, event stream, prompt preamble, dispatch semantics.
+- The **frontmatter standard**: base fields and per-kind extensions.
+- The **summary standard**: shape of action-produced summaries per kind.
+- The **plugin manifest**: metadata, spec-compat range, storage mode, security declarations.
+
+## What this spec does not define
+
+- Language or runtime of the implementation.
+- Database engine (spec assumes a relational, SQL-like store; engine-agnostic).
+- UI framework, theming, layout.
+- Test framework (conformance suite is language-neutral data, not code).
+- Logging format, telemetry, or distribution channels.
+- Plugin marketplace mechanics.
+
+These are implementation decisions. The reference impl picks them (see `../CLAUDE.md` and `../ROADMAP.md`); other implementations may pick differently and still conform.
+
+## Properties
+
+- **Machine-readable**: all domain shapes are JSON Schemas. Validate from any language that has a JSON Schema validator.
+- **Human-readable**: prose documents for each subsystem, with examples.
+- **Independently versioned**: spec `v1.0.0` can be implemented by CLI `v0.3.2`. See `versioning.md`.
+- **Platform-neutral**: no platform (Claude Code, Obsidian, …) is privileged. Each is expressed as an adapter extension.
+- **Conformance-tested**: every conforming implementation passes the suite under `conformance/`. Pass/fail is binary.
+
+## Repo layout
+
+```
+spec/
+├── README.md                   ← this file
+├── CHANGELOG.md                ← spec history (independent from CLI)
+├── versioning.md               ← evolution policy
+├── architecture.md             ← hexagonal ports & adapters                    (Step 0a phase 3)
+├── cli-contract.md             ← verbs, flags, exit codes, JSON introspection  (Step 0a phase 3)
+├── job-events.md               ← canonical event stream schema                 (Step 0a phase 3)
+├── prompt-preamble.md          ← canonical injection-mitigation preamble      (Step 0a phase 3)
+├── db-schema.md                ← table catalog (kernel-owned)                  (Step 0a phase 3)
+├── plugin-kv-api.md            ← ctx.store contract for storage mode A        (Step 0a phase 3)
+├── dispatch-lifecycle.md       ← queued → running → completed | failed        (Step 0a phase 3)
+├── schemas/                    ← JSON Schemas (Step 0a phase 2)
+│   ├── node.schema.json
+│   ├── link.schema.json
+│   ├── issue.schema.json
+│   ├── scan-result.schema.json
+│   ├── execution-record.schema.json
+│   ├── project-config.schema.json
+│   ├── plugins-registry.schema.json
+│   ├── job.schema.json
+│   ├── report-base.schema.json
+│   ├── frontmatter/
+│   │   ├── base.schema.json
+│   │   ├── skill.schema.json
+│   │   ├── agent.schema.json
+│   │   ├── command.schema.json
+│   │   ├── hook.schema.json
+│   │   └── note.schema.json
+│   └── summaries/
+│       ├── skill.schema.json
+│       ├── agent.schema.json
+│       ├── command.schema.json
+│       ├── hook.schema.json
+│       └── note.schema.json
+├── interfaces/
+│   └── security-scanner.md     ← contract for third-party security plugins
+└── conformance/
+    ├── fixtures/               ← controlled MD corpora
+    └── cases/                  ← declarative test cases (JSON)
+```
+
+## How to read this spec
+
+- **Building a tool or plugin that consumes skill-map output?** Start with `schemas/scan-result.schema.json` and `schemas/node.schema.json`.
+- **Building a custom detector, rule, or renderer?** Read `architecture.md`, then the relevant schema.
+- **Building an alternative CLI implementation?** Read `cli-contract.md` and run `conformance/`.
+- **Integrating a new platform (adapter)?** Read `architecture.md` §adapters, then the Claude adapter source in `../src/extensions/adapters/claude/` as a worked example.
+- **Shipping a job-running runner?** Read `job-events.md`, `dispatch-lifecycle.md`, `prompt-preamble.md`.
+
+## Relationship to the reference implementation
+
+The reference implementation (`../src/`) is one conforming consumer of this spec. It ships the CLI binary `sm`, a built-in SQLite storage adapter, and a bundle of default extensions.
+
+The reference impl has no privileged access to the spec. Breaking changes to the spec must follow `versioning.md` regardless of reference-impl convenience.
+
+When spec and reference impl disagree, the spec wins. File an issue; one of them is wrong.
+
+## Distribution
+
+- This directory is published to npm as `@skill-map/spec`.
+- Schemas are also published to JSON Schema Store when the domain is live.
+- Canonical URLs (stable across versions) land with Step 13.
+
+## License
+
+MIT. See `../LICENSE`.

package/architecture.md

@@ -0,0 +1,218 @@
+# Architecture
+
+Normative description of skill-map's internal boundaries: the **kernel**, the **ports** it exposes, the **adapters** that drive and serve it, and the six **extension kinds** that live outside the kernel.
+
+Any conforming implementation — reference or third-party — MUST respect these boundaries. The conformance suite under `conformance/` enforces them.
+
+---
+
+## Layering
+
+```
+                    Driving adapters (primary)
+                          │
+   ┌─────────┐       ┌─────────┐       ┌──────┐
+   │   CLI   │       │ Server  │       │Skill │
+   └────┬────┘       └────┬────┘       └───┬──┘
+        │                 │                │
+        └─────────────────┼────────────────┘
+                          ▼
+                   ┌──────────────┐
+                   │    Kernel    │  ← domain core
+                   │              │
+                   │  Registry    │
+                   │  Orchestrator│
+                   │  Use cases   │
+                   └──┬───┬───┬───┘
+                      │   │   │
+        ┌─────────────┘   │   └──────────────┐
+        ▼                 ▼                  ▼
+   ┌────────┐        ┌─────────┐        ┌─────────┐
+   │ Storage│        │   FS    │        │ Plugins │
+   └────────┘        └─────────┘        └─────────┘
+                Driven adapters (secondary)
+```
+
+- **Driving adapters** call into the kernel. The spec defines three: `CLI`, `Server`, `Skill`. A fourth driving adapter MAY be built by third parties (IDE extension, VSCode command palette, TUI) without spec changes.
+- **Driven adapters** implement ports the kernel declares. An implementation MUST ship adapters for every port — no port may be left unimplemented at runtime.
+- **Kernel** is domain-pure. It never imports a filesystem API, a database driver, or a subprocess spawner directly. All IO crosses a port.
+
+---
+
+## Ports
+
+An implementation MUST expose these five ports. Each is an interface (TypeScript, in the reference impl; equivalent in other languages).
+
+### `StoragePort`
+
+Persistence for all kernel tables in all three zones (`scan_*`, `state_*`, `config_*`). Exposes typed repositories, not raw SQL. Implementations MAY back this with SQLite, Postgres, in-memory, or anything else, as long as:
+
+- Transactional semantics for atomic claim (see `dispatch-lifecycle.md`).
+- Migration application with `PRAGMA user_version`-equivalent tracking.
+- Read isolation sufficient to avoid phantom reads across a single scan write.
+
+The reference impl backs this with `node:sqlite` + Kysely + `CamelCasePlugin`.
+
+### `FilesystemPort`
+
+Walks roots, reads node files, reports mtime/size. Abstracts away platform-specific path handling and test fixtures.
+
+Operations: `walk(roots, ignore)`, `readNode(path)`, `stat(path)`, `writeJobFile(path, content)`, `ensureDir(path)`.
+
+The reference impl uses real `node:fs` in production and an in-memory fixture in tests.
+
+### `PluginLoaderPort`
+
+Discovers plugin directories, reads `plugin.json`, checks `specCompat`, dynamically imports extension files, returns loaded extension descriptors ready to register.
+
+Operations: `discover(scopes)`, `load(pluginPath)`, `validateManifest(json)`.
+
+### `RunnerPort`
+
+Executes an action against a job file. Returns a report reference (or an error) plus runner-side metrics (duration, tokens, exit code).
+
+Operations: `run(jobFilePath, options)` → `{ reportPath, tokensIn, tokensOut, durationMs, exitCode } | Error`.
+
+Two reference implementations:
+- `ClaudeCliRunner` — subprocess `claude -p < jobfile`.
+- `MockRunner` — deterministic fake for tests.
+
+The Skill runner does NOT implement this port: it runs inside an agent session and closes jobs via `sm record` callback. See `dispatch-lifecycle.md`.
+
+### `ProgressEmitterPort`
+
+Emits progress events during long operations (scans, job runs). Consumers: CLI pretty printer, `--json` ndjson, Server's WebSocket broadcaster.
+
+Operations: `emit(event)`, `subscribe(listener)`. Events are defined in `job-events.md`.
+
+---
+
+## Kernel
+
+The kernel is the only component that:
+- Maintains the extension registry.
+- Runs the scan orchestrator.
+- Validates scan output against `scan-result.schema.json`.
+- Applies the canonical prompt preamble to job files (`prompt-preamble.md`).
+- Enforces duplicate-prevention and atomic-claim invariants for jobs.
+- Persists execution records.
+
+The kernel is the only component that MAY:
+- Import schemas.
+- Call `validate(data, schema)`.
+- Dispatch extension hooks.
+
+The kernel MUST NOT:
+- Know which adapter produced an event.
+- Know which platform a node belongs to (that is the `Adapter` extension's job).
+- Contain any platform-specific branching (e.g., `if (platform === 'claude')`).
+
+### Boot invariant
+
+**With all extensions removed, the kernel MUST boot and return an empty graph.** This is enforced by the conformance suite case `kernel-empty-boot`.
+
+No extension is privileged. The Claude adapter ships bundled with the reference impl but is removable, same as any third-party plugin.
+
+---
+
+## Extension kinds
+
+Six kinds, all first-class, all loaded through the same registry. Each kind has a JSON Schema describing its manifest shape (`spec/schemas/extensions/<kind>.schema.json`, landing with step 3 of the spec bootstrap).
+
+| Kind | Role | Input | Output |
+|---|---|---|---|
+| **Adapter** | Recognizes a platform. Decides which files are nodes and what kind they are. | Filesystem walk results, candidate path. | `{ kind, adapter } \| null`. |
+| **Detector** | Extracts signals from a node body. | Parsed node (frontmatter + body). | `Link[]`. |
+| **Rule** | Evaluates the graph. | Full graph (nodes + links). | `Issue[]`. |
+| **Action** | Operates on one or more nodes. Two modes: `local` (code) or `invocation-template` (LLM prompt). | Node(s), optional args. | Local: report JSON. Template: rendered prompt that a runner executes. |
+| **Audit** | Deterministic workflow that composes rules and actions. Produces a structured report. | Graph + optional scope filter. | Audit report (hardcoded shape, kind-specific). |
+| **Renderer** | Serializes the graph. | Graph + optional filter. | String (ASCII / Mermaid / DOT / JSON / user-defined). |
+
+### Contract rules
+
+1. An extension declares its kind in its module export and its manifest. Kind mismatch → load-error.
+2. An extension MAY declare `preconditions` — predicates that must be satisfied for the extension to be offered (e.g., `action.requires: ["kind=skill"]`).
+3. An extension MUST NOT retain state across invocations. Scoped persistence goes through `ctx.store` (storage mode `kv`) or the plugin's dedicated tables (`dedicated`).
+4. An extension MUST NOT import another extension directly. Cross-extension communication goes through the kernel's registry lookup.
+5. An extension MUST provide a sibling test file. The reference impl treats a missing test as a contract-check failure; other impls MAY relax this to a warning.
+
+### Locality
+
+- **Drop-in**: extensions live inside plugins, discovered at boot from `.skill-map/plugins/<id>/` and `~/.skill-map/plugins/<id>/`.
+- **Built-in**: the reference impl bundles a default extension set (one adapter, three detectors, three rules, one audit, one renderer). These are loaded from `src/extensions/` and are indistinguishable from plugin-supplied extensions from the kernel's point of view.
+
+---
+
+## Dependency rules
+
+The following imports are NORMATIVELY FORBIDDEN:
+
+- `kernel/*` → any `adapters/*` module.
+- `kernel/*` → `node:fs`, `node:sqlite`, `node:child_process`, or equivalent IO libraries.
+- Any extension → another extension.
+- Any extension → `adapters/*`.
+- `cli/*` or `server/*` → `adapters/*`. Driving adapters wire adapters into the kernel at startup; they do not import adapters directly in their command code.
+
+The following imports are permitted:
+
+- `kernel/*` → `spec/schemas/*` (type imports, JSON Schema files at runtime).
+- `adapters/*` → `kernel/*` (ports are declared in the kernel and implemented in adapters).
+- `cli/*`, `server/*`, extensions → `kernel/*` (consuming kernel APIs).
+
+---
+
+## Testability consequences
+
+Because the kernel depends only on ports:
+
+- Unit tests inject `InMemoryStorageAdapter`, `FixtureFilesystemAdapter`, `MockRunner`.
+- Integration tests wire real adapters.
+- Conformance tests exercise the kernel directly, bypassing the CLI entirely.
+- A driving adapter (CLI/Server/Skill) can be tested by asserting the kernel calls it makes, with all ports mocked.
+
+This collapses cleanly onto the test pyramid mandated by `CLAUDE.md`: contract tests exercise kind schemas; unit tests exercise the kernel in isolation; integration tests exercise adapter pairs; CLI tests spawn the binary.
+
+---
+
+## Package layout (reference impl)
+
+The spec does not prescribe package layout. The reference impl uses a single npm package with multiple `exports` entries:
+
+```
+src/
+├── kernel/              Registry, Orchestrator, domain types, use cases, port interfaces
+├── cli/                 Clipanion commands, thin wrappers over kernel
+├── server/              Hono + WebSocket, thin wrapper over kernel
+├── testkit/             Kernel mocks for plugin authors
+└── adapters/
+    ├── sqlite/          node:sqlite + Kysely + CamelCasePlugin (StoragePort)
+    ├── filesystem/      real fs (FilesystemPort)
+    ├── plugin-loader/   drop-in discovery (PluginLoaderPort)
+    └── runner/          claude -p subprocess (RunnerPort)
+```
+
+Alternative implementations MAY use workspaces, separate packages, or a compiled monolith. The spec has no opinion.
+
+---
+
+## Driving-adapter peer rule
+
+The CLI, Server, and Skill driving adapters are **peers**. None depends on another.
+
+- The Server MUST NOT call the CLI (no `child_process.spawn('sm', ...)`).
+- The Skill runner MUST NOT depend on the Server (it can be used offline).
+- The CLI MUST NOT embed HTTP logic.
+
+All three consume the same kernel API. Any use case a driving adapter needs MUST be available as a kernel function — if it isn't, the gap is a kernel bug, not a driving-adapter workaround.
+
+This is what makes "CLI-first" a coherent rule: every CLI verb is a kernel function call. The UI does not reimplement business logic; it calls the same functions.
+
+---
+
+## Stability
+
+The **port list** is stable as of spec v1.0.0. Adding a sixth port is a major bump.
+
+The **extension kind list** (6 kinds) is stable as of spec v1.0.0. Adding a seventh kind is a major bump.
+
+The **dependency rules** above are stable as of spec v1.0.0. Relaxing any is a major bump; tightening (forbidding an allowed import) is a minor bump.