@skill-map/spec 0.1.0

package/schemas/frontmatter/skill.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/frontmatter/skill.schema.json",
+  "title": "FrontmatterSkill",
+  "description": "Frontmatter shape for nodes classified as `skill`. Extends `base.schema.json`. Kind-specific fields: `inputs`, `outputs`. Stability: experimental — the parameter shape may tighten once summarizer needs emerge.",
+  "allOf": [
+    { "$ref": "base.schema.json" }
+  ],
+  "type": "object",
+  "additionalProperties": true,
+  "properties": {
+    "inputs": {
+      "type": "array",
+      "description": "Declared inputs for this skill. Optional structured. Stability: experimental.",
+      "items": { "$ref": "#/$defs/Parameter" }
+    },
+    "outputs": {
+      "type": "array",
+      "description": "Declared outputs. Optional structured. Stability: experimental.",
+      "items": { "$ref": "#/$defs/Parameter" }
+    }
+  },
+  "$defs": {
+    "Parameter": {
+      "type": "object",
+      "required": ["name"],
+      "additionalProperties": true,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "type": { "type": "string", "description": "Free-form type hint (e.g. `string`, `integer`, `path`, `glob`)." },
+        "description": { "type": "string" },
+        "required": { "type": "boolean", "default": false },
+        "default": { "description": "Any JSON value, or a templated string." }
+      }
+    }
+  }
+}

package/schemas/issue.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/issue.schema.json",
+  "title": "Issue",
+  "description": "Deterministic finding emitted by a rule when evaluating the graph. Not to be confused with `Finding`, which is probabilistic (LLM-produced).",
+  "type": "object",
+  "required": ["ruleId", "severity", "nodeIds", "message"],
+  "additionalProperties": false,
+  "properties": {
+    "ruleId": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+      "description": "Kebab-case identifier of the rule that emitted this issue (e.g. `trigger-collision`, `broken-ref`, `superseded`)."
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["error", "warn", "info"],
+      "description": "Severity level. `info` is emitted by `--strict` mode for recommendations."
+    },
+    "nodeIds": {
+      "type": "array",
+      "description": "`node.path` values involved in this issue. Most rules emit 1 or 2; trigger-collision may emit N. Field name uses `id` generically to remain stable across future identifier changes.",
+      "minItems": 1,
+      "items": { "type": "string" }
+    },
+    "linkIndices": {
+      "type": "array",
+      "description": "Optional indices into the sibling `links[]` array (in the same scan result) that the issue refers to.",
+      "items": { "type": "integer", "minimum": 0 }
+    },
+    "message": {
+      "type": "string",
+      "description": "Short one-line description, human-readable."
+    },
+    "detail": {
+      "type": ["string", "null"],
+      "description": "Longer explanation, markdown-friendly. Optional."
+    },
+    "fix": {
+      "type": ["object", "null"],
+      "description": "Machine-readable fix hint. Stability: experimental — shape may change before v1.",
+      "additionalProperties": false,
+      "properties": {
+        "summary": { "type": "string" },
+        "autofixable": { "type": "boolean" }
+      }
+    },
+    "data": {
+      "type": "object",
+      "description": "Rule-specific structured payload (e.g. the colliding trigger string, the missing target). Free-form.",
+      "additionalProperties": true
+    }
+  }
+}

