bmad-module-skill-forge 1.8.0 → 2.0.0

package/src/skf-test-skill/references/score.md

@@ -20,13 +20,16 @@ Load `{scoringRulesFile}` to get:
 - Category weights (naive vs contextual distribution)
 - Tier-dependent scoring adjustments
 
-**Resolve the pass threshold (precedence: CLI > scalar > bundled fallback):**
+**Resolve the pass threshold (precedence: CLI > pipeline default > scalar > bundled fallback):**
 
-1. If the workflow received `--threshold=<N>` on invocation, use that integer as `effective_threshold` (CLI wins).
-2. Else if the resolved `{defaultThreshold}` workflow-context variable (from SKILL.md On Activation §3 — `workflow.default_threshold` scalar, default `80`) is set, use it as `effective_threshold`.
-3. Else fall back to `80` (the bundled default — this branch should be unreachable when SKILL.md resolution ran correctly, but keeps the step robust if customize.toml resolution failed silently).
+1. If the workflow received `--threshold=<N>` on invocation, use that integer as `effective_threshold` (CLI wins). Set `threshold_source` = `"CLI override ({N}%)"`.
+2. Else if `{pipeline_default_threshold}` is set in workflow context (resolved by init.md §1b from the per-pipeline threshold lookup table when `{pipeline_alias}` is present), use it as `effective_threshold`. Set `threshold_source` = `"pipeline default ({pipeline_alias} → {N}%)"`.
+3. Else if the resolved `{defaultThreshold}` workflow-context variable (from SKILL.md On Activation §3 — `workflow.default_threshold` scalar, default `80`) is set, use it as `effective_threshold`. Set `threshold_source` = `"workflow default ({N}%)"`.
+4. Else fall back to `80` (the bundled default — this branch should be unreachable when SKILL.md resolution ran correctly, but keeps the step robust if customize.toml resolution failed silently). Set `threshold_source` = `"bundled fallback (80%)"`.
 
-Pass `effective_threshold` into the scoring-input JSON's `threshold` field in §3a (the compute-score.py script already honors this field). The CLI flag and the scalar feed the same downstream field; the script does not need to know which layer supplied the value.
+Store `threshold_source` in workflow context for use in the score report section.
+
+Pass `effective_threshold` into the scoring-input JSON's `threshold` field in §3a (the compute-score.py script already honors this field). The CLI flag, pipeline default, and the scalar all feed the same downstream field; the script does not need to know which layer supplied the value.
 
 **Docs-only mode check:** If the Coverage Analysis section in `{outputFile}` notes docs-only mode (set by step 3 for skills with all `[EXT:...]` citations and no local source), apply Quick-tier weight redistribution: Signature Accuracy and Type Coverage are not scored, their weights (22% + 14%) are redistributed proportionally to remaining active categories. Coverage score is based on documentation completeness rather than source coverage (as calculated by step 3).
 
@@ -82,7 +85,7 @@ Build a JSON object from the data gathered in steps 1-2:
     "coherence": "{combined_coherence_percentage or null if naive mode}",
     "externalValidation": "{external_validation_score or null if N/A}"
   },
