bmad-module-skill-forge 1.7.0 → 1.9.0

package/src/skf-create-skill/references/step-auto-shard.md

@@ -0,0 +1,110 @@
+---
+nextStepFile: 'step-doc-rot.md'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 5b: Auto-Shard
+
+## STEP GOAL:
+
+Proactively reduce oversized SKILL.md bodies to under 400 lines by extracting Tier 2 sections (`## Full` headings) to `references/`, providing 100 lines of headroom below the 500-line `body.max_lines` ceiling. Tier 1 sections always remain inline. If the body is already within budget, skip cleanly.
+
+## Rules
+
+- Auto-proceed step — no user interaction required
+- Graceful skip — if body is under threshold, proceed without modification
+- Only extract Tier 2 sections (identified by `## Full` heading prefix)
+- Tier 1 sections must NEVER be moved to references/
+- Do not modify frontmatter — only body content and references/ directory
+- Do not invoke `npx skill-check split-body` — this step uses direct extraction
+- Do not invoke the Description Guard Protocol — frontmatter is untouched
+
+## MANDATORY SEQUENCE
+
+### §1. Count Body Lines
+
+Count all lines in the staging SKILL.md between the frontmatter closing `---` and EOF. Exclude trailing blank lines from the count. Store as `body_line_count`.
+
+```
+body_lines_before = body_line_count
+```
+
+**IF `body_line_count` <= 400:**
+- Log: `"auto-shard: skipped (body {body_line_count} lines)"`
+- Set context: `auto_shard_triggered: false`, `sections_extracted: []`, `body_lines_before: {body_line_count}`, `body_lines_after: {body_line_count}`
+- Skip to §6 (Auto-Proceed)
+
+**ELSE:** Proceed to §2.
+
+### §2. Selective Shard — Tier 2 Extraction
+
+Identify Tier 2 sections by their `## Full` heading prefix:
+- `## Full API Reference` → `references/full-api-reference.md`
+- `## Full Type Definitions` → `references/full-type-definitions.md`
+- `## Full Integration Patterns` → `references/full-integration-patterns.md`
+
+Sort identified sections by line count descending (extract largest first).
+
+**FOR EACH Tier 2 section (largest first):**
+
+1. Extract the full section content (from `## Full` heading to the next `##` heading or EOF)
+2. Derive the reference filename from the heading: kebab-case (as shown above)
+3. Write the extracted content (preserving the `##` heading) to `<staging-skill-dir>/references/{filename}`
+4. Replace the extracted section in SKILL.md with a cross-reference blockquote:
+   ```markdown
+   > See [Full API Reference](references/full-api-reference.md)
+   ```
+5. Re-count body lines
+6. **IF `body_line_count` <= 400:** stop extracting, proceed to §3
+
+Track: `sections_extracted: [{heading names}]`
+
+### §3. Tier 1 Preservation Check
+
+Verify ALL Tier 1 sections remain inline in SKILL.md after extraction. Check for these headings:
+
+- `## Overview`
+- `## Quick Start`
+- `## Common Workflows`
+- `## Key API Summary` (or `## Component Catalog` for component-library scope)
+- `## Migration & Deprecation Warnings` (conditional — only check if it was present before extraction)
+- `## Key Types`
+- `## Architecture at a Glance`
+- `## CLI` (conditional — only check if present before extraction)
+- `## Scripts & Assets` (conditional — only check if present before extraction)
+- `## Manual Sections` (conditional — only check if present before extraction)
+
+**IF any Tier 1 section is missing after extraction:**
+HALT: `"Auto-shard removed Tier 1 section {name}. Aborting."`
+
+### §4. Post-Shard Validation
+
+Re-count body lines after all Tier 2 sections have been extracted.
+
+```
+body_lines_after = body_line_count
+```
+
+**IF `body_line_count` > 400 after all Tier 2 sections extracted:**
+- Trim oversized Tier 1 sections: reduce `## Key API Summary` and `## Architecture at a Glance` content to fit within the 400-line budget
+- Do NOT move any Tier 1 section to references/
+- Re-count and update `body_lines_after`
+
+### §5. Cross-Reference Integrity
+
+**FOR EACH extracted reference file:**
+1. Verify the file exists at `<staging-skill-dir>/references/{filename}`
+2. Verify the cross-reference blockquote in SKILL.md contains a link resolving to the file
+
+Log: `"auto-shard: {N} sections extracted, body reduced from {body_lines_before} to {body_lines_after} lines"`
+
+Set context:
+- `auto_shard_triggered: true`
+- `sections_extracted: [{heading names}]`
+- `body_lines_before: {before}`
+- `body_lines_after: {after}`
+
+### §6. Auto-Proceed
+
+Load, read the entire file, then execute `{nextStepFile}`.