package/schemas/job.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/job.schema.json",
+  "title": "Job",
+  "description": "Row in `state_jobs`. Non-terminal state until it reaches `completed` or `failed`, at which point an `ExecutionRecord` is also written.",
+  "type": "object",
+  "required": ["id", "actionId", "actionVersion", "nodeId", "contentHash", "nonce", "status", "ttlSeconds", "createdAt"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^d-\\d{8}-\\d{6}-[0-9a-f]{4}$",
+      "description": "Job id: `d-YYYYMMDD-HHMMSS-XXXX`. Human-readable, sortable."
+    },
+    "actionId": {
+      "type": "string"
+    },
+    "actionVersion": {
+      "type": "string",
+      "description": "Semver of the action implementation at submit time. Frozen for this job."
+    },
+    "nodeId": {
+      "type": "string",
+      "description": "Target `node.path`. `--all` submissions fan out into one job per node."
+    },
+    "contentHash": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$",
+      "description": "sha256(actionId + actionVersion + bodyHash + frontmatterHash + promptTemplateHash). Duplicate detection key."
+    },
+    "nonce": {
+      "type": "string",
+      "description": "Unique per-job token. `sm record` requires it to close the job — mismatch rejects with exit code 4."
+    },
+    "priority": {
+      "type": "integer",
+      "description": "Higher = claimed first. Default 0.",
+      "default": 0
+    },
+    "status": {
+      "type": "string",
+      "enum": ["queued", "running", "completed", "failed"],
+      "description": "Lifecycle state. See `dispatch-lifecycle.md` for allowed transitions."
+    },
+    "failureReason": {
+      "type": ["string", "null"],
+      "enum": ["runner-error", "report-invalid", "timeout", "abandoned", "job-file-missing", "user-cancelled", null],
+      "description": "Populated when `status = failed`."
+    },
+    "runner": {
+      "type": ["string", "null"],
+      "enum": ["cli", "skill", "in-process", null]
+    },
+    "ttlSeconds": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Resolved TTL at submit time: max(expectedDurationSeconds × graceMultiplier, minimumTtlSeconds). Frozen."
+    },
+    "filePath": {
+      "type": ["string", "null"],
+      "description": "Relative path to the rendered job file (usually `.skill-map/jobs/<id>.md`). Null before rendering."
+    },
+    "createdAt": { "type": "integer", "description": "Unix ms. Submit time." },
+    "claimedAt": { "type": ["integer", "null"], "description": "Unix ms. Null while queued." },
+    "finishedAt": { "type": ["integer", "null"], "description": "Unix ms. Null while not terminal." },
+    "expiresAt": {
+      "type": ["integer", "null"],
+      "description": "Derived = claimedAt + ttlSeconds × 1000. Used by auto-reap. Null while queued."
+    },
+    "submittedBy": {
+      "type": ["string", "null"],
+      "description": "Free-form: username, CI job id, or `skill:<skill-id>`. Optional provenance."
+    }
+  }
+}

package/schemas/link.schema.json

