bmad-module-skill-forge 2.2.0 → 4.0.0

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

@@ -0,0 +1,192 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-audit-result-envelope.v1.json",
+  "title": "SKF_AUDIT_RESULT_JSON envelope (v1)",
+  "description": "Single-line JSON document skf-audit-skill emits when {headless_mode} is true, prefixed with the literal 'SKF_AUDIT_RESULT_JSON: ': once on stdout when step 6 (report) finishes, which the health check displays as the run's last line, and once on stderr at every HARD HALT (status error). The shared emitter, skf-emit-result-envelope.py, builds every line from the payload a stage stages in the run folder, folds in the auto-decisions and warnings the run recorded there, derives exit_code from halt_reason, stamps run_id and result_path, writes the result files on success, and checks the line against this schema, so the model never types it. The skill's references/headless-contract.md holds the exit-code table and its stage files show the halt command.",
+  "$defs": {
+    "skf-envelope": {
+      "description": "The shared emitter's settings for this workflow, read by skf-emit-result-envelope.py: the workflow, the line's prefix, the wrapper, the status a halt carries, the exit code of each halt_reason and the result file stem. Nothing in the schema references this entry, so it constrains no envelope.",
+      "const": {
+        "workflow": "skf-audit-skill",
+        "prefix": "SKF_AUDIT_RESULT_JSON",
+        "wrapper": null,
+        "halt_status": "error",
+        "exit_codes": {
+          "input-missing": 2,
+          "skill-not-found": 3,
+          "not-skf-output": 3,
+          "forge-tier-missing": 3,
+          "no-baseline": 3,
+          "source-dir-missing": 3,
+          "provenance-invalid": 3,
+          "source-unreadable": 3,
+          "helper-missing": 3,
+          "write-failed": 4,
+          "user-cancelled": 6
+        },
+        "success_exit_code": 0,
+        "result_file": "audit-skill-result"
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "status",
+    "skill_name",
+    "drift_score",
+    "report_path",
+    "next_workflow",
+    "audit_ref",
+    "upstream_moved",
+    "upstream_ref",
+    "exit_code",
+    "halt_reason",
+    "run_id",
+    "result_path"
+  ],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["success", "error"],
+      "description": "'success' when step 6 wrote the drift report and its result contract. 'error' on any HARD HALT."
+    },
+    "skill_name": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "default": null,
+      "description": "The audited skill. Null when the run halted before one was named (input-missing)."
+    },
+    "drift_score": {
+      "type": ["string", "null"],
+      "enum": ["CLEAN", "MINOR", "SIGNIFICANT", "CRITICAL", null],
+      "default": null,
+      "description": "The drift_score skf-severity-classify.py saved in step 5's severity.json. Null when the run halted before severity classification."
+    },
+    "report_path": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "default": null,
+      "description": "The drift report, drift-report-<timestamp>.md in the audited version's forge folder. Null when the run halted before step 1 wrote it, or when the report write failed."
+    },
+    "next_workflow": {
+      "type": ["string", "null"],
+      "enum": ["update-skill", null],
+      "default": null,
+      "description": "'update-skill' when the classification counts a CRITICAL or HIGH finding, or when upstream_moved is true (the skill is built from an older ref than the remote now names), so a maintain pipeline reaches update-skill after an upstream release; null otherwise and on a halt."
+    },
+    "audit_ref": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "default": null,
+      "description": "The ref the audit read: the baseline ref when it stayed on the baseline, the upstream ref when step 1's upstream-drift gate chose [C] and the run read that ref from a private source tree. Null before step 1 decided it."
+    },
+    "upstream_moved": {
+      "type": ["boolean", "null"],
+      "default": null,
+      "description": "True when step 1's one skf-check-workspace-drift.py upstream call found that the remote moved past the commit and ref the skill was built from (status moved), false when it found them unchanged, null when the check was skipped (no git source, no baseline commit or ref, a stack skill, a docs-only skill) or could not reach the remote."
+    },
+    "upstream_ref": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "default": null,
+      "description": "When upstream_moved is true, the ref the remote moved to (the newer tag, the moved tag or branch, or 'HEAD' for the default branch): pass it to update-skill as --target-ref. Null otherwise."
+    },
+    "exit_code": {
+      "type": "integer",
+      "enum": [0, 2, 3, 4, 6],
+      "description": "Process exit code matching the Exit Codes table of the skill's references/headless-contract.md, derived from halt_reason: null gives 0, input-missing 2, skill-not-found, not-skf-output, forge-tier-missing, no-baseline, source-dir-missing, provenance-invalid, source-unreadable and helper-missing 3, write-failed 4, user-cancelled 6."
+    },
+    "halt_reason": {
+      "type": ["string", "null"],
+      "enum": [
+        null,
+        "input-missing",
+        "skill-not-found",
+        "not-skf-output",
+        "forge-tier-missing",
+        "no-baseline",
+        "source-dir-missing",
+        "provenance-invalid",
+        "source-unreadable",
+        "helper-missing",
+        "write-failed",
+        "user-cancelled"
+      ],
+      "description": "Null on success. One of the documented HALT classes on error, so a pipeline branches on the failure class without parsing the prose message."
+    },
+    "run_id": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "description": "The run's id, stamped by the emitter from the run folder name: the run's timestamp (YYYYMMDD-HHmmss), the stamp the drift report's file name carries. Null for a halt before the run folder exists."
+    },
+    "result_path": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "description": "The per-run result file the emitter wrote in the audited version's forge folder, audit-skill-result-<YYYYMMDD-HHmmss>.json (UTC), beside its audit-skill-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)."
+    },
+    "headless_decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["gate", "default_action", "taken_action", "reason"],
+        "properties": {
+          "gate": {
+            "type": "string",
+            "enum": ["init.manifest-lags-link", "init.upstream-drift", "init.baseline-confirm"],
+            "description": "The gate that auto-resolved: step 1's manifest-vs-link gate, its upstream-drift gate, or its baseline confirm gate (init.baseline-confirm), which a run reaches only on a baseline doubt: the forge tier below the compile tier, or a provenance map more than 90 days old. Each records its decision in the run sink the moment it decides."
+          },
+          "default_action": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The action documented as the gate's default: 'N' (audit the link's version) or 'C' (audit the upstream ref, or continue past the baseline doubt)."
+          },
+          "taken_action": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The action the run took: the default, or the pre-supplied upstream_drift_choice ('C', 'S' or 'X')."
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Human-readable rationale, such as 'headless: upstream moved v1.2.0 -> v1.3.0; auditing v1.3.0'."
+          },
+          "evidence": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Optional gate-specific data, such as the baseline and upstream refs."
+          }
+        }
+      },
+      "description": "Optional. One entry per gate that auto-resolved during the run, read from the run sink, so a halt reports the decisions taken before it. Present only when there is at least one."
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Optional. Non-fatal anomalies the run recorded in its sink or the emitter raised, one string each, starting with its code: upstream_tree_unavailable when [C] could not read the upstream ref into a private tree and the audit stayed on the baseline, source_tree_not_removed when the private tree could not be removed, recipe_runner_failed (with the recipe runner's error line) when the runner left no JSON and named an error on stderr, so re-index extracted without it, public_surface_not_applied (with the rule's problem) when re-index could read no public surface for a public-api skill (Quick tier, a runner that could not run, an incomplete run, one with errors, or an entry point it could not trace), so structural diff reported every export the provenance map does not hold as added, doc_fetch_failed and doc_not_hashed (each with its count) when a docs-only skill's score leaves out documents that could not be fetched or have no recorded hash, new_files_not_checked (with the reason) when the Script/Asset Drift check looked for no new script, asset or document because the skill has no brief it could read or a helper it needs could not be loaded, customization_resolver_unavailable when the customization resolver failed and only the bundled customize.toml applied, and result_file_write_failed when a result file could not be written. Present only when there is at least one."
+    },
+    "error": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["phase", "reason"],
+      "properties": {
+        "phase": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Where the run halted: the step and gate, for example 'init:skill-path' or 'report:write'."
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The halt message the step displayed, on one line."
+        },
+        "path": {
+          "type": "string",
+          "description": "Optional path the failed operation targeted."
+        }
+      },
+      "description": "Present on a HARD HALT only: where the run stopped and why. Pipelines branch on halt_reason and read error for the diagnostic."
+    }
+  }
+}

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

