feat: derive the ADRs a repo already obeys, and make the skill linter a gate that actually runs

.github/workflows/ci.yml

@@ -61,3 +61,20 @@ jobs:
       # `ci-adr-gate.test.ts` pins this step's existence — deleting it fails the suite.
       - name: ADR gate (accepted ADRs' kit-enforce rules)
         run: node dist/cli.js adr check
+
+      # SKILL DISCIPLINE — same failure class as the ADR gate above, found the same way.
+      # `kit skill test --gate` has always exited 1 on a failing skill and nothing ever ran
+      # it: not CI, not `kit review`, not verify-suite.sh. Measured the day this landed, kit's
+      # ONLY shipped SKILL.md failed kit's own linter (no `allowed-tools` — the skill
+      # implicitly claimed every tool) for as long as the linter had existed, and no pipeline
+      # said a word. A tool that lints skills while shipping one that fails it is not a gate,
+      # it is advice.
+      #
+      # This runs the `skill` stage of `kit review`, so it covers every SKILL.md the repo
+      # ships rather than one hard-coded path — a second skill cannot be added un-gated.
+      # Module discipline only: contract, trigger collision, BOUNDED tool scope, and drift
+      # from the committed snapshot. Whether a skill's output is any GOOD is a model
+      # judgement and stays outside kit (ADR-0001). A repo with no skills skips honestly.
+      # `ci-adr-gate.test.ts` pins this step's existence — deleting it fails the suite.
+      - name: Skill gate (module discipline for every shipped SKILL.md)
+        run: node dist/cli.js review --stages skill

AGENTS.md

@@ -25,7 +25,7 @@ makes them four deterministic rules — not prose:
 - **ADR-0003** the check path imports no coverage-framework mappings.
 
 `node dist/cli.js adr check` runs them and **fails CI hard** on a violation. `kit check`
-does **not** include the ADR stage — only `kit review` (check + design + standards + adr)
+does **not** include the ADR stage — only `kit review` (check + design + standards + adr + skill)
 does. So before opening a PR that adds a dependency, moves an import, or touches
 `src/check*.ts`, run `kit review`, not `kit check` alone.
 

CLAUDE.md

@@ -38,7 +38,7 @@ makes them four deterministic rules — not prose:
 - **ADR-0003** the check path imports no coverage-framework mappings.
 
 `node dist/cli.js adr check` runs them and **fails CI hard** on a violation. `kit check`
-does **not** include the ADR stage — only `kit review` (check + design + standards + adr)
+does **not** include the ADR stage — only `kit review` (check + design + standards + adr + skill)
 does. So before opening a PR that adds a dependency, moves an import, or touches
 `src/check*.ts`, run `kit review`, not `kit check` alone.
 

README.md

@@ -267,7 +267,7 @@ Complete reference: [`docs/COMMANDS.md`](./docs/COMMANDS.md). The shortlist:
 - `kit setup`: Full pipeline: install → hooks → login → secrets → check
 - `kit check`: Status of tools, services, secrets, hooks, deploy env, security, tests
 - `kit fix`: Auto-remediate gaps (tools, gitignore, hooks, .env.template, declared deploy env) and print HITL blocks for auth / DSN setup
-- `kit review` / `kit heal`: One-gate repo audit (check + design + standards + ADR); bounded self-heal loop
+- `kit review` / `kit heal`: One-gate repo audit (check + design + standards + ADR + skill discipline); bounded self-heal loop
 - `kit adr {check,list,freeze}`: Turn an Architecture Decision Record into a deterministic gate — enforce a `kit-enforce` block (`forbid_pattern` / `require_pattern` / `forbid_import`, incl. transitive and across npm package boundaries) cited back to the ADR. Zero-LLM (prose is never interpreted)
 - `.kit/standards.d/*.toml`: Declarative house-rule plugins support `mode = "forbid"` and `mode = "require"`; directory excludes like `scripts/` mean `scripts/**`, with zero-match warnings
 - `kit scan`: Run external scanners (snyk/trivy/grype/semgrep/osv/socket) → one merged, air-gap-aware verdict
@@ -1021,7 +1021,7 @@ For Cline, add the same config to your `cline_mcp_settings.json`.
 | Tool            | Description                                                                                     |
 | --------------- | ----------------------------------------------------------------------------------------------- |
 | `kit_check`     | Run all checks, return structured status JSON                                                   |
-| `kit_review`    | Full repo audit — check + design + standards + ADR gates as one structured report              |
+| `kit_review`    | Full repo audit — check + design + standards + ADR + skill gates as one structured report              |
 | `kit_fix`       | Auto-fix issues (install tools, generate lock files)                                            |
 | `kit_triage`    | Security-triage a dependency BEFORE installing it — a pass satisfies the install gate           |
 | `kit_memory`    | Search cross-session memory + the repo's curated shared decisions (search-only)                 |

contracts/kit.opencli.json

@@ -68,13 +68,17 @@
     },
     "adr": {
       "kind": "command",
-      "summary": "Enforce architecture decisions (ADR → gate): 'kit adr check' gates the repo on accepted ADRs' deterministic kit-enforce rules, cited to the ADR; 'kit adr list' shows enforced/documented. Zero-LLM (prose is never interpreted).",
+      "summary": "Enforce architecture decisions (ADR → gate): 'kit adr check' gates the repo on accepted ADRs' deterministic kit-enforce rules, cited to the ADR; 'kit adr list' shows enforced/documented; 'kit adr derive' proposes the decisions an inherited repo already obeys, each verified against the repo and emitted as status: proposed so it gates nothing until you accept it. Zero-LLM (prose is never interpreted).",
       "x-kit-accepted-flags": [
+        "--emit",
         "--env",
         "--help",
+        "--json",
+        "--min-support",
         "--non-interactive",
         "--read-only",
         "--readonly",
+        "--root",
         "--version"
       ],
       "x-kit-args-modeled": true,
@@ -3075,7 +3079,7 @@
     },
     "review": {
       "kind": "command",
-      "summary": "Full repo audit — runs check + design + standards + adr in one gate (for agents / PR checks; --json emits one structured report; --stages check,standards scopes the run, --category scopes the standards stage)",
+      "summary": "Full repo audit — runs check + design + standards + adr + skill in one gate (for agents / PR checks; --json emits one structured report; --stages check,standards scopes the run, --category scopes the standards stage)",
       "x-kit-accepted-flags": [
         "--attest",
         "--category",

docs/COMMANDS.md

@@ -97,8 +97,8 @@ port = 3107
 | `kit design`                                                                          | A11y + design-token checks, baseline-aware.                                                                                                                                                                                                               |
 | `kit standards [--category general\|specific\|plugins\|platform\|<lang>] [--enforce]` | Dev-standards gate: general metrics (complexity/duplication/size via lizard/jscpd/scc) + per-language linters (11 langs) + user plugins (`.kit/standards.d/`) + container (hadolint). Warn by default; `--enforce` fails net-new findings AND setup gaps. |
 | `kit standards freeze`                                                                | Snapshot only the standards dimensions into `.kit-baseline.json`.                                                                                                                                                                                         |
-| `kit review`                                                                          | Meta-runner — `check + design + standards + adr` gate for PR.                                                                                                                                                                                             |
-| `kit adr [check\|list\|freeze]`                                                        | ADR → gate: enforce accepted ADRs' `kit-enforce` rules (`forbid_pattern` / `require_pattern` / `forbid_import`, incl. transitive and cross-package via `follow_packages`), cited to the ADR. `list` shows status; `freeze` baselines existing findings. Zero-LLM (prose is never interpreted).     |
+| `kit review`                                                                          | Meta-runner — `check + design + standards + adr + skill` gate for PR. The `skill` stage runs module discipline over every shipped `SKILL.md` (contract, trigger collision, bounded tool scope, snapshot drift); a repo with no skills skips honestly.                                                                                                                                                                                             |
+| `kit adr [check\|list\|freeze\|derive]`                                                        | ADR → gate: enforce accepted ADRs' `kit-enforce` rules (`forbid_pattern` / `require_pattern` / `forbid_import`, incl. transitive and cross-package via `follow_packages`), cited to the ADR. `list` shows status; `freeze` baselines existing findings; `derive` proposes ADRs the code already obeys (absent import edges with a populated reverse), each re-run through the real evaluator before it is shown and emitted as `status: proposed` so it gates nothing until a human accepts it. Zero-LLM (prose is never interpreted).     |
 | `kit baseline [freeze]`                                                               | Snapshot current acceptable warnings (incl. standards + ADR) to `.kit-baseline.json`.                                                                                                                                                                     |
 | `kit analyze [--write]`                                                               | Mine git history + framework markers → draft `CLAUDE.md` / `RULES.md`.                                                                                                                                                                                    |
 

docs/MCP_TOOLS_GUIDE.md

@@ -40,7 +40,7 @@ kit_triage  → REQUIRED before installing anything the install gate has not
               MCP-run triage satisfies it identically to a CLI-run one
 kit_memory  → recall prior cross-session decisions before answering
               project-specific questions
-kit_review  → the full audit (check + design + standards + ADR) as one
+kit_review  → the full audit (check + design + standards + ADR + skill) as one
               structured report — run before merging; concise:true trims
               pass/skip rows for context economy
 kit_run     → escape hatch: any other kit command

skills/triage/.kit-skill.snapshot.json

@@ -0,0 +1,8 @@
+{
+  "name": "triage",
+  "triggerKey": "security triage a dependency before installing it",
+  "scope": [
+    "Bash"
+  ],
+  "fingerprint": "sha256:77a14838365b108a"
+}

skills/triage/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: triage
 description: "Security-triage a dependency before installing it."
+allowed-tools: Bash
 ---
 
 # Triage
@@ -33,6 +34,15 @@ python3 scripts/triage.py <type> <target>
   that is a CRITICAL ("cannot verify"), so the pass is withheld and kit blocks the
   install. Set `GITHUB_TOKEN` to avoid GitHub rate limits on `repo` checks.
 
+## Scope
+
+`allowed-tools: Bash` — the whole skill is one subprocess call to
+`scripts/triage.py`. It reads no files through the agent (the script opens what it
+needs itself), fetches nothing through the agent, and writes nothing. Anything
+broader would be a claim this skill cannot cash: an undeclared `allowed-tools`
+implicitly claims EVERY tool, which is the opposite of what a gate should assert
+about itself.
+
 ## Rules
 
 - Stdlib only (urllib). No third-party deps, no network calls other than the