bmad-module-skill-forge 2.1.0 → 3.0.0

package/src/skf-campaign/scripts/campaign-status.py

@@ -1,23 +1,16 @@
 # /// script
-# requires-python = ">=3.9"
+# requires-python = ">=3.11"
 # dependencies = ["pyyaml"]
 # ///
-"""Campaign Status — deterministic state summary + optional backup-drift verdict.
+"""Campaign Status: a deterministic summary of the campaign state.
 
-Collapses two in-prompt determinism leaks into one helper the LLM calls instead
-of hand-deriving:
-
-  - `campaign status` and the resume summary block tallied `skills[]` by status
-    ("N completed / M total, K pending, ...") in-prompt over a 15+ skill array.
-  - the `.bak` recovery path compared `primary` vs `backup` timestamps and stage
-    numbers by hand (an ISO-8601 + int compare across two YAML files).
-
-Both are mechanical, one-correct-answer computations. This script owns them so
-identical state always yields identical output.
+`campaign status` and step-resume's summary block tallied `skills[]` by status
+("N completed / M total, K pending, ...") in the prompt, over a 15+ skill
+array. That count is mechanical, with one correct answer, so this script owns
+it and identical state always yields identical output.
 
 CLI:
   uv run campaign-status.py --state-file <path>
-  uv run campaign-status.py --state-file <path> --backup-file <path>
 
 Output (JSON on stdout):
   {
@@ -25,12 +18,7 @@ Output (JSON on stdout):
     "current_stage": 0,
     "last_updated": "...",
     "total": 0, "completed": 0, "pending": 0,
-    "active": 0, "failed": 0, "skipped": 0,
-    "backup_comparison": null | {
-      "primary_behind": bool,
-      "primary_last_updated": "...", "backup_last_updated": "...",
-      "primary_stage": 0, "backup_stage": 0
-    }
+    "active": 0, "failed": 0, "skipped": 0
   }
 
 Exit codes:
@@ -43,7 +31,6 @@ from __future__ import annotations
 import argparse
 import json
 import sys
-from datetime import datetime
 from pathlib import Path
 from typing import Any, Dict, Optional
 
@@ -68,16 +55,6 @@ def _load_state(path: Path) -> Optional[Dict[str, Any]]:
     return data if isinstance(data, dict) else None
 
 
-def _parse_iso(value: Any) -> Optional[datetime]:
-    if not isinstance(value, str) or not value:
-        return None
-    text = value[:-1] + "+00:00" if value.endswith("Z") else value
-    try:
-        return datetime.fromisoformat(text)
-    except (ValueError, TypeError):
-        return None
-
-
 def _counts(state: Dict[str, Any]) -> Dict[str, int]:
     skills = state.get("skills", []) or []
     tally = {s: 0 for s in STATUSES}
@@ -89,38 +66,7 @@ def _counts(state: Dict[str, Any]) -> Dict[str, int]:
     return tally
 
 
-def _compare_backup(primary: Dict[str, Any], backup: Dict[str, Any]) -> Dict[str, Any]:
-    p_c = primary.get("campaign", {}) or {}
-    b_c = backup.get("campaign", {}) or {}
-    p_updated = p_c.get("last_updated")
-    b_updated = b_c.get("last_updated")
-    p_stage = p_c.get("current_stage")
-    b_stage = b_c.get("current_stage")
-
-    stage_behind = (
-        isinstance(p_stage, int) and isinstance(b_stage, int) and p_stage < b_stage
-    )
-
-    ts_behind = False
-    p_ts = _parse_iso(p_updated)
-    b_ts = _parse_iso(b_updated)
-    if p_ts is not None and b_ts is not None:
-        try:
-            ts_behind = p_ts < b_ts
-        except TypeError:
-            # naive vs aware datetime — cannot order; defer to stage compare.
-            ts_behind = False
-
-    return {
-        "primary_behind": bool(stage_behind or ts_behind),
-        "primary_last_updated": p_updated,
-        "backup_last_updated": b_updated,
-        "primary_stage": p_stage,
-        "backup_stage": b_stage,
-    }
-
-
-def run(state_file: str, backup_file: Optional[str]) -> int:
+def run(state_file: str) -> int:
     state = _load_state(Path(state_file))
     if state is None:
         return _err(f"State not readable as a mapping: {state_file}", "STATE_UNREADABLE")
@@ -131,14 +77,8 @@ def run(state_file: str, backup_file: Optional[str]) -> int:
         "current_stage": campaign.get("current_stage"),
         "last_updated": campaign.get("last_updated"),
         **_counts(state),
-        "backup_comparison": None,
     }
 
-    if backup_file:
-        backup = _load_state(Path(backup_file))
-        if backup is not None:
-            result["backup_comparison"] = _compare_backup(state, backup)
-
     json.dump(result, sys.stdout, separators=(",", ":"), default=str)
     sys.stdout.write("\n")
     return 0
@@ -147,15 +87,11 @@ def run(state_file: str, backup_file: Optional[str]) -> int:
 def main(argv: Optional[list] = None) -> int:
     parser = argparse.ArgumentParser(
         prog="campaign-status",
-        description="Summarize campaign state and (optionally) compare it to its backup.",
+        description="Summarize the campaign state.",
     )
     parser.add_argument("--state-file", required=True, help="Path to _campaign-state.yaml")
