bmad-module-skill-forge 2.2.0 → 4.0.0

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

@@ -117,7 +117,7 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
   "tool_versions": {
     "ast_grep": "{version-or-null}",
     "qmd": "{version-or-null}",
-    "skf": "{skf_version}"
+    "skf": "{installed-skf-version-or-unknown}"
   },
   "confidence_distribution": {
     "t1": 0,
@@ -134,7 +134,7 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
     "total_coverage": 0.0,
     "scripts_count": 0,
     "assets_count": 0
-    // "effective_denominator": 0  // optional — emitted for the curated-subset shapes in compile.md §4 condition 1; test-skill uses this as the coverage denominator when present. See compile.md §4 emit rules.
+    // "effective_denominator": 0  // optional: emitted when compile.md §4 passes it (counts.effective_denominator_decision.store and a stratified scope.notes); test-skill uses this as the coverage denominator when present.
   },
   // scripts[] and assets[] — include ONLY when inventories are non-empty; omit entirely otherwise
   // "scripts": [{ "file": "scripts/{name}", "purpose": "{description}", "source_file": "{source-path}", "confidence": "T1-low" }],
@@ -144,7 +144,7 @@ Indexed pipe-delimited format for CLAUDE.md managed section (~80-120 tokens per
   // 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}"
+  "compatibility": ""
 }
 ```
 
@@ -194,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"
     }
   ],
@@ -203,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"
     }
   ],
@@ -270,9 +270,9 @@ t2_future_count: {N}
 **Source:** {repo} @ {commit}
 
 ## Tool Versions
-- ast-grep: {version}
-- QMD: {version}
-- SKF: {skf_version}
+- ast-grep: {tool_versions.ast_grep}
+- QMD: {tool_versions.qmd}
+- SKF: {tool_versions.skf}
 
 ## Extraction Summary
 - Files scanned: {count}
@@ -282,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}
@@ -301,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.

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

@@ -1,8 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-create-skill.
-# Team overrides:     _bmad/custom/skf-create-skill.toml (under {project-root})
-# Personal overrides: _bmad/custom/skf-create-skill.user.toml (under {project-root})
+# Team overrides:     {project-root}/_bmad/custom/skf-create-skill.toml
+# Personal overrides: {project-root}/_bmad/custom/skf-create-skill.user.toml
 
 [workflow]
 
@@ -23,7 +23,7 @@ activation_steps_prepend = []
 activation_steps_append = []
 
 # Persistent facts the workflow keeps in mind for the whole run
-# (extraction style, compilation guardrails, tessl review preferences).
+# (extraction style, compilation guardrails).
 # Overrides append.
 #
 # Each entry is either:
@@ -31,17 +31,29 @@ activation_steps_append = []
 #   - a file reference prefixed with `file:`, e.g.
 #     "file:{project-root}/docs/create-policy.md" (globs supported; file
 #     contents are loaded and treated as facts).
+#
+# The bundled entry below loads every project-context.md under
+# {project-root} (the BMad project context) as facts for each brief.
+# Overrides append, so no override can delete it. To drop it, add the same
+# entry with a leading `!` in {project-root}/_bmad/custom/skf-create-skill.toml:
+#   persistent_facts = ["!file:{project-root}/**/project-context.md"]
+# The workflow then skips both (SKILL.md On Activation step 3); a `!` entry
+# drops any entry it names this way.
 
 persistent_facts = [
   "file:{project-root}/**/project-context.md",
 ]
 
-# Pipeline-integration hook invoked after the final report (step 8) and the
-# result JSON / metadata.json are finalized. The command is called as:
+# Pipeline-integration hook invoked by step 8 (report) once a brief's result
+# contract is written, after its compilation report. The value is a shell
+# command, run from {project-root}, not an agent instruction: a shell cannot
+# run a skill such as test-skill or export-skill. It is called as:
 #   <on_complete> --result-path=<{forge_version}/create-skill-result-latest.json>
-# Useful for Slack notifications, dashboard ingest, CI hooks, or chaining a
-# downstream skill (TS test-skill, EX export). Failures are logged to
-# workflow_warnings[] but never fail the workflow.
+# Under --batch it runs once per brief, each time with that brief's result
+# file; a brief that halts, or whose result file was not written, gets no
+# call. Useful for a Slack or email notifier, dashboard ingest, a CI script
+# or a git-add wrapper. A failure is reported on its own line and never
+# fails the brief.
 #
 # Empty string = no-op (default).
 

package/src/skf-create-skill/references/authoritative-files-protocol.md

@@ -2,28 +2,28 @@
 
 ## Overview
 
-Loaded on demand when step 3's `### 2a. Discovered Authoritative Files Protocol` sub-step runs.
+Loaded on demand when step 3's `### 2a. Discovered Authoritative Files Protocol` sub-step runs, after `### 2b. Resolve Source Access` has resolved the source to a local tree.
 
 **Skip this protocol entirely if `source_type: "docs-only"`** — there is no source tree to scan.
 
