bmad-module-skill-forge 2.2.0 → 4.0.0

package/src/skf-create-stack-skill/references/detect-manifests.md

@@ -6,6 +6,9 @@ scanManifestsProbeOrder:
 enumerateStackSkillsProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-enumerate-stack-skills.py'
   - '{project-root}/src/shared/scripts/skf-enumerate-stack-skills.py'
+emitEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-result-envelope.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -14,74 +17,50 @@ enumerateStackSkillsProbeOrder:
 
 ## STEP GOAL:
 
-Scan the project root for dependency manifest files, parse each to extract dependency names and versions, and produce a raw dependency list for ranking.
+Take the dependency manifests of `{scan_root}` (the folder step 1 chose) from the manifest scanner and produce a raw dependency list for ranking; in compose mode, pick the constituent skills instead.
 
 ## Rules
 
-- Focus only on finding and parsing manifest files
+- Render the scanner's and the candidates helper's JSON; never parse a manifest or join candidates by hand
 - Do not count imports or rank dependencies (Step 03) or extract documentation (Step 04)
 - If explicit dependency list was provided in step 01, use it and skip detection
 
 ## MANDATORY SEQUENCE
 
-### 0. Check Compose Mode
-
-**If `compose_mode` is true AND `explicit_deps` was provided in step 01:**
-
-Use the explicit dependency list directly. Store the explicit list as `raw_dependencies` with `source: "explicit"` and skip to [Auto-Proceed to Next Step](#4-auto-proceed-to-next-step).
-
-**If `compose_mode` is true AND `explicit_deps` was NOT provided:**
-
-Discover skills in `{skills_output_folder}` using version-aware resolution — see `knowledge/version-paths.md` for path templates.
-
-**Version-aware skill enumeration:**
+**Halt envelope.** Every HALT in this step names its exit code, `halt_reason` and phase. Stage `{run_dir}/halt.json` as `{"phase": "<phase>", "halt_reason": "<halt_reason>", "reason": "<the halt message, one line>", "skill_name": "{stack_name}", "mode": "<code|compose>"}`, then run:
 
-1. **Primary: Export manifest** — Read `{skills_output_folder}/.export-manifest.json`. For each entry in `exports`, resolve the active version path: `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/` — this directory must contain both `SKILL.md` and `metadata.json`.
-
-   **Stale manifest fallback (H6):** If a manifest entry resolves to a path that does not exist (broken `active_version`, deleted version dir, missing `SKILL.md` / `metadata.json`), do NOT HALT for that single entry. Instead:
-   a. Fall back to the symlink scan (rule 2) **for that one skill only**: probe `{skills_output_folder}/{skill-name}/active/{skill-name}/SKILL.md`.
-   b. If the symlink-based path resolves, use it and log a warning: `"export-manifest entry '{skill-name}' is stale — resolved via active symlink instead"`.
-   c. If BOTH the manifest path AND the symlink path fail, only then HALT with a manifest-corruption diagnostic naming the affected skill and pointing the user at `[SKF-update-skill]` to repair. Emit the result envelope on stderr per the Result Contract in SKILL.md, then STOP:
-
-   ```
-   SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":"{project_name}-stack","stack_libraries":[],"mode":"compose","exit_code":3,"halt_reason":"resolution-failure"}
-   ```
-
-   **Manifest JSON parse guard (B3):** Wrap the `.export-manifest.json` parse in try/except. If JSON parsing fails for any reason, fall through entirely to the `active` symlink scan (rule 2) across all skills; log a warning and validate each symlink target exists before including it.
-
-2. **Fallback: `active` symlinks** — If the manifest does not exist, is empty, JSON-parse fails, or an individual manifest entry fails to resolve, scan for `{skills_output_folder}/*/active/*/SKILL.md`. Each match resolves to a skill package at `{skills_output_folder}/{skill-name}/active/{skill-name}/` (the `{active_skill}` template). Verify the active symlink target actually exists and contains both `SKILL.md` and `metadata.json`.
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-stack-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"
+```
 
-**Filter & cycle guard (B4):** Skip any skill where the filter below matches:
+Display the line it prints, then stop with the halt's exit code (`references/invocation-contract.md` lists every halt). If `{emitEnvelopeHelper}` is not bound, resolve it from `{emitEnvelopeProbeOrder}`; if no path exists, or the emitter exits non-zero or prints no line, display the halt message alone.
 
-- Skill name equals `{project_name}-stack`, OR
-- `metadata.json` has `"skill_type": "stack"`, OR
-- `metadata.json` is missing or unreadable (treat `skill_type: unknown` as non-loadable — exclude to avoid loading a partially-written or self-referential skill).
+### 0. Check Compose Mode
 
-Maintain a **visited set keyed by `skill_dir`** (the top-level dir under `{skills_output_folder}`) while resolving. If a skill would be revisited via a circular reference (e.g., a constituent that claims another stack as dependency), skip the duplicate and log a warning `"cycle detected at {skill_dir} — skipping"`. Stack skills must not be loaded as source dependencies to avoid self-referencing loops.
+**If `compose_mode` is true:**
 
-**If zero skills remain after filtering:** HALT with: "**Cannot proceed in compose-mode.** No individual skills found in `{skills_output_folder}` (after filtering stack skills). Run [CS] Create Skill or [QS] Quick Skill to generate individual skills first, then re-run [SS]." Then emit the result envelope on stderr per the Result Contract in SKILL.md, and STOP:
+Pick the constituent skills with the shared helper, which keeps only the skills SKF generated (a `metadata.json` SKF marker: see `knowledge/version-paths.md` Ownership) and gates every candidate in one call. When step 1 kept `{skill_candidates}`, use that result: it ran this same call. Otherwise resolve `{enumerateStackSkillsHelper}` from `{enumerateStackSkillsProbeOrder}` (first existing path wins; if no candidate exists, HALT (exit 3, `halt_reason: "helper-missing"`, phase `detect-manifests:enumerate`) with "**Cannot proceed.** `skf-enumerate-stack-skills.py` is missing, so no constituent skill can be picked. Re-install SKF, then re-run.") and run it, passing `--explicit` with the `explicit_deps` entries as given, comma-separated, when step 1 bound them (the helper reduces a package path to its skill folder):
 
-```
-SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":"{project_name}-stack","stack_libraries":[],"mode":"compose","exit_code":3,"halt_reason":"resolution-failure"}
+```bash
+uv run {enumerateStackSkillsHelper} candidates {skills_output_folder} [--explicit "<names>"]
 ```
 
-**Deterministic metadata hashing (S13) — script-driven:** Do NOT compute `sha256` in-prompt (a model cannot reproduce a digest, so a hand-computed hash would false-diverge against step 4's script-computed hash). Invoke the same enumeration helper step 4 §0 uses to obtain every constituent's `metadata_hash` in one deterministic call:
+Render its JSON as it stands, never re-joining candidates by hand. An exit `1` (no skills folder) counts as an empty `kept[]`:
 
-**Resolve `{enumerateStackSkillsHelper}`** from `{enumerateStackSkillsProbeOrder}`; first existing path wins. HALT if no candidate exists.
-
-```bash
-uv run {enumerateStackSkillsHelper} enumerate {skills_output_folder}
-```
+- `manifest_parse_error` is not null: log `"{manifest_parse_error}: using the active links instead"` (B3).
+- `not_skf_output` is not empty: display it once, "Skipped (not SKF output): {not_skf_output}".
+- Each `excluded[]` entry: log its `message` as given, one line each.
+- `stale_manifest_keys` is not empty (**stale manifest, H6**: the export manifest names a skill whose folder is gone): HALT (exit 3, `halt_reason: "resolution-failure"`, phase `detect-manifests:stale-manifest`) with a manifest-corruption diagnostic naming each key and pointing the user at `[SKF-update-skill]` to repair.
+- `kept[]` is empty: HALT (exit 3, `halt_reason: "resolution-failure"`, phase `detect-manifests:no-skills`) with "**Cannot proceed in compose-mode.** No individual skills found in `{skills_output_folder}` (stack skills are never constituents). Run [CS] Create Skill or [QS] Quick Skill to generate individual skills first, then re-run [SS]."
 
-Key the emitted `skills[].metadata_hash` (a `sha256:`-prefixed digest of the raw `metadata.json`, or `null` when no metadata.json is present) by `skills[].name` for use in rule 5 below. The script's `name` is the top-level subdirectory under `{skills_output_folder}` — i.e. the `skill_dir` captured in rule 3, not the metadata `name` — so join on `skill_dir`.
+A composes cycle is not an exclusion: step 4 §0 halts on one that involves a confirmed skill.
 
-For each skill found:
-1. Read `metadata.json` from the resolved version-aware path (`{skill_package}` or `{active_skill}`). **Skill-type gate (S1):** the sibling `metadata.json` MUST be present AND parseable AND contain a `skill_type` field whose value is one of the known set (`skill`, `stack`, or any future values explicitly recognised by this workflow). Directories lacking a qualifying `metadata.json`/`skill_type` are NOT treated as skills — log `"{dir_name}: not a skill (no valid metadata.json/skill_type) — excluding"` and skip.
-2. Extract: name, language, confidence_tier, source_repo, exports count, version
-3. Store the skill group directory name as `skill_dir` (the top-level name under `{skills_output_folder}`, distinct from `name` — the directory may differ from the metadata name)
-4. Store the resolved package path as `skill_package_path` for use in later steps
-5. **Record the constituent metadata_hash (S13):** take this skill's `metadata_hash` from the enumerate-script inventory above (matched on `skill_dir`) and store it in workflow state alongside `skill_package_path`. The script is the single source of this hash — never hand-compute — so the step-4 drift check compares script-hash to script-hash and never false-positives on a model recomputation. Step-07 uses this stored hash (not a re-read) for `constituents[].metadata_hash` in `provenance-map.json`, so drift between step 2 read and step 7 write is captured.
-6. Store as `raw_dependencies` with source: "existing_skill"
+For each `kept[]` entry:
+1. Store its `name`, the top-level folder, as `skill_dir` (distinct from the metadata `name`).
+2. `skill_package_path` ← `{skills_output_folder}/{path}` from that entry: the package whose exports and `metadata_hash` the helper reported, so path and hash come from one resolution (the helper follows `active`, as the manifest-lag guard in `knowledge/version-paths.md` does).
+3. Read `metadata.json` from `skill_package_path` for the fields the entry lacks: name, version and source_authority. The entry gives language, confidence_tier, source_repo and the export count (`exports`).
+4. **Record the constituent metadata_hash (S13):** take its `metadata_hash` (a `sha256:`-prefixed digest of the raw `metadata.json`) from the same `kept[]` entry and store it in workflow state alongside `skill_package_path`. The script is the single source of this hash (never hand-compute it); step 4 §0 checks it for drift and records the provenance anchor.
+5. Store as `raw_dependencies` with source: "existing_skill" (`"explicit"` for a name from `explicit_deps`)
 
 Report the `{N}` loaded skills — for each: name, language, confidence tier, export count, and source.
 
@@ -103,58 +82,54 @@ Store the explicit list as `raw_dependencies` and skip to [Display Detection Sum
 
 ### 2. Scan and Parse Manifests
 
-Invoke the deterministic manifest scanner — it walks the project root, parses every recognised manifest, dedupes the production dep set, and flags monorepo layout:
-
-**Resolve `{scanManifestsHelper}`** from `{scanManifestsProbeOrder}`; first existing path wins. HALT if no candidate exists.
+Step 1 §3 ran the deterministic manifest scanner on `{scan_root}` and kept its JSON as `{manifest_scan}`: use it. Run the scanner again only on a folder the user names below. **Resolve `{scanManifestsHelper}`** from `{scanManifestsProbeOrder}`; first existing path wins. If no candidate exists, HALT (exit 3, `halt_reason: "helper-missing"`, phase `detect-manifests:scan`) with "**Cannot proceed.** `skf-scan-manifests.py` is missing, so no manifest can be read. Re-install SKF, then re-run."
 
 ```bash
-uv run {scanManifestsHelper} scan {scan_root}
+uv run {scanManifestsHelper} scan {scan_root} --include-dev
 ```
 
-Where `{scan_root}` is the project root path. Load `{manifestPatternsPath}` for the ecosystem reference table that documents supported filenames, dependency keys, and normalisation rules; the script implements exactly that table (npm/pnpm/yarn, python pip/poetry/pdm, rust cargo, go modules, java/kotlin maven + gradle, ruby bundler, composer, swift package manager). Exclusion patterns (`node_modules/`, `.venv/`, `vendor/`, `dist/`, `build/`, `target/`, `.git/`, hidden dirs) are applied internally.
-
-Parse the JSON output — shape:
+`references/manifest-patterns.md` documents the manifest files and dependency sections the scanner reads and the folders it skips; the script implements exactly that table. The JSON it emits (its docstring has every field):
 
 ```
 {
   "manifests": [
-    {"path": "<rel-from-root>", "ecosystem": "<name>", "deps": [{"name": "...", "version": "..."}]},
+    {"path": "<rel-from-scan-root>", "ecosystem": "<name>", "name": "<package name>" | null,
+     "deps": [{"name": "...", "version": "...", "scope": "dev"}]},   // `scope` only on a dev dependency
     ...
   ],
-  "total_unique": N,
+  "total_unique": N,                            // unique runtime dependency names
+  "total_unique_dev": N,                        // unique names that are dev dependencies only
   "monorepo": <bool>,
-  "warnings": ["..."]   // optional, only if any parse warning fired
+  "folders": [{"path": "<folder>", "names": ["..."]}, ...],  // each manifest folder ("." for {scan_root})
+  "searched_filenames": ["package.json", ...],  // every manifest name looked for
+  "warnings": ["..."]                           // only when a manifest did not parse
 }
 ```
 
 If `manifests` is empty:
 
-**Headless auto-cancel (S2):** If `{headless_mode}` is true, do NOT wait for user input. Emit the result envelope on stderr per the Result Contract in SKILL.md and exit `2`. Headless mode cannot proceed without an explicit dependency list.
-
-```
-SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":"{project_name}-stack","stack_libraries":[],"mode":"code","exit_code":2,"halt_reason":"no-manifests"}
-```
+**GATE [default: HALT]**, headless auto-cancel (S2): if `{headless_mode}` is true, do NOT wait for user input: HALT (exit 2, `halt_reason: "no-manifests"`, phase `detect-manifests:no-manifests`) with "**Cannot proceed.** No dependency manifests in `{scan_root}`, and a headless run needs one or an explicit `skills` list."
 
 **Interactive mode:**
 
-"**No dependency manifests detected** in the project root.
+"**No dependency manifests detected** in `{scan_root}`.
 
-Searched for: package.json, requirements.txt, Cargo.toml, go.mod, pom.xml, build.gradle, Gemfile, composer.json, *.csproj
+Searched for: {the `searched_filenames`, comma-separated}
 
 **Options:**
 1. Provide an explicit dependency list
-2. Specify a different project root path
+2. Scan a different folder
 3. Cancel workflow
 
-**Halting — please provide input.**"
+**Halting: please provide input.**"
 
-STOP — wait for user response.
+STOP and wait for the user's response. Option 2 sets `{scan_root}` to the folder the user names (a relative path resolves from `project_root`) and runs the scan call above again, replacing `{manifest_scan}`. Option 3 is a HALT (exit 6, `halt_reason: "user-cancelled"`, phase `detect-manifests:no-manifests`): emit it, then delete the run folder (`rm -rf "{run_dir}"`).
 
-Otherwise, store the parsed `manifests[]` and `total_unique` as `raw_dependencies` (dedup is already applied by the scanner), surface any `warnings[]` to the user as parse-quality notes, and inspect the `monorepo` flag: if `true`, mention the monorepo layout in the detection summary so the user can decide whether to scope the ranking to a specific package or proceed across all manifests.
+Otherwise, `raw_dependencies` is `{manifest_scan}` as it stands (the scanner already deduplicates, and step 3 pipes it to the import counter). Surface any `warnings[]` to the user as parse-quality notes. When `folders[]` lists more than one folder, the detection summary says so and names `{scan_root}`, the folder step 1 §3 chose (the whole project unless `project_path` or the user's answer named one package): to stack one package, re-run with `project_path` set to its folder.
 
 ### 3. Display Detection Summary
 
-Report the detected manifests (for each: path, ecosystem, dependency count) and the total unique dependency count split into runtime vs dev-only.
+Report `{scan_root}`, the detected manifests (for each: path, ecosystem, dependency count), and the unique dependency count split by each dependency's `scope`: runtime (`total_unique`) and dev only (`total_unique_dev`). With `explicit_deps`, report its library count instead.
 
 ### 4. Auto-Proceed to Next Step