bmad-module-skill-forge 1.5.1 → 1.6.0

package/.claude-plugin/marketplace.json

@@ -30,7 +30,7 @@
       "name": "skill-forge",
       "source": "./",
       "description": "Evidence-based agent skills compiler with progressive capability tiers (Quick/Forge/Forge+/Deep).",
-      "version": "1.5.1",
+      "version": "1.6.0",
       "author": {
         "name": "Armel"
       },

package/docs/_data/pinned.yaml

@@ -26,7 +26,7 @@
 # Enforced two ways: (1) release.yaml bumps this line in the same commit
 # as package.json + marketplace.json on every release; (2) validate-docs-drift.js
 # cross-checks this value against package.json.version and fails on mismatch.
-skf_version: "1.5.1"
+skf_version: "1.6.0"
 
 # Path to the oh-my-skills repo, resolved relative to this repo's root.
 # Override at runtime with the OMS environment variable if oh-my-skills

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",

package/src/shared/scripts/skf-description-guard.py

@@ -160,17 +160,45 @@ def is_diverged(diff_kind: str) -> bool:
 def restore_description(skill_md: Path, captured: str) -> None:
     """Atomically rewrite SKILL.md so its frontmatter `description` equals captured.
 
-    Preserves frontmatter key order and surrounding whitespace by doing a
-    line-level rewrite of just the `description:` value, not a full YAML
-    re-dump (which would re-order keys, change quoting style, and likely
-    fail roundtrip tests downstream).
+    Parses the entire frontmatter via PyYAML, replaces the top-level
+    `description` value, and re-emits the frontmatter via `yaml.safe_dump`.
+    This guarantees valid YAML output regardless of the source representation
+    (inline, double-quoted, single-quoted, folded `>`, literal `|`), and
+    avoids the line-level pitfalls a previous implementation had with folded
+    block scalars and nested `description:` keys in sibling mappings.
+
+    Key order is preserved (PyYAML's `safe_dump` honours dict insertion order;
+    this module's `requires-python = ">=3.10"` guarantees ordered dicts).
+    Quoting style of *other* fields may change to whatever `safe_dump`
+    chooses for each scalar — downstream readers parse YAML, so any valid
+    YAML emission is acceptable.
     """
     text = skill_md.read_text(encoding="utf-8")
     leading, fm_yaml, body = _split_frontmatter(text)
     if not fm_yaml:
         raise ValueError(f"cannot restore: no frontmatter in {skill_md}")
 
-    new_fm = _rewrite_description_line(fm_yaml, captured)
+    try:
+        fm = yaml.safe_load(fm_yaml)
+    except yaml.YAMLError as exc:
+        raise ValueError(f"frontmatter in {skill_md} is not valid YAML: {exc}") from exc
+    if not isinstance(fm, dict):
+        raise ValueError(f"frontmatter in {skill_md} is not a mapping")
+    if "description" not in fm:
+        raise ValueError(f"frontmatter in {skill_md} has no `description` field")
+
+    fm["description"] = captured
+
+    # `width=10**9` keeps the description on one line regardless of length;
+    # PyYAML otherwise inserts line breaks at ~80 chars which would re-introduce
+    # folded-scalar continuation lines — the exact failure mode this rewrite fixes.
+    new_fm = yaml.safe_dump(
+        fm,
+        sort_keys=False,
+        default_flow_style=False,
+        allow_unicode=True,
+        width=10**9,
+    ).rstrip("\n")
     new_text = f"{leading}{new_fm}\n---\n{body}"
 
     # atomic: write to a sibling temp file, fsync, rename
@@ -191,81 +219,6 @@ def restore_description(skill_md: Path, captured: str) -> None:
         raise
 
 
