bmad-module-skill-forge 2.0.1 → 2.1.0

package/src/skf-setup/references/ccc-index.md

@@ -32,9 +32,9 @@ For Quick and Forge tiers, or when ccc is unavailable, skip silently and proceed
 
 Read `{ccc}` and `{ccc_skip_index}` from context.
 
-**If `{ccc}` is false:** Set `{ccc_index_result: "none", ccc_indexed_path: null, ccc_last_indexed: null, ccc_exclude_patterns: [], ccc_exclusion_warnings: [], settings_yml_written: false, settings_yml_patterns_added: 0}`. Proceed directly to section 4 (Auto-Proceed) — no output, no messaging.
+**If `{ccc}` is false:** Set `{ccc_index_result: "none", ccc_indexed_path: null, ccc_last_indexed: null, ccc_exclude_patterns: [], ccc_exclusion_warnings: [], settings_yml_written: false, settings_yml_patterns_added: 0}`. Proceed directly to section 5 (Auto-Proceed) — no output, no messaging.
 
-**If `{ccc}` is true AND `{ccc_skip_index}` is true:** Run the exclusion-merge (section 3) so settings.yml stays current, then set `{ccc_index_result: "skipped", ccc_indexed_path: null, ccc_last_indexed: null}` and proceed to section 4 — do not run `ccc init` or `ccc index`. The envelope's `ccc_index.status` will be `"skipped"` so pipelines that plan an out-of-band re-index can distinguish "the operator opted out" from "indexing failed".
+**If `{ccc}` is true AND `{ccc_skip_index}` is true:** Run the exclusion-merge (section 3) so settings.yml stays current, then set `{ccc_index_result: "skipped", ccc_indexed_path: null, ccc_last_indexed: null}` and proceed to section 5 (Auto-Proceed) — do not run `ccc init` or `ccc index`. The envelope's `ccc_index.status` will be `"skipped"` so pipelines that plan an out-of-band re-index can distinguish "the operator opted out" from "indexing failed".
 
 **If `{ccc}` is true AND `{ccc_skip_index}` is false:** Continue to section 2.
 

package/src/skf-setup/references/report.md

@@ -77,7 +77,7 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
   {end if}
 
   {if hygiene_result is "qmd_unavailable":}
-  QMD Registry: skipped (daemon error — retry after `qmd start`).
+  QMD Registry: skipped (qmd unavailable — if the daemon is stopped, `qmd start` restores it).
   {end if}
 
   {if tools.ccc is true:}

package/src/skf-test-skill/references/coverage-check.md

@@ -216,9 +216,9 @@ On a split-body skill the §1 inventory (documented surface) and the §2 AST out
 
 1. **Enumerated path (`denominatorSource: "barrel"`)** — the common split-body case. `barrel_set` is the union of `exports_found[]` across every §2 per-file result. **When a stratified-scope or State-2 denominator applies (see §4) and it resolves to an enumerated name set** — the priority-2/3 re-derivation from `scope.tier_a_include` / `scope.include` globs — pass that resolved name set as `barrelSet` so the script intersects against it instead of the raw per-file union. The script computes `Documented := |documented_set ∩ barrel_set|`, `Missing := barrel_set − documented_set` (in source, not documented), `Stale := documented_set − barrel_set` (documented, not in source), and `Export Coverage = |Documented| / |barrel_set| * 100`.
 
-2. **Scalar-denominator branch (`denominatorSource: "scalar"`)** — §4 priority 1, when the resolved denominator is the scalar `metadata.json.stats.effective_denominator` (a count with **no enumerated name set**). There is no `barrel_set` to intersect, so the script instead greps each `documented_set` name across `SKILL.md ∪ references/*.md` and counts appearances. Pass `denominatorValue: effective_denominator` and `skillPackagePath: {resolved_skill_package}`; the script sets `Missing := effective_denominator − Documented` and returns an empty `Stale` (not enumerable without a barrel name set). If §4b's numerator-ground-truth arm fires (it triggers only when `exports_documented == effective_denominator`), its verified count is authoritative and **overrides** this numerator — do not apply both.
+2. **Scalar-denominator branch (`denominatorSource: "scalar"`)** — §4 priority 1, when the resolved denominator is the scalar `metadata.json.stats.effective_denominator` (a count with **no enumerated name set**). There is no `barrel_set` to intersect, so the script instead greps each `documented_set` name across `SKILL.md ∪ references/*.md` and counts appearances. Pass `denominatorValue: effective_denominator` and `skillPackagePath: {resolved_skill_package}`; the script sets `Missing := max(0, effective_denominator − Documented)` and returns an empty `Stale` (not enumerable without a barrel name set). When the grep count overshoots the denominator the script reports the surplus instead of a negative residual — see the surplus note under the returns list. If §4b's numerator-ground-truth arm fires (it triggers only when `exports_documented == effective_denominator`), its verified count is authoritative and **overrides** this numerator — do not apply both.
 
