bmad-module-skill-forge 2.1.0 → 3.0.0

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

@@ -0,0 +1,284 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-create-skill-result-envelope.v1.json",
+  "title": "SKF_CREATE_SKILL_RESULT_JSON envelope (v1)",
+  "description": "Single-line JSON document skf-create-skill prints, prefixed with the literal 'SKF_CREATE_SKILL_RESULT_JSON: ': on stdout when step 8 (report) finishes a brief, once per brief of a --batch run, and on stderr at every HARD HALT of steps 1 to 7. The shared emitter (skf-emit-result-envelope.py) builds each line from the payload a step stages in the brief's run folder, folds in the auto-decisions and warnings the run recorded there, derives exit_code from halt_reason, stamps timestamp, run_id and result_path, and checks the line against this schema, so the model never types it. The skill's SKILL.md Workflow Rules give the halt command, and references/report.md the finished run's.",
+  "$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-create-skill",
+        "prefix": "SKF_CREATE_SKILL_RESULT_JSON",
+        "wrapper": null,
+        "halt_status": "failed",
+        "exit_codes": {
+          "brief-missing": 2,
+          "brief-malformed": 2,
+          "brief-invalid": 2,
+          "forge-tier-missing": 3,
+          "source-not-found": 3,
+          "helper-missing": 3,
+          "docs-unreachable": 3,
+          "write-failed": 4,
+          "staging-unreadable": 4,
+          "not-skf-output": 5,
+          "flat-layout": 5,
+          "tier1-not-preserved": 5,
+          "shard-xref-broken": 5,
+          "description-angle-brackets": 5,
+          "references-missing": 5,
+          "active-link-blocked": 5,
+          "halted-for-brief-refinement": 6
+        },
+        "success_exit_code": 0,
+        "result_file": "create-skill-result"
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "status",
+    "exit_code",
+    "phase",
+    "halt_reason",
+    "error",
+    "outputs",
+    "summary",
+    "skill_package",
+    "timestamp",
+    "run_id",
+    "result_path",
+    "headless_decisions",
+    "warnings"
+  ],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["success", "partial", "failed"],
+      "description": "'success' when step 8 finished the brief, 'partial' when it finished a source brief whose extraction found no export (summary.warning 'zero-exports'), 'failed' at every HARD HALT, also one after step 7 promoted the package (skill_package and outputs then name what is on disk)."
+    },
+    "exit_code": {
+      "type": "integer",
+      "enum": [0, 2, 3, 4, 5, 6],
+      "description": "Derived from halt_reason: null gives 0; brief-missing, brief-malformed and brief-invalid 2; forge-tier-missing, source-not-found, helper-missing and docs-unreachable 3; write-failed and staging-unreadable 4; not-skf-output, flat-layout, tier1-not-preserved, shard-xref-broken, description-angle-brackets, references-missing and active-link-blocked 5; halted-for-brief-refinement 6."
+    },
+    "phase": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "description": "The step slug where the HARD HALT fired: load-brief, extract, component-extraction, fetch-docs, compile, doc-sources, auto-shard, validate or generate-artifacts, or batch-mode for a --batch run whose batch could not start or go on. Null on a finished run."
+    },
+    "halt_reason": {
+      "type": ["string", "null"],
+      "enum": [
+        null,
+        "brief-missing",
+        "brief-malformed",
+        "brief-invalid",
+        "forge-tier-missing",
+        "source-not-found",
+        "helper-missing",
+        "docs-unreachable",
+        "write-failed",
+        "staging-unreadable",
+        "not-skf-output",
+        "flat-layout",
+        "tier1-not-preserved",
+        "shard-xref-broken",
+        "description-angle-brackets",
+        "references-missing",
+        "active-link-blocked",
+        "halted-for-brief-refinement"
+      ],
+      "description": "Null on a finished run. The failure class of a HARD HALT, the same value as error.code and summary.halt_reason: pipelines branch on it without parsing the message."
+    },
+    "error": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["code", "message"],
+          "properties": {
+            "code": {
+              "type": "string",
+              "enum": [
+                "brief-missing",
+                "brief-malformed",
+                "brief-invalid",
+                "forge-tier-missing",
+                "source-not-found",
+                "helper-missing",
+                "docs-unreachable",
+                "write-failed",
+                "staging-unreadable",
+                "not-skf-output",
+                "flat-layout",
+                "tier1-not-preserved",
+                "shard-xref-broken",
+                "description-angle-brackets",
+                "references-missing",
+                "active-link-blocked",
+                "halted-for-brief-refinement"
+              ],
+              "description": "The halt_reason."
+            },
+            "message": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The halt's reason, the one-line form of the message the step displayed."
+            },
+            "phase": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The step slug where the halt fired."
+            },
+            "path": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The file or folder the halt names, when it names one (a missing helper's probe path, the folder a write or the ownership check refused)."
+            },
+            "details": {
+              "description": "Optional halt-specific context, such as the Tier 1 sections a split moved (details.tier1_missing) or the doc URLs that failed (details.failed_urls)."
+            }
+          }
+        }
+      ],
+      "description": "Null on a finished run. The failure of a HARD HALT."
+    },
+    "outputs": {
+      "type": "object",
+      "default": {},
+      "additionalProperties": false,
+      "properties": {
+        "skill_md": { "type": "string", "minLength": 1, "description": "Path of {skill_package}/SKILL.md." },
+        "context_snippet": { "type": "string", "minLength": 1, "description": "Path of {skill_package}/context-snippet.md." },
+        "metadata": { "type": "string", "minLength": 1, "description": "Path of {skill_package}/metadata.json." },
+        "references": { "type": "string", "minLength": 1, "description": "Path of the {skill_package}/references/ folder." },
+        "provenance_map": { "type": "string", "minLength": 1, "description": "Path of {forge_version}/provenance-map.json." },
+        "evidence_report": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Path of {forge_version}/evidence-report.md, which holds the Auto-Decisions table."
+        },
+        "extraction_rules": { "type": "string", "minLength": 1, "description": "Path of {forge_version}/extraction-rules.yaml." }
+      },
+      "description": "The files the brief's run wrote, by kind. Empty at a HARD HALT before step 7 promoted the package; a later halt lists what is on disk."
+    },
+    "summary": {
+      "type": "object",
+      "default": {},
+      "additionalProperties": false,
+      "properties": {
+        "skill_name": { "type": "string", "minLength": 1, "description": "The brief's name, the skill's folder name." },
+        "version": { "type": "string", "minLength": 1, "description": "The version folder the run wrote." },
+        "forge_tier": {
+          "type": "string",
+          "enum": ["Quick", "Forge", "Forge+", "Deep"],
+          "description": "The tier the run compiled at, after any tier_override."
+        },
+        "exports_documented": { "type": "integer", "minimum": 0, "description": "metadata.json stats.exports_documented." },
+        "confidence_distribution": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["t1", "t1_low", "t2", "t3"],
+          "properties": {
+            "t1": { "type": "integer", "minimum": 0 },
+            "t1_low": { "type": "integer", "minimum": 0 },
+            "t2": { "type": "integer", "minimum": 0 },
+            "t3": { "type": "integer", "minimum": 0 }
+          },
+          "description": "metadata.json confidence_distribution, as skf-render-metadata-stats.py computed it."
+        },
+        "auto_decision_count": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The decisions the run took without asking, as recorded in its run folder: every gate a headless run resolved by its default, and step 1's tier override in any mode. The rows of the evidence report's Auto-Decisions table; 0 when there were none."
+        },
+        "warning": {
+          "type": "string",
+          "enum": ["zero-exports"],
+          "description": "Set with status 'partial': a source brief's extraction found no export and the run went on."
+        },
+        "halt_reason": {
+          "type": "string",
+          "minLength": 1,
+          "description": "At a HARD HALT, the halt_reason again, where the halt line carried it before the envelope had a schema."
+        },
+        "evidence_report": {
+          "type": ["string", "null"],
+          "description": "At a HARD HALT, {forge_version}/evidence-report.md once step 7 promoted it, else null."
+        }
+      },
+      "description": "On a finished run, the facts a pipeline branches on. At a HARD HALT, halt_reason and evidence_report."
+    },
+    "skill_package": {
+      "type": ["string", "null"],
+      "description": "Absolute path of {skill_package} once step 7 promoted it; null before, and at the step 7 ownership halts (the refused folder is in error.path)."
+    },
+    "timestamp": {
+      "type": "string",
+      "minLength": 1,
+      "description": "ISO-8601 UTC time the emitter stamped from the clock."
+    },
+    "run_id": {
+      "type": ["string", "null"],
+      "description": "The brief's run folder id, stamped by the emitter (each brief of a --batch run has its own); null for a halt before the run folder exists."
+    },
+    "result_path": {
+      "type": ["string", "null"],
+      "description": "The per-run create-skill-result-<YYYYMMDD-HHmmss>.json this envelope's call wrote in {forge_version}, beside its -latest copy, or null when it wrote none (every halt before step 7 created {forge_version})."
+    },
+    "headless_decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["step", "gate", "decision", "rationale", "timestamp"],
+        "properties": {
+          "step": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The step whose gate decided: load-brief, extract, component-extraction or compile."
+          },
+          "gate": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The gate: tier-override, tag-choice, review-gate, zero-exports, demo-exclusion, registry-confirm, provide-or-skip-registry, manual-carry-forward (compile kept an earlier build's hand-written [MANUAL] content), or authoritative-file:<path> (one decision per authoritative file a headless run deferred)."
+          },
+          "decision": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The action the run took, such as 'C', 'Y', 'S', 'apply' or 'deferred-headless'."
+          },
+          "value": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Optional: the value the decision applied, such as the tier_override or the tag chosen."
+          },
+          "fallback": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Optional: what the run used instead, such as the detected tier when an override was rejected."
+          },
+          "rationale": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Why, for example 'headless mode: no human to confirm scope or ref'."
+          },
+          "timestamp": {
+            "type": "string",
+            "minLength": 1,
+            "description": "ISO-8601 time the gate decided."
+          }
+        }
+      },
+      "description": "One entry per decision the run took without asking, recorded in the run folder's sink the moment its gate decided: every gate a headless run resolved by its default, and step 1's tier override in any mode. The evidence report's Auto-Decisions table renders the same entries. Empty when there were none."
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Non-fatal anomalies the run recorded in its run folder, one string each, such as customization_resolver_unavailable. Empty when none."
+    }
+  }
+}

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