-def _rewrite_description_line(fm_yaml: str, new_description: str) -> str:
-    """Replace the `description:` value in a YAML frontmatter block.
-
-    Preserves other keys verbatim. Handles three common shapes:
-      description: single-line value
-      description: "double-quoted value"
-      description: |     # block scalar (folded variant: >)
-        multi-line
-        value here
-    """
-    lines = fm_yaml.split("\n")
-    out: list[str] = []
-    i = 0
-    quoted = _yaml_quote_inline(new_description)
-    replaced = False
-    while i < len(lines):
-        line = lines[i]
-        if not replaced and _is_description_key_line(line):
-            stripped = line.lstrip()
-            indent = line[: len(line) - len(stripped)]
-            # detect block-scalar indicator (| or >)
-            after_key = stripped[len("description:") :].lstrip()
-            if after_key.startswith("|") or after_key.startswith(">"):
-                # skip block-scalar continuation lines (deeper indent than the key line)
-                key_indent = len(indent)
-                i += 1
-                while i < len(lines):
-                    nxt = lines[i]
-                    if nxt.strip() == "":
-                        # blank lines belong to the block scalar
-                        i += 1
-                        continue
-                    nxt_indent = len(nxt) - len(nxt.lstrip())
-                    if nxt_indent <= key_indent:
-                        break
-                    i += 1
-                out.append(f"{indent}description: {quoted}")
-                replaced = True
-                continue
-            out.append(f"{indent}description: {quoted}")
-            replaced = True
-            i += 1
-            continue
-        out.append(line)
-        i += 1
-    if not replaced:
-        raise ValueError("description key not found while rewriting frontmatter")
-    return "\n".join(out)
-
-
-def _is_description_key_line(line: str) -> bool:
-    stripped = line.lstrip()
-    return stripped.startswith("description:") and (
-        len(stripped) == len("description:") or stripped[len("description:")] in (" ", "\t", "")
-    )
-
-
-def _yaml_quote_inline(value: str) -> str:
-    """Emit a YAML scalar suitable as the inline value of `description: `.
-
-    Uses double-quoted form so control characters and embedded quotes are
-    safe. Block scalars (| / >) are not used — the description field is a
-    single semantic string and downstream readers (skill-check, agentskills)
-    expect inline form.
-    """
-    escaped = (
-        value.replace("\\", "\\\\")
-        .replace("\"", "\\\"")
-        .replace("\n", "\\n")
-        .replace("\r", "\\r")
-        .replace("\t", "\\t")
-    )
-    return f'"{escaped}"'
-
-
 # --------------------------------------------------------------------------
 # CLI
 # --------------------------------------------------------------------------

package/src/skf-analyze-source/references/continue.md

@@ -6,6 +6,7 @@ nextStepOptions:
   step 4: 'map-and-detect.md'
   step 5: 'recommend.md'
   step 6: 'generate-briefs.md'
+  step 7: 'health-check.md'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -61,8 +62,9 @@ Map the last completed step to the next step file:
 | identify-units | map-and-detect |
 | map-and-detect | recommend |
 | recommend | generate-briefs |
+| generate-briefs | health-check |
 
-**IF all steps completed:**
+**IF `health-check` is in `stepsCompleted`:**
 "**This analysis appears to be complete.** All steps have been finished. Would you like to start a new analysis?"
 
 ### 5. Update and Route

package/src/skf-brief-skill/SKILL.md

@@ -13,6 +13,8 @@ A good skill brief sets a tight, cohesive boundary: one capability with 3-8 prim
 
 Brief-skill is split from create-skill so the scoping conversation runs *once*, on cheap signals (manifests, top-level exports, intent), without paying for AST extraction. Compilation is expensive; scoping decisions are cheap to revise. Keeping them in separate workflows lets a user iterate on the brief, share it for review, and re-run create-skill against the same brief whenever the upstream version moves.
 
+**Ratify path (interactive only).** When the user already has a `skill-brief.yaml` produced by another workflow — typically `skf-analyze-source`'s `generate-briefs` step, where one analyze pass emits several recommended briefs — invoking `/skf-brief-skill` with a path to that brief at the first prompt routes to a fast-path review: gather-intent §3.1a loads the YAML, hydrates the brief context, and jumps straight to step 4 (confirm-brief) where the standard review/edit cycle still applies before step 5 writes. This skips re-deriving fields the upstream draft already supplies and saves the 5-10 minutes a full re-run of intent + analyze + scope would cost.
+
 ## Conventions
 
 - Bare paths (e.g. `references/<name>.md`) resolve from the skill root.

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

@@ -1,5 +1,6 @@
 ---
 nextStepFile: 'analyze-target.md'
+ratifyTargetFile: 'confirm-brief.md'
 forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 descriptionVoiceExamplesFile: 'assets/description-voice-examples.md'
 headlessArgsFile: 'references/headless-args.md'
@@ -9,6 +10,9 @@ draftCheckpointFile: 'references/draft-checkpoint.md'
 validateBriefInputsProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-validate-brief-inputs.py'
   - '{project-root}/src/shared/scripts/skf-validate-brief-inputs.py'
+validateBriefSchemaProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-brief-schema.py'
+  - '{project-root}/src/shared/scripts/skf-validate-brief-schema.py'
 emitBriefEnvelopeProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-emit-brief-result-envelope.py'
   - '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
