bmad-module-skill-forge 1.4.1 → 1.5.0

package/src/skf-test-skill/{steps-c/step-06-report.md → references/report.md}

@@ -1,12 +1,13 @@
 ---
-nextStepFile: './step-07-health-check.md'
+nextStepFile: 'health-check.md'
 
 outputFile: '{forge_version}/test-report-{skill_name}-{run_id}.md'
 scoringRulesFile: 'references/scoring-rules.md'
 outputFormatsFile: 'assets/output-section-formats.md'
 # outputContractSchema and healthCheck resolve relative to the SKF module root
-# (`_bmad/skf/` when installed, `src/` during development), NOT relative to
-# this step file. Both paths are probed in order; HALT if neither exists.
+# (`{project-root}/_bmad/skf/` when installed, `{project-root}/src/` during
+# development), NOT relative to this step file. Both paths are probed in
+# order; HALT if neither exists.
 outputContractSchema: 'shared/references/output-contract-schema.md'
 healthCheckProbeOrder:
   - '{project-root}/_bmad/skf/shared/health-check.md'
@@ -16,22 +17,13 @@ atomicWriteProbeOrder:
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 ---
 
+<!-- Config: communicate in {communication_language}. Test report prose in {document_output_language}. -->
+
 # Step 6: Gap Report
 
 ## STEP GOAL:
 
-Generate a detailed gap report listing every issue found during coverage and coherence analysis, assign severity to each gap, provide specific actionable remediation suggestions, and finalize the test report document. This is the final step — no next step file.
-
-## Rules
-
-- Focus on gap enumeration, severity classification, and remediation — do not recalculate scores
-- Remediation suggestions reference specific files, exports, and line numbers
-- Gaps are ordered by severity (Critical > High > Medium > Low > Info)
-- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing report is NOT the terminal step
-
-## MANDATORY SEQUENCE
-
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+Generate a detailed gap report listing every issue found during coverage and coherence analysis, assign severity to each gap, provide specific actionable remediation suggestions, and finalize the test report document. Do not recalculate scores — that ran in step 5. This step chains to the local health-check step via `{nextStepFile}` after completion; the user-facing report is NOT the terminal step.
 
 ### 1. Collect All Issues
 
@@ -74,7 +66,7 @@ Load `{scoringRulesFile}` for gap severity classification:
 
 Load `{outputFormatsFile}` for gap entry format and remediation quality rules.
 
-For each issue, assign severity from `{scoringRulesFile}` and generate a specific remediation following the quality rules in `{outputFormatsFile}`. Order gaps by severity: Critical → High → Medium → Low → Info.
+For each issue, assign severity from `{scoringRulesFile}` and generate a specific remediation following the quality rules in `{outputFormatsFile}`. Remediation suggestions MUST reference specific files, exports, and line numbers. Order gaps by severity: Critical → High → Medium → Low → Info.
 
 ### 4. Generate Remediation Summary and Append Gap Report
 
@@ -82,7 +74,9 @@ Load the Gap Report section format from `{outputFormatsFile}`. Count gaps by sev
 
 If no gaps found, append a clean pass message recommending **export-skill** workflow.
 
-### 4b. Discovery Testing (MANDATORY — H4)
+### 4b. Discovery Testing (MANDATORY)
+
+**`--no-discovery` flag bypass (precedes the precondition check).** If `no_discovery: true` is set in workflow context (from §1 of `init.md` — `--no-discovery` flag on invocation), record an Info-severity note in the Discovery Quality subsection: `discovery — skipped: --no-discovery flag set`, log the bypass, and SKIP §4b.1–§4b.3. Proceed to §4b.4 (description optimization) only if tessl/skill-check flagged description issues; otherwise skip directly to §4c.
 
 After gap enumeration, perform minimum-viable discovery testing. This is a **Medium-weight** check contributing to the Discovery Quality subsection — no longer advisory boilerplate.
 
