bmad-module-skill-forge 6.0.0 → 8.0.0

package/src/skf-campaign/scripts/campaign-state.py

@@ -80,8 +80,22 @@ Operations:
                     summary read from the sub-skill's result envelope line
                     (a file or `-`; the line's SKF_*_RESULT_JSON: prefix is
                     optional). A success envelope is recorded; an error
-                    envelope, or --no-capstone and the like, records null.
-                    A recorded verification also sets capstone.verified.
+                    envelope, or --no-capstone and the like (a stage
+                    skipped on purpose), records null. A line that does
+                    not parse, is not a JSON object, or has no string
+                    `status` or integer `exit_code` records null with halt
+                    reason result-unreadable in its not_recorded row (an
+                    empty line, or a file it cannot read or decode, is
+                    still exit 2). --no-result <field> (repeatable) records
+                    a sub-skill that printed no result line: null, with
+                    halt reason no-result in its not_recorded row; it does
+                    not go with that field's --<field> or --no-<field>.
+                    Each field it writes also sets
+                    campaign.stage_outcomes.<field>: `completed` with the
+                    envelope's exit_code, `skipped` for --no-<field>, or
+                    `failed` with the not_recorded row's halt_reason and
+                    exit_code. A recorded verification also sets
+                    capstone.verified.
   recover           Copy a .bak that validates over the primary (step-resume).
   archive           Move the state, its .bak and the brief, each one that
                     exists, into archive/<campaign name>-<UTC stamp>/ beside
@@ -130,7 +144,8 @@ CLI:
       --entry <text> [--entry <text> ...] [--stage <N>]
   uv run campaign-state.py set-campaign --state-file <p> [--architecture-doc-path <p>] \\
       [--capstone <p|-> | --no-capstone] [--verification <p|-> | --no-verification] \\
-      [--refinement <p|-> | --no-refinement] [--stage <N>]
+      [--refinement <p|-> | --no-refinement] \\
+      [--no-result capstone|verification|refinement ...] [--stage <N>]
   uv run campaign-state.py recover --state-file <p>
   uv run campaign-state.py archive --state-file <p> --brief-file <p>
   uv run campaign-state.py log --log-file <p> --type <decision|auto|event> --text <entry>
@@ -144,7 +159,9 @@ Output (one JSON object on stdout):
              "last_updated", "current_stage", "changed": [...]} plus the
              operation's own keys (init: "quality_gate", "brief_file", null
              without --brief-out; apply-batch: "activated", "skipped",
-             "completed", "failed"; set-campaign: "recorded", "not_recorded")
+             "completed", "failed"; set-campaign: "recorded", and
+             "not_recorded", one {"field", "status", "halt_reason",
+             "exit_code"} row for each field it set to null)
   recover:  {"op", "state_file", "backup_file", "recovered", "last_updated",
              "current_stage"}
   archive:  {"op", "archive_dir", "moved": [...]}