-  "threshold": "{effective_threshold from §1 — CLI --threshold wins, then workflow.default_threshold scalar, then 80}"
+  "threshold": "{effective_threshold from §1 — CLI --threshold wins, then pipeline default, then workflow.default_threshold scalar, then 80}"
 }
 ```
 
@@ -150,6 +153,85 @@ IF score < threshold        → FAIL
 
 **Tooling-degraded cap:** If the `analysisConfidence` in output frontmatter is `degraded` (python3 missing, frontmatter validator missing, or other degraded state flagged in step 1), the step MUST cap the score at `threshold - 1` BEFORE the PASS/FAIL comparison. This forces a deterministic FAIL until tooling is restored. Do NOT override an INCONCLUSIVE result with the cap — INCONCLUSIVE remains the verdict.
 
+### 4b. Threshold Fallback and Evidence Report
+
+After §4 determines the result but before §5 recommends the next workflow, check whether a threshold fallback applies. The fallback converts a FAIL into a PASS at the 80% floor when the score is between 80% and the effective threshold, and documents the quality compromise in an evidence report.
+
+**Fallback trigger conditions:**
+
+```
+IF result == "FAIL"
+  AND totalScore >= 80
+  AND effective_threshold > 80
+THEN
+  → THRESHOLD FALLBACK triggered
+```
+
+**Do NOT trigger fallback when:**
+- `result == "INCONCLUSIVE"` — the evidence-floor verdict is never overridden by fallback
+- `totalScore < 80` — that is a genuine FAIL (floor not met)
+- `effective_threshold == 80` — there is nothing to fall back from
+
+**When fallback triggers:**
+
+1. Record `threshold_fallback: true`, `original_threshold: {effective_threshold}`, `fallback_threshold: 80` in workflow context.
+2. Override `result` to `"PASS"`.
+3. Set `effective_threshold = 80` for use by §5/§6/§7/§8.
+4. Generate the evidence report (§4b.1 below).
+
+#### 4b.1 Generate Evidence Report
+
+Write the evidence report to `{forge_version}/evidence-report-fallback.md`. The report documents the quality compromise for audit purposes.
+
+**Read gap entries:** extract findings from the Coverage Analysis and Coherence Analysis sections in `{outputFile}` — list each gap with severity (Critical through Low).
+
+**Check for prior remediation:** glob `{forge_version}/test-report-{skill_name}-*.md` for a prior test report. If found, note the path — this implies remediation was attempted between runs. If not found, note "first test run — no prior remediation cycle".
+
+**Check for post-score cap:** if Cap 1 or Cap 2 (§3d) fired, note the cap reason in the remediation section: "Score capped due to {cap_reason} — address tooling to test at the higher threshold."
+
+**Evidence report template:**
+
+```markdown
+# Evidence Report: Threshold Fallback
+
+**Skill:** {skill_name}
+**Date:** {ISO-8601 timestamp}
+**Run ID:** {run_id}
+
+## Threshold Summary
+
+| Field | Value |
+|-------|-------|
+| Attempted Threshold | {original_threshold}% |
+| Achieved Score | {totalScore}% |
+| Threshold Source | {threshold_source} |
+| Final Accepted Threshold | 80% |
+
+## Findings Preventing Higher Threshold
+
+{For each gap entry from Coverage Analysis and Coherence Analysis:}
+- **{GAP-NNN}: {title}** — Severity: {severity}, Category: {category}
+
+{Count: N critical, M high, P medium, Q low, R info findings}
+
+## Remediation Context
+
+{If prior test report exists:}
+A prior test run was found at `{prior_report_path}`, indicating remediation was attempted between runs.
+
+{If no prior test report:}
+No prior test report found for this skill version — this is the first test run.
+
+{If post-score cap was active:}
+**Note:** Score was capped due to {cap_reason}. Address tooling limitations to test at the higher threshold.
+
+## Conclusion
+
+Skill accepted at 80% floor (original target: {original_threshold}%). The {N} findings above prevented meeting the higher threshold. Review and address findings before the next pipeline run to achieve the {original_threshold}% target.
+```
+
+Record `evidence_report_path: '{forge_version}/evidence-report-fallback.md'` in workflow context for use by §6/§7/§8 and by report.md.
+
 ### 5. Determine Next Workflow Recommendation
 
 Based on test result:
@@ -203,6 +285,9 @@ Append the **Completeness Score** section to `{outputFile}`:
 **Inconclusive Reasons:**
 {bulleted list from script `inconclusiveReasons`}
 
+**Threshold Source:** {threshold_source}
+{If threshold_fallback is true:}
+**Threshold Fallback:** scored {totalScore}% against {original_threshold}% target — accepted at 80% floor. Evidence report: {evidence_report_path}
 **Weight Distribution:** {naive (redistributed) | contextual (full)}
 **Tier Adjustment:** {none | Quick tier — signature and type coverage not scored}
 **External Validators:** {both available | skill-check only | tessl only | none — weight redistributed}
@@ -225,6 +310,8 @@ Update `{outputFile}` frontmatter:
 - `testResult: '{pass|pass-with-drift|fail|inconclusive}'` (lowercase; mirrors script `result`, with `pass-with-drift` substituted for `pass` when `allow_workspace_drift` was set and drift was observed — see §5 drift override)
 - `score: '{total}%'`
 - `threshold: '{threshold}%'`
+- `thresholdSource: '{threshold_source}'`
+- When `threshold_fallback` is true, add: `thresholdFallback: true`, `originalThreshold: '{original_threshold}%'`, `evidenceReportPath: '{evidence_report_path}'`
 - `analysisConfidence: '{full|degraded|provenance-map|metadata-only|remote-only|docs-only}'`
 - `nextWorkflow: '{export-skill|update-skill|manual-review}'`
 - Append `'score'` to `stepsCompleted`
@@ -244,6 +331,8 @@ Update `{outputFile}` frontmatter:
 | External Validation | {N}% | {WS}% |
 
 **Threshold:** {threshold}%
+{If threshold_fallback is true:}
+**Threshold fallback:** scored {totalScore}% against {original_threshold}% target — accepted at 80% floor. Evidence report: {evidence_report_path}
 **Recommendation:** {export-skill if pass | update-skill if fail}
 
 **Proceeding to gap report...**"

package/src/skf-test-skill/references/source-access-protocol.md

@@ -41,14 +41,14 @@
 
   Leave `analysis_confidence` unchanged (still `full` or `provenance-map` per the waterfall) — stratified scope does not degrade confidence, only the denominator. Annotate the coverage report with: `Stratified scope — denominator: {effective_denominator | tier_a_include union | scope.include union} ({N} files matched, {M} exports union)`.
 
-  **When this clause does NOT apply:** `scope.type: "full-library"` skills, single-package repositories, or stratified briefs where the full monorepo is intentionally in scope. For those, use the standard barrel-based denominator — **unless** the single-package repo is a pattern-reference app (see next bullet).
+  **When this clause does NOT apply:** `scope.type: "full-library"` skills, single-package repositories, or stratified briefs where the full monorepo is intentionally in scope. For those, use the standard barrel-based denominator — **unless** the single-package repo is a pattern-reference app (see next bullet) or publishes a multi-subpath `exports` map (use the multi-entry clause below).
 
 - **Pattern-reference apps (non-library source):** If the source is a single-package repo whose purpose is demonstrating an integration pattern rather than distributing a library API — typical markers are `scope.type: "full-library"` **without** a barrel file at any recognized entry-point path (`__init__.py`, `index.ts`/`index.js`, `lib.rs`, `mod.rs`) AND without a monorepo layout — the skill's value lives in wiring patterns, not exports. None of the preceding three clauses fits: there is no barrel to count from, no empty-barrel `scope.include` to consult, and no monorepo stratification to re-derive.
 
   **Trigger (either fires):**
 
   1. `scope.notes` in `forge-data/{skill_name}/skill-brief.yaml` flags pattern-reference intent (phrases such as "Reference app, not a library", "pattern-reference", "embedded-pattern skill", or "skill value is the … pattern"). The `scope.notes` field is authoritative when the author wrote it.
-  2. Source tree lacks a barrel file at every recognized entry-point path AND the repo is not a monorepo (no `packages/`, `workspaces`, `lerna.json`, `rush.json`, `nx.json`, or Cargo `[workspace]`). Detected at test time by filesystem inspection of `{source_path}`.
+  2. Source tree lacks a barrel file at every recognized entry-point path AND the repo is not a monorepo (no `packages/`, `workspaces`, `lerna.json`, `rush.json`, `nx.json`, or Cargo `[workspace]`) AND the package does not declare a multi-subpath `exports` map (those route to the multi-entry clause below). Detected at test time by filesystem inspection of `{source_path}`.
 
   **Denominator:** canonicalized provenance-map entry count (same canonicalization as the "Provenance-map canonicalization" section below). `skf-create-skill`'s extraction pass has already curated the provenance-map to the authored pattern surface; treat it as the authoritative enumeration of the skill's documented reach.
 
@@ -56,7 +56,7 @@
 
   **Confidence:** leave `analysis_confidence` unchanged (still `full` or `provenance-map` per the waterfall). Pattern-reference does not degrade confidence — the surface is smaller than a library barrel, not lower quality. Annotate the coverage report with: `Pattern-reference — denominator: {tier_a_include union | canonicalized provenance-map count} ({N} pattern surfaces)`.
 
-  **When this clause does NOT apply:** any repo with a non-empty barrel file, any monorepo (use the stratified-scope clause), or any single-package repo whose `scope.type` is explicitly `public-api` / `specific-modules` / `component-library` / `docs-only` (those scope types have their own denominator semantics). Also does NOT apply when `scope.type: "reference-app"` — that scope type carries its own pattern-surface denominator semantics (the brief speaks for itself), so this clause's filesystem trigger is moot.
+  **When this clause does NOT apply:** any repo with a non-empty barrel file, any monorepo (use the stratified-scope clause), or any single-package repo whose `scope.type` is explicitly `specific-modules` (use the specific-modules clause), `public-api` with a multi-subpath `exports` map (use the multi-entry clause below — a `public-api` package WITHOUT such a map keeps the standard root-barrel rule), `component-library`, or `docs-only`. Also does NOT apply when `scope.type: "reference-app"` — that scope type carries its own pattern-surface denominator semantics (the brief speaks for itself), so this clause's filesystem trigger is moot.
 
 - **Single-crate curated subset (`scope.type: "specific-modules"`):** If the source is a single-package (non-monorepo) repo whose skill brief sets `scope.type: "specific-modules"` and uses `scope.include`/`scope.exclude` to carve a subset of the crate's public surface, the coverage denominator is the **in-scope reachable barrel** — not the full barrel.
 
@@ -72,6 +72,16 @@
 
   **When this clause does NOT apply:** monorepo packages (use the stratified-scope clause), `scope.type: "full-library"` (use the standard barrel), or empty-barrel packages (use the empty-barrel clause). This clause is specifically for single-crate repos where the brief intentionally documents a curated subset rather than the full public surface.
 
+- **Multi-entry (exports-map) packages (single-package libraries publishing via a `package.json` `exports` map):** If the in-scope `package.json` declares an `exports` map with **multiple non-root subpath entries** (more than just `"."`) and the repo carries **no** monorepo markers (`packages/` layout, `workspaces` field, `lerna.json`, `rush.json`, `nx.json`, Cargo `[workspace]`), the package's public surface spans every published subpath, not just the root barrel. The standard "named exports from `index.ts`" rule undercounts: it measures only the `"."` barrel while installers reach the full subpath set. This clause covers both `scope.type: "full-library"` AND `scope.type: "public-api"` for such packages.
+
+  **Denominator:** the **union of named exports across the files each NON-WILDCARD `exports` subpath resolves to**. Resolve each subpath to its target file (or its committed `.d.ts` / `.d.mts` declaration), then apply the same multi-line brace-accumulation and `export *` star-resolution rules documented for barrel re-derivation earlier in this file ("TypeScript / JavaScript barrel re-derivation"). **Explicitly exclude wildcard subpaths** (`"./*"` forms — they map to an open-ended file set whose surface is unbounded and uncountable). If the `exports` map has only a root `"."` entry, or only wildcard subpaths, fall back to the standard root-barrel rule.
+
+  **Curation/priority (same ladder the specific-modules clause uses):** prefer `metadata.json.stats.effective_denominator` first (subject to the existing deflation guard), then `scope.tier_a_include` globs (filtered by `scope.exclude`, the umbrella-barrel note applies) when the brief supplies it, else the full subpath union.
+
+  **Audit:** the root-barrel named-export count MUST be reported as a **secondary candidate** in the Denominator Candidates audit block (coverage-check.md §4) so the root-barrel-vs-subpath-union choice is auditable. Annotate the coverage report with: `Multi-entry (exports-map) — denominator: {effective_denominator | tier_a_include union | subpath union} ({N} subpaths resolved, {M} exports union; root barrel: {R})`.
+
+  **When this clause does NOT apply:** monorepo packages (use the stratified-scope clause), empty-barrel packages (use the empty-barrel clause), pattern-reference apps (use the pattern-reference clause), `scope.type: "specific-modules"` (use the specific-modules clause), or single-entry / wildcard-only `exports` maps (use the standard root-barrel rule).
+
 Internal module symbols are **excluded** from the coverage denominator unless they are explicitly documented in SKILL.md (in which case they count as documented extras, not missing coverage).
 
 This matches the extraction-patterns.md convention used during skill creation: coverage measures how well SKILL.md documents what users actually import, not the entire internal codebase.

package/src/skf-test-skill/references/step-hard-gate.md

@@ -0,0 +1,73 @@
+---
+nextStepFile: 'score.md'
+outputFile: '{forge_version}/test-report-{skill_name}-{run_id}.md'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 4c: Hard Gate
+
+## STEP GOAL:
+
+Scan accumulated findings from coverage and coherence analysis for critical or high severity gaps. If any exist, block the pipeline with a clear listing of every blocking finding — no coverage score is computed or reported. If only medium, low, or info findings exist, pass through to scoring.
+
+### §1. Read Findings from Output
+
+Read `{outputFile}` and scan the **Coverage Analysis** and **Coherence Analysis** sections for GAP entries. Each GAP entry contains a severity marker in this format:
+
+```
+**Severity:** {Critical|High|Medium|Low|Info}
+```
+
+Extract every line matching `**Severity:** Critical` or `**Severity:** High`. For each match, also capture the parent GAP heading (`### GAP-{NNN}: {title}`) and the `**Source:**` line to build a blocking-findings list.
+
+### §2. Evaluate Gate
+
+**Count blocking findings** (Critical + High severity).
+
+**IF blocking findings exist → BLOCK (§3)**
+
+**IF no blocking findings → PASS (§4)**
+
+### §3. Block — Critical/High Findings Detected
+
+The hard gate blocks the pipeline. No scoring step runs.
+
+Update `{outputFile}` frontmatter:
+- Set `testResult: 'fail'`
+- Append `'hard-gate'` to `stepsCompleted`
+
+Report to the user:
+
+"**Hard gate BLOCKED — {N} critical/high finding(s) must be resolved before scoring.**
+
+| # | GAP | Severity | Source |
+|---|-----|----------|--------|
+{for each blocking finding:}
+| {i} | {GAP-NNN}: {title} | {severity} | {source} |
+
+**{M} medium/low/info findings also noted (non-blocking).**
+
+**Action required:** resolve all Critical and High findings, then re-run test-skill.
+**Recommended next step:** update-skill"
+
+**Headless envelope (if `{headless_mode}`):** emit to **stderr**:
+
+```
+SKF_TEST_RESULT_JSON: {"status":"error","skill_name":"{skill_name}","verdict":"FAIL","score":null,"threshold":null,"report_path":"{outputFile}","next_workflow":"update-skill","exit_code":2,"halt_reason":"hard-gate-blocked"}
+```
+
+HALT — do not chain to `{nextStepFile}`.
+
+### §4. Pass — No Critical/High Findings
+
+The hard gate passes. Medium, low, and info findings are documented in the gap report but do not block.
+
+Update `{outputFile}` frontmatter:
+- Append `'hard-gate'` to `stepsCompleted`
+
+Report:
+
+"**Hard gate passed** — {N} medium/low/info finding(s) noted, proceeding to scoring."
+
+Update stepsCompleted, then load and execute `{nextStepFile}`.