@@ -93,7 +87,7 @@ Count the skills in `{skillsOutputFolder}`: `ls -1d {skillsOutputFolder}/*/ 2>/d
 - If `catalog_size < 2`: **skip §4b.1–§4b.3**. Record an Info-severity note in the Discovery Quality subsection: `discovery — skipped: catalog size N={catalog_size}, requires ≥2 candidates for meaningful routing`. The routing test is vacuous with one candidate (any prompt returns the sole skill); reporting `3/3 PASS` under those conditions inflates the Discovery score and masks genuinely bad description triggers. Proceed to §4b.4 (description optimization) if tessl/skill-check flagged description issues; otherwise skip to §4c.
 - If `catalog_size >= 2`: continue with §4b.1 as written.
 
-Optional escape hatch: the workflow accepts `--discovery-catalog=all` to broaden the candidate pool to `.claude/skills/` or `_bmad/agents/` for single-skill repos where the repo-local catalog is trivially too small. When the flag is set, rebuild `catalog_size` from the broader pool before the precondition check.
+Optional escape hatch: the workflow accepts `--discovery-catalog=all` to broaden the candidate pool to `{project-root}/.claude/skills/` or `{project-root}/_bmad/agents/` for single-skill repos where the repo-local catalog is trivially too small. When the flag is set, rebuild `catalog_size` from the broader pool before the precondition check.
 
 **4b.1 Extract realistic prompts from the skill under test:**
 
@@ -137,12 +131,12 @@ Realistic prompt patterns for synthesis (§4b.1 fallback):
 - Implicit: "why did {metric} drop last {period}"
 - Abbreviated: "run the {keyword} thing on this data"
 
-### 4c. Result Contract (atomic write — B4)
+### 4c. Result Contract (atomic write)
 
 **Resolve `{atomicWriteHelper}`:** probe `{atomicWriteProbeOrder}`. HALT if neither candidate exists — the contract is a downstream-consumer protocol and must never be written non-atomically.
 
 Write the result contract per `{outputContractSchema}`:
-- Per-run record: `{forge_version}/skf-test-skill-result-{run_id}.json` (the `{run_id}` set in step-01 §6a — already carries UTC timestamp + PID + random suffix, so no same-second collision).
+- Per-run record: `{forge_version}/skf-test-skill-result-{run_id}.json` (the `{run_id}` set in step 1 §6a — already carries UTC timestamp + PID + random suffix, so no same-second collision).
 - Latest copy: `{forge_version}/skf-test-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink).
 
 Both writes MUST go through the atomic writer so partial writes are never observable:
@@ -155,29 +149,37 @@ 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-05 §5 (M5). 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.
 - `runId` — the workflow's `{run_id}` for downstream correlation
 - `healthCheckDispatched` — boolean, set by §7 after the dispatch decision
 
-The `{forge_version}/.test-skill.lock` acquired in step-01 §6b remains held until the end of this step — it guards against concurrent latest-file overwrites.
+The `{forge_version}/.test-skill.lock` acquired in step 1 §6b remains held until the end of this step — it guards against concurrent latest-file overwrites.
+
+**Post-finalization hook.** If `{onCompleteCommand}` (resolved in SKILL.md On Activation §3 from `workflow.on_complete` scalar) is non-empty, invoke it as:
+
+```bash
+{onCompleteCommand} --result-path={forge_version}/skf-test-skill-result-{run_id}.json
+```
+
+Run it with a bounded timeout (default 60s). On success: log Info note "on_complete — invoked: {command}" and continue. On non-zero exit, timeout, or any failure: append the failure reason to `workflow_warnings[]` (e.g. `on_complete — failed (exit {N}): {stderr_first_line}`) and continue. **The hook must never fail the workflow** — its purpose is integration glue (notify a CI router, post to a queue, archive the result) and any failure there is orthogonal to the test verdict. If `{onCompleteCommand}` is empty, this hook is a no-op (no log entry needed).
 
 ### 5. Finalize Output Document — Enforce Step Completeness
 
-**Per S6 (incremental step tracking):** read `stepsCompleted` from the output frontmatter. The expected set is the canonical chain:
+**Incremental step tracking:** read `stepsCompleted` from the output frontmatter. The expected set is the canonical chain:
 
 ```
-['step-01-init',
- 'step-02-detect-mode',
- 'step-03-coverage-check',
- 'step-04-coherence-check',
- 'step-04b-external-validators',
- 'step-05-score',
- 'step-06-report']
+['init',
+ 'detect-mode',
+ 'coverage-check',
+ 'coherence-check',
+ 'external-validators',
+ 'score',
+ 'report']
 ```
 
-If any expected entry is missing, HALT with "step completeness violation — missing {list}; workflow state is inconsistent, do not finalize the report". Only append `'step-06-report'` and write back after the check passes.
+If any expected entry is missing, HALT with "step completeness violation — missing {list}; workflow state is inconsistent, do not finalize the report". Only append `'report'` and write back after the check passes.
 
-**M4 — Section anchor presence check (companion to stepsCompleted).** The
+**Section anchor presence check (companion to stepsCompleted).** The
 report template ships six canonical H2 anchors — one per populating step. An
 off-sequence run (e.g. a step wrote its section into the wrong anchor, or a
 subagent truncated the file) can leave `stepsCompleted` intact while a section
