bmad-module-skill-forge 0.9.0 → 0.10.1-alpha.0

package/src/skf-create-skill/steps-c/sub/step-03b-fetch-temporal.md

@@ -0,0 +1,229 @@
+---
+nextStepFile: './step-03c-fetch-docs.md'
+# Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
+# (installed SKF module path first, src/ dev-checkout fallback); first existing
+# path wins. HALT if neither resolves.
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+---
+
+# Step 3b: Fetch Temporal Context
+
+## STEP GOAL:
+
+To fetch temporal context (issues, PRs, changelogs, release notes) from the source repository and index it into a QMD collection for Deep tier enrichment. This ensures step-04 has historical data to search when annotating extracted functions with T2 provenance.
+
+## Rules
+
+- Deep tier only — Quick, Forge, and Forge+ tiers skip this step entirely and silently
+- GitHub repositories only — other source types degrade gracefully
+- Do not halt the workflow if fetching or indexing fails
+- Do not modify extraction data from step-03 — this step only creates QMD collections
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Check Eligibility
+
+Evaluate the following conditions sequentially. **If ANY condition fails, skip silently to section 5 (auto-proceed) with no output:**
+
+1. **Tier is Deep:** If tier is Quick, Forge, or Forge+, skip silently.
+2. **Source is GitHub:** Verify `source_repo` is a GitHub URL (`https://github.com/...`) or `owner/repo` format. If the source is a local path, a non-GitHub URL, or any other format, attempt GitHub remote detection (section 1b) before skipping.
+3. **`gh` CLI is available:** Run `timeout 10s gh auth status` to verify the CLI is installed and authenticated (the short timeout protects against a misconfigured network or hung auth helper blocking the workflow). If it fails or times out, skip silently.
+
+All three conditions must pass to proceed to section 2.
+
+### 1b. GitHub Remote Detection for Local Sources
+
+**Only runs when condition 2 above fails because `source_repo` is a local path.**
+
+Local repositories that are clones of GitHub repos contain temporal context (issues, PRs, releases) accessible via `gh`. Detect this automatically:
+
+1. Check if the local path is a git repository: `git -C "{source_repo}" rev-parse --is-inside-work-tree`
+2. If not a git repo: skip silently to section 5 (current behavior).
+3. Extract the origin remote: `git -C "{source_repo}" remote get-url origin`
+4. If the remote URL contains `github.com`:
+   - Extract `owner/repo` from the remote URL (strip `.git` suffix, handle both HTTPS and SSH formats)
+   - Log: "**Local source with GitHub remote detected:** {owner}/{repo} — fetching temporal context."
+   - Use the extracted `owner/repo` for all `gh` API calls in sections 3-4. Continue to condition 3 (gh CLI check).
+5. If no remote, or remote is not GitHub: skip silently to section 5 (current behavior).
+
+### 2. Check Cache (Skip If Fresh)
+
+Read `forge-tier.yaml` from the sidecar path.
+
+- Look for a `qmd_collections` entry where `skill_name` matches the current brief AND `type` is `"temporal"`.
+- If found AND `created_at` is within the last **7 days** (rationale: temporal context — issues, PRs, changelogs — rarely changes meaningfully on shorter horizons; a 7-day window balances freshness against re-fetch cost and GitHub rate limits): the temporal collection is fresh. Display:
+
+"**Temporal context: cached.** Collection `{skill-name}-temporal` is fresh ({days} days old). Skipping re-fetch."
+
+Skip to section 5 (auto-proceed).
+
+- If not found OR `created_at` is older than 7 days: continue to section 3.
+
+### 3. Fetch Temporal Context
+
+Create a staging directory: `_bmad-output/{skill-name}-temporal/`
+
+Resolve the `owner` and `repo` from `source_repo` (e.g., `acme/toolkit` from `https://github.com/acme/toolkit`).
+
+Execute the following fetches, writing output as markdown files to the staging directory. **If any individual fetch fails, log a warning and continue with the others:**
+
+1. **Issues (last 100):** (rationale: 100 is `gh issue list`'s default max-per-page; a single paginated call captures recent activity without extra round trips or rate-limit pressure)
+
+   ```bash
+   gh issue list -R {owner}/{repo} --state all --limit 100 --json number,title,state,labels,createdAt,closedAt,body | ...
+   ```
+
+   Write to `{staging}/issues.md` — format as a markdown document with one section per issue (number, title, state, labels, body summary).
+
+2. **Merged PRs (last 100):** (rationale: same 100-per-page convention as issues — captures the most recent merges in one API call)
+
+   ```bash
+   gh pr list -R {owner}/{repo} --state merged --limit 100 --json number,title,mergedAt,labels,body | ...
+   ```
+
+   Write to `{staging}/prs.md` — format as a markdown document with one section per PR.
+
+3. **Releases (last 10):** (rationale: release notes accumulate slowly relative to issues/PRs; the most recent 10 tags cover roughly the last 6-18 months of changelog-relevant history for typical OSS projects, which is enough context for T2-past annotations without fanning out to dozens of `gh release view` calls)
+
+   **Note:** `gh release list --json` does **not** support the `body` field. Use a two-step approach: list tags first, then fetch each release individually with `--json` (which IS supported on `gh release view`).
+
+   ```bash
+   # Step 1: Get release tags (body NOT available here)
+   gh release list -R {owner}/{repo} --limit 10 --json tagName,name,publishedAt
+   ```
+
+   If Step 1 returns an empty array (no releases), skip Step 2 and omit the releases section entirely.
+
+   ```bash
+   # Step 2: For EACH tagName from Step 1, fetch the full release
+   gh release view {tagName} -R {owner}/{repo} --json tagName,name,publishedAt,body
+   ```
+
+   Iterate over every `tagName` from Step 1's JSON array. **Append each release to `{staging}/releases.md` immediately after its `gh release view` call returns** — do not buffer the entire loop in memory and write once at the end. The append-per-release pattern guarantees that a mid-loop abort (rate limit, network drop, user interrupt) leaves a partial but well-formed `releases.md` with every release fetched so far, rather than discarding all of them because the loop didn't reach its final write.
+
+   Write an empty `{staging}/releases.md` with a header (`# Releases (partial if interrupted)`) before the loop, then append one `## {tagName} — {name} ({publishedAt})` section per successful fetch. Failed individual fetches get a one-line placeholder: `## {tagName} — fetch failed: {error}`.
+
+   If `gh release view` fails for a specific tag, log a warning and skip that release — continue with remaining tags. If a rate limit (HTTP 429) is hit, stop the release loop, keep the partial `releases.md` file in place (do NOT delete it), and log: "Release fetch stopped at tag {N}/{total} due to rate limiting — partial releases.md retained."
+
+   Format each section as a markdown block with tag, name, date, and body.
+
+4. **Changelog (if exists):**
+
+   Check if `CHANGELOG.md` or `RELEASES.md` exists in the repository root:
+
+   ```bash
+   gh api repos/{owner}/{repo}/contents/CHANGELOG.md --jq '.content' | base64 -d
+   ```
+
+   If found, write to `{staging}/changelog.md`. If not found (404), skip silently.
+
+#### 3b. Targeted Function Searches (Uses Extraction Inventory)
+
+After the generic fetches above, perform **targeted searches** using the top-level public API function names from `extraction_inventory.top_exports[]`. This produces high-signal results that generic list fetches miss.
+
+**Short-circuit on empty `top_exports`:** If `extraction_inventory.top_exports` is missing or `== []` (docs-only mode, or a source extraction that produced zero public exports), skip this sub-section entirely with a one-line log: "No exports in inventory — skipping targeted function searches." The generic fetches from §3 remain in place and continue to provide baseline temporal context.
+
+**Limit:** Search the top **10 function names** maximum to control API call volume and avoid `gh` rate limiting. (rationale: 10 targeted searches + generic fetches from §3 stays well under GitHub's unauthenticated search rate limit of 10 requests/minute and authenticated 30/minute; matches the `top_exports[]` size emitted by step-03 §5 so every tracked export gets one search.)
+
+For each function name in `top_exports[]` (up to 10), **sanitize first**: strip every character that is not in `[A-Za-z0-9_]` from `function_name` to produce `safe_name`. This prevents shell injection and `gh` query parser errors when an export name contains punctuation (e.g., `<T>`, `.method`, `::namespace`, quotes). If `safe_name` is empty after sanitization (the original was entirely punctuation — rare but possible for symbol exports), fall back to piping the original name through stdin via `--query-from-file -`-style indirection if your `gh` version supports it; otherwise skip that one entry with a log line — never substitute the unsanitized name back into the shell command.
+
+```bash
+# safe_name = re.sub(r'[^A-Za-z0-9_]', '', function_name); skip if empty
+# --limit 5: top-5 issues per function keeps signal-to-noise high (most matches
+# below rank 5 are typically keyword coincidences, not targeted discussions) and
+# caps the total response size across 10 function fan-outs at 50 issues.
+gh search issues --repo {owner}/{repo} "{safe_name}" --limit 5 --json number,title,state,body
+```
+
+Aggregate all targeted search results into a single file: `{staging}/targeted-issues.md`. Format as a markdown document with one section per function name, listing the matching issues/PRs found.
+
+**If `gh search` is unavailable** (older `gh` CLI versions): skip targeted searches silently. The generic fetches from section 3 still provide baseline temporal context.
+
+**If rate limiting occurs** (HTTP 429 or similar): stop targeted searches immediately, keep results collected so far. Log: "Targeted search stopped at function {N}/{total} due to rate limiting."
+
+**After all fetching,** verify at least one file was written to the staging directory. If the staging directory is empty (all fetches failed), log a warning and skip to section 5.
+
+### 4. Index Into QMD & Register
+
+**Index the staging directory:**
+
+If a `{skill-name}-temporal` collection already exists, remove and recreate for atomic replace. **Wrap the remove + add pair with rollback on `add` failure** — a `remove` that succeeds followed by an `add` that fails must not leave the registry claiming a collection that no longer exists in QMD:
+
+```bash
+qmd collection remove {skill-name}-temporal
+if ! qmd collection add {project-root}/_bmad-output/{skill-name}-temporal/ --name {skill-name}-temporal --mask "*.md"; then
+  # add failed after remove succeeded — the collection is gone from QMD. Clean the registry too.
+  # Remove any {skill-name}-temporal entry from forge-tier.yaml qmd_collections[].
+  # Warn the user, do not fail the workflow (temporal enrichment degrades gracefully).
+  echo "WARN: qmd add failed after remove — registry entry for {skill-name}-temporal removed to keep forge-tier.yaml consistent with QMD state."
+  # [skip the embed step]
+else
+  qmd embed --collection {skill-name}-temporal
+fi
+```
+
+**Rollback rule:** if the `qmd collection add` step fails (non-zero exit, network error, parse error) AND the prior `remove` succeeded, the canonical registry entry in `forge-tier.yaml` MUST be removed to match QMD's actual state. A dangling registry entry that points at a non-existent QMD collection poisons subsequent cache-hit checks in §2. Emit a warning in evidence-report and skip the embed — enrichment degrades to no-QMD for this run.
+
+**Scope the embed:** Always pass `--collection {skill-name}-temporal` to `qmd embed`. An unscoped `qmd embed` re-embeds every collection in the QMD store, which can take minutes per run in batch mode and generates wasteful GPU/API cost. If the installed `qmd` CLI does not accept `--collection` (older upstream versions), gate the embed behind a per-skill check: if a previous `{skill-name}-temporal` entry already exists in `qmd_collections` and its `created_at` is within 24 hours, skip the embed entirely and warn "qmd embed skipped — upstream qmd lacks --collection scope; re-embedding all collections would be wasteful in batch mode". Log the skip in the evidence report.
+
+**Note:** `qmd embed` generates vector embeddings required for semantic (`type:'vec'`) and HyDE (`type:'hyde'`) sub-queries inside the QMD `query` tool. Without embeddings, only BM25 (`type:'lex'`) keyword search works. Run `qmd embed` after every `qmd collection add`.
+
+**Update the registry** in `forge-tier.yaml` under a file lock to prevent concurrent batch runs from clobbering each other's entries:
+
+1. Acquire an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock` (create the lock file if absent). Use `flock -x {lockfile} -c "..."` or an equivalent `fcntl.flock(LOCK_EX)` guard.
+2. Read the current `forge-tier.yaml`, capturing its `st_mtime` as `mtime_before`.
+3. Perform the read-modify-write below.
+4. Write via `python3 {atomicWriteHelper} write --target {sidecar_path}/forge-tier.yaml`.
+5. Release the flock.
+
+**Fallback when `flock` is unavailable:** re-stat the file after the write; if the on-disk `st_mtime` is newer than `mtime_before` by more than this run's own write timestamp, halt with "forge-tier.yaml modified mid-update by another process — refusing to clobber. Re-run after the other run completes." This read-CAS-by-mtime is the belt-and-braces safety net for environments without `flock`.
+
+If an entry with `name: "{skill-name}-temporal"` already exists in `qmd_collections`, replace it. Otherwise, append:
+
+```yaml
+  - name: "{skill-name}-temporal"
+    type: "temporal"
+    source_workflow: "create-skill"
+    skill_name: "{skill-name}"
+    created_at: "{current ISO date}"
+```
+
+**Clean up** the staging directory after successful indexing:
+
+```bash
+rm -rf {project-root}/_bmad-output/{skill-name}-temporal/
+```
+
+**Error handling:**
+
+- If QMD indexing fails: log the error, note that temporal enrichment will be unavailable. Do NOT fail the workflow.
+- If registry update fails: log the error, continue. The collection may exist in QMD even if the registry entry failed.
+- If cleanup fails: log a warning and continue.
+
+Display brief confirmation:
+
+"**Temporal context indexed.** Collection `{skill-name}-temporal` created ({file_count} files: {list files}). Proceeding to enrichment..."
+
+### 5. Menu Handling Logic
+
+**Auto-proceed step — no user interaction.**
+
+After temporal context is fetched and indexed (or skipped for any reason), immediately load, read entire file, then execute `{nextStepFile}`.
+
+#### EXECUTION RULES:
+
+- This is an auto-proceed step with no user choices
+- Quick/Forge/Forge+ tiers skip directly to next step with no output
+- Non-GitHub sources skip directly to next step with no output
+- Cached collections (< 7 days old) skip with brief cache-hit message
+- Deep tier with fresh fetch displays brief confirmation then auto-proceeds
+- All failures degrade gracefully — skip and auto-proceed
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN temporal context is indexed into QMD (or the step is skipped due to eligibility, cache, or failure) will you proceed to load `{nextStepFile}` for documentation fetch.
+

package/src/{workflows/create-skill/steps-c → skf-create-skill/steps-c/sub}/step-03c-fetch-docs.md

@@ -1,7 +1,11 @@
 ---
-name: 'step-03c-fetch-docs'
-description: 'Fetch remote documentation from URLs for T3-confidence content — all tiers, tool-agnostic'
-nextStepFile: './step-04-enrich.md'
+nextStepFile: '../step-04-enrich.md'
+# Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
+# (installed SKF module path first, src/ dev-checkout fallback); first existing
+# path wins. HALT if neither resolves.
+atomicWriteProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
+  - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 ---
 
 # Step 3c: Fetch Remote Documentation
@@ -10,42 +14,12 @@ nextStepFile: './step-04-enrich.md'
 
 Fetch remote documentation from brief-specified URLs using whatever web fetching capability is available in the agent's environment, extract API information, and add T3-confidence content to the extraction inventory. Tool-agnostic — the agent uses Firecrawl, WebFetch, web-reader, curl, or any available web tool.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
+## Rules
 
-### Universal Rules:
-
-- CRITICAL: Read the complete step file before taking any action
-- ALWAYS follow the exact instructions in the step file
-- TOOL/SUBPROCESS FALLBACK: If any instruction references a tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- You are a skill compilation engine fetching external documentation for T3 enrichment
-- Doc fetching is best-effort — individual URL failures never block the workflow
-- Graceful degradation is paramount — if no web fetching tools are available, skip with a warning and proceed
-
-### Step-Specific Rules:
-
-- No tier gate — this step runs at any tier when `doc_urls` are present in the brief
-- Tool-agnostic — use whatever web fetching capability is available (Firecrawl, WebFetch, web-reader, curl, browser tools, etc.)
-- FORBIDDEN to halt the workflow if web fetching is unavailable or fails
-- FORBIDDEN to override existing T1, T1-low, or T2 extraction data with T3 content
-- FORBIDDEN to begin compilation — that is step-05
-
-## EXECUTION PROTOCOLS:
-
-- Follow MANDATORY SEQUENCE exactly
-- Every extracted item receives a T3 confidence citation: `[EXT:{url}]`
-- Merge doc-fetch results into the extraction inventory per the conflict rule in section 5
-- Do NOT hallucinate content — if information is not in the fetched text, exclude it
-
-## CONTEXT BOUNDARIES:
-
-- Available: brief_data (including `doc_urls`, `source_type`), tier, extraction_inventory from step-03
-- Focus: Fetching external documentation and producing T3-confidence extraction items
-- Limits: Do NOT modify existing T1/T1-low/T2 items, begin enrichment, or compile content
-- Dependencies: Step-03 extraction must be complete (even if inventory is empty for docs-only briefs)
+- No tier gate — runs at any tier when `doc_urls` are present in the brief
+- Tool-agnostic — use whatever web fetching capability is available
+- Do not halt the workflow if web fetching is unavailable or fails
+- Do not override existing T1, T1-low, or T2 extraction data with T3 content
 
 ## MANDATORY SEQUENCE
 
@@ -108,7 +82,7 @@ If neither trigger fires, keep the page content as-is and do NOT trigger subpage
    - Crawl: if a crawl tool is available, use it with depth=1 on the root URL
    - If no discovery tool is available, keep the root page content as-is and continue
 
-2. **Filter discovered URLs by relevance:** From the discovered subpage list, select the most relevant pages by searching for API-related terms in the URL path or title (e.g., `api`, `reference`, `quickstart`, `setup`, `config`, `getting-started`, `guide`, `sdk`, `methods`, `functions`). Exclude pages that are clearly non-API content (e.g., `blog`, `changelog`, `pricing`, `about`, `careers`).
+2. **Filter discovered URLs by relevance and origin:** Restrict candidates to the same **registrable domain** as the root URL — strip the URL down to its eTLD+1 (e.g., for root `https://docs.example.com/intro`, accept any subdomain of `example.com` such as `api.example.com` or `docs.example.com`, but reject `example.org` or `cdn.partner.io`). Cross-origin links must be discarded before any fetch. The same-registrable-domain rule prevents Mintlify/Docusaurus link clouds from pulling in tracking pixels, doc-site CDNs, or third-party embeds as if they were canonical docs. From the surviving same-domain candidates, select the most relevant pages by searching for API-related terms in the URL path or title (e.g., `api`, `reference`, `quickstart`, `setup`, `config`, `getting-started`, `guide`, `sdk`, `methods`, `functions`). Exclude pages that are clearly non-API content (e.g., `blog`, `changelog`, `pricing`, `about`, `careers`).
 
 3. **Fetch top subpages:** Fetch up to **10** of the most relevant subpages. For each:
    - Use the same web fetching tool as the root URL
@@ -141,6 +115,8 @@ Parse the successfully fetched markdown for:
 
 **Conflict rule:** T3 items NEVER override existing T1, T1-low, or T2 items for the same export. When an export already has a higher-confidence entry, the T3 item is discarded. T3 has the lowest priority.
 
+**Edge case — T1-zero supplemental mode:** If T1 extraction produced zero results and `doc_urls` are present in supplemental mode, T3 items should be used as the primary inventory since no T1 data exists to conflict with.
+
 **Aggregate totals for reporting:**
 - URLs fetched successfully vs. total
 - URLs that failed
@@ -153,9 +129,9 @@ Parse the successfully fetched markdown for:
 **If tier is Deep and at least one URL was fetched successfully:**
 
 1. Write fetched markdown files to a staging directory: `_bmad-output/{skill-name}-docs/`
-2. Index into QMD: `qmd collection add {project-root}/_bmad-output/{skill-name}-docs/ --name {skill-name}-docs --mask "*.md"`
-3. Generate embeddings: `qmd embed` (required for `vector_search` and `deep_search`)
-4. Register in forge-tier.yaml `qmd_collections` array:
+2. Index into QMD with atomic replace + rollback: if a `{skill-name}-docs` collection already exists, run `qmd collection remove {skill-name}-docs` first, then `qmd collection add {project-root}/_bmad-output/{skill-name}-docs/ --name {skill-name}-docs --mask "*.md"`. **If `qmd collection add` fails after a successful `remove`:** remove any matching `{skill-name}-docs` entry from `forge-tier.yaml` → `qmd_collections[]` to keep the registry consistent with QMD's actual state, warn in evidence-report, and skip the embed — docs enrichment degrades gracefully.
+3. Generate embeddings scoped to this collection (only if step 2 `add` succeeded): `qmd embed --collection {skill-name}-docs` (required for semantic `type:'vec'` and HyDE `type:'hyde'` sub-queries within the QMD `query` tool). If the installed `qmd` CLI does not accept `--collection`, gate the embed behind a freshness check: skip re-embedding if the existing `{skill-name}-docs` registry entry is within 24 hours, and log the skip in the evidence report to prevent unbounded batch-mode re-embedding.
+4. Register in forge-tier.yaml `qmd_collections` array — **acquire an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock` for the read-modify-write** (see the locking pattern documented in step-03b §4). Write via `python3 {atomicWriteHelper} write --target {sidecar_path}/forge-tier.yaml`. If `flock` is unavailable, fall back to read-CAS-by-mtime (capture `st_mtime` before, re-check after; refuse to clobber if a concurrent run wrote in between).
 
 ```yaml
 - name: "{skill-name}-docs"

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

@@ -0,0 +1,64 @@
+---
+name: skf-create-stack-skill
+description: Consolidated project stack skill with integration patterns — code-mode (analyzes manifests) or compose-mode (synthesizes from existing skills + architecture doc). Use when the user requests to "create a stack skill."
+---
+
+# Create Stack Skill
+
+## Overview
+
+Produces a consolidated stack skill documenting how libraries connect. **Code-mode** analyzes dependency manifests and co-import patterns from actual source code. **Compose-mode** synthesizes from pre-generated individual skills and architecture documents when no codebase exists yet. Every finding must trace to actual code with file:line citations; in compose-mode, inferred integrations are permitted but must be labeled `[inferred from shared domain]`.
+
+## Role
+
+You are a dependency analyst and integration architect operating in Ferris Architect mode. You bring expertise in dependency analysis, cross-library integration patterns, and compositional architecture, while the user brings their project knowledge and scope preferences.
+
+## Workflow Rules
+
+These rules apply to every step in this workflow:
+
+- Zero hallucination — all extracted content must trace to actual source code (compose-mode inferences must be labeled)
+- Read each step file completely before taking any action
+- Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
+- Only load one step file at a time — never preload future steps
+- If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
+- Always communicate in `{communication_language}`
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+- **Workflow state contract — `workflow_warnings[]` accumulator (M4):** every step that emits a warning ("log a warning", "record in workflow state for the evidence report", "Warning: ...", etc.) MUST append 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-07 surfaces these in `evidence-report.md`; step-08 may add validation findings; step-09 §5 reads the accumulated list and renders the user-facing "Warnings" section. Do not invent a per-step warning channel — there is exactly one accumulator for the whole workflow.
+
+## Stages
+
+| # | Step | File | Auto-proceed |
+|---|------|------|--------------|
+| 1 | Initialize & Mode Detection | steps-c/step-01-init.md | No (confirm) |
+| 2 | Detect Manifests | steps-c/step-02-detect-manifests.md | Yes |
+| 3 | Rank & Confirm Libraries | steps-c/step-03-rank-and-confirm.md | No (confirm) |
+| 4 | Parallel Extract | steps-c/step-04-parallel-extract.md | Yes |
+| 5 | Detect Integrations | steps-c/step-05-detect-integrations.md | Yes |
+| 6 | Compile Stack | steps-c/step-06-compile-stack.md | No (review) |
+| 7 | Generate Output | steps-c/step-07-generate-output.md | Yes |
+| 8 | Validate | steps-c/step-08-validate.md | Yes |
+| 9 | Report | steps-c/step-09-report.md | Yes |
+| 10 | Workflow Health Check | steps-c/step-10-health-check.md | Yes |
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | project_path [required], mode (code/compose) [auto-detected] |
+| **Gates** | step-03: Confirm Gate [C] | step-06: Review Gate [C] |
+| **Outputs** | SKILL.md (stack), context-snippet.md, metadata.json |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
+   - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `skills_output_folder`, `forge_data_folder`, `sidecar_path`
+
+2. **Resolve `{headless_mode}`** with explicit precedence (B2):
+   1. **Explicit disable wins.** If `--headless=false` or `--no-headless` was passed, `{headless_mode}` is `false` regardless of any preference.
+   2. **Explicit enable next.** If `--headless` or `-H` was passed (without `=false`), `{headless_mode}` is `true`.
+   3. **Preferences fallback.** Otherwise, read `headless_mode` from `{sidecar_path}/preferences.yaml` (`true` or `false`).
+   4. **Default:** `false`.
+
+3. Load, read the full file, and then execute `./steps-c/step-01-init.md` to begin the workflow.

package/src/{workflows/create-stack-skill/data → skf-create-stack-skill/assets}/stack-skill-template.md

@@ -69,7 +69,8 @@ Indexed format targeting ~80-120 tokens per stack:
   "name": "{project}-stack",
   "version": "1.0.0",
   "generation_date": "{ISO-8601}",
-  "confidence_tier": "{Quick|Forge|Forge+|Deep}",
+  "forge_tier": "{Quick|Forge|Forge+|Deep}",
+  "confidence_tier": "{T1|T1-low|T2|T3}",
   "spec_version": "1.3",
   "source_authority": "{official|community|internal}",
   "generated_by": "create-stack-skill",

package/src/{workflows/create-stack-skill/data → skf-create-stack-skill/references}/compose-mode-rules.md

@@ -4,7 +4,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](../../../knowledge/version-paths.md) for the full path templates and resolution rules.
+Skills use version-nested directories — see `knowledge/version-paths.md` for the full path templates and resolution rules.
 
 **Version-aware skill enumeration:**
 
@@ -17,6 +17,16 @@ Skills use version-nested directories — see [knowledge/version-paths.md](../..
 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"`
 
+## Compose-mode Co-mention Precision
+
+Prose co-mention detection is heuristic — it can only provide `Plausible`-class evidence (compared to code-mode's co-imports, which are literal). To reduce false positives the matcher in step-05 §2 applies three guards:
+
+1. **Word-boundary matching** (`\b{skill_name}\b`, case-insensitive). Substring matches are rejected (no `react` inside `reactive`).
+2. **Section filtering.** Paragraphs under H1/H2 headers that normalise to `introduction`, `overview`, `glossary`, `table of contents`, `references`, `appendix`, or `index` are excluded — they typically enumerate all libraries without describing integration. Headings themselves are also excluded as co-mention sources.
+3. **Two-paragraph minimum.** A pair `(A, B)` requires at least two distinct body paragraphs co-mentioning both names. A single paragraph can be coincidental.
+
+**Known limitations:** even with these guards, a co-mention only witnesses that two libraries are discussed together; it does not prove an integration exists. Downstream consumers should prefer stack manifests (`skf-create-stack-skill` output) to prose-derived evidence when both are available.
+
 ## Architecture Integration Mapping
 
 **If `{architecture_doc_path}` is null or the file does not exist:** Skip this section and proceed to [Inferred Integrations (No Architecture Document)](#inferred-integrations-no-architecture-document) below.
@@ -57,10 +67,14 @@ Each integration entry must cite both source skills by name with function signat
 
 ## Feasibility Report Integration
 
-If a feasibility report (`feasibility-report-{project_name}.md`) exists in `{forge_data_folder}/`:
-- Load the VS overall verdict from the report's YAML frontmatter `overall_verdict` field (`FEASIBLE`, `CONDITIONALLY FEASIBLE`, or `NOT FEASIBLE`) and parse per-pair verdicts from the `## Integration Verdicts` markdown table (`Verified`, `Plausible`, `Risky`, or `Blocked`)
-- Include the verdict in the integration evidence: `VS overall: {FEASIBLE|CONDITIONALLY FEASIBLE|NOT FEASIBLE}`, `VS pair: {Verified|Plausible|Risky|Blocked}`
-- Flag any pairs where VS reported `Risky` or `Blocked` verdicts
+The feasibility report contract 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). Consumers MUST follow the schema verbatim:
+
+- **Filename pattern:** `{forge_data_folder}/feasibility-report-{project_slug}-{YYYYMMDD-HHmmss}.md`, with a stable `feasibility-report-{project_slug}-latest.md` copy at the same location. Use `{project_slug}` (slugified `project_name`), not raw `{project_name}`.
+- **Schema version guard:** Parse frontmatter and confirm `schemaVersion == "1.0"`. On mismatch, HALT with an explicit error; never silently proceed with an unknown version.
+- **Overall verdict tokens** (frontmatter `overallVerdict`, case-sensitive): exactly one of `FEASIBLE | CONDITIONALLY_FEASIBLE | NOT_FEASIBLE`.
+- **Per-pair verdict tokens** (in the `## Integration Verdicts` table, case-sensitive): exactly one of `Verified | Plausible | Risky | Blocked`. Any unknown token is a hard error.
+- Include the verdict in the integration evidence: `VS overall: {overallVerdict}`, `VS pair: {verdict}`.
+- Flag pairs where VS reported `Risky` or `Blocked`.
 
 ## Inferred Integrations (No Architecture Document)
 

package/src/{workflows/create-stack-skill/data → skf-create-stack-skill/references}/integration-patterns.md

@@ -57,5 +57,5 @@ Library A + Library B
   Files: [count] files with co-imports
   Key files: [top 3 files by integration density]
   Pattern: [brief description of how they integrate]
-  Confidence: [T1/T1-low based on detection method]
+  Confidence: [weaker of the two libraries' tiers from per_library_extractions[], with detection-method qualifier in parens — e.g., `T1-low (grep-co-import)`, `T1 (ccc-augmented)`, `T1-low (architecture-co-mention) [composed]`. Integration detection is grep + co-import, never AST — do not label integrations "AST-verified".]
 ```

package/src/{workflows/create-stack-skill/data → skf-create-stack-skill/references}/manifest-patterns.md

@@ -2,16 +2,16 @@
 
 ## Supported Ecosystems
 
-| Ecosystem | Manifest File(s) | Dependency Key | Import Pattern |
-|-----------|-----------------|----------------|----------------|
-| JavaScript/TypeScript | package.json | dependencies, devDependencies | `import ... from '...'`, `require('...')` |
-| Python | requirements.txt, setup.py, pyproject.toml, Pipfile | install_requires, [project.dependencies] | `import ...`, `from ... import` |
-| Rust | Cargo.toml | [dependencies] | `use ...`, `extern crate` |
-| Go | go.mod | require | `import "..."` |
-| Java | pom.xml, build.gradle | dependencies | `import ...` |
-| Ruby | Gemfile | gem | `require '...'`, `require_relative` |
-| PHP | composer.json | require, require-dev | `use ...`, `require_once` |
-| .NET | *.csproj | PackageReference | `using ...` |
+| Ecosystem             | Manifest File(s)                                    | Dependency Key                           | Import Pattern                            |
+|-----------------------|-----------------------------------------------------|------------------------------------------|-------------------------------------------|
+| JavaScript/TypeScript | package.json                                        | dependencies, devDependencies            | `import ... from '...'`, `require('...')` |
+| Python                | requirements.txt, setup.py, pyproject.toml, Pipfile | install_requires, [project.dependencies] | `import ...`, `from ... import`           |
+| Rust                  | Cargo.toml                                          | [dependencies]                           | `use ...`, `extern crate`                 |
+| Go                    | go.mod                                              | require                                  | `import "..."`                            |
+| Java                  | pom.xml, build.gradle                               | dependencies                             | `import ...`                              |
+| Ruby                  | Gemfile                                             | gem                                      | `require '...'`, `require_relative`       |
+| PHP                   | composer.json                                       | require, require-dev                     | `use ...`, `require_once`                 |
+| .NET                  | *.csproj                                            | PackageReference                         | `using ...`                               |
 
 ## Detection Priority
 

package/src/{workflows/create-stack-skill → skf-create-stack-skill}/steps-c/step-01-init.md

@@ -1,7 +1,4 @@
 ---
-name: 'step-01-init'
-description: 'Initialize stack skill workflow by loading forge tier and validating prerequisites'
-
 nextStepFile: './step-02-detect-manifests.md'
 forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 ---
@@ -12,43 +9,25 @@ forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 
 Load forge tier configuration, validate prerequisites, and prepare the stack skill workflow for execution.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+## Rules
 
-### Role Reinforcement:
+- Focus only on loading configuration and validating prerequisites — do not start analyzing dependencies
 
-- ✅ You are a dependency analyst and integration architect operating in Ferris Architect mode
-- ✅ Execute with prescriptive precision — every finding must trace to actual code
-- ✅ Speed-first approach with zero hallucination
-
-### Step-Specific Rules:
+## MANDATORY SEQUENCE
 
-- 🎯 Focus ONLY on loading configuration and validating prerequisites
-- 🚫 FORBIDDEN to start detecting manifests or analyzing dependencies
-- 🚫 No A/P menu — this is an auto-proceed init step
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
 
-## EXECUTION PROTOCOLS:
+### 0. Validate Project Config
 
-- 🎯 Load forge tier and validate tools
-- 💾 Store tier, tools, and optional inputs as workflow state
-- 📖 Auto-proceed to next step after successful initialization
-- 🚫 HALT with actionable error if prerequisites missing
+Before anything else, load `{project-root}/_bmad/skf/config.yaml`. If the file is missing OR fails YAML parse OR lacks the required top-level keys (`project_name`, `output_folder`, `skills_output_folder`, `forge_data_folder`, `sidecar_path`), HALT with:
 
-## CONTEXT BOUNDARIES:
+"**Cannot proceed.** SKF is not initialized for this project (config.yaml missing or malformed).
 
-- This is the first step — no prior workflow state exists
-- Requires setup-forge to have been completed (forge-tier.yaml)
-- User may provide optional explicit dependency list or scope overrides
-- No dependencies on brief-skill or create-skill outputs
+**Required:** Run `skf init` first.
 
-## MANDATORY SEQUENCE
+**Halting workflow.**"
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+STOP — do not proceed.
 
 ### 1. Load Forge Tier Configuration
 
@@ -56,9 +35,9 @@ Load `{forgeTierFile}` from the Ferris sidecar.
 
 **If forge-tier.yaml does not exist:**
 
-"**Cannot proceed.** The setup-forge workflow has not been run for this project.
+"**Cannot proceed.** The setup workflow has not been run for this project.
 
-**Required:** Run `setup-forge` first to detect available tools and determine your forge tier.
+**Required:** Run `setup` first to detect available tools and determine your forge tier.
 
 **Halting workflow.**"
 
@@ -84,7 +63,7 @@ Extract:
 - **Forge+:** ast_bridge + ccc_bridge (ccc semantic co-import augmentation) — ccc available for step-05
 - **Deep:** qmd_bridge (QMD temporal enrichment) — required for Deep tier
 
-See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md) for how each bridge name resolves to concrete tools per IDE environment.
+See `knowledge/tool-resolution.md` for how each bridge name resolves to concrete tools per IDE environment.
 
 Report tool availability. If a tier-required tool is missing, downgrade tier and note:
 
@@ -106,7 +85,7 @@ Check if the user provided:
 
 Set `compose_mode: false` as the default.
 
-Skills use version-nested directories — see [knowledge/version-paths.md](../../../knowledge/version-paths.md) for the full path templates and resolution rules.
+Skills use version-nested directories — see `knowledge/version-paths.md` for the full path templates and resolution rules.
 
 - If user provides an architecture document path for composition or explicitly requests compose mode → set `compose_mode: true` and store `architecture_doc_path`
 - If no manifest files exist in project root AND at least one skill is discoverable in `{skills_output_folder}` → suggest compose mode to the user and ask for optional architecture document path
@@ -142,23 +121,3 @@ Where tier_description follows positive capability framing:
 
 Load, read the full file and then execute `{nextStepFile}`.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Forge tier loaded and validated
-- Tool availability confirmed with tier adjustment if needed
-- Optional inputs accepted and stored
-- Initialization summary displayed with positive capability framing
-- Auto-proceeded to step 02
-
-### ❌ SYSTEM FAILURE:
-
-- Proceeding without forge-tier.yaml
-- Not reporting tier adjustments when tools missing
-- Starting manifest detection in this step
-- Displaying A/P menu (this is auto-proceed)
-
-**Master Rule:** This step validates prerequisites and initializes state. No analysis, no detection, no extraction.