bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/skf-create-skill/scripts/scan-doc-rot.py

@@ -0,0 +1,245 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""Deterministic doc-rot correction-indicator scan (step-doc-rot.md §2).
+
+step 5c self-declares its correction scan "grep-based and deterministic — no AI
+judgment is used for detection." This helper *is* that grep: it walks the
+resolved feeder artifacts, matches every line against the fixed 13-row
+correction-pattern table with case-insensitive substring containment (no regex,
+no semantics), and emits the matches as JSON. It applies the one positional
+filter the step documents — dropping matches that land inside the compiled
+SKILL.md's own `## Migration & Deprecation Warnings` section (compile §4b
+already authored those, so re-emitting them would be circular) — before it
+returns. Running the scan here (instead of in-prompt) makes the "deterministic,
+identical input → identical output" promise actually hold: the model no longer
+hand-greps multi-KB artifacts.
+
+The genuine judgment the step keeps in-prompt is untouched by this script:
+enriching each match's `affected` symbol from surrounding context (§2) and
+choosing where the `## CORRECTION` block goes (§3). The script emits every
+deterministic field (`source`, `pattern`, `category`, `context_line`,
+`line_number`); the prompt adds `affected`.
+
+The pattern table and category labels are the contract in step-doc-rot.md §2 —
+keep the two in lockstep.
+
+CLI usage:
+  uv run scan-doc-rot.py --skill-md <staged SKILL.md> [FEEDER ...]
+  uv run scan-doc-rot.py --feeder evidence-report.md --feeder provenance-map.json
+
+  --skill-md  the compiled/staged SKILL.md feeder (feeder #4); matches inside its
+              `## Migration & Deprecation Warnings` section are excluded. It is
+              also scanned like any other feeder.
+  FEEDER      any other feeder artifact (evidence-report.md, provenance-map.json,
+              temporal-context files). Repeatable positionally or via --feeder.
+
+  Missing or empty files are skipped silently (not an error), matching §1's
+  "attempt to load; if it does not exist or is empty, skip it."
+
+Output (stdout, one object):
+  {
+    "scanned": ["<path>", ...],        # feeders that existed and were non-empty
+    "matches": [                        # correction_matches[] (affected added in-prompt)
+      {"source": "<path>", "pattern": "deprecated", "category": "Deprecation",
+       "context_line": "<line text>", "line_number": <1-indexed int>},
+      ...
+    ],
+    "match_count": <int>,
+    "excluded_count": <int>             # SKILL.md matches dropped by the §4b filter
+  }
+
+Exit codes:
+  0  — scan emitted successfully (including the zero-match case)
+  1  — invalid arguments (no feeders supplied)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+# Fixed correction-pattern table — mirrors step-doc-rot.md §2. (pattern, category)
+# Order is the table order; scanning is per-pattern so overlapping patterns
+# (e.g. "deprecated" ⊂ "@deprecated") each record their own hit, exactly as the
+# 13-row table enumerates them.
+PATTERN_TABLE: list[tuple[str, str]] = [
+    ("deprecated", "Deprecation"),
+    ("@deprecated", "Deprecation"),
+    ("breaking change", "Breaking change"),
+    ("BREAKING", "Breaking change"),
+    ("removed in", "Removal"),
+    ("was removed", "Removal"),
+    ("renamed to", "Rename"),
+    ("renamed from", "Rename"),
+    ("superseded by", "Supersession"),
+    ("replaced by", "Supersession"),
+    ("no longer supported", "End of life"),
+    ("migration required", "Migration"),
+    ("signature changed", "Signature change"),
+]
+
+_MIGRATION_HEADING = re.compile(r"^\s*##\s+Migration\s*&\s*Deprecation Warnings", re.IGNORECASE)
+
+
+def scan_text(text: str, source: str) -> list[dict]:
+    """Case-insensitive substring scan of `text` against PATTERN_TABLE.
+
+    Returns one record per (line, pattern) hit, in file order then table order.
+    line_number is 1-indexed. Pure — no I/O.
+    """
+    matches: list[dict] = []
+    for idx, line in enumerate(text.splitlines(), start=1):
+        lowered = line.lower()
+        for pattern, category in PATTERN_TABLE:
+            if pattern.lower() in lowered:
+                matches.append(
+                    {
+                        "source": source,
+                        "pattern": pattern,
+                        "category": category,
+                        "context_line": line.strip(),
+                        "line_number": idx,
+                    }
+                )
+    return matches
+
+
+def migration_section_range(skill_md_text: str) -> tuple[int, int] | None:
+    """1-indexed [start, end) line window of the `## Migration & Deprecation
+    Warnings` section, or None if the section is absent.
+
+    start = the heading line; end = the next level-2 (`## `) heading, or EOF.
+    A `### ` subsection inside the section does NOT close it (only a sibling
+    `## ` heading does), matching §2's "before the next `##` heading".
+    """
+    lines = skill_md_text.splitlines()
+    start = None
+    for idx, line in enumerate(lines, start=1):
+        if _MIGRATION_HEADING.match(line):
+            start = idx
+            break
+    if start is None:
+        return None
+    end = len(lines) + 1
+    for idx in range(start + 1, len(lines) + 1):
+        if lines[idx - 1].lstrip().startswith("## "):
+            end = idx
+            break
+    return (start, end)
+
+
+def apply_migration_exclusion(
+    matches: list[dict], skill_md_source: str | None, skill_md_text: str | None
+) -> tuple[list[dict], int]:
+    """Drop matches whose source is the compiled SKILL.md and whose line sits
+    inside its Migration & Deprecation Warnings section. Returns (kept, dropped)."""
+    if skill_md_source is None or skill_md_text is None:
+        return matches, 0
+    window = migration_section_range(skill_md_text)
+    if window is None:
+        return matches, 0
+    start, end = window
+    kept, dropped = [], 0
+    for m in matches:
+        if m["source"] == skill_md_source and start <= m["line_number"] < end:
+            dropped += 1
+            continue
+        kept.append(m)
+    return kept, dropped
+
+
+def _load(path: str) -> str | None:
+    """Read a feeder file as UTF-8. Returns None for missing/empty (skip, not
+    an error). UTF-8 avoids cp1252 mojibake on Windows."""
+    p = Path(path)
+    if not p.is_file():
+        return None
+    text = p.read_text(encoding="utf-8")
+    if not text.strip():
+        return None
+    return text
+
+
+def scan_files(feeders: list[str], skill_md: str | None) -> dict:
+    """Scan every feeder + the skill-md feeder, apply the §4b exclusion, return
+    the result object. Deterministic: feeders scanned in the given order."""
+    scanned: list[str] = []
+    matches: list[dict] = []
+    skill_md_text = None
+
+    ordered = list(feeders)
+    if skill_md is not None:
+        ordered.append(skill_md)
+
+    for path in ordered:
+        text = _load(path)
+        if text is None:
+            continue
+        scanned.append(path)
+        if path == skill_md:
+            skill_md_text = text
+        matches.extend(scan_text(text, path))
+
+    matches, excluded = apply_migration_exclusion(matches, skill_md, skill_md_text)
+    return {
+        "scanned": scanned,
+        "matches": matches,
+        "match_count": len(matches),
+        "excluded_count": excluded,
+    }
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="scan-doc-rot",
+        description=(
+            "Deterministic doc-rot correction-indicator scan (step-doc-rot.md §2): "
+            "case-insensitive substring match of feeder artifacts against the fixed "
+            "correction-pattern table, with the compiled SKILL.md's Migration & "
+            "Deprecation Warnings section excluded."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument(
+        "positional_feeders",
+        nargs="*",
+        metavar="FEEDER",
+        help="Feeder artifact paths (evidence-report.md, provenance-map.json, temporal files).",
+    )
+    parser.add_argument(
+        "--feeder",
+        action="append",
+        default=[],
+        dest="feeders",
+        help="Feeder artifact path (repeatable). Equivalent to a positional FEEDER.",
+    )
+    parser.add_argument(
+        "--skill-md",
+        dest="skill_md",
+        default=None,
+        help="Compiled/staged SKILL.md feeder; its Migration & Deprecation Warnings "
+        "section is excluded from matches.",
+    )
+    return parser
+
+
+def main(argv=None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    feeders = list(args.positional_feeders) + list(args.feeders)
+    if not feeders and args.skill_md is None:
+        parser.print_usage(file=sys.stderr)
+        print("error: supply at least one feeder path or --skill-md", file=sys.stderr)
+        return 1
+    result = scan_files(feeders, args.skill_md)
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/skf-create-stack-skill/SKILL.md

@@ -12,6 +12,7 @@ Produces a consolidated stack skill documenting how libraries connect. **Code-mo
 ## Conventions
 
 - Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
+- The `knowledge/` and `shared/` prefixes are the exception: they resolve from the **SKF module root** (`{project-root}/_bmad/skf/` when installed, `src/` during development), not the skill root — they point at module-shared reference docs (`knowledge/tool-resolution.md`, `knowledge/version-paths.md`) and scripts/schemas (`shared/references/…`) that live once at the module root, mirroring the resolution note `references/health-check.md` carries for `shared/health-check.md`.
 - `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
 - `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
 - `{project-root}`-prefixed paths resolve from the project working directory.
@@ -34,7 +35,9 @@ These rules apply to every step in this workflow:
 
 ## Workflow state contract
 
-Every step that emits a warning ("log a warning", "record in workflow state for the evidence report", "Warning: ...", etc.) appends a structured entry to a single in-memory list named `workflow_warnings[]`. Each entry has the shape `{step: "step-NN", severity: "info|warn|error", code: "<short-slug>", message: "<human text>", context: {<optional fields>}}`. Step 7 surfaces these in `evidence-report.md`; step 8 may add validation findings; step 9 §5 reads the accumulated list and renders the user-facing "Warnings" section. There is exactly one accumulator for the whole workflow — do not invent per-step channels.
+Every step that emits a warning appends a structured entry to a single in-memory list named `workflow_warnings[]` (the one accumulator for the whole workflow). Each entry has the shape `{step: "step-NN", severity: "info|warn|error", code: "<short-slug>", message: "<human text>", context: {<optional fields>}}`. Step 7 surfaces these in `evidence-report.md`; step 8 may add validation findings; step 9 §5 reads the accumulated list and renders the user-facing "Warnings" section.
+
+**Single-pass — no mid-run checkpoint.** State lives in memory until step 7 commits `provenance-map.json`/`evidence-report.md`; the workflow keeps no resumable checkpoint and On Activation does not probe for a prior run — the analysis is deterministic and cheap to redo, and the two gates are trivially re-confirmed. If interrupted before that commit, restart from step 1.
 
 ## Stages
 
@@ -65,14 +68,13 @@ Every step that emits a warning ("log a warning", "record in workflow state for
 
 Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
 
-| Code | Meaning              | Raised by                                                                                  |
+| Code | Meaning              | Raised by (halt_reason)                                                                     |
 | ---- | -------------------- | ------------------------------------------------------------------------------------------ |
 | 0    | success              | step 10 (terminal handoff to shared health-check)                                          |
-| 2    | input-missing / input-invalid | step 1 §0 (`config.yaml` missing or malformed); step 2 §2 headless cannot proceed without manifests (S2); step 4 §3 all extractions failed (B7); step 5 §2 feasibility-report `schemaVersion` mismatch; compose-mode-rules `schemaVersion` mismatch |
-| 3    | resolution-failure   | step 1 §1 (`forge-tier.yaml` missing); step 2 §0 compose-mode skill resolution corruption (manifest + symlink both fail); step 2 §0 compose-mode zero qualifying skills (S1/S3) |
-| 4    | write-failure        | step 7 §1 stage-dir / commit-dir failure; step 7 §1 group-dir collision when an existing non-stack skill occupies the target path |
-| 5    | overwrite-cancelled  | step 7 collision when the user declines to replace an existing stack package |
-| 6    | user-cancelled       | any interactive menu in step 3 / step 6 (user selected `[X]` Cancel and exit) |
+| 2    | input / precondition invalid | step 1 §0 `config.yaml` missing/malformed (`config-missing`); step 2 §2 headless with no manifests (`no-manifests`, S2); step 4 §3 all extractions failed (`all-extractions-failed`, B7); step 5 §2 feasibility-report `schemaVersion` mismatch (`schema-version-mismatch`) |
+| 3    | resolution-failure   | step 1 §1 `forge-tier.yaml` missing (`forge-tier-missing`); step 2 §0 compose-mode skill-resolution corruption (manifest + symlink both fail); step 2 §0 compose-mode zero qualifying skills (S1/B4); step 4 §0 compose-cycle — all `resolution-failure` |
+| 4    | write-failure        | step 7 §1 stage-dir / commit-dir failure; step 7 §1 group-dir collision when an existing non-stack skill occupies the target path — both `write-failure` |
+| 6    | user-cancelled       | any interactive menu in step 3 / step 6 when the user selects `[X]` Cancel and exit (`user-cancelled`) |
 
 ## Result Contract (Headless)
 
@@ -82,7 +84,7 @@ When `{headless_mode}` is true, step 9 emits a single-line JSON envelope on **st
 SKF_STACK_RESULT_JSON: {"status":"success|error","skill_package":"…|null","skill_name":"…","stack_libraries":["…"],"mode":"code|compose","exit_code":0,"halt_reason":null}
 ```
 
-`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `skill_package` is the absolute path to the committed stack-skill directory (or `null` on error before commit). `skill_name` is the stack skill's published name (e.g. `{project_name}-stack`). `stack_libraries` is the array of library names included in the stack (constituent skill names in compose-mode, dependency names in code-mode). `mode` is `"code"` or `"compose"` per the run's resolved mode. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"forge-tier-missing"`, `"config-missing"`, `"no-manifests"`, `"all-extractions-failed"`, `"schema-version-mismatch"`, `"resolution-failure"`, `"write-failure"`, `"overwrite-cancelled"`, `"user-cancelled"`. `exit_code` matches the table above.
+`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `skill_package` is the absolute path to the committed stack-skill directory (or `null` on error before commit). `skill_name` is the stack skill's published name (e.g. `{project_name}-stack`). `stack_libraries` is the array of library names included in the stack (constituent skill names in compose-mode, dependency names in code-mode). `mode` is `"code"` or `"compose"` per the run's resolved mode (`null` if the run halts before mode resolution). `halt_reason` is one of: `null` (success), `"config-missing"`, `"forge-tier-missing"`, `"no-manifests"`, `"all-extractions-failed"`, `"schema-version-mismatch"`, `"resolution-failure"`, `"write-failure"`, `"user-cancelled"`. `exit_code` matches the table above. Fields unknown at the halt point are `null` (`skill_name`) or `[]` (`stack_libraries`) — e.g. a `config-missing` halt precedes `project_name` resolution.
 
 ## On Activation
 
@@ -118,6 +120,10 @@ SKF_STACK_RESULT_JSON: {"status":"success|error","skill_package":"…|null","ski
    - `{composeModeRulesPath}` ← `workflow.compose_mode_rules_path` if non-empty, else `references/compose-mode-rules.md`
    - `{provenanceMapSchemaPath}` ← `workflow.provenance_map_schema_path` if non-empty, else `assets/provenance-map-schema.md`
 
-   Stash all five as workflow-context variables. Stage files reference `{stackSkillTemplatePath}` / `{integrationPatternsPath}` / `{manifestPatternsPath}` / `{composeModeRulesPath}` / `{provenanceMapSchemaPath}` directly — no conditional at the usage site. Empty-string overrides cleanly fall through to the bundled default; non-empty values let orgs swap in house-style copies without forking the skill.
+   Also resolve `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string (no-op — `references/report.md` §6c skips the hook invocation entirely).
+
+   Stash all five paths plus `{onCompleteCommand}` as workflow-context variables. Stage files reference `{stackSkillTemplatePath}` / `{integrationPatternsPath}` / `{manifestPatternsPath}` / `{composeModeRulesPath}` / `{provenanceMapSchemaPath}` directly; empty-string overrides fall through to the bundled default.
+
+   Also apply the array surfaces: run `workflow.activation_steps_prepend` now, keep `workflow.persistent_facts` as standing context (`file:` entries load their contents), then run `workflow.activation_steps_append` after.
 
 4. Load, read the full file, and then execute `references/init.md` to begin the workflow.

package/src/skf-create-stack-skill/assets/provenance-map-schema.md

@@ -53,7 +53,7 @@ Used when the workflow ran in code-mode against an actual codebase. `source_repo
 
 ## Compose-mode variant
 
-Used when the workflow ran in compose-mode against pre-generated constituent skills. Source-anchor fields (`source_repo`, `source_commit`, `source_ref`) are `null` because there is no codebase to anchor against — provenance traces back to the constituent skills instead, captured in the `constituents[]` array. Each entry's `extraction_method` is `"compose-from-skill"`; integrations have `detection_method` of `"architecture_co_mention"` (named in the architecture doc), `"constituent_documented_contract"` (a cross-library contract documented in a constituent skill's integration docs but not co-mentioned in the architecture document — e.g. a grep-verified upstream seam cited from a source skill), or `"inferred_from_shared_domain"` (synthesized inference from shared language/domain, no cited contract). `detection_method` records *how* an edge was discovered; it is orthogonal to `confidence`, which is inherited from the constituent skills per the Confidence Tier Inheritance matrix in `references/compose-mode-rules.md` (the integration tier is the weaker of the pair — never forced to a fixed band by detection method).
+Used when the workflow ran in compose-mode against pre-generated constituent skills. Source-anchor fields (`source_repo`, `source_commit`, `source_ref`) are `null` because there is no codebase to anchor against — provenance traces back to the constituent skills instead, captured in the `constituents[]` array. Each entry's `extraction_method` is `"compose-from-skill"`; integrations have `detection_method` of `"architecture_co_mention"` (named in the architecture doc), `"constituent_documented_contract"` (a cross-library contract documented in a constituent skill's integration docs but not co-mentioned in the architecture document — e.g. a grep-verified upstream seam cited from a source skill), or `"inferred_from_shared_domain"` (synthesized inference from shared language/domain, no cited contract). `detection_method` records *how* an edge was discovered; it is orthogonal to `confidence`, which is inherited from the constituent skills per the Confidence Tier Inheritance matrix in `{composeModeRulesPath}` (the integration tier is the weaker of the pair — never forced to a fixed band by detection method).
 
 ```json
 {

package/src/skf-create-stack-skill/customize.toml

@@ -1,6 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-create-stack-skill.
+# Team overrides:     _bmad/custom/skf-create-stack-skill.toml (under {project-root})
+# Personal overrides: _bmad/custom/skf-create-stack-skill.user.toml (under {project-root})
 
 [workflow]
 
@@ -34,6 +36,14 @@ persistent_facts = [
   "file:{project-root}/**/project-context.md",
 ]
 
+# Command invoked once the workflow reaches its terminal stage — after the
+# stack package is committed and the result contract is written (step 9,
+# report.md §6c), before the health-check chain. Override wins. Use for a
+# terminal action such as catalog registration or notifying a downstream
+# pipeline. Empty string = no terminal action. The hook never fails the run.
+
+on_complete = ""
+
 # --- Optional asset overrides ---
 #
 # Lift the canonical asset paths so orgs can substitute house-style copies

package/src/skf-create-stack-skill/references/compile-stack.md

@@ -1,6 +1,5 @@
 ---
 nextStepFile: 'generate-output.md'
-stackSkillTemplate: 'assets/stack-skill-template.md'
 ---
 
 <!-- Config: communicate in {communication_language}. Artifact text in {document_output_language}. -->
@@ -13,7 +12,7 @@ Assemble the main SKILL.md by combining per-library extractions with the integra
 
 ## Rules
 
-- Compile SKILL.md following the stack-skill-template structure — integration patterns go first (primary value)
+- Compile SKILL.md following the stack-skill-template structure — integration patterns go first
 - Do not write output files (Step 07)
 - Present compiled content for user review
 
@@ -21,7 +20,7 @@ Assemble the main SKILL.md by combining per-library extractions with the integra
 
 ### 1. Load Template Structure
 
-Load `{stackSkillTemplate}` and prepare SKILL.md section structure.
+Load `{stackSkillTemplatePath}` and prepare SKILL.md section structure.
 
 ### 2. Generate Frontmatter
 
@@ -41,12 +40,12 @@ description: >
 **Frontmatter rules:**
 
 - `name`: lowercase alphanumeric + hyphens only, must match skill output directory name. **Stack skills MUST end in `-stack`** (e.g., `{project_name}-stack`) — this is how consumers (skf-verify-stack, skf-test-skill) detect stack vs individual skills.
-- `description`: non-empty, max 1024 chars, trigger-optimized for agent discovery. MUST use third-person voice ("Processes..." not "I can..." or "You can..."). **Do NOT enumerate every library by name** — a 12+ library stack overruns 1024 chars. Keep the generic "{lib_count} libraries with {integration_count} integration patterns" form; if a per-library parenthetical is used, cap it to the top libraries by import/export count with a `+{N} more` suffix (full list lives in `metadata.json` `libraries[]`). See "Sizing Guidance for Large Stacks" in `{stackSkillTemplate}`.
+- `description`: non-empty, max 1024 chars, trigger-optimized for agent discovery. MUST use third-person voice ("Processes..." not "I can..." or "You can..."). **Do NOT enumerate every library by name** — a 12+ library stack overruns 1024 chars. Keep the generic "{lib_count} libraries with {integration_count} integration patterns" form; if a per-library parenthetical is used, cap it to the top libraries by import/export count with a `+{N} more` suffix (full list lives in `metadata.json` `libraries[]`). See "Sizing Guidance for Large Stacks" in `{stackSkillTemplatePath}`.
 - No other frontmatter fields — only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` are permitted by spec
 
 ### 3. Compile Integration Layer
 
-**This is the core value of the stack skill.** Compile in order:
+Compile in order:
 
 **Zero-integration guard:** If the integration graph from step 05 has zero edges (no detected integration pairs), skip the integration layer compilation and note: "No integration patterns detected — stack skill will contain library summaries without an integration layer." Proceed directly to section 4 (Per-Library Sections).
 
@@ -72,7 +71,7 @@ description: >
 `Per-Library Summaries` and `Library Reference Index` are the largest sections
 and grow with the stack. For a **large stack** (heuristic: **> 6 libraries OR
 > 6 integration patterns**), author both into `references/stack-catalog.md`
-(structure in `{stackSkillTemplate}`) and place only the inline pointer from the
+(structure in `{stackSkillTemplatePath}`) and place only the inline pointer from the
 template's "Sizing Guidance" in SKILL.md — this keeps the body under the 500-line
 `body.max_lines` budget that step 08 enforces. For a **small stack**, keep both
 inline (inline passive context yields higher task accuracy). Either way, step 08's
@@ -132,9 +131,9 @@ Display: **Select:** [C] Continue to Output Generation | [X] Cancel and exit
 
 #### EXECUTION RULES:
 
-- ALWAYS halt and wait for user input after presenting compilation
+- This is a review gate — advancing without the user's `C` would write output files from a compilation they never reviewed. Halt and wait for input after presenting the compiled SKILL.md.
 - **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-approve stack compilation"
-- ONLY proceed to next step when user approves and selects 'C'
+- Proceed to the next step only once the user approves by selecting `C`.
 
 #### Menu Handling Logic:
 

package/src/skf-create-stack-skill/references/compose-mode-rules.md

@@ -6,18 +6,7 @@ Rules for synthesizing a stack skill from pre-generated individual skills and an
 
 ## Skill Loading
 
-Skills use version-nested directories — see `knowledge/version-paths.md` for the full path templates and resolution rules.
-
-**Version-aware skill enumeration:**
-
-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`.
-2. **Fallback: `active` symlinks** — If the manifest does not exist, is empty, or a manifest entry lacks an `active_version`, 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).
-3. **Filter:** Skip any skill named `{project_name}-stack` or any skill where `metadata.json` has `"skill_type": "stack"` — stack skills must not be loaded as source dependencies to avoid self-referencing loops
-4. Skip any resolved skill package missing either `SKILL.md` or `metadata.json` — log a warning and skip
-5. Load each `metadata.json` from the resolved version-aware path and extract: `name`, `language`, `confidence_tier`, `source_repo`, `exports` (count), `version`
-6. 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)
-7. Store the resolved package path as `skill_package_path` for use in later steps (extraction, integration detection)
-8. Store loaded skills as `raw_dependencies` with `source: "existing_skill"`
+The version-aware skill-enumeration protocol (export-manifest primary → active-symlink fallback → stack-skill filter → load metadata fields → store as `raw_dependencies`) is specified operationally in `detect-manifests.md` §0. That step runs at step 2 and has already enumerated and loaded every constituent skill into workflow state before this file is consulted at step 5, so the loading is not re-performed here — this file covers only the compose-mode composition rules below.
 
 ## Compose-mode Co-mention Precision
 
@@ -86,4 +75,4 @@ When no architecture document is available:
 - Mark all inferred integrations: `[inferred from shared domain]`
 - Inferred integrations default to lowest confidence of the pair with `[inferred from shared domain]` suffix (use this instead of `[composed]` for inferred integrations)
 
-**Constituent-documented contracts (distinct from shared-domain inference):** When a constituent skill's own integration docs cite a verifiable cross-library contract (e.g. a grep-verified upstream seam) that the architecture document does not co-mention, record it with `detection_method: constituent_documented_contract` (see `assets/provenance-map-schema.md`) — NOT `inferred_from_shared_domain`. It is a cited contract, not a synthesized guess. Its confidence still inherits the weaker tier of the pair per the matrix above — detection method is orthogonal to tier and never forces a fixed band.
+**Constituent-documented contracts (distinct from shared-domain inference):** When a constituent skill's own integration docs cite a verifiable cross-library contract (e.g. a grep-verified upstream seam) that the architecture document does not co-mention, record it with `detection_method: constituent_documented_contract` (see `{provenanceMapSchemaPath}`) — NOT `inferred_from_shared_domain`. It is a cited contract, not a synthesized guess. Its confidence still inherits the weaker tier of the pair per the matrix above — detection method is orthogonal to tier and never forces a fixed band.

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

@@ -1,10 +1,14 @@
 ---
 nextStepFile: 'compile-stack.md'
-integrationPatterns: 'references/integration-patterns.md'
-composeModeRules: 'references/compose-mode-rules.md'
 pairIntersectProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-pair-intersect.py'
   - '{project-root}/src/shared/scripts/skf-pair-intersect.py'
+comentionProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-comention-pairs.py'
+  - '{project-root}/src/shared/scripts/skf-comention-pairs.py'
+validateFeasibilityReportProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-feasibility-report.py'
+  - '{project-root}/src/shared/scripts/skf-validate-feasibility-report.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -19,7 +23,6 @@ Analyze co-import patterns between confirmed libraries to identify integration p
 
 - Focus on detecting cross-library patterns using subprocess Pattern 1 (grep/search)
 - Do not compile SKILL.md (Step 06)
-- Integration detection is the core differentiator of stack skills vs individual skills
 
 ## MANDATORY SEQUENCE
 
@@ -54,7 +57,7 @@ From `confirmed_dependencies`, conceptually you have N*(N-1)/2 unordered pairs.
    `pairs[]` is sorted by `intersection_count` DESC, then `(a, b)` ASC for stable ordering. Default Top-K cap is **20** (matches S7 below); pass `--top-k N` to override.
 3. **Parse the JSON result** and use `pairs[]` as the qualifying-pair set for §2 onward. The `intersection_count` is the candidate file count for the §2 2-file threshold pre-grep; `files[]` is the grep-scope for that pair.
 
-**Top-K cap (S7, 20):** If the script's response has `truncated: true`, more pairs than the cap had non-empty intersections. Surface a user-visible warning composed as: `"non-empty-intersection pair count {total_pairs} exceeds cap — analyzing top 20 by intersection size; {total_pairs - 20} pairs skipped"`. Record this cap in the evidence report. (Tie-break by intersection size is what the script sorts on; if you need to override the cap intentionally, pass `--top-k N` and document the rationale.) The legacy 50-dependency threshold that formerly gated a separate Top-K pass is retired — the file-intersection prune does the bulk of the work and the cap is now a second-order safety limit, not a primary strategy.
+**Top-K cap (S7, 20):** If the script's response has `truncated: true`, more pairs than the cap had non-empty intersections. Surface a user-visible warning composed as: `"non-empty-intersection pair count {total_pairs} exceeds cap — analyzing top 20 by intersection size; {total_pairs - 20} pairs skipped"`. Record this cap in the evidence report. (Tie-break by intersection size is what the script sorts on; if you need to override the cap intentionally, pass `--top-k N` and document the rationale.) The cap is a second-order safety limit, not a primary strategy — the file-intersection prune does the bulk of the work.
 
 Report: "**Analyzing {pair_count} library pairs for integration patterns** (pruned from {N*(N-1)/2} via file-list intersection; {capped_count} after Top-K if applicable)**...**"
 
@@ -64,29 +67,54 @@ Report: "**Analyzing {pair_count} library pairs for integration patterns** (prun
 
 Instead of co-import grep, detect integrations from architecture document:
 
-1. Load `{composeModeRules}` for integration evidence format rules
+1. Load `{composeModeRulesPath}` for integration evidence format rules
 2. **If `{architecture_doc_path}` is null or not available:** Skip directly to the "If no architecture document available" fallback below
-3. Load the architecture document from `{architecture_doc_path}`
-4. **Prose-based co-mention analysis with precision guards (H2):**
-   - Use **word-boundary matching** when searching for skill names in the architecture document: `\b{skill_name}\b` (case-insensitive). This prevents substring false positives (e.g., `react` matching inside `reactive`).
-   - **Exclude non-body sections.** Detect H1 and H2 markdown headers (`^# ` and `^## `) and skip any paragraphs under headers that normalise to `introduction`, `overview`, `glossary`, `table of contents`, `references`, `appendix`, or `index`. Co-mentions inside headings themselves also do not qualify.
-   - **Require ≥2 qualifying paragraphs.** A pair `(A, B)` qualifies only when at least two distinct body paragraphs each contain word-boundary matches for both `A` and `B`. A single co-mention paragraph is insufficient evidence.
-   - Risks and rationale are documented in `{composeModeRules}` under "Compose-mode co-mention precision".
-5. For each detected integration pair:
+3. **Compute qualifying co-mention pairs deterministically via the shared script.** The precision guards (word-boundary matching `\b{skill_name}\b` case-insensitive to reject substrings like `react` inside `reactive`; H1/H2 section exclusion for headers that normalise to `introduction`, `overview`, `glossary`, `table of contents`, `references`, `appendix`, or `index`, with heading text itself never a co-mention source; and the ≥2-distinct-body-paragraph gate) are a scan-and-count with one correct answer per `(architecture_doc, skill-name-set)` — do not perform them in-prompt. Risks and rationale stay documented in `{composeModeRulesPath}` under "Compose-mode co-mention precision".
+
+   **Resolve `{comentionHelper}`** from `{comentionProbeOrder}`; first existing path wins.
+
+   ```bash
+   uv run {comentionHelper} comention --doc {architecture_doc_path} --skills -
+   ```
+   piping the loaded skill names — the `confirmed_dependencies` names — as a JSON array on stdin (e.g. `["react", "express"]`; use a temp file under `{forge_data_folder}/` if stdin piping is unavailable). The script emits:
+   ```json
+   {
+     "pairs": [
+       {"a": "<skill>", "b": "<skill>", "paragraph_count": N,
+        "evidence": [{"header": "<governing-header-or-null>", "excerpt": "<text>"}, ...]},
+       ...
+     ],
+     "excluded_section_count": M
+   }
+   ```
+   `pairs[]` contains only qualifying pairs (≥2 distinct body paragraphs), sorted by `paragraph_count` DESC then `(a, b)` ASC. Use `pairs[]` as the detected-integration-pair set for step 4 onward; each pair's `evidence[]` supplies the governing header and paragraph excerpts to quote as architecture-reference evidence.
+
+   **Graceful degradation:** if no `{comentionProbeOrder}` candidate exists (e.g. `uv` unavailable on claude.ai web), perform the equivalent scan directly per the guards above and the script's `--help` contract, then proceed with the same qualifying-pair set.
+4. For each detected integration pair (from `pairs[]`):
    - Load both skills' export lists and API signatures
-   - Compose an integration section following the format from `{composeModeRules}`
+   - Compose an integration section following the format from `{composeModeRulesPath}`
    - Include VS feasibility verdict if a feasibility report matching the filename pattern defined in `src/shared/references/feasibility-report-schema.md` exists under `{forge_data_folder}/` (timestamped `feasibility-report-{project_slug}-{YYYYMMDD-HHmmss}.md` or the stable `feasibility-report-{project_slug}-latest.md` copy). Schema version `"1.0"` is required; see the schema for the full contract.
    - Cite evidence from both skills: `[from skill: {skill_name}]`
 
-All integration evidence inherits confidence tiers from the source skills. Load and apply the full **Confidence Tier Inheritance** matrix from `{composeModeRules}` to compute the correct tier for each pair (covers T1+T1, T1+T1-low, T1-low+T1-low, T1+T2, T1-low+T2, T2+T2 cases). Apply the `[composed]` suffix to all confidence labels — e.g., `T1 [composed]`, `T1-low [composed, +T2 annotations]`.
+All integration evidence inherits confidence tiers from the source skills. Load and apply the full **Confidence Tier Inheritance** matrix from `{composeModeRulesPath}` to compute the correct tier for each pair (covers T1+T1, T1+T1-low, T1-low+T1-low, T1+T2, T1-low+T2, T2+T2 cases). Apply the `[composed]` suffix to all confidence labels — e.g., `T1 [composed]`, `T1-low [composed, +T2 annotations]`.
 
 **VS verdict parsing (if feasibility report exists):** The feasibility report format is defined by the shared schema at `src/shared/references/feasibility-report-schema.md` (single source of truth; skf-verify-stack is the producer, this skill is the consumer). Follow the schema strictly:
 
 - Locate the report via the filename pattern in the schema: `{forge_data_folder}/feasibility-report-{project_slug}-{YYYYMMDD-HHmmss}.md` (or the stable `feasibility-report-{project_slug}-latest.md` copy next to it).
-- **Schema version guard:** Parse the report's YAML frontmatter and verify `schemaVersion == "1.0"`. If the field is missing or mismatched, HALT with an explicit error: `"feasibility-report schemaVersion mismatch: expected '1.0', got '{value}' — refusing to proceed"`. Do NOT attempt to interpret unknown versions.
+- **Schema version guard (deterministic gate):** Resolve `{validateFeasibilityReportHelper}` from `{validateFeasibilityReportProbeOrder}` (first existing path wins) and run it against the located report:
+
+  ```bash
+  python3 {validateFeasibilityReportHelper} <located-report-path>
+  ```
+
+  Consume `schemaVersionOk` / `schemaVersionFound` from its JSON. If `schemaVersionOk` is false, HALT with `"feasibility-report schemaVersion mismatch: expected '1.0', got '{schemaVersionFound}' — refusing to proceed"`, then emit the result envelope on stderr per the Result Contract in SKILL.md and exit `2`. The script's structural findings (`headingsOk` / `orderViolations`) are advisory for this consumer — it gates only on schemaVersion. **If the helper does not resolve or cannot run,** parse the report's YAML frontmatter directly and compare `schemaVersion` to the literal `1.0`, applying the same HALT (a missing or mismatched version halts identically). Unknown versions are never interpreted.
+
+  ```
+  SKF_STACK_RESULT_JSON: {"status":"error","skill_package":null,"skill_name":"{project_name}-stack","stack_libraries":[],"mode":"compose","exit_code":2,"halt_reason":"schema-version-mismatch"}
+  ```
 - Read `overallVerdict` from frontmatter (exactly one of `FEASIBLE|CONDITIONALLY_FEASIBLE|NOT_FEASIBLE`).
 - Parse the `## Integration Verdicts` markdown table for per-pair verdicts (exactly one of `Verified|Plausible|Risky|Blocked`). Any unknown verdict token is a hard error per the schema — do not silently drop or map.
-- For each architecture-detected pair, include `VS overall: {overallVerdict}` and `VS pair: {verdict}` in the integration evidence per the format in `{composeModeRules}`. VS verdicts do not apply to inferred integrations since the VS report operates on architecture-described interactions only. Additionally, flag any pairs where VS reported `Risky` or `Blocked` by appending a `[VS: Risky]` or `[VS: Blocked]` warning annotation to the integration entry.
+- For each architecture-detected pair, include `VS overall: {overallVerdict}` and `VS pair: {verdict}` in the integration evidence per the format in `{composeModeRulesPath}`. VS verdicts do not apply to inferred integrations since the VS report operates on architecture-described interactions only. Additionally, flag any pairs where VS reported `Risky` or `Blocked` by appending a `[VS: Risky]` or `[VS: Blocked]` warning annotation to the integration entry.
 
 If no architecture document available:
 - Infer potential integrations from skills sharing the same `language` field or sharing domain keywords in their SKILL.md descriptions (use the `usage_patterns` and `exports` fields from `per_library_extractions[]` built in step 4, or reload SKILL.md from the version-aware path: use `skill_package_path` from step 2, or resolve via `{skills_output_folder}/{skill_dir}/active/{skill_dir}/SKILL.md` — see `knowledge/version-paths.md`)
@@ -115,7 +143,7 @@ If `tools.ccc` is true AND `ccc_index.status` is `"fresh"` or `"stale"` in forge
 
 For each library pair with **0 or 1 co-import files** (below the 2-file threshold — S9, symmetric to give the 0-hit case the same chance as the 1-hit case), run `ccc_bridge.search("{libA} {libB}", source_root, top_k=10)` to find files where the two libraries interact semantically — even without explicit import co-location. If CCC returns additional files where both libraries appear, add them to the pair's co-import candidate list and re-evaluate against the 2-file threshold.
 
-**CCC precision guard for 1-file pairs (H3):** When a CCC hit would elevate a 1-file pair to qualifying status, run a post-hoc verification on that file: re-grep the file and confirm it contains explicit import statements for **both** libraries (per the ecosystem import patterns from `references/manifest-patterns.md`). If either import is missing (e.g., one library is only name-dropped in a comment or string), drop the CCC-added file from the candidate list. Only pairs with ≥2 files that each contain explicit imports for both libraries qualify. Log rejected CCC candidates in workflow state for the evidence report.
+**CCC precision guard for 1-file pairs (H3):** When a CCC hit would elevate a 1-file pair to qualifying status, run a post-hoc verification on that file: re-grep the file and confirm it contains explicit import statements for **both** libraries (per the ecosystem import patterns from `{manifestPatternsPath}`). If either import is missing (e.g., one library is only name-dropped in a comment or string), drop the CCC-added file from the candidate list. Only pairs with ≥2 files that each contain explicit imports for both libraries qualify. Log rejected CCC candidates in workflow state for the evidence report.
 
 **Tool resolution for ccc_bridge.search:** Use `/ccc` skill search (Claude Code), ccc MCP server (Cursor), or `ccc search "{libA} {libB}" --path {source_root} --top 10` (CLI). See `knowledge/tool-resolution.md`.
 
@@ -125,16 +153,9 @@ CCC failures: skip augmentation silently, proceed with grep-only results.
 
 ### 3. Classify Integration Types
 
-Load `{integrationPatterns}` for classification rules.
+Load `{integrationPatternsPath}` for classification rules.
 
-For each qualifying pair, analyze to classify the integration type (**in compose-mode**: all architecture-document-detected pairs qualify automatically — the 2+ co-import file threshold applies only in code-mode; **in code-mode**: pair must have 2+ co-import files):
-
-- **Type 1: Middleware Chain** — Sequential function calls piping output between libraries
-- **Type 2: Shared Types** — Type definitions exchanged between libraries
-- **Type 3: Configuration Bridge** — One library configuring or initializing another
-- **Type 4: Event Handler** — Event patterns crossing library boundaries
-- **Type 5: Adapter/Wrapper** — Thin wrapper connecting library interfaces
-- **Type 6: State Sharing** — Shared state stores or context providers
+For each qualifying pair, analyze to classify the integration type against those pattern types (**in compose-mode**: all architecture-document-detected pairs qualify automatically — the 2+ co-import file threshold applies only in code-mode; **in code-mode**: pair must have 2+ co-import files):
 
 For each detected integration:
 - Identify the top 3 files demonstrating the pattern
@@ -145,7 +166,7 @@ For each detected integration:
   - `architecture-co-mention` — compose-mode pair qualified via word-boundary co-mention in the architecture document (per §2 H2 guards). Maps to `detection_method: architecture_co_mention` in `provenance-map.json`.
   - `constituent-documented-contract` — compose-mode pair whose cross-library contract is documented in a constituent skill's integration docs (cited, e.g. a grep-verified upstream seam) but not co-mentioned in the architecture document. Maps to `detection_method: constituent_documented_contract` in `provenance-map.json`.
   - `inferred-shared-domain` — compose-mode pair without an architecture document, inferred from shared `language` or domain keywords (no cited contract). Maps to `detection_method: inferred_from_shared_domain` in `provenance-map.json`.
-  - Render as `{tier} ({qualifier})` — e.g., `T1-low (grep-co-import)`, `T1 (ccc-augmented)`, `T1-low (architecture-co-mention) [composed]`. The `[composed]`/`[inferred from shared domain]` suffix from `compose-mode-rules.md` is appended after the qualifier in compose-mode.
+  - Render as `{tier} ({qualifier})` — e.g., `T1-low (grep-co-import)`, `T1 (ccc-augmented)`, `T1-low (architecture-co-mention) [composed]`. The `[composed]`/`[inferred from shared domain]` suffix from `{composeModeRulesPath}` is appended after the qualifier in compose-mode.
 
   **Provenance ↔ SKILL.md tier parity:** The tier derived above is the single value for this edge — write the *same* tier to both the SKILL.md integration label and `provenance-map.json` `integrations[].confidence`. The detection-method qualifier (and the `provenance-map.json` `detection_method` it maps to) records *how* the edge was found and is orthogonal to confidence; it never forces the tier into a fixed band.
 
@@ -159,33 +180,7 @@ Assemble the integration graph:
 
 ### 5. Display Integration Summary
 
-**If integrations detected:**
-
-"**Integration detection complete.**
-
-**Integration graph:** {lib_count} libraries, {pair_count} integration pairs
-
-**Hub libraries** (connected to 3+ others):
-{For each hub:} - **{library}** — integrates with {partner_list}
-
-**Detected integrations:**
-| Library A | Library B | Type | Co-import Files | Confidence |
-|-----------|-----------|------|-----------------|------------|
-| {name} | {name} | {type} | {count} | {tier} |
-
-{If cross-cutting patterns:}
-**Cross-cutting patterns:**
-- {description spanning 3+ libraries}
-
-**Proceeding to stack compilation...**"
-
-**If no integrations detected:**
-
-"**No co-import integration patterns detected** between confirmed libraries.
-
-The libraries in this project appear to operate independently. The stack skill will contain library summaries without an integration layer.
-
-**Proceeding to stack compilation...**"
+If integrations were detected, report the integration graph (`{lib_count}` libraries, `{pair_count}` pairs): the hub libraries (connected to 3+ others) with their partners, each detected pair (library A, library B, type, co-import file count, confidence tier), and any cross-cutting patterns spanning 3+ libraries. If none were detected, report that no co-import integration patterns were found — the libraries appear to operate independently, so the stack skill will carry library summaries without an integration layer.
 
 ### 6. Auto-Proceed to Next Step