-    parser.add_argument(
-        "--backup-file",
-        help="Path to _campaign-state.yaml.bak; when given, emit backup_comparison",
-    )
     args = parser.parse_args(argv)
-    return run(args.state_file, args.backup_file)
+    return run(args.state_file)
 
 
 if __name__ == "__main__":

package/src/skf-campaign/scripts/campaign-validate-pins.py

@@ -1,5 +1,5 @@
 # /// script
-# requires-python = ">=3.9"
+# requires-python = ">=3.11"
 # dependencies = ["pyyaml"]
 # ///
 """Campaign Validate Pins — validate all version pins in a campaign state file.
@@ -37,7 +37,8 @@ Output (JSON on stdout):
 Exit codes:
   0  all valid/resolved
   1  one or more invalid pins
-  2  error (missing files, bad YAML, gh unavailable)
+  2  error (missing files, bad YAML, gh unavailable), or INVALID_BRIEF: a
+     brief that is no mapping, or a target with no name or no repo_url
 """
 
 from __future__ import annotations
@@ -47,7 +48,7 @@ import importlib.util
 import json
 import sys
 from pathlib import Path
-from typing import Any, Dict, List
+from typing import Any, Dict, List, Optional
 
 import yaml
 
@@ -72,6 +73,25 @@ def _load_yaml(path: Path) -> Any:
         return yaml.safe_load(f)
 
 
+def _malformed_target(targets: List[Any]) -> Optional[str]:
+    """Why the first brief target with no name or no repo_url is unusable, or None.
+
+    Names the target by its 1-based number, and by its name when it has one,
+    and says which key it lacks.
+    """
+    for number, target in enumerate(targets, start=1):
+        if not isinstance(target, dict):
+            return f"Brief target {number} is not a mapping"
+        missing = [
+            key for key in ("name", "repo_url")
+            if not (isinstance(target.get(key), str) and target[key].strip())
+        ]
+        if missing:
+            named = "" if "name" in missing else f" ({target['name']})"
+            return f"Brief target {number}{named} has no {' and no '.join(missing)}"
+    return None
+
+
 def run(state_file: str, brief_file: str) -> int:
     state_path = Path(state_file)
     brief_path = Path(brief_file)
@@ -101,10 +121,17 @@ def run(state_file: str, brief_file: str) -> int:
         _emit_error("State file 'skills' is not an array", "INVALID_STATE")
         return 2
 
+    if not isinstance(brief, dict):
+        _emit_error("Brief file is not a YAML mapping", "INVALID_BRIEF")
+        return 2
     targets = brief.get("targets", [])
     if not isinstance(targets, list):
         _emit_error("Brief file 'targets' is not an array", "INVALID_BRIEF")
         return 2
+    malformed = _malformed_target(targets)
+    if malformed is not None:
+        _emit_error(malformed, "INVALID_BRIEF")
+        return 2
 
     name_to_repo: Dict[str, str] = {}
     for target in targets:

package/src/skf-campaign/scripts/campaign-validate-state.py

@@ -1,5 +1,5 @@
 # /// script
-# requires-python = ">=3.9"
+# requires-python = ">=3.11"
 # dependencies = ["pyyaml", "jsonschema>=4.0"]
 # ///
 """Campaign Validate State — schema check for _campaign-state.yaml on disk.
@@ -14,7 +14,11 @@ multi-session campaign.
 Loads the campaign state YAML, validates it against
 `assets/campaign-state-schema.json` (resolved relative to this script unless
 `--schema-file` overrides), and emits skill-friendly error records the calling
-step can forward verbatim.
+step can forward verbatim. A `date-time` field must parse as ISO-8601 with a
+UTC offset (`2026-05-01T00:00:00Z` or `+00:00`): the schema's `format` is only
+an annotation to a JSON Schema validator, so it is checked here, and an
+invented or offset-less timestamp fails instead of misordering the backup
+comparison and the report's durations.
 
 CLI:
   uv run campaign-validate-state.py --state-file <path>
@@ -43,11 +47,29 @@ from pathlib import Path
 from typing import Any
 
 import yaml
-from jsonschema import Draft7Validator
+from jsonschema import Draft7Validator, FormatChecker
 
 DEFAULT_SCHEMA_PATH = Path(__file__).resolve().parent.parent / "assets" / "campaign-state-schema.json"
 
 
+def _is_date_time(instance: Any) -> bool:
+    """ISO-8601 date and time with a UTC offset; anything but a string is the type check's."""
+    if not isinstance(instance, str):
+        return True
+    text = instance[:-1] + "+00:00" if instance.endswith(("Z", "z")) else instance
+    if "T" not in text and "t" not in text:
+        return False
+    try:
+        parsed = datetime.datetime.fromisoformat(text)
+    except ValueError:
+        return False
+    return parsed.tzinfo is not None
+
+
+FORMAT_CHECKER = FormatChecker(formats=())
+FORMAT_CHECKER.checks("date-time")(_is_date_time)
+
+
 def _emit(envelope: dict) -> None:
     json.dump(envelope, sys.stdout, separators=(",", ":"), default=str)
     sys.stdout.write("\n")
@@ -115,6 +137,14 @@ def _translate(err) -> dict:
             "field": field,
             "message": f"State validation failed: `{field}` — {err.message}",
         }
