bmad-module-skill-forge 7.0.0 → 8.0.0

package/src/shared/scripts/schemas/skf-test-result-envelope.v1.json

@@ -130,7 +130,7 @@
     "result_path": {
       "type": ["string", "null"],
       "minLength": 1,
-      "description": "The per-run result file the emitter wrote in the version folder, skf-test-skill-result-<YYYYMMDD-HHmmss>.json (UTC; -2, -3 appended when a run took that second's name), beside its skf-test-skill-result-latest.json copy. Stamped by the emitter, never typed. Null on a halt, which writes no result file, and when the write failed (warnings say why)."
+      "description": "The per-run result file the emitter wrote in the version folder, skf-test-skill-result-<YYYYMMDD-HHmmss>.json (UTC; -2, -3 appended when a run took that second's name), beside its skf-test-skill-result-latest.json copy. Stamped by the emitter, never typed. Null on a halt, which writes no result file, when --result-dir names no folder (nothing is written, and no warning is added), and when the per-run record could not be written (a result_file_write_failed warning says why); a -latest copy that could not be written leaves it set, and a result_file_write_failed warning names the copy."
     },
     "threshold_fallback": {
       "type": "boolean",

package/src/shared/scripts/schemas/skf-update-result-envelope.v1.json

@@ -50,7 +50,7 @@
             "halted-for-concurrent-run",
             "blocked"
           ],