@@ -0,0 +1,66 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/link.schema.json",
+  "title": "Link",
+  "description": "Directed relation between two nodes, produced by one or more detectors during a scan.",
+  "type": "object",
+  "required": ["source", "target", "kind", "confidence", "sources"],
+  "additionalProperties": false,
+  "properties": {
+    "source": {
+      "type": "string",
+      "description": "`node.path` of the origin."
+    },
+    "target": {
+      "type": "string",
+      "description": "`node.path` of the destination. MAY point to a missing node; rules detect broken refs."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["invokes", "references", "mentions", "supersedes"],
+      "description": "Nature of the relation. `invokes` = execution-level call (e.g. slash command). `references` = explicit link (e.g. wikilink, @-directive). `mentions` = informal textual mention. `supersedes` = replaces another node (from `metadata.supersedes`)."
+    },
+    "confidence": {
+      "type": "string",
+      "enum": ["high", "medium", "low"],
+      "description": "Detector's self-assessed confidence. Rules MAY filter by confidence."
+    },
+    "sources": {
+      "type": "array",
+      "description": "Detector ids that produced this link. At least one. Multiple detectors may converge on the same link; kernel merges them.",
+      "minItems": 1,
+      "items": { "type": "string" }
+    },
+    "trigger": {
+      "type": ["object", "null"],
+      "description": "Trigger-style link metadata (e.g. slash-command keyword, @-directive keyword). Null for links without a textual trigger.",
+      "required": ["originalTrigger", "normalizedTrigger"],
+      "additionalProperties": false,
+      "properties": {
+        "originalTrigger": {
+          "type": "string",
+          "description": "Exact string as it appears in the source body."
+        },
+        "normalizedTrigger": {
+          "type": "string",
+          "description": "NFD → strip diacritics → lowercase → hyphen/underscore → space → collapse whitespace → trim. Used for collision detection and lookup."
+        }
+      }
+    },
+    "location": {
+      "type": ["object", "null"],
+      "description": "Where in the source body the link was found. Null if the detector didn't track location.",
+      "required": ["line"],
+      "additionalProperties": false,
+      "properties": {
+        "line": { "type": "integer", "minimum": 1 },
+        "column": { "type": "integer", "minimum": 1 },
+        "offset": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "raw": {
+      "type": ["string", "null"],
+      "description": "Verbatim matched substring from the source body. Optional, for debugging and UI display."
+    }
+  }
+}

package/schemas/node.schema.json

@@ -0,0 +1,95 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/node.schema.json",
+  "title": "Node",
+  "description": "A single markdown file in the graph (skill, agent, command, hook, note). Identified by its relative path from the scope root.",
+  "type": "object",
+  "required": ["path", "kind", "adapter", "bodyHash", "frontmatterHash", "bytes", "linksOutCount", "linksInCount", "externalRefsCount"],
+  "additionalProperties": false,
+  "properties": {
+    "path": {
+      "type": "string",
+      "description": "Relative path from the scope root. Canonical node identifier in v0. Survives frontmatter edits; breaks on file moves (rare enough). FUTURE: a sibling `id` field (UUID stored in frontmatter) lands with write-back to decouple identity from location; `path` will remain as display metadata at that point. Stability: stable."
+    },
+    "kind": {
+      "type": "string",
+      "enum": ["skill", "agent", "command", "hook", "note"],
+      "description": "Category assigned by the adapter. Stability: stable. New kinds may be added in a minor bump."
+    },
+    "adapter": {
+      "type": "string",
+      "description": "Identifier of the adapter extension that classified this node (e.g. `claude`)."
+    },
+    "title": {
+      "type": ["string", "null"],
+      "description": "Human-readable title. Sourced from frontmatter `name` or falls back to filename. Null if neither is usable."
+    },
+    "description": {
+      "type": ["string", "null"],
+      "description": "Short description from frontmatter `description`. Null if absent."
+    },
+    "stability": {
+      "type": ["string", "null"],
+      "enum": ["experimental", "stable", "deprecated", null],
+      "description": "Denormalized from `metadata.stability` for fast queries."
+    },
+    "version": {
+      "type": ["string", "null"],
+      "description": "Denormalized from `metadata.version` for fast queries. Must be a valid semver if present."
+    },
+    "author": {
+      "type": ["string", "null"],
+      "description": "Denormalized from `metadata.author` for fast queries."
+    },
+    "frontmatter": {
+      "type": "object",
+      "description": "Full parsed frontmatter. See `frontmatter/base.schema.json` and `frontmatter/<kind>.schema.json`.",
+      "additionalProperties": true
+    },
+    "bodyHash": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$",
+      "description": "sha256 of the body content (post-frontmatter), hex-encoded lowercase. Used for rename heuristic (high confidence) and stale detection."
+    },
+    "frontmatterHash": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$",
+      "description": "sha256 of the raw frontmatter block, hex-encoded lowercase. Used for rename heuristic (medium confidence)."
+    },
+    "bytes": {
+      "$ref": "#/$defs/tripleSplit",
+      "description": "Size breakdown in bytes: frontmatter, body, total."
+    },
+    "tokens": {
+      "$ref": "#/$defs/tripleSplit",
+      "description": "Size breakdown in tokens (via `js-tiktoken`): frontmatter, body, total. Optional; MAY be absent if tokenization was disabled."
+    },
+    "linksOutCount": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Outgoing links from this node to other graph nodes."
+    },
+    "linksInCount": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Incoming links from other graph nodes to this one."
+    },
+    "externalRefsCount": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "http/https URLs in the body after normalization and exact-match dedup."
+    }
+  },
+  "$defs": {
+    "tripleSplit": {
+      "type": "object",
+      "required": ["frontmatter", "body", "total"],
+      "additionalProperties": false,
+      "properties": {
+        "frontmatter": { "type": "integer", "minimum": 0 },
+        "body": { "type": "integer", "minimum": 0 },
+        "total": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}

package/schemas/plugins-registry.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/plugins-registry.schema.json",
+  "title": "PluginsRegistry",
+  "description": "Two shapes in one file: (1) the per-plugin manifest that authors ship as `plugin.json` (see `$defs/PluginManifest`); (2) the aggregate registry the implementation produces on disk (e.g. `~/.skill-map/plugins.json`), which lists all discovered plugins with their compat status. Both shapes are normative. camelCase keys throughout.",
+  "type": "object",
+  "oneOf": [
+    { "$ref": "#/$defs/PluginsRegistry" },
+    { "$ref": "#/$defs/PluginManifest" }
+  ],
+  "$defs": {
+    "PluginManifest": {
+      "type": "object",
+      "required": ["id", "version", "specCompat", "extensions"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+          "description": "Kebab-case, globally unique plugin identifier."
+        },
+        "version": {
+          "type": "string",
+          "description": "Plugin semver."
+        },
+        "specCompat": {
+          "type": "string",
+          "description": "Semver range this plugin is compatible with (e.g. `^1.0.0`, `>=0.3.0 <0.4.0`). Checked via `semver.satisfies(specVersion, this)` at load time."
+        },
+        "description": {
+          "type": "string"
+        },
+        "extensions": {
+          "type": "array",
+          "description": "Relative paths to extension files, resolved from the plugin directory.",
+          "minItems": 1,
+          "items": { "type": "string" }
+        },
+        "storage": {
+          "type": "object",
+          "description": "Persistence mode for this plugin. Absent = plugin does not persist state.",
+          "oneOf": [
+            {
+              "required": ["mode"],
+              "additionalProperties": false,
+              "properties": {
+                "mode": { "const": "kv", "description": "Shared `state_plugin_kv` table, scoped by plugin id." }
+              }
+            },
+            {
+              "required": ["mode", "tables", "migrations"],
+              "additionalProperties": false,
+              "properties": {
+                "mode": { "const": "dedicated", "description": "Plugin-owned tables, prefixed `plugin_<normalizedId>_`." },
+                "tables": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+                "migrations": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "Relative paths to `.sql` migration files." }
+              }
+            }
+          ]
+        },
+        "author": { "type": "string" },
+        "license": { "type": "string", "description": "SPDX identifier." },
+        "homepage": { "type": "string", "format": "uri" },
+        "repository": { "type": "string", "format": "uri" }
+      }
+    },
+    "PluginsRegistry": {
+      "type": "object",
+      "required": ["schemaVersion", "plugins"],
+      "additionalProperties": false,
+      "properties": {
+        "schemaVersion": { "type": "integer", "const": 1 },
+        "plugins": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/DiscoveredPlugin" }
+        }
+      }
+    },
+    "DiscoveredPlugin": {
+      "type": "object",
+      "required": ["id", "path", "manifest", "status"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string" },
+        "path": { "type": "string", "description": "Absolute path to the plugin directory." },
+        "manifest": { "$ref": "#/$defs/PluginManifest" },
+        "status": {
+          "type": "string",
+          "enum": ["enabled", "disabled", "incompatible-spec", "invalid-manifest", "load-error"],
+          "description": "Resolved state after discovery. `disabled` = user-disabled via config; others = automatic."
+        },
+        "statusReason": {
+          "type": ["string", "null"],
+          "description": "Human-readable detail when status is anything other than `enabled`."
+        }
+      }
+    }
+  }
+}

