bmad-module-skill-forge 2.2.0 → 3.0.0

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

@@ -0,0 +1,261 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-quick-skill-result-envelope.v1.json",
+  "title": "SKF_QUICK_SKILL_RESULT_JSON envelope (v1)",
+  "description": "Single-line JSON document skf-quick-skill prints, prefixed with the literal 'SKF_QUICK_SKILL_RESULT_JSON: ': on stdout when a run finishes (step 6, finalize), and on stderr at every HARD HALT. The shared emitter (skf-emit-result-envelope.py) builds both from a staged payload, so pipelines branch on status, exit_code and halt_reason without parsing the human-readable output. A --batch run prints one per target.",
+  "$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-quick-skill",
+        "prefix": "SKF_QUICK_SKILL_RESULT_JSON",
+        "wrapper": null,
+        "halt_status": "error",
+        "exit_codes": {
+          "input-invalid": 2,
+          "resolution-failure": 3,
+          "write-failure": 4,
+          "overwrite-cancelled": 5,
+          "user-cancelled": 6,
+          "finalize-blocked": 7,
+          "ecosystem-redirect": 8,
+          "not-skf-output": 9,
+          "flat-layout": 9
+        },
+        "success_exit_code": 0,
+        "result_file": "quick-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", "error"],
+      "description": "'success' when step 6 finished the run, 'error' at every HARD HALT."
+    },
+    "exit_code": {
+      "type": "integer",
+      "enum": [0, 2, 3, 4, 5, 6, 7, 8, 9],
+      "description": "The exit code of the halt-contract.md table, derived from halt_reason: null gives 0, input-invalid 2, resolution-failure 3, write-failure 4, overwrite-cancelled 5, user-cancelled 6, finalize-blocked 7, ecosystem-redirect 8, not-skf-output and flat-layout 9."
+    },
+    "phase": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "description": "The step slug where the HARD HALT fired (resolve-target, ecosystem-check, quick-extract, compile, write-and-validate or finalize), on-activation for a halt before the run starts (SKILL.md On Activation, or batch mode's refusal of --description and --exports), or batch-mode for a batch that cannot start (batch mode section 1). Null on success."
+    },
+    "halt_reason": {
+      "type": ["string", "null"],
+      "enum": [
+        null,
+        "input-invalid",
+        "resolution-failure",
+        "write-failure",
+        "overwrite-cancelled",
+        "user-cancelled",
+        "finalize-blocked",
+        "ecosystem-redirect",
+        "not-skf-output",
+        "flat-layout"
+      ],
+      "description": "Null on success. The failure class of a HARD HALT, the same value as error.code: pipelines branch on it without grepping the message."
+    },
+    "error": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["code", "message"],
+          "properties": {
+            "code": {
+              "type": "string",
+              "enum": [
+                "input-invalid",
+                "resolution-failure",
+                "write-failure",
+                "overwrite-cancelled",
+                "user-cancelled",
+                "finalize-blocked",
+                "ecosystem-redirect",
+                "not-skf-output",
+                "flat-layout"
+              ],
+              "description": "The halt_reason."
+            },
+            "message": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The halt's reason, the one-line form of the message the step displayed."
+            },
+            "details": {
+              "description": "Optional phase-specific context, for example the folder the ownership halt refused (details.folder) or the file a failed write named (details.failed_path)."
+            }
+          }
+        }
+      ],
+      "description": "Null on success. 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; absent under --skip-snippet."
+        },
+        "metadata": { "type": "string", "minLength": 1, "description": "Path of {skill_package}/metadata.json." },
+        "active_pointer": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Path of the {skill_group}/active pointer the run flipped; absent when it was skipped."
+        }
+      },
+      "description": "The files the run wrote, by kind. Empty at a HARD HALT before step 5 writes; a later halt lists what was already on disk."
+    },
+    "summary": {
+      "type": "object",
+      "default": {},
+      "additionalProperties": false,
+      "properties": {
+        "skill_name": { "type": "string", "minLength": 1, "description": "The name the skill was written under ({repo_name})." },
+        "version": { "type": "string", "minLength": 1, "description": "The version folder the run wrote." },
+        "language": { "type": "string", "minLength": 1, "description": "The primary language the run compiled." },
+        "exports_documented": { "type": "integer", "minimum": 0, "description": "The exports the compiled SKILL.md documents." },
+        "quality_score": {
+          "type": ["number", "null"],
+          "minimum": 0,
+          "description": "skill-check's quality score (0 to 100) of the written package, from step 5. Null when skill-check did not run. It is the score every workflow's skill-check pass computes, not a test-skill score."
+        },
+        "confidence": {
+          "type": "string",
+          "enum": ["high", "medium", "low"],
+          "description": "The extraction confidence step 3 recorded."
+        },
+        "repo_shape": {
+          "type": ["string", "null"],
+          "enum": [null, "library", "skills-module", "awesome-list", "docs-site", "examples-only"],
+          "description": "The repository shape step 3 recorded, null when it recorded none (a plain library)."
+        },
+        "language_resolution": {
+          "type": ["string", "null"],
+          "enum": [null, "hint", "detected", "auto-picked-first", "user-confirmed"],
+          "description": "How step 1 chose the language: from a language hint, detected with no competing manifest, the first of several manifests picked by a headless run, or confirmed by the user at the multi-language gate."
+        },
+        "detected_languages": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "description": "Every manifest language step 1 detected, in priority order."
+        },
+        "zero_exports_rescue": {
+          "type": ["string", "null"],
+          "enum": [null, "user-accepted", "auto-proceeded"],
+          "description": "Set when step 3 found no export and no README description and the run went on anyway: a user choice or a headless default."
+        },
+        "active_pointer": {
+          "type": "string",
+          "enum": ["symlink", "junction", "skipped-no-active-pointer", "skipped-helper-missing"],
+          "description": "The kind of {skill_group}/active pointer step 6 flipped, or why it flipped none."
+        },
+        "validation_issues": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["skill_md", "context_snippet", "metadata", "security"],
+          "properties": {
+            "skill_md": { "type": "integer", "minimum": 0 },
+            "context_snippet": { "type": "integer", "minimum": 0 },
+            "metadata": { "type": "integer", "minimum": 0 },
+            "security": { "type": "integer", "minimum": 0 }
+          },
+          "description": "The advisory issues step 5's validators returned for each heading of its validation report: skill_md (skill-check's diagnostics, or the frontmatter validator's issues without it, plus the body checks), context_snippet, metadata and security (skill-check's security findings). Auto-fixed issues count nothing, and a check that did not run counts 0."
+        }
+      },
+      "description": "Empty at a HARD HALT. On success, the run's facts a pipeline branches on."
+    },
+    "skill_package": {
+      "type": ["string", "null"],
+      "description": "Absolute path of {skill_package} once step 5 computed it; null before, and at the step 5 ownership halt (the refused folder is in error.details.folder)."
+    },
+    "timestamp": {
+      "type": "string",
+      "minLength": 1,
+      "description": "ISO-8601 UTC time the emitter stamped from the clock."
+    },
+    "run_id": {
+      "type": ["string", "null"],
+      "description": "The run folder's id, stamped by the emitter; a --batch target's is the batch run's id and the target's number."
+    },
+    "result_path": {
+      "type": ["string", "null"],
+      "description": "The per-run result file this envelope's call wrote under {skill_package}, or null when it wrote none (every halt before metadata.json exists)."
+    },
+    "headless_decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["gate", "default_action", "taken_action", "reason"],
+        "properties": {
+          "gate": {
+            "type": "string",
+            "enum": [
+              "resolve-target.ambiguous-package",
+              "resolve-target.multi-language",
+              "ecosystem-check.ecosystem-match",
+              "quick-extract.repo-shape",
+              "quick-extract.zero-exports",
+              "compile.review",
+              "write-and-validate.overwrite"
+            ],
+            "description": "The gate that resolved without a person, named after its step and the gate the step file labels."
+          },
+          "default_action": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The gate's documented default (for example 'C' or 'Y')."
+          },
+          "taken_action": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The action the run took."
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Why, for example 'headless: no user to prompt'."
+          },
+          "evidence": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Optional gate-specific data, such as the detected languages or the package that was overwritten."
+          }
+        }
+      },
+      "description": "One entry per gate that resolved on its own during this run, recorded in the run folder's sink the moment it decided. Empty for an interactive run."
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Non-fatal anomalies, one string each, such as also_found_in (a package name another registry also holds, kept at the first registry's pick) or customization_resolver_unavailable. Empty when none."
+    }
+  }
+}

