bmad-module-skill-forge 2.1.0 → 3.0.0

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

@@ -2,7 +2,19 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-setup-result-envelope.v1.json",
   "title": "SKF_SETUP_RESULT_JSON envelope (v1)",
-  "description": "Single-line JSON document emitted by skf-setup step 4 §4 when {headless_mode} is true, prefixed with the literal 'SKF_SETUP_RESULT_JSON: '. Pipelines grep one line out of the workflow log without parsing ASCII-art and without racing the forge-tier.yaml writer. Schema added in PR #247, extended in PR #248 (header / outputs / failure modes), extended again in this PR with previous_tier / tier_changed / tools_added / tools_removed / error.",
+  "description": "Single-line JSON document skf-setup displays when {headless_mode} or {quiet_mode} is true, prefixed with the literal 'SKF_SETUP_RESULT_JSON: '. Step 4 builds it at the end of a run (status success or tier_failure); a halt that names a phase builds a blocked one with the helper's emit-blocked subcommand. Pipelines grep one line out of the workflow log without parsing ASCII-art and without racing the forge-tier.yaml writer.",
+  "$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 result file stem. Nothing in the schema references this entry, so it constrains no envelope.",
+      "const": {
+        "workflow": "skf-setup",
+        "prefix": "SKF_SETUP_RESULT_JSON",
+        "wrapper": "skf_setup",
+        "halt_status": "blocked",
+        "result_file": null
+      }
+    }
+  },
   "type": "object",
   "additionalProperties": false,
   "required": ["skf_setup"],
@@ -30,13 +42,13 @@
       "properties": {
         "status": {
           "type": "string",
-          "enum": ["success", "tier_failure", "write_failure", "blocked"],
-          "description": "Single-field outcome for pipeline branching. 'success' when no error and tier requirement (if any) is satisfied. 'tier_failure' when require_tier was set and is not satisfied. 'write_failure' when forge-tier.yaml or preferences.yaml could not be written. 'blocked' for any other halt that still produced an envelope (e.g. foreign ccc binary rejected pre-index)."
+          "enum": ["success", "tier_failure", "blocked"],
+          "description": "Single-field outcome for pipeline branching. 'success' when the run finished with no error and any required tier is satisfied. 'tier_failure' when --require-tier was set and is not satisfied. 'blocked' for any halt that still produced an envelope; error.phase names it, for example 'step 2:write-tools' or 'step 2:forge-data-dir' when forge-tier.yaml or the forge data folder could not be written."
         },
         "tier": {
           "type": "string",
           "enum": ["Quick", "Forge", "Forge+", "Deep"],
-          "description": "Active capability tier this run."
+          "description": "Active capability tier this run. A blocked envelope carries 'Quick' as a placeholder."
         },
         "previous_tier": {
           "type": ["string", "null"],
@@ -73,7 +85,7 @@
         "config_path": {
           "type": "string",
           "minLength": 1,
-          "description": "Absolute path to the forge-tier.yaml that this run wrote (or attempted to write — see error)."
+          "description": "Absolute path to the forge-tier.yaml this run wrote. A blocked envelope carries error.path here, or '<unknown — halt before config_path resolved>' when the halt has no path."
         },
         "ccc_index": {
           "type": "object",
@@ -92,10 +104,10 @@
           "type": "array",
           "items": {
             "type": "string",
-            "enum": ["forge-tier.yaml", "preferences.yaml", "settings.yml", "ccc_index"]
+            "enum": ["forge-tier.yaml", "settings.yml", "ccc_index"]
           },
           "uniqueItems": true,
-          "description": "Files actually written this run. Empty array when a write failure halted the run before any file was written."
+          "description": "Files written this run, as step 4 reports them. Setup never writes preferences.yaml: the installer creates it. A blocked envelope always carries an empty array, even when an earlier step had already written a file."
         },
         "tier_override_active": {
           "type": "boolean",
@@ -112,7 +124,7 @@
         "warnings": {
           "type": "array",
           "items": { "type": "string" },
-          "description": "Non-fatal anomalies surfaced during the run. May include tier_override_invalid, tier_override_unsafe, ccc_exclusion_warnings entries, ccc_registry_stale_removed entries, qmd_daemon_stopped, ccc_indexing_failed, etc. Empty when none."
+          "description": "Non-fatal anomalies surfaced during the run. May include customization_resolver_unavailable, tier_override_invalid, tier_override_unsafe, ccc_exclusion_warnings entries, ccc_registry_stale_removed entries, qmd_daemon_stopped, tool_below_minimum entries (one per tool below its minimum version: '<tool> <version> (minimum <minimum>)'; a tier tool among them reads false under tools), ccc_indexing_failed, etc. Empty when none."
         },
         "error": {
           "oneOf": [
@@ -125,14 +137,18 @@
                 "phase": {
                   "type": "string",
                   "minLength": 1,
-                  "description": "Step or operation that failed (e.g. 'write-config:forge-tier.yaml')."
+                  "description": "The halt that produced the envelope, as <step>:<cause> (e.g. 'step 2:write-tools', 'on-activation:uv-missing')."
+                },
+                "path": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Absolute path of the file or folder the halt concerns, or '<n/a>' when it has none."
                 },
-                "path": { "type": "string", "minLength": 1, "description": "Absolute path of the file the failed operation targeted." },
                 "reason": { "type": "string", "minLength": 1, "description": "Human-readable error message." }
               }
             }
           ],
-          "description": "Null on success. Object describing the failure when forge-tier.yaml or preferences.yaml could not be written. Pipelines branch on error !== null for 'exit code 2' semantics."
+          "description": "Null unless a halt produced the envelope; then the halt's phase, path and diagnostic. status is 'blocked' exactly when error is non-null, and the other fields of a blocked envelope are placeholders."
         }
       }
     }

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