package/schemas/project-config.schema.json

@@ -0,0 +1,87 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/project-config.schema.json",
+  "title": "ProjectConfig",
+  "description": "Shape of `.skill-map.json` at the project root. All fields optional; defaults apply when absent. camelCase keys throughout — consistent with the rest of the spec.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1,
+      "description": "Config file shape version. Bumped on breaking changes to this schema."
+    },
+    "adapters": {
+      "type": "array",
+      "description": "Adapter ids to enable, in priority order when multiple match. Empty/absent = use all registered.",
+      "items": { "type": "string" }
+    },
+    "roots": {
+      "type": "array",
+      "description": "Directories (relative to the config file) to scan. Defaults to the scope root.",
+      "items": { "type": "string" }
+    },
+    "ignore": {
+      "type": "array",
+      "description": "Glob patterns to exclude, in addition to `.skill-mapignore`.",
+      "items": { "type": "string" }
+    },
+    "scan": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tokenize": { "type": "boolean", "description": "Whether to compute token counts. Default true." },
+        "strict": { "type": "boolean", "description": "Promote frontmatter warnings to errors. Default false." },
+        "followSymlinks": { "type": "boolean", "description": "Default false." }
+      }
+    },
+    "plugins": {
+      "type": "object",
+      "description": "Per-plugin enable/disable overrides. Keys are plugin ids. Absent = use installed default (enabled).",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "config": { "type": "object", "description": "Plugin-specific config passed to extensions at load time. Shape defined by the plugin.", "additionalProperties": true }
+        }
+      }
+    },
+    "history": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "share": {
+          "type": "boolean",
+          "description": "When true, `./.skill-map/history.json` is intended to be committed. Stability: experimental. Default false."
+        },
+        "retentionDays": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "How long to keep execution records before GC."
+        }
+      }
+    },
+    "jobs": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "graceMultiplier": { "type": "number", "minimum": 1, "description": "Default grace multiplier applied to `expectedDurationSeconds`. Default 3." },
+        "minimumTtlSeconds": { "type": "integer", "minimum": 1, "description": "Floor for computed TTL. Default 60." },
+        "perActionTtl": {
+          "type": "object",
+          "description": "Per-action TTL overrides (seconds). Keys are action ids.",
+          "additionalProperties": { "type": "integer", "minimum": 1 }
+        }
+      }
+    },
+    "i18n": {
+      "type": "object",
+      "description": "Stability: experimental.",
+      "additionalProperties": false,
+      "properties": {
+        "locale": { "type": "string", "description": "BCP-47 tag. Default `en`." }
+      }
+    }
+  }
+}

