bmad-module-skill-forge 2.2.0 → 3.0.0

package/src/skf-test-skill/references/init.md

@@ -1,16 +1,50 @@
 ---
 nextStepFile: 'detect-mode.md'
-outputFile: '{forge_version}/test-report-{skill_name}-{run_id}.md'
+# §6c creates the report under this hidden name and binds `{report_file}` to
+# it; report.md §4c gives it its public name test-report-{skill_name}-{run_id}.md
+# once its checks pass, a blocked run's included.
+outputFile: '{forge_version}/.skf-test-report-{skill_name}-{run_id}.md'
 templateFile: '{testReportTemplatePath}'
 sidecarFile: '{sidecar_path}/forge-tier.yaml'
 skillsOutputFolder: '{skills_output_folder}'
+# Resolve `{emitEnvelopeHelper}` to the first existing path at §0, before
+# anything else: every HALT prints its headless envelope through it, and
+# report.md §4c writes the result contract with it.
+emitEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-result-envelope.py'
 # frontmatterScript resolves deterministically by probing two candidate
 # paths from `{project-root}` in order. There is NO silent manual fallback —
 # if neither candidate exists, the step HALTs with a diagnostic.
 frontmatterScriptProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-validate-frontmatter.py'
   - '{project-root}/src/shared/scripts/skf-validate-frontmatter.py'
-versionPathsKnowledge: 'knowledge/version-paths.md'
+# Resolve `{skillInventoryHelper}` to the first existing path. §2 runs its
+# `resolve` command to choose the version under test and bind its paths,
+# and runs it with `--skill` before a flat skill moves: only a flat skill
+# whose metadata.json carries an SKF marker (`flat_skf`) is migrated. §1
+# and §2 run it with `--near` to list the testable skills.
+skillInventoryProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-skill-inventory.py'
+  - '{project-root}/src/shared/scripts/skf-skill-inventory.py'
+# Resolve `{versionPathsKnowledge}` to the first existing path. §2 loads only
+# its "Migration: Flat to Versioned" section, and only to migrate a flat skill.
+versionPathsKnowledgeProbeOrder:
+  - '{project-root}/_bmad/skf/knowledge/version-paths.md'
+  - '{project-root}/src/knowledge/version-paths.md'
+# Resolve `{checkWorkspaceDriftHelper}` to the first existing path; §5b HALTs
+# if neither exists. It runs the workspace drift guard, once per repository
+# of a stack skill.
+checkWorkspaceDriftProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-check-workspace-drift.py'
+  - '{project-root}/src/shared/scripts/skf-check-workspace-drift.py'
+# Resolve `{runLockHelper}` to the first existing path; §6a HALTs if neither
+# exists. §6a takes the run lock and the run id through it, and it stays
+# bound for the rest of the run: report.md §4c renews the lock through it,
+# and every later HALT and report.md §7 release it.
+runLockProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-run-lock.py'
+  - '{project-root}/src/shared/scripts/skf-run-lock.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -21,24 +55,49 @@ versionPathsKnowledge: 'knowledge/version-paths.md'
 
 Discover and validate the target skill, load forge tier state to determine analysis depth, and create the test report document from template.
 
-### 1. Receive Skill Path
+**Halt envelope.** Every HALT in this step names its `halt_reason` and phase and carries exit code 1. Once §6a took the run lock, it releases the lock first, whatever the release prints: from `{project-root}`, run `uv run {runLockHelper} release --lock "{forge_version}/.test-skill.lock" --owner "{run_owner}"`. In headless mode it prints its envelope through `{emitEnvelopeHelper}` (§0). Until §6b has created the run folder, pass the payload on stdin, adding `"skill_name": "{skill_name}"` once §1 named the skill and `"path"` when the halt names one:
 
-If skill path was provided as workflow argument, use it directly.
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-test-skill --target stderr <<'SKF_TS_HALT'
+{"phase": "<phase>", "reason": "<the halt message>", "halt_reason": "<halt_reason>"}
+SKF_TS_HALT
+```
+
+Once §6b has created the run folder, write the same object, with `"report_path": "{report_file}"` once §6c created the report, to `{run_dir}/halt.json` and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-test-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`. The emitter sets `status: "error"`, derives `exit_code` from `halt_reason` and stamps `run_id`. Display the line it prints, as the run's last line, then stop. If the emitter exits non-zero or prints no line, display the halt message alone. An interactive HALT displays its message and emits nothing. `references/invocation-contract.md` lists every `halt_reason`.
+
+### 0. Resolve the Envelope Emitter
+
+Resolve `{emitEnvelopeHelper}` ← first existing path in `{emitEnvelopeProbeOrder}`, before any prompt or check; it stays bound for the run. If neither path exists, HALT (`halt_reason: "helper-missing"`, phase `init:emitter`) and display only: "**test-skill cannot run without `skf-emit-result-envelope.py`, which is not installed.** Re-install SKF." With no emitter, this HALT prints no envelope.
+
+### 0b. Check the Runtime
+
+Every step runs SKF's helpers through `uv run`, which also installs the dependencies each script declares (PEP 723); bare `python3` ignores them, so a helper such as the frontmatter validator fails on its PyYAML import. Confirm that `python3` and `uv` are both on `$PATH` (`command -v python3` and `command -v uv`). If either is missing, HALT (`halt_reason: "runtime-missing"`, phase `init:runtime`): "**test-skill needs `{the missing tool}`, which is not on your PATH.** Install it (`uv`: <https://docs.astral.sh/uv/getting-started/installation/>; `python3`: <https://www.python.org/downloads/>; both are documented runtime prerequisites, see `docs/getting-started.md`), then re-run." Nothing is written. The emitter needs only the standard library, so when `uv` is the missing tool the envelope command runs with `python3` in place of `uv run`; with both missing, display the halt message alone.
+
+### 1. Receive the Skill Name
+
+Bind `{skill_name}` from the workflow argument: a skill name, or a path inside `{skillsOutputFolder}`, which names the skill folder it lies in (its first folder under `{skillsOutputFolder}`).
 
 **Recognized flags on the invocation:**
-- `--allow-workspace-drift` — bypass the section 5b pre-flight guard that halts when local workspace HEAD does not match `metadata.source_commit`. Store `allow_workspace_drift: true` in workflow context when present. No effect when `source_commit` is unpinned or the source is not a git working tree.
+- `--allow-workspace-drift`: bypass the section 5b pre-flight guard that halts when local workspace HEAD does not match `metadata.source_commit`. Store `allow_workspace_drift: true` in workflow context when present; §5b decides whether drift was overridden and records it in the report frontmatter (`workspaceDrift`), which the later steps read. No effect when `source_commit` is unpinned or the source is not a git working tree.
 - `--no-discovery` — skip the §4b Discovery Testing block in step 6 (report). Store `no_discovery: true` in workflow context when present.
 - `--no-health-check` — skip the §7 health-check dispatch in step 6 (report). Store `no_health_check: true` in workflow context when present.