package/src/shared/scripts/schemas/skf-refine-architecture-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-refine-architecture-result-envelope.v1.json",
+  "title": "SKF_REFINE_ARCHITECTURE_RESULT_JSON envelope (v1)",
+  "description": "Single-line JSON document skf-refine-architecture emits when {headless_mode} is true, prefixed with the literal 'SKF_REFINE_ARCHITECTURE_RESULT_JSON: ': once on stdout when step 6 (report) writes the result contract, after step 5's review promoted the refined document, 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, and checks the line against this schema, so the model never types it. The skill's references/exit-codes.md lists the exit codes and the stage files hold 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-refine-architecture",
+        "prefix": "SKF_REFINE_ARCHITECTURE_RESULT_JSON",
+        "wrapper": null,
+        "halt_status": "error",
+        "exit_codes": {
+          "input-missing": 2,
+          "input-invalid": 2,
+          "output-folder-unconfigured": 3,
+          "forge-folder-unconfigured": 3,
+          "resolution-failure": 3,
+          "write-failed": 4,
+          "preservation-failed": 4,
+          "insufficient-skills": 5,
+          "user-cancelled": 6,
+          "inventory-unreliable": 7,
+          "recovery-failed": 8
+        },
+        "success_exit_code": 0,
+        "result_file": "refine-architecture-result"
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "status",
+    "refined_path",
+    "previous_refined_path",
+    "previous_pass",
+    "gap_count",
+    "issue_count",
+    "improvement_count",
+    "unverified_count",
+    "exit_code",
+    "halt_reason",
+    "run_id",
+    "result_path"
+  ],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["success", "error"],
+      "description": "'success' when the review approved the draft, the preservation check passed and the refined document was promoted to its output path. 'error' on any HARD HALT."
+    },
+    "refined_path": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "default": null,
+      "description": "The refined document, refined-architecture-<arch_project_name>.md in the output folder. Null on a halt before the review's [C] promoted the draft: a halt or a cancel before then leaves the output path as it was."
+    },
+    "previous_refined_path": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "default": null,
+      "description": "Where the earlier refined document went: the review's [C] renames a file already at the output path to refined-architecture-<arch_project_name>-<YYYYMMDD-HHmmss>.md (the run's timestamp, with -2, -3 ... when that name is taken) before it promotes the draft, so it is never overwritten. Null when there was none, and on a halt before the promotion."
+    },
+    "previous_pass": {
+      "type": "boolean",
+      "default": false,
+      "description": "True when the architecture document held an earlier Refine Architecture pass (RA's marked blocks, the unmarked annotations of an older pass with their Refinement Summary, or a refined-architecture-*.md file): the run set those annotations aside, analyzed the rest and replaced them with one current set."
+    },
+    "gap_count": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 0,
+      "description": "Gap-fill subsections in the refined document, counted by the preservation script from the insertion plan it applied. 0 on a halt."
+    },
+    "issue_count": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 0,
+      "description": "Issue annotations in the refined document, counted from the insertion plan. 0 on a halt."
+    },
+    "improvement_count": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 0,
+      "description": "Improvement suggestions in the refined document, counted from the insertion plan. 0 on a halt."
+    },
+    "unverified_count": {
+      "type": "integer",
+      "minimum": 0,
+      "default": 0,
+      "description": "Technologies the architecture document names that no skill covers, so nothing checked what it says about them (the Refinement Summary's Not verified (no skill) row), counted from the insertion plan. 0 on a halt."
+    },
+    "exit_code": {
+      "type": "integer",
+      "enum": [0, 2, 3, 4, 5, 6, 7, 8],
+      "description": "Process exit code matching the skill's references/exit-codes.md table, derived from halt_reason: null gives 0, input-missing and input-invalid 2, output-folder-unconfigured, forge-folder-unconfigured and resolution-failure 3, write-failed and preservation-failed 4, insufficient-skills 5, user-cancelled 6, inventory-unreliable 7, recovery-failed 8."
+    },
+    "halt_reason": {
+      "type": ["string", "null"],
+      "enum": [
+        null,
+        "input-missing",
+        "input-invalid",
+        "output-folder-unconfigured",
+        "forge-folder-unconfigured",
+        "resolution-failure",
+        "write-failed",
+        "preservation-failed",
+        "insufficient-skills",
+        "user-cancelled",
+        "inventory-unreliable",
+        "recovery-failed"
+      ],
+      "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. preservation-failed: the draft would not keep every line of the original architecture document, so it was not promoted."
+    },
+    "run_id": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "description": "The run's id, stamped by the emitter from the run folder name: the run's activation timestamp (YYYYMMDD-HHmmss, UTC). 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 output folder, refine-architecture-result-<YYYYMMDD-HHmmss>.json (UTC), beside its refine-architecture-result-latest.json copy. Stamped by the emitter, never typed; step 6 passes it to the on_complete hook. 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.vs-report", "init.vs-report-unreadable", "gap-analysis.scope", "compile.review"],
+            "description": "The gate that auto-resolved: init.vs-report (step 1 answered the [VS] report question with its default, the report the probe found or none), init.vs-report-unreadable (step 1 could not read the --vs-report-path it was given and probed for the report instead), gap-analysis.scope (step 2 kept the derived document scope), compile.review (step 5 approved the draft). The 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, such as 'C' for [C] continue or 'use-found-report'."
+          },
+          "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, the line the gate logged, such as 'headless: auto-approve compiled architecture'."
+          },
+          "evidence": {
+            "type": "object",
+            "additionalProperties": true,
+            "description": "Optional gate-specific data, such as the report a headless run used or the in-scope and out-of-scope skills it kept."
+          }
+        }
+      },
+      "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: malformed_ra_markers when the document holds an RA marker without its pair (left in place as ordinary text), legacy_blocks_set_aside when an older pass left unmarked RA blocks, which run to the next heading and were set aside unchecked (it names their lines, so a user paragraph inside one is not silently counted as preserved), unknown_scope_skills when --scope-skills names a skill that is not in the inventory, scope_fallback_all_skills when --scope-skills or the document names no inventory skill and every skill is analyzed, out_of_scope_skills when the run's scope left inventory skills out (it counts and names them, so a run scoped with --scope-skills still says what it did not check), customization_resolver_unavailable when the team and user overrides were not applied, and result_file_write_failed when the emitter could not write a result file. 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:vs-report' or 'compile:promote'."
+        },
+        "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-rename-skill-result-envelope.v1.json