@@ -161,8 +178,8 @@ Exit codes (each is the campaign's HALT code for the same class):
   2  invalid input: a missing or unreadable input file, an unknown skill,
      output from another script that holds an error, a gate the gate script
      rejects, a state that init would overwrite, a brief template that is
-     no YAML mapping, export flags that do not go together, or an archive
-     folder that exists
+     no YAML mapping, export flags or set-campaign flags that do not go
+     together, or an archive folder that exists
   3  invalid state: the state is missing, malformed or fails the schema, or
      the change would make it fail (nothing written)
   4  apply-plan: a plan the stages cannot follow (circular-deps)
@@ -417,8 +434,16 @@ def read_json(source: str, label: str) -> dict:
     return data
 
 
-def read_envelope(source: str, label: str) -> dict:
-    """A sub-skill's result envelope: the last SKF_*_RESULT_JSON line, or bare JSON."""
+def read_envelope(source: str, label: str) -> dict | None:
+    """A sub-skill's result envelope: the last SKF_*_RESULT_JSON line, or bare JSON.
+
+    None when that payload does not parse or is not a JSON object, which
+    set-campaign records as result-unreadable. json.loads raises ValueError
+    on a payload it cannot parse (JSONDecodeError is one, an integer of more
+    than 4,300 digits another) and RecursionError on nesting too deep for
+    it; both read as a payload that does not parse. An empty payload, or
+    input it cannot read or decode, is still exit 2.
+    """
     text = read_text(source, label)
     lines = [line for line in text.splitlines() if "_RESULT_JSON:" in line and "SKF_" in line]
     payload = lines[-1].split("_RESULT_JSON:", 1)[1].strip() if lines else text.strip()
@@ -426,11 +451,9 @@ def read_envelope(source: str, label: str) -> dict:
         raise StateError(EXIT_INPUT, "input-unreadable", f"{label} holds no result envelope")
     try:
         data = json.loads(payload)
-    except json.JSONDecodeError as exc:
-        raise StateError(EXIT_INPUT, "input-unreadable", f"{label} is not a result envelope: {exc}") from exc
-    if not isinstance(data, dict):
-        raise StateError(EXIT_INPUT, "input-unreadable", f"{label} is not a JSON object")
-    return data
+    except (ValueError, RecursionError):
+        return None
+    return data if isinstance(data, dict) else None
 
 
 def _skills_by_name(state: dict) -> dict[str, dict]:
@@ -786,7 +809,31 @@ def _refinement(envelope: dict, stamp: str) -> dict | None:
 SUMMARIES = (("capstone", _capstone), ("verification", _verification), ("refinement", _refinement))
 
 
+def _readable(envelope: dict | None) -> bool:
+    """An envelope set-campaign can read: an object with a string `status` and an integer `exit_code`.
+
+    The SS, VS and RA envelope schemas all require both, so a line missing
+    either is recorded result-unreadable, as step-10 records an Export line.
+    """
+    if not isinstance(envelope, dict):
+        return False
+    exit_code = envelope.get("exit_code")
+    return isinstance(envelope.get("status"), str) and isinstance(exit_code, int) and not isinstance(exit_code, bool)
+
+
+def _failed_outcome(row: dict) -> dict:
+    """The stage outcome of a field set-campaign did not record, from its not_recorded row."""
+    reason = row["halt_reason"]
+    return {"outcome": "failed", "halt_reason": reason if isinstance(reason, str) else None,
+            "exit_code": row["exit_code"]}
+
+
 def op_set_campaign(args: argparse.Namespace) -> dict:
+    no_result = set(args.no_result or ())
+    for field, _build in SUMMARIES:
+        if field in no_result and (getattr(args, field) is not None or getattr(args, f"no_{field}")):
+            raise StateError(EXIT_INPUT, "input-invalid",
+                             f"--no-result {field} does not go with --{field} or --no-{field}")
     envelopes = {}
     for field, _build in SUMMARIES:
         source = getattr(args, field)
@@ -800,21 +847,36 @@ def op_set_campaign(args: argparse.Namespace) -> dict:
             campaign["architecture_doc_path"] = args.architecture_doc_path
             changed.append("campaign.architecture_doc_path")
         for field, build in SUMMARIES:
-            if field in envelopes:
+            # Each branch decides the stage outcome; a failed one takes its row's halt_reason and exit_code.
+            if field in envelopes and not _readable(envelopes[field]):
+                value = None
+                row = {"field": field, "status": None, "halt_reason": "result-unreadable", "exit_code": None}
+                not_recorded.append(row)
+                outcome = _failed_outcome(row)
+            elif field in envelopes:
                 envelope = envelopes[field]
                 value = build(envelope, stamp)
                 if value is None:
-                    not_recorded.append({"field": field, "status": envelope.get("status"),
-                                         "halt_reason": envelope.get("halt_reason"),
-                                         "exit_code": envelope.get("exit_code")})
+                    row = {"field": field, "status": envelope.get("status"),
+                           "halt_reason": envelope.get("halt_reason"), "exit_code": envelope.get("exit_code")}
+                    not_recorded.append(row)
+                    outcome = _failed_outcome(row)
                 else:
                     recorded.append(field)
+                    outcome = {"outcome": "completed", "halt_reason": None, "exit_code": envelope["exit_code"]}
             elif getattr(args, f"no_{field}"):
                 value = None
                 not_recorded.append({"field": field, "status": None, "halt_reason": None, "exit_code": None})
+                outcome = {"outcome": "skipped", "halt_reason": None, "exit_code": None}
+            elif field in no_result:
+                value = None
+                row = {"field": field, "status": None, "halt_reason": "no-result", "exit_code": None}
+                not_recorded.append(row)
+                outcome = _failed_outcome(row)
             else:
                 continue
             campaign[field] = value
+            campaign.setdefault("stage_outcomes", {})[field] = outcome
             changed.append(f"campaign.{field}")
             if field == "verification" and isinstance(campaign.get("capstone"), dict):
                 verdict = (value or {}).get("overall_verdict")
@@ -1054,6 +1116,9 @@ def build_parser() -> argparse.ArgumentParser:
         group = p.add_mutually_exclusive_group()
         group.add_argument(f"--{field}", help=f"the {field} sub-skill's result envelope line, a file or -")
         group.add_argument(f"--no-{field}", action="store_true", help=f"record campaign.{field} as null")
+    p.add_argument("--no-result", action="append", choices=[f for f, _ in SUMMARIES], metavar="FIELD",
+                   help="record the field as null with halt reason no-result: its sub-skill printed no "
+                        "result line (repeat for several; not with that field's --FIELD or --no-FIELD)")
 
     command("recover", "copy a valid .bak over the primary", stage=None)
 

package/src/skf-campaign/templates/campaign-report-template.md

@@ -21,6 +21,10 @@
 |------|------|--------|---------------|-----|-------------|
 {{skills_table}}
 
+## Stages
+
+{{stages_section}}
+
 ## Export Gate
 
 {{export_gate_section}}

package/src/skf-create-skill/SKILL.md

@@ -65,8 +65,8 @@ These rules apply to every step in this workflow:
 |--------|--------|
 | **Inputs** | brief_path (a skill-brief.yaml path or a skill name) [optional: without it, step 1 offers the briefs in `{forge_data_folder}`, and a headless run halts unless there is one], --batch [optional: the briefs or folders of briefs after it, `{forge_data_folder}` when none is given, each validated before the first compiles] |
 | **Gates** | step 1: Brief Selection (no brief named and several in `{forge_data_folder}`; headless: HARD HALT `brief-missing`, exit 2; one brief: picked and recorded as gate `brief-selection`) | step 3: Tag Choice Gate (several tags match the brief's version; headless: the first in priority order) | step 3 §2a: Authoritative-File Gate [P]/[S]/[U] (an authoritative AI documentation file outside the brief's scope; headless: deferred-headless, one auto-decision per path) | step 3: Review Gate [C]/[R] (with the zero-export warning when a source brief without `doc_urls` extracted no export; [R] with it or the head-cap warning) | step 3c: Zero-Export Gate [C]/[R] (a source brief with no export whose every `doc_urls` fetch failed) | step 3d: Demo-Exclusion Gate [Y], then Registry Gate [Y] (candidate found) or [S] (none found), component-library scope only, each skipped once the brief holds `scope.demo_patterns` or `scope.registry_path`, which step 3d writes when a user confirms or gives the patterns or the registry path |
-| **Outputs** | SKILL.md, context-snippet.md, metadata.json, provenance-map.json, evidence-report.md, extraction-rules.yaml, references/; per brief, the result contract (`create-skill-result-{YYYYMMDD-HHmmss}.json` and its `-latest.json` copy in `{forge_version}`) and one `SKF_CREATE_SKILL_RESULT_JSON` line on stdout, on stderr at a HARD HALT |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true; each auto-decision reaches the envelope's and the result contract's `headless_decisions`. A caller reads the run's own `SKF_CREATE_SKILL_RESULT_JSON` line. A run that printed no envelope line has no result to read, whatever the process exit code: it was cut off, or could not write its result, and `create-skill-result-latest.json` may then describe an earlier run, so it is never read in its place. |
+| **Outputs** | SKILL.md, context-snippet.md, metadata.json, provenance-map.json, evidence-report.md, extraction-rules.yaml, references/; per brief, the result contract (`create-skill-result-{YYYYMMDD-HHmmss}.json` and its `-latest.json` copy in `{forge_version}`) and one `SKF_CREATE_SKILL_RESULT_JSON` line on stdout, on stderr at a HARD HALT; and under `--batch` the batch summary (`create-skill-batch-{YYYYMMDD-HHmmss}.json` and its `-latest.json` copy in `{skills_output_folder}/_batch/`) |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true; each auto-decision reaches the envelope's and the result contract's `headless_decisions`. A caller reads the run's own `SKF_CREATE_SKILL_RESULT_JSON` line. A run that printed no envelope line has no result to read, whatever the process exit code: it was cut off, or could not write its result, and `create-skill-result-latest.json` may then describe an earlier run, so it is never read in its place. Under `--batch`, a caller reads the batch's `batch_summary` event and the summary file its `summary_path` names, never `create-skill-batch-latest.json` in its place: that copy holds the last batch summary written, which may be another batch's. A printed `batch_summary` event stays the batch's result even if a halt line follows it. A batch that printed no `batch_summary` event has no batch result, whatever the process exit code: a halt line of its own (phase `batch-mode`) says why it stopped, and with no halt line it was cut off or could not print its halt line. A target it printed a `done` or `fail` event for ended as that event says, and a brief the plan listed as not compiled ended failed with its message; a target with a `start` event and no end event has no result, and any other target with no event did not run in this session. |
 | **Exit codes** | 0 for a finished brief; at a HARD HALT 2 (the brief is missing, malformed or invalid), 3 (no forge config, source, helper or documentation), 4 (a write failed), 5 (a refused or broken package), 6 (the user chose to refine the scope). A `--batch` run exits with the highest code among its briefs, 0 when every brief finished |
 
 ## On Activation

package/src/skf-create-skill/assets/skill-sections.md

@@ -283,7 +283,7 @@ t2_future_count: {N}
 - Schema: {pass/fail} (quality score: {score}/100)
 - Frontmatter: {pass/fail}
 - Body: {pass/fail} {body split applied if applicable}
-- Security: {pass/warn/skipped}
+- Security: {pass/warn/skipped} ({the note §5's Security row gives})
 - Description angle brackets: {none | re-sanitized ({count} substitutions) | not checked — no description}
 - Tessl Review: {tessl_summary}
 - Metadata: {pass/fail}
@@ -300,7 +300,7 @@ t2_future_count: {N}
 - Notes: {one-sentence detail or —}
 
 ## Auto-Fixed Issues
-- {list of issues automatically corrected by --fix}
+- {"skill-check --fix rewrote SKILL.md" when §2 recorded `skill_check_fix_changed: true`, "SKILL.md may have been rewritten (not hashed) by skill-check --fix" when it recorded `skill_check_fix_changed: unchecked`, otherwise "none"}
 
 ## Remaining Warnings
 - {any warnings from extraction or validation}

package/src/skf-create-skill/customize.toml

@@ -50,10 +50,10 @@ persistent_facts = [
 # run a skill such as test-skill or export-skill. It is called as:
 #   <on_complete> --result-path=<{forge_version}/create-skill-result-latest.json>
 # Under --batch it runs once per brief, each time with that brief's result
-# file; a brief that halts, or whose result file was not written, gets no
-# call. Useful for a Slack or email notifier, dashboard ingest, a CI script
-# or a git-add wrapper. A failure is reported on its own line and never
-# fails the brief.
+# file; a brief that halts, or whose result file or its -latest copy was
+# not written, gets no call. Useful for a Slack or email notifier,
+# dashboard ingest, a CI script or a git-add wrapper. A failure is reported
+# on its own line and never fails the brief.
 #
 # Empty string = no-op (default).
 

package/src/skf-create-skill/references/batch-mode.md

@@ -78,4 +78,6 @@ The helper counts the briefs, sets the batch status and exit code, writes the su
 
 Then load, read in full and execute `{healthCheckStepFile}`: the health check runs once per batch, here. The batch ends with the event's `exit_code`: 0 when every brief finished, else the highest exit code among the briefs that failed.
 
-If `summarize` exits non-zero (a brief is still pending, or the batch file is gone or unreadable), the health check does not run: display "**The batch stopped:** {its `message`}" and **HARD HALT** (exit code 4, `write-failed`, phase `batch-mode`; emit with nothing to stage in, as §1 does, with the reason "The batch stopped: <its message>"). The summary files may be missing then, but each brief's own result contract is in its `{forge_version}`.
+**Reading a batch.** Under `--batch`, a caller reads the batch's `batch_summary` event and the summary file its `summary_path` names, never `create-skill-batch-latest.json` in its place: that copy holds the last batch summary written, which may be another batch's. The event comes before the health check, so a caller reads it from the session's output stream (`claude -p --output-format stream-json`) or transcript, not from the final message. A printed `batch_summary` event stays the batch's result even if a halt line follows it. A batch that printed no `batch_summary` event has no batch result, whatever the process exit code: a halt line of its own (phase `batch-mode`) says why it stopped, and with no halt line it was cut off or could not print its halt line. A target it printed a `done` or `fail` event for ended as that event says, and a brief the plan listed as not compiled ended failed with its message; a target with a `start` event and no end event has no result, and any other target with no event did not run in this session. When the event's `summary_path` is null, the per-batch file was not written (its `summary_write_failed` warning says why): the event and `{batch_dir}/batch.jsonl`, which the helper then keeps, are the batch's result, never `create-skill-batch-latest.json`. A `summary_write_failed` warning beside a set `summary_path` means only the `-latest` copy failed: the file it names is still the batch's result. After a cut-off batch, run `--batch` again with the same briefs: while the batch has no summary, it finds the batch folder again and goes on with the brief it was working on (Execution, above). If `summarize` already ran but its event never reached the caller, `start` begins a new batch from the first brief, and that batch's summary is the per-batch file in `{skills_output_folder}/_batch/` whose `input_briefs` match.
+
+If `summarize` exits non-zero (a brief is still pending, or the batch file is gone or unreadable), the health check does not run: display "**The batch stopped:** {its `message`}" and **HARD HALT** (exit code 4, `write-failed`, phase `batch-mode`; emit with nothing to stage in, as §1 does, with the reason "The batch stopped: <its message>"). The summary files may be missing then, but each brief's own result contract is in its `{forge_version}`, and `create-skill-batch-latest.json` may be another batch's, so it is never read in its place.

package/src/skf-create-skill/references/report.md

@@ -107,11 +107,11 @@ Every brief that reaches this step gets its own result contract and `on_complete
 grep -c . "{run_dir}/headless-decisions.jsonl" 2>/dev/null; grep -c '"gate":"zero-exports"' "{run_dir}/headless-decisions.jsonl" 2>/dev/null
 ```
 
-Bind `{auto_decision_count}` ← the first count (0 when the file is missing), the rows of the evidence report's `## Auto-Decisions` table, so a consumer can tell from the result alone whether any gate auto-resolved. Bind `{run_status}` ← `partial` when the second count is above 0 (a headless run went on past zero exports at step 3), else `success`. Take `exports_documented` (`stats.exports_documented`) and `confidence_distribution` from the promoted `metadata.json`. Stage the payload with these values and `{auto_decision_count}` in place of the template's zeros, in both `summary` objects, adding `"warning": "zero-exports"` to both when `{run_status}` is `partial`, and run the emitter:
+Bind `{auto_decision_count}` ← the first count (0 when the file is missing), the rows of the evidence report's `## Auto-Decisions` table, so a consumer can tell from the result alone whether any gate auto-resolved. Bind `{run_status}` ← `partial` when the second count is above 0 (a headless run went on past zero exports at step 3), else `success`. Take `exports_documented` (`stats.exports_documented`) and `confidence_distribution` from the promoted `metadata.json`. Bind `{security_result}` ← the first word of the `- Security:` line under `## Validation Results` in the promoted `{forge_version}/evidence-report.md` (`pass`, `warn` or `skipped`), the security scan's outcome step 6 recorded; when that line is missing or starts with another word, leave `security_result` out of both `summary` objects. Stage the payload with these values and `{auto_decision_count}` in place of the template's zeros, in both `summary` objects, adding `"warning": "zero-exports"` to both when `{run_status}` is `partial`, and run the emitter:
 
 ```bash
 cat > "{run_dir}/result-context.json" <<'SKF_JSON'
-{"status": "{run_status}", "phase": null, "halt_reason": null, "error": null, "skill_package": "{skill_package}", "outputs": {"skill_md": "{skill_package}/SKILL.md", "context_snippet": "{skill_package}/context-snippet.md", "metadata": "{skill_package}/metadata.json", "references": "{skill_package}/references", "provenance_map": "{forge_version}/provenance-map.json", "evidence_report": "{forge_version}/evidence-report.md", "extraction_rules": "{forge_version}/extraction-rules.yaml"}, "summary": {"skill_name": "{name}", "version": "{version}", "forge_tier": "{tier}", "exports_documented": 0, "confidence_distribution": {"t1": 0, "t1_low": 0, "t2": 0, "t3": 0}, "auto_decision_count": 0}, "result_contract": {"skill": "skf-create-skill", "status": "{run_status}", "outputs": [{"type": "skill", "path": "{skill_package}/SKILL.md"}, {"type": "skill", "path": "{skill_package}/context-snippet.md"}, {"type": "skill", "path": "{skill_package}/metadata.json"}, {"type": "report", "path": "{forge_version}/evidence-report.md"}], "summary": {"skill_name": "{name}", "version": "{version}", "exports_documented": 0, "confidence_distribution": {"t1": 0, "t1_low": 0, "t2": 0, "t3": 0}, "auto_decision_count": 0}}}
+{"status": "{run_status}", "phase": null, "halt_reason": null, "error": null, "skill_package": "{skill_package}", "outputs": {"skill_md": "{skill_package}/SKILL.md", "context_snippet": "{skill_package}/context-snippet.md", "metadata": "{skill_package}/metadata.json", "references": "{skill_package}/references", "provenance_map": "{forge_version}/provenance-map.json", "evidence_report": "{forge_version}/evidence-report.md", "extraction_rules": "{forge_version}/extraction-rules.yaml"}, "summary": {"skill_name": "{name}", "version": "{version}", "forge_tier": "{tier}", "exports_documented": 0, "confidence_distribution": {"t1": 0, "t1_low": 0, "t2": 0, "t3": 0}, "auto_decision_count": 0, "security_result": "{security_result}"}, "result_contract": {"skill": "skf-create-skill", "status": "{run_status}", "outputs": [{"type": "skill", "path": "{skill_package}/SKILL.md"}, {"type": "skill", "path": "{skill_package}/context-snippet.md"}, {"type": "skill", "path": "{skill_package}/metadata.json"}, {"type": "report", "path": "{forge_version}/evidence-report.md"}], "summary": {"skill_name": "{name}", "version": "{version}", "exports_documented": 0, "confidence_distribution": {"t1": 0, "t1_low": 0, "t2": 0, "t3": 0}, "auto_decision_count": 0, "security_result": "{security_result}"}}}
 SKF_JSON
 uv run {emitEnvelopeHelper} emit --workflow skf-create-skill --run-dir "{run_dir}" --result-dir "{forge_version}" < "{run_dir}/result-context.json"
 ```
@@ -126,13 +126,18 @@ The evidence report in `outputs` carries the `## Auto-Decisions` audit table: a
 uv run {resolveCustomizationHelper} --skill {skill-root} --project-root {project-root} --key workflow.on_complete
 ```
 
-When `{onCompleteCommand}` is non-empty and the emitter wrote this brief's result contract (its `emit` exited 0), run it as a shell command from `{project-root}`, for this brief:
+When `{onCompleteCommand}` is non-empty and the emitter wrote this brief's result contract (its `emit` exited 0, the line's `result_path` is not null and its `warnings` hold no `result_file_write_failed` entry naming `create-skill-result-latest.json`), run it as a shell command from `{project-root}`, for this brief:
 
 ```bash
 {onCompleteCommand} --result-path={forge_version}/create-skill-result-latest.json
 ```
 
-The hook runs after the contract, so a git-add, registry registration or notifier sees a complete package. A hook failure never fails the brief, since the skill is written and its result contract is final: display "on_complete failed for `{name}`: {its exit code and first stderr line}" and go on. When the emitter wrote no result contract for this brief (no path in `{emitEnvelopeProbeOrder}` exists, or `emit` failed twice), `--result-path` would name a missing file or an earlier compile's: skip the hook and display "on_complete skipped for `{name}`: no result contract was written ({the reason})". When `{onCompleteCommand}` is empty (bundled default), skip the invocation entirely.
+The hook runs after the contract, so a git-add, registry registration or notifier sees a complete package. A hook failure never fails the brief, since the skill is written and its result contract is final: display "on_complete failed for `{name}`: {its exit code and first stderr line}" and go on. When `{onCompleteCommand}` is non-empty but the hook does not run, `--result-path` would name a missing file or an earlier compile's: skip the hook and display the line for its case:
+
+- No `emit` succeeded (no path in `{emitEnvelopeProbeOrder}` exists, or `emit` failed twice): "on_complete skipped for `{name}`: no result contract was written ({the reason})".
+- `emit` exited 0, but the line's `result_path` is null (the per-run record was not written) or a `result_file_write_failed` warning names `create-skill-result-latest.json` (the copy alone failed): "on_complete skipped for `{name}`: `create-skill-result-latest.json` was not written".
+
+When `{onCompleteCommand}` is empty (bundled default), skip the invocation entirely.
 
 **Remove the run folder.** The brief finished, so outside `--batch` delete `{run_dir}` (`rm -rf "{run_dir}"`); under `--batch`, batch-mode.md §3 reads the staged `result-context.json` there and removes the folder itself. A halted brief keeps its folder, with the decisions it recorded and its staged payloads.
 

package/src/skf-create-skill/references/validate.md

@@ -15,6 +15,13 @@ atomicWriteProbeOrder:
 descriptionGuardProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-description-guard.py'
   - '{project-root}/src/shared/scripts/skf-description-guard.py'
+# Resolve `{hashContentHelper}` by probing `{hashContentProbeOrder}` in order
+# (installed SKF module path first, src/ dev-checkout fallback); first existing
+# path wins. Advisory: if neither resolves, §2 hashes nothing and reports that
+# SKILL.md may have been rewritten (not hashed) by skill-check --fix.
+hashContentProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-hash-content.py'
+  - '{project-root}/src/shared/scripts/skf-hash-content.py'
 # Resolve `{frontmatterValidator}` by probing `{frontmatterValidatorProbeOrder}`
 # in order (installed SKF module path first, src/ dev-checkout fallback); first
 # existing path wins.
@@ -90,7 +97,7 @@ To validate the compiled SKILL.md content against the agentskills.io specificati
 - Validation and auto-fix modify files in the staging directory
 - `<staging-skill-dir>` resolves to `_bmad-output/.skf-stage/{skill-name}/` as created by step 5. Its last folder name must match the skill's frontmatter `name` field exactly — `skill-check`'s `frontmatter.name_matches_directory` rule rejects any suffix.
 - If skill-check unavailable: skip validation, add warning to evidence report
-- Ignore non-zero exit codes from skill-check if JSON output shows 0 errors
+- For the validation verdict, ignore non-zero exit codes from skill-check if JSON output shows 0 errors; the security scan's row follows its exit code and stderr tail (§5)
 - Tessl Review (§6b) is optional and advisory: it never halts, never asks the user anything and never changes the staged files, and SKF applies none of its suggestions
 - A HARD HALT, once step 3 §2b has bound `{source_tree}`, first runs `uv run {sourceTreeHelper} close --tree "{source_tree}"` from `{project-root}` (resolved from `{sourceTreeProbeOrder}`) and goes on whatever it prints, and emits through `{emitEnvelopeHelper}`, resolved from `{emitEnvelopeProbeOrder}` when it is not bound. After its envelope, under `--batch` it ends only this brief: return to `references/batch-mode.md` §3, even when the halt reads as the end of the run.
 
@@ -104,9 +111,9 @@ To validate the compiled SKILL.md content against the agentskills.io specificati
 
 The deterministic phases are executed via `{descriptionGuardHelper}`: the calling sections (§2 and §4) invoke the helper at the capture and verify-restore points.
 
-**Guard outputs.** Bind `{guarded_description}` ← `description` from each `capture`, which reads the staged `<staging-skill-dir>/SKILL.md` just before the tool that may rewrite it. Bind `{guard_restored}` ← `restored` and `{guard_diff_kind}` ← `diff_kind` from each `verify-restore`. When `{guard_restored}` is true, set the in-context `description` to `{guarded_description}` so later sections do not work from the tool-mutated value, and record `description_guard_restored: true` with the tool name and `description_guard_diff_kind: {guard_diff_kind}` in workflow context for the evidence report (§8). A later `verify-restore` that exits 0 with `{guard_restored}` false leaves those records in place.
+**Guard outputs.** Each `capture` writes the description it reads from the staged `<staging-skill-dir>/SKILL.md`, just before the tool that may rewrite it, to `{run_dir}/description-guard.json`, and each `verify-restore` reads it there with `--captured-file`, so the description never passes through a shell string. Bind `{guarded_description}` ← that file's `description`. Bind `{guard_restored}` ← `restored` and `{guard_diff_kind}` ← `diff_kind` from each `verify-restore`. When `{guard_restored}` is true, set the in-context `description` to `{guarded_description}` so later sections do not work from the tool-mutated value, and record `description_guard_restored: true` with the tool name and `description_guard_diff_kind: {guard_diff_kind}` in workflow context for the evidence report (§8). A later `verify-restore` that exits 0 with `{guard_restored}` false leaves those records in place.
 
-**Empty-snapshot rule.** `verify-restore` refuses an empty or whitespace-only `--captured-description` (exit 1, file untouched). Never re-run it with the empty value: writing it back would blank the field the guard protects. If the description compile §2a sanitized is still in context (an in-context copy of the description, not of the file), re-run `verify-restore` with that value. Otherwise record `description_guard_restored: false` and `description_guard_refused: empty-capture` with the tool name; the evidence report (§8) renders that as a fired guard, not as a clean run.
+**Empty-snapshot rule.** `verify-restore` refuses an empty or whitespace-only description in `{run_dir}/description-guard.json`, and a file it cannot read (exit 1, file untouched). Never re-run it with the empty value: writing it back would blank the field the guard protects. If the description compile §2a sanitized is still in context (an in-context copy of the description, not of the file), re-run `verify-restore` with that value: write `{"description": <that value as a JSON string>}` to `{run_dir}/description-guard.json` with a file write, never `echo` (the value can hold quotes, `$` or backticks), and run the same `verify-restore` line again, once. Otherwise, or when that re-run exits 1 too, record `description_guard_restored: false` and `description_guard_refused: empty-capture` with the tool name; the evidence report (§8) renders that as a fired guard, not as a clean run.
 
 **This skill's post-restore re-validation hook:** after `{descriptionGuardHelper}` reports `restored: true`, resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}` (first existing path wins), run `uv run {frontmatterValidator} <staging-skill-dir>/SKILL.md` and capture `schema_revalidation_result` in context. If the validator exits non-zero OR reports failure for the `description` field, flip the Schema result back to `FAIL` in the evidence report (overriding any prior PASS/WARN from §2), record `description_guard_revalidation: FAIL` with the validator's diagnostic message, and continue — do not halt (step 9 health-check and result contract still need to run so the failure is surfaced through the normal artifact path).
 
@@ -133,32 +140,39 @@ npx skill-check check --help 2>/dev/null | grep -- --no-security-scan
 - Else run a second probe — `npx skill-check check --help 2>/dev/null | grep -- --skip-security` — and if it matches, set `{security_scan_flag} = "--skip-security"`.
 - If neither flag exists: set `{security_scan_flag} = ""` (empty) AND set `{skill_check_flag_fallback} = true`. Skip §2 and §4 automated flows entirely — fall through to §3 manual frontmatter validation. Record in evidence-report: `skill_check_flag_probe: neither --no-security-scan nor --skip-security supported by installed skill-check; validation performed manually`.
 
-**If a security-scan-disable flag was resolved (probe succeeded):**
-
-```bash
-npx skill-check check <staging-skill-dir> --fix --format json {security_scan_flag}
-```
+**If a security-scan-disable flag was resolved (probe succeeded):** run the `skill-check check --fix` call where the Description Guard block below holds it (its Phase 2), never before that block's first `hash` and its `capture`.
 
 This performs frontmatter validation, description quality checks, body limit enforcement, local link resolution, file formatting, auto-fix of deterministic issues, and quality scoring (0-100) across five weighted categories.
 
-**Parse the JSON output** for: `scores[].score` (0-100 — match the entry by `relativePath`/`skillId`; falls back to a top-level `qualityScore` on older skill-check builds), `diagnostics[]` (remaining issues), `fixed[]` (auto-corrected issues).
+**Parse the JSON output** of the Phase 2 call below for: `scores[].score` (0-100; match the entry by `relativePath`/`skillId`; falls back to a top-level `qualityScore` on older skill-check builds) and `diagnostics[]` (remaining issues). skill-check's JSON lists no fix: the two `hash` calls below tell whether `--fix` changed SKILL.md.
 
-**Description Guard Protocol:** This invocation may modify SKILL.md (especially when `fixed[]` is non-empty). Wrap the `skill-check check --fix` call in the four-phase guard defined in §0 by invoking `{descriptionGuardHelper}` at the capture and verify-restore points:
+**Description Guard Protocol:** This invocation may modify SKILL.md. Wrap the `skill-check check --fix` call in the four-phase guard defined in §0 by invoking `{descriptionGuardHelper}` at the capture and verify-restore points, and hash SKILL.md with `{hashContentHelper}` (resolve it ← first existing path in `{hashContentProbeOrder}`) before the capture and after the verify-restore:
 
 ```bash
-# Phase 1 — capture before the tool call
-uv run {descriptionGuardHelper} capture <staging-skill-dir>/SKILL.md
-# stash the returned `description` as `guarded_description` in workflow context
+# Before the guard: hash SKILL.md
+uv run {hashContentHelper} hash <staging-skill-dir>/SKILL.md
+# stash the returned `content_hash` as `skill_md_hash_before`
+
+# Phase 1: capture before the tool call
+uv run {descriptionGuardHelper} capture <staging-skill-dir>/SKILL.md > "{run_dir}/description-guard.json"
+# the snapshot lands in the run folder; read its `description` as `guarded_description`
 
-# Phase 2 — run skill-check (see command block above)
+# Phase 2: run skill-check
+npx skill-check check <staging-skill-dir> --fix --format json {security_scan_flag}
 
-# Phases 3+4 — verify and restore after the tool call
+# Phases 3+4: verify and restore after the tool call
 uv run {descriptionGuardHelper} verify-restore <staging-skill-dir>/SKILL.md \
-    --captured-description "{guarded_description}"
+    --captured-file "{run_dir}/description-guard.json"
+
+# After the guard: hash SKILL.md again
+uv run {hashContentHelper} hash <staging-skill-dir>/SKILL.md
+# stash the returned `content_hash` as `skill_md_hash_after`
 ```
 
 If `restored: true` in the verify-restore output, apply §0's post-restore re-validation hook. Step 7 promotes the staged files as they are on disk, `--fix` changes included.
 
+Run the second `hash` call after the last `verify-restore`, a §0 re-run included. When `skill_md_hash_before` and `skill_md_hash_after` differ, record `skill_check_fix_changed: true` for §8. When no `{hashContentProbeOrder}` path exists (skip both `hash` calls) or a `hash` call prints no `content_hash`, record `skill_check_fix_changed: unchecked` whatever the other call printed, so §8 says SKILL.md may have been rewritten.
+
 **Note:** `skill-check` may return non-zero exit code even when `summary.errorCount` is 0. Always rely on parsed JSON, not the shell exit code.
 
 - **Score ≥ 70:** Record "Schema: PASS (score: {score}/100)" in evidence-report
@@ -186,15 +200,15 @@ If fails: auto-fix (deterministic), re-validate once, record result. If passes:
 
 ```bash
 # Phase 1: capture before the split
-uv run {descriptionGuardHelper} capture <staging-skill-dir>/SKILL.md
-# stash returned `description` as `guarded_description`
+uv run {descriptionGuardHelper} capture <staging-skill-dir>/SKILL.md > "{run_dir}/description-guard.json"
+# the snapshot lands in the run folder; read its `description` as `guarded_description`
 
 # Phase 2: the split
 uv run {shardBodyHelper} <staging-skill-dir>/SKILL.md --budget 400
 
 # Phases 3 and 4: verify and restore after the split
 uv run {descriptionGuardHelper} verify-restore <staging-skill-dir>/SKILL.md \
-    --captured-description "{guarded_description}"
+    --captured-file "{run_dir}/description-guard.json"
 ```
 
 If `restored: true` in the verify-restore output, apply §0's post-restore re-validation hook.
@@ -214,20 +228,26 @@ Then re-validate: `npx skill-check check <staging-skill-dir> --format json {secu
 **If skill-check available:**
 
 ```bash
-npx skill-check check <staging-skill-dir> --format json
+npx skill-check check <staging-skill-dir> --format json > "{run_dir}/skill-check.json" 2> "{run_dir}/skill-check.stderr"; echo "skill-check exited $?"
 ```
 
-(Security scan enabled by default when `--no-security-scan` omitted. The scan uses [Snyk](https://docs.snyk.io/) to check for prompt injection risks, sensitive data exposure, and unsafe tool permissions.)
+(Security scan enabled by default when `--no-security-scan` omitted. The scan uses [Snyk](https://docs.snyk.io/) to check for prompt injection risks, sensitive data exposure, and unsafe tool permissions.) The call keeps stdout, stderr and the exit code apart. Give it the longest timeout your shell tool takes. When no "skill-check exited" line came back, the shell tool stopped the call before skill-check finished (a cold `uvx mcp-scan` install can outlast its timeout).
 
-Record any security warnings in evidence-report. Security findings are advisory — they do not block artifact generation. If the full validation re-run produces a different quality score than section 2, update the evidence-report with the newer score.
+**Score refresh.** stdout can go on after the JSON (a `Wrote <path>` line when the project config sets a report path), so read only the JSON object at the start of `{run_dir}/skill-check.json`. If its quality score differs from section 2's, update the evidence-report with the newer score. When the file does not start with a JSON object (exit 2 on a config, option or plugin error, or a stopped call), keep section 2's score.
 
-**If security scan fails due to missing SNYK_TOKEN:**
+**Read the JSON, not the exit code.** skill-check prints its JSON before the security scan runs, then exits 1 when `summary.errorCount` is above 0, when `--strict` or `--fail-on-warning` is passed and `summary.warningCount` is above 0 (this call passes neither), or when the scan exits non-zero, and 2 when no scan runner starts, so a non-zero exit is not a security finding. skill-check 1.2.0 puts no security key in the JSON. The scan exited non-zero, which without `--ci` means it did not finish, when skill-check exits 1 although `summary.errorCount` is 0: stderr is then the scan's last lines (its tail), even when blank. On exit 0, stderr is never a scan tail (npm and Node warnings can be there); when exit 1 has another cause, stderr is a scan tail only when it holds the scanner's own lines, such as its token message or a finding code. A finding code is `[`, a capital letter, three digits and `]` (such as `[E001]`), the codes skill-check's own scan summary counts. Bind `{security_result}` from `{run_dir}/skill-check.stderr` and the exit code, the first that applies:
 
-Display: "Security scan requires a Snyk Enterprise API token ([docs](https://docs.snyk.io/snyk-api/authentication-for-api)). Set `SNYK_TOKEN=your-token` in environment or `.env`, then re-run [SF] Setup Forge. Without Enterprise, use `--no-security-scan` to skip. Security scanning is optional and does not block skill compilation."
+- `skipped`: §1 found no skill-check (**If skill-check unavailable** below), skill-check exits 2, the call stopped before it exited, or the scan exited non-zero and its tail carries no finding code. Log under the evidence report's Remaining Warnings "security scan skipped: SNYK_TOKEN not configured" when the tail says to set the `SNYK_TOKEN` environment variable (the scanner prints "To use Agent Scan, set the SNYK_TOKEN environment variable."), otherwise "security scan skipped: scanner could not run ({the stderr line that names the cause, or its last line})", or "security scan skipped: scanner exited non-zero with no output" when stderr is blank.
+- `warn`: `security[]` holds findings, or the tail carries finding codes. Record each finding under the evidence report's Remaining Warnings as an advisory warning: security findings do not block artifact generation.
+- `pass`: otherwise. The scan exited 0 and skill-check reported no finding. Without `--ci`, agent-scan also exits 0 when its analysis fails (a 401 from a bad token, a 429, a network error), so this does not show that the scan found nothing (#892).
 
-Record: "Security scan skipped — SNYK_TOKEN not configured"
+**Security row.** §8 writes the `- Security:` row as `{security_result}`, then its note in parentheses: for `skipped` the note above less its "security scan skipped: " prefix, such as `skipped (SNYK_TOKEN not configured)`; for `warn` each finding; for `pass` the row reads `pass (scan exited 0; skill-check 1.2.0 does not pass the scan's findings on)`. Step 8 takes the row's first word as `security_result`.
+
+**If the tail says to set `SNYK_TOKEN`** (the first `skipped` note):
+
+Display: "Security scan requires a Snyk Enterprise API token ([docs](https://docs.snyk.io/snyk-api/authentication-for-api)). Set `SNYK_TOKEN=your-token` in environment or `.env`, then re-run [SF] Setup Forge. Without Enterprise, use `--no-security-scan` to skip. Security scanning is optional and does not block skill compilation."
 
-**If skill-check unavailable:** Skip with note: "Security scan skipped — skill-check tool unavailable"
+**If skill-check unavailable:** bind `{security_result}` ← `skipped`, keep the Security row §1 marked, and log "security scan skipped: skill-check unavailable" under the evidence report's Remaining Warnings.
 
 ### 6. Description Angle-Bracket Check
 
@@ -346,14 +366,14 @@ Record the result on the evidence report's `Provenance lines` line (§8): `pass`
 
 ### 8. Update Evidence Report
 
-Write the validation results into the staged `<staging-skill-dir>/evidence-report.md`, in place of the `[PENDING: populated by step 6]` placeholders compile left, with `python3 {atomicWriteHelper} write --target <staging-skill-dir>/evidence-report.md`: step 7 promotes that file as it is. In the same write, add under `## Remaining Warnings` the notes steps 5a to 5c kept for the evidence report (the doc-sources note, `{temporal_feeder_notice}` when step 5c set it, because the Deep-tier temporal feeder held no files) and, once each, the skipped authoritative-files scan when the inventory's `authoritative_files_scan` records `not_scanned` (a remote source that was never cloned; the `skipped` count of candidates the user skipped is not a warning). When no split ran and the staged `references/` holds no file, the Body line says `Tier-2 kept inline (references/ empty)`, so an audit can tell inline by design from a split that failed.
+Write the validation results into the staged `<staging-skill-dir>/evidence-report.md`, in place of the `[PENDING: populated by step 6]` placeholders compile left and of the line under `## Auto-Fixed Issues`, which compile wrote before §2 ran, with `python3 {atomicWriteHelper} write --target <staging-skill-dir>/evidence-report.md`: step 7 promotes that file as it is. In the same write, add under `## Remaining Warnings` the notes steps 5a to 5c kept for the evidence report (the doc-sources note, `{temporal_feeder_notice}` when step 5c set it, because the Deep-tier temporal feeder held no files) and, once each, the skipped authoritative-files scan when the inventory's `authoritative_files_scan` records `not_scanned` (a remote source that was never cloned; the `skipped` count of candidates the user skipped is not a warning). When no split ran and the staged `references/` holds no file, the Body line says `Tier-2 kept inline (references/ empty)`, so an audit can tell inline by design from a split that failed.
 
 ```markdown
 ## Validation Results
 - Schema: {pass/fail} (quality score: {score}/100)
 - Frontmatter: {pass/fail}
 - Body: {pass/fail} {body split applied if applicable}
-- Security: {pass/warn/skipped}
+- Security: {pass/warn/skipped} ({the note §5's Security row gives})
 - Description angle brackets: {none | re-sanitized ({count} substitutions) | not checked — no description}
 - Tessl Review: {tessl_summary}
 - Metadata: {pass/fail}
@@ -370,7 +390,7 @@ Write the validation results into the staged `<staging-skill-dir>/evidence-repor
 - Notes: {one-sentence detail or —}
 
 ## Auto-Fixed Issues
-- {list of issues automatically corrected by --fix}
+- {"skill-check --fix rewrote SKILL.md" when §2 recorded `skill_check_fix_changed: true`, "SKILL.md may have been rewritten (not hashed) by skill-check --fix" when it recorded `skill_check_fix_changed: unchecked`, otherwise "none"}
 
 ## Remaining Warnings
 - {warnings and security results, then each entry of {tessl_warnings} — or "none"}

package/src/skf-create-stack-skill/references/invocation-contract.md

@@ -31,4 +31,4 @@ The shared emitter, `skf-emit-result-envelope.py`, builds every `SKF_STACK_RESUL
 SKF_STACK_RESULT_JSON: {"status":"success|error","skill_package":"...|null","skill_name":"...","stack_libraries":["..."],"mode":"code|compose","quality_score":null,"exit_code":0,"halt_reason":null,"run_id":"...","result_path":"...|null","headless_decisions":[],"warnings":[]}
 ```
 
-A halt adds `error`: its `phase`, its message as `reason`, and `path` when it names a file or folder. When the customization resolver could not run, `warnings` holds `[activation/warn] customization_resolver_unavailable: <reason>`, which step 1 records before any other warning: the run used the bundled `customize.toml` alone, without the `{project-root}/_bmad/custom/` overrides.
+A halt adds `error`: its `phase`, its message as `reason`, and `path` when it names a file or folder. A success line adds `security_result`, the outcome of step 8 §9's security scan (`pass`, `warn` or `skipped`); a halt leaves it out. When the customization resolver could not run, `warnings` holds `[activation/warn] customization_resolver_unavailable: <reason>`, which step 1 records before any other warning: the run used the bundled `customize.toml` alone, without the `{project-root}/_bmad/custom/` overrides.

package/src/skf-create-stack-skill/references/report.md

@@ -53,17 +53,17 @@ The shared emitter writes the result contract (`shared/references/output-contrac
 
 ```json
 {"status": "success", "skill_package": "{skill_package}", "skill_name": "{stack_name}",
- "stack_libraries": ["<library>"], "mode": "code|compose", "quality_score": null, "halt_reason": null,
+ "stack_libraries": ["<library>"], "mode": "code|compose", "quality_score": null, "security_result": "pass|warn|skipped", "halt_reason": null,
  "result_contract": {"skill": "skf-create-stack-skill", "status": "success",
   "outputs": [{"type": "skill", "path": "{skill_package}/SKILL.md"},
               {"type": "skill", "path": "{skill_package}/context-snippet.md"},
               {"type": "skill", "path": "{skill_package}/metadata.json"},
               {"type": "report", "path": "{forge_version}/evidence-report.md"}],
   "summary": {"lib_count": 0, "integration_count": 0, "forge_tier": "<tier>", "confidence_tier": "<tier>",
-              "confidence_distribution": {}, "quality_score": null}}}
+              "confidence_distribution": {}, "quality_score": null, "security_result": "pass|warn|skipped"}}}
 ```
 
-`skill_package` is the absolute path to the committed package and `stack_libraries` the committed `metadata.json`'s `libraries`. Both `quality_score` fields are `{quality_score}`, the skill-check score step 8 §3 bound (`null` when skill-check did not run), never a test-skill score. The summary's counts, `confidence_tier` and `confidence_distribution` are the committed `metadata.json`'s `library_count`, `integration_count`, `confidence_tier` and `confidence_distribution`, and `forge_tier` its run tier. Then run:
+`skill_package` is the absolute path to the committed package and `stack_libraries` the committed `metadata.json`'s `libraries`. Both `quality_score` fields are `{quality_score}`, the skill-check score step 8 §3 bound (`null` when skill-check did not run), never a test-skill score. Both `security_result` fields are `{security_result}`, the scan outcome step 8 §9 bound. The summary's counts, `confidence_tier` and `confidence_distribution` are the committed `metadata.json`'s `library_count`, `integration_count`, `confidence_tier` and `confidence_distribution`, and `forge_tier` its run tier. Then run:
 
 ```bash
 uv run {emitEnvelopeHelper} emit --workflow skf-create-stack-skill --run-dir "{run_dir}" --result-dir "{forge_version}" < "{run_dir}/result-context.json"

package/src/skf-create-stack-skill/references/validate.md

@@ -3,6 +3,9 @@ nextStepFile: 'report.md'
 outputValidatorProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-validate-output.py'
   - '{project-root}/src/shared/scripts/skf-validate-output.py'
+hashContentProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-hash-content.py'
+  - '{project-root}/src/shared/scripts/skf-hash-content.py'
 ---
 
 <!-- Config: communicate in {communication_language}. Artifact text in {document_output_language}. -->
@@ -70,17 +73,17 @@ timeout 10s npx --no-install skill-check -h
 
 ### 3. Validate SKILL.md via skill-check (if available)
 
-**If available**, run: `npx skill-check check <skill-dir> --fix --format json --no-security-scan`
+**If available**, resolve `{hashContentHelper}` ← first existing path in `{hashContentProbeOrder}`, then run in order: `uv run {hashContentHelper} hash <skill-dir>/SKILL.md`, `npx skill-check check <skill-dir> --fix --format json --no-security-scan`, then `uv run {hashContentHelper} hash <skill-dir>/SKILL.md` again, keeping the `content_hash` each `hash` call prints.
 
-This validates frontmatter, description, body limits, links, formatting — and auto-fixes deterministic issues. Parse JSON for `scores[].score` (match the entry by `relativePath`/`skillId`; falls back to a top-level `qualityScore` on older skill-check builds), `diagnostics[]`, `fixed[]`.
+This validates frontmatter, description, body limits, links and formatting, and auto-fixes deterministic issues. Parse JSON for `scores[].score` (match the entry by `relativePath`/`skillId`; falls back to a top-level `qualityScore` on older skill-check builds) and `diagnostics[]`. skill-check's JSON lists no fix: SKILL.md changed across the `--fix` call when the two `content_hash` values differ, and is taken as changed, not hashed, when no `{hashContentProbeOrder}` path exists (run the skill-check call alone) or a `hash` call prints no `content_hash`.
 
 Bind `{quality_score}` ← that score, from the latest skill-check run (§3 runs it again after a split); `{quality_score}` is null when skill-check is unavailable. It is the skill-check score, not a test-skill score, and step 9 puts it in the result envelope and the result contract.
 
-**Post-fix provenance drift guard (S15):** If `fixed[]` is non-empty, `skill-check --fix` has modified `SKILL.md` after step 7 wrote it — so the `metadata.json` hashes/provenance recorded against the pre-fix body may now be stale. Emit a **WARNING** finding listing each auto-fix (`"skill-check --fix modified SKILL.md: {fix_description} — metadata.json hashes/provenance may be out of date"`) rather than silently accepting the fixes, so the drift is surfaced. If the caller wants authoritative metadata, they should re-run the workflow.
+**Post-fix provenance drift guard (S15):** When SKILL.md changed across the `--fix` call, `skill-check --fix` modified it after step 7 wrote it, so the `metadata.json` hashes and provenance recorded against the earlier body may now be stale. Emit one **WARNING** finding, `"skill-check --fix modified SKILL.md after step 7 wrote it: metadata.json hashes and provenance may be out of date"` (`"SKILL.md may have been rewritten (not hashed) by skill-check --fix after step 7 wrote it: metadata.json hashes and provenance may be out of date"` when SKILL.md was not hashed), rather than silently accepting the fix, so the drift is surfaced. If the caller wants authoritative metadata, they should re-run the workflow.
 
 **If `body.max_lines` reported**, prefer selective split: extract only the largest Tier 2 section(s) to `references/`, keeping Tier 1 content inline (inline passive context achieves 100% task accuracy vs 79% for on-demand retrieval). For a stack capstone the canonical split is the catalog (`Library Reference Index` + `Per-Library Summaries`) → `references/stack-catalog.md`, leaving an inline pointer (see `{stackSkillTemplatePath}` "Sizing Guidance"). The moved catalog's links resolve from `references/`, so rewrite each `[ref](references/{name}.md)` in it to `[ref]({name}.md)`. This is the **intended** large-stack layout, not a violation: §4 below accepts the pointer form, so clearing the skill-check body ERROR this way does not also trip the structure check. Fall back to `npx skill-check split-body <skill-dir> --write` if not feasible. After the split, verify that any in-SKILL.md anchor links (e.g. to the catalog/pointer or other moved sections) still resolve, and that every link inside a moved section resolves from its new file.
 
-**Re-validate a changed package.** When `fixed[]` is non-empty or a split ran, run the §1 `{outputValidator}` command again (after a split, skill-check too), so §4 to §8 record the package as it now stands.
+**Re-validate a changed package.** When SKILL.md changed across the `--fix` call (not hashed included) or a split ran, run the §1 `{outputValidator}` command again (after a split, skill-check too), so §4 to §8 record the package as it now stands.
 
 **If unavailable**, do not hand-walk the frontmatter: use `validation.skill_md.frontmatter` from the §1 output-validator run, which checks delimiters, `name` format + directory match (`{stack_name}`), `description` presence/length, and unknown fields against the agentskills.io allow-set. Record each reported issue at its severity as a **WARNING** finding. (If the output validator was *also* unavailable in §1, fall back to the manual checklist: `---` delimiters; `name` lowercase-alphanumeric-plus-hyphens 1-64 chars matching `{stack_name}`; `description` present and 1-1024 chars; only `name`/`description`/`license`/`compatibility`/`metadata`/`allowed-tools` permitted.) Invalid frontmatter will fail `npx skills add` and `npx skill-check check`.
 
@@ -120,15 +123,25 @@ Record format violations as **WARNING** findings.
 
 ### 9. Security Scan (if skill-check available)
 
-Run: `npx skill-check check <skill-dir> --format json` (security scan enabled by default).
+Run: `npx skill-check check <skill-dir> --format json > "{run_dir}/skill-check.json" 2> "{run_dir}/skill-check.stderr"; echo "skill-check exited $?"` (security scan enabled by default), so stdout, stderr and the exit code are read apart.
 
-Record security findings as advisory **WARNING** findings — they do not block the report.
+**If `{run_dir}/skill-check.json` does not start with a JSON object**, skill-check stopped before it validated (exit 2 on a config, option or plugin error): record no finding, only the §10 note "security scan skipped: skill-check failed ({the stderr line that names the cause, or its last line})". Otherwise stdout can go on after the JSON (a `Wrote <path>` line when the project config sets a report path), so read only the JSON object at its start.
 
-**If unavailable:** Skip with note in validation results.
+**Read the JSON, not the exit code.** skill-check exits 1 when `summary.errorCount` is above 0, when `--strict` or `--fail-on-warning` is passed and `summary.warningCount` is above 0 (this call passes neither), or when the scan exits non-zero, and 2 when no scan runner starts, so a non-zero exit is not a security finding. skill-check 1.2.0 puts no security key in the JSON. The scan exited non-zero, which without `--ci` means it did not finish, when skill-check exits 1 although `summary.errorCount` is 0: stderr is then the scan's last lines (its tail), even when blank. On exit 0, stderr is never a scan tail (npm and Node warnings can be there); when exit 1 has another cause, stderr is a scan tail only when it holds the scanner's own lines, such as its token message or a finding code. A finding code is `[`, a capital letter, three digits and `]` (such as `[E001]`), the codes skill-check's own scan summary counts. Read the scan from stderr and the exit code, the first that applies:
+
+- **Could not run:** skill-check exits 2, the call stopped before it exited, or the scan exited non-zero and its tail carries no finding code. Record no finding, only a note in the §10 validation results: "security scan skipped: SNYK_TOKEN not configured" when the tail says to set the `SNYK_TOKEN` environment variable (the scanner prints "To use Agent Scan, set the SNYK_TOKEN environment variable."), otherwise "security scan skipped: scanner could not run ({the stderr line that names the cause, or its last line})", or "security scan skipped: scanner exited non-zero with no output" when stderr is blank.
+- **Findings:** `security[]` holds findings, or the tail carries finding codes.
+- **Neither:** record the §10 note "security scan exited 0; skill-check 1.2.0 does not pass the scan's findings on". Without `--ci`, agent-scan also exits 0 when its analysis fails (a 401 from a bad token, a 429, a network error), so this does not show that the scan found nothing (#892).
+
+Record security findings as advisory **WARNING** findings: they do not block the report.
+
+**If unavailable:** Skip, with the note "security scan skipped: skill-check unavailable" in the §10 validation results.
+
+Bind `{security_result}` ← `skipped` for **Could not run**, a run whose `{run_dir}/skill-check.json` does not start with a JSON object, or an unavailable skill-check; `warn` for **Findings**; `pass` for **Neither**. Step 9 puts it in the result envelope and the result contract.
 
 ### 10. Display Validation Results
 
-Report the validation outcome. If all checks passed, state so and name what was verified: file presence (`{count}/{count}`), SKILL.md structure, metadata.json fields, the `{lib_count}` library + `{pair_count}` integration reference files, and complete confidence-tier coverage. If there were findings, report the `{warning_count}` finding(s) — each with severity, description, and file path — plus files present/expected and warning/error counts; when errors include missing files, note this may indicate a write failure in step 07.
+Report the validation outcome. If all checks passed, state so and name what was verified: file presence (`{count}/{count}`), SKILL.md structure, metadata.json fields, the `{lib_count}` library + `{pair_count}` integration reference files, and complete confidence-tier coverage. If there were findings, report the `{warning_count}` finding(s), each with severity, description, and file path, plus files present/expected and warning/error counts; when errors include missing files, note this may indicate a write failure in step 07. In both cases, list each §9 security scan note.
 
 ### 11. Auto-Proceed to Next Step