bmad-module-skill-forge 2.2.0 → 3.0.0

package/src/skf-analyze-source/references/generate-briefs.md

@@ -1,9 +1,15 @@
 ---
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
-schemaFile: '{briefSchemaPath}'
+schemaFile: 'assets/skill-brief-schema.md'
+writeSkillBriefProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-write-skill-brief.py'
+  - '{project-root}/src/shared/scripts/skf-write-skill-brief.py'
 validateBriefSchemaProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-validate-brief-schema.py'
   - '{project-root}/src/shared/scripts/skf-validate-brief-schema.py'
+scanManifestsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-scan-manifests.py'
+  - '{project-root}/src/shared/scripts/skf-scan-manifests.py'
 nextStepFile: 'health-check.md'
 ---
 
@@ -13,71 +19,112 @@ nextStepFile: 'health-check.md'
 
 ## STEP GOAL:
 
-To generate a valid skill-brief.yaml file for each confirmed unit using the schema, write the files to the forge data folder, append generation results to the analysis report, and recommend the appropriate next workflow for each unit — completing the analyze-source workflow.
+To write a valid skill-brief.yaml for each confirmed unit through the brief writer, append the generation results to the analysis report, recommend the next workflow for each unit and end the run with its result files and envelope, completing the analyze-source workflow (also when no unit was confirmed).
 
 ## Rules
 
 - Generate only for units in confirmed_units — no extras, no omissions
-- Do not modify recommendations or re-ask for confirmations
+- Do not revisit the per-unit decisions of step 5: the §4 preview confirms only the write
 - Every generated field must trace back to data collected in steps 02-05
+- Briefs are written only by the brief writer, from a context file: never render or hand-edit brief YAML
 - Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing summary is not the terminal step
 
 ## MANDATORY SEQUENCE
 
+Every HARD HALT in this step names its exit code, `halt_reason` and phase. When `{headless_mode}` is true it first prints its envelope on stderr through the shared emitter (`{emitEnvelopeHelper}` and `{run_dir}` come from SKILL.md On Activation): stage `{run_dir}/halt.json` as `{"phase": "<phase>", "reason": "<the halt message>", "halt_reason": "<halt_reason>", "mode": "interactive", "report_path": "{outputFile as an absolute path}"}`, plus `"path"` when the halt names one and the envelope fields the site names, then run
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-analyze-source --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
+
+and display the line it prints verbatim. Write the payload as valid JSON: in the halt message and `path`, replace each backslash with / and each double quote with a backtick. If the emitter exits non-zero or prints no line, display the halt message alone. An interactive HALT displays its message and emits nothing.
+
 ### 1. Load Context
 
 Read {outputFile} completely to obtain:
 - `confirmed_units` from frontmatter (names of units approved in step 05)