package/src/skf-test-skill/scripts/compute-score.py

@@ -29,8 +29,10 @@ Input schema (one object):
   }
 
 Exit codes:
-  0  — score computed (verdict may be PASS/FAIL/INCONCLUSIVE)
-  1  — input error (bad JSON, missing fields, schema violation)
+  0  — input was parsed; either a score was computed (verdict may be
+       PASS/FAIL/INCONCLUSIVE) or a schema/validation error object
+       ({"error": ..., "code": "INVALID_INPUT"}) was emitted as JSON
+  1  — input could not be parsed at all (no input provided, or malformed JSON)
 """
 
 from __future__ import annotations
@@ -381,4 +383,3 @@ def main(argv: list[str] | None = None) -> int:
 
 if __name__ == "__main__":
     raise SystemExit(main())
-    sys.exit(1 if "error" in result else 0)

package/src/skf-test-skill/templates/test-report-template.md

@@ -28,6 +28,7 @@ Anchor / Step mapping:
   Coverage Analysis  → coverage-check
   Coherence Analysis → coherence-check
   External Validation→ external-validators
+  (hard gate)        → step-hard-gate (reads findings, blocks or passes; no report section)
   Completeness Score → score
   Gap Report         → report (includes Discovery Quality subsection)
 -->

package/src/skf-update-skill/customize.toml

@@ -33,12 +33,3 @@ activation_steps_append = []
 persistent_facts = [
   "file:{project-root}/**/project-context.md",
 ]
-
-# --- Optional gate thresholds ---
-#
-# Override the default thresholds used by detect-changes and merge. Empty
-# string or commented = use the bundled default (50% deletion ratio,
-# 80% rename similarity).
-
-deletion_ratio_threshold = ""
-rename_similarity_threshold = ""

package/src/skf-update-skill/references/detect-changes.md

@@ -25,6 +25,17 @@ buildChangeManifestProbeOrder:
 provenanceGapDispatchProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-provenance-gap-dispatch.py'
   - '{project-root}/src/shared/scripts/skf-provenance-gap-dispatch.py'
+# Resolve `{detectScriptsAssetsHelper}` to the first existing path; HALT if
+# neither candidate exists. §Category D uses `detect` to walk the current
+# source tree for scripts/assets (directory conventions, shebang signals,
+# `package.json` `bin` entry-points, asset filename patterns) so NEW_FILE
+# detection mirrors create-skill §4c exactly. Falling back to prose-driven
+# file walking would let the LLM drift on the heuristic list and miss new
+# scripts/assets at deeper directory depths — and on installed modules
+# (no `src/` tree) the LLM would otherwise guess a non-existent path.
+detectScriptsAssetsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-detect-scripts-assets.py'
+  - '{project-root}/src/shared/scripts/skf-detect-scripts-assets.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -305,7 +316,20 @@ Launch subprocesses in parallel that compare source state against provenance map
 
 **Category C — Rename detection:**
 - Cross-reference deleted files/exports with added files/exports
-- If content similarity > 80%: classify as RENAMED instead of deleted+added. **Similarity mechanism by tier:** Quick: compare file size ratio (within 20%) and export name overlap (>70% of exports match by name). Forge and above: use ast-grep to compare export signatures between the deleted and added files. Forge+/Deep: use CCC semantic similarity when available
+- If content similarity > 80% (fixed bundled threshold — not configurable): classify as RENAMED instead of deleted+added. **Similarity mechanism by tier:** Quick: compare file size ratio (within 20%) and export name overlap (>70% of exports match by name). Forge and above: use ast-grep to compare export signatures between the deleted and added files. Forge+/Deep: use CCC semantic similarity when available
+
+**Subprocess return contract.** Hand each Category worker its exact output slice so it returns parse-ready JSON, not prose the parent must re-read. Each worker returns ONLY its own object — no prose, no commentary, no markdown fences (parent strips wrapping fences before parsing). The slice each worker fills is exactly the key §3's `build` helper consumes (the `category_a/b/c` shape below; Category D is helper-driven, not a worker):
+
+```json
+// Category A worker returns ONLY:
+{"category_a": {"modified": [...], "added": [...], "deleted": [...]}}
+// Category B worker returns ONLY:
+{"category_b": {"modified_exports": [...], "new_exports": [...], "deleted_exports": [...], "moved_exports": [...]}}
+// Category C worker returns ONLY:
+{"category_c": {"renamed_files": [...], "renamed_exports": [...]}}
+```
+
+The parent merges the three slices (plus Category D and the `degraded_mode`/`update_mode` flags) into the single category-JSON object §3 pipes to the `build` helper.
 
 **Category D — Script/asset file changes:**
 
@@ -334,7 +358,13 @@ Translate the helper's output into the change manifest:
 - `DELETED_FILE` rows → add to manifest as DELETED_FILE
 - `UNCHANGED` rows → omit from the manifest (no action needed)
 
-The helper does NOT detect NEW_FILE — its job is provenance comparison only. Detect new files via `skf-detect-scripts-assets.py` from create-skill step 3 §4c against the current source tree, then subtract the paths already present in `provenance.file_entries[].source_file`. Remaining files matching detection patterns (`scripts/`, `bin/`, `assets/`, `templates/`) and NOT under `scripts/[MANUAL]/` or `assets/[MANUAL]/` are NEW_FILE.
+The helper does NOT detect NEW_FILE — its job is provenance comparison only. Detect new files by running the same deterministic detector create-skill step 3 §4c uses (resolved via `detectScriptsAssetsProbeOrder`) against the current source tree:
+
+```bash
+uv run {detectScriptsAssetsHelper} detect <source-root>
+```
+
+It emits `scripts_inventory[]` and `assets_inventory[]` (each entry carries `source_file`). Take every `source_file` across both inventories, then subtract the paths already present in `provenance.file_entries[].source_file`. Of the remaining files, those matching detection patterns (`scripts/`, `bin/`, `assets/`, `templates/`) and NOT under `scripts/[MANUAL]/` or `assets/[MANUAL]/` are NEW_FILE.
 
 Files in `scripts/[MANUAL]/` or `assets/[MANUAL]/` → SKIP (user-authored, preserved).
 
@@ -356,7 +386,7 @@ echo "{category JSON}" | uv run {buildChangeManifestHelper} deletion-ratio \
     --provenance-map {forge_version}/provenance-map.json
 ```
 
-The helper handles the three skip conditions internally — when the input has `update_mode: "gap-driven"`, `degraded_mode: true`, or the provenance has zero entries, it returns `skip_reason` set and `should_trigger: false`. The output envelope:
+The helper handles the three skip conditions internally — when the input has `update_mode: "gap-driven"`, `degraded_mode: true`, or the provenance has zero entries, it returns `skip_reason` set and `should_trigger: false`. `should_trigger` fires when the deletion ratio reaches the fixed bundled threshold of 50% (`ratio >= 0.50`, baked into the helper — not configurable). The output envelope:
 
 ```json
 {

package/src/skf-update-skill/references/health-check.md

@@ -1,7 +1,7 @@
 ---
 # `shared/health-check.md` resolves relative to the SKF module root
-# (`_bmad/skf/` when installed, `src/` during development), NOT relative
-# to this step file.
+# (`{project-root}/_bmad/skf/` when installed, `{project-root}/src/` during
+# development), NOT relative to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 

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

@@ -38,6 +38,7 @@ Provide either:
 3. If not in manifest: check for `active` symlink at `{skills_output_folder}/{skill-name}/active` — resolve to `{skill_group}/active/{skill-name}/`
 4. If neither: fall back to flat path `{skills_output_folder}/{skill-name}/`. If SKILL.md exists at the flat path, auto-migrate per `knowledge/version-paths.md` migration rules
 5. Store the resolved path as `{resolved_skill_package}` for all subsequent artifact loading
+6. Bind `{baseline_version}` to the pre-update version — for an update this is the version being updated, i.e. the `{active_version}` resolved in step 1 above (the flat-path fallback in step 4 has no version, so use the package version read from metadata.json in §2). Step 2 §1c passes `{baseline_version}` to `skf-provenance-gap-dispatch.py` as a required argument; leaving it unbound makes the helper search a wrong/empty directory and silently return `no-report`, dropping the major-version off-ramp.
 
 Resolve the path to an absolute skill folder location.
 

package/src/skf-update-skill/references/re-extract.md

@@ -254,7 +254,21 @@ DO NOT BE LAZY — For EACH remaining file in the change manifest with status MO
    - Record: return type (if function/method)
    - Record: JSDoc/docstring summary (if present)
    - Label: confidence tier (T1/T1-low/T2)
-4. Returns structured extraction findings to parent
+4. **Return contract.** Each extraction worker returns ONLY this per-file block — no prose, no commentary, no markdown fences (the parent strips wrapping fences before parsing). The shape is exactly the per-file record §4 aggregates (the `Per-file extractions` block, lines below), so the parent appends it verbatim rather than re-parsing free text:
+
+   ```json
+   {
+     "file_path": "...",
+     "exports": [
+       {"name": "...", "type": "function|class|type|constant",
+        "signature": "...", "location": "{file}:{start_line}-{end_line}",
+        "confidence": "T1|T1-low|T2",
+        "parameters": [{"name": "...", "type": "..."}],
+        "return_type": "...", "docstring": "...",
+        "qmd_evidence": "<if Deep tier, else omit>"}
+     ]
+   }
+   ```
 
 **For DELETED files:** No extraction needed — deletions handled in merge step.
 

package/src/skf-verify-stack/references/report.md

@@ -106,7 +106,7 @@ Based on the overall verdict, present the appropriate recommendation:
 
 **Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. HALT if no candidate exists.
 
-Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{forge_data_folder}/verify-stack-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{forge_data_folder}/verify-stack-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include the feasibility report path (both `{outputFile}` and `{outputFileLatest}`) in `outputs`; include `overallVerdict` (`FEASIBLE` / `CONDITIONALLY_FEASIBLE` / `NOT_FEASIBLE`), `coveragePercentage`, and `recommendationCount` in `summary` — use the case-sensitive schema tokens.
+Write the result contract per `shared/references/output-contract-schema.md` (this path resolves relative to the SKF module root — `{project-root}/_bmad/skf/` when installed, `{project-root}/src/` during development — NOT relative to this step file): the per-run record at `{forge_data_folder}/verify-stack-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{forge_data_folder}/verify-stack-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include the feasibility report path (both `{outputFile}` and `{outputFileLatest}`) in `outputs`; include `overallVerdict` (`FEASIBLE` / `CONDITIONALLY_FEASIBLE` / `NOT_FEASIBLE`), `coveragePercentage`, and `recommendationCount` in `summary` — use the case-sensitive schema tokens.
 
 Write both JSON files through `python3 {atomicWriteHelper} write --target ...` to avoid partial-write corruption. On any non-zero exit: HALT (exit code 4, `halt_reason: "write-failed"`) and emit the error envelope.
 

package/tools/cli/lib/ui.js

@@ -356,8 +356,9 @@ class UI {
         `${chalk.white.bold('Get Started')}`,
         `1. Open this folder in ${ideDisplay}`,
         `2. Activate Ferris:  ${activateLine}`,
-        '3. Ferris (your Skill Architect) will guide you through',
-        '   setting up and forging your first agent skill',
+        '3. Ferris (your Skill Architect) guides you through forge setup',
+        `4. Fastest first skill — ask Ferris to run ${brand.gold('forge-auto <repo-or-doc-url>')}:`,
+        '   one command auto-scopes, compiles, tests, and exports a verified skill',
       ].join('\n');
     }