bmad-module-skill-forge 2.0.0 → 2.0.1

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

@@ -11,6 +11,9 @@ feasibilitySchemaProbeOrder:
 atomicWriteProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+validateFeasibilityReportProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-validate-feasibility-report.py'
+  - '{project-root}/src/shared/scripts/skf-validate-feasibility-report.py'
 nextStepFile: 'health-check.md'
 ---
 
@@ -25,7 +28,7 @@ Present the complete feasibility report to the user. Display the overall verdict
 ## Rules
 
 - Focus only on presenting the completed report — no new analysis or changes to verdicts
-- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing report is NOT the terminal step
+- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing report is not the terminal step
 
 ## MANDATORY SEQUENCE
 
@@ -35,11 +38,24 @@ Read the entire `{outputFile}` to have all data available for presentation.
 
 **Resolve `{feasibilitySchemaRef}`** from `{feasibilitySchemaProbeOrder}`; first existing path wins (installed SKF module path first, dev-checkout `src/` fallback).
 
-Verify all expected sections are present in order per `{feasibilitySchemaRef}`: `## Executive Summary`, `## Coverage Analysis`, `## Integration Verdicts`, `## Recommendations`, `## Evidence Sources`. If any section is missing or out of order, HALT (exit code 5, `halt_reason: "schema-violation"`) and report the schema violation — do not display partial results. In headless, emit the error envelope per SKILL.md "Result Contract (Headless)" with `report_path: "{outputFile}"`, `overall_verdict: null`.
+**Validate report structure and schema version (deterministic gate).** Resolve `{validateFeasibilityReportHelper}` from `{validateFeasibilityReportProbeOrder}`; first existing path wins (installed SKF module path first, dev-checkout `src/` fallback). Then run:
 
-**Extract metrics from `{outputFile}` frontmatter** (per shared schema in `{feasibilitySchemaRef}`): `skillsAnalyzed`, `coveragePercentage`, `pairsVerified` (as `verified_count`), `pairsPlausible` (as `plausible_count`), `pairsRisky` (as `risky_count`), `pairsBlocked` (as `blocked_count`), `requirementsFulfilled` (as `fulfilled_count`), `requirementsPartial` (as `partial_count`), `requirementsNotAddressed` (as `not_addressed_count`), `requirementsPass`, `overallVerdict`, and `recommendationCount`. Use these mapped display names in the summary table and next steps below.
+```bash
+python3 {validateFeasibilityReportHelper} {outputFile}
+```
+
+The script (see `--help`) deterministically confirms the five required body sections — `## Executive Summary`, `## Coverage Analysis`, `## Integration Verdicts`, `## Recommendations`, `## Evidence Sources` — are all present and in canonical order per `{feasibilitySchemaRef}`, **and** that frontmatter `schemaVersion == "1.0"`. It emits a JSON verdict on stdout (`headingsOk`, `missingHeadings`, `orderViolations`, `schemaVersionOk`, `schemaVersionFound`, `violation`) and exits `0` when valid, `1` on a schema violation, `2` on an IO/parse error.
+
+**Graceful degradation:** if no `{validateFeasibilityReportProbeOrder}` candidate exists (e.g. partial installation, or `python3` unavailable), perform the equivalent structural check inline — confirm the five headings above are all present and in that exact order, and that frontmatter `schemaVersion` is `"1.0"` — and apply the same halt semantics below. The report is already on disk from steps 1-5, so a missing validator degrades to the inline check rather than blocking presentation.
+
+On any non-zero exit (or an inline check that fails), HALT (exit code 5, `halt_reason: "schema-violation"`) — do not display partial results. Report the specific violation from the JSON:
 