-- `project_paths`, `forge_tier`, `user_name`, `forge_data_folder` from frontmatter
-- Recommendation cards from "## Recommendations" section (proposed brief fields per unit)
+- `confirmed_composites` from frontmatter (composites approved in step 04, each with its constituents' names and paths)
+- `project_paths`, `refs`, `forge_tier`, `user_name`, `forge_data_folder` from frontmatter
+- Recommendation cards from "## Recommendations" section (proposed brief fields and the project path of each unit)
 - Export map and integration data from prior sections
 
 Load {schemaFile} for validation reference.
 
-**Guard clause:** If `confirmed_units` is empty, present:
+**No confirmed unit:** If `confirmed_units` is empty, present:
 "**No confirmed units to generate briefs for.** The analysis is complete with no skill briefs produced. Run analyze-source again with different scope or parameters if needed."
-Mark workflow complete and halt.
+The run still ends through the same sequence as one that wrote briefs: skip §2 to §6 and continue at §7, which appends the Generation Results with no brief and adds `generate-briefs` to `stepsCompleted` (so a re-run starts a fresh analysis instead of resuming into this guard), then §8, §9 (an envelope and result contract with `brief_paths: []` and `unit_counts.confirmed: 0`), §9b and §10.
+
+### 2. Build Each Brief's Context
 
-### 2. Generate Skill-Brief YAML Per Unit
+**Resolve `{writeSkillBriefHelper}`** from `{writeSkillBriefProbeOrder}` and **`{validateBriefSchemaHelper}`** from `{validateBriefSchemaProbeOrder}`; first existing path wins for each. If one has no candidate, HARD HALT (exit code 3, `halt_reason: "resolution-failure"`, phase `generate-briefs:2`): "`{the missing script}` is missing. Re-install SKF."
 
-For each unit in `confirmed_units`, construct a skill-brief.yaml using:
+The brief writer renders, checks and writes each brief, and applies the version precedence (`target_version`, then `detected_version`, then `1.0.0`): this step supplies the values. For each unit in `confirmed_units`, take them from:
 
 **Field mapping:**
 
 | Field | Source |
 |-------|--------|
-| name | Confirmed name from step 05 recommendation card |
-| version | Auto-detect from source (see schema Version Detection), fall back to `1.0.0` |
-| source_repo | `{project_paths[0]}` from frontmatter (or per-unit path if multi-repo) |
+| name | Confirmed name from step 05 recommendation card: the name identify-units Step C derived, unless step 5 renamed the unit |
+| version | Not set here: `detected_version` comes by {schemaFile}'s **Version Detection**, for the unit's own manifest in its project path's manifest scan, `{run_dir}/manifests-{i}.json` (scan-project and discover-additional-source write it). When that file is missing, as in a session that resumed the report, run `uv run {scanManifestsHelper} scan "{scan_root}" > "{run_dir}/manifests-{i}.json"` first, `{scanManifestsHelper}` the first existing path of `{scanManifestsProbeOrder}` |
+| source_repo | The unit's project path, the `project_paths[]` entry it was found under (a composite's constituents share one) |
+| target_ref | The unit's ref: its project path's entry in `refs`, else null. Never a version: `target_version` stays null |
 | language | Language the skill **documents** (primary language detected in step 03). For a language / spec reference this is the *documented* language, which may differ from the source language it is extracted from — e.g. a SurrealQL reference extracted from a Rust engine records `surrealql`, not `rust` (see {schemaFile} "Documented vs source language") |
 | scope.type | Scope type from step 05 recommendation card |
-| scope.include | Include patterns from step 05 recommendation card |
+| scope.include | Include patterns from step 05 recommendation card, plus, for a composite (`Boundary: Composite` on its card), `<path>/**` for every constituent path of its `confirmed_composites` entry (such as `crates/animato-core/**`), so the brief spans every constituent. Find the entry by those paths, which the card's Path lists, not by name: step 05 may rename the unit |
 | scope.exclude | Inferred from heuristics (test files, generated code) |
 | scope.tier_a_include | Optional — narrower tier-A surface for stratified-scope monorepos and `reference-app` pattern surfaces; usually left to skf-brief-skill to refine |
 | scope.notes | Rationale from step 05 recommendation card |
 | description | Description from step 05 recommendation card |
 | forge_tier | `{forge_tier}` from frontmatter |
-| created | Current date as a **quoted** string in ISO format `'YYYY-MM-DD'` — quote it so YAML stores it as text, not a parsed date object (the schema, and the §3a gate, require a string) |
+| created | Current date, `YYYY-MM-DD` |
 | created_by | `{user_name}` from frontmatter |
 
+Write each unit's context as `{run_dir}/brief-{unit-name}.json`, a file and never an echo'd string:
+
+```json
+{
+  "name": "{unit-name}",
+  "target_version": null,
+  "target_ref": "{the unit's ref, or null}",
+  "detected_version": "{version, or null}",
+  "source_type": "source",
+  "source_repo": "{source_repo}",
+  "language": "{language}",
+  "description": "{description}",
+  "forge_tier": "{forge_tier}",
+  "created": "{current_date}",
+  "created_by": "{user_name}",
+  "scope_type": "{scope.type}",
+  "scope_include": ["{scope.include}"],
+  "scope_exclude": ["{scope.exclude}"],
+  "scope_notes": "{scope.notes}",
+  "scope_rationale": null,
+  "scope_tier_a_include": null,
+  "scope_amendments": null,
+  "scope_registry_path": null,
+  "scope_ui_variants": null,
+  "scope_demo_patterns": null,
+  "doc_urls": null,
+  "scripts_intent": null,
+  "assets_intent": null,
+  "source_authority": null,
+  "source_ref": null
+}
+```
+
 ### 3. Validate Each Brief
 