@@ -84,7 +88,7 @@ Let's get started."
 
 ### 3. Gather Target Repository
 
-This section has three sub-flows. Execute exactly one branch — 3.2 *or* 3.3 — based on the user's response in 3.1, then end with the shared confirmation. Do not mix branches.
+This section has four sub-flows. Execute exactly one branch — 3.1a *or* 3.2 *or* 3.3 — based on the user's response in 3.1, then end with the shared confirmation (3.1a is terminal for §3 and jumps directly to confirm-brief.md). Do not mix branches.
 
 #### 3.1 Collect target
 
@@ -94,6 +98,7 @@ Provide one of:
 - A **GitHub URL** (e.g., `https://github.com/org/repo`)
 - A **local path** (e.g., `/path/to/project`)
 - **Documentation URLs** for a docs-only skill (e.g., `https://docs.stripe.com/api`) — use this when no source code is available (SaaS, closed-source)
+- A **path to an existing `skill-brief.yaml`** (file path or a directory containing one) — use this to ratify a brief produced by another workflow (e.g. `skf-analyze-source`) without re-deriving fields
 
 Or type `cancel` / `exit` / `[X]` to leave without writing anything.
 
@@ -102,10 +107,64 @@ Or type `cancel` / `exit` / `[X]` to leave without writing anything.
 Wait for user response. Branch on the response:
 
 - Empty input, `cancel`, `exit`, `[X]`, `q`, or `:q` → Display `"Cancelled — no brief was written."` and HALT (exit code 6, `halt_reason: "user-cancelled"`). Cancellation here is non-destructive — no files have been written yet by step 1. Headless mode never reaches this branch (the GATE in §8 short-circuits the interactive sub-flows).
+- Path that resolves to an existing `skill-brief.yaml` (file path ending in `skill-brief.yaml` that exists, OR a directory containing a `skill-brief.yaml`) → §3.1a
 - Documentation URLs only (no source location) → §3.2
 - GitHub URL or local filesystem path → §3.3
 - Any other free-form question (e.g. "what is this?", "show me an example", "how does SKF work?") → answer briefly, re-display the prompt
 
+#### 3.1a Branch — Ratify existing brief
+
+This branch handles the AN→BS handoff: another workflow (typically `skf-analyze-source`) has already produced a `skill-brief.yaml`, and the user wants to review and confirm it without re-running gather-intent / analyze-target / scope-definition. **This branch is interactive-only** — headless mode reaches step 1 via §8's GATE with `target_repo`/`skill_name` args, not via this §3.1a path. (A headless ratify equivalent could be added later via a `from_brief` argument; out of scope here.)
+
+Resolve the path:
+
+- If the user's input ends in `skill-brief.yaml` and points at an existing file → that is the brief path.
+- Otherwise (input was a directory) → the brief path is `<input>/skill-brief.yaml`.
+
+**Validate the brief against the schema** before presenting it. Resolve `{validateBriefSchemaHelper}` from `{validateBriefSchemaProbeOrder}` (first existing path wins; HALT if no candidate exists), then:
+
+```bash
+uv run {validateBriefSchemaHelper} <resolved-brief-path>
+```
+
+The script returns JSON `{valid, errors[], warnings[], halt_reason, brief}`. Apply the result:
+
+- **`valid: false`** — surface the `errors[]` messages and the `halt_reason` to the user, then re-display the §3.1 prompt for a corrected path (or another target altogether). Do not HALT — the user may simply have pointed at the wrong file. Example: `"**Brief at `{path}` is invalid:** {first error message}. Pick a different brief, or supply a repo / docs URL instead."`
+- **`valid: true`** — proceed with the parsed `brief` payload.
+
+Surface any non-empty `warnings[]` as a single grouped line (`"**Brief validation warnings:** {joined warnings}"`), then present the ratify menu:
+
+```
+**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 (overwriting this file once approved)
+  [F] Start fresh — discard this brief and re-prompt for a target
+  [X] Cancel and exit
+```
+
+Wait for user response. Branch:
+
+- **[R] Ratify** — Confirm overwrite up front: store `ratify_mode: true` and `ratify_source_path: <resolved-brief-path>` in workflow context. Hydrate the brief context variables from the parsed `brief` payload so step 4 has the same field set it normally derives from steps 1-3:
+  - `name` ← `brief.name`; `version` ← `brief.version`; `target_version` ← `brief.target_version`
+  - `source_repo` ← `brief.source_repo`; `source_type` ← `brief.source_type`; `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.notes` / `scope.rationale` ← `brief.scope.*`
+  - `scripts_intent` ← `brief.scripts_intent`; `assets_intent` ← `brief.assets_intent`
+
+  Then load, read entirely, and execute `{ratifyTargetFile}` — bypassing §3.1b/§3.2/§3.3, §3b, §4, §5, §6, §7, §7b, and §8 entirely. Skip step 2 (analyze-target) and step 3 (scope-definition) — both would re-derive fields already on disk. The forward chain resumes at step 4 (confirm-brief) where the user gets the standard review pass and can still adjust fields inline via §4.
+
+- **[F] Start fresh** — discard the loaded brief and re-display §3.1 above (the user is now at the same point as if they had typed nothing).
+- **[X] Cancel** — Display `"Cancelled — no brief was written."` and HALT (exit code 6, `halt_reason: "user-cancelled"`). Non-destructive.
+- **Any other input** — treat as a fresh §3.1 response and re-evaluate the routing branches above (a typed GitHub URL after seeing the menu means "I changed my mind, brief this repo instead").
+
 #### 3.2 Branch — Documentation URLs (docs-only)
 
 - Set `source_type: "docs-only"` in the brief data