package/src/skf-create-skill/references/step-doc-rot.md

@@ -0,0 +1,109 @@
+---
+nextStepFile: 'validate.md'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 5c: Doc-Rot
+
+## STEP GOAL:
+
+Scan feeder artifacts for doc-rot correction indicators and annotate the compiled SKILL.md with `## CORRECTION` blocks. Matching is grep-based and deterministic — no AI judgment is used for detection.
+
+## Rules
+
+- Auto-proceed step — no user interaction required
+- Graceful skip — if no corrections are found in any feeder artifact, proceed without modification
+- Only modify the compiled SKILL.md (correction block insertion) and references (if corrections target referenced content)
+- Do not modify feeder artifacts (evidence-report.md, provenance-map.json, metadata.json) — this step READS them only
+- Do not modify frontmatter — correction blocks are body content only
+- Matching is case-insensitive substring grep — no semantic or AI-based assessment
+
+## MANDATORY SEQUENCE
+
+### §1. Locate Feeder Artifacts
+
+Identify the feeder artifacts in the staging directory for the current skill:
+
+1. **Evidence report:** `{forge_data_folder}/{skill-name}/{version}/evidence-report.md`
+2. **Provenance map:** `{forge_data_folder}/{skill-name}/{version}/provenance-map.json` — focus on T2/T3 entries with temporal annotations
+3. **Temporal context:** changelogs, migration guides, and issue/PR data fetched by step 3b and enriched by step 4 (available in workflow context)
+4. **Compiled SKILL.md:** the staged SKILL.md itself — check for `[QMD:...]` or `[DOC:...]` annotations referencing corrections
+
+For each artifact, attempt to load its content. If an artifact does not exist or is empty, skip it — this is not an error.
+
+Store: `feeder_artifacts_scanned: [{list of artifacts that were loaded}]`
+
+### §2. Grep for Correction Indicators
+
+Scan each loaded feeder artifact for the following correction patterns. All matches are **case-insensitive substring matches** — no regex interpretation, no semantic analysis.
+
+| Pattern | Category |
+|---------|----------|
+| `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 |
+
+For each match, record:
+- `source`: the feeder artifact path or citation where the match was found
+- `pattern`: the specific pattern string that matched
+- `category`: the category from the table above
+- `context_line`: the line or excerpt containing the match
+- `affected`: the function name, API, or section the correction relates to (extract from surrounding context if identifiable; otherwise set to `"unknown"`)
+
+Store all matches as `correction_matches: [{match records}]`
+
+**IF `correction_matches` is empty:**
+- Log: `"doc-rot: skipped (no correction indicators found in feeder artifacts)"`
+- Set context: `doc_rot_triggered: false`, `corrections_added: 0`
+- Skip to §5 (Auto-Proceed)
+
+**ELSE:** Proceed to §3.
+
+### §3. Annotate SKILL.md with Correction Blocks
+
+For each entry in `correction_matches`, insert a `## CORRECTION` block into the compiled SKILL.md.
+
+**Block format:**
+
+```markdown
+## CORRECTION
+
+**Source:** {source}
+**Pattern:** {pattern}
+**Affected:** {affected}
+**Detail:** {context_line}
+```
+
+**Insertion rules:**
+- **After the relevant API section** in SKILL.md if the `affected` function or section can be identified and located in the document
+- **At the end of SKILL.md body** (before any trailing sections like `## Manual Sections`) if the affected section cannot be determined
+- **Never inside frontmatter** — body content only
+- Each correction block is self-contained with its own source citation
+- Multiple corrections produce multiple `## CORRECTION` blocks
+
+Store: `corrections_added: {count of blocks inserted}`
+
+### §4. Log Results
+
+Log: `"doc-rot: {corrections_added} correction blocks added from {feeder_artifacts_scanned_count} feeder artifacts"`
+
+Set context:
+- `doc_rot_triggered: true`
+- `corrections_added: {count}`
+- `feeder_artifacts_scanned: [{list}]`
+- `correction_matches: [{match records}]`
+
+### §5. Auto-Proceed
+
+Load, read the entire file, then execute `{nextStepFile}`.

package/src/skf-create-skill/references/step-doc-sources.md