-Before resolving source access for extraction, scan the source tree for **authoritative AI documentation files** that the brief's scope filters excluded. Project authors increasingly add files specifically written to steer AI assistants (`llms.txt`, `AGENTS.md`, `.cursorrules`, etc.), and these files often contain the **canonical** install command, quick-start, or architecture summary — information that nowhere else in the source tree provides. A brief authored from a scan of `src/**` will frequently exclude these files without the author realizing they exist.
+**Skip it too when `source_root` is still a remote URL** (a Quick-tier remote source, which §2b never clones, or a remote source §2b could not read into a tree): step 3 §2a's remote source guard skips the scan with a notice, because the helper below walks a local directory and refuses a URL.
 
-This protocol detects such files, prompts the user, and records the decision in the brief so future runs (re-create, update, audit) honor it.
+Once §2b has resolved source access, scan the resolved source tree (the local source, or the private tree §2b read a remote one into) for **authoritative AI documentation files** that the brief's scope filters excluded. Project authors increasingly add files specifically written to steer AI assistants (`llms.txt`, `AGENTS.md`, `.cursorrules`, etc.), and these files often contain the **canonical** install command, quick-start, or architecture summary: information that nowhere else in the source tree provides. A brief authored from a scan of `src/**` will frequently exclude these files without the author realizing they exist.
 
-**Heuristic scan list (handled by the helper — listed here for reference):** case-insensitive basename match, any directory depth, on `llms.txt`, `llms-full.txt`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `COPILOT.md`, `.cursorrules`, `.windsurfrules`, `.clinerules`.
+This protocol detects such files, prompts the user, and records the decision in the brief so future runs (re-create, update, audit) honor it.
 
 ## Procedure
 