-3. **Stack-skill branch (`denominatorSource: "stack"`, `metadata.json.skill_type == "stack"`)** — a stack's source barrel is empty by design, so intersecting against it would divide by zero. Pass `denominatorValue: stack_denominator` (the §2b composition-surface denominator) and `compositionNames`: the provenance-map cited-contract names (`::`-excluded) when the map exists and is non-empty, else the `libraries` and `integration_pairs` names. The script greps each composition name across `SKILL.md ∪ references/*.md` for the numerator, sets `Missing := stack_denominator − Documented`, and omits `Stale` (no source barrel to enumerate against).
+3. **Stack-skill branch (`denominatorSource: "stack"`, `metadata.json.skill_type == "stack"`)** — a stack's source barrel is empty by design, so intersecting against it would divide by zero. Pass `denominatorValue: stack_denominator` (the §2b composition-surface denominator) and `compositionNames`: the provenance-map cited-contract names (`::`-excluded) when the map exists and is non-empty, else the `libraries` and `integration_pairs` names. The script greps each composition name across `SKILL.md ∪ references/*.md` for the numerator, sets `Missing := max(0, stack_denominator − Documented)`, and omits `Stale` (no source barrel to enumerate against). The same surplus reporting as the scalar branch applies.
 
 **Build the reconciliation input and run the script:**
 