-          "description": "Single-field outcome for pipeline branching. 'success' when the run completed and wrote the updated artifacts. 'no-changes' when detect-changes found nothing to update. 'detect-only' when the workflow was invoked with --detect-only and exited after step 2 without modifying any artifact. 'dry-run' when the workflow was invoked with --dry-run and exited after step 3 (re-extract) without merging or writing: the envelope describes what merge+write WOULD have done. Each 'halted-for-*' value corresponds to a documented halt in the stage prose (workspace-drift from gap-driven.md §3, brief-refinement from detect-changes.md §1c [U] / §2.2 [B], audit from §2.2 [A], remediation-path from gap-driven.md §4a, manual-mismatch from write.md §1, after write.md §6's provenance fixes and after write.md §7's skill-check edits (all error.phase 'write:verify-manual-integrity'), from merge.md §6b's check of the merged SKILL.md before it is published (error.phase 'merge:verify-manual-integrity') and from a headless merge that meets a [MANUAL] conflict (error.phase 'merge:conflict-resolution'), write-failure for a merge.md §6b version-folder or SKILL.md write failure (among them error.phase 'merge:new-version-folder' when the version folder already exists or the next version cannot be computed), a failed write in write.md §2 to §5 (error.phase 'write:artifact-write') and a write.md §8/§8a active-link failure, concurrent-run when init.md §1b's acquire finds another run's fresh run lock (error.phase 'init:concurrency-guard'), or when this run no longer holds its lock at the renewal before merge.md §6b or write.md §2 writes (error.phase 'merge:run-lock' or 'write:run-lock'; error.reason 'run-lock-lost: ...' when the lock lapsed while the run waited), or when write.md §8 finds another flip of the active link holding its lock for 5 s (error.phase 'write:active-symlink', error.reason 'busy: ...'). error.reason names the run that holds a run lock, never a PID). 'blocked' is the catch-all for halts that don't map to a documented status code, among them a headless run given no skill name (error.phase 'init:skill-name', error.reason starting 'input-missing'), a stack skill (error.phase 'init:stack-skill-guard'), init.md §6b (error.phase 'init:source-tree') when no commit to read could be obtained, a helper that failed (each its own '<step>:<section>' phase), write.md §7's body split (error.phase 'write:body-split': skf-shard-body.py exited 1 or 2 or printed no JSON, or reported a Tier 1 heading pulled or a cross-reference that does not resolve), and a private source tree that disappeared mid-run (error.phase '<step>:source-tree-missing'). A halt after merge.md §6b's first write, until write.md §10 closes the rollback window, first undoes it: a gap-driven repair's package is restored from the snapshot it took, and a new version's folders are removed, unless the active link already names the new version, which the halt keeps. write.md §8 points the active link at the new version only after §6 and §7, the last checks that can halt, so a [MANUAL] halt never leaves a live version behind. NOTE: detect-only and dry-run are successful exits: pipelines treating non-success as failure must include them in the success set."
+          "description": "Single-field outcome for pipeline branching. 'success' when the run completed and wrote the updated artifacts. 'no-changes' when detect-changes found nothing to update. 'detect-only' when the workflow was invoked with --detect-only and exited after step 2 without modifying any artifact. 'dry-run' when the workflow was invoked with --dry-run and exited after step 3 (re-extract) without merging or writing: the envelope describes what merge+write WOULD have done. Each 'halted-for-*' value corresponds to a documented halt in the stage prose (workspace-drift from gap-driven.md §3, brief-refinement from detect-changes.md §1c [U] / §2.2 [B], audit from §2.2 [A], remediation-path from gap-driven.md §4a, manual-mismatch from write.md §1, after write.md §6's provenance fixes and after write.md §7's skill-check edits (all error.phase 'write:verify-manual-integrity'), from merge.md §6b's check of the merged SKILL.md before it is published (error.phase 'merge:verify-manual-integrity') and from a headless merge that meets a [MANUAL] conflict (error.phase 'merge:conflict-resolution'), write-failure for a merge.md §6b version-folder or SKILL.md write failure (among them error.phase 'merge:new-version-folder' when the version folder already exists or the next version cannot be computed), a failed write in write.md §2 to §5 (error.phase 'write:artifact-write') and a write.md §8/§8a active-link failure, and a headless result contract report.md §5b could not write (error.phase 'report:result-contract', printed after the run's last write, so nothing is undone), concurrent-run when init.md §1b's acquire finds another run's fresh run lock (error.phase 'init:concurrency-guard'), or when this run no longer holds its lock at the renewal before merge.md §6b or write.md §2 writes (error.phase 'merge:run-lock' or 'write:run-lock'; error.reason 'run-lock-lost: ...' when the lock lapsed while the run waited), or when write.md §8 finds another flip of the active link holding its lock for 5 s (error.phase 'write:active-symlink', error.reason 'busy: ...'). error.reason names the run that holds a run lock, never a PID). 'blocked' is the catch-all for halts that don't map to a documented status code, among them a headless run given no skill name (error.phase 'init:skill-name', error.reason starting 'input-missing'), a stack skill (error.phase 'init:stack-skill-guard'), init.md §6b (error.phase 'init:source-tree') when no commit to read could be obtained, a helper that failed (each its own '<step>:<section>' phase), write.md §7's body split (error.phase 'write:body-split': skf-shard-body.py exited 1 or 2 or printed no JSON, or reported a Tier 1 heading pulled or a cross-reference that does not resolve), and a private source tree that disappeared mid-run (error.phase '<step>:source-tree-missing'). A halt after merge.md §6b's first write, until write.md §10 closes the rollback window, first undoes it: a gap-driven repair's package is restored from the snapshot it took, and a new version's folders are removed, unless the active link already names the new version, which the halt keeps. write.md §8 points the active link at the new version only after §6 and §7, the last checks that can halt, so a [MANUAL] halt never leaves a live version behind. NOTE: detect-only and dry-run are successful exits: pipelines treating non-success as failure must include them in the success set."
         },
         "skill_name": {
           "type": "string",
@@ -89,6 +89,11 @@
           "uniqueItems": true,
           "description": "Artifacts actually written or updated this run. 'references' stands for one or more references/*.md files of the skill package written, added or removed (merge.md §6b's merge, at any priority, write.md §6's provenance fixes or write.md §7's body split), one value however many. Empty array when a halt fired before any write completed."
         },
