bmad-module-skill-forge 2.0.2 → 2.1.0

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,
     };