+    if validator == "format":
+        return {
+            "field": field,
+            "message": (
+                f"State validation failed: `{field}` value `{inst}` is not an ISO-8601 date and time "
+                f"with a UTC offset (e.g. `2026-05-01T00:00:00Z`)."
+            ),
+        }
     if validator in ("minimum", "maximum"):
         return {
             "field": field,
@@ -127,7 +157,7 @@ def _translate(err) -> dict:
 
 
 def validate_state(state: dict, schema: dict) -> dict:
-    validator = Draft7Validator(schema)
+    validator = Draft7Validator(schema, format_checker=FORMAT_CHECKER)
     errors = [
         _translate(err)
         for err in sorted(validator.iter_errors(state), key=lambda e: list(e.absolute_path))

package/src/skf-campaign/templates/campaign-brief-template.yaml

@@ -1,5 +1,5 @@
-# Machine-generated campaign brief — resume context for fresh sessions
-# Populated by step-01-setup.md from operator inputs
+# Machine-generated campaign brief: resume context for fresh sessions
+# Written by campaign-state.py init from the parsed targets
 
 # Campaign identifier
 campaign_name: ""
@@ -15,6 +15,8 @@ targets: []
 #   tier: "A"           # A (full pipeline) or B (batch)
 #   pin: null            # version pin, or null for latest
 #   depends_on: []       # list of skill names this target depends on
+#   plus any other field the target's source gave it, such as a language or
+#   scope hint
 
 # Quality thresholds applied to all skills in this campaign
 quality_gate:
@@ -22,9 +24,6 @@ quality_gate:
   soft_target: 90
   soft_fallback: 80
 
-# Where health findings are routed: "local" (project-local) or "improvement" (shared queue)
-health_findings_queue: "local"
-
 # Optional path to the architecture document the verify (Stage 7) and refine
 # (Stage 8) stages consume. Empty string means those stages discover it at
 # runtime (docs/architecture.md, then _bmad-output/planning-artifacts/architecture.md).

package/src/skf-campaign/templates/campaign-report-template.md

@@ -21,6 +21,10 @@
 |------|------|--------|---------------|-----|-------------|
 {{skills_table}}
 
+## Export Gate
+
+{{export_gate_section}}
+
 ## Quality Scores
 
 | Metric | Value |
@@ -37,7 +41,7 @@
 
 - **Total workarounds applied:** {{total_workarounds}}
 - **Skills with workarounds:** {{skills_with_workarounds}}
-- **Doc-rot corrections:** tracked per-skill in health-check findings (not aggregated in campaign state)
+- **Doc-rot corrections:** counted among the workarounds, one `[doc-rot]` entry for each correction a skill's doc-rot step kept
 
 ## Workarounds Applied
 

package/src/skf-campaign/templates/kickoff-template.md

@@ -4,7 +4,6 @@
 
 - **Campaign:** {{campaign_name}}
 - **Current Stage:** {{current_stage}}
-- **Quality Gate:** {{quality_gate_summary}}
 
 ## Skill Identity
 
@@ -33,16 +32,3 @@
 ## Workarounds Applied
 
 {{workarounds_list}}
-
-## Pipeline Instructions
-
-Execute the standard forge pipeline for **{{skill_name}}**:
-
-1. **AN** (Analyze) — scope and source intelligence
-2. **BS** (Brief Synthesis) — generate or validate the skill brief
-3. **CS** (Compile Skill) — compile the SKILL.md artifact
-4. **TS** (Test Skill) — run health-check validation
-
-**Parameters:**
-- Pin: {{pin}}
-- Quality target: {{quality_gate_summary}}

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

@@ -7,77 +7,84 @@ description: Compile a skill from a brief. Supports --batch for multiple briefs.
 
 ## Overview
 
-Compiles a verified agent skill from a skill-brief.yaml and source code, producing an agentskills.io-compliant SKILL.md with provenance map, evidence report, and progressive disclosure references. The workflow is mostly autonomous with three interaction points — after ecosystem check (if match found), after source extraction (to confirm findings), and after content quality review (when tessl produces suggestions). Steps adapt behavior based on forge tier (Quick/Forge/Forge+/Deep). Zero hallucination tolerance: every instruction in the output must trace to source code with a confidence tier citation. A single run is not resumable — if it is interrupted mid-compile, re-run from the brief (only `--batch` checkpoints progress across briefs).
+Compiles a verified agent skill from a skill-brief.yaml and the source code or documentation it names, producing an agentskills.io-compliant SKILL.md with provenance map, evidence report, and progressive disclosure references. The workflow is mostly autonomous: it stops for the user in step 1 when no brief is named and several exist, in step 3 when several tags match the brief's version, for each authoritative AI documentation file the brief's scope leaves out (step 3 §2a), after source extraction (to confirm findings), at step 3c when a source brief extracted no export and none of its `doc_urls` could be fetched, and, for a component library, at step 3d's demo-exclusion and registry prompts. When the user has opted in to Tessl Review, step 6 also records Tessl's review of the skill as advice; it never stops the run. Steps adapt behavior based on forge tier (Quick/Forge/Forge+/Deep). Zero hallucination tolerance: every statement in the output carries a provenance citation, and content that cannot be cited is left out. A single run is not resumable: if it is interrupted mid-compile, re-run from the brief (only `--batch` checkpoints progress across briefs).
 
 ## Conventions
 
 - Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
-- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
+- **Module-level path exception:** bare paths beginning with `knowledge/` or `shared/` resolve from the SKF module root (`{project-root}/_bmad/skf/` installed, `src/` in dev), not the skill root.
+- **Sibling skills:** a path that names another SKF skill's folder (`skf-<name>/...`) resolves from the SKF module root, and that skill must be installed with this one.
+- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs) and `references/sub/` the conditional sub-steps; a `nextStepFile` is relative to its own stage file (so a sub-step that returns to a main stage names it in the parent folder). `scripts/` and `assets/` hold deterministic helpers and templates.
 - `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
 - `{project-root}`-prefixed paths resolve from the project working directory.
 - `{skill-name}` resolves to the skill directory's basename.
 
 ## Role
 
-You are operating in Ferris Architect mode — a skill compilation engine performing structural extraction and assembly. Apply zero hallucination tolerance: uncitable content is excluded, not guessed.
+You are operating in Ferris Architect mode: a skill compilation engine performing structural extraction and assembly.
 
 ## Workflow Rules
 
 These rules apply to every step in this workflow:
 
-- Never include content in SKILL.md that cannot be cited to source code
+- Never include content in SKILL.md without a provenance citation: `[AST:]` or `[SRC:]` for code (T1 and T1-low), `[QMD:]` for T2 context or `[EXT:]` for T3 documentation, in the forms `assets/skill-sections.md` gives
+- Never write into a skill folder SKF did not generate — generate-artifacts §1 runs the inventory's write check before creating any directory; without the helper it writes only into a skill folder that does not exist yet
 - Only load one step file at a time — never preload future steps
+- Once step 3 §2b has bound `{source_tree}` (the private tree a remote source is read from), every HALT after it first runs `uv run {sourceTreeHelper} close --tree "{source_tree}"` from `{project-root}` and goes on whatever it prints. Step 7 removes the tree on a run that finishes, and a later run removes one a stopped run left behind, seven days on
+- Every HARD HALT in steps 1 to 7 emits the result envelope before it stops, in every mode. Each HALT names its exit code, `halt_reason` and phase where it fires, and its emit command. Stage `{"phase": "<phase>", "halt_reason": "<halt_reason>", "reason": "<the halt message, one line>", "summary": {"halt_reason": "<halt_reason>", "evidence_report": null}}` as `{run_dir}/halt.json` (add `"path"` when the halt names a file or folder; once step 7 has promoted the package, add `"skill_package"` and `"outputs"` and set `summary.evidence_report` to `{forge_version}/evidence-report.md`), then run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`, adding `--result-dir "{forge_version}"` once step 7 has created `{forge_version}`, so the emitter also writes the halt's `create-skill-result-*.json` and its `-latest.json` copy there. Display the line it prints, then stop with the exit code; under `--batch` the halt ends only its brief: go to `references/batch-mode.md` §3, which records it and takes the next brief. If `{emitEnvelopeHelper}` resolved no path, display the halt message alone. The schema, `shared/scripts/schemas/skf-create-skill-result-envelope.v1.json`, lists every `halt_reason` with its exit code
 - Always communicate in `{communication_language}`
-- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action, logging each auto-decision to the in-context `headless_decisions[]` buffer AND appending it as a JSON line to the on-disk auto-decision sink (established at step 1 §3) the moment it lands, so the audit trail survives context compaction before step 5 first writes the evidence report
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action
+- Every decision the run takes without asking (each gate a headless run resolves by its default, step 1's tier override and its pick of the only brief) is recorded the moment it is taken: stage `{"step": "<step>", "gate": "<gate>", "decision": "<action>", "rationale": "<why>", "timestamp": "<ISO-8601>"}`, plus `"value"` or `"fallback"` where the gate names one, as `{run_dir}/decision.json` and run `uv run {emitEnvelopeHelper} record --workflow skf-create-skill --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"`. The run sink it appends to, `{run_dir}/headless-decisions.jsonl`, is the brief's one decision trail: it survives context compaction, step 5 §7 renders the evidence report's `## Auto-Decisions` table from it, and the result envelope and contract carry it
 
 ## Stages
 
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
-| 1 | Load Brief | references/load-brief.md | Yes |
-| 2 | Ecosystem Check | references/ecosystem-check.md | Conditional |
+| 1 | Load Brief | references/load-brief.md | Conditional |
 | 2b | CCC Discover | references/sub/ccc-discover.md | Yes |
 | 3 | Extract | references/extract.md | No (confirm) |
 | 3b | Fetch Temporal | references/sub/fetch-temporal.md | Yes |
-| 3c | Fetch Docs | references/sub/fetch-docs.md | Yes |
+| 3c | Fetch Docs | references/sub/fetch-docs.md | Conditional |
 | 3d | Component Extraction | references/component-extraction.md | Conditional |
 | 4 | Enrich | references/enrich.md | Yes |
 | 5 | Compile | references/compile.md | Yes |
 | 5a | Doc Sources | references/step-doc-sources.md | Yes |
 | 5b | Auto-Shard | references/step-auto-shard.md | Yes |
 | 5c | Doc-Rot | references/step-doc-rot.md | Yes |
-| 6 | Validate | references/validate.md | Conditional |
+| 6 | Validate | references/validate.md | Yes |
 | 7 | Generate Artifacts | references/generate-artifacts.md | Yes |
 | 8 | Report | references/report.md | Yes |
 | 9 | Workflow Health Check | references/health-check.md | Yes |
 
-*Sub-steps under `references/sub/` are conditional branches (CCC discovery, temporal/doc enrichment) kept out of the top-level step count so main-line steps 1–9 drive the workflow. Step 3d (Component Extraction) stays top-level as an alternative main step that replaces the standard extraction path when `scope.type: "component-library"`.*
+*Sub-steps under `references/sub/` are conditional branches (CCC discovery, temporal and doc enrichment), lettered by the place they take in the run and kept out of the main-line step count. Step 3d (Component Extraction) is a branch inside step 3 for a `component-library` brief: extract §2c loads it in place of §4 to §4c and resumes at its §5, before Gate 2.*
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | brief_path (path to skill-brief.yaml) [required], --batch [optional] |
-| **Gates** | step 2: Choice Gate [P] (if match) | step 3: Review Gate [C] | step 6: Content-Quality Gate [C] (if novel tessl suggestions) |
-| **Outputs** | SKILL.md, context-snippet.md, metadata.json, provenance-map.json, evidence-report.md, references/ |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **Inputs** | brief_path (a skill-brief.yaml path or a skill name) [optional: without it, step 1 offers the briefs in `{forge_data_folder}`, and a headless run halts unless there is one], --batch [optional: the briefs or folders of briefs after it, `{forge_data_folder}` when none is given, each validated before the first compiles] |
+| **Gates** | step 1: Brief Selection (no brief named and several in `{forge_data_folder}`; headless: HARD HALT `brief-missing`, exit 2; one brief: picked and recorded as gate `brief-selection`) | step 3: Tag Choice Gate (several tags match the brief's version; headless: the first in priority order) | step 3 §2a: Authoritative-File Gate [P]/[S]/[U] (an authoritative AI documentation file outside the brief's scope; headless: deferred-headless, one auto-decision per path) | step 3: Review Gate [C]/[R] (with the zero-export warning when a source brief without `doc_urls` extracted no export; [R] with it or the head-cap warning) | step 3c: Zero-Export Gate [C]/[R] (a source brief with no export whose every `doc_urls` fetch failed) | step 3d: Demo-Exclusion Gate [Y], then Registry Gate [Y] (candidate found) or [S] (none found), component-library scope only, each skipped once the brief holds `scope.demo_patterns` or `scope.registry_path`, which step 3d writes when a user confirms or gives the patterns or the registry path |
+| **Outputs** | SKILL.md, context-snippet.md, metadata.json, provenance-map.json, evidence-report.md, extraction-rules.yaml, references/; per brief, the result contract (`create-skill-result-{YYYYMMDD-HHmmss}.json` and its `-latest.json` copy in `{forge_version}`) and one `SKF_CREATE_SKILL_RESULT_JSON` line on stdout, on stderr at a HARD HALT |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true; each auto-decision reaches the envelope's and the result contract's `headless_decisions` |
+| **Exit codes** | 0 for a finished brief; at a HARD HALT 2 (the brief is missing, malformed or invalid), 3 (no forge config, source, helper or documentation), 4 (a write failed), 5 (a refused or broken package), 6 (the user chose to refine the scope). A `--batch` run exits with the highest code among its briefs, 0 when every brief finished |
 
 ## On Activation
 
 1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
    - `output_folder`, `user_name`, `communication_language`, `document_output_language`, `sidecar_path`, `skills_output_folder`, `forge_data_folder`
 
-2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `{sidecar_path}/preferences.yaml`. Default: false.
 
 3. **Resolve workflow customization.** Run:
 
    ```bash
-   python3 {project-root}/_bmad/scripts/resolve_customization.py \
-       --skill {skill-root} --key workflow
+   uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow
    ```
 
-   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append): `{skill-root}/customize.toml` (bundled defaults), `_bmad/custom/skf-create-skill.toml` under `{project-root}` (team overrides, committed), and `_bmad/custom/skf-create-skill.user.toml` under `{project-root}` (personal overrides, gitignored). If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly.
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-create-skill.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. In that case keep the reason as `{customization_resolver_unavailable}` (unset when the resolver ran) for step 1 §0 to record in each brief's run folder.
 
-   Apply the resolved values so the surface is not a silent no-op: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (entries prefixed `file:` are paths or globs whose contents load as facts); and stash `{onCompleteCommand}` ← `workflow.on_complete` (empty string = no-op) for the final stage to invoke after the result JSON and metadata.json are finalized. After activation completes, execute each entry in `workflow.activation_steps_append` in order.
+   Apply the resolved values so the surface is not a silent no-op: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (entries prefixed `file:` are paths or globs whose contents load as facts), except a `!` entry and the entry it names (`!file:{project-root}/**/project-context.md` drops the bundled project-context default); and stash `{onCompleteCommand}` ← `workflow.on_complete` (empty string = no-op) for step 8 to invoke once each brief's result contract is written. After activation completes, execute each entry in `workflow.activation_steps_append` in order.
 
-4. Load, read the full file, and then execute `references/load-brief.md` to begin the workflow.
+4. Resolve `{emitEnvelopeHelper}` ← the first existing path of `{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py` and `{project-root}/src/shared/scripts/skf-emit-result-envelope.py`, the shared emitter every result envelope, result contract and recorded decision goes through.
+
+5. If `--batch` was given, load, read the full file, and then execute `references/batch-mode.md`: it validates every brief first, runs steps 1 to 8 for each one and the health check once. Otherwise load, read the full file, and then execute `references/load-brief.md` to begin the workflow.

package/src/skf-create-skill/assets/compile-assembly-rules.md

@@ -16,12 +16,12 @@ description: >
 
 - `name`: lowercase alphanumeric + hyphens only, must match the skill output directory name. Prefer gerund form (`processing-pdfs`, `analyzing-spreadsheets`) for clarity.
 - `description`: non-empty, max 1024 chars, optimized for agent discovery. Use third-person voice ("Processes Excel files..." not "I can help you..." or "You can use this to...") and include a trigger phrase so agents know when to match. **The description must contain a literal `Use when` clause somewhere** — `skill-check`'s `description.use_when_phrase` rule tests for that exact phrase anywhere in the string, so `Triggers on …` or `Reach for this when …` on their own score below 100 with a `description should contain "Use when" phrasing` warning. The lead is still free: a descriptive opener followed by a `Use when …` clause (`Charts and visualizations powered by D3.js. Use when plotting data …`) passes cleanly, and the other two phrases are fine as *additional* text. When using `Use when `, follow with a **gerund** (`Use when building/processing/analyzing X…`) or a noun-phrase clause (`Use when the user requests to "X"`); never a bare indicative verb like `builds`/`processes`, because `skill-check --fix` will prepend a literal `Use when ` to a description missing the trigger phrase, producing ungrammatical output (`Use when builds X…`). Inconsistent point-of-view or a missing trigger phrase causes discovery problems since the description is injected into the system prompt. See `skf-brief-skill/assets/description-voice-examples.md` for the canonical voice palette.
-- **The `description` cannot contain angle brackets** — neither standalone placeholders like `<name>`, `<component>`, `<path>`, nor inline generics like `` `Array<T>` `` or `` `Meta<typeof X>` ``. Both `skill-check`'s `description_field` validator and `tessl`'s deterministic description check parse the frontmatter description as a raw string and reject any `<` or `>`, regardless of markdown context (backticks do not protect content here). A rejected description fails the review with 0% score. When the natural phrasing would use angle brackets:
-  - Prefer the curly-brace form in prose: `{name}`, `{component-id}`, `{path}` — readable and tessl-safe.
+- **The `description` cannot contain angle brackets** — neither standalone placeholders like `<name>`, `<component>`, `<path>`, nor inline generics like `` `Array<T>` `` or `` `Meta<typeof X>` ``. The Claude platform does not accept a skill description that contains XML tags, and the description is read as a raw string, so backticks do not protect content here. No validator SKF runs catches this (skill-check has no such rule and Tessl Review accepts angle brackets), so SKF enforces it itself. When the natural phrasing would use angle brackets:
+  - Prefer the curly-brace form in prose: `{name}`, `{component-id}`, `{path}` — readable and free of angle brackets.
   - Uppercase placeholders are also acceptable: `NAME`, `COMPONENT_ID`.
   - For code-ish fragments, use curly braces in place of angle brackets inside the backticks: `` `Meta{typeof X}` ``, `` `Array{T}` ``.
 
-  Authors should not rely on remembering this — step 5 §2a enforces it via a pre-write sanitization pass that unconditionally replaces every `<` with `{` and every `>` with `}` in the frontmatter `description`. See step 5 §2a for the rule and `assets/tessl-dismissal-rules.md` (`description-xml-tags-guarded-upstream`) for the recovery path if a downstream tool rewrites the description after §2a has run.
+  Authors should not rely on remembering this — step 5 §2a enforces it via a pre-write sanitization pass that unconditionally replaces every `<` with `{` and every `>` with `}` in the frontmatter `description`. See step 5 §2a for the rule and step 6 §6 for the check that applies it again if a later tool rewrites the description after §2a has run.
 - Only `name` and `description` in frontmatter — `version` and `author` go in metadata.json
 - No other frontmatter fields for standard skills (only `name`, `description`, `license`, `compatibility`, `metadata`, `allowed-tools` are permitted by spec)
 
@@ -100,6 +100,7 @@ These sections form the essential standalone body. Target: **under 300 lines tot
 <!-- [/MANUAL:additional-notes] -->
 ```
 - Place after Quick Start and after Key API Summary sections
+- **Carry an earlier build's blocks.** Step 7 replaces an earlier build of this version whole, so when `{skills_output_folder}/{name}/{version}/{name}/SKILL.md` exists (`{version}` with build metadata stripped, as step 7 §1 does), carry its hand-written blocks into this SKILL.md. A block runs from `<!-- [MANUAL:<id>] -->` to the first `<!-- [/MANUAL:<id>] -->` after it, and it is hand-written unless it holds nothing but whitespace or the seeded note above (a note of the user's own in an HTML comment is hand-written). Put each hand-written block's interior, byte for byte, in place of the seeded note of the marker with its id, and append a block whose id has no marker here at the end of this section. Step 6 then validates SKILL.md with the blocks in, and step 7's promotion checks each one arrived and carries the earlier build's `scripts/[MANUAL]/` and `assets/[MANUAL]/` files. When the earlier build holds a hand-written block or such a file, record the decision: stage `{"step": "compile", "gate": "manual-carry-forward", "decision": "carry", "rationale": "<the earlier build's folder, its block ids and its [MANUAL]/ files>", "timestamp": "<ISO-8601>"}` as `{run_dir}/decision.json` and run `uv run {emitEnvelopeHelper} record --workflow skf-create-skill --run-dir "{run_dir}" --decision < "{run_dir}/decision.json"`.
 
 ### Tier 2 — Reference-Eligible (can be extracted by split-body)
 
@@ -268,7 +269,7 @@ Replace per-function subsections with `references/pattern-*.md` groupings: one r
 
 - `stats.exports_documented` MAY be set to the Pattern Surface row count as a proxy, but its semantics change: it counts authored pattern surfaces, not public exports. Emit an adjacent `stats.pattern_surfaces_documented` with the same integer so downstream consumers (test-skill, feasibility, discovery) can discriminate.
 - `exports_public_api` / `exports_internal` / `exports_total` are not meaningful for a reference app — omit them, or set all three to the Pattern Surface count with a note in `stats.notes`: `"reference-app: export counts are pattern-surface proxies, not library exports"`.
-- Do not fabricate signature / type-coverage data from pattern surfaces. skf-test-skill will skip those categories when metadata flags a reference-app (same skip path as `stackSkill` once that flag is wired — see scoring-rules.md).
+- Do not fabricate signature / type-coverage data from pattern surfaces. skf-test-skill skips those categories when metadata flags a reference-app (`referenceApp`, the same skip path as `stackSkill`; its `scripts/compute-score.py` redistributes their weights).
 - Do not emit `effective_denominator` for reference-app scope, even when the source is a monorepo. `effective_denominator` counts public exports from the authoring-surface barrel — a library concept that `pattern_surfaces_documented` already replaces here. A reference-app-in-monorepo literally satisfies `compile.md` §4's emit-conditions (condition 1 arm (a) + non-`full-library` + stratified `scope.notes`), so this carve-out takes precedence: pattern-surface coverage is the reference-app basis, and skf-test-skill skips library-export coverage for it.
 
 **Language / spec-reference sub-shape:** A reference app that documents an engine- or spec-versioned **language** — a query language, grammar, or DSL (e.g. SurrealQL @ SurrealDB) whose value is construct idioms rather than wiring or exports — is a recognized reference-app sub-shape. Keep `scope.type: "reference-app"` (there is no separate enum value), so every carve-out above applies unchanged (`pattern_surfaces_documented` proxy, no `effective_denominator`, test-skill signature/type skip). Adapt the three overrides to the language's surface instead of app wiring:
@@ -297,7 +298,7 @@ A **whole-language reference** is a compiler/interpreter repo (rustc, CPython, t
 
 **GATE — apply ONLY when this is a whole-language reference.** The brief carries ≥1 `doc_urls` entry with `source: language-registry` (equivalently, `skf-derive-assembly-shape.py` returns `assembly_shape: "whole-language-reference"`). This is a structured, schema-validated signal — not a `scope.notes` substring — so an ordinary `full-library` library, a parser *library* (pest/lalrpop — its code IS the product, so §6b seeds no corpora), a component-library, a reference-app (including the language/spec-reference DSL sub-shape, which stays `scope.type: reference-app` and is handled by the reference-app override above), and a docs-only brief all fail the gate. When the gate does not fire, **skip this entire section** — the standard Tier 1 (sections 1–8) and Tier 2 (9–11) layout and the signature-fidelity rule run unchanged, so non-whole-language skills assemble byte-identically.
 
-When the gate fires, the assembler has a `language_guide[]` artifact from step 3c §4a (the retained corpora prose, carved out of the T3-vs-T1 conflict rule). Apply these overrides:
+When the gate fires, the assembler has a `language_guide[]` artifact, which step 5 §1 builds from the registry pages step 3c §4a kept (the retained corpora prose, carved out of the T3-vs-T1 conflict rule). Apply these overrides:
 
 **Empty-guide guard (check first):** If `language_guide[]` is absent or every entry's `prose` is null (all registry corpora failed to fetch), do not emit a thin Language Guide above a full internals section — fall back to the standard layout and record a warning in `evidence-report.md`: "Whole-language reference gated but no Language-Guide prose was retained — assembled as a standard library skill." This prevents the inverse-value outcome (prose section empty, compiler internals dominant).
 

package/src/skf-create-skill/assets/skill-sections.md

@@ -140,7 +140,8 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
   // "scripts": [{ "file": "scripts/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }],
   // "assets": [{ "file": "assets/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }],
   // doc_sources[] — include ONLY when doc detection ran; omit if detection was skipped entirely
-  // "doc_sources": [{ "url": "https://...", "detected_via": "homepageUrl|readme_link|pages_api|docs_folder|readme_always", "content_hash": "sha256:{hex}|null", "recorded_at": "ISO-8601" }],
+  // "doc_sources": [{ "url": "https://...", "detected_via": "homepageUrl|readme_link|pages_api|docs_folder|readme_always|brief_doc_urls", "content_hash": "sha256:{hex}|null", "recorded_at": "ISO-8601" }],
+  // detected_via "brief_doc_urls" = docs-only skills: the brief's doc_urls (plus subpages step 3c fetched), hashed by `skf-detect-docs.py hash-urls`
   "generated_by": "{quick-skill|create-skill}",
   "dependencies": [],
   "compatibility": "{semver-range}"
@@ -193,7 +194,7 @@ Each reference file includes:
       "source_line": 42,
       "confidence": "T1",
       "extraction_method": "ast-grep",
-      "ast_node_type": "export_function_declaration",
+      "ast_node_type": "export_statement",
       "signature_source": "T1"
     }
   ],
@@ -202,7 +203,7 @@ Each reference file includes:
       "libraries": ["lib-a", "lib-b"],
       "pattern_type": "provider-consumer",
       "detection_method": "co-import grep|architecture_co_mention|inferred_from_shared_domain",
-      "co_import_files": [{"file": "src/app.ts", "line": 5}],
+      "co_import_files": [{"path": "src/app.ts", "line_a": 5, "line_b": 7}],
       "confidence": "T1|T2|T3"
     }
   ],
@@ -281,10 +282,13 @@ t2_future_count: {N}
 ## Validation Results
 - Schema: {pass/fail} (quality score: {score}/100)
 - Frontmatter: {pass/fail}
-- Body: {pass/fail} {split-body applied if applicable}
+- Body: {pass/fail} {body split applied if applicable}
 - Security: {pass/warn/skipped}
-- Content Quality (tessl): {pass/warn/skipped} (score: {score}%)
+- Description angle brackets: {none | re-sanitized ({count} substitutions) | not checked — no description}
+- Tessl Review: {tessl_summary}
 - Metadata: {pass/fail}
+- Provenance labels: {pass | relabeled {N} to match extraction_method: {export names}}{; WARN, no node kind found: {export names}}
+- Provenance lines: {pass | findings | fixed {N} source lines, {M} citation prefixes and {K} node kinds | not run: verifier missing | not run: verifier error}{; second run: verifier error}{; unverified, no definition line found: {export names}}{; WARN: {each line, citation or node-kind warning §7a lists}}{; source lines not checked: no local source tree}{; node kinds not checked: no ast-grep CLI | unrecognized ast-grep}{; node kinds unchecked: {export name (reason) for each node_kinds_unchecked item}}{; node kinds skipped: {N} in files ast-grep has no language for}
 
 ## Quality Score Breakdown
 - Frontmatter (30%): {score} | Description (30%): {score} | Body (20%): {score} | Links (10%): {score} | File (10%): {score}
@@ -300,8 +304,15 @@ t2_future_count: {N}
 
 ## Remaining Warnings
 - {any warnings from extraction or validation}
+
+## Tessl Review
+- Result: {tessl_summary}
+- Workspace: {tessl_workspace or —} · tessl {tessl_version or —} · Run: {tessl_run_id or —}
+- Validation findings: {each {tessl_validation} finding as `name (status): message`, or "none"}
+- Description suggestions (to act on one, edit the description in the brief and re-run create-skill): {each of {tessl_description_suggestions}, or "none"}
+- Content suggestions (advisory, not applied): {each of {tessl_content_suggestions} with its `(not applicable: <rule-id>)` mark, or "none"}
 ```
 
 **Frontmatter — pinned detection contract:** the `t2_future_count` field is the authoritative forward-looking-annotation count for downstream gate checks (e.g. skf-test-skill §2b migration-section rule). Emit **always**, even when 0 — omission is indistinguishable from "no T2-future data" and silently flips the gate into Case 2/3 for a Case-1 skill. `generated` and `forge_tier` mirror the narrative header for consumers that read only the frontmatter. Downstream gate rules parse `t2_future_count` from frontmatter, not prose — prose drift (heading renames, alternate phrasings like "forward-looking annotations") silently breaks grep-based detection.
 
-**Description Guard slot:** populated by step 6 §0 (create-skill) and §0 (update-skill) when the guard protocol fires. `Restored: true` indicates that an external tool (typically `skill-check --fix` or `split-body`) rewrote the frontmatter `description` and the guard restored the pre-tool value. When `Restored: false`, leave `Triggering tool`, `Original description preserved`, and `Notes` as `—`. When `Restored: true`, fill all four fields: tool name, whether the original was successfully written back, and a one-sentence note describing what the tool had changed (e.g., "replaced with generic summary", "truncated at 80 chars", "angle-bracket tokens re-introduced"). Downstream test-skill assertions can grep for `Restored: true` to detect unintended tool rewrites without parsing free-form warning prose.
+**Description Guard slot:** populated by step 6 §0 (create-skill) and §0 (update-skill) when the guard protocol fires. `Restored: true` indicates that an external tool (typically `skill-check --fix`, create-skill's `skf-shard-body.py` body split or update-skill's `split-body`) rewrote the frontmatter `description` and the guard restored the pre-tool value. When `Restored: false`, leave `Triggering tool`, `Original description preserved`, and `Notes` as the no-fire dash the template above shows. When `Restored: true`, fill all four fields: tool name, whether the original was successfully written back, and a one-sentence note describing what the tool had changed (e.g., "replaced with generic summary", "truncated at 80 chars", "angle-bracket tokens re-introduced"). Downstream test-skill assertions can grep for `Restored: true` to detect unintended tool rewrites without parsing free-form warning prose.