@skill-map/spec 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,109 @@
 # Spec changelog
 
+## 0.6.0
+
+### Minor Changes
+
+- 9a89124: Step 5.1 — Persist scan-result metadata in a new `scan_meta` table so
+  `loadScanResult` returns real values for `scope` / `roots` / `scannedAt` /
+  `scannedBy` / `adapters` / `stats.filesWalked` / `stats.filesSkipped` /
+  `stats.durationMs` instead of the synthetic envelope shipped at Step 4.7.
+
+  **Spec change (additive, minor)**:
+
+  - New `scan_meta` table in zone `scan_*`, single-row (CHECK `id = 1`).
+    Columns: `scope`, `roots_json`, `scanned_at`, `scanned_by_name`,
+    `scanned_by_version`, `scanned_by_spec_version`, `adapters_json`,
+    `stats_files_walked`, `stats_files_skipped`, `stats_duration_ms`.
+    `nodesCount` / `linksCount` / `issuesCount` are not stored — they are
+    derived from `COUNT(*)` of the sibling tables.
+  - Replaced atomically with the rest of `scan_*` on every `sm scan`.
+
+  **Runtime change**:
+
+  - New kernel migration `002_scan_meta.sql`.
+  - `IScanMetaTable` added to `src/kernel/adapters/sqlite/schema.ts` and
+    bound in `IDatabase`.
+  - `persistScanResult` writes the row (and deletes prior rows in the same
+    transaction).
+  - `loadScanResult` reads from `scan_meta` when the row exists; degrades
+    to the previous synthetic envelope when it does not (DB freshly
+    migrated, never scanned, or pre-5.1 snapshot).
+  - The Step 4.7 follow-up notes in `scan-load.ts` documenting the
+    synthetic envelope are simplified to describe both branches.
+
+  Test count: 151 → 154 (+3 covering meta round-trip, replace-all
+  single-row invariant, and synthetic-fallback on empty DB).
+
+- 9a89124: Step 5.7 — Conformance coverage for the rename heuristic.
+
+  **Spec change (additive, minor)**:
+
+  - `spec/schemas/conformance-case.schema.json` gains
+    `setup.priorScans: Array<{ fixture, flags? }>` — an ordered list of
+    staging scans the runner executes BEFORE the main `invoke`. Each
+    step replaces every non-`.skill-map/` directory in the scope with
+    the named fixture and runs `sm scan` (with optional flags). The DB
+    persists across steps because `.skill-map/` is preserved between
+    swaps. After the last step, the runner copies the top-level
+    `fixture` and runs the case's `invoke`.
+
+    Required to express scenarios that need a prior snapshot (rename
+    heuristic, future incremental cases). The schema is purely
+    additive — every existing case keeps passing without modification.
+
+  - Two new conformance cases under `spec/conformance/cases/`:
+
+    - **`rename-high`** — moving a single file with identical body
+      triggers a high-confidence auto-rename. Asserts:
+      `stats.nodesCount === 1`, `stats.issuesCount === 0`,
+      `nodes[0].path === skills/bar.md`. Verifies the spec invariant
+      that high-confidence renames emit NO issue.
+    - **`orphan-detection`** — deleting a file with no replacement
+      emits exactly one `orphan` issue (severity `info`). Asserts the
+      `ruleId` and `severity` directly.
+
+  - Four new fixture directories under `spec/conformance/fixtures/`:
+    `rename-high-before/`, `rename-high-after/`,
+    `orphan-before/`, `orphan-after/`.
+
+  - `spec/conformance/coverage.md`: row I (Rename heuristic) flips
+    from `🔴 missing` to `🟢 covered`. Notes the medium / ambiguous
+    branches stay covered by `src/test/rename-heuristic.test.ts` for
+    now (assertion vocabulary in the schema is not rich enough to
+    express "the issues array contains an item with ruleId X and
+    data.confidence === 'medium'" — when the conformance schema gains
+    array-filter assertions, those branches can land here too).
+
+  **Runtime change**:
+
+  - `src/conformance/index.ts` runner: implements `setup.priorScans`.
+    Helper `replaceFixture(scope, specRoot, fixture)` clears every
+    top-level entry in the scope except `.skill-map/`, then copies the
+    named fixture on top. Used by both staging steps and the main
+    `fixture` phase.
+  - `src/test/conformance.test.ts`: includes the two new cases in the
+    Step-0b subset. Total conformance cases passing in CI: 1 → 3.
+
+  **`spec/index.json`** regenerated (50 → 57 files). `npm run spec:check`
+  green.
+
+  Test count: 201 → 203 (+2 conformance cases). The Step 5 totals close
+  at: 151 → 203 (+52 across 7 sub-steps).
+
+### Patch Changes
+
+- dacd4d9: Move the auto-generated CLI reference from `docs/cli-reference.md` to
+  `context/cli-reference.md`. Spec change is editorial: `cli-contract.md`
+  references the file path in three spots (`--format md` description, the
+  NORMATIVE introspection section, and the "Related" link list); all three
+  updated to the new location. No schema or behavioural change.
+
+  Reference impl: `scripts/build-cli-reference.mjs` writes to the new path,
+  the `cli:reference` / `cli:check` npm scripts point there, and `sm help`
+  output (which embeds the path in the `--format md` flag description) is
+  regenerated. The `docs/` folder is gone.
+
 ## 0.5.1
 
 ### Patch Changes