-**Schema guard:** Verify `schemaVersion == "1.0"` in the frontmatter. If mismatched, HALT (exit code 5, `halt_reason: "schema-violation"`) with "Report frontmatter schemaVersion `{value}` does not match producer schema `1.0` — report was corrupted between steps. Re-run [VS]." (Producer never proceeds past a schema mismatch.) In headless, emit the error envelope.
+- a missing or out-of-order section (`missingHeadings` / `orderViolations`); or
+- a schemaVersion mismatch — "Report frontmatter schemaVersion `{schemaVersionFound}` does not match producer schema `1.0` — report was corrupted between steps. Re-run [VS]." (Producer never proceeds past a schema mismatch.)
+
+In headless, emit the error envelope per SKILL.md "Result Contract (Headless)" with `report_path: "{outputFile}"`, `overall_verdict: null`.
+
+With the deterministic gate passed (sections present + in order, `schemaVersion == "1.0"`), **extract metrics from `{outputFile}` frontmatter** (per shared schema in `{feasibilitySchemaRef}`): `skillsAnalyzed`, `coveragePercentage`, `pairsVerified` (as `verified_count`), `pairsPlausible` (as `plausible_count`), `pairsRisky` (as `risky_count`), `pairsBlocked` (as `blocked_count`), `requirementsFulfilled` (as `fulfilled_count`), `requirementsPartial` (as `partial_count`), `requirementsNotAddressed` (as `not_addressed_count`), `requirementsPass`, `overallVerdict`, and `recommendationCount`. Use these mapped display names in the summary table and next steps below.
 
 ### 2. Present Summary
 
@@ -76,37 +92,17 @@ Walk through the highlights — coverage gaps, risky/blocked integrations, and p
 
 ### 4. Present Next Steps
 
-Based on the overall verdict, present the appropriate recommendation:
-
-**IF `overallVerdict == "FEASIBLE"`:**
-"**Your stack is verified.** All technologies are covered, integrations are compatible, and requirements are all fulfilled (or requirements pass was skipped).
-
-**Recommended next steps:**
-1. **[RA] Refine Architecture** — Produce an implementation-ready architecture document enriched with skill-backed API details
-2. **[SS] Create Stack Skill** — compose your individual skills into a unified stack skill, providing the refined architecture doc when prompted
-3. **[TS] Test Skill** → **[EX] Export Skill** — Verify completeness and package for distribution"
-
-**IF `overallVerdict == "CONDITIONALLY_FEASIBLE"`:**
-"**Your stack is conditionally feasible.** There are {recommendationCount} items to address before proceeding.
-
-**Required actions:**
-{List the specific recommendations from Step 05 synthesis}
-
-**After addressing these items:** Re-run **[VS] Verify Stack** to confirm resolution, then proceed to **[RA]**."
-
-**IF `overallVerdict == "NOT_FEASIBLE"`:**
-"**Critical blockers must be resolved.** The stack cannot support the architecture as described.
-
-**Critical actions:**
-{List the blocked integration recommendations and missing skill actions from Step 05}
+Step 05 already wrote a **Suggested next workflow** block (keyed on the case-sensitive `overallVerdict` token) at the end of `## Recommendations`. Surface that block from the §1 load rather than re-deriving it, prefixed with the one-line verdict-specific framing:
 
-**After resolving blockers:** Re-run **[VS] Verify Stack**. Repeat until verdict improves to FEASIBLE or CONDITIONALLY FEASIBLE."
+- **`FEASIBLE`:** "**Your stack is verified.** All technologies are covered, integrations are compatible, and requirements are all fulfilled (or requirements pass was skipped)."
+- **`CONDITIONALLY_FEASIBLE`:** "**Your stack is conditionally feasible.** There are {recommendationCount} items to address before proceeding." — then list the specific recommendations from the report's `## Recommendations` section.
+- **`NOT_FEASIBLE`:** "**Critical blockers must be resolved.** The stack cannot support the architecture as described." — then list the blocked-integration and missing-skill recommendations from the report's `## Recommendations` section.
 
 ### 4b. Result Contract
 
-**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. HALT if no candidate exists.
+**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. If no candidate exists: HALT (exit code 3, `halt_reason: "resolution-failure"`); in headless, emit the error envelope.
 
-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 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.
 