-1. **Resolve, scan, classify, and load previews in one call.** The helper handles the source-tree walk (pruning `node_modules`, `dist`, `.git`, etc.), case-insensitive basename matching, scope-filter diff (with `**`-recursive-glob support), amendment reconciliation (most-recent action wins), preview load (first 20 lines), and SHA-256 hashing:
+1. **Resolve, scan, classify, and load previews in one call.** Resolve `{resolveAuthoritativeFilesHelper}` ← first existing path in `{resolveAuthoritativeFilesProbeOrder}` (step 3's frontmatter); if neither exists, **HARD HALT** (exit code 3, `helper-missing`, phase `extract`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`): "Cannot scan for authoritative files: skf-resolve-authoritative-files.py is missing. Re-install SKF, then re-run create-skill." The helper walks the tree, classifies each candidate and hashes it:
 
    ```bash
    uv run {resolveAuthoritativeFilesHelper} resolve \
-       --source-root {source_root} \
-       --brief {forge_data_folder}/{skill_name}/skill-brief.yaml \
+       --source-root "{source_root}" \
+       --brief "{brief_path}" \
        [--preview-lines 20]
    ```
 
-   The helper emits one envelope with three buckets:
+   `{source_root}` is the local tree §2b resolved: the local source, or the private tree of a remote one, and `{brief_path}` the `skill-brief.yaml` step 1 loaded. The helper emits one envelope with three buckets:
 
    ```json
    {
@@ -47,17 +47,18 @@ This protocol detects such files, prompts the user, and records the decision in
        {"path": "...", "heuristic": "...", "size_bytes": N,
         "line_count": N, "content_hash": "sha256:...",
         "preview": "<first N lines>",
-        "excluded_by_pattern": "<glob>"|"not matched by any scope.include"}
+        "excluded_by_pattern": "<glob>"|"not matched by any scope.include",
+        "prior_action": null|"deferred-headless"}
      ]
    }
    ```
 
 2. **Apply the helper's classification:**
 
-   - **`already_in_scope[]`** — file is in scope and not skipped. **Remove the path from §2's filtered file list** and append the record to in-context `promoted_docs[]`. No prompt — authoritative docs must never reach §4 code extraction even when scope.include matches.
+   - **`already_in_scope[]`**: the file is in scope and not skipped. Append the record to in-context `promoted_docs[]`, and remove the path from §2's filtered file list when §2 built one. No prompt: authoritative docs must never reach §4 code extraction even when scope.include matches.
    - **`pre_decided[]` with `prior_action: "promoted"`** — amendment says promoted; **append to `promoted_docs[]`** using the helper-supplied hash/size/lines. Deterministic replay path.
    - **`pre_decided[]` with `prior_action: "skipped"`** — user previously declined. Do nothing. Move on.
-   - **`unresolved[]`** — proceed to step 3 below (user prompt).
+   - **`unresolved[]`**: proceed to step 3 below (user prompt). A `prior_action` of `deferred-headless` means an earlier headless run met the file and left the decision to the next interactive run.
 
 3. **Prompt.** Present each `unresolved[]` candidate to the user. Use the helper's `preview`, `size_bytes`, `line_count`, and `excluded_by_pattern` fields verbatim so the prompt reports facts rather than recomputing them:
 
@@ -79,64 +80,41 @@ This protocol detects such files, prompts the user, and records the decision in
    [U] Update  — halt this run and return to skf-brief-skill to refine scope
    ```
 
-4. **Headless mode (`{headless_mode}` is true):** auto-select `[S] Skip` for every candidate. Record amendment entries with `action: "skipped"` and `reason: "headless: no user to prompt"`. A non-interactive run must never silently promote files into scope — the decision requires a human.
+4. **GATE [default: defer]**: in headless mode (`{headless_mode}` is true), promote nothing and decline nothing: whether a file enters scope is a person's decision, so this run leaves every `unresolved[]` candidate out of extraction and defers it to the next interactive run, which asks. For each candidate:
+   - Record one auto-decision per path, per the Workflow Rules: stage `{"step": "extract", "gate": "authoritative-file:{path}", "decision": "deferred-headless", "rationale": "headless mode: no person to decide whether {path} enters the scope", "timestamp": "{ISO}"}` 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 path in the gate keeps several candidates from collapsing into one row.
+   - When its `prior_action` is null, record the deferral in the brief with step 5's **Write the decision** call, with one amendment per such candidate: `action: "deferred-headless"`, `reason: "headless: no person to decide; the next interactive run asks"`, `heuristic: {basename}`, `date: {today ISO}`, `workflow: "skf-create-skill"`. The helper keeps a `deferred-headless` path in `unresolved[]`, never in `pre_decided[]`. A candidate whose `prior_action` is already `deferred-headless` is not written again.
 
 5. **Apply decision:**
 
+   **Write the decision** to the brief at once, so a crashed run still leaves it recorded and a re-run replays it instead of asking again. Resolve `{writeSkillBriefHelper}` ← first existing path in `{writeSkillBriefProbeOrder}` and, from `{project-root}`, run `amend`: it reads the brief again, appends the paths in `include` to `scope.include` and the entries in `amendments` to `scope.amendments`, refuses an amendment that breaks the brief schema, keeps the previous brief as `{brief_path}.bak` and writes the new one atomically:
+
+   ```bash
+   uv run {writeSkillBriefHelper} amend --target "{brief_path}" <<'SKF_BRIEF_DECISION'
+   {"include": ["{path}"], "amendments": [{"path": "{path}", "action": "promoted|skipped|deferred-headless", "reason": "{reason}", "heuristic": "{basename}", "date": "{today ISO}", "workflow": "skf-create-skill"}]}
+   SKF_BRIEF_DECISION
+   ```
+
+   Pass `include` for a promoted path only. The helper appends it only when `scope.include` is not empty: an empty include already covers every file, and appending one path would narrow the scope to it; the `promoted` amendment replays the decision either way, through the helper's `pre_decided[]`. When the command exits non-zero or no path resolves, warn "The decision on `{path}` was not saved to the brief ({its stderr}): the next run asks again." and continue.
+
    - **[P] Promote:**
-     1. **Do not add the path to the filtered file list from §2.** Authoritative documentation files are not code — they must not go through the AST extraction pipeline in §4, which would silently produce no exports (ghost entries). Instead, add the path to a new in-context list `promoted_docs[]` with `{path, heuristic, size_bytes, line_count, content_hash}`. Compute the SHA-256 content hash of the file now.
-     2. Append to `brief.scope.include`: add the exact `candidate.path` as a literal glob (no wildcards — the amendment targets this specific file). This write ensures that a re-run of `skf-create-skill` against the amended brief sees the path in scope and skips re-prompting.
-     3. Append to `brief.scope.amendments[]` a new entry with `action: "promoted"`, `path: candidate.path`, `reason: {user-provided one-sentence reason or auto-generated "authoritative AI docs — matched heuristic {basename}"}`, `heuristic: {basename}`, `date: {today ISO}`, `workflow: "skf-create-skill"`.
-     4. **Write the amended brief back to disk immediately** at `{forge_data_folder}/{skill_name}/skill-brief.yaml`. Immediate write (not deferred to step 7) ensures a crashed run still leaves the amendment recorded. Preserve all other brief fields and formatting. **Use atomic write + backup:** before writing, copy the original brief to `{forge_data_folder}/{skill_name}/skill-brief.yaml.bak` (overwriting any prior `.bak` — the most recent pre-amendment snapshot is the useful one). Then pipe the amended YAML through the shared atomic writer so a crash mid-write cannot corrupt the brief:
-
-        ```bash
-        # 1. Backup
-        cp {forge_data_folder}/{skill_name}/skill-brief.yaml \
-           {forge_data_folder}/{skill_name}/skill-brief.yaml.bak
-
-        # 2. Atomic write (stdin → tmp → fsync → rename)
-        cat <<'AMENDED_YAML' | python3 {atomicWriteHelper} write \
-            --target {forge_data_folder}/{skill_name}/skill-brief.yaml
-        {amended brief YAML}
-        AMENDED_YAML
-        ```
-
-        The helper stages into `{brief}.skf-tmp`, fsyncs, then `os.replace()`s — readers never see a half-written brief.
-     5. Display: "**Promoted `{path}`** — tracked as documentation file, amendment recorded."
+     1. **Do not hand the path to §4.** Authoritative documentation files are not code: the AST extraction pipeline would silently produce no exports (ghost entries). Add the path to a new in-context list `promoted_docs[]` with `{path, heuristic, size_bytes, line_count, content_hash}`, taking the values the helper reported, and remove it from §2's filtered file list when §2 built one.
+     2. **Write the decision** with `include: ["{path}"]` and an amendment with `action: "promoted"`, `reason`: the user's one-sentence reason, else "authoritative AI docs, matched heuristic {basename}".
+     3. Display: "**Promoted `{path}`**: tracked as documentation file, amendment recorded."
 
    - **[S] Skip:**
-     1. Do not modify `scope.include` or `scope.exclude`.
-     2. Append to `brief.scope.amendments[]` a new entry with `action: "skipped"`, `path: candidate.path`, `reason: {user-provided reason or auto-generated "user declined promotion at create-skill §2a"}`, `heuristic: {basename}`, `date: {today ISO}`, `workflow: "skf-create-skill"`.
-     3. **Write the amended brief back to disk** so future runs do not re-prompt. Use the same backup-then-atomic-write pattern as the [P] Promote path (copy to `skill-brief.yaml.bak` first, then pipe through `skf-atomic-write.py write --target {brief_path}`).
-     4. Display: "**Skipped `{path}`** — decision recorded in amendments."
+     1. Leave `scope.include` and `scope.exclude` as they are.
+     2. **Write the decision** with no `include` and an amendment with `action: "skipped"`, `reason`: the user's reason, else "user declined promotion at create-skill §2a".
+     3. Display: "**Skipped `{path}`**: decision recorded in amendments."
 
    - **[U] Update:**
-     1. Halt the workflow immediately.
-     2. Display: "**Halting create-skill.** Re-run `skf-brief-skill` to refine the scope filters for `{skill_name}`, then re-run `skf-create-skill`. Decisions for previously prompted candidates were already persisted to the brief; the current candidate was not written."
-     3. Exit with status `halted-for-brief-refinement`.
+     1. When `{source_tree}` is set, first run `uv run {sourceTreeHelper} close --tree "{source_tree}"` from `{project-root}` and go on whatever it prints: the scan read the tree §2b made, and nothing reads it after this halt.
+     2. **HARD HALT** (exit code 6, `halted-for-brief-refinement`, phase `extract`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --target stderr < "{run_dir}/halt.json"`): "**Halting create-skill.** Re-run `skf-brief-skill` to refine the scope filters for `{skill_name}`, then re-run `skf-create-skill`. Decisions for previously prompted candidates were already persisted to the brief; the current candidate was not written."
 
 6. **Summary.** After all candidates are resolved (or none were found), display a one-line summary:
 