package/schemas/report-base.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/report-base.schema.json",
+  "title": "ReportBase",
+  "description": "Base shape for any probabilistic report produced by an LLM-backed action (summarizers, `sm what`, `sm cluster-triggers`, etc.). All per-kind summary schemas under `summaries/` extend this. Kernel validates the `confidence` and `safety` fields regardless of action-specific extensions.",
+  "type": "object",
+  "required": ["confidence", "safety"],
+  "properties": {
+    "confidence": {
+      "type": "number",
+      "minimum": 0,
+      "maximum": 1,
+      "description": "Model's self-assessed confidence in its own output, 0–1. Not calibrated across models; compare within the same action."
+    },
+    "safety": {
+      "type": "object",
+      "required": ["injectionDetected", "contentQuality"],
+      "additionalProperties": false,
+      "properties": {
+        "injectionDetected": {
+          "type": "boolean",
+          "description": "True when the model flagged a prompt-injection attempt inside the node content. See `prompt-preamble.md` for the contract the model was primed with."
+        },
+        "injectionType": {
+          "type": ["string", "null"],
+          "enum": ["direct-override", "role-swap", "hidden-instruction", "other", null],
+          "description": "Classification. Null when `injectionDetected = false`."
+        },
+        "injectionDetails": {
+          "type": ["string", "null"],
+          "description": "Free-form notes from the model about the injection attempt."
+        },
+        "contentQuality": {
+          "type": "string",
+          "enum": ["clean", "suspicious", "malformed"],
+          "description": "`clean` = normal input. `suspicious` = unusual patterns without a concrete injection. `malformed` = unparseable or structurally broken."
+        }
+      }
+    }
+  }
+}

package/schemas/scan-result.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://skill-map.dev/spec/v0/scan-result.schema.json",
+  "title": "ScanResult",
+  "description": "Canonical output of `sm scan --json` (and the data shape sent over WebSocket scan events). Self-describing and versioned; consumers MUST check `schemaVersion` before parsing.",
+  "type": "object",
+  "required": ["schemaVersion", "scannedAt", "scope", "roots", "nodes", "links", "issues", "stats"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1,
+      "description": "Scan result shape version. Bumped only on breaking changes to this schema."
+    },
+    "scannedAt": {
+      "type": "integer",
+      "description": "Unix milliseconds when the scan started."
+    },
+    "scannedBy": {
+      "type": ["object", "null"],
+      "description": "Implementation metadata. Optional so that synthetic fixtures can omit it.",
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "description": "Implementation name (e.g. `skill-map`)." },
+        "version": { "type": "string", "description": "Implementation semver." },
+        "specVersion": { "type": "string", "description": "Spec version that this scan conforms to (e.g. `0.1.0`)." }
+      }
+    },
+    "scope": {
+      "type": "string",
+      "enum": ["project", "global"],
+      "description": "Scan scope. `project` walks the cwd repo; `global` walks user-level skill directories."
+    },
+    "roots": {
+      "type": "array",
+      "description": "Filesystem roots that were walked during this scan, as absolute or scope-root-relative paths.",
+      "minItems": 1,
+      "items": { "type": "string" }
+    },
+    "adapters": {
+      "type": "array",
+      "description": "Adapter ids that participated in classification. Empty if no adapter matched.",
+      "items": { "type": "string" }
+    },
+    "nodes": {
+      "type": "array",
+      "items": { "$ref": "node.schema.json" }
+    },
+    "links": {
+      "type": "array",
+      "items": { "$ref": "link.schema.json" }
+    },
+    "issues": {
+      "type": "array",
+      "items": { "$ref": "issue.schema.json" }
+    },
+    "stats": {
+      "type": "object",
+      "required": ["filesWalked", "filesSkipped", "nodesCount", "linksCount", "issuesCount", "durationMs"],
+      "additionalProperties": false,
+      "properties": {
+        "filesWalked": { "type": "integer", "minimum": 0 },
+        "filesSkipped": { "type": "integer", "minimum": 0, "description": "Files walked but not classified by any adapter." },
+        "nodesCount": { "type": "integer", "minimum": 0 },
+        "linksCount": { "type": "integer", "minimum": 0 },
+        "issuesCount": { "type": "integer", "minimum": 0 },
+        "durationMs": { "type": "integer", "minimum": 0 }
+      }
+    }
+  }
+}