bmad-module-skill-forge 2.2.0 → 4.0.0

package/src/shared/health-check.md

@@ -16,7 +16,7 @@ liveSubmitSeverities: ['bug']  # friction/gap go local-queue-default with explic
 
 Reflect on the workflow that just completed. If real friction, bugs, or gaps were encountered in the SKF workflow instructions, capture them as structured findings for the user to review and optionally submit as GitHub issues.
 
-**Zero overhead for clean runs.** If nothing went wrong, say so and exit immediately.
+**Zero overhead for clean runs.** If nothing went wrong, say so (or, on an envelope-only run, display only the setup envelope — see §0) and exit immediately.
 
 ## MANDATORY EXECUTION RULES:
 
@@ -24,17 +24,8 @@ Reflect on the workflow that just completed. If real friction, bugs, or gaps wer
 - Read the complete step file before taking any action
 - Speak in `{communication_language}`
 
-### Role Reinforcement:
-- You are a **self-improvement auditor** — honest, precise, evidence-based
-- You report ONLY what you actually experienced during THIS session
-- You are NOT a creative writer looking for things to say
-
-### Anti-Hallucination Rules:
-- **DO NOT FABRICATE ISSUES.** If the workflow ran smoothly, say so and exit. Inventing issues to appear thorough is a SYSTEM FAILURE.
-- Only report issues you **ACTUALLY encountered** during THIS workflow execution
-- Every finding MUST cite the **specific step file path and section** where the issue occurred
-- If you are unsure whether something was a real issue or your own confusion, DO NOT report it
-- Reporting zero issues is the EXPECTED outcome for a well-designed workflow
+### Findings Rule:
+Zero findings is the expected outcome of a good run. Report only a bug, friction or gap you hit in this session, each with the step file and section where it happened, and leave out anything you cannot tell apart from your own confusion: a finding you invent can become a real GitHub issue filed against the module.
 
 ---
 
@@ -42,11 +33,15 @@ Reflect on the workflow that just completed. If real friction, bugs, or gaps wer
 
 ### 0. Announce Arrival
 