@@ -0,0 +1,114 @@
+---
+nextStepFile: 'step-auto-shard.md'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 5a: Doc Sources
+
+## STEP GOAL:
+
+Record detected documentation pages and README with content hashes in metadata.json so that downstream audit (analyze-skill) can detect when upstream docs have changed since the skill was compiled.
+
+## Rules
+
+- Auto-proceed step — no user interaction required
+- Graceful failure — if doc detection fails, skip with a warning and proceed to validate
+- Do not modify any compiled artifact other than `metadata.json`
+- Do not block the pipeline on any doc detection error
+
+## MANDATORY SEQUENCE
+
+### 1. Check for Upstream Doc Detection Results
+
+Check if `doc_detection_results` is already populated in the workflow context (set by BS auto-brief in the deepwiki pipeline).
+
+- **If upstream results exist:** use them directly, skip to step 3.
+- **If no upstream results:** continue to step 2.
+
+### 2. Run Doc Detection (if needed)
+
+Check that `{source_repo}` is available from the skill brief.
+
+**If `{source_repo}` is not available:**
+- Set `doc_detection_results` to an empty array `[]`
+- Add evidence note: `"Doc sources: detection skipped — no source_repo in brief"`
+- Skip to step 3.
+
+**If `{source_repo}` is available:**
+
+Invoke the detect-docs script:
+
+```bash
+uv run python src/shared/scripts/skf-detect-docs.py \
+  --repo-url {source_repo} \
+  [--local-path {source_path}] \
+  [--skip-pages-api]
+```
+
+Pass `--local-path {source_path}` when a local clone exists from the extraction step to avoid redundant cloning for `docs/` folder detection.
+
+**Handle exit codes:**
+- **Exit 0** (found ≥1 doc): parse JSON stdout as `doc_detection_results`
+- **Exit 1** (none found): set `doc_detection_results` to empty array `[]`
+- **Exit 2** (error): set `doc_detection_results` to empty array `[]`, add evidence note: `"Doc sources: detection partial — skf-detect-docs.py error (exit 2)"`
+
+### 3. Ensure README Entry
+
+After obtaining detection results, check if any entry has a URL matching `*/README.md` or `*/readme.md`.
+
+**If a README entry already exists** from detection (e.g., `detected_via: "docs_folder"` found a README): keep it as-is.
+
+**If no README entry exists,** add one:
+
+- `url`: Construct from `{source_repo}/blob/main/README.md`
+- `detected_via`: `"readme_always"`
+- `content_hash`: Hash the README content using `sha256:{hexdigest}` convention:
+  - If `{source_path}` is available: read `{source_path}/README.md` locally with `encoding="utf-8"`, compute `sha256:{hexdigest}`
+  - Else: fetch via `gh api repos/{owner}/{repo}/readme --jq '.content'`, base64-decode, hash
+  - If README cannot be found or fetched: set `content_hash` to `null`
+- `recorded_at`: current ISO-8601 timestamp with timezone
+
+### 4. Build doc_sources Array
+
+Map each detection result to the `doc_sources` schema:
+
+```json
+{
+  "url": "{url from detection result}",
+  "detected_via": "{detected_via from detection result}",
+  "content_hash": "{content_hash from detection result — sha256:{hexdigest} or null}",
+  "recorded_at": "{current ISO-8601 timestamp with timezone}"
+}
+```
+
+Field mapping from `skf-detect-docs.py` output:
+- `url` ← `url` (direct copy)
+- `detected_via` ← `detected_via` (direct copy; or `"readme_always"` for the mandatory README entry)
+- `content_hash` ← `content_hash` (direct copy, already in `sha256:{hexdigest}` format from story 1.2)
+- `recorded_at` ← generated at step execution time (ISO-8601 with timezone)
+
+Note: `content_type` from detect-docs output is NOT carried into `doc_sources`.
+
+### 5. Update metadata.json
+
+Read the staging `_bmad-output/{skill-name}/metadata.json` that compile (step 5) wrote.
+
+**If the staging metadata.json is unreadable:** HALT — this indicates compile failed (critical, not doc-detection-related).
+
+**Replace** the `doc_sources` field entirely (do not merge or append to stale data from prior compiles):
+
+```python
+metadata["doc_sources"] = new_doc_sources  # full replacement
+```
+
+Write the updated metadata.json back to the staging directory.
+
+Add evidence note summarizing the result:
+- Success: `"Doc sources: {N} detected, README tracked"`
+- Skip: `"Doc sources: detection skipped — {reason}"`
+- Partial: `"Doc sources: detection partial — {N} found, {errors}"`
+
+### 6. Auto-Proceed
+
+Load, read the entire file, then execute `{nextStepFile}`.

package/src/skf-create-stack-skill/references/generate-output.md

