Runner-less skips name their exit

README.html

@@ -235,7 +235,7 @@ <h1>cladding</h1>
   <p class="badges">
     <a href="https://github.com/qwerfunch/ironclad"><img src="https://img.shields.io/badge/ironclad-L4%20conformant-brightgreen" alt="ironclad"></a>
     <a href="https://github.com/qwerfunch/ironclad"><img src="https://img.shields.io/badge/spec-v0.0.23-blue" alt="spec"></a>
-    <img src="https://img.shields.io/badge/tests-2953%2F2953-brightgreen" alt="tests">
+    <img src="https://img.shields.io/badge/tests-2981%2F2981-brightgreen" alt="tests">
     <img src="https://img.shields.io/badge/detectors-41-brightgreen" alt="detectors">
     <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="license"></a>
   </p>
@@ -566,7 +566,7 @@ <h2>Status</h2>
       </td>
       <td style="text-align:center;width:140px;background:#f8fafc;padding:18px 10px;border-radius:8px;border:none">
         <div style="font-size:11px;color:#64748b;letter-spacing:1.5px;text-transform:uppercase;font-weight:600">tests</div>
-        <div style="font-size:24px;font-weight:800;color:#0f172a;margin:8px 0;letter-spacing:-0.5px">2953<span style="font-size:16px;color:#94a3b8">/2953</span></div>
+        <div style="font-size:24px;font-weight:800;color:#0f172a;margin:8px 0;letter-spacing:-0.5px">2981<span style="font-size:16px;color:#94a3b8">/2981</span></div>
         <div style="font-size:11px;color:#64748b">all pass</div>
       </td>
       <td style="text-align:center;width:140px;background:#f8fafc;padding:18px 10px;border-radius:8px;border:none">

README.ja.md

@@ -12,7 +12,7 @@
 <p align="center">
   <a href="https://github.com/qwerfunch/ironclad"><img src="https://img.shields.io/badge/ironclad-L4%20conformant-brightgreen" alt="ironclad"/></a>
   <a href="https://github.com/qwerfunch/ironclad"><img src="https://img.shields.io/badge/spec-v0.0.23-blue" alt="spec"/></a>
-  <img src="https://img.shields.io/badge/tests-2953%2F2953-brightgreen" alt="tests"/>
+  <img src="https://img.shields.io/badge/tests-2981%2F2981-brightgreen" alt="tests"/>
   <img src="https://img.shields.io/badge/detectors-41-brightgreen" alt="detectors"/>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="license"/></a>
 </p>
@@ -347,7 +347,7 @@ clad update              # 3. プロジェクト接続と派生状態を更新
 
 | Version | 準拠レベル | Tests | Gate | Features |
 |---|---|---|---|---|