-   - `"Authoritative files scan: {N} candidates, {P} promoted, {S} skipped, {A} pre-decided from amendments."`
+   - `"Authoritative files scan: {N} candidates, {P} promoted, {S} skipped, {D} left for an interactive run, {A} pre-decided from amendments."`
    - If N = 0: `"Authoritative files scan: no candidates."`
 
-**Record for evidence report:** `authoritative_files_scan: {candidates: N, promoted: P, skipped: S, pre_decided: A, decisions: [{path, action, heuristic, reason}]}` — step 7 includes this in `evidence-report.md`.
-
-## How promoted docs reach the provenance map
-
-Promoted docs do not flow through §4 code extraction. Instead:
-
-1. §2a populates the in-context `promoted_docs[]` list with content hashes.
-2. **Step-05 §6** (provenance-map assembly) reads `promoted_docs[]` and emits one `file_entries[]` entry per promoted doc with `file_type: "doc"`, `extraction_method: "promoted-authoritative"`, `confidence: "T1-low"`, and the pre-computed `content_hash`.
-3. **Step-07 §2** does not copy doc files into the skill package (unlike scripts and assets). The source file remains at its original path; only the provenance map tracks it. Future audit and update workflows compare against this tracking entry via content hash — no file copy is required because the intent is drift detection on the *source*, not bundling documentation into the skill output.
-
-**Re-running `skf-create-skill`** reads the amended brief. Files with `action: "promoted"` amendments already appear in `scope.include`, but §2a still runs — it detects the file is in scope AND has an existing amendment, and takes the "pre-decided" silent path. The `promoted_docs[]` list is rebuilt on each run by scanning amendments with `action: "promoted"` (this is the deterministic replay path).
-
-## Downstream workflow consumption
-
-Zero code changes required in consumer workflows:
-
-- **`skf-update-skill`** reads `provenance-map.json`. Promoted docs appear as `file_entries[]` entries. Update-skill Category D (script/asset file changes) iterates `file_entries` and compares content hashes — this works identically for `file_type: "doc"` entries, giving drift detection for free.
-- **`skf-audit-skill`** scans files from `provenance-map.json`. The re-index builds its list from `entries[].source_file ∪ file_entries[].source_file`, so promoted doc paths are naturally included in the audit scan.
+**Record for evidence report:** `authoritative_files_scan: {candidates: N, promoted: P, skipped: S, deferred: D, pre_decided: A, decisions: [{path, action, heuristic, reason}]}`. Step 3 §5 writes it and `promoted_docs[]` into the extraction inventory, and step 5 writes it into `evidence-report.md`.
 