@@ -194,12 +196,12 @@ return ≥1 match:
 ```
 
 On any miss, HALT with "report anchor missing: {anchor} — section was not
-appended by its owning step". Do NOT append `'step-06-report'` and do NOT
+appended by its owning step". Do NOT append `'report'` and do NOT
 write the result contract. The template in `templates/test-report-template.md`
 declares these anchors as TBD placeholders; a miss means a step silently
 skipped its append.
 
-**INCONCLUSIVE as gate:** if `testResult == 'inconclusive'` (from step-05), the report final presentation (§6) and result contract (§4c) have already been written with that verdict. Do NOT auto-map INCONCLUSIVE to PASS or FAIL. Recommend `manual-review`. The step must still complete (health-check runs unconditionally) — INCONCLUSIVE is a report-time signal, not a workflow abort.
+**INCONCLUSIVE as gate:** if `testResult == 'inconclusive'` (from step 5), the report final presentation (§6) and result contract (§4c) have already been written with that verdict. Do NOT auto-map INCONCLUSIVE to PASS or FAIL. Recommend `manual-review`. The step must still complete (health-check runs unconditionally) — INCONCLUSIVE is a report-time signal, not a workflow abort.
 
 ### 6. Present Final Report
 
@@ -240,7 +242,7 @@ skipped its append.
 
 **Test report finalized.**"
 
-### 6b. Headless Exit Status (S7)
+### 6b. Headless Exit Status
 
 If `{headless_mode}`:
 - `testResult: 'pass'` → `exit 0`
@@ -252,7 +254,9 @@ Non-headless mode always drops to the menu in §7.
 
 ### 7. Health-Check Dispatch + MENU OPTIONS
 
-Resolve `{healthCheckFile}` per H2: probe `{healthCheckProbeOrder}` in order. **HALT** if neither candidate exists — the health-check is the true terminal step; without it the workflow cannot complete honestly:
+**`--no-health-check` flag bypass (precedes the health-check resolution).** If `no_health_check: true` is set in workflow context (from §1 of `init.md` — `--no-health-check` flag on invocation), set `health_check_dispatched: false` in the output report frontmatter and mirror `healthCheckDispatched: false` into the result contract written in §4c (re-write atomically via `{atomicWriteHelper}`). Log Info note "health-check — skipped: --no-health-check flag set" and EXIT THE WORKFLOW: in `{headless_mode}`, exit with the code already determined in §6b; non-headless, simply terminate after the §6 presentation. Do NOT resolve `{healthCheckFile}`, do NOT display the menu, do NOT chain to `{nextStepFile}`. The §6b exit branch is the terminal state under this flag.
+
+Resolve `{healthCheckFile}`: probe `{healthCheckProbeOrder}` in order. **HALT** if neither candidate exists — the health-check is the true terminal step; without it the workflow cannot complete honestly:
 
 ```
 Error: cannot locate shared/health-check.md at either of:
@@ -272,19 +276,5 @@ Also mirror the boolean into the `healthCheckDispatched` field of the result con
 
 Display: "**Test complete.** [C] Finish"
 
-#### Menu Handling Logic:
-
-- IF C: Load, read the full file, and execute `{nextStepFile}` — the health-check step is the true terminal step of this workflow.
-- IF Any other: help user respond, then redisplay menu
-
-#### EXECUTION RULES:
-
-- ALWAYS halt and wait for user input after presenting menu
-- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-continue past report menu"; set `health_check_dispatched: true` in frontmatter before chaining
-- C triggers the health check, which is the true workflow exit
-- User may ask questions about the report before finishing
-
-## CRITICAL STEP COMPLETION NOTE
-
-When the user selects C, this step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md`. After the health check completes, the test-skill workflow is fully done. The test report document at `{outputFile}` contains the full analysis: Test Summary, Coverage Analysis, Coherence Analysis, Completeness Score, and Gap Report.
+On [C] (or auto-proceed in `{headless_mode}` — log: "headless: auto-continue past report menu"): set `health_check_dispatched: true` in frontmatter, then load and execute `{nextStepFile}` (the local health-check dispatcher). The test report document at `{outputFile}` contains the full analysis: Test Summary, Coverage Analysis, Coherence Analysis, Completeness Score, and Gap Report.
 

package/src/skf-test-skill/{steps-c/step-05-score.md → references/score.md}

@@ -1,36 +1,34 @@
 ---
-nextStepFile: './step-06-report.md'
+nextStepFile: 'report.md'
 outputFile: '{forge_version}/test-report-{skill_name}-{run_id}.md'
 scoringRulesFile: 'references/scoring-rules.md'
 sourceAccessProtocol: 'references/source-access-protocol.md'
 scoringScript: 'scripts/compute-score.py'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 5: Score
 
 ## STEP GOAL:
 
 Calculate the overall completeness score by aggregating coverage, coherence, and external validation category scores with the appropriate weight distribution (naive or contextual), apply the pass/fail threshold, and determine the test result.
 
-## Rules
-
-- Focus only on score calculation — do not generate remediation suggestions (Step 06)
-- Score must be deterministic — same inputs always produce same output
-- Show the math: category scores, weights, weighted contributions, total
-
-## MANDATORY SEQUENCE
-
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Load Scoring Rules
 
 Load `{scoringRulesFile}` to get:
 - Category weights (naive vs contextual distribution)
-- Default threshold (80%)
 - Tier-dependent scoring adjustments
-- Any custom threshold override from workflow input
 
-**Docs-only mode check:** If the Coverage Analysis section in `{outputFile}` notes docs-only mode (set by step-03 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-03).
+**Resolve the pass threshold (precedence: CLI > 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).
+
+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.
+
+**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).
 
 ### 2. Read Category Scores from Output
 
@@ -53,9 +51,9 @@ Read `{outputFile}` and extract the category scores calculated in previous steps
 
 **Read testMode from {outputFile} frontmatter.**
 
-#### 2b. Apply S9 State 2 Undercount Deduction (pre-script)
+#### 2b. Apply State 2 Undercount Deduction (pre-script)
 
-If `analysis_confidence == 'provenance-map'` (State 2) AND step-03 recorded a provenance vs metadata divergence > 5% (see §4b in step-03), apply a 10-point deduction to `exportCoverage` BEFORE building the scoring input:
+If `analysis_confidence == 'provenance-map'` (State 2) AND step 3 recorded a provenance vs metadata divergence > 5% (see §4b in step 3), apply a 10-point deduction to `exportCoverage` BEFORE building the scoring input:
 
 ```
 exportCoverage_adjusted = max(0, exportCoverage - 10)