@@ -242,11 +242,14 @@ Input JSON (one object — supply only the fields the chosen branch needs; `{rec
 
 The script returns (read these — **do not re-derive them by hand**):
 
-- `documented` — the numerator (`|documented_set ∩ barrel_set|` for barrel; grep-verified count for scalar/stack)
-- `missing` / `missingCount` — source names not documented (barrel enumerates the names; scalar/stack give only the residual count)
+- `documented` — the numerator (`|documented_set ∩ barrel_set|` for barrel; grep-verified count for scalar/stack). This is always the true count, never capped.
+- `missing` / `missingCount` — source names not documented (barrel enumerates the names; scalar/stack give only the residual count). Never negative.
 - `stale` / `staleCount` — documented names not in source (barrel only; empty with `staleApplicable: false` for scalar/stack)
 - `denominator` — `|barrel_set|` (barrel) or the resolved scalar/stack denominator
-- `exportCoverage` — `documented / denominator * 100`, already rounded
+- `exportCoverage` — `documented / denominator * 100`, already rounded; capped at 100 on the scalar/stack branches
+- `numeratorSurplus` / `coverageUncapped` / `coverageCapped` — scalar/stack only; see the surplus note below
+
+**Surplus on the grep branches.** The scalar and stack branches grep a name set against the skill body, so their numerator and denominator measure independent sets and `documented` can exceed `denominator` — a consumer-surface denominator counts one surface while the documented body may also name migration aliases or re-exported sibling symbols. When that happens the script reports `numeratorSurplus > 0` and `coverageCapped: true`, holds `exportCoverage` at 100, floors `missingCount` at 0, and preserves the raw ratio in `coverageUncapped`. **A surplus is a signal, not a pass:** it means the two sets disagree, so state it in the Coverage Analysis section (§5) alongside both counts. A large surplus on a skill whose brief carries no `scope.tier_a_include` is the deflated-denominator signature the `source-access-protocol.md` deflation guard describes — check that guard before accepting the 100.
 
 Carry these into §3's table/summary and §4's Export Coverage, and record the counts in the Coverage Analysis section (§5) so the numerator is auditable. The `exportCoverage` recorded here is the value step 5 feeds to `compute-score.py` — it is the script's value, not a parent estimate.
 
@@ -267,6 +270,8 @@ Aggregate findings across all source files:
 - Signature mismatches: {N}
 - Undocumented in SKILL.md but not in source (stale docs): `staleCount`
 
+When the script reports `coverageCapped: true`, add the surplus to the summary — `Documented (surplus over denominator): {numeratorSurplus}` and `Uncapped coverage: {coverageUncapped}%` — so the reader can see that `Missing documentation: 0` is a floored residual rather than a verified-complete surface.
+
 ### 4. Load Scoring Rules
 
 Load `{scoringRulesFile}` to determine category scores:
@@ -390,6 +395,7 @@ Append the **Coverage Analysis** section to `{outputFile}`:
 - **Missing Documentation:** {N}
 - **Signature Mismatches:** {N}
 - **Stale Documentation:** {N}
+- **Numerator Surplus:** {N} — omit this row unless `coverageCapped: true`; when present, also give the uncapped percentage
 
 ### Category Scores
 

package/src/skf-test-skill/references/score.md

@@ -123,7 +123,13 @@ Use these values for Section 4 (pass/fail/inconclusive) and Section 6 (output fo
 
 #### 3c. Fallback (if script execution fails)
 
-If the script is unavailable or errors, redistribute each skipped category's weight (the `null`-scored categories in the §3a JSON — naive mode already zeroes coherence, and Quick-tier/docsOnly/state2/stackSkill/referenceApp already null out Signature Accuracy + Type Coverage) proportionally across the active categories, then report `total = Σ(weight/100 × category_score)` using the detected mode's weight table in `{scoringRulesFile}`. Report: "**Note:** Scoring script unavailable — calculated manually per scoring-rules.md."
+**First distinguish "the script could not run" from "the script rejected the input" — they take opposite paths.**
+
+A `{"error": ..., "code": "INVALID_INPUT"}` envelope on stdout means the script ran fine and refused what it was given: a field is missing, mistyped, or out of range (exit 2), or the payload was not parseable JSON at all (exit 1). Either way the *input* is wrong, not the script. **Correct the §3a input and re-run.** Do not fall through to the manual redistribution below — it would hand-compute a total from the very numbers the script just refused, so an out-of-range `exportCoverage` would silently become a score. If the input cannot be corrected, report `score: scoring input rejected — {error}` and leave the score unset rather than emitting a computed total.
+
+The fallback below applies only when the script genuinely could not run — missing file, no `uv`, unreadable interpreter — that is, **no envelope on stdout at all**.
+
+If the script is unavailable, redistribute each skipped category's weight (the `null`-scored categories in the §3a JSON — naive mode already zeroes coherence, and Quick-tier/docsOnly/state2/stackSkill/referenceApp already null out Signature Accuracy + Type Coverage) proportionally across the active categories, then report `total = Σ(weight/100 × category_score)` using the detected mode's weight table in `{scoringRulesFile}`. Report: "**Note:** Scoring script unavailable — calculated manually per scoring-rules.md."
 
 ### 3d. Read Post-Score Caps (applied by the script)
 

package/src/skf-test-skill/scripts/aggregate-coherence.py

@@ -62,10 +62,14 @@ CLI usage (mirrors compute-score.py):
   uv run aggregate-coherence.py --json-input '<JSON>'     # explicit flag form
   cat input.json | uv run aggregate-coherence.py --stdin  # piped input
 
-Exit codes:
-  0  — input was parsed; either a result object or a schema-validation error
-       object ({"error": ..., "code": "INVALID_INPUT"}) was emitted as JSON
+Exit codes (same convention as compute-score.py / reconcile-coverage.py):
+  0  — a result object was emitted
   1  — input could not be parsed at all (no input provided, or malformed JSON)
+  2  — input parsed but schema/semantics invalid
+
+Both 1 and 2 emit an {"error": ..., "code": "INVALID_INPUT"} envelope on stdout,
+so the envelope's presence — not the specific code — tells a caller the input was
+refused rather than scored.
 """
 
 from __future__ import annotations
@@ -269,6 +273,12 @@ def main(argv: list[str] | None = None) -> int:
 
     result = aggregate_coherence(data)
     print(json.dumps(result, indent=2))
+    # Same convention as compute-score.py / reconcile-coverage.py. This script
+    # produces the coherence percentage that score.md §3a feeds to
+    # compute-score.py, so a silently-rejected run here would hand a bogus or
+    # absent number to the gate one layer downstream.
+    if isinstance(result, dict) and result.get("code") == "INVALID_INPUT":
+        return 2
     return 0
 
 

package/src/skf-test-skill/scripts/compute-score.py

@@ -39,11 +39,17 @@ Verdict override (post-score caps + threshold fallback — see compute_score):
   and `result` is the final verdict. `result` itself is never mutated — it is
   always the pre-cap/pre-fallback score-vs-threshold (or evidence-floor) verdict.
 
-Exit codes:
-  0  — input was parsed; either a score was computed (verdict may be
-       PASS/FAIL/INCONCLUSIVE) or a schema/validation error object
-       ({"error": ..., "code": "INVALID_INPUT"}) was emitted as JSON
+Exit codes (same convention as reconcile-coverage.py):
+  0  — a score was computed; the verdict may be PASS/FAIL/INCONCLUSIVE
   1  — input could not be parsed at all (no input provided, or malformed JSON)
+  2  — input parsed but schema/semantics invalid
+
+Both 1 and 2 emit an {"error": ..., "code": "INVALID_INPUT"} envelope on stdout,
+so the presence of that envelope — not the specific code — is what tells a caller
+the input was refused. A refused input is distinct from an unavailable script:
+the numbers handed in are wrong and must be fixed, NOT hand-computed into a total
+from the values this script declined to score. score.md §3c keys its
+manual-redistribution fallback on that distinction (no envelope at all).
 """
 
 from __future__ import annotations
@@ -508,6 +514,13 @@ def main(argv: list[str] | None = None) -> int:
 
     result = compute_score(data)
     print(json.dumps(result, indent=2))
+    # A rejected input exits 2, matching reconcile-coverage.py. Exiting 0 here
+    # made a malformed scoring input indistinguishable from a scored run, so the
+    # error envelope could be skimmed past and the score hand-computed from the
+    # very numbers the script refused. score.md §3c keys the manual-redistribution
+    # fallback on this distinction.
+    if isinstance(result, dict) and result.get("code") == "INVALID_INPUT":
+        return 2
     return 0
 
 

package/src/skf-test-skill/scripts/reconcile-coverage.py

@@ -22,15 +22,24 @@ It covers the three branches §2c enumerates:
   * "scalar"  (§4 priority-1 effective_denominator, no enumerated name set) —
     grep each documented name across SKILL.md ∪ references/*.md;
     Documented = count present, denominator = effective_denominator,
-    Missing = denominator − Documented, Stale not enumerable (empty),
-    Export Coverage = Documented / denominator * 100.
+    Missing = max(0, denominator − Documented), Stale not enumerable (empty),
+    Export Coverage = min(100, Documented / denominator * 100).
 
   * "stack"   (skill_type == "stack", empty source barrel) — grep each
     composition-surface name (provenance-map cited contracts, ::-excluded, or
     libraries + integration_pairs — resolved upstream) across
     SKILL.md ∪ references/*.md; denominator = stack_denominator,
-    Missing = denominator − Documented, Stale not enumerable,
-    Export Coverage = Documented / stack_denominator * 100.
+    Missing = max(0, denominator − Documented), Stale not enumerable,
+    Export Coverage = min(100, Documented / stack_denominator * 100).
+
+The two grep branches bound their outputs because the numerator and the
+denominator are independent measures of different sets — the grep count can
+exceed a consumer-surface denominator without either being wrong. Unbounded,
+that produced a negative Missing and a >100% coverage that compute-score.py
+rejects as out of range. `documented` is left as the true count (it is reported
+verbatim as "Documented in SKILL.md"); the derived ratio is what gets bounded,
+and `numeratorSurplus` / `coverageUncapped` / `coverageCapped` report the
+overshoot so a deflated denominator stays visible instead of being swallowed.
 
 CLI usage:
   uv run reconcile-coverage.py '<JSON>'                  # JSON literal positional
@@ -55,11 +64,14 @@ Output (stdout, one object):
     "denominator": <int>,
     "documented": <int>,
     "missing": [names],          # enumerated: source names not documented; scalar/stack: []
-    "missingCount": <int>,       # always present
+    "missingCount": <int>,       # always present; never negative
     "stale": [names],            # enumerated: documented names not in source; scalar/stack: []
     "staleCount": <int>,         # always present
     "staleApplicable": <bool>,   # false for scalar/stack (no barrel to enumerate)
-    "exportCoverage": <float>
+    "exportCoverage": <float>,   # scalar/stack: capped at 100
+    "numeratorSurplus": <int>,   # scalar/stack only: max(0, documented − denominator)
+    "coverageUncapped": <float>, # scalar/stack only: the ratio before the cap
+    "coverageCapped": <bool>     # scalar/stack only: true when the cap bound the ratio
   }
 
 Exit codes:
@@ -232,18 +244,33 @@ def reconcile(inp, doc_text=None):
             "upstream §2b guard should HALT before reconciliation"
         )
 
-    missing_count = denominator - documented
+    # The grep numerator and the resolved denominator are independent measures,
+    # so `documented` can legitimately exceed `denominator` — a consumer-surface
+    # denominator counts one surface while the documented body may also name
+    # migration aliases, re-exported sibling symbols, and other extras. Left
+    # unbounded that yields a negative Missing and >100% coverage (which
+    # compute-score.py then rejects outright as out of range).
+    #
+    # `documented` stays the true grep count: it is reported as "Documented in
+    # SKILL.md", so capping it would print a number that was never measured.
+    # The derived ratio is what gets bounded, and the surplus is surfaced rather
+    # than swallowed so a deflated denominator stays visible.
+    surplus = max(0, documented - denominator)
+    coverage_uncapped = round2(documented / denominator * 100)
     return {
         "branch": source,
         "denominatorSource": source,
         "denominator": denominator,
         "documented": documented,
         "missing": [],
-        "missingCount": missing_count,
+        "missingCount": max(0, denominator - documented),
+        "numeratorSurplus": surplus,
         "stale": [],
         "staleCount": 0,
         "staleApplicable": False,
-        "exportCoverage": round2(documented / denominator * 100),
+        "exportCoverage": min(100.0, coverage_uncapped),
+        "coverageUncapped": coverage_uncapped,
+        "coverageCapped": surplus > 0,
     }
 
 

package/tools/cli/lib/installer.js

@@ -205,10 +205,39 @@ class Installer {
     }
   }
 
+  /**
+   * Read the health_check_repo default from src/module.yaml (single source of truth).
+   */
+  async readHealthCheckRepoDefault() {
+    try {
+      const moduleData = yaml.load(await fs.readFile(path.join(this.srcDir, 'module.yaml'), 'utf8'));
+      const value = moduleData && moduleData.health_check_repo && moduleData.health_check_repo.default;
+      if (typeof value === 'string' && value.length > 0) return value;
+    } catch {
+      /* fall through to literal fallback */
+    }
+    return 'armelhbobdad/bmad-module-skill-forge';
+  }
+
   async writeConfig(skfDir, config) {
     // On update, restore the user's existing config
     if (config._savedConfigYaml) {
-      await fs.writeFile(path.join(skfDir, 'config.yaml'), config._savedConfigYaml, 'utf8');
+      let savedYaml = config._savedConfigYaml;
+      try {
+        // Inject health_check_repo into configs generated before it existed.
+        // Append one line instead of re-dumping so user comments/ordering survive.
+        // Only mapping-shaped (or empty/comments-only) docs are appendable —
+        // appending a key to an array or scalar doc would corrupt the YAML.
+        const savedData = yaml.load(savedYaml);
+        const isPlainObject = typeof savedData === 'object' && savedData !== null && !Array.isArray(savedData);
+        if (savedData == null || (isPlainObject && !('health_check_repo' in savedData))) {
+          const suffix = savedYaml.endsWith('\n') ? '' : '\n';
+          savedYaml = `${savedYaml}${suffix}health_check_repo: ${await this.readHealthCheckRepoDefault()}\n`;
+        }
+      } catch {
+        /* unparseable saved config — restore verbatim */
+      }
+      await fs.writeFile(path.join(skfDir, 'config.yaml'), savedYaml, 'utf8');
       return;
     }
 
@@ -232,6 +261,7 @@ class Installer {
       forge_data_folder: config.forge_data_folder || 'forge-data',
       sidecar_path: '_bmad/_memory/forger-sidecar',
       skf_folder: config.skfFolder,
+      health_check_repo: await this.readHealthCheckRepoDefault(),
       ides: config.ides || [],
       install_learning: config.install_learning !== false,
     };