@@ -0,0 +1,179 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-rename-skill-result-envelope.v1.json",
+  "title": "SKF_RENAME_SKILL_RESULT_JSON envelope (v1)",
+  "description": "Single-line JSON document skf-rename-skill emits when {headless_mode} is true, prefixed with the literal 'SKF_RENAME_SKILL_RESULT_JSON: ': on stdout when a rename finishes (step 3, report) and at the --dry-run exit (step 1, select), and on stderr at every HARD HALT. The shared emitter (skf-emit-result-envelope.py) builds every line from a staged payload and checks it against this schema, so pipelines branch on status, halt_reason and exit_code without grepping message text.",
+  "$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-rename-skill",
+        "prefix": "SKF_RENAME_SKILL_RESULT_JSON",
+        "wrapper": null,
+        "halt_status": "error",
+        "exit_codes": {
+          "input-missing": 2,
+          "input-invalid": 2,
+          "manifest-corrupt": 3,
+          "nothing-to-rename": 3,
+          "copy-failed": 4,
+          "write-failed": 4,
+          "manifest-write-failed": 4,
+          "not-skf-output": 5,
+          "flat-layout": 5,
+          "name-collision": 5,
+          "source-authority-blocked": 5,
+          "halted-for-concurrent-run": 5,
+          "verify-failed": 5,
+          "user-cancelled": 6
+        },
+        "success_exit_code": 0,
+        "result_file": "rename-skill-result"
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "status",
+    "old_name",
+    "new_name",
+    "versions_renamed",
+    "manifest_rekeyed",
+    "context_files_updated",
+    "exit_code",
+    "halt_reason",
+    "headless_decisions"
+  ],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["success", "error", "dry-run"],
+      "description": "'success' when the rename finished (step 3). 'dry-run' when --dry-run ended the run after the step 1 confirmation block, with nothing copied, re-keyed or deleted. 'error' on any HARD HALT, with halt_reason naming its class."
+    },
+    "old_name": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "description": "The skill being renamed. Null when the run halted before step 1 bound it."
+    },
+    "new_name": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "description": "The validated new name. Null when the run halted before step 1 bound it."
+    },
+    "versions_renamed": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "uniqueItems": true,
+      "description": "On success, the versions whose package step 2 renamed, as step 2 recorded them from its own moves: a version folder without a package is copied but not listed. On a dry run, the versions the rename would touch. Empty on a halt."
+    },
+    "manifest_rekeyed": {
+      "type": "boolean",
+      "description": "True when step 2 re-keyed the skill's export manifest entry to the new name. False on a dry run and on a halt."
+    },
+    "context_files_updated": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "The context files (CLAUDE.md, AGENTS.md, .cursorrules and the like) whose SKF managed section step 2 rebuilt. The rebuild is best-effort and never halts; a file that failed is reported in the step 3 report and the result file, not here. Empty on a dry run and on a halt."
+    },
+    "exit_code": {
+      "type": "integer",
+      "enum": [0, 2, 3, 4, 5, 6],
+      "description": "Process exit code, derived by the emitter from halt_reason through $defs.skf-envelope.exit_codes (0 when halt_reason is null). references/exit-codes.md says where each code is raised."
+    },
+    "halt_reason": {
+      "type": ["string", "null"],
+      "enum": [
+        null,
+        "input-missing",
+        "input-invalid",
+        "manifest-corrupt",
+        "nothing-to-rename",
+        "not-skf-output",
+        "flat-layout",
+        "name-collision",
+        "source-authority-blocked",
+        "halted-for-concurrent-run",
+        "copy-failed",
+        "verify-failed",
+        "manifest-write-failed",
+        "write-failed",
+        "user-cancelled"
+      ],
+      "description": "Null on success and on a dry run. One of the documented HALT classes otherwise. halted-for-concurrent-run fires while another rename of the same skill holds a fresh run lock (step 1), or when this run's lock went stale while it waited at a step 1 gate and another run may have taken it (step 2); error.reason names the run that holds the lock and when it goes stale, never a PID."
+    },
+    "headless_decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["gate", "default_action", "taken_action", "reason"],
+        "properties": {
+          "gate": {
+            "type": "string",
+            "enum": ["source-authority", "confirm-rename"],
+            "description": "The gate that auto-resolved: the step 1 source-authority warning or the step 1 confirmation gate. Matches the labels in the stage prose."
+          },
+          "default_action": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The action documented as the gate's default."
+          },
+          "taken_action": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The action the run took."
+          },
+          "reason": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Why the gate resolved without a person, for example 'headless auto-confirm'."
+          }
+        }
+      },
+      "description": "One entry per gate that auto-resolved under {headless_mode}, recorded in the run folder's sink the moment the gate decided, so a halt still reports the decisions taken before it. Empty in interactive runs."
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "Optional. Non-fatal anomalies the run recorded, one string each, such as run-lock-replaced (step 1 took over a stale run lock), run-lock-not-released (a halt could not release the run lock), result_file_write_failed or customization_resolver_unavailable. Present only when the run recorded at least one."
+    },
+    "run_id": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "description": "The run's id, the UTC time the run started and a random suffix. It names the run folder, {project-root}/_bmad-output/.skf-run/skf-rename-skill-<run_id>/, which a halt leaves in place with its staged payloads, and it ends the run lock's owner."
+    },
+    "result_path": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "description": "The per-run result file step 3 wrote, rename-skill-result-<YYYYMMDD-HHmmss>.json beside rename-skill-result-latest.json in the renamed skill's folder. Null on a dry run, on a halt and when the file could not be written."
+    },
+    "error": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["phase", "reason"],
+          "properties": {
+            "phase": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The step and operation that halted, for example 'select:concurrency-guard' or 'execute:copy'."
+            },
+            "reason": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The message the halt displayed."
+            },
+            "path": {
+              "type": "string",
+              "description": "The path the halt names, when it names one: the lock file, the manifest or a folder."
+            }
+          }
+        }
+      ],
+      "description": "Optional. Present on a halt: the phase, the message and the path the halt names. Absent on success and on a dry run."
+    }
+  }
+}