-Validation has two parts: a **deterministic schema gate** (authoritative for structure) and **semantic cross-checks** the schema cannot express. Run the schema gate first.
+Validation has two parts: a **deterministic gate** (authoritative for structure) and **semantic cross-checks** the schema cannot express. Run the gate first.
 
-**3a. Deterministic schema gate.** Resolve `{validateBriefSchemaHelper}` from `{validateBriefSchemaProbeOrder}` (first existing path wins; HALT with a clear message if no candidate exists). For each generated brief, pipe the *exact* assembled YAML to the helper:
+**3a. Deterministic gate.** Render each brief into the run folder, then run on it the schema check `skf-brief-skill` runs when it reads a brief, so a brief that passes here is not rejected there for structural reasons:
 
 ```bash
-uv run {validateBriefSchemaHelper} - <<'YAML'
-{assembled-brief-yaml}
-YAML
+uv run {writeSkillBriefHelper} write --target "{run_dir}/briefs/{unit-name}/skill-brief.yaml" --from-flat < "{run_dir}/brief-{unit-name}.json"
+uv run {validateBriefSchemaHelper} "{run_dir}/briefs/{unit-name}/skill-brief.yaml"
 ```
 
-The script returns JSON `{valid, errors[], warnings[], halt_reason, brief}` — the same validator and contract `skf-brief-skill` runs at consumption time, so a brief that passes here will not be rejected there for structural reasons. Apply the result:
-
-- **`valid: false`** — the `errors[]` name the offending field (e.g. a `description` mis-indented under `scope:`, which leaves the required top-level `description` absent). Repair the assembled YAML and re-run the helper until `valid: true`. A brief is written only after it passes this gate.
-- **`valid: true`** — carry any non-empty `warnings[]` into the §4 preview, then proceed.
-
-This catches structural YAML errors where they are created, rather than letting them surface downstream as a HALT in `skf-brief-skill`'s ratify path.
+- **The writer exits non-zero, or the validator answers `valid: false`:** the `message` and `field` of the writer's stderr JSON, or the validator's `errors[]`, name the offending field. Correct that value in `{run_dir}/brief-{unit-name}.json` when it is a value you mistyped from the recommendation card, and run both commands again; a value the user must decide is presented in §4 for correction (`M`). In headless mode a brief still rejected after one correction is a HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `generate-briefs:3`, path `{forge_data_folder}/{unit-name}/skill-brief.yaml`, with `unit_counts` from step 5): "The brief for {unit-name} was rejected: {the message}." A brief is written only after it passes this gate.
+- **Both pass:** carry the writer's and the validator's non-empty `warnings` into the §4 preview, then proceed.
 
 **3b. Semantic cross-checks** (not expressible in the JSON schema — apply in addition to 3a):
 
@@ -90,7 +137,8 @@ This catches structural YAML errors where they are created, rather than letting
 
 **If any check fails:**
 - Document the failure with specific field and reason
-- Repair (3a structural errors) or present to user for correction (3b semantic issues) before writing — an invalid brief is not written
+- Correct the context (3a) or present to user for correction (3b semantic issues) before writing: an invalid brief is not written
+- In headless mode no one corrects it: correct what the recommendation card and the report settle and check again, once; a brief still failing a 3b check is a HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `generate-briefs:3`, path `{forge_data_folder}/{unit-name}/skill-brief.yaml`, with `unit_counts` from step 5), as in 3a: "The brief for {unit-name} failed the {check} check: {the reason}."
 
 ### 4. Present Generation Preview
 
@@ -100,9 +148,9 @@ This catches structural YAML errors where they are created, rather than letting
 
 {For each unit:}
 ---
-**{unit-name}** → `{forge_data_folder}/{unit-name}/skill-brief.yaml`
+**{unit-name}** → `{forge_data_folder}/{unit-name}/skill-brief.yaml`{, replacing the earlier brief there when the unit is in `existing_briefs`}
 ```yaml
-{complete YAML content}
+{the content of {run_dir}/briefs/{unit-name}/skill-brief.yaml, as the writer rendered it}
 ```
 ---
 