@@ -0,0 +1,176 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-stack-result-envelope.v1.json",
+  "title": "SKF_STACK_RESULT_JSON envelope (v1)",
+  "description": "Single-line JSON document skf-create-stack-skill prints, prefixed with the literal 'SKF_STACK_RESULT_JSON: ': on stdout when step 9 (report) finishes, before it chains to the health check, and on stderr at every HARD HALT (status error). The shared emitter, skf-emit-result-envelope.py, builds every line from the payload a step 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/invocation-contract.md lists each halt with its step; each halting step file shows the emit-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-create-stack-skill",
+        "prefix": "SKF_STACK_RESULT_JSON",
+        "wrapper": null,
+        "halt_status": "error",
+        "exit_codes": {
+          "config-missing": 2,
+          "input-invalid": 2,
+          "no-manifests": 2,
+          "all-extractions-failed": 2,
+          "schema-version-mismatch": 2,
+          "unknown-verdict-token": 2,
+          "forge-tier-missing": 3,
+          "helper-missing": 3,
+          "resolution-failure": 3,
+          "write-failure": 4,
+          "not-skf-output": 5,
+          "flat-layout": 5,
+          "user-cancelled": 6
+        },
+        "success_exit_code": 0,
+        "result_file": "create-stack-skill-result"
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "status",
+    "skill_package",
+    "skill_name",
+    "stack_libraries",
+    "mode",
+    "quality_score",
+    "exit_code",
+    "halt_reason",
+    "run_id",
+    "result_path",
+    "headless_decisions",
+    "warnings"
+  ],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["success", "error"],
+      "description": "'success' when step 9 finished the run, 'error' at every HARD HALT."
+    },
+    "skill_package": {
+      "type": ["string", "null"],
+      "description": "Absolute path of the committed stack package, {skills_output_folder}/{stack_name}/{version}/{stack_name}/. Null at every HARD HALT: no halt comes after step 7 committed the package."
+    },
+    "skill_name": {
+      "type": ["string", "null"],
+      "description": "The stack's published name, {stack_name}, as step 1 bound it. Null for a halt before step 1 bound it (config-missing, or a stack_name step 1 refused)."
+    },
+    "stack_libraries": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "The libraries of the stack: dependency names in code mode, constituent skill names in compose mode. At a halt, the confirmed libraries when step 3 confirmed them, else []."
+    },
+    "mode": {
+      "type": ["string", "null"],
+      "enum": ["code", "compose", null],
+      "description": "The run's resolved mode; null for a halt before step 1 chose it."
+    },
+    "quality_score": {
+      "type": ["number", "null"],
+      "minimum": 0,
+      "description": "The skill-check score step 8 recorded for the committed package; null when skill-check did not run and at every halt. It is not a test-skill score: [TS] grades the stack."
+    },
+    "exit_code": {
+      "type": "integer",
+      "enum": [0, 2, 3, 4, 5, 6],
+      "description": "Derived from halt_reason: null gives 0; config-missing, input-invalid, no-manifests, all-extractions-failed, schema-version-mismatch and unknown-verdict-token 2; forge-tier-missing, helper-missing and resolution-failure 3; write-failure 4; not-skf-output and flat-layout 5; user-cancelled 6."
+    },
+    "halt_reason": {
+      "type": ["string", "null"],
+      "enum": [
+        null,
+        "config-missing",
+        "input-invalid",
+        "no-manifests",
+        "all-extractions-failed",
+        "schema-version-mismatch",
+        "unknown-verdict-token",
+        "forge-tier-missing",
+        "helper-missing",
+        "resolution-failure",
+        "write-failure",
+        "not-skf-output",
+        "flat-layout",
+        "user-cancelled"
+      ],
+      "description": "Null on success. The failure class of a HARD HALT, so a pipeline branches on it without parsing the message. helper-missing: a shared helper the run needs resolved to no path (re-install SKF)."
+    },
+    "error": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["phase", "reason"],
+      "properties": {
+        "phase": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Where the run halted: the step file and the check, for example 'detect-manifests:enumerate'."
+        },
+        "reason": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The halt message the step displayed, on one line."
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Optional: the file or folder the halt names, such as a missing helper's probe path or the folder the ownership check refused."
+        }
+      },
+      "description": "Present at a HARD HALT only: where the run stopped and why."
+    },
+    "run_id": {
+      "type": ["string", "null"],
+      "description": "The run folder's id, stamped by the emitter from {run_dir}'s name; null for a halt before the run folder exists."
+    },
+    "result_path": {
+      "type": ["string", "null"],
+      "description": "The per-run create-stack-skill-result-<YYYYMMDD-HHmmss>.json the emitter wrote in {forge_version} on success, beside its -latest copy; null at a halt 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.compose-suggestion", "init.scan-root", "rank-and-confirm.scope", "compile-stack.review"],
+            "description": "The gate a headless run resolved by its default: step 1's compose suggestion and scan-scope question, step 3's scope gate and step 6's review gate. Each records its decision in the run sink the moment it decides."
+          },
+          "default_action": {
+            "type": "string",
+            "minLength": 1,
+            "description": "The gate's documented default action."
+          },
+          "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": "Why, such as 'headless: kept the recommended scope'."
+          },
+          "evidence": {
+            "type": "object",
+            "description": "Optional gate data. The scope gate gives scope (the libraries kept) and dropped (each library the default left out, with its reason), so no library leaves the stack unrecorded."
+          }
+        }
+      },
+      "description": "One entry per gate the run resolved without asking, read from the run sink, so a halt reports the decisions taken before it. [] when there were none."
+    },
+    "warnings": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 },
+      "description": "The run's workflow_warnings[], one '[<step>/<severity>] <code>: <message>' string each as the steps recorded them in the run sink, then any the emitter raised (result_file_write_failed, a sink line it could not read). [] when none."
+    }
+  }
+}

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