@@ -2,7 +2,30 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-brief-result-envelope.v1.json",
   "title": "SKF_BRIEF_RESULT_JSON envelope (v1)",
-  "description": "Single-line JSON document emitted by skf-brief-skill step 5 §4b when {headless_mode} is true, prefixed with the literal 'SKF_BRIEF_RESULT_JSON: '. Pipelines grep one line out of the workflow log to branch on the brief outcome without parsing prose. Schema mirrors the contract in src/skf-brief-skill/SKILL.md Result Contract section.",
+  "description": "Single-line JSON document skf-brief-skill prints when {headless_mode} is true or the run is in [auto] mode, at the end of a successful run and at every HARD HALT, prefixed with the literal 'SKF_BRIEF_RESULT_JSON: '. Pipelines grep one line out of the workflow log to branch on the brief outcome without parsing prose. Schema mirrors the contract in src/skf-brief-skill/references/invocation-contract.md (Result Contract).",
+  "$defs": {
+    "skf-envelope": {
+      "description": "The shared emitter's settings for this workflow, read by skf-emit-result-envelope.py: the workflow, the line's prefix, the wrapper, the status a halt carries, the exit code of each halt_reason and the result file stem. Nothing in the schema references this entry, so it constrains no envelope.",
+      "const": {
+        "workflow": "skf-brief-skill",
+        "prefix": "SKF_BRIEF_RESULT_JSON",
+        "wrapper": null,
+        "halt_status": "error",
+        "exit_codes": {
+          "input-missing": 2,
+          "input-invalid": 2,
+          "forge-tier-missing": 3,
+          "target-inaccessible": 3,
+          "gh-auth-failed": 3,
+          "write-failed": 4,
+          "overwrite-cancelled": 5,
+          "user-cancelled": 6
+        },
+        "success_exit_code": 0,
+        "result_file": null
+      }
+    }
+  },
   "type": "object",
   "additionalProperties": false,
   "required": ["status", "brief_path", "skill_name", "version", "language", "scope_type", "exit_code", "halt_reason", "mode"],