+**Envelope-only runs.** Treat `{quiet_mode}` as true only when the workflow that loaded this step is skf-setup and it set `{quiet_mode}` to true. In every other case (unset, another workflow ran, or the user asked for this health check directly) treat it as false. skf-setup sets it under `--quiet` or in headless mode because its result envelope must be the only line setup displays. When it is true, this whole step displays nothing of its own and writes no text between tool calls: skip this announcement and its headless log, and queue any findings locally through **[Q]** without presenting them (§3, §4). Wherever it stops (the clean-run stop in §2, or the end of §5c), it displays skf-setup's `{setup_envelope_line}` verbatim after every tool call, with no code fence and nothing of this step's own before or after it (nothing at all if that line is empty). In a standalone setup run that line is the final message, because `claude -p` prints only the final message. When `{pipeline_mode}` is true, skf-setup is one step of a forger pipeline: control then returns to the forger, which keeps chaining.
+
+**Result envelope line.** Any other workflow may bind `{result_envelope_line}` before it loads this step, in headless mode only (Brief Skill also in an `[auto]` run), to the result envelope line its run printed through the shared emitter (its `SKF_<NAME>_RESULT_JSON: ...` line; skf-test-skill's report step binds its `SKF_TEST_RESULT_JSON` line). When it is bound and not empty, wherever this step stops (the clean-run stop in §2, or the end of §5c) it displays that line verbatim as its very last line, after everything else it displays, with no code fence and nothing after it. In a standalone headless run, such as `claude -p`, which prints only the final message, that line is then the final message a pipeline reads. A workflow that binds nothing gets nothing extra.
+
 **Display in `{communication_language}`:**
 
 "**Running a quick self-improvement check on this workflow.** If nothing rough came up, I'll close out immediately."
 
-**GATE [default: skip]** — If `{headless_mode}`: skip the display entirely, log: "headless: skipped health-check arrival announcement".
+**GATE [default: skip]** — If `{quiet_mode}` is true: skip the display and log nothing. Otherwise, if `{headless_mode}`: skip the display entirely, log: "headless: skipped health-check arrival announcement".
 
 **If interactive:** display the line above, then proceed to step 1 (Read Workflow Context) without waiting. The line is informational, not a commitment gate — the user's commitment to continuing was already captured upstream (either via an explicit menu in the calling step or by auto-chain). This announcement just tells them what is about to happen.
 
@@ -68,16 +63,20 @@ Silently review the workflow execution. Ask yourself:
 
 **If the answer to ALL of these is "no":**
 
-Display:
+If `{quiet_mode}` is true, display only `{setup_envelope_line}` (§0). Otherwise display:
 
 "**Health Check: Clean run.** No workflow issues to report.
 
 Workflow complete."
 
+When `{result_envelope_line}` is bound (§0), display it verbatim after that, as the last line.
+
 **STOP HERE. Do not proceed further. The workflow is done.**
 
 ### 3. Present Findings (Only If Issues Exist)
 
+**If `{quiet_mode}` is true:** do not present the findings. Go to §4, which chooses **[Q]** without displaying anything, so every finding, whatever its severity, is written to the local queue per §5c and nothing is submitted to GitHub.
+
 For each genuine finding, present it in this format:
 
 "**Workflow Health Check — {N} finding(s)**
@@ -112,13 +111,16 @@ For each genuine finding, present it in this format:
 
 ### 4. User Review Gate
 
-After presenting all findings, ask:
+**GATE [default: Q]** — If `{quiet_mode}` is true, choose **[Q]** without displaying anything. Otherwise, if `{headless_mode}` is true, choose **[Q]** and log: "headless: queued {N} finding(s) locally". In both cases skip the question below and go to Menu Handling: live submission always needs an interactive **[Y]**.
+
+**If interactive:** after presenting all findings, ask:
 
 "**Submit these findings?**
 
 - **[Y]** Yes — submit all findings
 - **[N]** No — discard all findings
 - **[E]** Edit — let me revise before submitting
+- **[Q]** Queue locally — save every finding to {localFallbackFolder}/, submit nothing
 
 _You are the final filter. Reject any finding that doesn't reflect a real issue you observed._"
 
@@ -129,6 +131,7 @@ _You are the final filter. Reject any finding that doesn't reflect a real issue
 - **IF Y:** Proceed to step 5
 - **IF N:** Display "Findings discarded. Workflow complete." — STOP
 - **IF E:** Let user specify which findings to keep, modify, or remove. Then re-present the revised list and ask again.
+- **IF Q:** Compute each finding's fingerprint as §5a sub-step 1 describes, then write every finding, whatever its severity, to the local queue per §5c — STOP after §5c
 
 ### 5. Route Each Finding by Severity
 
@@ -149,6 +152,12 @@ fp="fp-$(printf '%s|%s|%s|%s' "{severity}" "{workflow}" "{step_file}" "{section-
 
 The `section-slug` is a kebab-case normalized section heading (e.g. `missing-staging-path`). Never include line numbers — they drift when files are edited.
 
+`sha1sum` is not on stock macOS or Windows. On macOS, use `shasum -a 1` in its place. Anywhere neither exists, this prints the same 7 hex characters, to prefix the same way:
+
+```
+uv run python -c "import hashlib,sys; print(hashlib.sha1(sys.argv[1].encode()).hexdigest()[:7])" "{severity}|{workflow}|{step_file}|{section-slug}"
+```
+
 **2. Check the local seen-cache** at `{seenCachePath}`:
 
 Read `{seenCachePath}`. A missing file, an empty file, or one that does not parse as JSON is an empty cache — never an error, never a reason to halt.
@@ -246,7 +255,6 @@ After the issue is created, write the fingerprint → issue-url mapping to the s
 - **Respect the length budgets.** Finding, Expected, Actual, Impact are each ONE sentence. Evidence is 2-5 bullets, not prose. Suggested Fix is 1-3 sentences with ONE recommendation — multiple options go in the `Alternatives considered` collapsible or (better) not at all.
 - **Quote, don't paraphrase.** In Evidence, cite the exact `file:line` and put the quoted text in quotes. Link the convention to the instruction that caused it.
 - **Never narrate the session.** The reader wants the defect, not the story. If a sentence starts with "During my run..." or "I was trying to...", delete it.
-- **If unsure whether it's a real issue, do not submit it.** Reporting zero findings is a healthy outcome.
 
 **Issue body format:**
 ```markdown
@@ -290,7 +298,7 @@ After the issue is created, write the fingerprint → issue-url mapping to the s
 
 ## Suggested Fix
 <!-- ONE recommended change. 1-3 sentences. Do NOT list multiple options here. -->
-{e.g. Add a rule to step 5 naming `_bmad-output/{skill-name}/` as the staging directory used by step 6 validation.}
+{e.g. Add a rule to step 5 naming `_bmad-output/.skf-stage/{skill-name}/` as the staging directory used by step 6 validation.}
 
 <details>
 <summary>Alternatives considered (optional)</summary>
@@ -339,11 +347,11 @@ Ensure the parent directory exists. This file is global across the user's machin
 
 **The `action` vocabulary is `created`, `reacted`, `commented`, `resolved`.** The first three are written by this workflow. `resolved` is written by hand when the defect is fixed, and it is the only one that does not suppress. See the health-check section of `CONTRIBUTING.md` for when to record it.
 
-### 5c. Local-Queue Path (gh unavailable OR friction/gap default)
+### 5c. Local-Queue Path (gh unavailable, friction/gap default, or Queue locally)
 
-For findings that didn't go live (gh unavailable, user declined the friction/gap opt-in, or user chose **\[S]** at the dedup gate), write a local file to `{localFallbackFolder}/`:
+For findings that didn't go live (gh unavailable, user declined the friction/gap opt-in, user chose **\[S]** at the dedup gate, or the §4 review gate resolved to **\[Q]**), write a local file to `{localFallbackFolder}/`:
 
-**Filename:** `hc-{workflow}-{timestamp}.md` (one file per finding, timestamp as YYYYMMDD-HHmmss)
+**Filename:** `hc-{workflow}-{timestamp}.md` (one file per finding, timestamp as YYYYMMDD-HHmmss; when findings share a timestamp, append `-2`, `-3`, … to the later names so no file is overwritten)
 
 **File content:** Same structured format as the issue body above, with YAML frontmatter:
 
@@ -358,52 +366,16 @@ date: {ISO date}
 ---
 ```
 
-After writing all files, display:
+After writing all files, if `{quiet_mode}` is true, display only `{setup_envelope_line}` (§0) and stop. Otherwise display the block below. `{reason}` is the sentence that says why the findings stayed local: "GitHub CLI is not available.", "Friction and gap findings stay local unless you opt in.", "You skipped these at the dedup gate." or "The review gate queued these locally."
 
 "**{N} finding(s) saved locally:**
 {list each file path}
 
-GitHub CLI is not available. To submit these as issues, run:
+{reason} To submit these as issues, run:
 `gh issue create --repo {healthCheckRepo} --title \"[title]\" --body-file {file-path}`
 
 Or open them manually at: <https://github.com/{healthCheckRepo}/issues/new/choose>
 
 Workflow complete."
 
----
-
-## CRITICAL STEP COMPLETION NOTE
-
-This is the TERMINAL step — shared across all SKF workflows. After the health check completes (clean run or findings submitted/discarded), the workflow is fully done. No further steps to load.
-
----
-
-## SYSTEM SUCCESS/FAILURE METRICS
-
-### SUCCESS:
-
-- Clean runs exit immediately with no findings (most common outcome)
-- Findings cite specific step files and sections with real evidence
-- User review gate presented before any submission
-- Severity gate respected: only `bug` submits live by default; `friction`/`gap` require explicit opt-in
-- Fingerprint computed deterministically and applied to both title prefix and `fp-*` label
-- `fp-*` label is ensured idempotently (`gh label create ... || true`) before `gh issue create`, so a first reporter of a defect never hard-fails
-- Remote dedup search performed before every live submission; existing issues get reactions/delta-comments rather than duplicates
-- Seen-cache at `{seenCachePath}` updated after every submission/reaction and consulted before every search
-- Local fallback files written with clear manual submission instructions (when `gh` unavailable)
-- Workflow ends cleanly
-
-### SYSTEM FAILURE:
-
-- Fabricating issues that were not actually encountered during the session
-- Reporting vague issues without step file citations ("the workflow was confusing")
-- Skipping the user review gate
-- Creating issues without user confirmation
-- Creating a new issue when a matching `fp-*` open issue already exists (without explicit user \[N] override)
-- Submitting `friction` or `gap` findings live without the explicit severity-gate opt-in
-- Using LLM-judged "similarity" in place of the deterministic fingerprint
-- Not updating the seen-cache, causing the same user to re-report identical fingerprints
-- Not providing the local fallback when `gh` is unavailable
-- Continuing to load steps after this one (this is terminal)
-
-**Master Rule:** Honesty is the only policy. Zero findings is the expected, healthy outcome. Fabricating issues to appear thorough undermines the entire self-improvement system and constitutes SYSTEM FAILURE.
+When `{result_envelope_line}` is bound (§0), display it verbatim after that block, as the last line.

package/src/shared/references/description-guard-protocol.md

@@ -4,9 +4,9 @@
 
 External validators (`skill-check check --fix`, `skill-check split-body`, and any future tool that may rewrite SKILL.md frontmatter) occasionally replace, truncate, or otherwise mutate the `description` field — sometimes substituting a generic version, sometimes re-introducing angle-bracket tokens that earlier sanitization removed.
 
-The on-disk description is **authoritative**: it has been compiled (in `skf-create-skill`) or merged (in `skf-update-skill`) with deliberate trigger-optimization. Losing it to a tool's well-meaning rewrite breaks agent discovery quality and can re-introduce the angle-bracket failure mode that breaks tessl on the next run.
+The on-disk description is **authoritative**: it has been compiled (in `skf-create-skill`) or merged (in `skf-update-skill`) with deliberate trigger-optimization. Losing it to a tool's well-meaning rewrite breaks agent discovery quality and can re-introduce angle brackets that create-skill removed, which the Claude platform does not accept in a skill description (it cannot contain XML tags).
 
-Any tool invocation that may touch SKILL.md must run inside the four-phase guard below. Workflows invoke the deterministic phases (1, 3, 4) via `src/shared/scripts/skf-description-guard.py`; the LLM only performs phase 2 (the tool call itself).
+Any tool invocation that may touch SKILL.md must run inside the four-phase guard below. Workflows invoke the deterministic phases (1, 3, 4) via `skf-description-guard.py`, which each calling step resolves as `{descriptionGuardHelper}` from its `descriptionGuardProbeOrder` (installed SKF module path first, src/ dev-checkout fallback); the LLM only performs phase 2 (the tool call itself).
 
 ## The Four-Phase Guard
 
@@ -15,7 +15,7 @@ Any tool invocation that may touch SKILL.md must run inside the four-phase guard
 Before invoking the tool, snapshot the on-disk `description` value:
 
 ```bash
-uv run {project-root}/src/shared/scripts/skf-description-guard.py \
+uv run {descriptionGuardHelper} \
     capture <skill-md-path>
 ```
 
@@ -39,11 +39,13 @@ Run the tool as specified in its section. The LLM performs this step normally
 After the tool completes, run:
 
 ```bash
-uv run {project-root}/src/shared/scripts/skf-description-guard.py \
+uv run {descriptionGuardHelper} \
     verify-restore <skill-md-path> \
     --captured-description "{guarded_description}"
 ```
 
+In place of `--captured-description`, `--captured-file <path>` reads the snapshot from a JSON file's `description`: redirect `capture`'s output into the run folder (`capture <skill-md-path> > <run-folder>/description-guard.json`) and pass that file, so the value never passes through context or a shell string. quick-skill calls it this way. An empty or whitespace-only `description` in the file is refused like an empty `--captured-description` (below), and so is a file the helper cannot read or that holds no string `description`.
+
 The script:
 
 1. Re-reads on-disk `description`
@@ -61,7 +63,7 @@ Output JSON:
 }
 ```
 
-If `restored == true`, also update the in-context copy of `description` to match `guarded_description` so subsequent stages do not work from a stale tool-mutated version. Record `description_guard_restored: true` (with the tool name) in workflow context for the evidence report.
+If `restored == true`, also update the in-context copy of `description` to match `guarded_description` so subsequent stages do not work from a stale tool-mutated version. Record `description_guard_restored: true` (with the tool name and the `diff_kind`) in workflow context for the evidence report.
 
 **Empty snapshot refusal.** The helper exits 1 and leaves the file untouched when `--captured-description` is empty or whitespace-only. There is nothing to restore from: either `guarded_description` was lost from context between capture and verify, or the field was already empty before the tool ran. Never retry with the empty value — writing it back would blank the field the guard exists to protect. If the compiled description is still available in context (the in-context SKILL.md copy), re-run `verify-restore` with that value. Otherwise record `description_guard_restored: false` and `description_guard_refused: empty-capture` (with the tool name) in workflow context; the calling stage's evidence-report populator renders that as a fired guard (`Restored: false`, the triggering tool, `Original description preserved: false`, `Notes: guard refused — empty captured snapshot (empty-capture)`) rather than as the all-`—` clean-run state, and the frontmatter validator surfaces the empty field through the normal artifact path.
 
@@ -84,19 +86,20 @@ Splitting on whitespace and comparing token lists catches replaced words, trunca
 
 ## Post-Restore Re-Validation (Optional)
 
-Skills that run frontmatter compliance checks (e.g. `skf-create-skill validate.md`) should additionally re-validate the restored description against the frontmatter contract after restore — a restored value must still satisfy length limits, forbidden-token rules, and required-field shape. Run:
+Skills that run frontmatter compliance checks (e.g. `skf-create-skill validate.md`) should additionally re-validate the restored description against the frontmatter contract after restore — a restored value must still satisfy the length limit and required-field shape. (create-skill also checks the final description for angle brackets, in its validate §6, after every tool has run.) Run the frontmatter validator the calling step resolves (create-skill resolves `{frontmatterValidator}` from its `frontmatterValidatorProbeOrder`):
 
 ```bash
-uv run {project-root}/src/shared/scripts/skf-validate-frontmatter.py <skill-md-path>
+uv run {frontmatterValidator} <skill-md-path>
 ```
 
 If the validator reports failure for the `description` field, flip the Schema row in the evidence report back to `FAIL` and record `description_guard_revalidation: FAIL` with the validator diagnostic. Do not halt — let the failure surface through the normal artifact path so step health-check and the result contract record it.
 
 ## Why This Protocol Is Centralized
 
-Previously, each tool invocation in each calling stage carried its own copy of the capture/verify/restore prose. Duplicated defensive logic drifts: a fix in one section did not propagate to the other, and adding a new tool invocation required remembering to copy the pattern. Centralizing the protocol gives every calling stage one place to update when external validator behavior changes.
+Previously, each tool invocation in each calling stage carried its own copy of the capture/verify/restore prose. Duplicated defensive logic drifts: a fix in one section did not propagate to the other, and adding a new tool invocation required remembering to copy the pattern. This file is the maintainers' reference for the guard, and no stage loads this file at run time. The rules each calling stage acts on, the restore handling and the empty-snapshot refusal, are also stated in the stage's §0 (quick-skill states them beside its one guarded call): change them there, and keep this file in step.
 
 ## Calling Workflows
 
 - `src/skf-create-skill/references/validate.md` — wraps `skill-check check --fix` (§2) and `split-body` (§4). Runs the optional post-restore re-validation.
-- `src/skf-update-skill/references/write.md` — wraps `skill-check check --fix` and `skill-check split-body --write` in §7. Does not run post-restore re-validation today; the post-write checks in §1 catch downstream issues.
+- `src/skf-update-skill/references/write.md`: wraps `skill-check check --fix` and `skill-check split-body --write` in §7, then re-checks the [MANUAL] blocks. Does not run post-restore re-validation.
+- `src/skf-quick-skill/references/write-and-validate.md`: wraps `skill-check check --fix` in §4, which also states the restore and empty-snapshot rules. With no guard helper it runs skill-check without `--fix`. Does not run post-restore re-validation.

package/src/shared/references/feasibility-report-schema.md

@@ -1,6 +1,6 @@
 # Feasibility Report Schema
 
-**Purpose:** Canonical contract shared between `skf-create-stack-skill` (consumer) and `skf-verify-stack` (producer). Any change here must be applied to both skills in lockstep.
+**Purpose:** Canonical contract shared between `skf-verify-stack` (producer) and the skills that read its report, `skf-refine-architecture` and `skf-create-stack-skill` (consumers). Any change here must be applied to the producer and every consumer in lockstep.
 
 ## Filename
 
@@ -8,7 +8,9 @@
 {forge_data_folder}/feasibility-report-{project_slug}-{YYYYMMDD-HHmmss}.md
 ```
 
-`{project_slug}` is the slugified `project_name` (lowercase, hyphens only, no unicode). A stable `feasibility-report-{project_slug}-latest.md` copy (not symlink) is written next to the timestamped file for pipeline consumers.
+`{project_slug}` is `project_name` slugified by one rule: NFKD-decompose it and drop the combining marks (so `Café` gives `cafe`), drop any letter or digit that has no ASCII form, lowercase the rest, turn every run of other characters (spaces, punctuation, symbols) into one hyphen, and trim hyphens from both ends. A name that leaves nothing, an empty one included, gets the slug `project`. A stable `feasibility-report-{project_slug}-latest.md` copy (not symlink) is written next to the timestamped file for pipeline consumers.
+
+`skf-validate-feasibility-report.py` (in `{project-root}/_bmad/skf/shared/scripts/`, or `{project-root}/src/shared/scripts/` in a dev checkout) holds the slug rule, so no skill derives the file name by hand. `--locate "{forge_data_folder}" --project-name "{project_name}"` applies the rule and reads only the `-latest` copy (a timestamped file can be a halted run's partial report). Given a report path instead, the script checks and reads that file the same way and prints the same JSON, so a consumer reads a path its user gives through the script too. Both modes check the required sections and `schemaVersion`, and return `path` and `schemaVersion` for any report they read; for a `1.0` report they also return `generatedAt`, `overallVerdict`, `coveragePercentage`, `coverageMeasured`, `pairVerdicts` (from the canonical table under `## Integration Verdicts`) and `unknownTokens`. `--locate` adds `projectName`, `projectSlug` and `latestPath`. `coverageMeasured` is true only when `stepsCompleted` lists `coverage` and `coveragePercentage` is a whole percentage: the producer writes `coveragePercentage: 0` when a run starts, so a run that stopped earlier holds a 0 that was never measured. `--locate` exits 0 with `status: "ok"`, or with `status: "not-found"` when the project has no `-latest` report. Both modes exit 1 when a required section is missing or out of order, the report's `schemaVersion` is not `"1.0"`, its canonical table is missing or there twice (`duplicateVerdictTableLine` gives the second one's line), or a verdict token is unknown, and 2 when the report cannot be read. Either mode also exits 2 on a usage error, which prints no JSON: a missing `--project-name`, an empty folder, or a stray argument such as an unquoted path that holds a space.
 
 ## Frontmatter (required)
 
@@ -39,18 +41,18 @@ Exactly one of:
 
 | Token | Meaning | Required evidence |
 |---|---|---|
-| `Verified` | All compatibility checks pass with declared evidence in both skills | Documentation cross-reference (Check 4) MUST pass with literal substring/name citation; language + protocol + type checks all pass |
-| `Plausible` | Checks pass but at least one relies on inferred rather than declared evidence | Language + protocol + type checks pass; Check 4 weak or missing |
-| `Risky` | At least one check produced incompatibility that a workaround may resolve | Any single check fails; workaround cited in recommendation |
+| `Verified` | Every compatibility check passes, and at least one of the two skills cites the other literally | Documentation cross-reference (Check 4) MUST pass with a literal substring/name citation in at least one direction; language + protocol + type checks all pass |
+| `Plausible` | Every check passes except the documentation cross-reference: neither skill cites the other literally | Language + protocol + type checks pass; Check 4 weak or missing (no literal citation) |
+| `Risky` | At least one check produced incompatibility that a workaround may resolve | The language, protocol or type check fails (a missing Check 4 citation caps at `Plausible` instead); workaround cited in recommendation |
 | `Blocked` | Fundamental incompatibility that cannot be worked around | Language mismatch, protocol mismatch with no bridge, or type mismatch with no adapter |
 
 ## Overall verdict tokens (case-sensitive)
 
 Exactly one of `FEASIBLE`, `CONDITIONALLY_FEASIBLE`, `NOT_FEASIBLE`.
 
-- `FEASIBLE` — 100% coverage AND zero Blocked pairs AND zero pairs with Check 4 missing.
-- `NOT_FEASIBLE` — Any Blocked pair OR zero coverage.
-- `CONDITIONALLY_FEASIBLE` — Everything else.
+- `FEASIBLE`: every live technology is Covered (100% coverage; a technology marked Replaced is not live), every integration pair is `Verified`, at least one integration pair exists when there are two or more live technologies, and, when the requirements pass ran, every requirement is Fulfilled.
+- `NOT_FEASIBLE`: any `Blocked` pair, or zero coverage.
+- `CONDITIONALLY_FEASIBLE`: everything else. This includes a run that found no integration pair across two or more live technologies: those integrations were never checked, so they are not known to be compatible.
 
 ## Body section headings (required, in order)
 
@@ -62,24 +64,28 @@ Exactly one of `FEASIBLE`, `CONDITIONALLY_FEASIBLE`, `NOT_FEASIBLE`.
 ## Evidence Sources
 ```
 
-Consumers grep for `## Integration Verdicts` to locate the pair table. The table header is fixed:
+Consumers read the pair table under `## Integration Verdicts` through the script (see Filename). The table header is fixed:
 
 ```markdown
 | lib_a | lib_b | verdict | rationale |
 ```
 
+Only this table carries the per-pair verdicts, and the report holds it exactly once. The script fails on a report with a second one (a filled table appended below the report template's empty one, say), skips any table in fenced code or an HTML comment, and does not read the display table with more columns that may follow for human readers.
+
 ## Producer obligations (skf-verify-stack)
 
 - Set `schemaVersion: "1.0"` in frontmatter.
+- Write the `-latest` copy only after the finished report passes `skf-validate-feasibility-report.py`, and write nothing but the timestamped report before that, so a run that halts leaves the previous finished copy, the one `--locate` reads, in place.
 - Never emit a verdict token outside the defined set.
-- When Check 4 (documentation cross-reference) produces weak/missing evidence, cap the per-pair verdict at `Plausible`.
+- Write the canonical table exactly once under `## Integration Verdicts`, with no data rows when the run found no integration pair: fill the empty table in `assets/feasibility-report-template.md` instead of appending a second one.
+- When Check 4 (documentation cross-reference) finds no literal citation, cap the per-pair verdict at `Plausible`. Protocol and data-format tokens inferred from prose (Check 2) can flag a risk, but they neither promote a pair to `Verified` nor cap it at `Plausible`.
 - When `coveragePercentage == 0`, force `overallVerdict: NOT_FEASIBLE` regardless of pair results.
 
-## Consumer obligations (skf-create-stack-skill)
+## Consumer obligations (skf-refine-architecture, skf-create-stack-skill)
 
+- Locate and read the report with `skf-validate-feasibility-report.py --locate` (see Filename), and read a report path the user gives through the same script; never build the file name or parse the report in prose.
 - Verify `schemaVersion == "1.0"`; halt with explicit error on mismatch.
-- Treat any unknown verdict token as a hard error (do not silently drop or map).
-- Use filename pattern above when referencing prior reports.
+- Treat any unknown verdict token (`--locate` lists them in `unknownTokens`) as a hard error (do not silently drop or map).
 
 ## Versioning policy
 

package/src/shared/references/headless-gate-convention.md

@@ -9,14 +9,16 @@ Gates are user interaction points where a workflow pauses for confirmation or in
 Every gate in a step file follows this pattern:
 
 ```
-**GATE: [default action]** — Present [options] to user.
-If `{headless_mode}`: auto-proceed with [default action], log: "headless: auto-[action]".
+**GATE [default: <option>]**: present [options] to the user.
+If `{headless_mode}`: auto-proceed with <option>, log: "headless: auto-<option>".
 ```
 
+A gate with no safe default names its HALT instead: `**GATE [default: HALT]**`, with the HALT's exit code and `halt_reason` where it fires.
+
 The gate always:
 1. Prepares the same output (summary, preview, menu) regardless of mode
 2. In interactive mode: displays the output and waits for user input
-3. In headless mode: displays the output, logs the auto-action, and proceeds with the default
+3. In headless mode: displays the output, logs the auto-action, records it in the run sink (see [Recording Auto-Decisions and Warnings](#recording-auto-decisions-and-warnings)), and proceeds with the default
 
 ## Resolving `{headless_mode}`
 
@@ -27,6 +29,17 @@ The gate always:
 
 Each workflow's On Activation section resolves this variable alongside other config. The forger passes it through when dispatching to workflows.
 
+## Binding Inputs at Activation
+
+Each workflow's On Activation, or its first stage, binds and checks what the run needs, so that a headless run never waits for a reply, makes up a value or widens what it acts on, and an interactive run never asks for what the invocation already said:
+
+1. **Parse every input once.** Bind each input and flag of the workflow's Invocation Contract to a variable, in every mode. An argument the invocation supplies answers its question in an interactive run too. List every input and flag activation parses in the contract, and parse every one the contract lists.
+2. **Validate fail-closed.** Bind a flag's raw value whenever the flag is present (null only when it is absent), and let the script that owns the check reject a wrong value. Halt on a value outside the documented set, with the exit code and the `halt_reason` the workflow's schema gives an invalid input, such as `input-invalid` (Campaign: `invalid-input`; update-skill and setup halt `blocked` at a named phase), and never fall back to a default. Audit-skill's `tier_override` is the one exception: an invalid value falls through to the preferences tier, then the detected one.
+3. **Resolve the emitter before the first prompt.** Resolve the result envelope's emitter, and create the run folder where the workflow keeps one, at activation or at the start of the first stage, so every HARD HALT can emit its envelope. A helper that only a later stage runs may be resolved in that stage; when it is missing, the stage halts with the workflow's `helper-missing` or `resolution-failure` reason (brief-skill's helper halts name no `halt_reason` and emit nothing, as its SKILL.md Halt Contract says).
+4. **Give every gate a default or a coded HALT.** Name each gate's headless default in its `**GATE [default: <option>]**` annotation, and record the decision it takes in the run sink, unless the workflow's contract names where that decision goes instead: Campaign's decision log, brief-skill's log lines (its envelope has no `headless_decisions`), or a field or warning the run already writes, such as Analyze's `coexistence`. A gate with no safe default, such as an input gate whose required input is missing, halts with its exit code and the `halt_reason` the workflow's schema gives a missing input, such as `input-missing` (update-skill and setup halt `blocked` at a named phase).
+
+The workflow's Stages table and its contract's Gates row follow the `GATE` annotations: a stage that holds a gate does not read as auto-proceeding, a stage that waits holds one, and the Gates row names the steps that hold one.
+
 ## Gate Types
 
 ### Confirm Gate (default: Continue)
@@ -55,8 +68,47 @@ For skills that require user input (skill name, target path, etc.), headless mod
 
 Example: `@Ferris QS cocoindex --headless` passes `cocoindex` as the target and skips all gates.
 
+## Recording Auto-Decisions and Warnings
+
+Every run owns a run folder, `_bmad-output/.skf-run/<workflow>-<run_id>/` (`{run_dir}`). Its sink holds what the run decided and noticed without a person, one JSON value per line:
+
+| File | One line per |
+| --- | --- |
+| `headless-decisions.jsonl` | auto-decision: a JSON object shaped like one entry of the workflow's `headless_decisions` |
+| `warnings.jsonl` | warning: a JSON string, such as `"customization_resolver_unavailable: <reason>"` |
+
+A gate appends its decision the moment it decides, and a step appends a warning when it raises it, through the shared emitter rather than by hand. For a decision, stage the object as a file in the run folder first:
+
+```bash
+uv run {emitEnvelopeHelper} record --workflow <workflow> --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"
+uv run {emitEnvelopeHelper} record --run-dir "{run_dir}" --warning "<warning>"
+```
+
+With `--workflow`, a decision the workflow's envelope schema rejects fails here, at the gate; without it, the emitter leaves the decision out when the run ends and adds a `headless_decision_invalid` warning. Because the sink is on disk, the trail survives context compaction, and a HARD HALT reports every decision taken before it.
+
+When the On Activation customization resolver is missing or fails, the run applies only the skill's own `customize.toml`. Record `customization_resolver_unavailable: <reason>` as a warning, or pass the reason in the envelope payload as `customization_resolver_unavailable`, so a pipeline sees that the team and user overrides under `_bmad/custom/` were not applied. Campaign's run spans several sessions, so it logs `customization_resolver_unavailable: <reason>` as an `event` in its decision log instead, and its result envelope's `decision_log` names that file.
+
+## Emitting the Result Envelope
+
+A workflow with a headless contract prints one `SKF_<NAME>_RESULT_JSON: {...}` line when a run ends and at every HARD HALT. The shared emitter builds it; the model never types it. Stage the payload as a file in the run folder, then run one command:
+
+```bash
+uv run {emitEnvelopeHelper} emit --workflow <workflow> --run-dir "{run_dir}" --result-dir "{forge_version}" < "{run_dir}/result-context.json"
+uv run {emitEnvelopeHelper} emit-halt --workflow <workflow> --run-dir "{run_dir}" < "{run_dir}/halt.json"
+```
+
+- `result-context.json` holds the envelope's fields, and optionally the `result_contract` object for the run's result files. `halt.json` holds the halt's `phase`, `reason`, `halt_reason`, `exit_code` and `path`, plus any envelope field the halt already knows, such as the skill name.
+- The emitter stamps what the model must not type: the timestamp from the clock, the run id and the result file path. It folds the sink into `headless_decisions` and `warnings`, derives `exit_code` from `halt_reason`, checks the envelope against the workflow's schema, `shared/scripts/schemas/skf-<name>-result-envelope.v1.json`, and prints the line. Display that line verbatim.
+- With `--result-dir` naming a folder that exists (the version folder), it also writes the run's per-run and `-latest` result files, as `output-contract-schema.md` describes. A halt before that folder exists reports through the line alone.
+- Write the `emit-halt` command at each HARD HALT, naming its phase, `halt_reason` and exit code there, and resolve the helper once at activation, before the first halt can fire. The halt then emits the right line even when the step file that defines the run's success envelope was never loaded, or was compacted away.
+- If the helper exits non-zero or prints no line, display the halt reason alone.
+
+A workflow adopts the emitter by adding its schema under `src/shared/scripts/schemas/`, with the emitter's settings in its `$defs`: an entry `skf-envelope` whose `const` names the workflow, the line's prefix, the status a halt carries, the exit code of each `halt_reason` and the result file name (the emitter's docstring lists the fields). `$defs` and `const` are standard keywords, so a strict validator such as Ajv still compiles the installed schema. skf-setup calls the same helper through its `emit` and `emit-blocked` subcommands, and skf-brief-skill through `skf-emit-brief-result-envelope.py`, which stays as an alias. Like the helper it replaced, the alias refuses no payload for a key the envelope has no field for, or for a typed `exit_code`: it drops the key, derives the code, and says so in the envelope's `warnings`.
+
 ## What Headless Does NOT Skip
 
 - Error halts (hard halts on missing files, invalid state)
 - Progress output (summaries, status updates still display)
 - Quality thresholds (if a step produces output below spec, it still reports the issue)
+
+Exception: skf-setup makes its result envelope the final message of a standalone headless run, so the envelope line is all `claude -p` prints. Under `--headless`, its alias `--quiet`, or `headless_mode: true` in `{sidecar_path}/preferences.yaml`, it skips its progress output, resolves its gates without displaying them, and the health check it chains to adds nothing of its own before that envelope. Inside a forger pipeline it displays the same line and returns control to the forger. skf-setup's `references/invocation-contract.md` states this.

package/src/shared/references/output-contract-schema.md

@@ -9,22 +9,28 @@ Every pipeline-capable skill writes a result JSON file at its final step. This e
   "skill": "skf-skill-name",
   "status": "success" | "failed" | "partial",
   "timestamp": "ISO-8601",
+  "run_id": "<run id>",
   "outputs": [
     {"type": "report|skill|manifest|config", "path": "relative/path/to/file"}
   ],
   "summary": {
     // skill-specific summary fields
-  }
+  },
+  "headless_decisions": [ /* the run's auto-decisions */ ],
+  "warnings": [ /* the run's non-fatal warnings */ ]
 }
 ```
 
+The shared emitter stamps `timestamp` (UTC, from the clock), `run_id` (when the run has a run folder), `headless_decisions` and `warnings` (from the run sink, see `headless-gate-convention.md`) into the record it writes. The workflow supplies the rest.
+
 ## Filenames
 
 Each run writes **two files** to `{output_dir}`:
 
 1. **Per-run record** (audit trail): `{skill-name}-result-{YYYYMMDD-HHmmss}.json`
-   - Timestamp is UTC, resolution to seconds — e.g., `update-skill-result-20260413-145230.json`
-   - Never overwritten by subsequent runs — preserves a durable audit trail across retries, aborts, and re-runs
+   - Timestamp is UTC, resolution to seconds, for example `update-skill-result-20260413-145230.json`
+   - When a run of the same workflow already took that second's name, the emitter appends `-2`, `-3` and so on (`update-skill-result-20260413-145230-2.json`), so two runs that end in the same second never share a file
+   - Never overwritten by subsequent runs, so it keeps a durable audit trail across retries, aborts, and re-runs
 2. **Stable latest pointer** (pipeline consumption): `{skill-name}-result-latest.json`
    - A **copy** (not a symlink) of the per-run record just written
    - Always present at a deterministic path so CI / pipelines / the forger can read `summary.*` without enumerating timestamps
@@ -34,12 +40,17 @@ Write the per-run record first, then copy it to the `-latest.json` path. If the
 
 **Consumers (forger, CI, chained workflows):** read from `{skill-name}-result-latest.json`. Do not enumerate timestamped files unless inspecting prior-run history.
 
-## Available Helpers
+## Writing the Files
 
-There is no generic helper that writes the schema above; each skill assembles the JSON in its terminal step today. One specialised helper exists:
+The shared emitter, `shared/scripts/skf-emit-result-envelope.py`, writes both files when it builds the run's `SKF_<NAME>_RESULT_JSON` envelope (see `headless-gate-convention.md`). Pass the version folder as `--result-dir`:
 
-- **`src/shared/scripts/skf-emit-result-envelope.py`** — `skf-setup`-specific. Writes a different envelope (`SKF_SETUP_RESULT_JSON: {…}`) following the JSON schema at `src/shared/scripts/schemas/skf-setup-result-envelope.v1.json`. Carries setup-specific fields (`tier`, `previous_tier`, `tools`, `ccc_index`, `tier_override_*`, `qmd_status`, etc.) that have no analogue in other workflows. **Do not reuse for non-skf-setup skills.**
+```bash
+uv run {emitEnvelopeHelper} emit --workflow <workflow> --run-dir "{run_dir}" --result-dir "{forge_version}" < "{run_dir}/result-context.json"
+```
 
-A generalised emitter (matching this document's schema) is a reasonable future helper when a second consumer materialises with the same shape. For now, skills that write this contract assemble the JSON in their terminal step — the work is small (5–8 fields) and skill-specific summary content benefits from being expressed inline alongside the rest of the step's logic.
+- The file name's stem comes from the workflow's envelope schema (`result_file` in the emitter settings its `$defs` holds under `skf-envelope`), and the emitter chooses the per-run name, suffix included. A workflow whose settings name no result file writes none, and ignores `--result-dir` with a `result_dir_ignored` warning.
+- The record is the payload's `result_contract` object with the stamped fields above, and with the payload's own `status` and `summary` when the contract leaves them out, so a workflow lists its summary once. A payload without one records the envelope itself, the error variant several workflows write on a HARD HALT (`emit-halt` takes `--result-dir` too).
+- Each file is written atomically, the per-run record first and then its `-latest.json` copy. A write that fails adds a `result_file_write_failed` warning to the envelope, and a failed per-run record also leaves its `result_path` null; the envelope line still prints.
+- When `--result-dir` names no folder that exists, nothing is written: a halt before the version folder exists reports through the envelope line alone.
 
-skf-quick-skill writes both the success-variant contract (`finalize.md` §3) and the error-variant contract on every HARD HALT (per `SKILL.md` § "Result Contract on HARD HALT") in this hand-assembled style.
+Workflows that have not adopted the emitter yet still assemble the record in their terminal step. skf-create-skill writes each brief's record through the emitter from step 8 (`references/report.md`), and a halt's from step 7 on. skf-quick-skill writes both through the emitter: the success-variant contract from `finalize.md` §3's `result_contract`, and the error variant, its envelope, at a HARD HALT once the version folder holds `metadata.json` (`references/halt-contract.md`).