@@ -113,20 +161,29 @@ This catches structural YAML errors where they are created, rather than letting
 
 Wait for explicit user confirmation before writing files.
 
-**GATE [default: Y]** — If `{headless_mode}` is true: auto-confirm [Y], write all briefs, and log: "headless: auto-write {count} briefs". Do not stall at this gate — it is the deliverable-producing step of a headless/pipeline run.
+**GATE [default: Y]**: if `{headless_mode}` is true, auto-confirm [Y] and write all briefs, and record that decision the moment it is taken: stage `{run_dir}/decision.json` as `{"gate": "generate-briefs.write", "default_action": "Y", "taken_action": "Y", "reason": "headless: auto-write {count} briefs", "evidence": {"briefs": [<each unit name>]}}`, then run
+
+```bash
+uv run {emitEnvelopeHelper} record --workflow skf-analyze-source --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"
+```
+
+If the command fails, go on: only that entry is lost. Do not stall at this gate: it is the deliverable-producing step of a headless or pipeline run.
 
 ### 5. Write Files
 
 **IF user confirms (Y):**
 
-For each confirmed brief:
-1. Create directory `{forge_data_folder}/{unit-name}/` if it does not exist
-2. Write `skill-brief.yaml` to `{forge_data_folder}/{unit-name}/skill-brief.yaml` — write the exact YAML that passed the §3a schema gate verbatim; do not re-serialize, so the bytes on disk are the bytes that validated
-3. Verify the file was written; if the write fails, HARD HALT with exit code 4 (`write-failed`) per `references/headless-contract.md`
+Write each brief to its place from the context that passed §3 (the writer renders the same bytes the preview showed, creates the folder and writes atomically):
+
+```bash
+uv run {writeSkillBriefHelper} write --target "{forge_data_folder}/{unit-name}/skill-brief.yaml" --from-flat < "{run_dir}/brief-{unit-name}.json"
+```
+
+Keep each `brief_path` it prints for §9. If it exits non-zero, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `generate-briefs:5`, path `{forge_data_folder}/{unit-name}/skill-brief.yaml`, with `unit_counts` from step 5 and the `brief_paths` written so far): "The brief for {unit-name} could not be written: {its `message`}."
 
 **IF user modifies (M):**
 - Ask which brief and what to change
-- Update the YAML, re-validate, present again
+- Update `{run_dir}/brief-{unit-name}.json`, run the §3 gate again, present again
 - Return to confirmation prompt
 
 **IF user skips writing (N):**
@@ -134,7 +191,7 @@ For each confirmed brief:
 - Skip file writing, proceed to report update
 
 **IF user cancels (X):**
-- HARD HALT with exit code 6 (`user-cancelled`). Emit the error envelope on stderr with `halt_reason: "user-cancelled"`, `brief_paths: []`, and `unit_counts` reflecting the confirmed/skipped/maybe state from step 5 (shape in `references/headless-contract.md`)
+- HARD HALT (exit code 6, `halt_reason: "user-cancelled"`, phase `generate-briefs:4`), with `brief_paths: []` and `unit_counts` reflecting the confirmed/skipped/maybe state from step 5 in its payload: "Cancelled before any brief was written."
 
 ### 6. Determine Next Workflow Per Unit
 
@@ -204,41 +261,50 @@ nextWorkflow: '{primary recommendation}'
 
 To refine any brief, run the recommended next workflow. To re-analyze with different scope, run analyze-source again."
 
-### 9. Result Contract
-
-Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{forge_data_folder}/analyze-source-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all generated `skill-brief.yaml` paths in `outputs` and brief counts in `summary`. If the per-run record cannot be written, HARD HALT with exit code 4 (`write-failed`) per `references/headless-contract.md`.
-
-### 9a. Emit Result Envelope
+### 9. End the Run
+
+The shared emitter writes the result files and prints the envelope; this section stages their content, in every mode. Write `{run_dir}/result-context.json`:
+
+```json
+{
+  "status": "success",
+  "report_path": "{outputFile as an absolute path}",
+  "brief_paths": ["{the brief_path of each brief §5 wrote}"],
+  "unit_counts": {"confirmed": <confirmed count from step 5>, "skipped": <rejected count from step 5>, "maybe": 0},
+  "mode": "interactive",
+  "result_contract": {
+    "skill": "skf-analyze-source",
+    "status": "success",
+    "outputs": [{"type": "report", "path": "{outputFile as an absolute path}"}, {"type": "brief", "path": "{each brief_path}"}],
+    "summary": {"mode": "interactive", "brief_count": <briefs written>, "confirmed_units": <confirmed count>, "stack_skill_candidates": <count>, "next_workflow": "{primary recommendation}"}
+  }
+}
+```
 
