bmad-module-skill-forge 2.2.0 → 4.0.0

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

@@ -1,20 +1,31 @@
 ---
 nextStepFile: 'health-check.md'
 
-outputFile: '{forge_version}/test-report-{skill_name}-{run_id}.md'
-scoringRulesFile: '{scoringRulesPath}'
-outputFormatsFile: '{outputFormatsPath}'
+outputFile: '{report_file}'
+# §4c gives the report this public name once its checks pass (a run the hard
+# gate blocked included), the name export-skill and update-skill read.
+publishedReportFile: '{forge_version}/test-report-{skill_name}-{run_id}.md'
+# The run's gap ledger: the stages recorded their gaps in it, §4b adds the
+# discovery outcome, and §4c renders the Gap Report from it.
+ledgerFile: '{forge_version}/test-findings-{run_id}.json'
+gapLedgerScript: 'scripts/gap-ledger.py'
+# §4c builds the shared emitter's payload from the run's records with it.
+resultContextScript: 'scripts/build-result-context.py'
+scoringRulesFile: 'references/scoring-rules.md'
+outputFormatsFile: 'assets/output-section-formats.md'
 # outputContractSchema and healthCheck resolve relative to the SKF module root
 # (`{project-root}/_bmad/skf/` when installed, `{project-root}/src/` during
-# development), NOT relative to this step file. Both paths are probed in
-# order; HALT if neither exists.
+# development), NOT relative to this step file. §4c probes both health-check
+# paths in order and HALTs, before anything is published, if neither exists.
 outputContractSchema: 'shared/references/output-contract-schema.md'
 healthCheckProbeOrder:
   - '{project-root}/_bmad/skf/shared/health-check.md'
   - '{project-root}/src/shared/health-check.md'
-atomicWriteProbeOrder:
-  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
-  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+# Resolve `{skillInventoryHelper}` to the first existing path. §4b.0 reads the
+# inventory to count the folders that hold a skill.
+skillInventoryProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-skill-inventory.py'
+  - '{project-root}/src/shared/scripts/skf-skill-inventory.py'
 ---
 
 <!-- Config: communicate in {communication_language}. Test report prose in {document_output_language}. -->
@@ -23,57 +34,62 @@ atomicWriteProbeOrder:
 
 ## STEP GOAL:
 
-Generate a detailed gap report listing every issue found during coverage and coherence analysis, assign severity to each gap, provide specific actionable remediation suggestions, and finalize the test report document. Do not recalculate scores — that ran in step 5. This step chains to the local health-check step via `{nextStepFile}` after completion; the user-facing report is not the terminal step.
+Publish the run. Record the discovery outcome in the gap ledger, render the Gap Report from the ledger, check that every stage ran and wrote its section, then publish the report under its public name, write the result contract, run the on_complete hook and present the result. Do not recalculate scores (step 5 ran them) or classify the stages' gaps again (each stage recorded its own). A run the hard gate blocked comes here straight from step 4c and takes the same sequence, with the blocked-run branch each section names. This step chains to the local health-check step via `{nextStepFile}` after completion; the user-facing report is not the terminal step.
 
-### 1. Collect All Issues
+**Halt envelope.** Every HALT in this step names its `halt_reason` and phase and carries exit code 1. It releases the run lock first, whatever the release prints: from `{project-root}`, run `uv run {runLockHelper} release --lock "{forge_version}/.test-skill.lock" --owner "{run_owner}"` (SKILL.md Workflow Rules). In headless mode it then writes `{"phase": "<phase>", "reason": "<the halt message>", "halt_reason": "<halt_reason>", "skill_name": "{skill_name}", "report_path": "{report_file}"}`, adding `"path"` when the halt names one, to `{run_dir}/halt.json` and runs:
 
-Read `{outputFile}` and extract every issue found across all analysis sections:
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-test-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
 
-**From Coverage Analysis (step 03):**
-- Missing documentation (exports in source but not in SKILL.md)
-- Signature mismatches (documented signature differs from source)
-- Stale documentation (documented but no longer in source)
-- Type coverage gaps (undocumented types/interfaces)
+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.
 