@@ -118,7 +114,7 @@ SKF_VERIFY_STACK_RESULT_JSON: {"status":"success","report_path":"{outputFile}","
 
 `{overallVerdict}` uses the schema tokens (`FEASIBLE` / `CONDITIONALLY_FEASIBLE` / `NOT_FEASIBLE`).
 
-**Result-contract ordering:** The result contract is written exactly once on the first entry to step 6 (the `[X] Exit verification` path). Re-walks of the report via the `[R] Review full report` menu option do NOT regenerate it — the contract captures the run, not the presentation loop. If the user selects `[R]` repeatedly before exiting, the single on-disk contract written on first entry remains authoritative.
+**Result-contract ordering:** The result contract is written exactly once on the first entry to step 6 (the `[X] Exit verification` path). Re-walks of the report via the `[R] Review full report` menu option do not regenerate it — the contract captures the run, not the presentation loop. If the user selects `[R]` repeatedly before exiting, the single on-disk contract written on first entry remains authoritative.
 
 ### 5. Present Menu
 
@@ -133,13 +129,11 @@ Re-run **[VS] Verify Stack** anytime after making changes to your skills or arch
 
 **Verification workflow complete.**"
 
-  Then load, read the full file, and execute `{nextStepFile}` — the health-check step is the true terminal step of this workflow.
+  If `{workflow.on_complete}` is non-empty, execute it now (e.g. route the verdict onward or trigger a downstream step); in headless, log the action. Then load, read the full file, and execute `{nextStepFile}` — the health-check step is the true terminal step of this workflow.
 
 #### EXECUTION RULES:
 
-- ALWAYS halt and wait for user input after presenting the menu
 - **GATE [default: X]** — If `{headless_mode}`: auto-proceed with [X] Exit verification, log: "headless: auto-exit past report menu"
 - R may be selected multiple times — always walk through the full report
-- X triggers the health check, which is the true workflow exit
 
 

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

@@ -28,7 +28,7 @@ If a PRD or vision document was provided in Step 01, verify that the combined ca
 
 ### 1. Check PRD Availability
 
-**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. HALT if no candidate exists.
+**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. If no candidate exists: HALT (exit code 3, `halt_reason: "resolution-failure"`); in headless, emit the error envelope.
 
 **Read `prdAvailable` from `{outputFile}` frontmatter (set in Step 01). If `prdAvailable` is false (no PRD/vision document was provided):**
 
@@ -42,7 +42,7 @@ To include this pass, re-run **[VS]** with a PRD or vision document path.
 
 Update `{outputFile}` frontmatter: append `'requirements'` to `stepsCompleted`; set `requirementsPass: "skipped"`. Pipe the updated content through `python3 {atomicWriteHelper} write --target {outputFile}` and again with `--target {outputFileLatest}`.
 
-Load, read the full file and then execute `{nextStepFile}`. **STOP HERE — do not execute sections 2-6.**
+Load, read the full file and then execute `{nextStepFile}`. The no-PRD path ends here — sections 2-6 are the PRD-present branch and do not run.
 
 **If PRD/vision document was provided:** Continue to section 2.
 
@@ -78,7 +78,7 @@ For each requirement, evaluate whether the combined capabilities of the generate
 - **Partially Fulfilled** — skills provide related capability but gaps remain (specify what is covered and what is not)
 - **Not Addressed** — no skill in the stack provides capability relevant to this requirement
 
-**Each verdict MUST include:**
+**Each verdict includes:**
 - Which skills contribute (if any)
 - Specific exports or capabilities from those skills that are relevant
 - For Partially Fulfilled: what gap remains

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

@@ -1,5 +1,7 @@
 ---
 nextStepFile: 'report.md'
+verdictRollupScript: 'scripts/skf-verdict-rollup.py'
+reportDeltaScript: 'scripts/skf-report-delta.py'
 feasibilitySchemaProbeOrder:
   - '{project-root}/_bmad/skf/shared/references/feasibility-report-schema.md'
   - '{project-root}/src/shared/references/feasibility-report-schema.md'
@@ -27,33 +29,29 @@ Calculate the overall feasibility verdict based on all three analysis passes, ge
 
 ### 1. Calculate Overall Verdict
 
-**Zero-coverage short-circuit (evaluate before anything else):** Read `coveragePercentage` from `{outputFile}` frontmatter. If `coveragePercentage == 0`, force `overallVerdict: NOT_FEASIBLE` with rationale "no coverage — analysis vacuous: zero generated skills match the architecture's referenced technologies, so integration and requirements verdicts cannot produce meaningful evidence." Skip the remainder of the verdict ladder; proceed directly to section 2 to generate recommendations for the Missing and/or Replaced technologies surfaced by Step 02.
+**The verdict token is deterministic — do not walk the ladder in prose.** All three passes have already persisted their counts (`coveragePercentage`, `pairsBlocked`/`pairsRisky`/`pairsPlausible`/`pairsVerified`, `requirementsPass` + `requirementsNotAddressed`/`requirementsPartial` in `{outputFile}` frontmatter; the Missing technology count in the Coverage Analysis table). Rolling those already-decided counts up into one token has a single correct answer per input, so delegate it. Count Missing rows directly from the Coverage table — half-up rounding can leave `coveragePercentage == 100` with one technology still Missing — assemble the counts, and run:
 
-Apply the following decision logic using findings from all completed passes:
+```bash
+echo '<counts JSON>' | uv run {verdictRollupScript} --stdin
+```
 
-**Evaluate in order — the first matching condition wins. Do not continue once a verdict is determined.**
+Input keys: `coveragePercentage`, `missingCount`, `pairsBlocked`, `pairsRisky`, `pairsPlausible`, `pairsVerified`; plus, only when the requirements pass ran (`requirementsPass == "completed"`), `requirementsEvaluated: true` with `requirementsNotAddressed`/`requirementsPartial`; plus `continuedPastZeroState: true` if the user pressed `[C] Continue anyway` past a step-2 zero-state gate (all-Replaced or 0%-coverage). The script (run `uv run {verdictRollupScript} --help` for the contract) returns `overallVerdict` (one of `FEASIBLE`/`CONDITIONALLY_FEASIBLE`/`NOT_FEASIBLE`), `matchedConditions` (the condition codes that fired), and `zeroPairsGuardFired`. If `uv` is unavailable (e.g. claude.ai web), apply the ladder below inline.
 
-**NOT_FEASIBLE (evaluate first):**
-- Any integration is **Blocked** → overall verdict is `NOT_FEASIBLE`
-- Rationale: a blocked integration represents a fundamental architectural incompatibility. Also note in the rationale any co-occurring Missing skills or Risky integrations so the user understands the full set of problems
+**The ladder it applies (documented so the rationale can cite it — the script is the executor; evaluate top-to-bottom, first match wins):**
+- `coveragePercentage == 0` → `NOT_FEASIBLE` (short-circuit: no live coverage, analysis vacuous).
+- Any Blocked integration → `NOT_FEASIBLE` (fundamental architectural incompatibility).
+- Any Missing technology, any Risky integration, or — when requirements ran — any Not Addressed / Partially Fulfilled requirement → `CONDITIONALLY_FEASIBLE`.
+- Otherwise → `FEASIBLE`, but any pair capped at `Plausible` (including Check-4-missing caps) downgrades to `CONDITIONALLY_FEASIBLE`.
+- Post-verdict guard: when all four integration counts are 0 and the user continued past a step-2 zero-state gate, `zeroPairsGuardFired` is true — a `FEASIBLE` verdict is overridden to `CONDITIONALLY_FEASIBLE`.
 
-**CONDITIONALLY_FEASIBLE (evaluate second):**
-If ANY of the following apply, the verdict is `CONDITIONALLY_FEASIBLE`. Include ALL matching conditions in the rationale:
-- Any technology is **Missing** from coverage (no skill exists). Technologies marked **Replaced** in Step 02 are intentionally being removed and do NOT count as Missing — they never trigger CONDITIONALLY_FEASIBLE or a [CS]/[QS] recommendation.
-- Any integration is **Risky** (but none Blocked)
-- Requirements have any **Not Addressed** items
-- Requirements have any **Partially Fulfilled** items
-- Rationale: the stack can work but has gaps, risks, or unverified assumptions that must be addressed
+Technologies marked **Replaced** in Step 02 are intentionally being removed and are already excluded from `missingCount` and the coverage denominator — they never trigger `CONDITIONALLY_FEASIBLE` or a [CS]/[QS] recommendation.
 
-**FEASIBLE (evaluate last):**
-- Coverage is 100% (no Missing skills) AND all integrations are `Verified` AND requirements are all Fulfilled (or requirements pass was skipped) AND no Blocked or Risky integrations AND zero pairs were capped at `Plausible` due to missing Check 4 evidence → overall verdict is `FEASIBLE`
-- If any pair sits at `Plausible` (including Check-4-missing caps), downgrade to `CONDITIONALLY_FEASIBLE`
-- Rationale: {IF requirements pass completed:} the stack can support the architecture as described — all requirements fully fulfilled, every integration pair has a literal cross-reference. {IF requirements pass was skipped:} the stack can support the architecture as described — requirements were not evaluated (no PRD provided)
-
-**Post-verdict: Zero integration pairs guard (apply after ANY verdict):**
-If zero integration pairs were extracted (all four integration counts are 0), fire the guard whenever the user continued past the step 2 `[C] Continue anyway` prompt (i.e., any `[C]` continuation from 0% coverage or any other zero-state) — regardless of how many technologies the architecture document references:
-- If the verdict was `FEASIBLE`, override to `CONDITIONALLY_FEASIBLE`
-- Regardless of verdict, append this note to the rationale: "No integration claims were found in the architecture document prose. Manual review recommended to confirm that technology relationships are not documented exclusively in diagrams or implied without explicit co-mention."
+**Write the rationale** from `matchedConditions`, naming the specific findings behind each code:
+- `zero-coverage` → "no coverage — analysis vacuous: zero generated skills match the architecture's referenced technologies, so integration and requirements verdicts cannot produce meaningful evidence." Then proceed directly to section 2 to generate recommendations for the Missing and/or Replaced technologies surfaced by Step 02.
+- `blocked-integration` → a blocked integration is a fundamental architectural incompatibility; name each Blocked pair and note any co-occurring `missing-coverage`/`risky-integration` codes so the user sees the full set of problems.
+- `missing-coverage` / `risky-integration` / `requirements-not-addressed` / `requirements-partial` / `plausible-cap` → the stack can work but has gaps, risks, or unverified assumptions that must be addressed; name the specific items behind each code.
+- No codes (`FEASIBLE`) → {IF requirements pass completed:} the stack can support the architecture as described — all requirements fully fulfilled, every integration pair has a literal cross-reference. {IF requirements pass was skipped:} the stack can support the architecture as described — requirements were not evaluated (no PRD provided).
+- `zero-integration-pairs` (present whenever the guard fired, regardless of verdict) → append: "No integration claims were found in the architecture document prose. Manual review recommended to confirm that technology relationships are not documented exclusively in diagrams or implied without explicit co-mention."
 
 Store the verdict for use in the report.
 
@@ -66,7 +64,7 @@ For each non-verified finding across all passes, generate an actionable next ste
 
 **Replaced / being-removed technology (from Step 02):**
 - "`{library_name}` is marked for removal/replacement in the architecture document — no skill is needed. Remove it from the architecture document (or, if it is in fact staying, correct the document to drop the removal marker), then re-run **[VS]**."
-- Do NOT emit a [CS]/[QS] recommendation for a Replaced technology — forging a skill for a technology that is being deleted is exactly the misfire this category prevents.
+- Do not emit a [CS]/[QS] recommendation for a Replaced technology — forging a skill for a technology that is being deleted is exactly the misfire this category prevents.
 
 **Risky integration (from Step 03):**
 - If protocol mismatch → "Consider adding a bridge layer between `{lib_a}` and `{lib_b}` (e.g., HTTP adapter, message queue). Document the bridge in the architecture."
@@ -89,18 +87,20 @@ For each non-verified finding across all passes, generate an actionable next ste
 
 ### 3. Check for Previous Report
 
-Read `previousReport` from `{outputFile}` frontmatter (set in Step 01). Since the current workflow run overwrites the report starting in Step 01, the delta feature requires the user to have saved a copy before re-running [VS].
+Read `previousReport` from `{outputFile}` frontmatter (set in Step 01). Each run writes a new timestamped `feasibility-report-{projectSlug}-{timestamp}.md`, so prior reports persist on disk automatically — Step 01 auto-discovers the most recent one for delta comparison when no path is supplied. `previousReport` holds the resolved path, or is empty when no prior report exists or the user skipped the comparison.
 
-**Note:** The delta feature is only available when the user has manually backed up a prior report and provided the path. To enable delta comparisons, instruct the user to copy their feasibility report (e.g., `feasibility-report-{projectSlug}-v1.md`) before re-running [VS], then provide the backup path when prompted in Step 01.
+**Note:** A manual backup is only needed to compare against a *specific older* snapshot rather than the most recent prior run; provide that backup path when prompted in Step 01.
 
 **If a previous report is found:**
-- Load its verdict, coverage percentage, integration verdicts, and per-skill `confidence_tier` values (if captured in the previous report's inventory block)
-- Generate a delta comparison:
-  - **Improved items:** findings that were Risky/Blocked/Missing and are now Verified/Covered
-  - **Regressed items:** findings that were Verified/Covered and are now Risky/Blocked/Missing
-  - **Tier downgrades (regression):** for each skill present in both runs, compare current `confidence_tier` against previous. A downgrade (e.g., Tier 1 → Tier 2, or T1 → T1-low) is a regression — flag explicitly in the delta section with rationale "skill `{skill_name}` regressed from `{prev_tier}` to `{curr_tier}` — re-extract with [CS] at the prior tier level".
-  - **New items:** findings not present in the previous report
-  - **Unchanged items:** count of findings with the same verdict
+- Extract from both reports (current run + the previous report's tables/inventory block): the coverage findings (`{technology, verdict}`), the integration findings (`{libA, libB, verdict}`), and each skill's `confidence_tier`. Reading the tables is judgment; classifying the difference is not — so hand the two extracted finding sets to the delta helper rather than diffing in prose (matching pair keys and applying the verdict ranking by hand drifts between runs).
+- Serialize as `{"previous": {"coverage": […], "integration": […]}, "current": {…}, "previousTiers": {skill: tier}, "currentTiers": {…}}` and run:
+
+  ```bash
+  echo '<delta JSON>' | uv run {reportDeltaScript} --stdin
+  ```
+
+  The script (run `uv run {reportDeltaScript} --help` for the contract and rankings) returns `improved`/`regressed`/`unchanged`/`new`/`dropped`/`replaced` label lists with counts, plus `tierDowngrades` (each `{skill, from, to}`) — a tier drop (Tier 1 → Tier 2, or T1 → T1-low) counts as a regression. If `uv` is unavailable, apply the ranking from `--help` inline (coverage Missing<Covered; integration Blocked<Risky<Plausible<Verified; tier T2<T1-low<T1; Replaced findings bucketed, not scored).
+- Render the delta section from those results. For each tier downgrade, flag: "skill `{skill}` regressed from `{from}` to `{to}` — re-extract with [CS] at the prior tier level".
 
 **If no previous report found:**
 - Note: "First verification run — no delta available."
@@ -129,7 +129,7 @@ Assemble the following for the report:
 
 ### 5. Append to Report
 
-**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. HALT if no candidate exists.
+**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. If no candidate exists: HALT (exit code 3, `halt_reason: "resolution-failure"`); in headless, emit the error envelope.
 
 **Resolve `{feasibilitySchemaRef}`** from `{feasibilitySchemaProbeOrder}`; first existing path wins (installed SKF module path first, dev-checkout `src/` fallback).
 
@@ -141,14 +141,11 @@ Write the **Recommendations** and **Evidence Sources** sections to `{outputFile}
 - Populate `## Evidence Sources` with per-skill citations (SKILL.md path, `metadata_schema_version`, `confidence_tier`, stack manifest if any) and architecture/PRD doc paths
 - Update frontmatter (shared-schema keys):
   - Append `'synthesize'` to `stepsCompleted`
-  - Set `overallVerdict` to one of `FEASIBLE`, `CONDITIONALLY_FEASIBLE`, `NOT_FEASIBLE` (case-sensitive, underscores — NOT spaces)
+  - Set `overallVerdict` to one of `FEASIBLE`, `CONDITIONALLY_FEASIBLE`, `NOT_FEASIBLE` (case-sensitive, underscores not spaces)
   - Set `recommendationCount` to the total number of recommendations
-  - If delta was computed (section 3), set `deltaImproved`, `deltaRegressed`, `deltaNew`, `deltaUnchanged`
+  - If delta was computed (section 3), set `deltaImproved`, `deltaRegressed`, `deltaNew`, `deltaUnchanged` from the delta helper's `improvedCount` / `regressedCount` / `newCount` / `unchangedCount`
   - Verify that `pairsVerified`, `pairsPlausible`, `pairsRisky`, `pairsBlocked` match the counts from Step 03 (these were set in Step 03). If a discrepancy is found, overwrite the frontmatter counts with the values from Step 03 — the report file is the system of record
-- **Overall verdict enforcement (schema producer obligation):**
-  - If any pair has Check 4 missing/weak AND was capped at `Plausible`, that alone does NOT force `NOT_FEASIBLE`, but `FEASIBLE` requires zero such pairs
-  - `FEASIBLE` requires 100% coverage AND zero Blocked pairs AND zero Check-4-missing pairs — otherwise downgrade to `CONDITIONALLY_FEASIBLE`
-  - `coveragePercentage == 0` forces `NOT_FEASIBLE` (per section 1 short-circuit)
+- **Overall verdict enforcement (schema producer obligation):** write the `overallVerdict` the §1 rollup script returned verbatim — do not re-derive the ladder here. §1 (via `{verdictRollupScript}`) is its single source of truth (the 100%-coverage + zero-Blocked + zero-Check-4-missing bar for `FEASIBLE`, and the `coveragePercentage == 0` → `NOT_FEASIBLE` short-circuit included).
 - Pipe the updated full content through `python3 {atomicWriteHelper} write --target {outputFile}` and again with `--target {outputFileLatest}`
 
 ### 6. Auto-Proceed to Next Step

package/src/skf-verify-stack/scripts/skf-coverage-tally.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# dependencies = []
+# ///
+"""Deterministic technology-coverage tally for skf-verify-stack (coverage.md §6).
+
+The coverage verdicts themselves (Covered / Missing / Replaced) are LLM judgment
+— matching an architecture technology to a generated skill involves aliases and
+prose. This script takes that already-decided coverage matrix and does only the
+part with one correct answer: counting each verdict class and turning the counts
+into `coveragePercentage`.
+
+Two gotchas make the in-prose version drift between runs, so they live here
+instead:
+
+  * The denominator excludes Replaced. `live_count = Covered + Missing`;
+    technologies flagged Replaced (intentionally being removed) are not a gap and
+    must not dilute the percentage.
+  * Rounding is pinned to half-up to the nearest integer, so the same matrix
+    always yields the same `coveragePercentage` (the shared schema declares
+    `coveragePercentage: <0..100 integer>` but not the rounding rule).
+
+CLI usage:
+  uv run skf-coverage-tally.py '<JSON>'                  # JSON literal positional
+  uv run skf-coverage-tally.py --json-input '<JSON>'     # explicit flag form
+  cat input.json | uv run skf-coverage-tally.py --stdin  # piped input
+
+Input schema (one object):
+  {
+    "rows": [
+      {"technology": "react",   "verdict": "Covered"},
+      {"technology": "postgres","verdict": "Missing"},
+      {"technology": "old-orm", "verdict": "Replaced"}
+    ]
+  }
+
+Output (stdout, one object):
+  {
+    "covered_count": <int>,
+    "missing_count": <int>,
+    "replaced_count": <int>,
+    "live_count": <int>,          # Covered + Missing (denominator)
+    "total_referenced": <int>,    # all rows after dedup
+    "coverage_percentage": <int>  # round-half-up(covered/live*100); 0 when live==0
+  }
+
+Exit codes:
+  0  — tally emitted successfully
+  1  — no input / input could not be parsed as JSON
+  2  — input parsed but schema/semantics invalid (error object emitted as JSON)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import sys
+
+VALID_VERDICTS = ("Covered", "Missing", "Replaced")
+
+
+def make_error(message):
+    return {"error": message, "code": "INVALID_INPUT"}
+
+
+def _validate(inp):
+    if inp is None or not isinstance(inp, dict):
+        return "Input must be a JSON object"
+    rows = inp.get("rows")
+    if not isinstance(rows, list):
+        return "Missing or invalid required field: rows (must be a list)"
+    seen = set()
+    for i, row in enumerate(rows):
+        if not isinstance(row, dict):
+            return f"rows[{i}] must be an object"
+        tech = row.get("technology")
+        if not isinstance(tech, str) or not tech.strip():
+            return f"rows[{i}] requires a non-empty string `technology`"
+        verdict = row.get("verdict")
+        if verdict not in VALID_VERDICTS:
+            return (
+                f"rows[{i}] verdict {verdict!r} is not one of: "
+                f"{', '.join(VALID_VERDICTS)}"
+            )
+        norm = tech.strip().lower()
+        if norm in seen:
+            return f"duplicate technology {tech!r} — the coverage list must be deduplicated first"
+        seen.add(norm)
+    return None
+
+
+def tally(inp):
+    """Pure tally. Counts each verdict class and computes coverage_percentage."""
+    err = _validate(inp)
+    if err:
+        return make_error(err)
+
+    covered = missing = replaced = 0
+    for row in inp["rows"]:
+        verdict = row["verdict"]
+        if verdict == "Covered":
+            covered += 1
+        elif verdict == "Missing":
+            missing += 1
+        else:  # Replaced
+            replaced += 1
+
+    live = covered + missing
+    percentage = math.floor(covered / live * 100 + 0.5) if live > 0 else 0
+    return {
+        "covered_count": covered,
+        "missing_count": missing,
+        "replaced_count": replaced,
+        "live_count": live,
+        "total_referenced": covered + missing + replaced,
+        "coverage_percentage": percentage,
+    }
+
+
+# --- CLI --------------------------------------------------------------------
+
+
+def _build_parser():
+    parser = argparse.ArgumentParser(
+        prog="skf-coverage-tally",
+        description=(
+            "Deterministic technology-coverage tally (coverage.md §6). Counts "
+            "Covered/Missing/Replaced verdicts and computes coveragePercentage "
+            "with Replaced excluded from the denominator and half-up rounding."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=(
+            "Example:\n"
+            "  uv run skf-coverage-tally.py "
+            "'{\"rows\":[{\"technology\":\"react\",\"verdict\":\"Covered\"},"
+            "{\"technology\":\"postgres\",\"verdict\":\"Missing\"}]}'"
+        ),
+    )
+    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):
+    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=None):
+    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(raw)
+    except json.JSONDecodeError as exc:
+        print(json.dumps(make_error(f"Invalid JSON: {exc.msg}"), indent=2))
+        return 1
+
+    result = tally(data)
+    print(json.dumps(result, indent=2))
+    if isinstance(result, dict) and result.get("code") == "INVALID_INPUT":
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())