package/cli-contract.md

@@ -121,7 +121,7 @@ Exit: 0 if all green, 1 if warnings, 2 if any `error`-level problem.
 Self-describing introspection.
 
 - `human` (default): pretty terminal output.
-- `md`: canonical markdown for documentation sites. Implementations MUST NOT hand-maintain equivalent markdown; `docs/cli-reference.md` (in the reference impl) is regenerated from this output in CI.
+- `md`: canonical markdown for documentation sites. Implementations MUST NOT hand-maintain equivalent markdown; `context/cli-reference.md` (in the reference impl) is regenerated from this output in CI.
 - `json`: structured surface dump. Shape:
 
 ```json
@@ -314,7 +314,7 @@ Destructive verbs (`reset --state`, `reset --hard`, `restore`) require interacti
 ### Introspection
 
 - `sm help --format json` — structured CLI surface dump.
-- `sm help --format md` — canonical markdown, CI-enforced for the reference impl's `docs/cli-reference.md`.
+- `sm help --format md` — canonical markdown, CI-enforced for the reference impl's `context/cli-reference.md`.
 
 These two formats are NORMATIVE: any change to verbs, flags, or exit codes MUST reflect in `--format json` output immediately. Third-party consumers rely on this.
 
@@ -390,7 +390,7 @@ The `done in …` stderr line, its format grammar, and the `elapsedMs` field con
 - [`job-lifecycle.md`](./job-lifecycle.md) — state machine behind `sm job` verbs.
 - [`job-events.md`](./job-events.md) — event stream emitted via `--json` and `--stream-output`.
 - [`db-schema.md`](./db-schema.md) — tables behind `sm db` verbs.
-- [`../docs/cli-reference.md`](../docs/cli-reference.md) — auto-generated reference from `sm help --format md`.
+- [`../context/cli-reference.md`](../context/cli-reference.md) — auto-generated reference from `sm help --format md`.
 - [`conformance/`](./conformance/README.md) — test suite exercising CLI behavior.
 
 ---

package/conformance/cases/orphan-detection.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://skill-map.dev/spec/v0/conformance-case.schema.json",
+  "id": "orphan-detection",
+  "description": "Deleting a file with no replacement triggers the orphan branch of the rename heuristic: exactly one issue with ruleId `orphan` is emitted, severity `info`, naming the dead path. The remaining survivor node is reported normally.",
+  "fixture": "orphan-after",
+  "setup": {
+    "priorScans": [
+      { "fixture": "orphan-before" }
+    ]
+  },
+  "invoke": {
+    "verb": "scan",
+    "flags": ["--changed", "--json"]
+  },
+  "assertions": [
+    { "type": "exit-code", "value": 0 },
+    { "type": "json-path", "path": "$.stats.nodesCount", "equals": 1 },
+    { "type": "json-path", "path": "$.stats.issuesCount", "equals": 1 },
+    { "type": "json-path", "path": "$.issues[0].ruleId", "equals": "orphan" },
+    { "type": "json-path", "path": "$.issues[0].severity", "equals": "info" }
+  ]
+}

package/conformance/cases/rename-high.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://skill-map.dev/spec/v0/conformance-case.schema.json",
+  "id": "rename-high",
+  "description": "Moving a single file with identical body across the rename triggers a high-confidence auto-rename: NO issue is emitted (per spec/db-schema.md §Rename detection), the new path is the only node in the result, and the rename heuristic operates silently.",
+  "fixture": "rename-high-after",
+  "setup": {
+    "priorScans": [
+      { "fixture": "rename-high-before" }
+    ]
+  },
+  "invoke": {
+    "verb": "scan",
+    "flags": ["--changed", "--json"]
+  },
+  "assertions": [
+    { "type": "exit-code", "value": 0 },
+    { "type": "json-path", "path": "$.stats.nodesCount", "equals": 1 },
+    { "type": "json-path", "path": "$.stats.issuesCount", "equals": 0 },
+    { "type": "json-path", "path": "$.nodes[0].path", "equals": "skills/bar.md" }
+  ]
+}

package/conformance/coverage.md

@@ -54,7 +54,7 @@ These have their own conformance cases even though they are not JSON Schemas.
 | F | Nonce mismatch | — | 🔴 missing | Blocked by Step 10. `sm record` with wrong nonce → exit 4. |
 | G | Reap | — | 🔴 missing | Blocked by Step 10. Set TTL to 1s; claim; wait; next `sm job run` reaps with reason `abandoned`. |
 | H | `run.*` event envelope for Skill agent | — | 🔴 missing | Blocked by Step 10. Skill-agent flow emits synthetic `r-ext-*` run envelope around one job. |
-| I | Rename heuristic | — | 🔴 missing | Blocked by Step 5. Move a file; same-`body_hash` → high-confidence auto-rename; `state_*` FK rows migrated; no issue emitted. |
+| I | Rename heuristic | `rename-high`, `orphan-detection` | 🟢 covered | High-confidence rename emits no issue and the new path is the sole node. Orphan branch emits exactly one `orphan` issue (severity `info`) when a deleted node has no replacement. Medium / ambiguous branches are exercised by `src/test/rename-heuristic.test.ts` until the conformance schema grows richer assertions. |
 | J | Plugin DDL rejection | — | 🔴 missing | Blocked by Step 9. Plugin migration referencing `state_jobs` → disabled with `invalid-manifest`. |
 | K | Plugin prefix injection | — | 🔴 missing | Blocked by Step 9. Plugin declares `CREATE TABLE foo` → kernel applies as `plugin_<id>_foo`. |
 | L | Elapsed-time reporting | — | 🔴 missing | Blocked by Step 4 (first real verb work). Run any in-scope verb; stderr last line MUST match `/^done in (\d+ms\|\d+\.\d+s\|\d+m \d+s)$/`. In-scope verb with `--json` returning an object MUST carry `elapsedMs`. Exempt verb (`sm version`) MUST NOT emit the line. |

package/conformance/fixtures/orphan-after/skills/keep.md

@@ -0,0 +1,13 @@
+---
+name: orphan-keep
+description: Fixture node that survives across before/after, so the after-state still has at least one node.
+metadata:
+  version: 1.0.0
+  stability: stable
+  author: conformance
+---
+
+# Survivor
+
+Keeps the after-state graph non-empty so we can assert that the orphan
+issue is the only one emitted.

package/conformance/fixtures/orphan-before/skills/keep.md

@@ -0,0 +1,13 @@
+---
+name: orphan-keep
+description: Fixture node that survives across before/after, so the after-state still has at least one node.
+metadata:
+  version: 1.0.0
+  stability: stable
+  author: conformance
+---
+
+# Survivor
+
+Keeps the after-state graph non-empty so we can assert that the orphan
+issue is the only one emitted.

package/conformance/fixtures/orphan-before/skills/lonely.md

@@ -0,0 +1,13 @@
+---
+name: orphan-lonely
+description: Fixture node that gets deleted in the after-state to trigger the orphan path.
+metadata:
+  version: 1.0.0
+  stability: stable
+  author: conformance
+---
+
+# Orphan lonely body
+
+This file disappears in `orphan-after`. With no replacement matching
+its hashes, the rename heuristic emits an `orphan` issue.

package/conformance/fixtures/rename-high-after/skills/bar.md

@@ -0,0 +1,14 @@
+---
+name: rename-high-foo
+description: Fixture node for the high-confidence rename conformance case.
+metadata:
+  version: 1.0.0
+  stability: stable
+  author: conformance
+---
+
+# Rename high body
+
+Body content kept identical between the before and after fixtures so
+the body hash matches across the rename. Move it to `bar.md` to trigger
+a high-confidence auto-rename.

package/conformance/fixtures/rename-high-before/skills/foo.md

@@ -0,0 +1,14 @@
+---
+name: rename-high-foo
+description: Fixture node for the high-confidence rename conformance case.
+metadata:
+  version: 1.0.0
+  stability: stable
+  author: conformance
+---
+
+# Rename high body
+
+Body content kept identical between the before and after fixtures so
+the body hash matches across the rename. Move it to `bar.md` to trigger
+a high-confidence auto-rename.

package/db-schema.md

@@ -134,6 +134,28 @@ One row per rule-emitted issue, matching [`schemas/issue.schema.json`](./schemas
 
 Indexes: `ix_scan_issues_rule_id`, `ix_scan_issues_severity`.
 
+### `scan_meta`
+
+Single-row table holding the metadata of the last persisted scan. Lets `loadScanResult` return the real `scope` / `roots` / `scannedAt` / `scannedBy` / `adapters` / `stats.filesWalked|filesSkipped|durationMs` instead of synthesising them. Replaced atomically with the rest of the `scan_*` zone on every `sm scan`.
+
+`nodesCount` / `linksCount` / `issuesCount` are not stored here — they derive from `COUNT(*)` of the sibling tables.
+
+| Column | Type | Constraint |
+|---|---|---|
+| `id` | INTEGER | PRIMARY KEY, CHECK `id = 1` |
+| `scope` | TEXT | NOT NULL, CHECK in (`project`, `global`) |
+| `roots_json` | TEXT | NOT NULL | JSON array of strings (filesystem roots walked). |
+| `scanned_at` | INTEGER | NOT NULL | Unix milliseconds. |
+| `scanned_by_name` | TEXT | NOT NULL |
+| `scanned_by_version` | TEXT | NOT NULL |
+| `scanned_by_spec_version` | TEXT | NOT NULL |
+| `adapters_json` | TEXT | NOT NULL | JSON array of adapter ids. |
+| `stats_files_walked` | INTEGER | NOT NULL |
+| `stats_files_skipped` | INTEGER | NOT NULL |
+| `stats_duration_ms` | INTEGER | NOT NULL |
+
+No indexes (single row).
+
 ---
 
 ## Table catalog: zone `state_`

package/index.json

@@ -190,31 +190,38 @@
       }
     ]
   },
-  "specPackageVersion": "0.5.1",
+  "specPackageVersion": "0.6.0",
   "integrity": {
     "algorithm": "sha256",
     "files": {
-      "CHANGELOG.md": "b810067bdba655d066242db3159a157880250257c6cff03e96acc614758b8d1d",
+      "CHANGELOG.md": "e74921b61ca835c4ebc8f2a4814d2c9513a59ce47c8c719b4d17865b39d93cba",
       "README.md": "8bd57e02d9a9d3f0a4efd18c0f0bd1f4bbe13eb206add0317659e48eab435e7e",
       "architecture.md": "99f9d6a1a90e6c96d3c8a6f36c2650da4a1af0a1bc21173ea8eb2c492008539a",
-      "cli-contract.md": "4f01df640f39eacbb2192d543288e670de9ce2b89bf3931bc09f8488eb3baaea",
+      "cli-contract.md": "bab14bb72ddd8a57e00808f7f12741c63a33da99055b278e4407ab9b4bb7e2c1",
       "conformance/README.md": "79c5e63f18a368951dc9f3e31e9bf9574de3f8b97150b2d75365d4febd8eb6dc",
       "conformance/cases/basic-scan.json": "24623da0cad8c8c54b3ff9b09820ea1276fe8b8f0fc680bf6e8abeb4edb8e424",
       "conformance/cases/kernel-empty-boot.json": "175524674b14d993d29f10080d7697074b3a2eee25b359ff903344d73c6acc98",
-      "conformance/coverage.md": "db9518f5a560b3df01093107de5c09ff38d478ae07c0476eea92644677fb1d83",
+      "conformance/cases/orphan-detection.json": "7fea6e866d775d09cadb70ccd764f6c8317ca61316c6d187a97cb2466db4e19e",
+      "conformance/cases/rename-high.json": "f23513893e25fc4259db06a497906137de981da775d8ab2ef262554d54af5f27",
+      "conformance/coverage.md": "a67fb38c69765bb3cafb78c75e211c530ab00a88d8ccf0254335d3b6d4f69b8d",
       "conformance/fixtures/minimal-claude/agents/reviewer.md": "d0dd681ba63838301e480116aa09825329f01832b0116de5c5476fdd8a5dcf54",
       "conformance/fixtures/minimal-claude/commands/status.md": "3f36e053fd1c059ffd902f84a55be8a458c26072f97cb37dd7e97314ae2a9bf5",
       "conformance/fixtures/minimal-claude/hooks/pre-commit.md": "ec9cec8ac4ce34d40ec055ffd90e8f06ea3e5764d6ec3ee84e0d97de71b930c7",
       "conformance/fixtures/minimal-claude/notes/architecture.md": "5a7e6fdbb1556733dacebad63758057dc1e19090b5a983292c0c65e90b98bcf1",
       "conformance/fixtures/minimal-claude/skills/hello.md": "8598074020430f294ff1eac39876302448f004b6c48446d453092159319bcbee",
+      "conformance/fixtures/orphan-after/skills/keep.md": "a6fdc33104cb2e8092f386a427784685eee1c8d7cb8fddb934cf65984143c7fd",
+      "conformance/fixtures/orphan-before/skills/keep.md": "a6fdc33104cb2e8092f386a427784685eee1c8d7cb8fddb934cf65984143c7fd",
+      "conformance/fixtures/orphan-before/skills/lonely.md": "4ba2bb336fa46644d2b0dfef4c3b97879ecbf693b825a5348f032d1af049d80a",
       "conformance/fixtures/preamble-v1.txt": "1e0aeef224b64477bdc13a949c3ad402e68249caf499ecdba1302371677c068b",
-      "db-schema.md": "ce4f9ddf84fa2aad746b44d6d9142b29b23c339e4915f97928489e035100fa55",
+      "conformance/fixtures/rename-high-after/skills/bar.md": "16f7678829c7702f8ebaeef920a891756da198466a1884badd8d8b4a7d1bab6a",
+      "conformance/fixtures/rename-high-before/skills/foo.md": "16f7678829c7702f8ebaeef920a891756da198466a1884badd8d8b4a7d1bab6a",
+      "db-schema.md": "e9b436b143e2e56985c69498c7d48527bde0baa441be586e2740a4051b366c2d",
       "interfaces/security-scanner.md": "81dc3dc2c439a75f4603b6d52e714f44ac564032c8aa424385ebbf4502adae3e",
       "job-events.md": "08796b7fbeb55e5b03cf3bc394224e70a23438a4d15a46ad1d70121c2c68b967",
       "job-lifecycle.md": "1fe88b1a2ed204e41bb41ac172fbb3e912dccd0dd8a1f8ea8e21a681b336d6ee",
       "plugin-kv-api.md": "04b2178f46fb88adeae9240df9c9e1761b660396072001dac32cd402e11a2d7d",
       "prompt-preamble.md": "23a8eff0477fbbc46192a27781bc781bda4202bb9c669b7a7a002b0d668146b0",
-      "schemas/conformance-case.schema.json": "2740874e00269de6d8121300339401d0283197b6d97dcd77538ec5d108b14de2",
+      "schemas/conformance-case.schema.json": "d69c501bbca079da0ca87685eb4cbdbc2e405334469fc937929ca9134e01a2b3",
       "schemas/execution-record.schema.json": "ec0f3acf1d0ce099c059d73eb434936bfd1bcf12023693bd572efb2a7352faa6",
       "schemas/extensions/action.schema.json": "c7520d3cefecf75d27d3e04473821fd6e5dc5a7924eede147f74275ba6caccad",
       "schemas/extensions/adapter.schema.json": "429b865e738664bb437ac62690a2d7282ce992339fbb300417c73625f5cdb7c8",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skill-map/spec",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "JSON Schemas, prose contracts, and conformance suite for the skill-map specification.",
   "license": "MIT",
   "type": "module",

package/schemas/conformance-case.schema.json

@@ -28,12 +28,32 @@
     },
     "setup": {
       "type": "object",
-      "description": "Pre-invocation toggles. All default to `false`.",
+      "description": "Pre-invocation toggles and ordered staging steps. All toggles default to `false`. `priorScans`, when present, run BEFORE the main `invoke` so a case can establish a prior snapshot the heuristic-driven verbs (e.g. `sm scan` rename detection) can react to.",
       "additionalProperties": false,
       "properties": {
         "disableAllAdapters": { "type": "boolean" },
         "disableAllDetectors": { "type": "boolean" },
-        "disableAllRules": { "type": "boolean" }
+        "disableAllRules": { "type": "boolean" },
+        "priorScans": {
+          "type": "array",
+          "description": "Ordered staging scans, each running before the next. For step N, the runner first replaces the scope's adapter content with `priorScans[N].fixture`, then invokes `sm scan` with the supplied flags. After the last step, the runner copies the top-level `fixture` (overwriting again) and runs the main `invoke`. The DB persists across all steps because `.skill-map/` is preserved between fixture swaps.",
+          "items": {
+            "type": "object",
+            "required": ["fixture"],
+            "additionalProperties": false,
+            "properties": {
+              "fixture": {
+                "type": "string",
+                "description": "Folder under `conformance/fixtures/` to copy into the scope, replacing every non-`.skill-map/` directory."
+              },
+              "flags": {
+                "type": "array",
+                "description": "Flags passed to `sm scan`. Default: empty (full scan).",
+                "items": { "type": "string" }
+              }
+            }
+          }
+        }
       }
     },
     "invoke": {