@@ -0,0 +1,164 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-drop-skill-result-envelope.v1.json",
+  "title": "SKF_DROP_SKILL_RESULT_JSON envelope (v1)",
+  "description": "Single-line JSON document skf-drop-skill emits when {headless_mode} is true, prefixed with the literal 'SKF_DROP_SKILL_RESULT_JSON: ': on stdout when step 3 reports a finished drop, on stdout when a --dry-run stops at the step 1 confirmation gate, and on stderr at every HARD HALT. The shared emitter builds each line from the payload a stage gives it, so pipelines branch on status and halt_reason without parsing the human-readable report. src/skf-drop-skill/references/invocation-contract.md describes each field.",
+  "$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 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-drop-skill",
+        "prefix": "SKF_DROP_SKILL_RESULT_JSON",
+        "wrapper": null,
+        "halt_status": "error",
+        "exit_codes": {
+          "input-missing": 2,
+          "input-invalid": 2,
+          "manifest-corrupt": 3,
+          "nothing-to-drop": 3,
+          "manifest-write-failed": 4,
+          "context-rebuild-failed": 4,
+          "delete-failed": 4,
+          "write-failed": 4,
+          "active-version-guard-refused": 5,
+          "not-skf-output": 5,
+          "headless-purge-forbidden": 6,
+          "user-cancelled": 6
+        },
+        "success_exit_code": 0,
+        "result_file": "drop-skill-result"
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "status",
+    "skill",
+    "drop_mode",
+    "versions_affected",
+    "files_deleted",
+    "would_delete",
+    "forge_left_in_place",
+    "manifest_updated",
+    "result_path",
+    "exit_code",
+    "halt_reason",
+    "error"
+  ],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["success", "error", "dry-run"],
+      "description": "'success' when step 3 reports a finished drop (also when some purge folders could not be deleted: the result file's own status says 'partial' then). 'dry-run' when --dry-run stopped at the step 1 confirmation gate before any change. 'error' at every HARD HALT."
+    },
+    "skill": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "description": "The skill the run selected. Null when the run halted before one was selected."
+    },
+    "drop_mode": {
+      "type": ["string", "null"],
+      "enum": ["deprecate", "purge", null],
+      "default": null,
+      "description": "'deprecate' (manifest only, files kept) or 'purge' (files deleted too). Null when the run halted before the mode was decided."
+    },
+    "versions_affected": {
+      "oneOf": [
+        {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 }
+        },
+        {
+          "type": "string",
+          "enum": ["all"]
+        }
+      ],
+      "default": [],
+      "description": "The versions the drop covers: a list holding the one version dropped, or 'all' for a drop of the whole skill. An empty list when the run halted before the scope was chosen."
+    },
+    "files_deleted": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "default": [],
+      "description": "The absolute folder paths a purge deleted. Empty for a deprecate, a dry run and a HALT (a purge that deleted nothing halts with delete-failed)."
+    },
+    "would_delete": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "default": [],
+      "description": "Dry run of a purge only: the absolute folder paths the purge would delete (the purge check's affected_directories), so a pipeline can check the blast radius before it runs the drop. Empty otherwise, and for a dry run in deprecate mode."
+    },
+    "forge_left_in_place": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "default": null,
+      "description": "The forge folder a purge leaves in place (or, in a dry run, would leave) because SKF did not generate it. Null otherwise, and in deprecate mode."
+    },
+    "manifest_updated": {
+      "type": "boolean",
+      "default": false,
+      "description": "True when step 2 wrote the export manifest. False for a draft skill (it has no manifest entry), a dry run and a HALT before the write; a failed manifest write halts with manifest-write-failed."
+    },
+    "result_path": {
+      "type": ["string", "null"],
+      "description": "The per-run result file the emitter wrote for a finished drop, {skills_output_folder}/drop-skill-result-<YYYYMMDD-HHmmss>.json (UTC), beside its drop-skill-result-latest.json copy. Stamped by the emitter, never typed. Null for a dry run and a HALT, which write no result file, and when the write failed (warnings say why)."
+    },
+    "exit_code": {
+      "type": "integer",
+      "enum": [0, 2, 3, 4, 5, 6],
+      "description": "Process exit code matching the Exit Codes table in src/skf-drop-skill/references/invocation-contract.md, derived from halt_reason: null gives 0, input-missing and input-invalid 2, manifest-corrupt and nothing-to-drop 3, manifest-write-failed, context-rebuild-failed, delete-failed and write-failed 4, active-version-guard-refused and not-skf-output 5, headless-purge-forbidden and user-cancelled 6."
+    },
+    "halt_reason": {
+      "type": ["string", "null"],
+      "enum": [
+        null,
+        "input-missing",
+        "input-invalid",
+        "manifest-corrupt",
+        "nothing-to-drop",
+        "manifest-write-failed",
+        "context-rebuild-failed",
+        "delete-failed",
+        "write-failed",
+        "active-version-guard-refused",
+        "not-skf-output",
+        "headless-purge-forbidden",
+        "user-cancelled"
+      ],
+      "description": "Null on success and on a dry run. One of the documented HALT classes on error, so a pipeline surfaces the right operator message without parsing the prose."
+    },
+    "error": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["phase", "reason"],
+          "properties": {
+            "phase": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The step and gate that halted, such as 'select:scope' or 'execute:manifest-write'."
+            },
+            "reason": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The halt's one-line message."
+            },
+            "path": {
+              "type": "string",
+              "description": "The file or folder the failed operation targeted, when the halt names one."
+            }
+          }
+        }
+      ],
+      "description": "Null on success and on a dry run. On a HALT, the step that halted and its message."
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Optional. Non-fatal anomalies the run recorded, one string each, such as result_file_write_failed when the result file could not be written. Present only when there is at least one."
+    }
+  }
+}

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