@@ -10,7 +33,7 @@
     "status": {
       "type": "string",
       "enum": ["success", "error"],
-      "description": "'success' on the terminal happy path (after step 5 wrote the brief and step 6 returned). 'error' on any HARD HALT."
+      "description": "'success' once the run has written the brief (step 5) or, in [auto] mode, the user or a headless run approved it (step 1b). 'error' on any HARD HALT."
     },
     "brief_path": {
       "type": ["string", "null"],
@@ -19,7 +42,7 @@
     "skill_name": {
       "type": "string",
       "minLength": 1,
-      "description": "Brief's skill_name field — present in every envelope (success and error) since it is captured at step 1 §6 before any of the other failure branches."
+      "description": "Brief's skill_name field, present in every envelope (success and error): the literal 'unknown' on a halt that fires before step 1 resolves the name."
     },
     "version": {
       "type": ["string", "null"],
@@ -37,7 +60,7 @@
     "exit_code": {
       "type": "integer",
       "enum": [0, 2, 3, 4, 5, 6],
-      "description": "Process exit code matching the SKILL.md Exit Codes table. Derived deterministically from halt_reason: null→0, input-missing/input-invalid→2, forge-tier-missing/target-inaccessible/gh-auth-failed→3, write-failed→4, overwrite-cancelled→5, user-cancelled→6."
+      "description": "Process exit code matching the Exit Codes table in src/skf-brief-skill/references/invocation-contract.md. Derived deterministically from halt_reason: null→0, input-missing/input-invalid→2, forge-tier-missing/target-inaccessible/gh-auth-failed→3, write-failed→4, overwrite-cancelled→5, user-cancelled→6."
     },
     "halt_reason": {
       "type": ["string", "null"],
@@ -58,6 +81,11 @@
       "type": ["string", "null"],
       "enum": ["auto", null],
       "description": "'auto' when BS was invoked with the [auto] bracket modifier (pipeline auto-brief generation). Null otherwise (interactive or headless-without-auto)."
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Optional. Non-fatal anomalies surfaced during the run, one string each, such as customization_resolver_unavailable when the customization resolver could not apply the _bmad/custom/ overrides. Present only when the run recorded at least one, so an envelope without warnings is unchanged."
     }
   }
 }

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