-**From Coherence Analysis (step 04):**
-- Broken references (file paths, skill references, type imports that don't resolve)
-- Incomplete integration patterns (contextual mode)
-- Structural issues (naive mode — missing sections, broken examples)
+§7 releases the lock when the run ends.
 
-**From External Validation (step 04b):**
-- skill-check diagnostics (unresolved errors and warnings)
-- tessl judge suggestions (content quality and actionability improvements)
+### 1. Collect All Issues
 
-### 2. Load Severity Rules
+The stages before this one recorded every gap they found in the gap ledger `{ledgerFile}`, each with the severity and the category the Gap Severity table gives it. The ledger is the record of the run's gaps: the hard gate counted it, and the Gap Report, the result contract and update-skill `--from-test-report` read it. Do not collect gaps again from the report's sections. The one source of gaps left is discovery testing (§4b), which runs after the gate.
 
-Load the **Gap Severity** table from `{scoringRulesFile}` — it is the single source of truth for classifying every gap (Critical / High / Medium / Low / Info). Classify each issue directly against that table in §3; do not restate its rows here, so the table cannot drift between this step and the scoring step that already consumes it.
+**A run the hard gate blocked** (frontmatter `hardGate: 'blocked'`, set by step 4c §3) was not scored and skips discovery testing (§4b) and the loads in §2 and §3: after §4, continue at §4c.
 
-### 3. Classify and Order Gaps
+### 2. Load Severity Rules
+
+For the discovery record §4b writes, load the **Gap Severity** table from `{scoringRulesFile}`, the single source of truth for a gap's severity and category; do not restate its rows here.
 
-Load `{outputFormatsFile}` for gap entry format and remediation quality rules.
+### 3. Load the Record Format
 
-For each issue, assign severity from `{scoringRulesFile}` and generate a specific remediation following the quality rules in `{outputFormatsFile}`. Remediation suggestions must reference specific files, exports, and line numbers. Order gaps by severity: Critical → High → Medium → Low → Info.
+Load `{outputFormatsFile}` for the Ledger Record Format and the remediation quality rules the discovery record follows. The ledger numbers the gaps and the Gap Report orders them, so nothing is ordered by hand.
 
-### 4. Generate Remediation Summary and Append Gap Report
+### 4. The Terminal Sequence
 
-Load the Gap Report section format from `{outputFormatsFile}`. Count gaps by severity, estimate effort per the guidelines in `{outputFormatsFile}`, and append the complete **Gap Report** section to `{outputFile}`.
+Every run that reaches this step, a blocked one included, ends through one sequence, and a check that fails stops it before anything is published:
 
-If no gaps found, append a clean pass message recommending **export-skill** workflow.
+1. §4b records the discovery outcome in the ledger (a blocked run skips it).
+2. §4c renders the Gap Report from the ledger, checks that every stage ran and wrote its section and that the health check is installed, then builds the result payload, publishes the report, writes the result contract and runs the on_complete hook.
+3. §6 presents the result, §6b keeps the headless envelope for the run's last line, and §7 releases the run lock and hands over to the health check.
 
 ### 4b. Discovery Testing
 
-**`--no-discovery` flag bypass (precedes the precondition check).** If `no_discovery: true` is set in workflow context (from §1 of `init.md` — `--no-discovery` flag on invocation), record an Info-severity note in the Discovery Quality subsection: `discovery — skipped: --no-discovery flag set`, log the bypass, and SKIP §4b.1–§4b.3. Proceed to §4b.4 (description optimization) only if tessl/skill-check flagged description issues; otherwise skip directly to §4c.
+**`--no-discovery` flag bypass (precedes the precondition check).** If `no_discovery: true` is set in workflow context (from §1 of `init.md`: the `--no-discovery` flag on invocation), record the skip (below) with the reason `--no-discovery flag set`, log the bypass, and SKIP §4b.1 to §4b.3. Proceed to §4b.4 (description optimization) only if Tessl Review's description score is below 90% or skill-check flagged description issues; otherwise skip directly to §4b.5.
+
+Perform minimum-viable discovery testing. Its outcome is at most one gap (§4b.5), and the Discovery Quality subsection §4c writes shows it.
 
-After gap enumeration, perform minimum-viable discovery testing. This is a **Medium-weight** check contributing to the Discovery Quality subsection.
+**Recording a skip.** A discovery test that does not run is still counted. Each skip branch (the bypass above, §4b.0 and the §4b.2 guard) is one Info `discovery` gap, the Gap Severity table's "Discovery testing not performed" row, titled `Discovery testing not performed: {reason}`, with the SKILL.md frontmatter `description` as its Source and a Remediation that names what lets the test run: a run without `--no-discovery`, a second skill in the catalog (or `--discovery-catalog=all`), or an environment that can spawn subagents. The Discovery Quality subsection also gets the note `discovery: skipped, {reason}`. §4b.5 records the gap.
 
 **4b.0 Precondition — catalog size check:**
 
-Count the skills in `{skillsOutputFolder}`: `ls -1d {skillsOutputFolder}/*/ 2>/dev/null | wc -l` (directories only — each skill package lives at `{skillsOutputFolder}/<skill-name>/`).
+Count the folders that hold a skill, not every folder: SKF's own `_batch/` holds none, and a versioned skill keeps its `SKILL.md` under `active/`. Resolve `{skillInventoryHelper}` ← first existing path in `{skillInventoryProbeOrder}` and run:
 
-- If `catalog_size < 2`: **skip §4b.1–§4b.3**. Record an Info-severity note in the Discovery Quality subsection: `discovery — skipped: catalog size N={catalog_size}, requires ≥2 candidates for meaningful routing`. The routing test is vacuous with one candidate (any prompt returns the sole skill); reporting `3/3 PASS` under those conditions inflates the Discovery score and masks genuinely bad description triggers. Proceed to §4b.4 (description optimization) if tessl/skill-check flagged description issues; otherwise skip to §4c.
+```bash
+uv run {skillInventoryHelper} {skillsOutputFolder}
+```
+
+Bind `{not_skf_output}` ← `not_skf_output` and `{discovery_catalog}` ← every `skills[]` entry whose `has_skill_md` is true and whose `skf_skill` is true or whose `name` is in `{not_skf_output}`, each as its `name` plus `{active_path}/SKILL.md`. Skills SKF did not generate stay in the catalog: they compete for the same prompts. `catalog_size` ← the number of `{discovery_catalog}` entries. Without the helper (no candidate resolves, or the status is not `ok`), build the same set with your file tools, never a shell pipeline: each folder directly in `{skillsOutputFolder}` whose name does not start with `.`, is not `_batch` and holds no `.skf-`, and that holds `SKILL.md` directly or at `active/<folder>/SKILL.md`.
+
+- If `catalog_size < 2`: **skip §4b.1 to §4b.3**. Record the skip with the reason `catalog size N={catalog_size}, requires ≥2 candidates for meaningful routing`. The routing test is vacuous with one candidate (any prompt returns the sole skill); reporting `3/3 PASS` under those conditions inflates the Discovery score and masks genuinely bad description triggers. Proceed to §4b.4 (description optimization) if Tessl Review's description score is below 90% or skill-check flagged description issues; otherwise skip to §4b.5.
 - If `catalog_size >= 2`: continue with §4b.1 as written.
 
-Optional escape hatch: the workflow accepts `--discovery-catalog=all` to broaden the candidate pool to `{project-root}/.claude/skills/` or `{project-root}/_bmad/agents/` for single-skill repos where the repo-local catalog is trivially too small. When the flag is set, rebuild `catalog_size` from the broader pool before the precondition check.
+Optional escape hatch: the workflow accepts `--discovery-catalog=all` (init.md §1 stores `discovery_catalog_all: true`) to broaden the candidate pool to `{project-root}/.claude/skills/` or `{project-root}/_bmad/agents/` for single-skill repos where the repo-local catalog is trivially too small. When `discovery_catalog_all` is true, add each folder directly in `{project-root}/.claude/skills/` or `{project-root}/_bmad/agents/` that holds a `SKILL.md` directly to `{discovery_catalog}` (a name already in it counts once), then recount `catalog_size` before the precondition check.
 
 **4b.1 Extract realistic prompts from the skill under test:**
 
@@ -86,10 +102,10 @@ If SKILL.md does not contain enough organic examples, synthesize 3 from the skil
 
 **4b.2 Spawn a discovery subagent:**
 
-**Subagents-unavailable guard (precedes the spawn).** If subagents cannot be spawned in this environment (e.g. a headless/CI pipeline with no subagent capability), do not fall back to answering the routing in the main thread — the main thread knows which skill is under test, so it would self-route to `3/3 PASS` and inflate the Discovery score, the exact false confidence §4b.0 warns against. Instead record an Info-severity note in the Discovery Quality subsection: `discovery — skipped: subagents unavailable, routing test requires isolated context`, exclude the discovery check from Discovery Quality scoring (do not count it PASS or FAIL), and skip to §4c.
+**Subagents-unavailable guard (precedes the spawn).** If subagents cannot be spawned in this environment (e.g. a headless/CI pipeline with no subagent capability), do not fall back to answering the routing in the main thread: the main thread knows which skill is under test, so it would self-route to `3/3 PASS` and inflate the Discovery score, the exact false confidence §4b.0 warns against. Instead record the skip with the reason `subagents unavailable, routing test requires isolated context`, exclude the discovery check from Discovery Quality scoring (do not count it PASS or FAIL), and skip to §4b.5.
 
 For each of the 3 prompts, spawn an isolated subagent with NO prior context about which skill is under test. Provide only:
-1. A compact list of ALL skills available in `{skillsOutputFolder}` (name + description line from each skill's SKILL.md frontmatter)
+1. A compact list of every skill in `{discovery_catalog}` (the same set §4b.0 counted): name + description line from that entry's SKILL.md frontmatter
 2. The prompt text
 
 Instruction to the subagent:
@@ -102,13 +118,13 @@ Parse the 3 responses. Schema-validate (required: `selected_skill`, `confidence`
 
 For each prompt, PASS = `selected_skill == skill_name` (the skill under test), FAIL otherwise.
 
-- **3 of 3 PASS** → discovery check PASS (Info severity note, no gap)
-- **2 of 3 PASS** → discovery check WARN → **Medium**-severity gap: `discovery — 1/3 realistic prompts misrouted`
-- **≤1 of 3 PASS** → discovery check FAIL → **High**-severity gap: `discovery — {N}/3 realistic prompts misrouted; description triggers are not pulling the skill`
+- **3 of 3 PASS** → discovery check PASS: no gap.
+- **2 of 3 PASS** → discovery check WARN: a Medium `discovery` gap titled `discovery: 1/3 realistic prompts misrouted`.
+- **≤1 of 3 PASS** → discovery check FAIL: a High `discovery` gap titled `discovery: {N}/3 realistic prompts misrouted; description triggers are not pulling the skill`.
 
-Append the prompts, selected skills, and outcomes as a table in the Discovery Quality subsection.
+Either gap has the SKILL.md frontmatter `description` as its Source, the misrouted prompts and the skills they reached as its Issue, and a Remediation that names the trigger phrases to add (§4b.4). Keep the prompts, the selected skills and the outcomes for the Discovery Quality table, which §4c writes after the Gap Report.
 
-**4b.4 Description optimization (secondary):** If tessl `description_score` (from step 04b) is below 90%, or skill-check flagged description issues, add remediation hints to the Discovery Quality subsection:
+**4b.4 Description optimization (secondary):** If the Tessl Review description score (the test report's `### Tessl Review` block; absent when Tessl Review did not run) is below 90%, or skill-check flagged description issues, keep these remediation hints for the Discovery Quality subsection §4c writes:
 - Third-person voice check
 - Explicit trigger keywords matching real user phrasing
 - Negative triggers ("NOT for: ...") to prevent false positives
@@ -119,45 +135,37 @@ Realistic prompt patterns for synthesis (§4b.1 fallback):
 - Implicit: "why did {metric} drop last {period}"
 - Abbreviated: "run the {keyword} thing on this data"
 
-### 4c. Result Contract (atomic write)
-
-**Resolve `{atomicWriteHelper}`:** probe `{atomicWriteProbeOrder}`. HALT if neither candidate exists — the contract is a downstream-consumer protocol and must never be written non-atomically. **Headless envelope (if `{headless_mode}`):** emit to **stderr** before halting:
+**4b.5 Record the discovery gap.** A skip, a WARN or a FAIL is one gap; a PASS records none. Record it in the ledger, with the record between the two markers exactly as it is (`{gapLedgerScript}` resolves relative to the skill root):
 
-```
-SKF_TEST_RESULT_JSON: {"status":"error","skill_name":"{skill_name}","verdict":null,"score":null,"threshold":null,"report_path":"{outputFile}","next_workflow":null,"exit_code":1,"halt_reason":"atomic-writer-missing"}
+```bash
+uv run {gapLedgerScript} append --ledger "{ledgerFile}" --stage report <<'SKF_GAPS'
+<the discovery record, a JSON array of one>
+SKF_GAPS
 ```
 
-Write the result contract per `{outputContractSchema}`:
-- Per-run record: `{forge_version}/skf-test-skill-result-{run_id}.json` (the `{run_id}` set in step 1 §6a — already carries UTC timestamp + PID + random suffix, so no same-second collision).
-- Latest copy: `{forge_version}/skf-test-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink).
+Exit 0: continue. Exit 2: nothing was written; correct the record `errors[]` names and run the command again. Exit 1: HALT with the script's `error` (`halt_reason: "helper-failed"`, phase `report:discovery`). Discovery runs after the hard gate, so a discovery gap blocks nothing, a High one included: it is counted in the Gap Report's totals and in the counts §6 presents, never as a blocking gap.
 
-Both writes must go through the atomic writer so partial writes are never observable:
+### 4c. Result Contract
+
+Nothing is published until the report is whole: render the Gap Report and check the report first, and only then give the report its public name, write the result files and run the on_complete hook.
+
+**Render the Gap Report.** The ledger now holds every gap of the run (`{gapLedgerScript}` resolves relative to the skill root):
 
 ```bash
-# Build the JSON payload in memory, then:
-cat payload.json | python3 {atomicWriteHelper} write --target {forge_version}/skf-test-skill-result-{run_id}.json
-cat payload.json | python3 {atomicWriteHelper} write --target {forge_version}/skf-test-skill-result-latest.json
+uv run {gapLedgerScript} render --ledger "{ledgerFile}" --heading
 ```
 
-Payload contents:
-- `outputs[]` — include the test report path at `{outputFile}` with its `{run_id}` suffix
-- `summary` — `score`, `threshold`, `result` (`"PASS"`, `"PASS_WITH_DRIFT"`, `"FAIL"`, or **`"INCONCLUSIVE"`**), `testMode` (naive/contextual), `activeCategories[]`, `inconclusiveReasons[]` (when present). `PASS_WITH_DRIFT` is set when the workflow observed workspace drift and the user passed `--allow-workspace-drift` — see step 5 §5 drift override. Downstream consumers must treat `PASS_WITH_DRIFT` as a non-exportable result: re-run against the pinned commit before export. When threshold fallback occurred, add `threshold_fallback: true`, `original_threshold: {N}`, and `evidence_report_path: '{path}'` to the summary — these fields are absent (not `false`/`null`) when no fallback occurred.
-- `runId` — the workflow's `{run_id}` for downstream correlation
-- `healthCheckDispatched` — boolean, set by §7 after the dispatch decision
+Exit 0: its output is the whole Gap Report section, heading included: the totals, the Remediation Summary and one entry per gap, by severity (with no gaps, it says none were found). Write it unchanged in place of the template's `## Gap Report` heading and the placeholder comment under it, in `{outputFile}`, then add the **Discovery Quality** subsection under it (format in `{outputFormatsFile}`): the §4b outcome, its prompt table or skip note, and the §4b.4 hints, or, for a run the hard gate blocked, the line that discovery testing did not run. Any other exit printed its error on stderr: HALT with it (`halt_reason: "helper-failed"`, phase `report:gap-report`).
 
-The `{forge_version}/.test-skill.lock` acquired in step 1 §6b remains held until the end of this step — it guards against concurrent latest-file overwrites.
-
-**Post-finalization hook.** If `{onCompleteCommand}` (resolved in SKILL.md On Activation §3 from `workflow.on_complete` scalar) is non-empty, invoke it as:
+Then take the gap counts from the ledger:
 
 ```bash
-{onCompleteCommand} --result-path={forge_version}/skf-test-skill-result-{run_id}.json
+uv run {gapLedgerScript} summary --ledger "{ledgerFile}"
 ```
 
-Run it with a bounded timeout (default 60s). On success: log Info note "on_complete — invoked: {command}" and continue. On non-zero exit, timeout, or any failure: append the failure reason to `workflow_warnings[]` (e.g. `on_complete — failed (exit {N}): {stderr_first_line}`) and continue. **The hook must never fail the workflow** — its purpose is integration glue (notify a CI router, post to a queue, archive the result) and any failure there is orthogonal to the test verdict. If `{onCompleteCommand}` is empty, this hook is a no-op (no log entry needed).
-
-### 5. Finalize Output Document — Enforce Step Completeness
+Bind `{gap_counts}` ← `counts`, `{total_gaps}` ← `total` and `{blocking_gaps}` ← `blocking`: §6 presents them. Exit 1: HALT with its `error` (`halt_reason: "helper-failed"`, phase `report:gap-report`).
 
-**Incremental step tracking:** read `stepsCompleted` from the output frontmatter. The expected set is the canonical chain:
+**Enforce step completeness.** Read `stepsCompleted` from the `{outputFile}` frontmatter. Each stage appended its own token when it finished, and `'report'` is appended only once the result files are written, so it is not in the expected set:
 
 ```
 ['init',
@@ -166,47 +174,84 @@ Run it with a bounded timeout (default 60s). On success: log Info note "on_compl
  'coherence-check',
  'external-validators',
  'hard-gate',
- 'score',
- 'report']
+ 'score']
 ```
 
-If any expected entry is missing, HALT with "step completeness violation — missing {list}; workflow state is inconsistent, do not finalize the report". **Headless envelope (if `{headless_mode}`):** emit to **stderr** before halting:
+A run the hard gate blocked was never scored: its expected set ends at `'hard-gate'`. If any expected entry is missing, HALT (`halt_reason: "step-completeness-violation"`, phase `report:steps`) with "step completeness violation: missing {list}; workflow state is inconsistent, do not finalize the report".
 
+**Check the report sections.** Each stage wrote its section in place of its heading and the placeholder comment under it in the template, so a stage that skipped its section left the placeholder behind, and one that appended its section instead left its heading twice. Count them with grep, not by eye, and read the counts it prints (a count of 0 also makes grep exit 1):
+
+```bash
+for heading in '## Test Summary' '## Coverage Analysis' '## Coherence Analysis' '## External Validation' '## Completeness Score' '## Gap Report'; do
+  printf '%s: ' "$heading"; grep -cxF "$heading" "{outputFile}"
+done
+printf 'placeholders: '; grep -c '^<!-- Populated by' "{outputFile}"
+```
+
+Each heading must print 1, standing alone on exactly one line, and `placeholders` must print 0. A run the hard gate blocked has all six: step 4c §3 wrote the Completeness Score section in scoring's place. On a heading whose count is not 1, or a placeholder left, HALT (`halt_reason: "report-anchor-missing"`, phase `report:anchors`) with "report anchor missing: {each heading whose count is not 1, with its count}, or {N} placeholder comments left; the section was not written once by its owning step".
+
+**Find the health check** unless `no_health_check` is true (the `--no-health-check` flag): resolve `{healthCheckFile}` ← first existing path in `{healthCheckProbeOrder}`. It ends the run (§7), so check it now, while a HALT still leaves the previous run's report and result files in place. If neither candidate exists, HALT (`halt_reason: "health-check-missing"`, phase `report:health-check`):
+
+```
+Error: cannot locate shared/health-check.md at either of:
+  - {project-root}/_bmad/skf/shared/health-check.md
+  - {project-root}/src/shared/health-check.md
+
+test-skill delegates its terminal step to the shared health-check. Install
+the SKF module or run from a development checkout with src/ present.
 ```
-SKF_TEST_RESULT_JSON: {"status":"error","skill_name":"{skill_name}","verdict":null,"score":null,"threshold":null,"report_path":"{outputFile}","next_workflow":null,"exit_code":1,"halt_reason":"step-completeness-violation"}
+
+**Renew the run lock** before anything below writes. The lock init.md §6a took goes stale 60 minutes after it was taken, and a long run can outlast that; an acquire by the owner that holds the lock renews it. From `{project-root}`, run:
+
+```bash
+uv run {runLockHelper} acquire --lock "{forge_version}/.test-skill.lock" --owner "{run_owner}"
 ```
 
-Only append `'report'` and write back after the check passes.
+- Exit 0: the lock is this run's again; continue.
+- Exit 3 (`acquired` is false): another run took the lock over after this run's lock went stale. HALT before writing anything (`halt_reason: "another-run-active"`, phase `report:run-lock`), with "**Another test-skill run took over the run lock for {skill_name}.** This run wrote no result files. {message}", where `{message}` is the helper's.
+- Exit 1 or 2, or no JSON: HALT with the helper's stderr message (`halt_reason: "helper-failed"`, phase `report:run-lock`), as init.md §6b does.
 
-**Section anchor presence check (companion to stepsCompleted).** The
-report template ships six canonical H2 anchors — one per populating step. An
-off-sequence run (e.g. a step wrote its section into the wrong anchor, or a
-subagent truncated the file) can leave `stepsCompleted` intact while a section
-is missing. `grep -n` each anchor below against `{outputFile}`; each must
-return ≥1 match:
+The run lock renewed here stays held until §7 releases it, so no other run publishes over this run's report or result files meanwhile.
 
+**Build the result payload** before the report takes its public name. Every value in it comes from the run's own records: `{resultContextScript}` (it resolves relative to the skill root) reads the report frontmatter, the gap ledger and the scoring output, checks the verdict fields score.md §7 wrote (`testResult`, `score`, `threshold` and the fallback fields) against the scoring output, derives `verdict`, `exit_code` and `next_workflow` from `testResult`, and writes the shared emitter's payload, which names the report by its public name. Pass `--score` for a scored run (a run the hard gate blocked has no scoring output), `--no-health-check` when that flag was given, and `--warning` when SKILL.md On Activation step 3 kept a `{customization_resolver_unavailable}` reason: first write `customization_resolver_unavailable: {customization_resolver_unavailable}` to `{run_dir}/resolver-warning.txt` with a file write, never `echo` (the reason can hold quotes, backticks or `$( )`), and pass that file's text (the emitter adds the warnings a stage recorded in the run's sink):
+
+```bash
+uv run {resultContextScript} --report "{report_file}" --report-path "{publishedReportFile}" --ledger "{ledgerFile}" [--score "{run_dir}/score.json"] [--no-health-check] [--warning "$(cat "{run_dir}/resolver-warning.txt")"] --output "{run_dir}/result-context.json"
 ```
-^## Test Summary$
-^## Coverage Analysis$
-^## Coherence Analysis$
-^## External Validation$
-^## Completeness Score$
-^## Gap Report$
+
+Bind `{emit_target}` ← `target` from its JSON (`stderr` for a run the hard gate blocked, else `stdout`). Exit 2: correct the command and run it again. Exit 1: HALT with its `error` (`halt_reason: "helper-failed"`, phase `report:result-contract`); the report keeps its in-progress name, so export-skill never reads a verdict the scoring output did not settle.
+
+**Publish the report.** Set `health_check_dispatched` in the `{outputFile}` frontmatter: `false` when `no_health_check` is true (the `--no-health-check` flag), else `true`, since the health check now runs with no menu before it. The checks passed, so the report takes its public name, the one export-skill and update-skill read, a blocked run's included. From `{project-root}`, run:
+
+```bash
+mv "{report_file}" "{publishedReportFile}"
 ```
 
-On any miss, HALT with "report anchor missing: {anchor} — section was not
-appended by its owning step". **Headless envelope (if `{headless_mode}`):** emit to **stderr** before halting:
+and bind `{report_file}` ← `{publishedReportFile}`. If the move fails, HALT (`halt_reason: "write-failed"`, phase `report:publish`, `"path": "{publishedReportFile}"`): no result file has been written, so the previous run's verdict still stands.
+
+**Write the result contract.** The shared emitter writes it, per `{outputContractSchema}`. In every mode, run:
 
+```bash
+uv run {emitEnvelopeHelper} emit --workflow skf-test-skill --run-dir "{run_dir}" --result-dir "{forge_version}" --target {emit_target} < "{run_dir}/result-context.json"
 ```
-SKF_TEST_RESULT_JSON: {"status":"error","skill_name":"{skill_name}","verdict":null,"score":null,"threshold":null,"report_path":"{outputFile}","next_workflow":null,"exit_code":1,"halt_reason":"report-anchor-missing"}
+
+It writes `{forge_version}/skf-test-skill-result-{YYYYMMDD-HHmmss}.json` (UTC; it picks the name) and then its `skf-test-skill-result-latest.json` copy (stable path for pipeline consumers: a copy, not a symlink), each atomically, so a partial write is never observable; stamps the timestamp, `run_id`, `headless_decisions` and `warnings` into both; and prints the `SKF_TEST_RESULT_JSON:` line. Bind `{result_line}` ← that line and `{result_path}` ← its `result_path`. A run the hard gate blocked writes the record too, as a FAIL (`status: "error"`, `verdict: "FAIL"`, `halt_reason: "hard-gate-blocked"`, `exit_code` 2), so `skf-test-skill-result-latest.json` never holds an earlier run's verdict. A result file that could not be written leaves `result_path` null and a `result_file_write_failed` warning in the line, and the run still finishes. If the emitter exits non-zero, run it once more; if it fails again, HALT (`halt_reason: "write-failed"`, phase `report:result-contract`) with its stderr: the run's result contract could not be written. `references/invocation-contract.md` lists the record's fields.
+
+Once the result files are written, append `'report'` to `stepsCompleted` in the `{outputFile}` frontmatter (it stays out of the expected set above).
+
+**Post-finalization hook.** If `{onCompleteCommand}` (resolved in SKILL.md On Activation §3 from `workflow.on_complete` scalar) is non-empty and `{result_path}` is not null, invoke it as:
+
+```bash
+{onCompleteCommand} --result-path={result_path}
 ```
 
-Do not append `'report'` and do not
-write the result contract. The template at `{testReportTemplatePath}`
-declares these anchors as TBD placeholders; a miss means a step silently
-skipped its append.
+Run it with a bounded timeout (default 60s). On success: log Info note "on_complete: invoked {command}" and continue. On non-zero exit, timeout, or any failure: keep the reason (for example `on_complete failed (exit {N}): {stderr_first_line}`) for a line of its own in §6, and continue. **The hook must never fail the workflow**: its purpose is integration glue (notify a CI router, post to a queue, archive the result) and any failure there is orthogonal to the test verdict, which the result files already hold. If `{onCompleteCommand}` is empty, this hook is a no-op (no log entry needed).
+
+### 5. Finalize Output Document
+
+The report is final once §4c published it and wrote the result files: no later section changes it.
 
-**INCONCLUSIVE as gate:** if `testResult == 'inconclusive'` (from step 5), the report final presentation (§6) and result contract (§4c) have already been written with that verdict. Do not auto-map INCONCLUSIVE to PASS or FAIL. Recommend `manual-review`. The step must still complete (health-check runs unconditionally) — INCONCLUSIVE is a report-time signal, not a workflow abort.
+**INCONCLUSIVE as gate:** if `testResult == 'inconclusive'` (from step 5), §4c wrote the result contract with that verdict and §6 presents it. Do not auto-map INCONCLUSIVE to PASS or FAIL. Recommend `manual-review`. The step must still complete (§7 dispatches the health check): INCONCLUSIVE is a report-time signal, not a workflow abort.
 
 ### 6. Present Final Report
 
@@ -216,17 +261,22 @@ skipped its append.
 
 **Result:** **{PASS|PASS_WITH_DRIFT|FAIL|INCONCLUSIVE}** — **{score}%** (threshold: {threshold}%)
 
+{If the hard gate blocked the run, in place of the line above:}
+**Result:** **FAIL**, not scored: the hard gate blocked the run on {blocking_gaps} Critical or High gap(s).
+
 {If `thresholdFallback` is present in output frontmatter:}
 **Threshold fallback:** scored {score}% against {originalThreshold} target — accepted at 80% floor. Evidence report: {evidenceReportPath}
 
 **Gaps Found:** {total_gaps}
-- Critical: {N}
-- High: {N}
-- Medium: {N}
-- Low: {N}
-- Info: {N}
+- Critical: {gap_counts.Critical}
+- High: {gap_counts.High}
+- Medium: {gap_counts.Medium}
+- Low: {gap_counts.Low}
+- Info: {gap_counts.Info}
 
 **Report saved to:** `{outputFile}`
+{If the on_complete hook failed:}
+**on_complete hook failed:** {its reason}. The verdict and the result files stand.
 
 ---
 
@@ -238,8 +288,11 @@ skipped its append.
 {IF PASS_WITH_DRIFT:}
 **update-skill** — The skill scored above threshold, but `--allow-workspace-drift` was in effect: the test ran against workspace HEAD, not `metadata.source_commit`. A conditional PASS is not trustworthy enough to export. Re-sync the source tree to the pinned commit (or re-extract against current HEAD) and re-run test-skill without the drift override before exporting.
 
-{IF FAIL:}
-**update-skill** — This skill needs remediation. Review the gap report above and run the update-skill workflow to address the {N} blocking issues (Critical + High).
+{IF FAIL after scoring:}
+**update-skill `--from-test-report`**: This skill needs remediation. Review the Gap Report above, then run `@Ferris US {skill_name} --from-test-report`: Update Skill reads this report's gaps and repairs the skill at its pinned commit. Test it again afterwards.
+
+{IF the hard gate blocked the run:}
+**update-skill `--from-test-report`**: The hard gate stopped this run before scoring on {blocking_gaps} Critical or High gap(s), listed first in the Gap Report. Run `@Ferris US {skill_name} --from-test-report` to repair them, then test again.
 
 {IF INCONCLUSIVE:}
 **manual-review** — The evidence base was too thin to grade automatically. See `inconclusiveReasons` in the Completeness Score section. Typical fixes: upgrade forge tier, enable external validators, or re-extract with a wider scope. Do not export.
@@ -250,55 +303,24 @@ skipped its append.
 
 **Test report finalized.**"
 
-### 6b. Determine Headless Exit Code
+### 6b. Keep the Headless Result Envelope for the Last Line
 
-This step only determines the terminal exit code — it does not exit. Both modes then reach §7 (headless auto-proceeds past the menu; non-headless goes through the [C] menu), and the terminal process-exit with this code happens in §7 after the health-check dispatch.
+If `{headless_mode}`, bind `{result_envelope_line}` ← `{result_line}`, the `SKF_TEST_RESULT_JSON` line §4c's emitter printed, a blocked run's included. Do not display it here and never retype it: the shared health check displays it verbatim as the run's last line, after everything else it shows (§7 displays it itself under `--no-health-check`), so it is the final message of a headless run. Non-headless runs bind nothing: the §6 presentation is their result.
 
-If `{headless_mode}`, map `testResult` to the code the workflow will exit with in §7 and store it as `{headless_exit_code}` in workflow context:
-- `testResult: 'pass'` → exit code 0
-- `testResult: 'pass-with-drift'` → exit code 4 (distinct from clean pass — see the pass-with-drift row in SKILL.md Exit Codes; exiting 0 under a drift override would wrongly signal a clean pass)
-- `testResult: 'fail'` → exit code 2 (the result contract was written in §4c — never exit before it)
-- `testResult: 'inconclusive'` → exit code 3 (distinct from fail so orchestrators can route to manual-review queues)
+### 7. Health-Check Dispatch
 
-### 6c. Emit Headless Result Envelope (stdout)
-
-If `{headless_mode}`, emit the terminal result envelope to **stdout** as a single line before chaining to §7 — this is the branchable record a headless orchestrator reads for the happy path (PASS / FAIL / INCONCLUSIVE / pass-with-drift). The SKILL.md Result Contract owns the shape and the field rules; the on-disk copy written in §4c is the richer form. Build it from the settled verdict and the values already in the output frontmatter:
-
-```
-SKF_TEST_RESULT_JSON: {"status":"success","skill_name":"{skill_name}","verdict":"{PASS|FAIL|INCONCLUSIVE|pass-with-drift}","score":{score},"threshold":{threshold},"report_path":"{outputFile}","next_workflow":{export-skill when PASS | update-skill when FAIL or pass-with-drift | null when INCONCLUSIVE},"exit_code":{headless_exit_code},"halt_reason":null}
-```
+**`--no-health-check` flag bypass.** If `no_health_check: true` is set in workflow context (from the `--no-health-check` flag, `init.md` §1), §4c already recorded `health_check_dispatched: false` in the report and `healthCheckDispatched: false` in the result files. Release the run lock now, from `{project-root}`, with `uv run {runLockHelper} release --lock "{forge_version}/.test-skill.lock" --owner "{run_owner}"`, and remove the run folder with `rm -rf "{project-root}/_bmad-output/.skf-run/skf-test-skill-{run_id}"`. Log Info note "health-check: skipped, --no-health-check flag set", then, in `{headless_mode}`, display `{result_envelope_line}` verbatim as the run's last line, with nothing after it. The workflow ends there (non-headless, after the §6 presentation): do not chain to `{nextStepFile}`. This flag is the one path where §7 does not dispatch the health-check.
 
-`verdict` is uppercase for `pass`/`fail`/`inconclusive` (→ `PASS`/`FAIL`/`INCONCLUSIVE`) and the literal `pass-with-drift`. When threshold fallback occurred (frontmatter `thresholdFallback: true`), add `"threshold_fallback":true` and `"original_threshold":{originalThreshold}`; omit both otherwise. Non-headless runs skip this emission — the §6 presentation is their terminal output.
+**Release the run lock:** §4c's write of the result files was the run's last, and the health check writes none, so no run waits on this one while the health check runs. From `{project-root}`, run:
 
-### 7. Health-Check Dispatch + MENU OPTIONS
-
-**`--no-health-check` flag bypass (precedes the health-check resolution).** If `no_health_check: true` is set in workflow context (from §1 of `init.md` — `--no-health-check` flag on invocation), set `health_check_dispatched: false` in the output report frontmatter and mirror `healthCheckDispatched: false` into the result contract written in §4c (re-write atomically via `{atomicWriteHelper}`). Log Info note "health-check — skipped: --no-health-check flag set" and exit the workflow: in `{headless_mode}`, exit with `{headless_exit_code}` (determined in §6b); non-headless, simply terminate after the §6 presentation. Do not resolve `{healthCheckFile}`, do not display the menu, do not chain to `{nextStepFile}`. This flag is the one path where §7 does not dispatch the health-check.
-
-Resolve `{healthCheckFile}`: probe `{healthCheckProbeOrder}` in order. **HALT** if neither candidate exists — the health-check is the true terminal step; without it the workflow cannot complete honestly:
-
-```
-Error: cannot locate shared/health-check.md at either of:
-  - {project-root}/_bmad/skf/shared/health-check.md
-  - {project-root}/src/shared/health-check.md
-
-test-skill delegates its terminal step to the shared health-check. Install
-the SKF module or run from a development checkout with src/ present.
+```bash
+uv run {runLockHelper} release --lock "{forge_version}/.test-skill.lock" --owner "{run_owner}"
 ```
 
-**Headless envelope (if `{headless_mode}`):** emit to **stderr** before halting:
+Then remove the run folder init.md §6b created: no later step reads it.
 
+```bash
+rm -rf "{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":"{outputFile}","next_workflow":null,"exit_code":1,"halt_reason":"health-check-missing"}
-```
-
-Before displaying the menu, write the dispatch decision into the output report frontmatter (so the artifact records whether the health-check ran):
-
-- `health_check_dispatched: true` — when the C menu choice will be taken (headless, or user will select C)
-- `health_check_dispatched: false` — should be rare (only if operator explicitly skips, e.g. future flag)
-
-Also mirror the boolean into the `healthCheckDispatched` field of the result contract written in §4c (re-write atomically via `{atomicWriteHelper}` if the dispatch decision is made after the initial contract write).
-
-Display: "**Test complete.** [C] Finish"
-
-On [C] (or auto-proceed in `{headless_mode}` — log: "headless: auto-continue past report menu"): set `health_check_dispatched: true` in frontmatter, then load and execute `{nextStepFile}` (the local health-check dispatcher). The test report document at `{outputFile}` contains the full analysis: Test Summary, Coverage Analysis, Coherence Analysis, Completeness Score, and Gap Report. In `{headless_mode}`, once the dispatched health-check completes, the workflow makes its terminal process-exit with `{headless_exit_code}` (determined in §6b) — this is the single terminal exit for the headless happy path.
 
+Then load and execute `{nextStepFile}` (the local health-check step, which hands over to the `{healthCheckFile}` §4c found), with no menu before it: the run is finished, and the health check is informational. The test report at `{outputFile}` contains the full analysis: Test Summary, Coverage Analysis, Coherence Analysis, Completeness Score, and Gap Report. In `{headless_mode}`, `{result_envelope_line}` (§6b) is bound, and the health check displays it as the run's last line.