@@ -0,0 +1,160 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-export-result-envelope.v1.json",
+  "title": "SKF_EXPORT_RESULT_JSON envelope (v1)",
+  "description": "Single-line JSON document skf-export-skill emits when {headless_mode} is true, prefixed with the literal 'SKF_EXPORT_RESULT_JSON: ': once on stdout when a run ends (step 6, summary, with status success or dry-run) 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 run passes it, folds in the auto-decisions the run's gates recorded in its run sink, derives exit_code from halt_reason and checks the line against this schema, so the model never types it. The skill's references/result-envelope.md holds the halt command and the Exit Codes table that maps each halt site to its code.",
+  "$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-export-skill",
+        "prefix": "SKF_EXPORT_RESULT_JSON",
+        "wrapper": null,
+        "halt_status": "error",
+        "exit_codes": {
+          "input-missing": 2,
+          "resolution-failure": 3,
+          "not-skf-output": 3,
+          "write-failed": 4,
+          "context-rebuild-failed": 4,
+          "manifest-write-failed": 4,
+          "malformed-markers": 5,
+          "user-cancelled": 6
+        },
+        "success_exit_code": 0,
+        "result_file": "export-skill-result"
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "status",
+    "skills",
+    "context_files_updated",
+    "manifest_path",
+    "headless_decisions",
+    "exit_code",
+    "halt_reason",
+    "result_path"
+  ],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["success", "dry-run", "error"],
+      "description": "'success' when the run reached the terminal step and recorded every skill of the batch in the export manifest (with passive context on, it also wrote the context files and the snippets). 'dry-run' when --dry-run previewed the run and wrote none of them (no result file either). 'error' on any HARD HALT."
+    },
+    "skills": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "description": "The skill names of the run's batch. Empty when a halt came before step 1 resolved the batch."
+    },
+    "context_files_updated": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "description": "The context files (CLAUDE.md, AGENTS.md, .cursorrules) whose managed section this run wrote and verified. Empty on a dry run, with passive context off, and when a halt came before any write."
+    },
+    "manifest_path": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "description": "The export manifest path once step 4 recorded every skill of the batch in it. Null when no manifest write completed: every dry run, and every halt before the manifest write finished."
+    },
+    "headless_decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["gate", "default_action", "taken_action", "reason"],
+        "properties": {
+          "gate": {
+            "type": "string",
+            "enum": [
+              "load-skill.snippet-root-layout",
+              "load-skill.snippet-root-probe",
+              "load-skill.confirmation",
+              "update-context.orphan-context-files",
+              "update-context.orphan-rows",
+              "update-context.write-confirmation"
+            ],
+            "description": "The gate that auto-resolved: step 1's snippet-root layout question (no earlier export chose a root), snippet-root mismatch gate (an earlier export's root differs from the IDE mapping, resolved by the folder on disk that holds the skills) and confirmation gate, and step 4's orphaned context files gate, orphaned managed-section rows gate and write confirmation gate. Each gate 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 (for example 'C' for [C] Continue, 'b' for option (b))."
+          },
+          "taken_action": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The action the run took. In a headless run it equals default_action."
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Human-readable rationale, such as 'headless: auto-continue past skill confirmation'."
+          },
+          "evidence": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Optional gate-specific data: the observed snippet-root prefixes, the orphaned context files, or the orphaned rows' skills."
+          }
+        }
+      },
+      "description": "One entry per gate that auto-resolved during the run, read from the run sink, so a halt reports the decisions taken before it. Empty in an interactive run."
+    },
+    "exit_code": {
+      "type": "integer",
+      "enum": [0, 2, 3, 4, 5, 6],
+      "description": "Process exit code matching the Exit Codes table of the skill's references/result-envelope.md, derived from halt_reason: null gives 0, input-missing 2, resolution-failure and not-skf-output 3, write-failed, context-rebuild-failed and manifest-write-failed 4, malformed-markers 5, user-cancelled 6."
+    },
+    "halt_reason": {
+      "type": ["string", "null"],
+      "enum": [
+        null,
+        "input-missing",
+        "resolution-failure",
+        "not-skf-output",
+        "write-failed",
+        "context-rebuild-failed",
+        "manifest-write-failed",
+        "malformed-markers",
+        "user-cancelled"
+      ],
+      "description": "Null on success and dry-run. One of the documented HALT classes on error, so pipelines branch on the failure class without grepping the prose message."
+    },
+    "result_path": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "description": "The per-run result file the emitter wrote in the skills output folder, export-skill-result-<YYYYMMDD-HHmmss>.json (its copy is export-skill-result-latest.json beside it). Null on a dry run, on every halt, and when the write failed (a result_file_write_failed warning says why)."
+    },
+    "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 (for example result_file_write_failed). 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 file and section, for example 'update-context §9'."
+        },
+        "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."
+    }
+  }
+}