package/src/skf-brief-skill/references/write-brief.md

@@ -52,7 +52,11 @@ The script's atomic-write helper creates parent directories as needed (`mkdir -p
 
 Before writing, check whether the resolved target path already exists.
 
-**Interactive (`{headless_mode}` is false):**
+**Ratify path (`ratify_mode: true` in workflow context):**
+
+The user already confirmed overwrite up-front at step 1 §3.1a when they chose `[R] Ratify` against the same file. Skip the interactive prompt below; log a single-line `brief-skill: ratify-mode auto-overwriting existing brief at {path}` and proceed to §3. Resuming the prompt would be friction — the user has by now also reviewed and approved the brief at step 4. This auto-accept does not apply to headless mode (handled below) nor to the standard interactive path (also below).
+
+**Interactive (`{headless_mode}` is false, `ratify_mode` not set):**
 
 If the file exists, present:
 

package/src/skf-create-skill/assets/compile-assembly-rules.md

@@ -15,7 +15,7 @@ description: >
 **Frontmatter rules:**
 
 - `name`: lowercase alphanumeric + hyphens only, must match the skill output directory name. Prefer gerund form (`processing-pdfs`, `analyzing-spreadsheets`) for clarity.
-- `description`: non-empty, max 1024 chars, optimized for agent discovery. **MUST use third-person voice** ("Processes Excel files..." not "I can help you..." or "You can use this to..."). Inconsistent point-of-view causes discovery problems since the description is injected into the system prompt.
+- `description`: non-empty, max 1024 chars, optimized for agent discovery. **MUST use third-person voice** ("Processes Excel files..." not "I can help you..." or "You can use this to...") AND **MUST include a trigger phrase** so agents know when to match — one of `Use when …`, `Triggers on …`, or `Reach for this when …`. When using `Use when `, follow with a **gerund** (`Use when building/processing/analyzing X…`) or a noun-phrase clause (`Use when the user requests to "X"`); never a bare indicative verb like `builds`/`processes`, because `skill-check --fix` will prepend a literal `Use when ` to a description missing the trigger phrase, producing ungrammatical output (`Use when builds X…`). Inconsistent point-of-view or a missing trigger phrase causes discovery problems since the description is injected into the system prompt. See `skf-brief-skill/assets/description-voice-examples.md` for the canonical voice palette.
 - **`description` must NOT contain angle brackets** — neither standalone placeholders like `<name>`, `<component>`, `<path>`, nor inline generics like `` `Array<T>` `` or `` `Meta<typeof X>` ``. Both `skill-check`'s `description_field` validator and `tessl`'s deterministic description check parse the frontmatter description as a raw string and reject any `<` or `>`, regardless of markdown context (backticks do NOT protect content here). A rejected description fails the review with 0% score. When the natural phrasing would use angle brackets:
   - Prefer the curly-brace form in prose: `{name}`, `{component-id}`, `{path}` — readable and tessl-safe.
   - Uppercase placeholders are also acceptable: `NAME`, `COMPONENT_ID`.

package/src/skf-create-skill/assets/skill-sections.md

@@ -18,7 +18,7 @@ description: >
 **Frontmatter rules (agentskills.io specification):**
 
 - `name`: 1-64 characters, lowercase alphanumeric + hyphens only, must match parent directory name. Prefer gerund form (`processing-pdfs`, `analyzing-spreadsheets`) for clarity; noun phrases and action-oriented forms are acceptable alternatives.
