bmad-module-skill-forge 1.3.0 → 1.4.0

package/src/skf-brief-skill/steps-c/step-05-write-brief.md

@@ -1,6 +1,12 @@
 ---
 briefSchemaFile: 'assets/skill-brief-schema.md'
+versionResolutionFile: 'references/version-resolution.md'
+qmdRegistrationFile: 'references/qmd-collection-registration.md'
 nextStepFile: './step-06-health-check.md'
+writeSkillBriefScript: '{project-root}/src/shared/scripts/skf-write-skill-brief.py'
+emitBriefEnvelopeScript: '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
+forgeTierRwScript: '{project-root}/src/shared/scripts/skf-forge-tier-rw.py'
+forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 ---
 
 # Step 5: Write Brief
@@ -15,145 +21,136 @@ To generate the complete skill-brief.yaml from the approved brief data and write
 - Do not change any field values without user request — the brief was already approved
 - Create the output directory if it doesn't exist
 - Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing success summary is NOT the terminal step
+- All user-facing output in `{communication_language}`; written artifact (`description`, `notes`) in `{document_output_language}`
+- **Determinism delegation:** YAML rendering, version-precedence, atomic write, the headless result envelope, and the QMD-collection registry mutation are all delegated to shared SKF scripts. The LLM's job in this step is to assemble inputs, branch on script results, and surface user-facing prose — not to render YAML, JSON envelopes, or YAML-mutation diffs in the model.
 
 ## MANDATORY SEQUENCE
 
 **CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
 
-### 1. Load Schema Template
+### 1. Reference the Schema (LLM context only)
 
-Load `{briefSchemaFile}` to reference the YAML template structure.
+`{briefSchemaFile}` and `{versionResolutionFile}` document the brief contract for human readers. The deterministic enforcement of that contract lives in `{writeSkillBriefScript}` and its JSON Schema artifact at `src/shared/scripts/schemas/skill-brief.v1.json`. Load `{briefSchemaFile}` only if you need to explain a specific field to the user during inline adjustments — otherwise skip the read; the script is the source of truth.
 
-### 2. Create Output Directory
+### 2. Resolve Output Path
 