-The brief is the single source of truth for authored scope intent. The provenance map is the single source of truth for extracted state. `scope.amendments[]` is the bridge that records when those two intentionally diverged. `promoted_docs[]` is the in-memory handoff from §2a to step 5 §6; it is not persisted — the persisted form is the `file_entries[]` list in provenance-map.json.
+When step 3 §2a's remote source guard skipped the scan, the record is `authoritative_files_scan: {not_scanned: "remote source not cloned"}` instead (its own key, apart from the `skipped` count of candidates above), and step 6 lists that skip under the evidence report's Remaining Warnings.

package/src/skf-create-skill/references/batch-mode.md

@@ -0,0 +1,81 @@
+---
+nextStepFile: 'load-brief.md'
+healthCheckStepFile: 'health-check.md'
+# Resolve `{quickBatchHelper}` to the first existing path. It keeps the
+# batch on disk: §1 starts it, §2 hands out each brief, §3 records how each
+# one ended and §4 ends the batch. If neither path exists, §1 halts before
+# any brief compiles.
+quickBatchProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-quick-batch.py'
+  - '{project-root}/src/shared/scripts/skf-quick-batch.py'
+# HARD HALT helper (Execution).
+emitEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-result-envelope.py'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Batch Mode
+
+With `--batch`, create-skill compiles every brief the paths after the flag name, one after another: each path is a `skill-brief.yaml`, or a folder whose `skill-brief.yaml` files (at any depth, hidden folders left out) are compiled; with no path, the briefs under `{forge_data_folder}`. `skf-quick-batch.py` keeps the batch in its run folder, never only in context: it checks every brief with the brief schema validator before the first one compiles, hands out each brief in turn, records how each one ended, and computes the counts, the status and the exit code. A HARD HALT ends its brief, not the batch.
+
+## Execution
+
+Resolve `{quickBatchHelper}` ← the first existing path in `{quickBatchProbeOrder}`, and `{emitEnvelopeHelper}`, which every HARD HALT here emits through, ← the first existing path in `{emitEnvelopeProbeOrder}` when it is not bound. The helper names the batch run folder, `{batch_dir}`, after the briefs: the same briefs always get the same folder, so a batch a session ended mid-way is found again (run `--batch` with the same briefs and it goes on with the brief it was working on, which compiles again from the start), and a batch of other briefs, from another terminal, never touches it. After a compaction, `{batch_dir}` is the parent folder of the brief's `{run_dir}`, and §1's `start` run again with the same briefs prints it without changing the batch.
+
+### 1. Start the Batch
+
+```bash
+uv run {quickBatchHelper} start --briefs {batch_paths} --run-root "{project-root}/_bmad-output/.skf-run"
+```
+
+`{batch_paths}` is each path given to `--batch`, quoted, or `"{forge_data_folder}"` when none was given. The helper finds the briefs and checks each one, and records each brief the validator refuses as failed, with its `halt_reason` (`brief-missing`, `brief-malformed` or `brief-invalid`) and the validator's first message, before any brief compiles; a brief whose `name` an earlier brief already has is refused the same way (`brief-invalid`), since both would compile into one skill folder. Bind `{batch_dir}` ← its `batch_dir`. When On Activation step 3 kept a `{customization_resolver_unavailable}` reason, write `customization_resolver_unavailable: {customization_resolver_unavailable}` to `{batch_dir}/resolver-warning.txt` with a file write, never `echo`: load-brief.md §0 records it in each brief's sink, after a compaction too. Display the plan: "**Batch:** {targets_total} briefs, {targets_total minus the `rejected` count} to compile." and, for each `rejected` entry, "Not compiled: `{target}`: {message}". When `resumed` is true, add "Resuming the batch: {recorded} briefs already ended."
+
+If it exits non-zero, no brief compiles: the `halt_reason` of its stderr JSON names the halt. Display "**The batch cannot start:** {its `message`, or: skf-quick-batch.py is missing, re-install SKF}", and stop:
+
+- `brief-missing`, no brief under the paths: **HARD HALT** (exit code 2, `brief-missing`, phase `batch-mode`; emit with nothing to stage in, below).
+- `helper-missing`, the validator cannot load, or no path in `{quickBatchProbeOrder}` exists: **HARD HALT** (exit code 3, `helper-missing`, phase `batch-mode`; emit with nothing to stage in, below).
+- `write-failed`, the batch folder cannot be written, or holds an unfinished batch of other briefs, which start never deletes: **HARD HALT** (exit code 4, `write-failed`, phase `batch-mode`; emit with nothing to stage in, below).
+
+No run folder holds a payload yet, so the halt's envelope comes from the command alone. Every halt of this file emits this way, with the reason it gives:
+
+```bash
+uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --target stderr <<'SKF_JSON'
+{"phase": "batch-mode", "halt_reason": "<the halt_reason>", "reason": "The batch cannot start: <that message, one line>", "summary": {"halt_reason": "<the halt_reason>", "evidence_report": null}}
+SKF_JSON
+```
+
+### 2. Take the Next Brief
+
+```bash
+uv run {quickBatchHelper} next --run-dir "{batch_dir}"
+```
+
+- **`"status": "next"`**: display the `start` event the helper printed on stderr. Bind `{run_dir}` ← its `run_dir`, the brief's own run folder, created empty, and `{brief_path}` ← its `target`. Nothing else carries over from the previous brief: its source, tree, extraction, staged skill and summary values all start empty. Then load, read in full and execute `{nextStepFile}`: steps 1 to 8 run for this brief.
+- **`"status": "record"`**: brief `batch` ended, its payload staged, before §3 recorded it (a compaction came between its envelope and §3): go to §3 with that `batch`, never compiling it again.
+- **`"status": "done"`**: no brief is pending. Go to §4.
+
+If it exits non-zero (the brief's run folder cannot be created, or the batch file is gone or unreadable), the batch cannot go on: display "**The batch stopped:** {its `message`}" and **HARD HALT** (exit code 4, `write-failed`, phase `batch-mode`; emit with nothing to stage in, as §1 does, with the reason "The batch stopped: <its message>").
+
+### 3. Record the Brief
+
+Every brief ends here: step 8 §6 sends a finished brief here, and every HARD HALT of steps 1 to 7 returns here after its envelope (each stage's Rules say so). Control returns here even when the step that ended the brief reads as the end of the run. Record it:
+
+```bash
+uv run {quickBatchHelper} record --run-dir "{batch_dir}" --batch {batch} --target stderr
+```
+
+`{batch}` is the number §2's `next` printed. The helper reads how the brief ended from what its run folder staged for the emitter (`halt.json`, or step 8's `result-context.json`), appends the outcome to the batch file, removes the run folder of a brief that finished (a halted brief keeps its folder for a look), and prints the brief's `done` or `fail` event on stderr: display it verbatim. Then go back to §2. If it exits non-zero, its `message` names what is missing: stage the payload the brief ended with and record again, once. If it exits non-zero a second time (the batch file cannot be written, or a `halt_reason` maps to no exit code), the outcome cannot be kept: display "**The batch stopped:** {its `message`}" and **HARD HALT** (exit code 4, `write-failed`, phase `batch-mode`; emit with nothing to stage in, as §1 does, with the reason "The batch stopped: <its message>").
+
+### 4. Batch Summary
+
+```bash
+uv run {quickBatchHelper} summarize --run-dir "{batch_dir}" --output-dir "{skills_output_folder}/_batch" --target stderr
+```
+
+The helper counts the briefs, sets the batch status and exit code, writes the summary to `{skills_output_folder}/_batch/create-skill-batch-{YYYYMMDD-HHmmss}.json` and its `create-skill-batch-latest.json` copy (`skill`, `mode`, `status`, `timestamp`, `input_briefs`, `targets_total`, `succeeded`, `failed`, `fail_fast_triggered`, `exit_code`, and `results[]`, one per brief with its `batch`, `target`, `status`, `exit_code`, `skill_package` and `error_code`), removes the batch run folder when no brief failed, and prints the `batch_summary` event on stderr: display it verbatim, then "Batch complete: {succeeded} of {targets_total} briefs compiled." and, when `failed` is above 0, the `target` and `error_code` of each failed `results[]` entry of the summary file.
+
+Then load, read in full and execute `{healthCheckStepFile}`: the health check runs once per batch, here. The batch ends with the event's `exit_code`: 0 when every brief finished, else the highest exit code among the briefs that failed.
+
+If `summarize` exits non-zero (a brief is still pending, or the batch file is gone or unreadable), the health check does not run: display "**The batch stopped:** {its `message`}" and **HARD HALT** (exit code 4, `write-failed`, phase `batch-mode`; emit with nothing to stage in, as §1 does, with the reason "The batch stopped: <its message>"). The summary files may be missing then, but each brief's own result contract is in its `{forge_version}`.

package/src/skf-create-skill/references/ccc-index-check.md

@@ -0,0 +1,27 @@
+# CCC Index Check
+
+Step 3 §2b (deferred ccc discovery on SKF's workspace clone) and step 7 §6b (the index the skill registers) load this file after they run `ccc index`. It waits for a running pass, checks that the source language was indexed, and repairs the index settings when it was not. The caller binds:
+
+- `{ccc_root}`: the folder the index belongs to. ccc takes no path argument, so every ccc command below runs as `cd "{ccc_root}" && ccc ...`.
+- `{ccc_settings_owner}`: `skf` when `{ccc_root}` is SKF's workspace clone of a remote source, whose `settings.yml` SKF edits only through `{mergeCccExclusionsHelper}`; `user` when `{ccc_root}` is the user's own source folder, whose `settings.yml` SKF never edits.
+
+`{mergeCccExclusionsHelper}` is the first existing path in the caller's `mergeCccExclusionsProbeOrder`; run it from `{project-root}`.
+
+## 1. Wait for the Pass
+
+Run `cd "{ccc_root}" && ccc status`. If it prints an `Indexing in progress:` line, a pass is still running and the counts below it are not final: run `cd "{ccc_root}" && ccc index` again, which waits for the running pass to finish and then makes a quick incremental pass, then run `ccc status` again. If the line is still there after 3 such runs, return **index unverified** to the caller and skip §2 and §3.
+
+## 2. Check the Languages
+
+Once the line is gone, read the `Languages:` breakdown: a non-zero `Chunks`/`Files` total is not sufficient. Confirm the source's primary language (`{brief.language}`) reports a non-trivial chunk count. An index dominated by `markdown`/config chunks with the source language absent or near-zero means the source code was never indexed, and searches over it return nothing useful. When the source language is there, return **verified**.
+
+## 3. Repair
+
+When the source language is absent, apply these repairs in order, stopping at the first one after which `Languages:` shows the source language:
+
+1. **No project of its own:** `{ccc_root}/.cocoindex_code/settings.yml` is missing and the `Project:` line of `ccc status` names another folder, so ccc indexed an enclosing project. With `{ccc_settings_owner}` `skf`, run `uv run {mergeCccExclusionsHelper} --clone-root "{ccc_root}"`: it runs `ccc init -f` there and adds the standard build and dependency exclusions. With `user`, run `cd "{ccc_root}" && ccc init -f`. Then run `ccc index`, then run `ccc status` and check `Languages:` again.
+2. **Language not included:** ccc indexes only the file types listed in `include_patterns`, and its default list leaves some languages out (Elixir's `.ex`, for example). Take the extensions of the `{brief.language}` files in step 3's §2 filtered file list, at most 3.
+   - `skf`: run `uv run {mergeCccExclusionsHelper} --clone-root "{ccc_root}" --include-ext {ext}`, with one `--include-ext` per extension. It appends a single-quoted `- '**/*.{ext}'` item for each extension no `include_patterns` entry matches (`includes_added_list`) and lists the extensions an entry already matches (`includes_covered_list`). On a file with no `include_patterns` list it adds nothing and says so in `warnings`, since a list written from scratch replaces ccc's default file types: display that `{ccc_root}/.cocoindex_code/settings.yml` has no `include_patterns` list to add the `{brief.language}` file types to, and return **degraded**. When `includes_covered_list` holds every extension, the files are excluded rather than left out of `include_patterns`: skip this repair and display which `exclude_patterns` entry covers the `{brief.language}` source files (`**/build` covers a package under `src/build/`, for example). Otherwise display "Added {includes_added_list} to include_patterns in {ccc_root}/.cocoindex_code/settings.yml so ccc indexes {brief.language} files.", run a plain `cd "{ccc_root}" && ccc index`, then run `ccc status` and check `Languages:` again.
+   - `user`: the settings belong to the user's project, so do not edit them. Keep the extensions that no `include_patterns` entry matches. If there are none, the files are excluded rather than left out of `include_patterns`: display which `exclude_patterns` entry covers the `{brief.language}` source files. Otherwise display that ccc did not index `{brief.language}` files, and the exact lines to add under `include_patterns` in `{ccc_root}/.cocoindex_code/settings.yml`, one single-quoted `- '**/*.{ext}'` line per extension (YAML reads an unquoted leading `*` as an alias, and ccc then fails to load the file), followed by a plain `ccc index`.
+
+A plain `ccc index` is enough after any `settings.yml` edit; nothing needs deleting first. Do not run `ccc reset`: it deletes only the index databases and keeps `settings.yml`, so it cannot repair the settings, a `ccc index` right after it can fail and leave the project with no index, and run from a folder without its own `settings.yml` it deletes the enclosing project's index. If the source language is still missing after these repairs, return **degraded** to the caller.