-- `description`: 1-1024 characters, trigger-optimized for agent matching. MUST use third-person voice ("Processes..." not "I can..." or "You can...").
+- `description`: 1-1024 characters, trigger-optimized for agent matching. MUST use third-person voice ("Processes..." not "I can..." or "You can...") AND include a trigger phrase ("Use when ...", "Triggers on ...", "Reach for this when ..."). When using "Use when ", follow with a gerund (`Use when building/processing/analyzing X…`) or noun-phrase clause — never a bare indicative verb, since `skill-check --fix` will prepend a literal "Use when " to descriptions missing the phrase. See `skf-brief-skill/assets/description-voice-examples.md`.
 - Only 6 fields permitted: `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools`
 - `version` and `author` belong in metadata.json, NOT in frontmatter
 

package/src/skf-test-skill/SKILL.md

@@ -51,7 +51,7 @@ These rules apply to every step in this workflow:
 |--------|--------|
 | **Inputs** | skill_name [required]; optional flags: `--allow-workspace-drift`, `--no-discovery` (skip §4b Discovery Testing), `--no-health-check` (skip §7 health-check dispatch), `--tier=<Quick\|Forge\|Forge+\|Deep>` (bypass forge-tier.yaml sidecar requirement), `--threshold=<N>` (override pass threshold; CLI wins over `workflow.default_threshold` scalar) |
 | **Gates** | step 6: Confirm Gate [C] |
-| **Outputs** | test-report-{skill_name}.md with completeness score and result (PASS/FAIL); per-run `skf-test-skill-result-{run_id}.json` and `skf-test-skill-result-latest.json` written atomically under `{forge_version}/` |
+| **Outputs** | per-run `test-report-{skill_name}-{run_id}.md` with completeness score and result (PASS/FAIL); per-run `skf-test-skill-result-{run_id}.json` and `skf-test-skill-result-latest.json` written atomically under `{forge_version}/` — downstream consumers (export-skill, update-skill `--from-test-report`) glob `test-report-{skill_name}-*.md` and pick newest by parsed ISO timestamp |
 | **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
 | **Exit codes** | See "Exit Codes" below |
 

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

@@ -42,7 +42,14 @@ Provide either:
 Resolve the path to an absolute skill folder location.
 
 **If `--from-test-report` was provided (or user references a test report):**
-Search for the test report at `{forge_data_folder}/{skill_name}/{active_version}/test-report-{skill_name}.md` (i.e., `{forge_version}/test-report-{skill_name}.md`). If not found at the versioned path, fall back to `{forge_data_folder}/{skill_name}/test-report-{skill_name}.md`. If found, set `test_report_path` in context and `update_mode: gap-driven`. If not found at either path, warn and continue with normal source drift mode.
+
+`skf-test-skill` writes timestamped test-report filenames (`test-report-{skill_name}-{ISO-TIMESTAMP}-{HASH}.md`) — there is no exact-name `test-report-{skill_name}.md` on disk. Locate the most recent report by glob, mirroring `skf-export-skill/references/load-skill.md §4b`:
+
+1. Glob `{forge_data_folder}/{skill_name}/{active_version}/test-report-{skill_name}-*.md` (i.e. `{forge_version}/test-report-{skill_name}-*.md`). Sort matches descending by the parsed ISO-timestamp segment in the filename (`YYYYMMDDTHHMMSSZ` between the skill name and the hash — `sort -r` on the filename works because the timestamp is the first variable component). Take the first match.
+2. If the versioned glob returns nothing, fall back to the same glob at the flat path `{forge_data_folder}/{skill_name}/test-report-{skill_name}-*.md`. Pick the newest by parsed timestamp.
+3. If neither glob returns anything, look for the stable companion `skf-test-skill-result-latest.json` in the same two directories (versioned first, then flat). Read the report path from `outputs[]` per the canonical contract documented at `shared/references/output-contract-schema.md` (resolved by skf-test-skill step 6 §4c) and load that file.
+
+If a report is located, set `test_report_path` in context to the resolved absolute path and set `update_mode: gap-driven`. Surface the actual file picked in the message (e.g. `test-report-{skill_name}-20260507T050917Z-487606-9b2f.md`) so an operator can navigate to the report from the log. If all three lookups fail, warn and continue with normal source drift mode.
 
 **If `--allow-workspace-drift` was provided:** set `allow_workspace_drift: true` in workflow context. This flag is consumed by step 3 §0.a's pre-flight drift guard (gap-driven mode only) and has no effect in normal source-drift mode.