-Create the directory `{forge_data_folder}/{skill-name}/` if it doesn't already exist.
+Resolve the target write path:
+- Primary: `{forge_data_folder}/{skill-name}/skill-brief.yaml`
+- Fallback (when `{forge_data_folder}` is not set or doesn't exist): `{output_folder}/forge-data/{skill-name}/skill-brief.yaml` and inform user "**Note:** forge_data_folder not configured. Writing to {output_folder}/forge-data/{skill-name}/ instead."
 
-If `{forge_data_folder}` is not set or doesn't exist:
-- Fall back to `{output_folder}/forge-data/{skill-name}/`
-- Inform user: "**Note:** forge_data_folder not configured. Writing to {output_folder}/forge-data/{skill-name}/ instead."
+The script's atomic-write helper creates parent directories as needed (`mkdir -p`) — no separate mkdir call required.
 
-### 3. Generate skill-brief.yaml
+### 2b. Existing Brief — Overwrite Policy
 
-**Resolve the `version` field before generating the YAML:**
+Before writing, check whether the resolved target path already exists.
 
-- If `target_version` was set in step 01 (the user explicitly asked for a specific version), use `target_version` as the value of the `version` field. This is the authoritative version for create-skill.
-- Otherwise, use the auto-detected source version from step 02, or `1.0.0` if none was detected.
+**Interactive (`{headless_mode}` is false):**
 
-`target_version` and `version` must never carry different values in the written brief. When the user provided a `target_version`, also include it as a separate `target_version` field so downstream tooling can distinguish "user-requested" from "auto-detected" without re-deriving the provenance — but its value must be identical to `version`.
+If the file exists, present:
 
-Generate the YAML file using the approved field values and the schema template:
+"**An existing brief was found at `{path}`.**
+Overwrite it with the brief you just approved? [Y/N]"
 
-```yaml
----
-name: "{approved skill name}"
-version: "{resolved version — target_version if set, else detected source version, else 1.0.0}"
-source_type: "{source or docs-only}"
-source_repo: "{approved source repo or doc site URL}"
-language: "{approved language}"
-description: "{approved description}"
-forge_tier: "{approved forge tier}"
-created: "{current date}"
-created_by: "{user_name}"
-scope:
-  type: "{approved scope type}"
-  include:
-    - "{approved include patterns}"
-  exclude:
-    - "{approved exclude patterns}"
-  notes: "{approved scope notes or empty string}"
----
-```
+- **[Y]** Overwrite — proceed to §3.
+- **[N]** Cancel — emit a single-line stderr log `brief-skill: overwrite-cancelled at {path}` and HALT with exit code 5 (do not chain to step-06; the run produced no new artifact).
 
-**Conditional optional field inclusion:**
+**Headless (`{headless_mode}` is true):**
 
-**If `target_version` was set in step 01:**
-Include the `target_version` field in the generated YAML — its value MUST be identical to the `version` field above:
-```yaml
-target_version: "{target_version — same value as version}"
-```
+If the file exists:
 
-**If `source_type: "docs-only"` OR supplemental `doc_urls` were collected:**
-Include the `doc_urls` array (uncommented) in the generated YAML:
-```yaml
-doc_urls:
-  - url: "{documentation URL}"
-    label: "{page label}"
-```
-When `source_type: "docs-only"`: `doc_urls` is required (at least one entry), `source_repo` may be set to the doc site URL for reference or omitted.
+- If `force` was supplied as a headless argument: log `"headless: force-overwriting existing brief at {path}"` and proceed to §3.
+- Otherwise: emit the error envelope per §4b with `halt_reason: "overwrite-cancelled"`, then HALT with exit code 5.
 
-**If `scripts_intent` was collected and is not the default `"detect"`:**
-Include the `scripts_intent` field (uncommented):
-```yaml
-scripts_intent: "{none or description}"
-```
+If the file does not exist, proceed normally.
+
+### 3. Write the Brief
 
-**If `assets_intent` was collected and is not the default `"detect"`:**
-Include the `assets_intent` field (uncommented):
-```yaml
-assets_intent: "{none or description}"
+Assemble the brief context as a **flat** JSON object — every approved value is a top-level key, scope is split across four `scope_*` keys instead of nested, and every optional field is passed as `null` when not set rather than conditionally omitted. This eliminates the "decide what to omit" cognitive load that previously made this the most expensive HALT-typo site in the workflow:
+
+```json
+{
+  "name":             "{approved skill name}",
+  "target_version":   "{target_version from step 01, or null}",
+  "detected_version": "{auto-detected version from step 02, or null}",
+  "source_type":      "{source or docs-only}",
+  "source_repo":      "{approved source repo or doc site URL}",
+  "language":         "{approved language}",
+  "description":      "{approved description}",
+  "forge_tier":       "{Quick|Forge|Forge+|Deep}",
+  "created":          "{current ISO date YYYY-MM-DD}",
+  "created_by":       "{user_name}",
+  "scope_type":       "{approved scope type}",
+  "scope_include":    ["{approved include patterns}"],
+  "scope_exclude":    ["{approved exclude patterns}"],
+  "scope_notes":      "{approved scope notes or empty string}",
+  "doc_urls":         null | [{"url": "...", "label": "..."}],
+  "scripts_intent":   null | "{detect|none|free-text}",
+  "assets_intent":    null | "{detect|none|free-text}",
+  "source_authority": null | "{official|community|internal}"
+}
 ```
 
-**Always include** `source_authority` (default: `"community"`, forced to `"community"` when `source_type: "docs-only"`):
-```yaml
-source_authority: "{official|community|internal}"
+Pipe it into the writer script with the `--from-flat` flag:
+
+```bash
+echo '<context-json>' | uv run {writeSkillBriefScript} write --target {resolved-target-path} --from-flat
 ```
 
-### 4. Write the File
+The script translates flat → nested internally, drops the null optional fields, and runs the same schema validation and atomic write as before — pass every key always, the writer decides what reaches the YAML.
 
-Write the generated YAML to `{forge_data_folder}/{skill-name}/skill-brief.yaml`.
+The script:
+- Validates the context against `src/shared/scripts/schemas/skill-brief.v1.json`
+- Applies the version-precedence rule from `{versionResolutionFile}`
+- Enforces the `target_version == version` invariant (refuses to write a brief that violates it)
+- Renders YAML in canonical key order (byte-stable across runs)
+- Atomically writes the file via temp + fsync + rename (no half-written file ever visible)
+- Emits a JSON success envelope on stdout: `{"status":"ok","brief_path":"…","version":"…","bytes":…,"warnings":[…]}`
 
-If write fails: **HALT** — "**Error:** Failed to write skill-brief.yaml. Please check that the directory is writable and try again."
+**On script failure (non-zero exit):**
+- Exit 1 (validation/invariant): The error JSON on stderr names the offending field. This indicates a context-assembly bug, not a user error — surface the message to the user, log it, then HALT.
+  - Interactive: **HALT** — display the error JSON's `message` field.
+  - Headless: emit the error envelope per §4b with `halt_reason: "input-invalid"`, then `exit 2`.
+- Exit 2 (I/O failure): The atomic write failed (target unwritable, disk full, etc.).
+  - Interactive: **HALT** — "**Error:** Failed to write skill-brief.yaml. Check that the directory is writable and try again."
+  - Headless: emit the error envelope per §4b with `halt_reason: "write-failed"`, then `exit 4`.
 
-### 5. QMD Collection Registration (Deep Tier Only)
+**On success:** capture `brief_path` and `version` from the response envelope — both are needed for §4b and §6.
 
-**IF forge tier is Deep AND QMD tool is available:**
+**Draft cleanup.** After a successful write, remove `{forge_data_folder}/{skill-name}/.brief-draft.json` if it exists (`rm -f` — silent on absent). The draft was a step-01 §7 checkpoint covering the in-flight workflow window; once the brief is written it is no longer meaningful. In headless mode this rm is a no-op (drafts are only written interactively).
 
-Index the skill brief into a QMD collection so that portfolio-level searches can find existing briefs and avoid duplicate skill creation across large monorepos.
+### 4b. Headless Result Envelope (Canonical)
 
-**Collection creation:**
+This section is the canonical envelope-emission reference for the workflow. Every headless emission — the success terminal here and every HARD HALT in step-01/02/05 — uses this contract. Remote sites point here instead of restating it.
+
+**Success (this call site only — emitted from §3 directly):**
 
-Create a QMD collection targeting only the brief file:
 ```bash
-qmd collection add {forge_data_folder}/{skill-name} --name {skill-name}-brief --mask "skill-brief.yaml"
-qmd embed
+echo '{"status":"success","brief_path":"<from §3 response>","skill_name":"<name>","version":"<from §3 response>","language":"<language>","scope_type":"<scope.type>","halt_reason":null}' | \
+  uv run {emitBriefEnvelopeScript} emit
 ```
 
-If collection already exists (re-briefing): remove and recreate for atomic replace:
+**Error (used by every HARD HALT site):**
+
 ```bash
-qmd collection remove {skill-name}-brief
-qmd collection add {forge_data_folder}/{skill-name} --name {skill-name}-brief --mask "skill-brief.yaml"
-qmd embed
+echo '{"status":"error","skill_name":"<name>","halt_reason":"<reason>"}' | \
+  uv run {emitBriefEnvelopeScript} emit --target stderr
 ```
 
-**Embed verification:**
+When the HALT fires before `skill_name` has been resolved (step-01 §1 pre-flight write probe, step-01 §8 input-missing on a malformed args bundle), pass the partially-gathered value or the literal `"unknown"` — the script accepts any non-empty string at this position.
 
-After `qmd embed` completes, verify the collection was embedded:
-- Run `qmd status` or `qmd collection list` and confirm `{skill-name}-brief` shows document count > 0
-- If verification succeeds: proceed to registry update normally
-- If verification fails: log warning "QMD embed verification failed for {skill-name}-brief — collection may not be searchable yet", still proceed to registry update but add `status: "pending"` field to the registry entry
+The script derives `exit_code` deterministically from `halt_reason` (null→0, input-missing/input-invalid→2, forge-tier-missing/target-inaccessible/gh-auth-failed→3, write-failed→4, overwrite-cancelled→5, user-cancelled→6 [interactive-only — headless never raises this]), validates against `src/shared/scripts/schemas/skf-brief-result-envelope.v1.json`, and prints the prefixed `SKF_BRIEF_RESULT_JSON: {…}` line.
 
-**Registry update:**
+The script enforces the success/error halt_reason invariant (success requires null halt_reason; error requires non-null). The `user-cancelled` halt_reason is accepted for completeness (interactive `[X]` Cancel sites in step-01/03/04) but never appears on the headless code path.
 
-Read `{sidecar_path}/forge-tier.yaml` and update the `qmd_collections` array.
+Invocation sites (each pointed at this block, not duplicated): step-01 §1 (write-failed pre-resolution), step-01 §8 (input-missing/input-invalid GATE), step-05 §2b (overwrite-cancelled), step-05 §3 (input-invalid/write-failed from script). Step-01 §1 forge-tier-missing and step-02 §1 (target-inaccessible/gh-auth-failed) currently HALT without emitting an envelope — pre-existing gaps tracked separately, not addressed by this canonicalization.
 
-If an entry with `name: "{skill-name}-brief"` already exists, replace it. Otherwise, append:
+When `{headless_mode}` is false, skip this section silently — no envelope is emitted.
 
-```yaml
-  - name: "{skill-name}-brief"
-    type: "brief"
-    source_workflow: "brief-skill"
-    skill_name: "{skill-name}"
-    created_at: "{current ISO date}"
-    # status: "pending"    # Added only when embed verification fails
-```
-
-Write the updated forge-tier.yaml.
+### 5. QMD Collection Registration (Deep Tier Only)
 
-**Error handling:**
-- If QMD collection creation fails: log the error. Do NOT fail the workflow — the brief file was already written successfully.
-- If forge-tier.yaml update fails: log the error, continue.
+**IF forge tier is Deep AND QMD tool is available:** load `{qmdRegistrationFile}` and follow the procedure there to index the brief into a QMD collection and update the forge-tier registry.
 
-**IF forge tier is NOT Deep:** Skip this section silently. No messaging.
+**IF forge tier is NOT Deep OR QMD is not available:** skip this section silently — do not load `{qmdRegistrationFile}`. No messaging.
 
 ### 6. Display Success Summary
 
@@ -161,7 +158,7 @@ Write the updated forge-tier.yaml.
 
 ---
 
-**File:** `{forge_data_folder}/{skill-name}/skill-brief.yaml`
+**File:** `{brief_path from §3 response}`
 **Skill:** {name}
 **Language:** {language}
 **Scope:** {scope type}
@@ -190,4 +187,3 @@ ONLY WHEN the brief file has been written and the success summary displayed will
 ## CRITICAL STEP COMPLETION NOTE
 
 This step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md`. After the health check completes, the brief-skill workflow is fully done.
-

package/src/skf-brief-skill/steps-c/step-06-health-check.md

@@ -1,7 +1,7 @@
 ---
 # `shared/health-check.md` resolves relative to the SKF module root
-# (`_bmad/skf/` when installed, `src/` during development), NOT relative
-# to this step file.
+# (`{project-root}/_bmad/skf/` when installed, `{project-root}/src/`
+# during development), NOT relative to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 
@@ -16,7 +16,16 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 - No user-facing reports, file writes, or result contracts in this step — those belong in step-05
 - Delegate directly to `{nextStepFile}` with no additional commentary
 - Do not attempt any other action between loading this step and executing `{nextStepFile}`
+- All user-facing output in `{communication_language}`
 
 ## MANDATORY SEQUENCE
 
 Load `{nextStepFile}`, read it fully, then execute it.
+
+## Completion criteria
+
+This is the terminal step of brief-skill. The workflow is complete when `{nextStepFile}` returns control — do not transition to any further step.
+
+## CRITICAL STEP COMPLETION NOTE
+
+Step 06 is the terminal stage of brief-skill. After `{nextStepFile}` returns control, the brief-skill workflow is fully complete — do not re-enter step-05 or step-06, do not load any further step file, and do not loop back into the workflow.