-| v0.9.4（2026-08） | L4 · [自己申告](https://github.com/qwerfunch/ironclad/blob/main/GOVERNANCE.md) | 2953 / 2953 | 15 段階 · 41 detectors | 277（273 done） |
+| v0.9.4（2026-08） | L4 · [自己申告](https://github.com/qwerfunch/ironclad/blob/main/GOVERNANCE.md) | 2981 / 2981 | 15 段階 · 41 detectors | 277（273 done） |
 
 <sub>253 test files · capability 6 個 · カバレッジ低下は COVERAGE_DROP detector がブロック</sub>
 

README.ko.html

@@ -277,7 +277,7 @@ <h1>cladding</h1>
   <p class="badges">
     <a href="https://github.com/qwerfunch/ironclad"><img src="https://img.shields.io/badge/ironclad-L4%20conformant-brightgreen" alt="ironclad"></a>
     <a href="https://github.com/qwerfunch/ironclad"><img src="https://img.shields.io/badge/spec-v0.0.23-blue" alt="spec"></a>
-    <img src="https://img.shields.io/badge/tests-2953%2F2953-brightgreen" alt="tests">
+    <img src="https://img.shields.io/badge/tests-2981%2F2981-brightgreen" alt="tests">
     <img src="https://img.shields.io/badge/detectors-41-brightgreen" alt="detectors">
     <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="license"></a>
   </p>
@@ -600,7 +600,7 @@ <h2>Status</h2>
       </td>
       <td style="text-align:center;width:140px;background:#f8fafc;padding:18px 10px;border-radius:8px;border:none">
         <div style="font-size:11px;color:#64748b;letter-spacing:1.5px;text-transform:uppercase;font-weight:600">tests</div>
-        <div style="font-size:24px;font-weight:800;color:#0f172a;margin:8px 0;letter-spacing:-0.5px">2953<span style="font-size:16px;color:#94a3b8">/2953</span></div>
+        <div style="font-size:24px;font-weight:800;color:#0f172a;margin:8px 0;letter-spacing:-0.5px">2981<span style="font-size:16px;color:#94a3b8">/2981</span></div>
         <div style="font-size:11px;color:#64748b">all pass</div>
       </td>
       <td style="text-align:center;width:140px;background:#f8fafc;padding:18px 10px;border-radius:8px;border:none">

README.ko.md

@@ -12,7 +12,7 @@
 <p align="center">
   <a href="https://github.com/qwerfunch/ironclad"><img src="https://img.shields.io/badge/ironclad-L4%20conformant-brightgreen" alt="ironclad"/></a>
   <a href="https://github.com/qwerfunch/ironclad"><img src="https://img.shields.io/badge/spec-v0.0.23-blue" alt="spec"/></a>
-  <img src="https://img.shields.io/badge/tests-2953%2F2953-brightgreen" alt="tests"/>
+  <img src="https://img.shields.io/badge/tests-2981%2F2981-brightgreen" alt="tests"/>
   <img src="https://img.shields.io/badge/detectors-41-brightgreen" alt="detectors"/>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="license"/></a>
 </p>
@@ -346,7 +346,7 @@ clad update              # 3. 프로젝트 연결과 파생 데이터를 함께
 
 | version | 준수 등급 | tests | gate | features |
 |---|---|---|---|---|
-| v0.9.4 · 2026-08 | L4 · [L0–L4 중 최고 · 자가 선언](https://github.com/qwerfunch/ironclad/blob/main/GOVERNANCE.md) | 2953 / 2953 · all pass | 15 단계 · 41 detectors | 277 · 273 done · 자기 스펙 |
+| v0.9.4 · 2026-08 | L4 · [L0–L4 중 최고 · 자가 선언](https://github.com/qwerfunch/ironclad/blob/main/GOVERNANCE.md) | 2981 / 2981 · all pass | 15 단계 · 41 detectors | 277 · 273 done · 자기 스펙 |
 
 <sub>253 test files · capability 6개 · coverage는 COVERAGE_DROP detector가 하락 차단</sub>
 

README.md

@@ -12,7 +12,7 @@
 <p align="center">
   <a href="https://github.com/qwerfunch/ironclad"><img src="https://img.shields.io/badge/ironclad-L4%20conformant-brightgreen" alt="ironclad"/></a>
   <a href="https://github.com/qwerfunch/ironclad"><img src="https://img.shields.io/badge/spec-v0.0.23-blue" alt="spec"/></a>
-  <img src="https://img.shields.io/badge/tests-2953%2F2953-brightgreen" alt="tests"/>
+  <img src="https://img.shields.io/badge/tests-2981%2F2981-brightgreen" alt="tests"/>
   <img src="https://img.shields.io/badge/detectors-41-brightgreen" alt="detectors"/>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="license"/></a>
 </p>
@@ -360,7 +360,7 @@ Reconcile the drift the update flagged.
 
 | Version | Conformance | Tests | Gate | Features |
 |---|---|---|---|---|
-| v0.9.4 (2026-08) | L4 · [self-declared](https://github.com/qwerfunch/ironclad/blob/main/GOVERNANCE.md) | 2953 / 2953 | 15 stages · 41 detectors | 277 (273 done) |
+| v0.9.4 (2026-08) | L4 · [self-declared](https://github.com/qwerfunch/ironclad/blob/main/GOVERNANCE.md) | 2981 / 2981 | 15 stages · 41 detectors | 277 (273 done) |
 
 <sub>253 test files · 6 capabilities · coverage drop blocked by the COVERAGE_DROP detector</sub>
 

README.zh.md

@@ -12,7 +12,7 @@
 <p align="center">
   <a href="https://github.com/qwerfunch/ironclad"><img src="https://img.shields.io/badge/ironclad-L4%20conformant-brightgreen" alt="ironclad"/></a>
   <a href="https://github.com/qwerfunch/ironclad"><img src="https://img.shields.io/badge/spec-v0.0.23-blue" alt="spec"/></a>
-  <img src="https://img.shields.io/badge/tests-2953%2F2953-brightgreen" alt="tests"/>
+  <img src="https://img.shields.io/badge/tests-2981%2F2981-brightgreen" alt="tests"/>
   <img src="https://img.shields.io/badge/detectors-41-brightgreen" alt="detectors"/>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="license"/></a>
 </p>
@@ -343,7 +343,7 @@ clad update              # 3. 刷新项目连接和派生状态
 
 | 版本 | 一致性 | Tests | Gate | Features |
 |---|---|---|---|---|
-| v0.9.4（2026-08） | L4 · [自我声明](https://github.com/qwerfunch/ironclad/blob/main/GOVERNANCE.md) | 2953 / 2953 | 15 阶段 · 41 检测器 | 277（273 done） |
+| v0.9.4（2026-08） | L4 · [自我声明](https://github.com/qwerfunch/ironclad/blob/main/GOVERNANCE.md) | 2981 / 2981 | 15 阶段 · 41 检测器 | 277（273 done） |
 
 <sub>253 个测试文件 · 6 项 capability · 覆盖率下降由 COVERAGE_DROP 检测器拦下</sub>
 

spec.yaml

@@ -54,7 +54,7 @@ project:
 
 # Auto-maintained by `clad sync` (F-5b9f9f). Do not edit by hand.
 inventory:
-  features: 280
+  features: 281
   scenarios: 2
   capabilities: 6
-  test_files: 257
+  test_files: 259

spec/attestation.yaml

@@ -26,12 +26,12 @@ attested_modules:
   CHANGELOG.md: b15c6185d8326b9b
   CLAUDE.md: 9f2fa4edd5c6df80
   GOVERNANCE.md: 21cc28eaaf637a20
-  README.html: 736f4c0126990f5b
-  README.ja.md: 82b53a627e2d1b1f
-  README.ko.html: efbfce7cab897fb6
-  README.ko.md: 3f31659ae168dcb1
-  README.md: 4b06c324d8168a7c
-  README.zh.md: c7ac2cfce5153064
+  README.html: 238c9d2f0b277e22
+  README.ja.md: 22f0dc832db0fa5e
+  README.ko.html: ee75bfe5b5a1bc76
+  README.ko.md: 3ca7d8b31a5e3ce6
+  README.md: 562ae2d94af38500
+  README.zh.md: 695a60c73fd01383
   SECURITY.md: df1d0c80304b2f28
   bin/clad: 77b80666665dd1b0
   conformance/fixtures.yaml: 5b461bb43a79a983
@@ -123,7 +123,7 @@ attested_modules:
   skills/serve/SKILL.md: f08bbdbbfeb05041
   skills/status/SKILL.md: 09faadc50b3449da
   skills/sync/SKILL.md: 775c0f990a52a3d9
-  spec.yaml: 92fb4b9e3ef75577
+  spec.yaml: 9b979cd4e7d137d2
   spec/README.md: 7c257426396d435c
   spec/architecture.yaml: f0888480405a13a8
   spec/features/: a4d0f0eb87fed960
@@ -157,7 +157,7 @@ attested_modules:
   src/cli/benchmark.ts: 77f84d2a898d724f
   src/cli/changelog.ts: 2de1adb009b89ab4
   src/cli/ci-version.ts: 9fce2c2d7415b4ca
-  src/cli/clad.ts: dc3a50b14786e23b
+  src/cli/clad.ts: 8705b384a37f38e1
   src/cli/clarify.ts: f17177969d5b75ff
   src/cli/doctor-hosts.ts: 1f0c2cec5a310b81
   src/cli/doctor.ts: 50d904fdbfe7e942
@@ -267,7 +267,7 @@ attested_modules:
   src/stages/arch.ts: 268422e53c6d20bb
   src/stages/audit.ts: 3ba117606f8a81a1
   src/stages/commit.ts: f6b6836af0a4d96c
-  src/stages/cov.ts: 3dbe8381e374e8c0
+  src/stages/cov.ts: 4529f5e80bda08fd
   src/stages/deliverable-smoke.ts: 9ecfd4210e6ec5c0
   src/stages/detector-result-cache.ts: 93ea6af02ef361c5
   src/stages/detectors/README.md: 3fe2c865aa2adcba
@@ -320,7 +320,7 @@ attested_modules:
   src/stages/finding-parser.ts: d9cd56dbe3c3b9a7
   src/stages/graph-health.ts: a294f06796b0e293
   src/stages/junit-report.ts: f8466dc1e00140f1
-  src/stages/lint.ts: e9c4505e587e6088
+  src/stages/lint.ts: e2bd76900a583983
   src/stages/perf.ts: 2b27c12427f65b2e
   src/stages/secret.ts: b90abc0e00c86219
   src/stages/skip-policy.ts: 1a6412d708561cf0
@@ -334,11 +334,11 @@ attested_modules:
   src/stages/toolchain/module-scope.ts: 88358ec3b84eedd3
   src/stages/toolchain/scoped-command.ts: f2dd6410c063279f
   src/stages/toolchain/types.ts: 05f018fb3dddc321
-  src/stages/type.ts: 0ac37e45b407446d
-  src/stages/types.ts: 95e8c9e13187d85b
+  src/stages/type.ts: 56c43d7954c25db3
+  src/stages/types.ts: ccc885299871e57f
   src/stages/uat.ts: 62ec3e37a124f8c5
-  src/stages/unit.ts: b503350b0e5c7e5a
-  src/stages/util.ts: 7c49de3250816de8
+  src/stages/unit.ts: 7471a2cca0c969d6
+  src/stages/util.ts: c9e18d2c9cd90dba
   src/stages/vacuous-tests.ts: 8e71b81e151325af
   src/stages/visual.ts: 2b60dd991fa8124e
   src/ui: a4d0f0eb87fed960
@@ -676,6 +676,7 @@ attested_features:
   F-bdcd90: ok
   F-be5306eb: ok
   F-c037ae: ok
+  F-c17e1edc: ok
   F-c2c996: ok
   F-c3747d7d: ok
   F-c48eb2: ok

spec/features/skip-exit-guidance-c17e1edc.yaml

@@ -0,0 +1,63 @@
+id: F-c17e1edc
+slug: skip-exit-guidance
+title: "Runner-less skips name their exit: gate.commands guidance"
+status: done
+modules:
+  - src/stages/types.ts
+  - src/stages/type.ts
+  - src/stages/lint.ts
+  - src/stages/unit.ts
+  - src/stages/cov.ts
+  - src/stages/util.ts
+  - src/cli/clad.ts
+acceptance_criteria:
+  - id: AC-4b7d20e5
+    ears: ubiquitous
+    action: "tag every skip result with a structured reason — 'no-runner' when a command stage skips because no runner is registered for the project's language, 'tool-missing' when the resolved tool is absent or npx cannot fetch it — leaving by-design skips (missing oracles, no declared deliverable) untagged"
+    response: "the machine surface distinguishes 'cladding does not know how to run this' from 'this stage does not apply', without changing any existing stderr string, exit code, or skip semantics"
+    text: "The system shall carry a structured skipReason ('no-runner' | 'tool-missing') on command-stage skip results, tagged at the production sites, with by-design skips untagged and every existing skip message byte-identical."
+    notes: |
+      ## Why
+      Measured on a zig adopter: six of nine stages skip, and the six split into
+      two classes — four say "no <X> registered for language" (curable by
+      declaring gate.commands) and two are by-design (oracle absence, no
+      deliverable) where that cure is a false prescription. Blanket guidance
+      would lie on two stages; a stderr regex would be a parser where a field
+      belongs.
+    test_refs: ["tests/cli/skip-exit-guidance.test.ts", "tests/cli/gate-golden-matrix.test.ts"]
+  - id: AC-90c3f1a8
+    ears: event
+    condition: "when a check run finishes with at least one no-runner skip and text output is active"
+    action: "print exactly one trailing info line that lists the skipped stage labels and shows the concrete remedy inline — declaring commands under gate.commands in .cladding/config.yaml — noting the file is committable so CI runs the same gate"
+    response: "an adopter whose language cladding cannot drive sees, at the moment of the skip, the one declaration that turns those stages on — measured true end-to-end before this feature was designed: declaring gate.commands flips all four stages from skip to run through the shipped binary"
+    text: "When at least one stage skipped for lack of a runner, the system shall print one info line naming those stages and the gate.commands declaration inline, and shall print nothing when no such skip occurred."
+    notes: |
+      ## Why
+      The exit exists but is invisible: across every adopter-reachable surface
+      (gate output, READMEs, managed AGENTS.md, doctor, MCP tool descriptions)
+      gate.commands is mentioned once — a CHANGELOG line. The gate.language
+      external E2E proved this exact configuration fails: removing that one
+      line left a fully-capable AI unable to find the exit. The guidance is
+      inline (key path + example) because docs/ does not ship in the npm
+      package. The language name is not printed — it reads 'unknown' in the
+      motivating case.
+    test_refs: ["tests/cli/skip-exit-guidance.test.ts"]
+  - id: AC-2f6e88d0
+    ears: unwanted
+    condition: "if every skip is by-design or tool-missing, or gate.commands is already declared, or all stages ran"
+    action: "print no guidance line"
+    response: "the by-design skips (spec-conformance oracles, deliverable smoke) never carry a false prescription, a tool-missing skip is not advised to declare commands it already has, and a fully-driven project sees nothing new — measured 4/0/0/0 across the four guard environments before implementation"
+    text: "If no stage skipped for lack of a runner, the system shall print no guidance."
+    test_refs: ["tests/cli/skip-exit-guidance.test.ts"]
+  - id: AC-b59a37c4
+    ears: event
+    condition: "when check emits its JSON report"
+    action: "include the skipReason field on each skipped stage entry that carries one"
+    response: "MCP and CI consumers receive the same discrimination the terminal renders, additively — no existing JSON field changes"
+    text: "When emitting JSON, the system shall include skipReason on tagged stage entries and change no existing field."
+    test_refs: ["tests/cli/skip-exit-guidance.test.ts"]
+design_impact:
+  classification: none
+  rationale: "Additive observability: a structured reason on an existing skip lane and one rendered line. No gate decision, severity, or stage semantics change; skips stay skips."
+  status: resolved
+  artifacts: []

spec/index.yaml

@@ -234,6 +234,7 @@ features:
   F-bdcd90: {slug: oracle-policy-risk-weighted, status: done, modules: 8}
   F-be5306eb: {slug: cold-start-cycle-signal, status: done, modules: 3}
   F-c037ae: {slug: test-refs-repair, status: done, modules: 4}
+  F-c17e1edc: {slug: skip-exit-guidance, status: done, modules: 7}
   F-c2c996: {slug: checkpoint-events, status: done, modules: 3}
   F-c3747d7d: {slug: spec-first-window-complete, status: done, modules: 5}
   F-c48eb2: {slug: scan-source-roots, status: done, modules: 5}