+        "security_result": {
+          "type": "string",
+          "enum": ["pass", "warn", "skipped"],
+          "description": "The outcome of write.md §7's security scan, from the Security row of this update's Validation Summary in the evidence report (PASS as 'pass', WARN as 'warn', SKIP as 'skipped'), and the value follows that row. 'pass': the scan exited 0 and skill-check reported no finding, which does not show that the scan found nothing. 'warn': it reported findings. 'skipped': it did not run (skill-check unavailable, or the scan could not run, such as without SNYK_TOKEN). Absent on 'no-changes', 'detect-only' and 'dry-run', which run no scan, at every halt, and when that row is missing or starts with another word."
+        },
         "headless_decisions": {
           "type": "array",
           "items": {
@@ -136,7 +141,7 @@
         "warnings": {
           "type": "array",
           "items": { "type": "string" },
-          "description": "Non-fatal anomalies surfaced during the run. May include workspace_drift_overridden, scope_reconciliation_post entries, qmd indexing failures, source-tree:, source-not-fetched, source-version-lower, file-diff-unavailable, no-baseline-time, moved-check-skipped and unknown-language (detect-changes.md §2.1 Category A), new-files-not-checked (Category D: a skill with no brief, so no new script or asset was looked for), workspace-clone-not-updated, target-ref-not-recorded, source-tree-not-removed, run-lock-replaced (init.md §1b took over a stale run lock) and run-lock-not-released entries, unconsumed-test-report (init.md §4b: a failing test report newer than the skill that this normal run did not apply), interrupted-run-cleaned and interrupted-run-not-cleaned (init.md §1b undid what an update whose stale lock it replaced had written), proposed-amendment: entries (a --detect-only or --dry-run run's skill brief decisions, not written), doc-fetch-failed, doc-not-hashed and doc-drift-not-checked (a docs-only skill's documents), rollback-incomplete (a halt could not undo all of this run's writes), run-state-not-finished, public-api-counted-by-hand: entries (write.md §2: the recipe runner exited 2, so the public names were found without it; each quotes the runner's error line), customization_resolver_unavailable, test-report: entries (what the test report helpers could not read, and test-report: not routed: for each gap a gap-driven run does not repair), etc. Empty when none."
+          "description": "Non-fatal anomalies surfaced during the run. May include workspace_drift_overridden, scope_reconciliation_post entries, qmd indexing failures, source-tree:, source-not-fetched, source-version-lower, file-diff-unavailable, no-baseline-time, moved-check-skipped and unknown-language (detect-changes.md §2.1 Category A), new-files-not-checked (Category D: a skill with no brief, so no new script or asset was looked for), workspace-clone-not-updated, target-ref-not-recorded, source-tree-not-removed, run-lock-replaced (init.md §1b took over a stale run lock) and run-lock-not-released entries, unconsumed-test-report (init.md §4b: a failing test report newer than the skill that this normal run did not apply), interrupted-run-cleaned and interrupted-run-not-cleaned (init.md §1b undid what an update whose stale lock it replaced had written), proposed-amendment: entries (a --detect-only or --dry-run run's skill brief decisions, not written), doc-fetch-failed, doc-not-hashed and doc-drift-not-checked (a docs-only skill's documents), rollback-incomplete (a halt could not undo all of this run's writes), run-state-not-finished, public-api-counted-by-hand: entries (write.md §2: the recipe runner exited 2, so the public names were found without it; each quotes the runner's error line), customization_resolver_unavailable, test-report: entries (what the test report helpers could not read, and test-report: not routed: for each gap a gap-driven run does not repair), result_file_write_failed (a result file not written, or a version forge folder not created), etc. Empty when none."
         },
         "error": {
           "oneOf": [

package/src/shared/scripts/schemas/skf-verify-stack-result-envelope.v1.json

@@ -111,7 +111,7 @@
     "result_path": {
       "type": ["string", "null"],
       "minLength": 1,
-      "description": "The per-run result file the emitter wrote in the forge data folder, verify-stack-result-<YYYYMMDD-HHmmss>.json, named after the run's own stamp (its run_id, the stamp the timestamped report's file name carries; -2, -3, ... appended when a run already took the name), beside its verify-stack-result-latest.json copy. Stamped by the emitter, never typed. Null on every halt, which writes no result file, and when the write failed (warnings say why)."
+      "description": "The per-run result file the emitter wrote in the forge data folder, verify-stack-result-<YYYYMMDD-HHmmss>.json, named after the run's own stamp (its run_id, the stamp the timestamped report's file name carries; -2, -3, ... appended when a run already took the name), beside its verify-stack-result-latest.json copy. Stamped by the emitter, never typed. Null on every halt, which writes no result file, when --result-dir names no folder (nothing is written, and no warning is added), and when the per-run record could not be written (a result_file_write_failed warning says why); a -latest copy that could not be written leaves it set, and a result_file_write_failed warning names the copy."
     },
     "headless_decisions": {
       "type": "array",

package/src/shared/scripts/skf-parse-gaps.py

@@ -1023,7 +1023,10 @@ NOT_ROUTED_REASONS = {
     "provenance-unverified": (
         "the line-check rules could not verify the line, or the recorded line is not a number, so a person checks "
         "by hand which line defines the export and, when it is not the recorded one, sets its provenance "
-        "`source_line` to that line"),
+        "`source_line` to that line; when the gap names an alias, no line of the cited file defines the export, so "
+        "a person records the rename in its provenance entry (`export_name` the name the alias renames, "
+        "`reexported_as` the export) only when no other entry has that `export_name` and the alias does not "
+        "rename a default export, and otherwise cites the alias line, as the remediation says"),
     "denominator-inflation": (
         "it concerns the brief's scope and the count design, which a person decides in the skill brief, as the "
         "gap's remediation says"),

package/src/shared/scripts/skf-quick-batch.py

@@ -123,7 +123,9 @@ summarize
   stderr, on stdout otherwise): {"batch_summary": true, "targets_total",
   "succeeded", "failed", "status", "fail_fast_triggered", "exit_code",
   "summary_path"}, with "warnings" when a summary file could not be
-  written. A batch already summarized prints its event again.
+  written, and "batch_file", the path of the run folder's batch.jsonl,
+  when summary_path is null. A batch already summarized prints its event
+  again.
   The batch's result is that event and the file its summary_path names
   (with summary_path null, when the per-batch file could not be written,
   the event and batch.jsonl; a summary_write_failed warning beside a set
@@ -625,13 +627,15 @@ def _write_json(path: Path, value: dict) -> None:
         raise
 
 
-def summary_event(summary: dict) -> dict:
+def summary_event(summary: dict, run_dir: Path) -> dict:
     event = {"batch_summary": True}
     for key in ("targets_total", "succeeded", "failed", "status", "fail_fast_triggered", "exit_code",
                 "summary_path"):
         event[key] = summary.get(key)
     if summary.get("warnings"):
         event["warnings"] = summary["warnings"]
+    if summary.get("summary_path") is None:
+        event["batch_file"] = (run_dir / BATCH_FILE).as_posix()  # no summary file: batch.jsonl holds the results
     return event
 
 
@@ -648,7 +652,7 @@ def cmd_summarize(run_dir: Path, output_dir: Path) -> dict:
     state = load(run_dir)
     name = workflow(state)
     if state["summary"] is not None:
-        return summary_event(state["summary"])
+        return summary_event(state["summary"], run_dir)
     left, stopped = pending(state), _stop_early(state)
     if left and not stopped:
         raise BatchError(f"{len(left)} target(s) of the batch are still pending: run next and finish "
@@ -692,7 +696,7 @@ def cmd_summarize(run_dir: Path, output_dir: Path) -> dict:
     inside = output_dir.resolve().is_relative_to(run_dir.resolve())
     if not failed and summary_path is not None and not inside and run_dir.name.startswith(f"{name}-"):
         _remove_tree(run_dir)  # kept when a target halted, or when batch.jsonl is the only record
-    return summary_event(final)
+    return summary_event(final, run_dir)
 
 
 # ─── CLI ─────────────────────────────────────────────────────────────────────