bmad-module-skill-forge 2.0.2 → 2.2.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/src/skf-update-skill/references/write.md

@@ -65,7 +65,7 @@ Verify the merged SKILL.md that step 4 section 6b wrote to disk, then write the
 
 **Used by:** §7 (`skill-check check --fix` and `skill-check split-body --write`), and any future tool invocation that may modify SKILL.md's frontmatter on disk.
 
-Load `{descriptionGuardProtocol}` for the full prose explanation of the four-phase guard (why it exists, what counts as divergence, why token-stream comparison is the right shape). The deterministic phases are executed via `{descriptionGuardHelper}` — §7 invokes the helper at the capture and verify-restore points around every `skill-check` call.
+Load `{descriptionGuardProtocol}` for the full prose explanation of the four-phase guard (why it exists, what counts as divergence, why token-stream comparison is the right shape). The deterministic phases are executed via `{descriptionGuardHelper}` — §7 invokes the helper at the capture and verify-restore points around every `skill-check` call. `verify-restore` refuses an empty `--captured-description` (exit 1, file untouched); when that happens, follow the protocol's empty-snapshot rule instead of re-running with the empty value.
 
 Update-skill does not run the optional post-restore frontmatter re-validation today — the post-write checks in §1 catch downstream issues, and a `restored: true` outcome is already surfaced through the evidence report (§4).
 
@@ -203,7 +203,7 @@ Append update operation section to `{forge_version}/evidence-report.md` (create
 - Notes: {one-sentence detail or —}
 ```
 
-**Description Guard population** (used by §7 Post-Write Validation when the §0 protocol fires): fill all four fields from context when `description_guard_restored == true` (triggering tool, whether restore succeeded, what changed). When `Restored: false`, the other three fields are `—` — this is the clean-run expected state. Same field semantics and populator logic as create-skill step 6 §8.
+**Description Guard population** (used by §7 Post-Write Validation when the §0 protocol fires): fill all four fields from context when `description_guard_restored == true` (triggering tool, whether restore succeeded, what changed). When `Restored: false`, the other three fields are `—` — this is the clean-run expected state — except when `description_guard_refused == "empty-capture"` (the §0 protocol's empty-snapshot rule): then set `Triggering tool` to the recorded tool name, `Original description preserved: false`, and `Notes: guard refused — empty captured snapshot (empty-capture)`, so a refused restore is distinguishable from a run where the guard never fired. Same field semantics and populator logic as create-skill step 6 §8.
 
 **Context Snippet population** (used by §5 after the staleness check runs): §4 writes the sub-block with placeholders; §5 updates the on-disk evidence report in place after deciding whether to regenerate. Set `Regenerated: true` and populate `Triggers fired` with any combination of `headline-exports`, `version`, `gotchas` when at least one trigger fired. Set `Regenerated: false` and `Triggers fired: —` when none fired (the gap-driven / internals-only outcome). Always fill `Notes` with a one-sentence reason (e.g., `"Gap-driven repair — no snippet surface changed"`, `"Version bumped 0.1.0 → 0.2.0; headline exports re-ranked"`).
 

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