@@ -226,19 +226,19 @@ Use the schema from `{provenanceMapSchemaPath}` — see that asset for the canon
 
 ### 8. Pre-Commit Frontmatter & Body-Size Gate
 
-The full schema/frontmatter validation runs in step 8 (`validate.md`) — but that runs *after* commit-dir and flip-link have already published the package. The two most common non-auto-fixable `skill-check` hard rejects — a `description` over the 1024-char limit (which `skill-check --fix` cannot trim for you) and a SKILL.md body over the `body.max_lines` limit (default **500**) — would therefore only surface on an already-committed, symlink-active artifact, forcing edits to the live `SKILL.md`. Additive re-composition of an already-large stack grows the body monotonically, so the body overflow is the likeliest trigger. Catch both here, while the package is still in `.skf-tmp`.
+The full schema/frontmatter validation runs in step 8 (`validate.md`) — but that runs *after* commit-dir and flip-link have already published the package. The most common non-auto-fixable `skill-check` hard rejects — a `description` over the 1024-char limit (which `skill-check --fix` cannot trim for you), a SKILL.md body over the `body.max_lines` limit (default **500**), and a body exceeding the `body.max_tokens` limit (default **5000**) — would therefore only surface on an already-committed, symlink-active artifact, forcing edits to the live `SKILL.md`. Additive re-composition of an already-large stack grows the body monotonically, so body overflow (lines or tokens) is the likeliest trigger. Catch all three here, while the package is still in `.skf-tmp`.
 
-Resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}` (first existing path wins). Run it against the **staged** `SKILL.md`, passing the real skill name so the directory-match check is not fooled by the `.skf-tmp` staging suffix, and `--max-body-lines 500` to assert the skill-check body limit pre-commit:
+Resolve `{frontmatterValidator}` from `{frontmatterValidatorProbeOrder}` (first existing path wins). Run it against the **staged** `SKILL.md`, passing the real skill name so the directory-match check is not fooled by the `.skf-tmp` staging suffix, `--max-body-lines 500` to assert the skill-check body-line limit, and `--max-body-tokens 5000` to assert the skill-check body-token limit pre-commit:
 
 ```bash