@@ -81,7 +79,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": "{custom_threshold or omit for default 80}"
+  "threshold": "{effective_threshold from §1 — CLI --threshold wins, then workflow.default_threshold scalar, then 80}"
 }
 ```
 
@@ -90,10 +88,10 @@ Build a JSON object from the data gathered in steps 1-2:
 #### 3b. Run the Scoring Script
 
 ```bash
-python3 {scoringScript} '<JSON>'
+echo '<JSON>' | uv run {scoringScript} --stdin
 ```
 
-Where `{scoringScript}` is the path resolved from the frontmatter variable (relative to the skill root, i.e., the skf-test-skill/ directory).
+Where `{scoringScript}` is the path resolved from the frontmatter variable (relative to the skill root, i.e., the skf-test-skill/ directory). The script also accepts the JSON as a positional argument (`uv run {scoringScript} '<JSON>'`) or via `--json-input '<JSON>'`; `--stdin` is preferred since it avoids shell-quote escaping of nested JSON.
 
 Parse the JSON output. The script returns:
 - `weights` — final redistributed weights per category
@@ -127,9 +125,9 @@ Report: "**Note:** Scoring script unavailable — calculated manually per scorin
 
 The scoring script returns `totalScore` and a preliminary `result`. Two caps may override the script's PASS into FAIL — applied in this order, and ONLY if the script did NOT return INCONCLUSIVE (floor always takes precedence):
 
-**Cap 1 — Tooling degraded (B3):** if `analysisConfidence == "degraded"` or `toolingStatus` indicates a missing helper (`python3-missing`, `frontmatter-validator-missing`), set `effective_score = min(totalScore, threshold - 1)` and record `scoring_notes: tooling degraded — capped below threshold until helper restored`.
+**Cap 1 — Tooling degraded:** if `analysisConfidence == "degraded"` or `toolingStatus` indicates a missing helper (`python3-missing`, `frontmatter-validator-missing`), set `effective_score = min(totalScore, threshold - 1)` and record `scoring_notes: tooling degraded — capped below threshold until helper restored`.
 
-**Cap 2 — Docs-only without external validators (S4):** if `docsOnly == true` AND `externalValidation` score was null (neither skill-check nor tessl ran), set `effective_score = min(effective_score, threshold - 1)` and record `scoring_notes: docs-only without external validators — capped below threshold per S4`.
+**Cap 2 — Docs-only without external validators:** if `docsOnly == true` AND `externalValidation` score was null (neither skill-check nor tessl ran), set `effective_score = min(effective_score, threshold - 1)` and record `scoring_notes: docs-only without external validators — capped below threshold`.
 
 If either cap fired and `result` was `PASS`, change it to `FAIL`. If `result` was already `INCONCLUSIVE`, leave it — the evidence-floor verdict is never overridden by a cap.
 
@@ -147,7 +145,7 @@ IF score < threshold        → FAIL
 - `active_categories < 2` (after all redistribution), OR
 - `tier == "Quick"` AND Export Coverage is the sole scoring contributor
 
-**Tooling-degraded cap (B3):** If the `analysisConfidence` in output frontmatter is `degraded` (python3 missing, frontmatter validator missing, or other degraded state flagged in step-01), 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.
+**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.
 
 ### 5. Determine Next Workflow Recommendation
 
@@ -155,12 +153,12 @@ Based on test result:
 
 **IF PASS:**
 - `nextWorkflow: 'export-skill'` — skill is ready for export
-- **M5 — drift override:** if workflow context carries
-  `allow_workspace_drift: true` (set in step-01 §5b when the user passed
+- **Drift override:** if workflow context carries
+  `allow_workspace_drift: true` (set in step 1 §5b when the user passed
   `--allow-workspace-drift` AND the workspace HEAD did not match
   `metadata.source_commit`), the PASS is a **conditional PASS**:
   - Write `testResult: 'pass-with-drift'` to the output frontmatter instead of
-    bare `'pass'`. The result contract (§4c of step-06) mirrors the same
+    bare `'pass'`. The result contract (§4c of step 6) mirrors the same
     value.
   - Override `nextWorkflow` to `'update-skill'` — **refuse to recommend
     `export-skill`**. The drift override weakens the workflow's strongest
@@ -221,12 +219,12 @@ If `analysis_confidence` is not `full`, append a degradation notice. **The notic
 ### 7. Update Output Frontmatter
 
 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 M5)
+- `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}%'`
 - `analysisConfidence: '{full|degraded|provenance-map|metadata-only|remote-only|docs-only}'`
 - `nextWorkflow: '{export-skill|update-skill|manual-review}'`