-When `{headless_mode}` is true, emit the `SKF_ANALYZE_RESULT_JSON` envelope on **stdout** — the success signal for the interactive path, alongside §9's on-disk record (both are produced):
+`brief_paths` is empty, and so is the brief part of `outputs`, when no unit was confirmed or the user skipped writing with [N]. Then run:
 
+```bash
+uv run {emitEnvelopeHelper} emit --workflow skf-analyze-source --run-dir "{run_dir}" --result-dir "{forge_data_folder}" < "{run_dir}/result-context.json"
 ```
-SKF_ANALYZE_RESULT_JSON: {"status":"success","report_path":"{outputFile_abs_path}","brief_paths":["{brief_path_1}",…,"{brief_path_N}"],"unit_counts":{"confirmed":N,"skipped":N,"maybe":N},"exit_code":0,"halt_reason":null,"mode":"interactive"}
-```
-
-- `report_path` — absolute path to {outputFile}.
-- `brief_paths` — every `skill-brief.yaml` written in §5 (empty array when the user skipped writing with [N]).
-- `unit_counts` — confirmed/skipped counts from step 5 (`maybe` reserved; see `references/headless-contract.md`).
 
-When `{headless_mode}` is false (interactive human run), skip this section — there is no pipeline consumer to signal.
+The emitter stamps the UTC time and the run id into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy (the stable path pipeline consumers read), and prints the `SKF_ANALYZE_RESULT_JSON:` line on stdout (field rules in `references/headless-contract.md`). When `{headless_mode}` is true, display the line verbatim: it is the success signal of a headless run. A result file that could not be written leaves the line's `result_path` null and a `result_file_write_failed` warning in it, and the run still finishes. If the emitter exits non-zero, correct `result-context.json` from the message on its stderr and run it once more; if it fails again, HARD HALT (exit code 4, `halt_reason: "write-failed"`, phase `generate-briefs:9`, path `{forge_data_folder}`, with `brief_paths` and `unit_counts` from the payload): "The result contract could not be written: {its message}."
 
 ### 9b. On-Complete Hook (pipeline integration)
 
-If `{onCompleteCommand}` is non-empty, invoke it now — after the timestamped result JSON and the `analyze-source-result-latest.json` copy have both been written:
+If `{onCompleteCommand}` is non-empty and the §9 line's `result_path` is not null, invoke it now, after the emitter wrote the timestamped result JSON and its `analyze-source-result-latest.json` copy:
 
 ```