@@ -0,0 +1,173 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-test-result-envelope.v1.json",
+  "title": "SKF_TEST_RESULT_JSON envelope (v1)",
+  "description": "Single-line JSON document skf-test-skill emits when {headless_mode} is true, prefixed with the literal 'SKF_TEST_RESULT_JSON: ': once when the report step has written the result contract (status success for a scored run, status error with halt_reason hard-gate-blocked for a run the hard gate blocked), and once 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 (the report step's from scripts/build-result-context.py), derives a halt's exit_code from halt_reason, stamps run_id and result_path, and checks the line against this schema, so the model never types it. A skill run cannot set the exit status of the agent that runs it, so automators read exit_code from this line or from skf-test-skill-result-latest.json. The skill's references/invocation-contract.md describes each halt.",
+  "$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. No success_exit_code: a scored run's exit_code follows its verdict (0 PASS, 2 FAIL, 3 INCONCLUSIVE, 4 pass-with-drift), which build-result-context.py derives. Nothing in the schema references this entry, so it constrains no envelope.",
+      "const": {
+        "workflow": "skf-test-skill",
+        "prefix": "SKF_TEST_RESULT_JSON",
+        "wrapper": null,
+        "halt_status": "error",
+        "exit_codes": {
+          "input-missing": 1,
+          "input-invalid": 1,
+          "runtime-missing": 1,
+          "helper-missing": 1,
+          "helper-failed": 1,
+          "write-failed": 1,
+          "target-inaccessible": 1,
+          "not-skf-output": 1,
+          "frontmatter-invalid": 1,
+          "forge-tier-missing": 1,
+          "workspace-drift": 1,
+          "another-run-active": 1,
+          "inventory-invalid": 1,
+          "indeterminate-surface": 1,
+          "step-completeness-violation": 1,
+          "report-anchor-missing": 1,
+          "health-check-missing": 1,
+          "hard-gate-blocked": 2
+        },
+        "result_file": "skf-test-skill-result"
+      }
+    }
+  },
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "status",
+    "skill_name",
+    "verdict",
+    "score",
+    "threshold",
+    "report_path",
+    "next_workflow",
+    "exit_code",
+    "halt_reason",
+    "run_id",
+    "result_path"
+  ],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["success", "error"],
+      "description": "'success' when a scored run wrote its result contract (PASS, FAIL, INCONCLUSIVE or pass-with-drift: the workflow completed). 'error' on a HARD HALT, and on a run the hard gate blocked, which still writes the Gap Report and its FAIL result contract."
+    },
+    "skill_name": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "default": null,
+      "description": "The skill under test. Null only for a halt before the run had a name (a headless run given none halts input-missing)."
+    },
+    "verdict": {
+      "type": ["string", "null"],
+      "enum": ["PASS", "FAIL", "INCONCLUSIVE", "pass-with-drift", null],
+      "default": null,
+      "description": "The settled result: PASS, FAIL (a blocked run included), INCONCLUSIVE (the minimum-evidence floor) or pass-with-drift (a PASS under --allow-workspace-drift with drift observed, never exportable). Null on a halt before a verdict exists. The result file's summary.result spells the same verdict PASS, FAIL, INCONCLUSIVE or PASS_WITH_DRIFT."
+    },
+    "score": {
+      "type": ["number", "null"],
+      "minimum": 0,
+      "default": null,
+      "description": "The completeness score, in percent, from the scoring script. Null for a run the hard gate blocked (never scored) and on a halt."
+    },
+    "threshold": {
+      "type": ["number", "null"],
+      "minimum": 0,
+      "default": null,
+      "description": "The pass threshold the verdict was settled against, in percent: 80 when the threshold fallback fired (original_threshold holds the target). Null for a blocked run and on a halt."
+    },
+    "report_path": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "default": null,
+      "description": "The test report. A finished or blocked run names its published report, test-report-<skill>-<run_id>.md. A halt after the report was created names the in-progress copy, .skf-test-report-<skill>-<run_id>.md, which no consumer reads; null on a halt before it exists."
+    },
+    "next_workflow": {
+      "type": ["string", "null"],
+      "enum": ["export-skill", "update-skill", null],
+      "default": null,
+      "description": "\"export-skill\" only when verdict is PASS; \"update-skill\" for FAIL (a blocked run included) and pass-with-drift; null for INCONCLUSIVE (route to manual review) and on a halt."
+    },
+    "exit_code": {
+      "type": "integer",
+      "enum": [0, 1, 2, 3, 4],
+      "description": "The exit code the run settles on, for automators to branch on: 0 PASS, 2 FAIL (a blocked run's hard-gate-blocked included), 3 INCONCLUSIVE, 4 pass-with-drift, and 1 for every other halt_reason. A skill run cannot set the process exit status of the agent that runs it, so this field (or skf-test-skill-result-latest.json) is the place to read it."
+    },
+    "halt_reason": {
+      "type": ["string", "null"],
+      "enum": [
+        null,
+        "input-missing",
+        "input-invalid",
+        "runtime-missing",
+        "helper-missing",
+        "helper-failed",
+        "write-failed",
+        "target-inaccessible",
+        "not-skf-output",
+        "frontmatter-invalid",
+        "forge-tier-missing",
+        "workspace-drift",
+        "another-run-active",
+        "inventory-invalid",
+        "indeterminate-surface",
+        "step-completeness-violation",
+        "report-anchor-missing",
+        "health-check-missing",
+        "hard-gate-blocked"
+      ],
+      "description": "Null for a scored run. On a halt, the failure class: input-missing (headless with no skill name), input-invalid (a --tier value that names no tier), runtime-missing (python3 or uv is not on PATH), helper-missing (an SKF helper is not installed), helper-failed (a helper or scoring script exited with an error), write-failed (the run folder, the report or the result contract could not be written), target-inaccessible (no version of the skill to test), not-skf-output, frontmatter-invalid, forge-tier-missing, workspace-drift, another-run-active, inventory-invalid (the documented inventory failed its schema check or spot-check twice), indeterminate-surface (zero exports, or an empty stack surface: no score can be attached), step-completeness-violation, report-anchor-missing, health-check-missing; hard-gate-blocked for a run the hard gate blocked (verdict FAIL, exit 2)."
+    },
+    "run_id": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "description": "The run's id, stamped by the emitter from the run folder name: the UTC time the run took its lock and a random suffix, the {run_id} in the report's file name. 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 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)."
+    },
+    "threshold_fallback": {
+      "type": "boolean",
+      "const": true,
+      "description": "Present, and true, only when the threshold fallback accepted the run at the 80% floor; absent (never false or null) otherwise."
+    },
+    "original_threshold": {
+      "type": "number",
+      "minimum": 0,
+      "description": "The threshold the run was asked to meet, present only beside threshold_fallback."
+    },
+    "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: customization_resolver_unavailable when the customization resolver could not run, 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 the check, for example 'init:runtime' or 'report:anchors'."
+        },
+        "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-update-result-envelope.v1.json