@@ -0,0 +1,174 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-campaign-result-envelope.v1.json",
+  "title": "SKF_CAMPAIGN_RESULT_JSON envelope (v1)",
+  "description": "Single-line JSON document skf-campaign emits when {headless_mode} is true, prefixed with the literal 'SKF_CAMPAIGN_RESULT_JSON: ': once at the end of a campaign (step 11, after its final state write and the on_complete hook), which the end-of-run health check displays as the run's last line, again as the last line of a headless resume that finds the campaign already complete, and once on stderr at every HARD HALT (status error). The shared emitter, skf-emit-result-envelope.py, builds every line from the payload the step stages (at the end, the context campaign-report.py writes; at a HARD HALT, the one campaign-state.py halt-payload prints), derives exit_code from halt_reason and checks the line against this schema, so the model never types it. This schema is the one definition of the envelope: the skill's references/campaign-contracts.md lists the exit codes and holds the halt command.",
+  "$defs": {
+    "skf-envelope": {
+      "description": "The shared emitter's settings for this workflow, read by skf-emit-result-envelope.py: the workflow, the line's prefix, the wrapper, the status a halt carries and the exit code of each halt_reason. Campaign writes no result file of its own (its state, report and decision log hold the record). Nothing in the schema references this entry, so it constrains no envelope.",
+      "const": {
+        "workflow": "skf-campaign",
+        "prefix": "SKF_CAMPAIGN_RESULT_JSON",
+        "wrapper": null,
+        "halt_status": "error",
+        "exit_codes": {
+          "invalid-input": 2,
+          "invalid-state": 3,
+          "circular-deps": 4,
+          "invalid-pin": 5,
+          "inaccessible-repo": 6,
+          "dependency-deadlock": 7,
+          "missing-brief": 8,
+          "corrupt-state": 9,
+          "report-failure": 10,
+          "export-cancelled": 11,
+          "user-cancelled": 12,
+          "dependency-blocked": 13
+        },
+        "success_exit_code": 0,
+        "result_file": null
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "status",
+    "exit_code",
+    "halt_reason",
+    "skills_completed",
+    "skills_failed",
+    "quality_scores",
+    "export_verdicts",
+    "skills_excluded",
+    "campaign_report_path",
+    "decision_log",
+    "duration"
+  ],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["success", "error"],
+      "description": "'success' when the campaign completed and its report was written. 'error' on any HARD HALT, and on the one degraded finish: a campaign that completed but whose report could not be generated (halt_reason report-failure, exit_code 10, campaign_report_path null), which keeps its state intact."
+    },
+    "exit_code": {
+      "type": "integer",
+      "enum": [0, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13],
+      "description": "The campaign's exit code, derived from halt_reason: null gives 0, invalid-input 2, invalid-state 3, circular-deps 4, invalid-pin 5, inaccessible-repo 6, dependency-deadlock 7, missing-brief 8, corrupt-state 9, report-failure 10, export-cancelled 11, user-cancelled 12, dependency-blocked 13."
+    },
+    "halt_reason": {
+      "type": ["string", "null"],
+      "enum": [
+        null,
+        "invalid-input",
+        "invalid-state",
+        "circular-deps",
+        "invalid-pin",
+        "inaccessible-repo",
+        "dependency-deadlock",
+        "missing-brief",
+        "corrupt-state",
+        "report-failure",
+        "export-cancelled",
+        "user-cancelled",
+        "dependency-blocked"
+      ],
+      "description": "Null on success. The Exit Codes meaning of the halt otherwise, so a pipeline branches on the failure class without parsing the message; report-failure is the degraded finish described under status."
+    },
+    "phase": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Present on a HARD HALT only: the kebab slug of the step where the campaign stopped, such as 'strategy' or 'skill-loop'."
+    },
+    "error": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["code", "message"],
+      "properties": {
+        "code": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The halt_reason."
+        },
+        "message": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The halt message the step displayed, on one line."
+        }
+      },
+      "description": "Present on a HARD HALT only: why the campaign stopped. Pipelines branch on halt_reason and read error for the diagnostic."
+    },
+    "skills_completed": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 0,
+      "description": "Skills whose status is completed: campaign-report.py's count at the end, campaign-state.py halt-payload's count at a HARD HALT (0 before the state exists)."
+    },
+    "skills_failed": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 0,
+      "description": "Skills whose status is failed, counted as skills_completed is."
+    },
+    "quality_scores": {
+      "type": "object",
+      "additionalProperties": true,
+      "default": {},
+      "description": "Each completed skill's recorded score, by skill name: test-skill's for a Tier A skill, the skill-check score quick-skill records for a Tier B skill. Empty on a HARD HALT."
+    },
+    "export_verdicts": {
+      "type": ["object", "null"],
+      "additionalProperties": true,
+      "default": null,
+      "description": "Each completed skill's quality-gate verdict at Export, by skill name: pass, fallback or fail. Null when the gate could not be applied, and on a HARD HALT."
+    },
+    "skills_excluded": {
+      "type": ["array", "null"],
+      "items": { "type": "string", "minLength": 1 },
+      "default": null,
+      "description": "The completed skills the gate kept from export (verdict fail), so a completed skill is not taken for an exported one. Null when the gate could not be applied, and on a HARD HALT."
+    },
+    "skills_exported": {
+      "type": ["array", "null"],
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Optional. The skills the Export stage exported (skf-export-skill exited 0), by campaign skill name, from the outcome campaign-state.py recorded for each one. Null when the Export stage did not run; absent on a HARD HALT."
+    },
+    "export_failures": {
+      "type": ["array", "null"],
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["skill", "halt_reason", "exit_code"],
+        "properties": {
+          "skill": { "type": "string", "minLength": 1 },
+          "halt_reason": { "type": ["string", "null"] },
+          "exit_code": { "type": ["integer", "null"] }
+        }
+      },
+      "description": "Optional. Each skill whose skf-export-skill call failed, with that call's halt_reason and exit code (null when it gave none). The campaign still ends with status success, so a CI job gates on this list. Null when the Export stage did not run; absent on a HARD HALT."
+    },
+    "campaign_report_path": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "default": null,
+      "description": "The campaign-report.md step 11 wrote. Null when it could not be written, and on a HARD HALT."
+    },
+    "decision_log": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "default": null,
+      "description": "The append-only _campaign-decision-log.md, whose typed entries record every operator decision, headless default and event. Null before the campaign workspace exists."
+    },
+    "duration": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "default": null,
+      "description": "Wall-clock time from campaign.started_at to its last state write before the report, as campaign-report.py formats it (such as '2h 5m 3s'). Null on a HARD HALT."
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Optional. Non-fatal anomalies the emitter raised, one string each, starting with its code. Present only when there is at least one."
+    }
+  }
+}