-uv run {frontmatterValidator} {skill_staging}/SKILL.md --skill-dir-name {project_name}-stack --max-body-lines 500
+uv run {frontmatterValidator} {skill_staging}/SKILL.md --skill-dir-name {project_name}-stack --max-body-lines 500 --max-body-tokens 5000
 ```
 
-The validator emits JSON: `status` (`pass`/`warn`/`fail`), `issues[]` (each with `severity` ∈ `high|medium|low`, `field`, `message`), `body_lines` (the counted body size), and `summary`. Disposition:
+The validator emits JSON: `status` (`pass`/`warn`/`fail`), `issues[]` (each with `severity` ∈ `high|medium|low`, `field`, `message`), `body_lines` (the counted body size), `body_tokens` (the estimated token count), and `summary`. Disposition:
 
 - **`status` is `fail`, OR any `issues[]` entry has `severity` `high` or `medium`** — a hard violation that `npx skill-check` (step 8) would reject and `--fix` cannot auto-correct. HALT-to-fix **in staging**, then re-run the validator until it clears. Remediate by `field`:
   - `description` / `name` / `compatibility` — trim/correct `{skill_staging}/SKILL.md` (e.g. shorten `description` to ≤ 1024 chars).
-  - `body` (`body lines N exceeds max 500`) — reduce the staged body: prefer a **selective split** of the largest Tier-2 section(s) into `{skill_staging}/references/`, keeping Tier-1 content inline (mirrors `validate.md` §3); or trim redundant content. Re-run the gate until `body_lines ≤ 500`.
+  - `body` (`body lines N exceeds max 500` or `body token estimate N exceeds max 5000`) — reduce the staged body: prefer a **selective split** of the largest Tier-2 section(s) into `{skill_staging}/references/`, keeping Tier-1 content inline (mirrors `validate.md` §3); or trim redundant content. Re-run the gate until both `body_lines ≤ 500` and `body_tokens ≤ 5000`.
 
   Do NOT proceed to §9 commit-dir with an unresolved high/medium issue. Note: an over-long `description` is rated `medium` and exits `0`, so key the HALT on the issue severities above — not on the exit code.
 - **Only `low`-severity issues (e.g. an unexpected field)** — record each as a WARNING in the evidence report and proceed; these do not block the commit.

package/src/skf-forger/SKILL.md

@@ -84,13 +84,17 @@ When the user provides multiple workflow codes (e.g., `BS CS TS EX`, `QS TS EX`,
 
 **Pipeline activation:**
 
-1. **Parse the sequence** — split codes, expand aliases (`forge` → `BS CS TS EX`, `forge-quick` → `QS TS EX`, `onboard` → `AN CS TS EX`, `maintain` → `AS US TS EX`), extract any bracket arguments (`CS[cocoindex]`, `TS[min:80]`)
+1. **Parse the sequence** — split codes, expand aliases (`deepwiki` → `AN[auto] BS[auto] CS TS[min:90] EX`, `forge` → `BS CS TS EX`, `forge-quick` → `QS TS EX`, `onboard` → `AN CS TS EX`, `maintain` → `AS US TS EX`), extract any bracket arguments (`CS[cocoindex]`, `TS[min:80]`)
+   **Alias lifecycle:** When the parsed alias is `onboard`, emit a deprecation notice **before** expanding the alias and **before** pipeline progress reporting begins. Emit on **every** invocation — this is not a one-time warning. After emitting the notice, expand `onboard` → `AN CS TS EX` as normal (no behavioral change — existing 80% default threshold applies):
+
+   > ⚠️ **onboard is deprecated — use deepwiki instead.** The onboard pipeline (AN CS TS EX at 80% threshold) still runs, but will be removed in v2.0. To migrate: replace `onboard` with `deepwiki <repo-url>`. deepwiki adds auto-brief generation (BS[auto]) and a 90% quality threshold.
+
 2. **Validate the sequence** — check for anti-patterns (EX before TS, CS without BS, duplicates). If found, warn the user and ask to confirm or adjust. In `{headless_mode}`, warn but proceed.
 3. **Set `{headless_mode}` = true** — pipelines auto-activate headless mode for all workflows in the chain. The user committed to the sequence by providing it.
 4. **Execute left to right** — for each workflow in the sequence:
    - a. **Report start**: "Pipeline [{current}/{total}]: Starting {code} ({description})..."
    - b. **Resolve inputs** from the previous workflow's output using the Data Flow table in pipeline-contracts.md. If the previous workflow produced a `skill_name`, `brief_path`, or other handoff data, pass it as the input argument.
-   - c. **Invoke the workflow** with `{headless_mode}` = true and any resolved arguments.
+   - c. **Invoke the workflow** with `{headless_mode}` = true, `{pipeline_alias}` set to the alias name (`deepwiki`, `forge`, `forge-quick`, `onboard`, `maintain`, or `null` for ad-hoc sequences), and any resolved arguments.
    - d. **Check circuit breaker** after completion. Load the output artifact and validate against the threshold (default or user-specified via `[min:N]`). If the check fails: halt the pipeline, report what completed and what remains.
    - e. **Report completion**: "Pipeline [{current}/{total}]: {code} complete — {brief summary of output}."
 5. **Pipeline summary** — after all workflows complete (or on halt), present a summary:
@@ -100,6 +104,8 @@ When the user provides multiple workflow codes (e.g., `BS CS TS EX`, `QS TS EX`,
    - Next steps recommendation
 6. **Result Contract** — write the pipeline result contract per `shared/references/output-contract-schema.md`: the per-run record at `{sidecar_path}/pipeline-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{sidecar_path}/pipeline-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include one entry per completed workflow in `outputs` (referencing each workflow's own `-latest.json` result record); include per-step status and the overall pipeline status in `summary`.
 
+**deepwiki pipeline note:** `deepwiki <repo-url> --pin <version>` — the `--pin` argument is passed to AN's pipeline data context alongside the `[auto]` flag. AN's `step-auto-scope.md §0b` consumes it for pin resolution.
+
 **Special pipeline behaviors:**
 - `AN` in a pipeline with `CS`: if AN produces multiple recommended briefs, auto-select all and process sequentially in batch mode. If only one unit found, auto-select it.
 - `AS` followed by `US`: if `summary.severity` in `audit-skill-result-latest.json` is CLEAN, skip US and report "No drift detected — skipping update."

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

@@ -41,6 +41,7 @@ These rules apply to every step in this workflow:
 | 3 | Coverage Check | references/coverage-check.md | Yes |
 | 4 | Coherence Check | references/coherence-check.md | Yes |
 | 4b | External Validators | references/external-validators.md | Yes |
+| 4c | Hard Gate | references/step-hard-gate.md | Yes |
 | 5 | Score | references/score.md | Yes |
 | 6 | Report | references/report.md | No (confirm) |
 | 7 | Workflow Health Check | references/health-check.md | Yes |
@@ -49,9 +50,9 @@ These rules apply to every step in this workflow:
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | skill_name [required]; optional flags: `--allow-workspace-drift`, `--no-discovery` (skip §4b Discovery Testing), `--no-health-check` (skip §7 health-check dispatch), `--tier=<Quick\|Forge\|Forge+\|Deep>` (bypass forge-tier.yaml sidecar requirement), `--threshold=<N>` (override pass threshold; CLI wins over `workflow.default_threshold` scalar) |
+| **Inputs** | skill_name [required]; optional flags: `--allow-workspace-drift`, `--no-discovery` (skip §4b Discovery Testing), `--no-health-check` (skip §7 health-check dispatch), `--tier=<Quick\|Forge\|Forge+\|Deep>` (bypass forge-tier.yaml sidecar requirement), `--threshold=<N>` (override pass threshold; CLI wins over per-pipeline defaults and `workflow.default_threshold` scalar) |
 | **Gates** | step 6: Confirm Gate [C] |
-| **Outputs** | per-run `test-report-{skill_name}-{run_id}.md` with completeness score and result (PASS/FAIL); per-run `skf-test-skill-result-{run_id}.json` and `skf-test-skill-result-latest.json` written atomically under `{forge_version}/` — downstream consumers (export-skill, update-skill `--from-test-report`) glob `test-report-{skill_name}-*.md` and pick newest by parsed ISO timestamp |
+| **Outputs** | per-run `test-report-{skill_name}-{run_id}.md` with completeness score and result (PASS/FAIL); per-run `skf-test-skill-result-{run_id}.json` and `skf-test-skill-result-latest.json` written atomically under `{forge_version}/`; `evidence-report-fallback.md` written under `{forge_version}/` when threshold fallback occurs (score between 80% and target threshold) — downstream consumers (export-skill, update-skill `--from-test-report`) glob `test-report-{skill_name}-*.md` and pick newest by parsed ISO timestamp |
 | **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
 | **Exit codes** | See "Exit Codes" below |
 
@@ -62,7 +63,7 @@ Every terminal state in this workflow exits with a stable code so headless autom
 | Code | Meaning              | Raised by                                                                                  |
 | ---- | -------------------- | ------------------------------------------------------------------------------------------ |
 | 0    | success / PASS       | step 6 §6b — `testResult: 'pass'` (after the result contract is written in §4c)            |
-| 2    | fail / FAIL          | step 6 §6b — `testResult: 'fail'` (after the result contract is written in §4c)            |
+| 2    | fail / FAIL          | step 4c §3 — hard gate blocked (`halt_reason: "hard-gate-blocked"`); step 6 §6b — `testResult: 'fail'` (after the result contract is written in §4c) |
 | 3    | inconclusive         | step 6 §6b — `testResult: 'inconclusive'` (distinct from fail so orchestrators can route to manual-review queues) |
 | 4    | pass-with-drift      | step 6 §6b — `testResult: 'pass-with-drift'` (distinct from clean pass — `--allow-workspace-drift` was in effect; orchestrators MUST route to re-test-against-pinned-commit queues and refuse export; never exit 0 under drift override) |
 
@@ -71,10 +72,10 @@ Every terminal state in this workflow exits with a stable code so headless autom
 When `{headless_mode}` is true, step 6 emits a single-line JSON envelope on **stdout** before chaining to step 7, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
 
 ```
-SKF_TEST_RESULT_JSON: {"status":"success|error","skill_name":"…","verdict":"PASS|FAIL|INCONCLUSIVE|pass-with-drift","score":N,"threshold":N,"report_path":"…|null","next_workflow":"export-skill|update-skill|null","exit_code":0,"halt_reason":null}
+SKF_TEST_RESULT_JSON: {"status":"success|error","skill_name":"…","verdict":"PASS|FAIL|INCONCLUSIVE|pass-with-drift","score":N,"threshold":N,"report_path":"…|null","next_workflow":"export-skill|update-skill|null","exit_code":0,"halt_reason":null,"threshold_fallback":true,"original_threshold":90}
 ```
 
-`status` is `"success"` on the terminal happy path (any of PASS / FAIL / INCONCLUSIVE / pass-with-drift — the workflow completed), `"error"` on any HARD HALT before §4c. `verdict` is the canonical result string. `next_workflow` is `"export-skill"` only when `verdict == "PASS"`; `"update-skill"` for `FAIL` or `pass-with-drift`; `null` for `INCONCLUSIVE` (manual review). `halt_reason` is `null` on the terminal path or one of the workflow-defined halt strings (`"forge-tier-missing"`, `"target-inaccessible"`, `"write-failed"`, `"step-completeness-violation"`, `"report-anchor-missing"`, `"health-check-missing"`, `"atomic-writer-missing"`). `exit_code` matches the table above.
+`status` is `"success"` on the terminal happy path (any of PASS / FAIL / INCONCLUSIVE / pass-with-drift — the workflow completed), `"error"` on any HARD HALT before §4c. `verdict` is the canonical result string. `next_workflow` is `"export-skill"` only when `verdict == "PASS"`; `"update-skill"` for `FAIL` or `pass-with-drift`; `null` for `INCONCLUSIVE` (manual review). `halt_reason` is `null` on the terminal path or one of the workflow-defined halt strings (`"forge-tier-missing"`, `"target-inaccessible"`, `"write-failed"`, `"step-completeness-violation"`, `"report-anchor-missing"`, `"health-check-missing"`, `"atomic-writer-missing"`, `"hard-gate-blocked"`). `exit_code` matches the table above. When threshold fallback occurred, the envelope includes `"threshold_fallback":true` and `"original_threshold":N`; these fields are omitted when no fallback occurred.
 
 The same payload is persisted to disk by step 6 §4c (atomic write) at two locations under `{forge_version}/`:
 
@@ -83,7 +84,7 @@ The same payload is persisted to disk by step 6 §4c (atomic write) at two locat
 | `skf-test-skill-result-{run_id}.json`         | Per-run record. `{run_id}` carries UTC timestamp + PID + random suffix.    |
 | `skf-test-skill-result-latest.json`           | Latest copy — stable path for pipeline consumers (copy, not symlink).      |
 
-The on-disk payload is the richer form: it adds `outputs[]` (report-path entries), `summary` (`score`, `threshold`, `result`, `testMode`, `activeCategories[]`, `inconclusiveReasons[]` when present), `runId`, and `healthCheckDispatched`. The stdout envelope is the compact subset documented above.
+The on-disk payload is the richer form: it adds `outputs[]` (report-path entries), `summary` (`score`, `threshold`, `result`, `testMode`, `activeCategories[]`, `inconclusiveReasons[]` when present, `threshold_fallback`, `original_threshold`, `evidence_report_path` when threshold fallback occurred), `runId`, and `healthCheckDispatched`. The stdout envelope is the compact subset documented above.
 
 ## On Activation
 
@@ -113,7 +114,7 @@ The on-disk payload is the richer form: it adds `outputs[]` (report-path entries
    - `{testReportTemplatePath}` ← `workflow.test_report_template_path` if non-empty, else `templates/test-report-template.md`
    - `{outputFormatsPath}` ← `workflow.output_formats_path` if non-empty, else `assets/output-section-formats.md`
    - `{scoringRulesPath}` ← `workflow.scoring_rules_path` if non-empty, else `references/scoring-rules.md`
-   - `{defaultThreshold}` ← `workflow.default_threshold` if non-empty/non-null, else `80`. CLI `--threshold=<N>` (when present) wins over the scalar at the usage site in `references/score.md`.
+   - `{defaultThreshold}` ← `workflow.default_threshold` if non-empty/non-null, else `80`. CLI `--threshold=<N>` wins over per-pipeline defaults (from init.md §1b) which win over this scalar at the usage site in `references/score.md`.
    - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string. When empty, the post-finalization hook in `references/report.md` is a no-op.
 
    Stash all five as workflow-context variables. Stage files reference `{testReportTemplatePath}` / `{outputFormatsPath}` / `{scoringRulesPath}` / `{defaultThreshold}` / `{onCompleteCommand}` 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.

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

@@ -43,7 +43,8 @@ test_report_template_path = ""
 output_formats_path = ""
 scoring_rules_path = ""
 
-# Pass threshold (percent). CLI `--threshold=<N>` wins over this scalar.
+# Pass threshold (percent). Precedence: CLI `--threshold=<N>` > per-pipeline
+# defaults (from init.md §1b lookup table) > this scalar > bundled fallback 80.
 # Override here to change the org-wide default without forking the skill.
 default_threshold = 80
 

package/src/skf-test-skill/references/external-validators.md

@@ -1,5 +1,5 @@
 ---
-nextStepFile: 'score.md'
+nextStepFile: 'step-hard-gate.md'
 outputFile: '{forge_version}/test-report-{skill_name}-{run_id}.md'
 ---
 

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

@@ -30,7 +30,7 @@ If skill path was provided as workflow argument, use it directly.
 - `--no-discovery` — skip the §4b Discovery Testing block in step 6 (report). Store `no_discovery: true` in workflow context when present.
 - `--no-health-check` — skip the §7 health-check dispatch in step 6 (report). Store `no_health_check: true` in workflow context when present.
 - `--tier=<Quick|Forge|Forge+|Deep>` — bypass the §4 forge-tier.yaml sidecar HALT. Store `tier_flag: '<value>'` in workflow context when present; §4 will set `detected_tier` directly from this value and skip the sidecar probe.
-- `--threshold=<N>` — override the pass threshold for this run. Consumed by `references/score.md` §1; CLI wins over the `workflow.default_threshold` scalar.
+- `--threshold=<N>` — override the pass threshold for this run. Consumed by `references/score.md` §1; CLI wins over per-pipeline defaults (§1b) and the `workflow.default_threshold` scalar.
 
 If no path provided, ask:
 
@@ -40,6 +40,21 @@ Provide the skill path or name. I'll search in `{skillsOutputFolder}`.
 
 **Path or name:**"
 
+### 1b. Resolve Per-Pipeline Quality Threshold
+
+If `{pipeline_alias}` is set in the workflow data context (forwarded by the forger when TS runs inside a pipeline — see `shared/references/pipeline-contracts.md` Pipeline State), look up the alias in the per-pipeline threshold defaults table:
+
+| Pipeline Alias | Default Threshold |
+|----------------|-------------------|
+| `deepwiki`     | 90                |
+| `forge`        | 80                |
+| `forge-quick`  | 80                |
+| `campaign`     | 90                |
+
+- **If `{pipeline_alias}` is present AND found in the table:** store the corresponding value as `{pipeline_default_threshold}` in workflow context. This variable is consumed by `references/score.md` §1 as a precedence layer between CLI `--threshold` and `{defaultThreshold}`.
+- **If `{pipeline_alias}` is present but NOT in the table:** `{pipeline_default_threshold}` remains unset. Score.md falls through to `{defaultThreshold}`.
+- **If `{pipeline_alias}` is absent** (standalone TS invocation, not running inside a pipeline): `{pipeline_default_threshold}` remains unset. Score.md falls through to `{defaultThreshold}`.
+
 ### 2. Validate Skill Exists (version-aware)
 
 Resolve the skill path using version-aware resolution (see `{versionPathsKnowledge}`):

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

@@ -149,7 +149,7 @@ cat payload.json | python3 {atomicWriteHelper} write --target {forge_version}/sk
 
 Payload contents:
 - `outputs[]` — include the test report path at `{outputFile}` with its `{run_id}` suffix
-- `summary` — `score`, `threshold`, `result` (`"PASS"`, `"PASS_WITH_DRIFT"`, `"FAIL"`, or **`"INCONCLUSIVE"`**), `testMode` (naive/contextual), `activeCategories[]`, `inconclusiveReasons[]` (when present). `PASS_WITH_DRIFT` is set when the workflow observed workspace drift and the user passed `--allow-workspace-drift` — see step 5 §5 drift override. Downstream consumers MUST treat `PASS_WITH_DRIFT` as a non-exportable result: re-run against the pinned commit before export.
+- `summary` — `score`, `threshold`, `result` (`"PASS"`, `"PASS_WITH_DRIFT"`, `"FAIL"`, or **`"INCONCLUSIVE"`**), `testMode` (naive/contextual), `activeCategories[]`, `inconclusiveReasons[]` (when present). `PASS_WITH_DRIFT` is set when the workflow observed workspace drift and the user passed `--allow-workspace-drift` — see step 5 §5 drift override. Downstream consumers MUST treat `PASS_WITH_DRIFT` as a non-exportable result: re-run against the pinned commit before export. When threshold fallback occurred, add `threshold_fallback: true`, `original_threshold: {N}`, and `evidence_report_path: '{path}'` to the summary — these fields are absent (not `false`/`null`) when no fallback occurred.
 - `runId` — the workflow's `{run_id}` for downstream correlation
 - `healthCheckDispatched` — boolean, set by §7 after the dispatch decision
 
@@ -173,6 +173,7 @@ Run it with a bounded timeout (default 60s). On success: log Info note "on_compl
  'coverage-check',
  'coherence-check',
  'external-validators',
+ 'hard-gate',
  'score',
  'report']
 ```
@@ -211,6 +212,9 @@ skipped its append.
 
 **Result:** **{PASS|PASS_WITH_DRIFT|FAIL|INCONCLUSIVE}** — **{score}%** (threshold: {threshold}%)
 
+{If `thresholdFallback` is present in output frontmatter:}
+**Threshold fallback:** scored {score}% against {originalThreshold} target — accepted at 80% floor. Evidence report: {evidenceReportPath}
+
 **Gaps Found:** {total_gaps}
 - Critical: {N}
 - High: {N}