-- `--tier=<Quick|Forge|Forge+|Deep>` — bypass the §4 forge-tier.yaml sidecar HALT. Store `tier_flag: '<value>'` in workflow context when present; §4 will set `detected_tier` directly from this value and skip the sidecar probe.
-- `--threshold=<N>` — override the pass threshold for this run. Consumed by `references/score.md` §1; CLI wins over per-pipeline defaults (§1b) and the `workflow.default_threshold` scalar.
+- `--tier=<Quick|Forge|Forge+|Deep>`: bypass the §4 forge-tier.yaml sidecar HALT. Store `tier_flag: '<value>'` in workflow context when present; §4 will set `detected_tier` directly from this value and skip the sidecar probe. A value that is not one of the four (case-sensitive) HALTs here, before anything runs (`halt_reason: "input-invalid"`, phase `init:flags`): "Error: --tier=<value> is not one of Quick, Forge, Forge+, Deep".
+- `--threshold=<N>`: override the pass threshold for this run. §1b resolves it: CLI wins over per-pipeline defaults and the `workflow.default_threshold` scalar.
+- `--discovery-catalog=all`: widen the discovery catalog of step 6 §4b.0. Store `discovery_catalog_all: true` in workflow context when present.
 
-If no path provided, ask:
+**No skill name given.** In `{headless_mode}` there is no one to ask: HALT (`halt_reason: "input-missing"`, phase `init:skill-name`, no `skill_name` in the payload): "**test-skill needs a skill name.** Re-run with the name of the skill to test." Interactively, list the skills there are to test, then ask. Resolve `{skillInventoryHelper}` ← first existing path in `{skillInventoryProbeOrder}` (§2 uses it too; if neither path exists, HALT (`halt_reason: "helper-missing"`, phase `init:skill-name`) with §2's not-found message) and run:
+
+```bash
+uv run {skillInventoryHelper} {skillsOutputFolder} --near ""
+```
+
+Show each `near[]` entry's `name` and `active_version` (`no active version` when it is null); when the helper exits non-zero, or `near[]` is absent or empty, show the create-skill line below instead. Then ask:
 
 "**Which skill would you like to test?**
 
-Provide the skill path or name. I'll search in `{skillsOutputFolder}`.
+{the list above, or: No skill SKF generated is in `{skillsOutputFolder}` yet: run the **create-skill** workflow first.}
 
-**Path or name:**"
+**Skill name:**"
 
 ### 1b. Resolve Per-Pipeline Quality Threshold
 
@@ -51,20 +110,47 @@ If `{pipeline_alias}` is set in the workflow data context (forwarded by the forg
 | `forge-quick`  | 80                |
 | `campaign`     | 90                |
 
-- **If `{pipeline_alias}` is present AND found in the table:** store the corresponding value as `{pipeline_default_threshold}` in workflow context. This variable is consumed by `references/score.md` §1 as a precedence layer between CLI `--threshold` and `{defaultThreshold}`.
-- **If `{pipeline_alias}` is present but NOT in the table:** `{pipeline_default_threshold}` remains unset. Score.md falls through to `{defaultThreshold}`.
-- **If `{pipeline_alias}` is absent** (standalone TS invocation, not running inside a pipeline): `{pipeline_default_threshold}` remains unset. Score.md falls through to `{defaultThreshold}`.
+- **If `{pipeline_alias}` is present AND found in the table:** store the corresponding value as `{pipeline_default_threshold}` in workflow context. It is the precedence layer between CLI `--threshold` and `{defaultThreshold}` below.
+- **If `{pipeline_alias}` is present but NOT in the table:** `{pipeline_default_threshold}` remains unset, and the threshold falls through to `{defaultThreshold}`.
+- **If `{pipeline_alias}` is absent** (standalone TS invocation, not running inside a pipeline): `{pipeline_default_threshold}` remains unset, and the threshold falls through to `{defaultThreshold}`.
+
+**Resolve the pass threshold once, here (precedence: CLI > pipeline default > scalar > bundled fallback):**
+
+1. If the workflow received `--threshold=<N>` on invocation, use that integer as `effective_threshold` (CLI wins). Set `threshold_source` = `"CLI override ({N}%)"`.
+2. Else if `{pipeline_default_threshold}` is set (the table above), use it as `effective_threshold`. Set `threshold_source` = `"pipeline default ({pipeline_alias} → {N}%)"`.
+3. Else if the resolved `{defaultThreshold}` workflow-context variable (from SKILL.md On Activation §3: the `workflow.default_threshold` scalar, default `80`) is set, use it as `effective_threshold`. Set `threshold_source` = `"workflow default ({N}%)"`.
+4. Else fall back to `80` (the bundled default: this branch should be unreachable when SKILL.md resolution ran correctly, but keeps the step robust if customize.toml resolution failed silently). Set `threshold_source` = `"bundled fallback (80%)"`.
+
+§6c writes both into the report frontmatter (`threshold`, `thresholdSource`), and `references/score.md` §1 reads them from there: a long run's context may lose them, the report keeps them.
 
 ### 2. Validate Skill Exists (version-aware)
 
-Resolve the skill path using version-aware resolution (see `{versionPathsKnowledge}`):
+The inventory helper chooses the version to test and binds its paths by the Reading Workflows rules of the version-paths knowledge (the Manifest-lag guard included), so this step never walks the export manifest or the `active` link by hand. Resolve `{skillInventoryHelper}` ← first existing path in `{skillInventoryProbeOrder}` (unless §1 already did) and run:
+
+```bash
+uv run {skillInventoryHelper} resolve {skillsOutputFolder} --skill {skill_name} --forge-data-folder {forge_data_folder}
+```
+
+Bind from its `resolve` object:
+
+- `{resolved_version}` ← `chosen_version`
+- `{resolved_skill_package}` ← `skill_package`
+- `{forge_version}` ← `forge_version`: the version's folder in the forge data, where this run writes its report, its result files and its lock
+- `{forge_provenance_map}` ← `paths.provenance_map.path` and `{forge_evidence_report}` ← `paths.evidence_report.path`: the version folder's file when it exists, else the flat copy an older skill may still keep in `{forge_data_folder}/{skill_name}/`, else null. Every later step reads the provenance map and the evidence report through these two bindings, except coverage-check §4c: it checks the version folder's own map, whose lines update-skill moves.
+
+Log each entry of `resolve.errors` (a broken `active` link, for example), and `resolve.manifest_error` when it is set (an export manifest that cannot be read), as an Info note, then act on `reason`:
+
+1. `manifest-and-link`, `manifest` or `link`: the export manifest or the `active` link names the version, and its package is on disk. Continue.
+2. `manifest-lags-link`: the `active` link names a version the manifest has not caught up with (the Manifest-lag guard). Continue, and emit the helper's `detail` as an Info note.
+3. If neither: fall back to the flat path `{skillsOutputFolder}/{skill_name}/` (`reason` is `flat-layout`: `SKILL.md` sits at the skill folder root, with no version folder yet). Check that SKF generated it before anything moves:
+   - Run `uv run {skillInventoryHelper} {skillsOutputFolder} --skill {skill_name}`, and bind `{group_flat_skf}` ← `skills[0].flat_skf` and `{group_errors}` ← `skills[0].errors`.
+   - **`{group_flat_skf}` is true:** auto-migrate per the migration rules of `{versionPathsKnowledge}` (resolve it ← first existing path in `{versionPathsKnowledgeProbeOrder}` and load only its "Migration: Flat to Versioned" section), then run the `resolve` command above again and bind its values anew: they now name the version folder.
+   - **Otherwise** (`{group_flat_skf}` is false, the status is not `ok`, `skills[]` has no entry, or no helper candidate resolves): do not migrate. HALT before anything moves (`halt_reason: "not-skf-output"`, phase `init:ownership`) with this message: "**`{skill_name}` is not SKF output: nothing was moved.** `{skillsOutputFolder}/{skill_name}/SKILL.md` has no SKF marker in the `metadata.json` beside it, so SKF will not move or test it. A shared `{skillsOutputFolder}` is supported: SKF leaves the skills it did not generate alone, so manage `{skill_name}` yourself. Only if `{skillsOutputFolder}` holds a module's own source rather than skills, set `skills_output_folder` in `{project-root}/_bmad/skf/config.yaml` to a folder of its own, move your SKF skills there and re-run `/skf-setup`." When there is another reason, show it in place of the marker sentence: `{group_errors}` when it is non-empty (for example, the folder is a link, which SKF never moves), the helper's `error` when the status is not `ok`, and, when no helper candidate resolved, that SKF could not check the marker because `skf-skill-inventory.py` is missing, so re-install SKF.
+4. `missing`, or the helper stops with `SKILL_NOT_FOUND` or `DIR_NOT_FOUND`: no version of the skill is on disk, or the name names none. Take the not-found branch below.
+5. `newest-on-disk`: version folders exist, but neither the export manifest nor a working `active` link names one. The Reading Workflows rules test only a version one of them names, so take the SKILL.md error below.
+6. Any other error, or no JSON: HALT (`halt_reason: "helper-failed"`, phase `init:resolve`) with the helper's stderr message. Nothing is written.
 
-1. Read `{skillsOutputFolder}/.export-manifest.json` and look up the skill name in `exports` to get `active_version`
-2. **Manifest-lag guard.** If the skill is in the manifest, also read the `active` symlink target at `{skillsOutputFolder}/{skill_name}/active`. If that symlink resolves to a *different* version than `active_version`, prefer the **symlink target** as `{resolved_version}` and emit an Info note: "manifest active_version {M} lags the active symlink {N} — testing the symlink target (the just-forged version); run export-skill to reconcile the manifest." This is the canonical SS→TS→EX case: create-stack-skill flipped `active` to the new version, but the manifest only advances when export-skill runs — so a bare manifest-first resolution would test the *previously exported* version and report a PASS for the wrong version (silent false confidence). When the symlink matches `active_version` (or no `active` symlink exists), use `active_version`. See `{versionPathsKnowledge}` "Reading Workflows".
-3. If found: resolve to `{skill_package}` = `{skillsOutputFolder}/{skill_name}/{resolved_version}/{skill_name}/`
-4. If not in manifest: check for `active` symlink at `{skillsOutputFolder}/{skill_name}/active` — resolve to `{skill_group}/active/{skill_name}/`
-5. If neither: fall back to flat path `{skillsOutputFolder}/{skill_name}/`. If SKILL.md exists at the flat path, auto-migrate per `{versionPathsKnowledge}` migration rules
-6. Store the resolved path as `{resolved_skill_package}`
+If no helper candidate resolves, SKF can neither choose the version nor check a flat skill's marker. Nothing moves: when `{skillsOutputFolder}/{skill_name}/SKILL.md` exists, take step 3's Otherwise branch; else HALT (`halt_reason: "helper-missing"`, phase `init:resolve`) with "Error: cannot locate skf-skill-inventory.py at `{project-root}/_bmad/skf/shared/scripts/skf-skill-inventory.py` or `{project-root}/src/shared/scripts/skf-skill-inventory.py`. Install the SKF module or run from a development checkout with src/ present."
 
 Check that the skill package contains required files:
 
@@ -72,18 +158,17 @@ Check that the skill package contains required files:
 - `{resolved_skill_package}/SKILL.md` — the skill documentation
 - `{resolved_skill_package}/metadata.json` — skill metadata
 
-**If SKILL.md missing:**
-"**Error: SKILL.md not found at `{resolved_skill_package}/SKILL.md`**
+**Not found** (step 4): the name may be mistyped or partial, so list the skills there are to test, closest to it first, rather than sending the user to create a skill that already exists:
 
-This skill has not been created yet. Run the **create-skill** workflow first."
+```bash
+uv run {skillInventoryHelper} {skillsOutputFolder} --near "{skill_name}"
+```
 
-**Headless envelope (if `{headless_mode}`):** emit to **stderr**:
+Its `near[]` lists every skill SKF generated that has a SKILL.md, the `close` names first (one name holds the other, or they are similar). Say "**No version of `{skill_name}` is on disk.** {the helper's `detail` or `error`}", then show each `close` entry's `name` and `active_version`, or, when none is close, every entry, adding "If `{skill_name}` is a new skill, run the **create-skill** workflow first." When the helper exits non-zero, or `near[]` is absent or empty (a `{skillsOutputFolder}` that does not exist, say), show no list, only that create-skill line. Interactively, ask for the skill name again and run this section anew with it. In `{headless_mode}`, HALT (`halt_reason: "target-inaccessible"`, phase `init:resolve`) with that message, the close names written as "Did you mean: {names}?".
 
-```
-SKF_TEST_RESULT_JSON: {"status":"error","skill_name":"{skill_name}","verdict":null,"score":null,"threshold":null,"report_path":null,"next_workflow":null,"exit_code":1,"halt_reason":"target-inaccessible"}
-```
+**If SKILL.md missing** (or step 5 found no version to test): HALT (`halt_reason: "target-inaccessible"`, phase `init:resolve`) with "**Error: SKILL.md not found at `{resolved_skill_package}/SKILL.md`**
 
-HALT — do not proceed.
+This skill has not been created yet. Run the **create-skill** workflow first." When step 5 applies, say instead: "**Error: no version of `{skill_name}` is named for testing.** {the helper's `detail`}. Point `{skillsOutputFolder}/{skill_name}/active` at the version to test, then re-run."
 
 **If metadata.json missing:**
 "**Warning:** metadata.json not found. Proceeding with limited metadata. Some checks may be skipped."
@@ -97,7 +182,7 @@ HALT — do not proceed.
 
 Use the first path that exists as `{frontmatterScript}`. There is no manual fallback.
 
-**If neither path exists, HALT** with the diagnostic below. test-skill is a quality gate; without the deterministic validator it cannot produce a trustworthy frontmatter verdict, and a silent manual check can miss subtle spec drift. The missing helper must be restored before testing continues:
+**If neither path exists, HALT** (`halt_reason: "helper-missing"`, phase `init:frontmatter`) with the diagnostic below. test-skill is a quality gate; without the deterministic validator it cannot produce a trustworthy frontmatter verdict, and a silent manual check can miss subtle spec drift. The missing helper must be restored before testing continues:
 
 ```
 Error: cannot locate skf-validate-frontmatter.py at either of:
@@ -110,28 +195,24 @@ SKF module (`skf init`) or run from a development checkout with src/ present.
 
 Do not proceed. No partial test report is written.
 
-**3b. Python runtime probe (before invoking the validator).** Confirm both `python3` and `uv` are on `$PATH` (`command -v python3` and `command -v uv`). Both are required: `uv run` shells through to `python3` and honors the script's PEP 723 PyYAML dependency declaration that bare `python3` ignores (bare `python3` fails with `ModuleNotFoundError: No module named 'yaml'` on a fresh interpreter — `docs/getting-started.md` documents uv as the runtime prereq for exactly this). If either is missing, set `analysis_confidence: degraded` in workflow context and carry a **score cap** into step 5: `capped_score = threshold - 1` → forces auto-FAIL until the runtime is restored. Record the reason in evidence-report and the test report frontmatter (`analysisConfidence: degraded`, `toolingStatus: python3-missing` or `uv-missing` as appropriate). `uv` is a documented runtime prerequisite — see `docs/getting-started.md` for install instructions.
-
-**3c. Run the validator (30s timeout — the deterministic validator should finish in <1s; the cap only guards against runaway python).**
+**3b. Run the validator (30s timeout: the deterministic validator should finish in under 1s, and the cap only guards against runaway python).**
 
 ```bash
 timeout 30s uv run {frontmatterScript} {resolved_skill_package}/SKILL.md --skill-dir-name {skill_name}
 ```
 
 If the command trips the 30s wall-clock (exit code `124`), set
-`analysis_confidence: degraded` and `toolingStatus: frontmatter-validator-timeout`
-in workflow context, apply the step 5 tooling-degraded cap (score capped at
-`threshold - 1` → auto-FAIL), and record the reason in evidence-report.
+`tooling_status: frontmatter-validator-timeout` in workflow context; otherwise
+set `tooling_status: ok`. Tooling health lives only there: `analysis_confidence`
+names the source access coverage-check resolves, so neither overwrites the
+other. Step 5 passes `tooling_status` to its scoring script, whose Cap 1 fails
+any run whose tooling status is not `ok`, at every threshold.
 
 Parse the JSON output. Treat each `status` value explicitly:
 
 - `status: "pass"` — continue silently.
 - `status: "warn"` — display the warning below, log each issue as a pre-check finding, and continue with testing. Frontmatter issues surface in the gap report alongside coverage/coherence findings.
-- `status: "fail"` — **HALT with auto-FAIL.** Frontmatter failure means the skill will be rejected by `npx skills add` and `npx skill-check check`; shipping it would produce a false PASS downstream. Write the halt note into evidence-report and exit non-zero. **Headless envelope (if `{headless_mode}`):** emit to **stderr** before halting. The output document does not exist yet (created in §6), so `report_path` is `null` — matching the other pre-report init HALTs (target-inaccessible, forge-tier-missing, workspace-drift, another-run-active). A frontmatter-invalid target is the most common failure this gate exists to catch, so a headless orchestrator must be able to branch on it (route to update-skill) rather than see an unlabelled non-zero exit:
-
-```
-SKF_TEST_RESULT_JSON: {"status":"error","skill_name":"{skill_name}","verdict":null,"score":null,"threshold":null,"report_path":null,"next_workflow":null,"exit_code":1,"halt_reason":"frontmatter-invalid"}
-```
+- `status: "fail"`: **HALT** (`halt_reason: "frontmatter-invalid"`, phase `init:frontmatter`) with the message below. Frontmatter failure means the skill will be rejected by `npx skills add` and `npx skill-check check`; shipping it would produce a false PASS downstream. The report does not exist yet (§6c creates it), so the envelope carries no `report_path`, like every HALT before §6c. A frontmatter-invalid target is the most common failure this gate exists to catch, so a headless orchestrator branches on its `halt_reason` (route to update-skill) rather than on an unlabelled failure.
 
 ```
 **Warning/Error: SKILL.md frontmatter is non-compliant with agentskills.io specification.**
@@ -143,7 +224,7 @@ This skill will fail `npx skills add` and `npx skill-check check`. {If warn:} Co
 
 ### 4. Load Forge Tier State
 
-**`--tier=<...>` flag bypass (precedes the sidecar probe).** If `tier_flag` is set in workflow context (from §1's `--tier=<Quick|Forge|Forge+|Deep>` flag), validate the value against the allowed set. On valid match: set `detected_tier` directly to the flag's value, leave `ast_grep`/`gh_cli`/`qmd` availability flags unset (downstream steps treat unset as "unknown" — analysis proceeds without tool-specific enrichment), log Info note "tier — supplied via --tier flag, sidecar bypassed", and SKIP the sidecar probe and HALT below (jump straight to §4b "Apply Tier Override"). On invalid value (not one of the four), HALT with "Error: --tier=<value> is not one of Quick, Forge, Forge+, Deep".
+**`--tier=<...>` flag bypass (precedes the sidecar probe).** If `tier_flag` is set in workflow context (from §1's `--tier=<Quick|Forge|Forge+|Deep>` flag, which §1 checked): set `detected_tier` directly to the flag's value, leave `ast_grep`/`gh_cli`/`qmd` availability flags unset (downstream steps treat unset as "unknown": analysis proceeds without tool-specific enrichment), log Info note "tier: supplied via --tier flag, sidecar bypassed", and SKIP the sidecar probe and HALT below (jump straight to §4b "Apply Tier Override").
 
 **Otherwise (no `--tier` flag):** Read `{sidecarFile}` to determine available analysis depth.
 
@@ -151,16 +232,7 @@ This skill will fail `npx skills add` and `npx skill-check check`. {If warn:} Co
 - Read `tier` value (Quick, Forge, Forge+, or Deep)
 - Read tool availability flags (ast_grep, gh_cli, qmd)
 
-**If forge-tier.yaml missing:**
-"**Cannot proceed.** forge-tier.yaml not found at `{sidecarFile}`. Please run the **setup** workflow first to configure your forge tier (Quick/Forge/Forge+/Deep), or re-run with `--tier=<Quick|Forge|Forge+|Deep>` to bypass the sidecar."
-
-**Headless envelope (if `{headless_mode}`):** emit to **stderr**:
-
-```
-SKF_TEST_RESULT_JSON: {"status":"error","skill_name":"{skill_name}","verdict":null,"score":null,"threshold":null,"report_path":null,"next_workflow":null,"exit_code":1,"halt_reason":"forge-tier-missing"}
-```
-
-HALT — do not proceed.
+**If forge-tier.yaml missing:** HALT (`halt_reason: "forge-tier-missing"`, phase `init:forge-tier`, `"path": "{sidecarFile}"`) with "**Cannot proceed.** forge-tier.yaml not found at `{sidecarFile}`. Please run the **setup** workflow first to configure your forge tier (Quick/Forge/Forge+/Deep), or re-run with `--tier=<Quick|Forge|Forge+|Deep>` to bypass the sidecar."
 
 ### 4b. Apply Tier Override (if set)
 
@@ -176,71 +248,72 @@ Read `metadata.json` to extract:
 - `source_ref` — pinned ref (tag/branch/`HEAD`) used at extraction time
 - `generation_date` — when skill was generated
 - `confidence_tier` — tier used during creation
+- `generated_by`: the SKF workflow that built the skill (coverage-check §2 reads it at Quick tier)
 
 If source path override was provided as optional input, use that instead.
 
 ### 5b. Verify Workspace HEAD Matches Pinned Commit
 
-Test-skill reads `source_path` during coverage and coherence analysis. If the local workspace has drifted from `metadata.source_commit`, gap and signature-mismatch findings will silently reflect the drifted tree, not the skill's pinned source — producing false positives that downstream update-skill runs may then "repair" by corrupting correct documentation.
+Test-skill reads `source_path` during coverage and coherence analysis. If the local workspace has drifted from `metadata.source_commit`, gap and signature-mismatch findings silently reflect the drifted tree, not the skill's pinned source: false positives that downstream update-skill runs may then "repair" by corrupting correct documentation.
 
-- Resolve `pinned_commit` from `metadata.source_commit`.
-- **If `pinned_commit` is null, empty, or `"local"`:** skip the guard; log `workspace_drift_check: skipped (no pinned commit)` and continue to section 6.
-- **If `pinned_commit` is a per-repo map (stack skills):** iterate each `{repo_path: commit}` entry — for each repo run `git -C "{repo_path}" rev-parse HEAD` and compare to its pinned commit (accept full-SHA or short-SHA-prefix match). If ANY repo diverges and the user did not pass `--allow-workspace-drift`, HALT with exit status `workspace-drift` listing every mismatched repo (in `{headless_mode}`, emit the same `workspace-drift` stderr envelope shown in the single-tree branch below before halting). On all-match: log `workspace_drift_check: ok (stack, {N} repos verified)` and continue to section 6. This guard must iterate every repo — do not skip stack skills.
-- **If `source_path` is not a git working tree** (bare checkout, tarball extract, docs-only source) — detect by `git -C "{source_path}" rev-parse --is-inside-work-tree`, non-zero exit means skip: log `workspace_drift_check: skipped (not a git working tree)` and continue to section 6.
-- **Otherwise** run `git -C "{source_path}" rev-parse HEAD` and compare to `pinned_commit`. Accept full-SHA or short-SHA-prefix match (stored pins are often 8-char short hashes — see `src/knowledge/provenance-tracking.md`).
-  - **On match:** log `workspace_drift_check: ok ({short_sha})` and continue.
-  - **On mismatch, AND the user did not pass `--allow-workspace-drift`:** HALT with exit status `workspace-drift`. Display:
+The guard runs through `{checkWorkspaceDriftHelper}`, never through `git` commands run by hand. Resolve it ← first existing path in `{checkWorkspaceDriftProbeOrder}`. If neither path exists, HALT (`halt_reason: "helper-missing"`, phase `init:workspace-drift`) with: "Error: cannot locate skf-check-workspace-drift.py at `{project-root}/_bmad/skf/shared/scripts/skf-check-workspace-drift.py` or `{project-root}/src/shared/scripts/skf-check-workspace-drift.py`. Install the SKF module or run from a development checkout with src/ present." No test report is written.
 
-    ```
-    Workspace HEAD does not match the commit this skill was pinned against.
+Run it once per source tree, from `{project-root}`, passing `--allow-drift` only when the user passed `--allow-workspace-drift`:
 
-      pinned (metadata.source_commit): {pinned_commit}
-      pinned ref (metadata.source_ref): {source_ref or "unset"}
-      workspace HEAD ({source_path}):  {head_sha}
+```bash
+uv run {checkWorkspaceDriftHelper} "{tree}" --pinned-commit "{pinned_commit}" [--source-ref "{source_ref}"] [--allow-drift] --workflow test-skill
+```
 
-    Test-skill verifies against the source the skill was extracted from.
-    Testing against a drifted tree produces false gaps/mismatches. Re-sync:
+- **One tree:** `{tree}` is `{source_path}`, `{pinned_commit}` is `metadata.source_commit` (an empty string when it is null), and `{source_ref}` is `metadata.source_ref` when it is set.
+- **A stack skill** (`metadata.source_commit` is a `{repo_path: commit}` map): one call per entry, with that repo path as `{tree}`, its commit as `{pinned_commit}`, and the same key's value of `metadata.source_ref` as `{source_ref}` when that is a map too. Check every repo: do not skip stack skills.
+- Make no call for a tree that is not on disk (coverage then reads the provenance map, State 2 of the source access protocol), and log `workspace_drift_check: skipped (no local source at {tree})`. The helper itself skips a tree with no pinned commit (`""` or `"local"`) and one that is not a git working tree.
 
-      git -C "{source_path}" checkout {source_ref or pinned_commit}
+Log each call's `log_message`, then act on the statuses together:
 
-    Or re-run test-skill with `--allow-workspace-drift` to test against the
-    current workspace (accepts that findings reflect HEAD, not the pin).
-    ```
+- **Any `mismatch`** (exit 2): HALT (`halt_reason: "workspace-drift"`, phase `init:workspace-drift`), displaying the `halt_message` of every tree that drifted, verbatim: it names the pinned commit and ref, the workspace HEAD, the `git checkout` that re-syncs the tree, and `--allow-workspace-drift`. The test report has not been created; no partial writes.
+- **Any `overridden`, and no `mismatch`:** carry `workspaceDrift: overridden` into the report frontmatter. The later steps read it there, never the flag: score.md §5 demotes a PASS under drift to `pass-with-drift` and forces `nextWorkflow` to `update-skill`, never `export-skill`, and coverage-check §4c skips its line check. A flag passed on a clean tree changes nothing. Continue.
+- **Otherwise** every call is `ok` or `skipped`: set `workspaceDrift: ok` when at least one tree was checked, else `not-checked`, and continue.
+- A call that exits 1 or prints no JSON could not read its tree (for example, `git` is not installed): log `workspace_drift_check: skipped (helper error: {its stderr})`, count it as `skipped`, and continue.
 
-    **Headless envelope (if `{headless_mode}`):** emit to **stderr**:
+### 6. Create Output Document
 
-    ```
-    SKF_TEST_RESULT_JSON: {"status":"error","skill_name":"{skill_name}","verdict":null,"score":null,"threshold":null,"report_path":null,"next_workflow":null,"exit_code":1,"halt_reason":"workspace-drift"}
-    ```
+**6a. Take the run lock and the run id.** A run spans many tool calls and turns, so no process can hold a lock for it: the lock is a file, `{forge_version}/.test-skill.lock`, that names its owner and the time, and it keeps two test-skill runs against this version from writing the same result files. Resolve `{runLockHelper}` ← first existing path in `{runLockProbeOrder}`; it stays bound for the rest of the run. If neither path exists, HALT (`halt_reason: "helper-missing"`, phase `init:run-lock`) with: "Error: cannot locate skf-run-lock.py at `{project-root}/_bmad/skf/shared/scripts/skf-run-lock.py` or `{project-root}/src/shared/scripts/skf-run-lock.py`. Install the SKF module or run from a development checkout with src/ present." From `{project-root}`, run:
 
-    Do not proceed. The test report has not been created; no partial writes.
-  - **On mismatch WITH `--allow-workspace-drift`:** log `workspace_drift_check: overridden (pinned={pinned_commit}, head={head_sha})`, carry the warning into the final report frontmatter (`workspaceDrift: overridden`), and set `allow_workspace_drift: true` in workflow context (consumed by step 5 §5 drift override — a PASS under drift is demoted to `pass-with-drift` and `nextWorkflow` is forced to `update-skill`, never `export-skill`). Continue.
+```bash
+uv run {runLockHelper} acquire --lock "{forge_version}/.test-skill.lock" --owner "test-skill:{skill_name}"
+```
 
-### 6. Create Output Document
+The owner names no run id, so the helper adds one. Bind `{run_id}` ← `run_id` (the UTC time and a random suffix, safe in file names) and `{run_owner}` ← `owner`. Every per-run artifact of this and the later steps carries `{run_id}`, and every release names `{run_owner}` (SKILL.md Workflow Rules).
 
-**6a. Generate `{run_id}`**: a per-run identifier of the form `{YYYYMMDDTHHmmssZ}-{pid}-{rand4}` (UTC timestamp + process PID + 4-char random hex). Store in workflow context. All per-run artifacts in this and subsequent steps must carry this suffix; step 6 verifies `testDate` in the resulting report matches the run's stamp and fail-fast otherwise.
+**6b. Act on the result:**
 
-**6b. Acquire the per-skill test lock**: `flock {forge_version}/.test-skill.lock` for the duration of this run to serialize concurrent `skf-test-skill` invocations against the same skill. If the lock is already held by another run, HALT with "another test-skill run is active for {skill_name}". **Headless envelope (if `{headless_mode}`):** emit to **stderr** before halting:
+- `acquired` is true: the lock is this run's. When `stale_replaced` is not null, a run that ended without releasing its lock left it: log `run lock: replaced the stale lock of {stale_replaced.held_by} (held since {stale_replaced.held_since})` and continue. Then create the run folder, where the later steps keep the files their scripts hand each other, and bind `{run_dir}` ← `{project-root}/_bmad-output/.skf-run/skf-test-skill-{run_id}`:
 
-```
-SKF_TEST_RESULT_JSON: {"status":"error","skill_name":"{skill_name}","verdict":null,"score":null,"threshold":null,"report_path":null,"next_workflow":null,"exit_code":1,"halt_reason":"another-run-active"}
-```
+  ```bash
+  mkdir -p "{project-root}/_bmad-output/.skf-run/skf-test-skill-{run_id}"
+  ```
 
-**6c. Create `{outputFile}` from `{templateFile}`** — use `{forge_version}/test-report-{skill_name}-{run_id}.md` Initial frontmatter:
+  If it cannot be created, HALT (`halt_reason: "write-failed"`, phase `init:run-folder`, `"path"` the folder) with the first stderr line, releasing the run lock first as the **Halt envelope** paragraph says and passing the envelope's payload on stdin: there is no folder to stage it in. report.md §7 removes the folder when the run ends; a HALT leaves it for inspection.
+- `acquired` is false (exit 3): another run holds a lock that has not gone stale. HALT (`halt_reason: "another-run-active"`, phase `init:run-lock`) with "**Another test-skill run is active for {skill_name}.** {message}": the helper's `message` names that run, the lock file to delete when no run is active, and the time the lock goes stale. This run holds no lock, so nothing is released.
+- The helper exits 1 or 2, or prints no JSON: HALT (`halt_reason: "helper-failed"`, phase `init:run-lock`) with its stderr message (exit 2: the lock file could not be written, so check that `{forge_version}` is writable). This run holds no lock, so nothing is released.
+
+**6c. Create `{outputFile}` from `{templateFile}`**, under the in-progress name `{forge_version}/.skf-test-report-{skill_name}-{run_id}.md` beside the run lock, and bind `{report_file}` ← that path: every later step writes the report there, and report.md §4c gives it its public name `test-report-{skill_name}-{run_id}.md` once its checks pass, a blocked run's included. Until then no consumer can mistake it for a finished report: export-skill and update-skill read only the public name, and `skf-skill-inventory.py` counts a `.skf-` name as SKF's, so a halted run's leftover never turns the version folder foreign. If the file cannot be written, HALT (`halt_reason: "write-failed"`, phase `init:report`, `"path": "{report_file}"`). Initial frontmatter:
 
 ```yaml
 ---
 workflowType: 'test-skill'
 skillName: '{skill_name}'
-skillDir: '{skill_path}'
+skillDir: '{resolved_skill_package}'
 runId: '{run_id}'
 testMode: ''
 forgeTier: '{detected_tier}'
+hardGate: ''
 testResult: ''
 score: ''
-threshold: ''
-analysisConfidence: '{full|degraded}'
-toolingStatus: '{ok|python3-missing|uv-missing|frontmatter-validator-missing|frontmatter-validator-timeout}'
+threshold: '{effective_threshold}%'
+thresholdSource: '{threshold_source}'
+analysisConfidence: ''
+toolingStatus: '{ok|frontmatter-validator-timeout}'
 workspaceDrift: '{not-checked|ok|overridden}'
 testDate: '{run_id timestamp ISO-8601 UTC}'
 stepsCompleted: ['init']
@@ -248,9 +321,11 @@ nextWorkflow: ''
 ---
 ```
 
+`toolingStatus` is the `tooling_status` §3b set: score.md §3a reads it back for Cap 1. `threshold` and `thresholdSource` are the pass threshold §1b resolved and its source: score.md §1 reads them back, and score.md §7 rewrites `threshold` with the threshold the verdict was settled against. `analysisConfidence` stays empty until score.md §7 writes the source access coverage-check resolved: `full`, `provenance-map`, `metadata-only`, `remote-only` or `docs-only`.
+
 ### 7. Report Initialization Status
 
 Report initialization to the user: the resolved skill name, path, type, forge tier, and source path. Then proceed to mode detection.
 
-Update stepsCompleted, then load and execute {nextStepFile}.
+`stepsCompleted` already holds `'init'` (§6c created the report with it), so load and execute {nextStepFile}.
 

package/src/skf-test-skill/references/invocation-contract.md

@@ -0,0 +1,66 @@
+# Invocation Contract: skf-test-skill
+
+The full argument set, gate map, outputs, exit codes and `SKF_TEST_RESULT_JSON` result envelope of `skf-test-skill`, and how a HALT prints its envelope. Interactive runs need none of it: headless automators and pipeline integrators read this file, and each stage's **Halt envelope** paragraph carries what a halting stage needs.
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | `skill_name` [required: an interactive run asks for it, a headless run without it halts `input-missing`; a path inside `{skills_output_folder}` names the skill folder it lies in]; optional flags: `--headless` / `-H` (or `headless_mode: true` in preferences.yaml), `--allow-workspace-drift`, `--no-discovery` (skip the report step's Discovery Testing block), `--no-health-check` (skip the health check that ends the run), `--tier=<Quick\|Forge\|Forge+\|Deep>` (bypass the forge-tier.yaml sidecar requirement; any other value halts `input-invalid`), `--threshold=<N>` (override the pass threshold; CLI wins over per-pipeline defaults and the `workflow.default_threshold` scalar), `--discovery-catalog=all` (widen the discovery catalog to the skills in `{project-root}/.claude/skills/` and `{project-root}/_bmad/agents/`) |
+| **Gates** | none: every stage auto-proceeds, and the shared health check ends the run (its review gate defaults to [Q] in headless mode) |
+| **Outputs** | the test report `test-report-{skill_name}-{run_id}.md` in `{forge_version}/`, written as `.skf-test-report-{skill_name}-{run_id}.md` until report.md §4c's checks pass (a run the hard gate blocked included), so a halted run never leaves a partial report under the name export-skill and update-skill read; the result contract `skf-test-skill-result-{YYYYMMDD-HHmmss}.json` and its `skf-test-skill-result-latest.json` copy in `{forge_version}/`, written by the shared emitter; `evidence-report-fallback.md` in `{forge_version}/` when the threshold fallback fires (a score between 80% and the target threshold, no cap fired); the gap ledger `test-findings-{run_id}.json` in `{forge_version}/`; for the run itself, a run folder `{project-root}/_bmad-output/.skf-run/skf-test-skill-{run_id}/` holding the files the scripts hand each other, which report.md §7 removes (a HALT keeps it) |
+| **Concurrency** | init.md §6a takes the run lock `{forge_version}/.test-skill.lock` through `skf-run-lock.py`, and report.md §4c renews it before it publishes the report and writes the result files; while another run holds a fresh lock, the run halts with `halt_reason: "another-run-active"` (exit 1). |
+| **Headless** | No stage waits for an answer: a missing `skill_name` halts `input-missing`, the shared health check queues its findings locally, and the result envelope is the run's last line |
+| **Exit codes** | See "Exit Codes" below |
+
+## Exit Codes
+
+Every terminal state settles one exit code, so a headless automator branches on the verdict, and on any HARD HALT, without grepping message text. A skill run cannot set the process exit status of the agent that runs it (`claude -p` exits 0 whatever the run decided), so automators read `exit_code` from the `SKF_TEST_RESULT_JSON` line or from `skf-test-skill-result-latest.json`:
+
+| Code | Meaning              | Raised by                                                                                  |
+| ---- | -------------------- | ------------------------------------------------------------------------------------------ |
+| 0    | success / PASS       | step 6: `testResult: 'pass'`                                                               |
+| 1    | error (HARD HALT)    | a HALT before a verdict exists, in steps 1 to 6: every `halt_reason` below but `hard-gate-blocked` |
+| 2    | fail / FAIL          | step 4c §3: the hard gate blocked the run (`halt_reason: "hard-gate-blocked"`), and step 6 publishes it as a FAIL; step 6: `testResult: 'fail'` |
+| 3    | inconclusive         | step 6: `testResult: 'inconclusive'` (distinct from fail so orchestrators can route to manual-review queues) |
+| 4    | pass-with-drift      | step 6: `testResult: 'pass-with-drift'` (distinct from clean pass: `--allow-workspace-drift` was in effect and drift was observed; re-test against the pinned commit and refuse export, since exit 0 would wrongly signal a clean pass) |
+
+## Result Envelope (Headless)
+
+When `{headless_mode}` is true the run ends with one `SKF_TEST_RESULT_JSON: {...}` line. The shared emitter, `skf-emit-result-envelope.py`, builds every line from a payload the stage stages in `{run_dir}`, stamps `run_id` and `result_path`, and checks it against `{project-root}/_bmad/skf/shared/scripts/schemas/skf-test-result-envelope.v1.json` (`{project-root}/src/shared/scripts/schemas/skf-test-result-envelope.v1.json` in a development checkout), whose descriptions say what each field holds: `status`, `skill_name`, `verdict`, `score`, `threshold`, `report_path`, `next_workflow`, `exit_code`, `halt_reason`, `run_id`, `result_path`, and `threshold_fallback`, `original_threshold`, `warnings` and `error` when they apply. Never type the line yourself.
+
+- **A finished run** (report.md §4c): `scripts/build-result-context.py` builds the payload from the report frontmatter, the gap ledger and the scoring output, deriving `verdict`, `exit_code` and `next_workflow` from `testResult`, and the emitter prints the line and writes the result files. `status` is `"success"` for a scored run (PASS, FAIL, INCONCLUSIVE or pass-with-drift) and `"error"` with `halt_reason: "hard-gate-blocked"` for a run the hard gate blocked (verdict `FAIL`, exit 2), which still writes the Gap Report and its FAIL result contract. `next_workflow` is `"export-skill"` only when `verdict` is `PASS`, `"update-skill"` for `FAIL` and `pass-with-drift`, null for `INCONCLUSIVE`. `threshold_fallback` (true) and `original_threshold` appear only when the threshold fallback fired.
+- **A HALT** (below): `status: "error"`, the `halt_reason` of its failure class and the `exit_code` it maps to.
+
+The emitter prints a finished run's line on stdout and a halt's or a blocked run's on stderr; the run displays the line either way, so the split is a label only. The line is the run's last line: report.md binds `{result_envelope_line}` to it and the shared health check displays it after everything else (report.md §7 displays it itself under `--no-health-check`), and a HALT displays its line and stops.
+
+| `halt_reason` | Raised by |
+| --- | --- |
+| `input-missing` | init.md §1: a headless run given no skill name |
+| `input-invalid` | init.md §1: a `--tier` value that names no tier |
+| `runtime-missing` | init.md §0b: `python3` or `uv` is not on `PATH` |
+| `helper-missing` | an SKF helper the run needs is not installed: init.md §1, §2, §3a, §5b and §6a, coherence-check.md §1 |
+| `helper-failed` | a helper or a script that exits with an error the step cannot correct: init.md §2 and §6b, the coverage and coherence steps' scripts, external-validators.md §5b, step 4c §2, score.md §3c, report.md §4b and §4c |
+| `write-failed` | init.md §6b and §6c (the run folder or the report), report.md §4c (the report's public name, or the result contract the emitter refused twice) |
+| `target-inaccessible` | init.md §2: no version of the skill to test |
+| `not-skf-output` | init.md §2: a flat skill SKF did not generate |
+| `frontmatter-invalid` | init.md §3b |
+| `forge-tier-missing` | init.md §4 |
+| `workspace-drift` | init.md §5b |
+| `another-run-active` | init.md §6b, and the lock renewal in report.md §4c |
+| `inventory-invalid` | coverage-check.md §1a: the documented inventory failed its schema check or spot-check twice |
+| `indeterminate-surface` | coverage-check.md §2b: zero exports, an empty stack surface or a docs-only skill that documents nothing, so no score can be attached |
+| `step-completeness-violation` | step 4c §2 (a stage recorded nothing in the gap ledger) and report.md §4c |
+| `report-anchor-missing` | report.md §4c |
+| `health-check-missing` | report.md §4c, before anything is published |
+| `hard-gate-blocked` | step 4c §3: not a halt, the run ends through report.md and publishes its FAIL |
+
+When the emitter itself is not installed (init.md §0), no line can be printed: that HALT displays its message alone.
+
+## Result Files
+
+report.md §4c runs the emitter with `--result-dir "{forge_version}"`. It writes the per-run record `skf-test-skill-result-{YYYYMMDD-HHmmss}.json` (UTC; it picks the name, `-2`, `-3` appended when a run already took that second's name) and then its copy `skf-test-skill-result-latest.json`, the stable path pipeline consumers read (a copy, not a symlink), each atomically. The record holds the envelope's fields, plus `skill`, `outputs[]` (the published report), `summary` (`score`, `threshold`, `result` (`PASS`, `PASS_WITH_DRIFT`, `FAIL` or `INCONCLUSIVE`), `testMode`, `activeCategories[]`, `inconclusiveReasons[]` when present, `threshold_fallback`, `original_threshold` and `evidence_report_path` when the threshold fallback fired, `gapCounts` with the gap ledger's gaps by severity, and `hardGate`), `runId` and `healthCheckDispatched`, and the emitter stamps `timestamp`, `run_id`, `headless_decisions` and `warnings` into it. A run the hard gate blocked writes it too, as a FAIL record, so `skf-test-skill-result-latest.json` never holds an earlier run's verdict. A HALT writes no result file.
+
+## Emitting a Halt
+
+Every HALT names its `halt_reason` and its phase (`<step>:<check>`, such as `init:runtime` or `report:anchors`) and, in headless mode, prints its envelope through the shared emitter's `emit-halt`, which sets `status: "error"` and derives `exit_code` 1 from the `halt_reason`. Each stage's **Halt envelope** paragraph holds the command, the payload and, once init.md §6a took the run lock, its release.

package/src/skf-test-skill/references/migration-section-rules.md

@@ -11,7 +11,10 @@
 Execute this check only when both conditions are met:
 
 1. Forge tier is **Deep** (tool-gated)
-2. `{forge_data_folder}/{skill_name}/evidence-report.md` exists (data-gated)
+2. The evidence report exists (data-gated): init.md §2 bound
+   `{forge_evidence_report}` (the skill version folder's evidence report, or
+   the flat copy an older skill may still keep); the detection contract below
+   reads it.
 
 If either condition fails, skip silently and proceed to the next section.
 
@@ -53,7 +56,7 @@ narrative body.
 ```bash
 # Extract t2_future_count from frontmatter. Requires a `---` delimiter pair.
 awk '/^---$/{c++;next} c==1 && /^t2_future_count:/{print $2; exit}' \
-    {forge_data_folder}/{skill_name}/evidence-report.md
+    {forge_evidence_report}
 ```
 
 - **Frontmatter missing OR `t2_future_count` absent** → treat as Case 4 (see