-{onCompleteCommand} --result-path={result_json_path}
+{onCompleteCommand} --result-path={forge_data_folder}/analyze-source-result-latest.json
 ```
 
-Where `{result_json_path}` is the absolute path to the freshly written `analyze-source-result-latest.json` (stable path is preferred over the timestamped copy so downstream consumers don't need to discover the timestamp).
+The stable `-latest` path is preferred over the timestamped copy so downstream consumers don't need to discover the timestamp.
 
-- On success: log to `workflow_warnings[]` as informational only if the hook emitted stderr (`on_complete hook stderr: …`); otherwise no entry.
-- On non-zero exit / process error: log to `workflow_warnings[]` (`on_complete hook failed (exit {code}): {stderr_snippet}`).
+- On success: display the hook's stderr, if it wrote any, as information (`on_complete hook stderr: …`).
+- On non-zero exit / process error: display the hook failure (`on_complete hook failed (exit {code}): {stderr_snippet}`); it never fails the run.
 - **Never fail the workflow on hook errors** — the hook is for pipeline integration (Slack, dashboards, CI), not for gating skill-brief production.
 
 If `{onCompleteCommand}` is empty, skip this section entirely (default behavior — no hook configured).
 
 ### 10. Chain to Health Check
 
-After the briefs are written (or skipped per user abort), the report updated, the summary presented, the result contract saved, and the on-complete hook invoked (or skipped per empty `{onCompleteCommand}`), load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — continue past the summary even though it reads as final.
-
+After the briefs are written (or skipped, or none was confirmed), the report updated, the summary presented, the run ended in §9 and the on-complete hook invoked (or skipped per empty `{onCompleteCommand}`), delete the run folder, whose payloads the emitter has read: `rm -rf "{run_dir}"`. Then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step: continue past the summary even though it reads as final.

package/src/skf-analyze-source/references/headless-contract.md

@@ -1,24 +1,51 @@
 # Headless Result Contract & Exit Codes
 
-Canonical headless/pipeline contract for skf-analyze-source. Step files emit the envelope and exit with the codes defined here.
+Canonical headless/pipeline contract for skf-analyze-source. The shared emitter, `shared/scripts/skf-emit-result-envelope.py` (`{emitEnvelopeHelper}`, bound at SKILL.md On Activation §1), builds every line from the payload a step stages in `{run_dir}` and checks it against `shared/scripts/schemas/skf-analyze-result-envelope.v1.json`, so no step types an envelope.
 
 ## Result Envelope
 
-When `{headless_mode}` is true, step 6 (interactive) or step 1a (auto) emits a single-line JSON envelope on **stdout** before chaining to step 7. Every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`, using the exit code and `halt_reason` named at that HALT — so an automator branches on the failure class without grepping message text.
+The step that ends a run (step 6 §9, step 1a §9, or the docs-only branch §5) prints the envelope on **stdout** before chaining to step 7, and displays it when `{headless_mode}` is true. Every HARD HALT of a headless run prints it on **stderr** with `status: "error"`, so an automator branches on the failure class without grepping message text.
 
 ```
-SKF_ANALYZE_RESULT_JSON: {"status":"success|error|redirect|skipped","report_path":"…|null","brief_paths":["…"],"unit_counts":{"confirmed":N,"skipped":N,"maybe":N},"exit_code":0,"halt_reason":null,"mode":"interactive|auto"}
+SKF_ANALYZE_RESULT_JSON: {"status":"success|error|redirect|skipped","report_path":"…|null","brief_paths":["…"],"unit_counts":{"confirmed":N,"skipped":N,"maybe":N},"exit_code":0,"halt_reason":null,"mode":"interactive|auto","result_path":"…|null"}
 ```
 
-- `status` — `"success"` on the terminal happy path, `"error"` on any HALT, `"redirect"` when coexistence routes to US (merge), `"skipped"` when the user skips a conflicting target.
-- `halt_reason` — one of `null` (success), `"input-missing"`, `"resolution-failure"`, `"pin-invalid"`, `"write-failed"`, `"user-cancelled"`.
-- `exit_code` — matches the table below.
-- `report_path` — absolute path to the analysis report, or `null` on an early HALT.
-- `brief_paths` — array of absolute paths to every generated `skill-brief.yaml` (empty array if none).
+- `status`: `"success"` when the run ends, also with zero confirmed units (`brief_paths: []`, `unit_counts.confirmed: 0`); `"error"` on any HALT; `"redirect"` when coexistence routes to US (merge); `"skipped"` when the user skips a conflicting target.
+- `halt_reason`: `null` unless the run halted, else one of `"input-missing"`, `"resolution-failure"`, `"pin-invalid"`, `"write-failed"`, `"user-cancelled"`. A brief the writer or the brief schema gate rejects halts with `"write-failed"`.
+- `exit_code`: the emitter derives it from `halt_reason`, per the table below.
+- `report_path`: absolute path to the analysis report, or `null` on a redirect, a skip and an early HALT.
+- `brief_paths`: absolute path of every `skill-brief.yaml` the run wrote (empty array if none). A brief is written only after it passed the brief writer and, outside the docs-only branch, the schema gate.
 - `unit_counts` — `confirmed` (units approved for briefs) and `skipped` (rejected in step 5, or the skipped target in coexistence §0c) counts; auto mode reports `confirmed:N, skipped:0`. `maybe` is a reserved slot, currently always `0`.
