bmad-module-skill-forge 2.1.0 → 3.0.0

package/src/skf-brief-skill/references/draft-checkpoint.md

@@ -1,26 +1,40 @@
+---
+# Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
+# (installed SKF module path first, src/ dev-checkout fallback); first
+# existing path wins. With neither, Half 2 writes no checkpoint.
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+---
+
 # Draft Checkpoint Lifecycle
 
-The `.brief-draft.json` file at `{forge_data_folder}/{skill-name}/.brief-draft.json` is a step 1 in-flight-state checkpoint. It exists only while the workflow has progressed past §7 but not yet completed step 5 — once the final brief writes successfully, step 5 §4 removes it.
+The `.brief-draft.json` file at `{forge_data_folder}/{skill-name}/.brief-draft.json` is the in-flight checkpoint of an interactive run. Half 2 writes it twice: when step 1 §8 continues to step 2, with the gathered intent and the accepted description, and again after step 3's scope decisions (scope-definition.md §5c), so it then holds the scope too. Once the final brief writes successfully, step 5 §3 removes it.
 
 **Headless mode skips this entire lifecycle** — the run completes in a single invocation, so no resume is meaningful and no checkpoint is written.
 
-The two halves of the lifecycle (resume after the target is confirmed in §3, write on §7 confirmation) form a pair. This file documents both so a single load covers them.
+The two halves of the lifecycle (resume after the target is confirmed in §3, write at §8 and after step 3) form a pair. This file documents both so a single load covers them.
 
-## Half 1 — Resume Check (loaded from §3 after the target is confirmed)
+## Half 1: Resume Check (loaded from §3 after the target is confirmed)
 
-Keyed on the confirmed **target**, not the derived skill name, so the offer can fire right after §3 — before the returning user re-answers version (§3b), intent (§4), or scope (§5), which is exactly the state a draft restores. The caller (gather-intent §3) has already globbed `{forge_data_folder}/*/.brief-draft.json`, kept only drafts whose `target_repo` equals the confirmed target (or whose `doc_urls` contain it, for docs-only) with no `skill-brief.yaml` beside them, and selected the most-recently-modified survivor. Its directory basename is the candidate skill `name`. Present the resume prompt for that draft.
+Keyed on the confirmed **target**, not the derived skill name, so the offer can fire right after §3, before the returning user re-answers version (§3b), intent (§4), or scope (§5), which is exactly the state a draft restores. The caller (gather-intent §3) has selected the candidate draft; its directory basename is the candidate skill `name`. Present the resume prompt for that draft.
 
 When a live draft is found, present:
 
 ```
 **An in-progress draft for `{name}` was found** (last updated: {mtime}).
-  [Y] Resume from the saved draft (jump to §8 with prior answers restored)
+  [Y] Resume from the saved draft (prior answers restored)
   [N] Start fresh (ignore this draft and keep gathering)
 ```
 
 ### `[Y]` — Resume
 