@@ -2,7 +2,19 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-update-result-envelope.v1.json",
   "title": "SKF_UPDATE_RESULT_JSON envelope (v1)",
-  "description": "Single-line JSON document emitted by skf-update-skill step 7 (report) when {headless_mode} is true, prefixed with the literal 'SKF_UPDATE_RESULT_JSON: '. Pipelines branch on the envelope's top-level fields without parsing the human-readable report. The `headless_decisions[]` array surfaces every auto-resolved gate so non-interactive runs can be audited post-hoc — previously these were buried in the evidence report as free-form log lines. Schema added in PR #319.",
+  "description": "Single-line JSON document skf-update-skill emits when {headless_mode} is true, prefixed with the literal 'SKF_UPDATE_RESULT_JSON: ': once at the end of a run (step 6, report) and once at every halt. Every line, a halt's included, carries the skf_update wrapper, so pipelines branch on skf_update.status without parsing the human-readable report. The headless_decisions[] array surfaces every auto-resolved gate so non-interactive runs can be audited post-hoc.",
+  "$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 result file stem. Nothing in the schema references this entry, so it constrains no envelope.",
+      "const": {
+        "workflow": "skf-update-skill",
+        "prefix": "SKF_UPDATE_RESULT_JSON",
+        "wrapper": "skf_update",
+        "halt_status": "blocked",
+        "result_file": "update-skill-result"
+      }
+    }
+  },
   "type": "object",
   "additionalProperties": false,
   "required": ["skf_update"],