-- `mode` — `"auto"` when the `[auto]` flag was active, `"interactive"` otherwise.
+- `mode`: `"auto"` when the invocation carries `[auto]`, from activation through step 1a and the docs-only branch; `"interactive"` otherwise, also in the step-by-step chain an `[auto]` run falls back to (step 1a §3, exit 1).
+- `result_path`: the per-run result file the emitter wrote, stamped by it; `null` for a HALT, which writes no result file, and when the write failed (a `result_file_write_failed` warning then says why).
+- `error`: on a HALT only, `{"phase", "reason"}` plus `path` when the halt names one.
+- `headless_decisions`: present when the run recorded an auto-decision: step 1a's §3b merge-or-split decision (gate `auto-scope.cohesion`), its §4 choices of shape for a repository on a framework or a parser library (gate `auto-scope.shape`) and its §5 choice of the documented language (gate `auto-scope.language`), and each gate default a headless run of the step-by-step chain took: `scan-project.scan`, `identify-units.classifications`, `map-and-detect.findings` (with the composite merges it accepted), `recommend.recommendations` and `generate-briefs.write`.
+- `warnings`: present when the run recorded at least one.
 
-In auto mode the envelope also carries `coexistence` (the §0c decision) and, when a pin resolves, `pinned_ref`/`pinned_version` — `step-auto-scope.md` §0b/§0c define those field semantics. The docs-only path adds `source_type: "docs-only"`.
+In auto mode the envelope also carries `coexistence` (the §0c decision) and, when a pin resolves, `pinned_ref`/`pinned_version`; `step-auto-scope.md` §0b/§0c define those field semantics. A redirect adds `redirect_to`, `skill_name` and `skill_path`, a skip `skipped_reason`, and the docs-only path `source_type: "docs-only"`.
+
+## Ending a Run
+
+The step that ends the run stages `{run_dir}/result-context.json` with the envelope fields it knows and a `result_contract` object, the record the result files hold (`skill`, `status`, `outputs`, `summary`, per `shared/references/output-contract-schema.md`), and runs the emitter in every mode:
+
+```bash
+uv run {emitEnvelopeHelper} emit --workflow skf-analyze-source --run-dir "{run_dir}" --result-dir "{forge_data_folder}" < "{run_dir}/result-context.json"
+```
+
+The emitter stamps the UTC time, the run id, the decisions and warnings the run recorded into the record, writes `{forge_data_folder}/analyze-source-result-{YYYYMMDD-HHmmss}.json` and its `analyze-source-result-latest.json` copy, and prints the line. 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, the step corrects the payload from the message on its stderr and runs it once more; if it fails again, it HARD HALTs with exit code 4 (`write-failed`). Then `{onCompleteCommand}` runs, when it is set and `result_path` is not null, with `--result-path={forge_data_folder}/analyze-source-result-latest.json`; a hook failure is displayed and never fails the run. Last, the step deletes `{run_dir}` and chains to step 7.
+
+## Halt Envelope
+
+Every HARD HALT names its exit code, `halt_reason` and phase where it stops. In headless mode it prints its envelope before it stops: it stages `{run_dir}/halt.json` as `{"phase": "<phase>", "reason": "<the halt message>", "halt_reason": "<halt_reason>", "mode": "<auto or interactive>"}`, plus `"path"` when the halt names one, runs the first command below and displays the line it prints verbatim. A halt before SKILL.md On Activation §5 created `{run_dir}` hands that payload, on one line, to the second command. Write the payload as valid JSON: in the halt message and `path`, replace each backslash with / and each double quote with a backtick. The emitter gives every field the payload leaves out its default (`null`, `[]`, zero counts, `"interactive"`) and derives `exit_code` from `halt_reason`. When the helper is missing, exits non-zero or prints no line, display the halt message alone. An interactive HALT displays its message and emits nothing. A halt writes no result file and keeps `{run_dir}`.
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-analyze-source --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-analyze-source --target stderr <<'SKF_ANALYZE_HALT'
+{"phase": "on-activation:config", "reason": "<the halt message>", "halt_reason": "input-missing", "mode": "interactive"}
+SKF_ANALYZE_HALT
+```
+
+Each step file states this rule in its own opening, so the HALTs of a step never depend on this file.
 
 ## Exit Codes
 
@@ -26,8 +53,8 @@ Every HARD HALT exits with a stable code so headless automators can branch on th
 
 | Code | Meaning | Raised by |
 | ---- | -------------------- | ------------------------------------------------------------------------------------------ |
-| 0    | success / skipped / redirect | step 7 (terminal — health check completion); coexistence `"skipped"`/`"redirect"` statuses from §0c |
-| 2    | input-missing        | On Activation (config.yaml not loadable); step 1 §3 (project path empty/invalid in headless mode); step 1 §2b (auto mode without `--project-path`) |
-| 3    | resolution-failure   | step 1 §2 (`forge-tier.yaml` missing at `{sidecar_path}/forge-tier.yaml`); step 1 §3 (project path does not exist or remote URL inaccessible); step 1a §0a (docs-only URL unreachable); step 1a §0b (`halt_reason: "pin-invalid"` when the supplied `--pin` matches no tag or branch); step 1a §3 (shape detection script error, exit code 2) |
-| 4    | write-failed         | a failed write of the analysis report (step 1 §6 / step 1a §7 / §0a), a `skill-brief.yaml` (step 6 §5 / step 1a §8 / §0a), or the result contract (step 6 §9 / step 1a §10 / §0a) |
-| 6    | user-cancelled       | any interactive menu in steps 2/3/5/6 (user selected `[X]` Cancel and exit) |
+| 0    | success / skipped / redirect | the step that ends the run: step 6 §9 (briefs written, or none when no unit was confirmed), step 1a §9, docs-only §5; coexistence `"skipped"`/`"redirect"` statuses from §0c |
+| 2    | input-missing        | On Activation §2 (config.yaml not loadable); step 1 §2b (auto mode without `--project-path`); step 1 §3 (no project path in headless mode); step 1 §4 (`--target-refs` given with `--target-ref`, or a `--target-refs` key that matches no project path) |
+| 3    | resolution-failure   | step 1 §2 (`forge-tier.yaml` missing at `{sidecar_path}/forge-tier.yaml`); step 1 §2b and §4 (project path does not exist or remote URL inaccessible, headless); step 1a §0 (a documentation URL that git reads as a repository, which on most hosts is the repository's main page, one whose server asks for credentials, or one that gives git no answer in 20 s: rerun with its `.git` clone URL, its address without https:// or its SSH address, or a documentation URL that answers; a repository browser page git cannot read at that address, such as a Bitbucket Data Center `/projects/<p>/repos/<r>` page, a SourceForge or Launchpad code page or a link to a file or folder inside a repository, is still read as documentation, so give its clone URL); step 1a §0a (docs-only URL unreachable); step 1a §0b (`halt_reason: "pin-invalid"` when the supplied `--pin` matches no tag or branch, `resolution-failure` when the pin helper fails); step 1a §2 (a remote path cannot be fetched, another path halts as in §0, or the target's files cannot be listed); step 1a §3 (shape detection script error, exit code 2); step 2 §2 (a project path cannot be fetched at its ref); step 3 §1 and step 4 §1 (a scan root a resumed session makes again cannot be fetched); a shared helper script found at none of its probe paths (On Activation §1; step 1 §5; step 1a §0, §0b, §2, §3, §5 and §8, and its split branch; docs-only §2 and §4; step 2 §2; step 3 §2 and §4; step 4 §2, §3 and §5, and the [D] discover file of steps 4 and 5; step 6 §2) |
+| 4    | write-failed         | On Activation §5 (the run folder cannot be created); step 1 §1 (an earlier report cannot be archived); a failed write of the analysis report (step 1 §6 / step 1a §7 / docs-only §3); a brief the writer or the schema gate rejects, or a brief write that fails (step 6 §3 and §5 / step 1a §8 / docs-only §4), and a brief that still fails a semantic check of step 6 §3 in headless mode; the emitter failing twice when the run ends (step 6 §9 / step 1a §9 / docs-only §5) |
+| 6    | user-cancelled       | any interactive menu in steps 2/3/4/5/6 (user selected `[X]` Cancel and exit) |