-Restore the candidate `name` (the matched draft's directory basename), then load the JSON and restore the captured fields: `target_repo`, `source_type`, `source_authority`, `target_version`, `doc_urls`, `intent`, `scope_hint`, `description`, `forge_tier`, `tier_source`. Then jump directly to §8 — **skip §3b, §4, §5, §6, §7, and §7b** — so the version, intent, scope, and description the draft already holds are never re-gathered.
+Restore the candidate `name` (the matched draft's directory basename), then load the JSON and restore the step 1 fields it holds: `target_repo`, `source_type`, `source_authority`, `target_version`, `target_ref`, `doc_urls`, `intent`, `scope_hint`, `description`, `forge_tier`, `tier_source`.
+
+- **A draft written after step 3** (it holds `scope`): restore its step 3 fields too, `language`, `detected_version`, `analysis_ref` and `monorepo_workspace`, `scripts_intent` and `assets_intent`, and `scope.type` / `scope.include` / `scope.exclude` / `scope.tier_a_include` / `scope.notes` / `scope.rationale` / `scope.registry_path` / `scope.ui_variants` / `scope.demo_patterns` ← `draft.scope.*`, each kept verbatim as a ratified brief's are (`references/gather-intent-ratify.md`). Then load, read entire file, and execute `references/confirm-brief.md` (step 4): steps 2 and 3 already ran in the session that wrote the draft. A `[R] Revise Scope` there re-runs step 2 first, because this session has no staged analysis (scope-definition.md Rules).
+- **A draft written by step 1** (no `scope`): jump directly to §8, which shows the §7 summary with the restored description before its menu.
+
+Either way **§3b, §4, §5, §6, §7, and §7b are skipped**, so the version, intent, scope, and description the draft already holds are never re-gathered.
 
 The skip rule for §7b is load-bearing: re-running §7b would overwrite the user's previously accepted `description` with a fresh candidate synthesized from the seed material. The restored `description` is authoritative. §6 is skipped too, so the restored `name` is used as-is — it already cleared the collision and portfolio-similarity checks in the session that wrote the draft.
 
@@ -28,19 +42,24 @@ The user can still revise any field at step 4 §3 if a refinement is needed afte
 
 ### `[N]` — Start fresh
 
-Leave the draft in place and continue forward to §3b — the normal gather flow (§3b version, §4 intent, §5 scope, §6 name) resumes, and the §6 collision / portfolio-similarity checks run in their usual place. Do not delete the draft here: the skill name has not been chosen yet, so there is nothing to key a deletion on. If the user lands on the same name, step 5's atomic write overwrites the stale draft; otherwise it stays a harmless orphan that the resume check offers again on a future run targeting the same repo.
+Leave the draft in place and continue forward to §3b: the normal gather flow (§3b version, §4 intent, §5 scope, §6 name) resumes, and the §6 collision / portfolio-similarity checks run in their usual place. Do not delete the draft here: the skill name has not been chosen yet, so there is nothing to key a deletion on. If the user lands on the same name, the next checkpoint write replaces the stale draft; otherwise it stays a harmless orphan that the resume check offers again on a future run targeting the same repo.
 
-## Half 2 — Checkpoint Write (loaded from §7 after summary confirmation)
+## Half 2: Checkpoint Write (loaded from step 1 §8, and from step 3 §5c)
 
-After the user confirms the §7 summary, persist the captured state atomically. Write a single JSON object with all of:
+Write one JSON object with every field the run holds so far:
 
-- `target_repo`, `source_type`, `source_authority`
-- `target_version` (if set)
-- `doc_urls` (if collected)
-- `intent`, `scope_hint`
-- `description` (the §7b accepted text)
-- `forge_tier`, `tier_source` (for diagnostics)
+- From step 1 (§8): `target_repo`, `source_type`, `source_authority`, `target_version` (if set), `target_ref` (if set), `doc_urls` (if collected), `intent`, `scope_hint`, `description` (the accepted text), and `forge_tier`, `tier_source` (for diagnostics).
+- After step 3 (§5c), the same fields plus the scope: `language`, `detected_version` (step 2's, or null), `analysis_ref`, `monorepo_workspace` (if set), `scripts_intent`, `assets_intent`, and `scope` with `type`, `include`, `exclude`, `notes` and, when set, `tier_a_include`, `rationale`, `registry_path`, `ui_variants` and `demo_patterns`.
+
+Stage the object in the run folder, then write it with `{atomicWriteHelper}` (resolved from `{atomicWriteProbeOrder}`), which creates the skill's folder when it does not exist yet and renames a complete file into place, so a partial write never becomes visible as `.brief-draft.json`:
+
+```bash
+cat > "{run_dir}/draft.json" <<'SKF_JSON'
+<the draft, as one JSON object>
+SKF_JSON
+uv run {atomicWriteHelper} write --target "{forge_data_folder}/{skill-name}/.brief-draft.json" < "{run_dir}/draft.json"
+```
 
-Atomic-write protocol: write to `.brief-draft.json.tmp` first, then `mv .brief-draft.json.tmp .brief-draft.json`. The rename is atomic on a single filesystem; a partial write never becomes visible as `.brief-draft.json`.
+The checkpoint is a convenience: when the helper has no path or the write fails, log `warn: draft checkpoint not written ({reason})` and continue.
 
-The file is removed by step 5 §4 after the final brief writes successfully.
+The file is removed by step 5 §3 after the final brief writes successfully.

package/src/skf-brief-skill/references/gather-intent-ratify.md

@@ -0,0 +1,68 @@
+---
+ratifyTargetFile: 'confirm-brief.md'
+validateBriefSchemaProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-brief-schema.py'
+  - '{project-root}/src/shared/scripts/skf-validate-brief-schema.py'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 1: Ratify an Existing Brief
+
+A pre-authored `skill-brief.yaml` (typically from `skf-analyze-source`) is reviewed and written to `{forge_data_folder}/{brief.name}/skill-brief.yaml` (in place when it already lives there) instead of derived again. Step 1 loads this file with the brief's path in two ways: interactively, when the §3.1 target is a brief or a folder holding one (§3.1a), and headlessly, when the input gate in `references/headless-args.md` finds a `from_brief` argument. Steps 2 and 3 do not run: they would derive again what the brief already holds. The run goes on at step 4, which reviews the brief, and step 5 writes it there. `references/invocation-contract.md` states the ratify contract.
+
+## 1. Validate the Brief
+
+The brief path is the given path when it ends in `skill-brief.yaml`, else `<path>/skill-brief.yaml`. Resolve `{validateBriefSchemaHelper}` from `{validateBriefSchemaProbeOrder}` (first existing path wins; HALT if no candidate exists), then run:
+
+```bash
+uv run {validateBriefSchemaHelper} <resolved-brief-path>
+```
+
+It returns `{valid, errors[], warnings[], halt_reason, brief}`:
+
+- **`valid: false`**, interactive: display "**Brief at `{path}` is invalid:** {first error message}. Pick a different brief, or supply a repo / docs URL instead." and re-display the step 1 §3.1 prompt: the user may have pointed at the wrong file.
+- **`valid: false`**, headless, with the script's `halt_reason` `brief-missing` (the path is absent or unreadable): emit the halt envelope first, `uv run {emitBriefEnvelopeHelper} emit --target stderr` with `halt_reason: "input-missing"` (SKILL.md Halt Contract), surface `errors[]` to the operator log, then HALT (exit code 2).
+- **`valid: false`**, headless, with any other `halt_reason` (`brief-malformed` or `brief-invalid`): emit the halt envelope first, `uv run {emitBriefEnvelopeHelper} emit --target stderr` with `halt_reason: "input-invalid"` (SKILL.md Halt Contract), surface `errors[]` to the operator log, then HALT (exit code 2).
+- **`valid: true`**: log any non-empty `warnings[]`, add each to `workflow_warnings[]` as `<field>: <message>`, and continue with the parsed `brief`.
+
+## 2. Ratify Menu
+
+**GATE [default: R]**: a headless run takes `[R]` without showing the menu: its `from_brief` argument already chose to ratify.
+
+```
+**Existing brief detected at `{path}`.**
+
+- **Name:** {brief.name}
+- **Target:** {brief.source_repo}
+- **Description:** "{brief.description}"
+- **Created:** {brief.created} by {brief.created_by}
+- **Scope:** {brief.scope.type}
+
+Pick one:
+  [R] Ratify: review in step 4 and write it to {forge_data_folder}/{brief.name}/skill-brief.yaml once approved
+  [F] Start fresh: discard this brief and re-prompt for a target
+  [X] Cancel and exit
+```
+
+Wait for the user's response:
+
+- **[R]**: continue at §3.
+- **[F]**: discard the brief and re-display the step 1 §3.1 prompt.
+- **[X]**: remove the run folder (`case "{run_dir}" in "{project-root}/_bmad-output/.skf-run/skf-brief-skill-"*) rm -rf "{run_dir}" ;; esac`), display `"Cancelled: no brief was written."` and HALT (exit code 6, `halt_reason: "user-cancelled"`). The brief at `{path}` is left as it is.
+- **Any other input**: treat it as a new step 1 §3.1 response and route it there (a GitHub URL typed here means the user wants that repository briefed instead).
+
+## 3. Hydrate and Route
+
+Store `ratify_mode: true` and `ratify_source_path: <resolved-brief-path>` in workflow context, then hydrate the brief context variables from the parsed `brief`, so step 4 has the field set steps 1 to 3 would derive. The hydrated values feed steps 3 and 4 and the patch step 5 lays over this brief, not the write itself: step 5 writes from the brief file. This is the one mapping list every route uses:
+
+- `name` ← `brief.name`; `version` ← `brief.version`; `target_version` ← `brief.target_version`
+- `target_ref` ← `brief.target_ref`; `source_ref` ← `brief.source_ref` (optional git refs; preserve when present)
+- `source_repo` ← `brief.source_repo`; `source_type` ← `brief.source_type` (`source` when absent, the schema default); `source_authority` ← `brief.source_authority`; `doc_urls` ← `brief.doc_urls`
+- `language` ← `brief.language`; `description` ← `brief.description`; `forge_tier` ← `brief.forge_tier`
+- `created` ← `brief.created`; `created_by` ← `brief.created_by`
+- `scope.type` / `scope.include` / `scope.exclude` / `scope.tier_a_include` / `scope.notes` / `scope.rationale` / `scope.amendments` ← `brief.scope.*` (preserve `tier_a_include` and the `amendments` log verbatim: do not re-derive or drop them)
+- `scope.registry_path` / `scope.ui_variants` / `scope.demo_patterns` ← `brief.scope.*` (a component library's registry file, design system variants and demo globs; skf-create-skill writes the registry file and the demo globs back once the user confirms them: preserve all three verbatim)
+- `scripts_intent` ← `brief.scripts_intent`; `assets_intent` ← `brief.assets_intent`
+
+Then load, read entirely, and execute `{ratifyTargetFile}` (step 4). Under headless it confirms with `[C]`, and step 5 writes the brief: no `force` needed when it already lives at that path; otherwise `force` applies as on the derive route (step 5 §2b).