@@ -38,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 re-extract.md §0.a, brief-refinement from detect-changes.md §1c [U] / §2.2 [B], audit from §2.2 [A], remediation-path from re-extract.md §0a, manual-mismatch from write.md §1, write-failure for any §5b/§6 failure, concurrent-run from init.md §1b's PID-file collision check). 'blocked' is the catch-all for halts that don't map to a documented status code. 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, 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). error.reason names the run that holds a 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), 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",
@@ -48,7 +60,7 @@
         "version": {
           "type": "string",
           "minLength": 1,
-          "description": "Version written this run. In gap-driven mode this equals previous_version (gap-driven runs do not bump). In normal mode this is either the detected source version or an incremented patch."
+          "description": "Version written this run. In gap-driven mode this equals previous_version (gap-driven runs do not bump). In normal mode this is either the detected source version or an incremented patch, and names the new version folder the run created beside the previous one."
         },
         "previous_version": {
           "type": "string",
@@ -80,9 +92,11 @@
                 "type": "string",
                 "enum": [
                   "init.update-confirmation",
+                  "init.degraded-rebuild",
                   "detect-changes.promoted-doc-prompt",
                   "detect-changes.scope-expansion",
                   "detect-changes.deletion-ratio",
+                  "gap-driven.rescope",
                   "merge.clean-merge-gate"
                 ],
                 "description": "Identifier for the gate. Matches the labels in stage prose so post-hoc audits can grep both directions."
@@ -95,7 +109,7 @@
               "taken_action": {
                 "type": "string",
                 "minLength": 1,
-                "description": "The action actually taken. In headless mode this almost always equals default_action — the field exists so future user-overrides via flags (e.g. --orphan-action style) can differ from defaults."
+                "description": "The action actually taken. It differs from default_action where headless resolves a gate its own way: 'D' at init.degraded-rebuild under --allow-degraded, 'R' at gap-driven.rescope when gap-driven.md's rule R1 rescopes the export (one entry per gap, evidence.gap_id), and 'deferred-headless' at detect-changes.promoted-doc-prompt and detect-changes.scope-expansion, where a headless run decides nothing and leaves the path, recorded in the brief's scope.amendments[] as deferred-headless, for the next interactive run. One entry per path at those two gates (evidence.path)."
               },
               "reason": {
                 "type": "string",
@@ -114,7 +128,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, 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), 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, 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."
         },
         "error": {
           "oneOf": [