-- Append `'step-05-score'` to `stepsCompleted`
+- Append `'score'` to `stepsCompleted`
 
 ### 8. Report Score
 
@@ -247,20 +245,5 @@ Update `{outputFile}` frontmatter:
 
 **Proceeding to gap report...**"
 
-### 9. Auto-Proceed
-
-Display: "**Proceeding to gap report...**"
-
-#### Menu Handling Logic:
-
-- After score is calculated and frontmatter updated, immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed scoring step with no user choices
-- Proceed directly to next step after score is determined
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the score is calculated, pass/fail is determined, the Completeness Score section is appended to {outputFile}, and frontmatter is updated with testResult and score, will you then load and read fully `{nextStepFile}` to execute gap report generation.
+Update stepsCompleted, then load and execute {nextStepFile}.
 

package/src/skf-test-skill/references/scoring-rules.md

@@ -1,3 +1,5 @@
+<!-- Config: communicate in {communication_language}. -->
+
 # Scoring Rules
 
 ## Default Threshold
@@ -44,7 +46,7 @@ tessl evaluates SKILL.md body content only — it does not read `references/*.md
 
 ### Docs-Only Mode (all [EXT:...] citations, any tier)
 
-When `docs_only_mode: true` is set by step-03 (indicating a skill where all SKILL.md citations are `[EXT:...]` format with no local source code):
+When `docs_only_mode: true` is set by step 3 (indicating a skill where all SKILL.md citations are `[EXT:...]` format with no local source code):
 
 - **Signature Accuracy:** Not scored (no source to compare against)
 - **Type Coverage:** Not scored (no source to compare against)
@@ -54,7 +56,7 @@ When `docs_only_mode: true` is set by step-03 (indicating a skill where all SKIL
 
 This is functionally identical to Quick tier weight redistribution but with a different coverage denominator (self-consistency instead of source comparison).
 
-**S4 external-validator requirement for docs-only:** docs-only mode removes two categories (Signature Accuracy, Type Coverage) from scoring. If External Validation is ALSO unavailable, the evidence base collapses to Coverage alone (naive) or Coverage + Coherence (contextual) — which in the naive/Quick case trips the minimum-evidence floor (INCONCLUSIVE). To keep docs-only skills gradable when external validators are present but still deterministic when they are missing: **when `docsOnly: true` AND `externalValidation is null`, step-05 MUST cap `totalScore` at `threshold - 1` (forcing FAIL) before the INCONCLUSIVE floor is evaluated.** This prevents a docs-only skill from PASSing with only one or two redistributed categories carrying all the weight. Implement in step-05 §4 as a pre-compare cap, recorded in the report as `scoring_notes: docs-only without external validators — capped below threshold per S4`.
+**External-validator requirement for docs-only:** docs-only mode removes two categories (Signature Accuracy, Type Coverage) from scoring. If External Validation is ALSO unavailable, the evidence base collapses to Coverage alone (naive) or Coverage + Coherence (contextual) — which in the naive/Quick case trips the minimum-evidence floor (INCONCLUSIVE). To keep docs-only skills gradable when external validators are present but still deterministic when they are missing: **when `docsOnly: true` AND `externalValidation is null`, step 5 MUST cap `totalScore` at `threshold - 1` (forcing FAIL) before the INCONCLUSIVE floor is evaluated.** This prevents a docs-only skill from PASSing with only one or two redistributed categories carrying all the weight. Implement in step 5 §4 as a pre-compare cap, recorded in the report as `scoring_notes: docs-only without external validators — capped below threshold`.
 
 ### Stack Skills (Any Tier)
 
@@ -64,7 +66,7 @@ When `metadata.json.skill_type == "stack"` (set `stackSkill: true` in the scorin
 - **Type Coverage:** N/A — same rationale; the type surface belongs to the external libraries.
 - **Weight redistribution:** Same as Quick tier / docs-only / State 2 — Signature Accuracy (22%) and Type Coverage (14%) weights redistributed proportionally to remaining active categories (Export Coverage, Coherence, External Validation).
 - **Applies regardless of detected tier** (Quick, Forge, Forge+, Deep) and is independent of `docsOnly` and `state2`. A stack skill can also be docs-only or State 2; the skip reasons combine additively (e.g. `"stack skill (external type surface) + State 2 (provenance-map)"`).
-- **Detection:** step-05 reads `metadata.json.skill_type` from the skill package. If the value is `"stack"`, set `stackSkill: true` in the scoring input JSON.
+- **Detection:** step 5 reads `metadata.json.skill_type` from the skill package. If the value is `"stack"`, set `stackSkill: true` in the scoring input JSON.
 
 Equivalence-class note: stack skills with `docsOnly:false` / `state2:false` map to the same equivalence class as State 2 contextual rows (class B) or State 2 naive rows (class D) — the redistribution math is identical; only the `skipReasons` string changes.
 
@@ -80,7 +82,7 @@ When source is not locally available and analysis resolves to State 2 (provenanc
 
 Note: When provenance-map entries are predominantly T1 (AST-verified at compilation time), the coverage and name-matching data is already at highest confidence. The N/A categories reflect the inability to re-verify at test time, not low-quality extraction data.
 
-**S9 State 2 undercount risk acknowledgement:** provenance-map is a cached extraction snapshot — if the source has evolved since extraction, public API adds/removes will NOT surface in Export Coverage (denominator is frozen to the provenance-map union). When `state2: true` AND step-03 records any provenance vs metadata divergence (e.g. union > either source by >5%), apply a flat **10% deduction** to `exportCoverage` before calling the scoring script, AND set `analysis_confidence: provenance-map` (already set) with a report note: `scoring_notes: State 2 undercount risk acknowledged — 10% deduction applied to Export Coverage`. Rationale: the skill cannot be reliably scored on a frozen denominator when the cache is known to disagree with its own metadata; prefer understating over overstating.
+**State 2 undercount risk acknowledgement:** provenance-map is a cached extraction snapshot — if the source has evolved since extraction, public API adds/removes will NOT surface in Export Coverage (denominator is frozen to the provenance-map union). When `state2: true` AND step 3 records any provenance vs metadata divergence (e.g. union > either source by >5%), apply a flat **10% deduction** to `exportCoverage` before calling the scoring script, AND set `analysis_confidence: provenance-map` (already set) with a report note: `scoring_notes: State 2 undercount risk acknowledged — 10% deduction applied to Export Coverage`. Rationale: the skill cannot be reliably scored on a frozen denominator when the cache is known to disagree with its own metadata; prefer understating over overstating.
 
 ### Forge Tier (ast-grep)
 - Export Coverage: AST-backed export comparison
@@ -98,7 +100,7 @@ Note: When provenance-map entries are predominantly T1 (AST-verified at compilat
 - Cross-repository reference verification
 - QMD knowledge enrichment for coherence
 - Full scoring formula with maximum depth
-- **Migration & Deprecation Warnings section:** If T2-future annotations exist in the enrichment data, verify that Section 4b is present in SKILL.md Tier 1 and that each warning traces to a T2 provenance citation. If no T2-future annotations exist, Section 4b should normally be absent (not empty). Presence/absence mismatch is a Medium severity gap — with one Info-severity exception for historical-migration content (completed package renames, consolidated import paths, shipped API cutovers that remain load-bearing for training-data drift remediation). See `steps-c/step-04-coherence-check.md` §2b/§5b for the three-case rule.
+- **Migration & Deprecation Warnings section:** If T2-future annotations exist in the enrichment data, verify that Section 4b is present in SKILL.md Tier 1 and that each warning traces to a T2 provenance citation. If no T2-future annotations exist, Section 4b should normally be absent (not empty). Presence/absence mismatch is a Medium severity gap — with one Info-severity exception for historical-migration content (completed package renames, consolidated import paths, shipped API cutovers that remain load-bearing for training-data drift remediation). See `references/coherence-check.md` §2b/§5b for the three-case rule.
 
 ## Redistribution Combinations Matrix (M3 — terminology + determinism)
 
@@ -179,7 +181,7 @@ Three-state gate — **PASS / FAIL / INCONCLUSIVE**. `INCONCLUSIVE` is not PASS
   - `active_categories` = count of categories with a non-zero final weight *after* all redistribution (Quick tier, docs-only, State 2, external-validator-unavailable). Categories with a redistributed weight of 0 do not count as active, even if they received a score.
   - **If `active_categories < 2`** → force `result: INCONCLUSIVE` with rationale `"insufficient evidence: only {N} active category"`. A single active category cannot cross-validate itself and a PASS would be a false signal.
   - **If `tier == "Quick"` AND the sole active contributor is Export Coverage** → force `result: INCONCLUSIVE` with rationale `"Quick tier: Export Coverage alone is insufficient evidence — add a second active category by upgrading tier or enabling external validators"`. This catches the degenerate case where every signature/type/coherence/external category gets redistributed to 0 and Export Coverage is doing all the work.
-  - The floor is enforced by `scripts/compute-score.py`. The step-05 scoring step reads `result` from the script output and writes it into the test report frontmatter unchanged.
+  - The floor is enforced by `scripts/compute-score.py`. The step 5 scoring step reads `result` from the script output and writes it into the test report frontmatter unchanged.
 
 - Otherwise:
   - score >= threshold → PASS

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

@@ -1,3 +1,5 @@
+<!-- Config: communicate in {communication_language}. -->
+
 # Source Access Protocol
 
 ## Source API Surface Definition
@@ -14,7 +16,7 @@
 
   **Resolution order:**
 
-  1. **Prefer `metadata.json.stats.effective_denominator`** when present. `skf-create-skill` step-05 §4 writes this field for stratified-scope skills. When set, use it directly as the `exports_public_api` count for coverage scoring.
+  1. **Prefer `metadata.json.stats.effective_denominator`** when present. `skf-create-skill` step 5 §4 writes this field for stratified-scope skills. When set, use it directly as the `exports_public_api` count for coverage scoring.
   2. **Fall back to live re-derivation** when `effective_denominator` is absent (older skills, quick-tier output, or skills compiled before this rule existed). Read the brief's scope globs from `forge-data/{skill_name}/skill-brief.yaml`, resolve them against `source_path`, filter out files matching `scope.exclude`, and compute the source API surface as the **union of named exports across the matched files only**. The skill brief's `scope.notes` field should document the stratification strategy (e.g., "Tier A: fully documented; Tier B: deferred to references; Tier C: excluded") — when present, treat it as confirmation that the curated subset is by design, not a scope gap.
 
      **Honor `scope.tier_a_include` when present.** When re-deriving, prefer the brief-level `scope.tier_a_include` narrow include list over the coarse `scope.include`. `tier_a_include` is an optional brief field that lists only the authoring surface the brief actually intends to document (tier A), letting the denominator match the brief's authoring-vs-installing intent even when `scope.include` uses coarse globs that also match internal infrastructure. When `tier_a_include` is present, resolve its globs (still filtered by `scope.exclude`), compute the union across those files, and use that count as the denominator. When absent, fall back to resolving `scope.include`.
@@ -38,7 +40,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 if `scope.type: "reference-app"` exists in the enum (pending upgrade in `skf-create-skill/steps-c/step-03-extract.md`) — in that case the brief speaks for itself and 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 `public-api` / `specific-modules` / `component-library` / `docs-only` (those scope types have their own denominator semantics). Also does NOT apply if `scope.type: "reference-app"` exists in the enum (pending upgrade in `skf-create-skill/references/extract.md`) — in that case the brief speaks for itself and this clause's filesystem trigger is moot.
 
 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).
 
@@ -87,7 +89,7 @@ Check `{forge_data_folder}/{skill_name}/provenance-map.json`. If present AND con
 - Build the coverage denominator from the **union** of provenance-map entry names and metadata.json `exports[]` names. Exports present in metadata but absent from provenance-map are counted as "missing documentation" in the coverage calculation.
 - If metadata.json is unavailable or has no `exports[]` array, use provenance-map count alone with a note: "Coverage denominator is provenance-map only — may undercount if extraction was incomplete." If remote reading tools are available (zread, deepwiki, gh API, or similar), supplement by reading the entry point file for live signature verification. Set `analysis_confidence: provenance-map`.
 
-**State 2 limitations:** Signature verification at State 2 is **string comparison only**, not semantic. Provenance-map stores parameters as flat string arrays (e.g., `["data: Union[BinaryIO, list, str]"]`), so `str` vs `String` or `list` vs `List[Any]` would be treated as mismatches even when semantically equivalent. For full type-aware verification (handling type aliases, generic equivalence), State 1 (local source) with AST re-parsing is required. When the SKILL.md was compiled from the same provenance-map (typical for create-then-test flows), most strings will match. However, enrichment (step-04) and doc-fetching (step-03c) during compilation may alter parameter descriptions, add type annotations, or normalize signatures, causing mismatches even in create-then-test flows. Expect some string-level mismatches and treat them as compilation artifacts, not source drift signals, until signature fidelity is enforced by step-05's Signature Fidelity Rule (see `signature_source` field in provenance-map entries).
+**State 2 limitations:** Signature verification at State 2 is **string comparison only**, not semantic. Provenance-map stores parameters as flat string arrays (e.g., `["data: Union[BinaryIO, list, str]"]`), so `str` vs `String` or `list` vs `List[Any]` would be treated as mismatches even when semantically equivalent. For full type-aware verification (handling type aliases, generic equivalence), State 1 (local source) with AST re-parsing is required. When the SKILL.md was compiled from the same provenance-map (typical for create-then-test flows), most strings will match. However, enrichment (step 4) and doc-fetching (step 3c) during compilation may alter parameter descriptions, add type annotations, or normalize signatures, causing mismatches even in create-then-test flows. Expect some string-level mismatches and treat them as compilation artifacts, not source drift signals, until signature fidelity is enforced by step 5's Signature Fidelity Rule (see `signature_source` field in provenance-map entries).
 
 **State 3 — No provenance-map, metadata exports exist (quick-skill path):**
 If no provenance-map.json exists (typical for quick-skill output), fall back to `metadata.json`'s `exports[]` array for the export name list. Coverage check becomes a self-consistency comparison: are all names in `exports[]` documented in SKILL.md with description, parameters, and return type? Signatures cannot be verified. If remote reading tools are available, supplement by reading the entry point for live export comparison. Set `analysis_confidence: metadata-only`.
@@ -96,9 +98,9 @@ If no provenance-map.json exists (typical for quick-skill output), fall back to
 If neither provenance-map nor metadata exports provide a usable baseline, but remote reading tools (zread, deepwiki, gh API, or similar) are available and `source_repo` is set in metadata.json, read the entry point remotely to build the export inventory from scratch. Name-matching only — no AST. Set `analysis_confidence: remote-only`.
 
 **State 5 — No source access at all:**
-If none of the above succeed, fall through to docs-only mode (as defined in step-03-coverage-check.md Section 0: pre-analysis source type detection). Set `analysis_confidence: docs-only`. Warn: "**No source access available.** Coverage check evaluates documentation self-consistency only. Re-run with local clone or remote access for source-backed verification."
+If none of the above succeed, fall through to docs-only mode (as defined in coverage-check.md Section 0: pre-analysis source type detection). Set `analysis_confidence: docs-only`. Warn: "**No source access available.** Coverage check evaluates documentation self-consistency only. Re-run with local clone or remote access for source-backed verification."
 
-Set `analysis_confidence` in context for use in Section 2 analysis depth, step-05 output, and step-05 scoring.
+Set `analysis_confidence` in context for use in Section 2 analysis depth, step 5 output, and step 5 scoring.
 
 **Confidence tier mapping:** `full` = T1, `provenance-map` = T1, `metadata-only` = T1-low, `remote-only` = T1-low, `docs-only` = T3. This aligns with the T1/T1-low/T2/T3 scale used across all SKF workflows.
 

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

@@ -8,11 +8,34 @@ Pure-function scoring script for the SKF test-skill workflow (step-05).
 Implements the weight tables, skip conditions, and proportional redistribution
 defined in scoring-rules.md.
 
-CLI: python3 compute-score.py '<JSON>'
+CLI usage:
+  uv run compute-score.py '<JSON>'                  # JSON literal as positional arg
+  uv run compute-score.py --json-input '<JSON>'     # explicit flag form
+  cat input.json | uv run compute-score.py --stdin  # piped input
+
+Input schema (one object):
+  {
+    "mode": "contextual" | "naive",
+    "tier": "Quick" | "Forge" | "Forge+" | "Deep",
+    "scores": {
+      "exportCoverage": <0-100>,
+      "signatureAccuracy": <0-100>,
+      "typeCoverage": <0-100>,
+      "coherence": <0-100>,
+      "externalValidation": <0-100>
+    },
+    "threshold": <0-100, optional, default 80>,
+    "evidenceCount": <int, optional, used for INCONCLUSIVE floor>
+  }
+
+Exit codes:
+  0  — score computed (verdict may be PASS/FAIL/INCONCLUSIVE)
+  1  — input error (bad JSON, missing fields, schema violation)
 """
 
 from __future__ import annotations
 
+import argparse
 import json
 import math
 import sys
@@ -286,25 +309,73 @@ def compute_score(inp):
 
 # --- CLI Entry Point ---
 
-if __name__ == "__main__":
-    if len(sys.argv) < 2:
-        print("Usage: python3 compute-score.py '<JSON>'", file=sys.stderr)
-        print(
-            'Example: python3 compute-score.py \'{"mode":"contextual","tier":"Deep",'
-            '"scores":{"exportCoverage":92,"signatureAccuracy":85,"typeCoverage":100,'
-            '"coherence":80,"externalValidation":78}}\'',
-            file=sys.stderr,
-        )
-        sys.exit(1)
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="compute-score",
+        description=(
+            "Deterministic Completeness Score calculator. Input is a single JSON "
+            "object describing mode, tier, scores, and optional threshold/evidence "
+            "count; output is the verdict + redistributed score breakdown."
+        ),
+        epilog=(
+            "Example:\n"
+            "  uv run compute-score.py "
+            "'{\"mode\":\"contextual\",\"tier\":\"Deep\","
+            "\"scores\":{\"exportCoverage\":92,\"signatureAccuracy\":85,"
+            "\"typeCoverage\":100,\"coherence\":80,\"externalValidation\":78}}'"
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    src = parser.add_mutually_exclusive_group()
+    src.add_argument(
+        "json_input",
+        nargs="?",
+        help="JSON object as a positional argument (single-quote it on the shell).",
+    )
+    src.add_argument(
+        "--json-input",
+        dest="json_input_flag",
+        help="JSON object passed via flag (overrides positional).",
+    )
+    src.add_argument(
+        "--stdin",
+        action="store_true",
+        help="Read the JSON object from stdin.",
+    )
+    return parser
+
+
+def _resolve_input(args: argparse.Namespace) -> str:
+    if args.stdin:
+        return sys.stdin.read()
+    if args.json_input_flag is not None:
+        return args.json_input_flag
+    if args.json_input is not None:
+        return args.json_input
+    return ""
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    raw = _resolve_input(args)
+    if not raw.strip():
+        parser.print_usage(file=sys.stderr)
+        print("error: no input provided (positional arg, --json-input, or --stdin)", file=sys.stderr)
+        return 1
 
     try:
-        data = json.loads(sys.argv[1])
-    except json.JSONDecodeError:
-        print(
-            json.dumps(make_error(f"Invalid JSON: {sys.argv[1][:100]}"), indent=2)
-        )
-        sys.exit(1)
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        print(json.dumps(make_error(f"Invalid JSON: {exc.msg}"), indent=2))
+        return 1
 
     result = compute_score(data)
     print(json.dumps(result, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
     sys.exit(1 if "error" in result else 0)