bmad-module-skill-forge 2.2.0 → 3.0.0

package/src/skf-create-skill/references/generate-artifacts.md

@@ -1,20 +1,67 @@
 ---
 nextStepFile: 'report.md'
 forgeTierConfig: '{sidecar_path}/forge-tier.yaml'
+cccIndexCheckData: 'references/ccc-index-check.md'
+# Resolve `{skillInventoryHelper}` by probing `{skillInventoryProbeOrder}` in
+# order (installed SKF module path first, src/ dev-checkout fallback); first
+# existing path wins. §1 runs its write check before any directory is
+# created; without it, §1 writes only into a skill folder that does not exist yet.
+skillInventoryProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-skill-inventory.py'
+  - '{project-root}/src/shared/scripts/skf-skill-inventory.py'
 # Resolve `{atomicWriteHelper}` by probing `{atomicWriteProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
-# path wins. HALT if neither resolves — the active-symlink flip and registry
-# writes below go through the atomic helper for concurrency safety.
+# path wins. HALT (exit code 3, helper-missing) if neither resolves: the
+# active-symlink flip (§4) goes through the atomic helper, so §2 resolves it
+# before anything is written.
 atomicWriteProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
+# Resolve `{cccGitHygieneHelper}` to the first existing path. It keeps ccc's
+# index folders and SKF's workspace lock out of git, and undoes the
+# `.gitignore` edit `ccc init` makes in a workspace clone. If neither path
+# exists, skip the call and continue: it never gates the workflow.
+cccGitHygieneProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-ccc-git-hygiene.py'
+  - '{project-root}/src/shared/scripts/skf-ccc-git-hygiene.py'
 # Resolve `{forgeTierRwHelper}` by probing `{forgeTierRwProbeOrder}` in order
 # (installed SKF module path first, src/ dev-checkout fallback); first existing
-# path wins. HALT if neither resolves — §6b's ccc-index registry round-trip is
-# comment-preserving and has no prose fallback.
+# path wins. §6 and §6b change the registry only through it, a
+# comment-preserving round-trip with no prose fallback. If neither resolves,
+# they skip the registry change with a warning: registration never halts the
+# workflow.
 forgeTierRwProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-forge-tier-rw.py'
   - '{project-root}/src/shared/scripts/skf-forge-tier-rw.py'
+# Resolve `{mergeCccExclusionsHelper}` to the first existing path. §6b
+# prepares the settings.yml of SKF's workspace clone with it; if neither path
+# exists, §6b skips the index of a remote source.
+mergeCccExclusionsProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-merge-ccc-exclusions.py'
+  - '{project-root}/src/shared/scripts/skf-merge-ccc-exclusions.py'
+# Resolve `{extractionInventoryHelper}` to the first existing path; HALT
+# (exit code 3, helper-missing) if neither exists. §2 writes
+# extraction-rules.yaml from the extraction inventory through its `rules`.
+extractionInventoryProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-extraction-inventory.py'
+  - '{project-root}/src/shared/scripts/skf-extraction-inventory.py'
+# Resolve `{promoteStagedHelper}` to the first existing path; HALT (exit
+# code 3, helper-missing) if neither exists. §3 promotes the staged skill
+# through it.
+promoteStagedProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-promote-staged.py'
+  - '{project-root}/src/shared/scripts/skf-promote-staged.py'
+# Resolve `{sourceTreeHelper}` to the first existing path. §7 removes the
+# private tree step 3 read a remote source from; if neither path exists, the
+# tree stays until a later run removes it, seven days on; every HARD HALT
+# also closes the tree through it (Rules).
+sourceTreeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-source-tree.py'
+  - '{project-root}/src/shared/scripts/skf-source-tree.py'
+# HARD HALT helper (Rules).
+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}. -->
@@ -23,78 +70,76 @@ forgeTierRwProbeOrder:
 
 ## STEP GOAL:
 
-To write all compiled content to disk — 4 deliverable files to `{skill_package}` and 3 workspace artifacts to `{forge_version}`, creating directories as needed. Then create or update the `active` symlink.
+To publish the staged skill byte for byte: the deliverables to `{skill_package}` and the workspace artifacts to `{forge_version}`, through one helper that creates the folders it needs. Then create or update the `active` symlink.
 
 ## Rules
 
-- Focus only on writing files from compiled content — do not modify content during writing
-- All base artifact types must be written (4 deliverables + 3 workspace files + N reference files)
-- Create directories before writing files
+- Generate only `extraction-rules.yaml` (§2): every other file is promoted as steps 5 to 6 left it in the staging folder, never written again from what context holds
+- All base artifact types must be written (3 deliverables + N reference files + 3 workspace files)
+- A HARD HALT, once step 3 §2b has bound `{source_tree}`, first runs `uv run {sourceTreeHelper} close --tree "{source_tree}"` from `{project-root}` (resolved from `{sourceTreeProbeOrder}`) and goes on whatever it prints, and emits through `{emitEnvelopeHelper}`, resolved from `{emitEnvelopeProbeOrder}` when it is not bound. After its envelope, under `--batch` it ends only this brief: return to `references/batch-mode.md` §3, even when the halt reads as the end of the run.
 
 ## MANDATORY SEQUENCE
 
-### 1. Create Directory Structure
+### 1. Check Ownership
 
-Resolve `{version}` from the skill brief's `version` field. Create the following directories:
+`{name}` is the skill name from the brief (kebab-case). `{version}` is the working version: the brief's `version`, unless step 3's source resolution replaced it with `target_version` or the detected source version (`source-resolution-protocols.md` "Version Reconciliation"), with build metadata stripped per `knowledge/version-paths.md`.
 
-```
-{skill_group}                          # {skills_output_folder}/{name}/
-{skill_package}                        # {skills_output_folder}/{name}/{version}/{name}/
-{skill_package}/references/
-{forge_version}                        # {forge_data_folder}/{name}/{version}/
+**Ownership check.** Run it before creating any directory, `{forge_version}` included. Resolve `{skillInventoryHelper}` ← first existing path in `{skillInventoryProbeOrder}` and run:
+
+```bash
+uv run {skillInventoryHelper} {skills_output_folder} --skill {name} --write-check --write-version {version} --forge-data-folder {forge_data_folder}
 ```
 
-If `scripts_inventory` is non-empty, also create: `{skill_package}/scripts/`
-If `assets_inventory` is non-empty, also create: `{skill_package}/assets/`
+`--forge-data-folder` only tells the helper whether both settings name one folder, so the brief and forge files there count as SKF output.
 
-Where `{name}` is the skill name from the brief (kebab-case) and `{version}` is the semver version from the brief (with build metadata stripped per `knowledge/version-paths.md`).
+Bind `{write_verdict}` ← `write_check.verdict`, `{write_folder}` ← `write_check.folder`, `{write_detail}` ← `write_check.detail` and `{existing_generator}` ← `write_check.version_generated_by` (the build §3 replaces, for step 8; null when none). Continue only when the status is `ok` and `{write_verdict}` is `"ok"`: nothing is at the skill folder yet, it holds only what an interrupted run leaves, or SKF generated it and the version is new or SKF's own. Otherwise create nothing and refuse with the first case that applies:
 
-If directories already exist, do not error — proceed with file writing (overwrites existing files).
+- `{write_verdict}` is `"flat-layout"` → `halt_reason: "flat-layout"`: "**`{name}` still uses the flat layout — nothing was written.** A version written beside its root `SKILL.md` would leave a skill SKF can no longer migrate or rename. Run `@Ferris TS {name}` (or US, AS or EX) once to move it into the versioned layout, then re-run."
+- `{write_verdict}` is `"not-skf-output"` → `halt_reason: "not-skf-output"`: "**`{name}` is not SKF output — nothing was written.** `{write_folder}` {write_detail}, so SKF will not write a version there. A shared `{skills_output_folder}` is supported: SKF leaves the skills it did not generate alone, so manage `{name}` yourself, and set a different `name` in the brief to create this skill beside it. Only if `{skills_output_folder}` holds a module's own source rather than skills, set `skills_output_folder` in `{project-root}/_bmad/skf/config.yaml` to a folder of its own, move your SKF skills there and re-run `/skf-setup`. A version folder with no `metadata.json` can also be one that an interrupted create-skill run left behind; delete it yourself in that case."
+- The status is not `ok`, or the output has no `write_check` (an older helper: it has no `--write-check` and reports a new skill as `SKILL_NOT_FOUND`) → `halt_reason: "not-skf-output"`: the same message with "SKF could not check it ({the helper's `error`, if any}; re-install SKF if the installed `skf-skill-inventory.py` is out of date)" in place of "`{write_folder}` {write_detail}".
+- When no helper candidate resolves, continue only when nothing exists at `{skill_group}` (no folder, no file, not even a broken link). Otherwise refuse with `halt_reason: "not-skf-output"` and the same message, giving "SKF cannot check who generated `{skill_group}`: `skf-skill-inventory.py` is missing; re-install SKF" in place of "`{write_folder}` {write_detail}".
 
-### 2. Write Deliverables to {skill_package}
+Each refusal is a **HARD HALT** (exit code 5, `{halt_reason}`, phase `generate-artifacts`; 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"`), with the `halt_reason` shown and `{write_folder}` as `"path"`. Nothing was written, and the command leaves out `--result-dir`: a result file would land in a folder SKF refuses to write.
 
-Write these 4 files from the compiled content:
+The folders this step writes:
 
-**File 1:** `{skill_package}/SKILL.md`
-- The complete compiled skill document
-- agentskills.io-compliant format with all sections
-- [MANUAL] markers seeded
+```
+{skill_group}                          # {skills_output_folder}/{name}/
+{skill_package}                        # {skills_output_folder}/{name}/{version}/{name}/
+{forge_version}                        # {forge_data_folder}/{name}/{version}/
+```
 
-**File 2:** `{skill_package}/context-snippet.md`
-- Compressed 2-line format for CLAUDE.md integration
+The promotion (§3) creates them. An existing `{skill_package}` is replaced whole: the ownership check accepted it, and a package left half from an earlier compile of this version would mix two runs. Only its hand-written `[MANUAL]` content carries forward: its blocks are in the staged SKILL.md (step 5), and §3 carries its files.
 
-**File 3:** `{skill_package}/metadata.json`
-- Machine-readable birth certificate with stats and provenance
+### 2. Generate extraction-rules.yaml
 
-**File 4:** `{skill_package}/references/*.md`
-- One file per function group or type
-- Progressive disclosure detail files
+`extraction-rules.yaml` records the language and the ast-grep rules this extraction used, for reproducibility, and it is the one file this step generates. `{extractionInventoryHelper}` writes it from the extraction inventory step 3 §5 wrote, `{extraction_inventory}` (`{project-root}/_bmad-output/.skf-stage/{skill-name}.inventory.json`): its `extraction_rules` (`recipe_set`, the `recipes` ids the runner ran, its `scope` and `ast_grep_version`), its `tier` and extraction mode, and the brief's `language`. Resolve `{extractionInventoryHelper}` ← first existing path in `{extractionInventoryProbeOrder}` and `{atomicWriteHelper}` ← first existing path in `{atomicWriteProbeOrder}` (§4's flip goes through it); if either has no path, **HARD HALT** (exit code 3, `helper-missing`, phase `generate-artifacts`; 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 generate the artifacts: {the missing script} is missing. Re-install SKF, then re-run create-skill." From `{project-root}`, write it into the staging folder, so the promotion carries it with the rest:
 
-**Files 4b (conditional):** `{skill_package}/scripts/*`
-- One file per detected script, copied from source with content preserved
-- Only created when `scripts_inventory` is non-empty
+```bash
+uv run {extractionInventoryHelper} rules --inventory "{extraction_inventory}" --language "{brief.language}" --target "<staging-skill-dir>/extraction-rules.yaml"
+```
 
-**Files 4c (conditional):** `{skill_package}/assets/*`
-- One file per detected asset, copied from source with content preserved
-- Only created when `assets_inventory` is non-empty
+When it exits non-zero, **HARD HALT** (exit code 4, `write-failed`, phase `generate-artifacts`; 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"`), with `"path"` the staged `extraction-rules.yaml`: "Cannot write extraction-rules.yaml: {the helper's message}. Check permissions and disk space." Nothing has been promoted yet.
 
-**Note on `file_type: "doc"` entries** (promoted authoritative docs from step 3 §2a):
+### 3. Promote the Staged Skill
 
-Promoted docs are tracked in `file_entries[]` with `file_type: "doc"` for drift detection but are **not** copied into the skill package. The source file remains at its original location outside `{skill_package}`. Step-07 must skip any `file_entries[]` row where `file_type == "doc"` when iterating for file copy — these entries exist only for provenance tracking, not bundling. Step-07 verification (§5) also does not check for doc files in the skill package.
+Resolve `{promoteStagedHelper}` ← first existing path in `{promoteStagedProbeOrder}`; if neither exists, **HARD HALT** (exit code 3, `helper-missing`, phase `generate-artifacts`; 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 promote the staged skill: skf-promote-staged.py is missing. Re-install SKF, then re-run create-skill." From `{project-root}`, run:
 
-### 3. Write Workspace Artifacts to {forge_version}
+```bash
+uv run {promoteStagedHelper} promote --stage "<staging-skill-dir>" --package "{skill_package}" --forge-version "{forge_version}" [--inventory "{extraction_inventory}" --source-root "{source_root}"] [--carry-manual "{skill_package}"]
+```
 
-Write these 3 files from the compiled content:
+Pass `--inventory` and `--source-root` when the inventory's `scripts_inventory` or `assets_inventory` is not empty, and `--carry-manual "{skill_package}"` when `{skill_package}` already exists. The helper copies the staged bytes, never a copy from context:
 
-**File 5:** `{forge_version}/provenance-map.json`
-- Per-claim source map with AST bindings and confidence tiers
+- **To `{skill_package}`:** `SKILL.md`, `context-snippet.md`, `metadata.json` (with the `doc_sources` step 5a wrote into it) and every file under the staged `references/` (the `references/full-*.md` files step 5b extracted included), plus `scripts/{name}` and `assets/{name}` for each inventory script and asset, copied from `{source_root}`, and, with `--carry-manual`, the earlier build's `scripts/[MANUAL]/` and `assets/[MANUAL]/` files. The package is built beside its target and swapped in, so a reader never sees half of it.
+- **To `{forge_version}`:** `{forge_version}/provenance-map.json`, `{forge_version}/evidence-report.md` and `{forge_version}/extraction-rules.yaml`, one atomic write each, and, with a warning, `{forge_version}/manual-backup/SKILL-<UTC time>.md` (the earlier SKILL.md, a new file each run) when the staged one lacks a hand-written `[MANUAL]` block of it.
+- **Not copied:** a promoted authoritative doc (`file_entries[]` with `file_type: "doc"`, from step 3 §2a) stays at its source path; the provenance map tracks it for drift detection.
 
-**File 6:** `{forge_version}/evidence-report.md`
-- Build artifact with extraction summary, validation results, warnings
+Bind `{promotion}` ← its JSON: `files[]` (each promoted file's `path`, `kind`, `bytes` and `sha256`, read back and checked against the staged bytes), `counts`, `ignored` (staged files it did not promote), `manual` (what `--carry-manual` kept: `blocks`, `missing_blocks`, `files`, `backup`) and `warnings`; display each warning. Act on its exit code:
 
-**File 7:** `{forge_version}/extraction-rules.yaml`
-- Language and ast-grep schema used for this extraction (for reproducibility)
-- Note: This file is generated here from extraction data collected during steps 3-4, not assembled in step 5
+- **0:** continue to §4.
+- **1** (a staged file it needs is missing, the inventory names a script or asset it cannot copy, or the earlier package cannot be read; nothing was written): **HARD HALT** (exit code 4, `staging-unreadable`, phase `generate-artifacts`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --result-dir "{forge_version}" --target stderr < "{run_dir}/halt.json"`), with the message the helper printed on stderr.
+- **2** (a write failed; the earlier package stays in place when the swap itself failed): **HARD HALT** (exit code 4, `write-failed`, phase `generate-artifacts`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --result-dir "{forge_version}" --target stderr < "{run_dir}/halt.json"`): "Artifact generation failed: {the message the helper printed on stderr}. Check permissions and disk space." Once the swap succeeded, stage `"skill_package"` and `"outputs"` as the Workflow Rules say.
 
 ### 4. Create Active Symlink (atomic flip)
 
@@ -106,28 +151,15 @@ python3 {atomicWriteHelper} flip-link \
   --target {version}
 ```
 
-The helper returns non-zero (exit 2) if `{skill_group}/active` already exists as a real directory or file rather than a symlink — in that case, halt with: "Refusing to flip `{skill_group}/active` — existing path is not a symlink. Investigate manually; expected a symlink pointing at a version directory."
+The helper returns non-zero (exit 2) if `{skill_group}/active` already exists as a real directory or file rather than a symlink. In that case **HARD HALT** (exit code 5, `active-link-blocked`, phase `generate-artifacts`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --result-dir "{forge_version}" --target stderr < "{run_dir}/halt.json"`), with `"skill_package"`, `"outputs"` and `{skill_group}/active` as `"path"`: "Refusing to flip `{skill_group}/active`: the existing path is not a symlink. Investigate manually; expected a symlink pointing at a version directory."
 
 Do not `rm` + `ln -s` the active link by hand. The bare-rm pattern has two failure modes: (1) a concurrent reader sees a missing `active` mid-flip, and (2) a bug or typo that replaces `{skill_group}/active` with a plain directory turns the next manual `rm -rf {skill_group}/active` into data loss. The helper encapsulates both guards.
 
 ### 5. Verify Write Completion
 
-After all files are written, verify:
-- All 4 deliverable artifact types exist (SKILL.md, context-snippet.md, metadata.json, **and** either at least one file in `references/` **or** `references/` is empty AND Tier-2 content is inline in SKILL.md — see "Empty `references/` exception" below), all 3 workspace artifacts exist (provenance-map.json, evidence-report.md, extraction-rules.yaml), plus scripts/ and assets/ files when inventories are non-empty
-- The `active` symlink at `{skill_group}/active` resolves to `{version}`
-- Store `ref_count` = count of files written to `references/` for use in step 8 report
-- List each file with its path and size
+The promotion's exit 0 is the write check: it refused a missing staged file, script or asset before writing (§3, exit 1) and read back every file it wrote against the staged bytes (exit 2 on a mismatch), and the flip's exit 0 (§4) means `{skill_group}/active` points at `{version}`. From `{promotion}`, bind `ref_count` ← `counts.references` for the step 8 report, and list each file of its `files[]` with its `path` and `bytes`.
 
-**Empty `references/` exception (Tier-2 inline):** `ref_count == 0` is a valid completion state when step 6 kept Tier-2 content inline in SKILL.md — e.g., the body was already under the size limit, or `skill-check` was unavailable and the manual fallback (step 6 §3) skipped the split. In that case, append a single line to `{forge_version}/evidence-report.md` recording the inline state so downstream tooling and audits can distinguish "inline by design" from "split-body skipped due to error":
-
-```
-ref_count: 0  # Tier-2 kept inline in SKILL.md (no split performed in step 6)
-```
-
-When `ref_count > 0` is expected (because step 6 ran a split) but no files were written, halt with: "Split-body produced zero reference files. Investigate step 6 output before retrying — empty `references/` after a split is never a valid state."
-
-**If any write failed:**
-Halt with: "Artifact generation failed: could not write `{file_path}`. Check permissions and disk space."
+`ref_count` 0 is a valid state when step 6 kept Tier-2 content inline (its evidence report says so on the Body line). When step 5b or step 6 split the body (`sections_extracted` is not empty) and `ref_count` is 0 anyway, **HARD HALT** (exit code 5, `references-missing`, phase `generate-artifacts`; stage `{run_dir}/halt.json` per the Workflow Rules and run `uv run {emitEnvelopeHelper} emit-halt --workflow skf-create-skill --run-dir "{run_dir}" --result-dir "{forge_version}" --target stderr < "{run_dir}/halt.json"`), with `"skill_package"` and `"outputs"`: "Split-body produced zero reference files. Investigate step 6 output before retrying: empty `references/` after a split is never a valid state."
 
 **If all writes succeeded:**
 Display brief confirmation:
@@ -157,32 +189,32 @@ Proceeding to compilation report..."
 
 Index the generated skill artifacts into a QMD collection so that audit-skill and update-skill can perform high-signal searches against curated extraction data instead of raw source files.
 
-**Collection creation:** Create (or replace) a QMD collection from the skill artifacts:
+Resolve `{forgeTierRwHelper}` from `{forgeTierRwProbeOrder}`; first existing path wins. Every registry change below goes through it: it holds `{sidecar_path}/forge-tier.yaml.lock` for its one read-modify-write of `{forgeTierConfig}`, so no step takes a lock of its own. If no candidate exists, warn "forge-tier.yaml registry not updated: skf-forge-tier-rw.py is missing; re-install SKF" and leave out every registry command below.
+
+**Collection creation:** Create (or replace) a QMD collection from the skill artifacts. When `qmd collection add` fails after the `remove`, the collection is gone from QMD, so its registry entry goes too:
+
 ```bash
 qmd collection remove {name}-extraction 2>/dev/null  # no-op if new
-qmd collection add {skill_package} --name {name}-extraction --mask "**/*"
-qmd embed --collection {name}-extraction  # generates vector embeddings for semantic (vec) and HyDE query sub-types; scope to this collection to avoid re-embedding others. If the installed qmd CLI lacks --collection, gate the embed behind a per-skill freshness check (skip when the existing {name}-extraction entry is within 24 hours — rationale: an unscoped embed re-runs over every collection, which in a populated QMD store can cost minutes of GPU time per create-skill run; 24 hours is long enough to absorb rapid re-forges from the same brief without losing meaningful content freshness) and warn in evidence-report.
+if qmd collection add {skill_package} --name {name}-extraction --mask "**/*"; then
+  qmd embed --collection {name}-extraction
+else
+  uv run {forgeTierRwHelper} remove-qmd-collection --target "{forgeTierConfig}" --name {name}-extraction
+fi
 ```
 
-**Registry update:**
-
-Read `{forgeTierConfig}` and update the `qmd_collections` array **under an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock`** (see step 3b §4 for the full pattern — acquire lock → read → modify → atomic write via `skf-atomic-write.py write` → release). If `flock` is unavailable, fall back to read-CAS-by-mtime.
+`qmd embed` generates the vector embeddings for semantic (`vec`) and HyDE query sub-types; scope it to this collection to avoid re-embedding others. If the installed qmd CLI lacks `--collection`, gate the embed behind a per-skill freshness check: read the registry with `uv run {forgeTierRwHelper} read --target "{forgeTierConfig}"`, skip the embed when the `{name}-extraction` entry in its `data.qmd_collections` was created within the last 24 hours, and warn in evidence-report. An unscoped embed re-runs over every collection, which in a populated QMD store can cost minutes of GPU time per create-skill run; 24 hours is long enough to absorb rapid re-forges from the same brief without losing meaningful content freshness.
 
-If an entry with `name: "{name}-extraction"` already exists, replace it. Otherwise, append:
+**Registry update:** only when `qmd collection add` succeeded, register the collection. The helper replaces the entry with the same `name`, or appends one:
 
-```yaml
-  - name: "{name}-extraction"
-    type: "extraction"
-    source_workflow: "create-skill"
-    skill_name: "{name}"
-    created_at: "{current ISO date}"
+```bash
+uv run {forgeTierRwHelper} register-qmd-collection --target "{forgeTierConfig}" <<'SKF_REGISTRY_ENTRY'
+{"name": "{name}-extraction", "type": "extraction", "source_workflow": "create-skill", "skill_name": "{name}", "created_at": "{current ISO date}"}
+SKF_REGISTRY_ENTRY
 ```
 
-Write the updated forge-tier.yaml.
-
 **Error handling:**
 - If QMD collection creation fails: log the error, note that indexing can be retried via [SF] setup. Do not fail the workflow.
-- If forge-tier.yaml update fails: log the error, continue. The collection exists in QMD even if the registry entry failed.
+- If a registry command fails: log the error, continue. The collection exists in QMD even if the registry entry failed.
 
 **IF forge tier is not Deep:** Skip this section silently. No messaging.
 
@@ -190,36 +222,56 @@ Write the updated forge-tier.yaml.
 
 **IF `tools.ccc` is true in forge-tier.yaml (Forge+ or Deep with ccc available):**
 
-Ensure the source path used for extraction is indexed by ccc and registered in the `ccc_index_registry` array.
+Ensure the source of this skill is indexed by ccc and registered in the `ccc_index_registry` array.
+
+**Pick the folder:** bind `{ccc_root}`, the folder the index belongs to, and `{ccc_settings_owner}`:
+
+- **Docs-only skill** (`source_type: "docs-only"`): there is no source to index. Skip the rest of this section.
+- **Remote source** (`source_repo` is a GitHub URL, an `owner/repo` shorthand or another git URL): the index belongs in SKF's workspace clone, which persists, and not in the tree step 3 read the source from, which §7 removes. When step 3 bound `{remote_clone_path}`, the clone holds `source_commit`: bind `{ccc_root}` ← `{remote_clone_path}` and `{ccc_settings_owner}` ← `skf`. When it left `{remote_clone_path}` null (Quick tier, a run step 3 degraded to source reading, or a clone it did not move to this skill's commit), skip the rest of this section, including the registry update.
+- **Local source:** bind `{ccc_root}` ← `{source_root}` and `{ccc_settings_owner}` ← `user`.
 
 **Index verification:**
 
-**Working-directory contract:** `ccc init`, `ccc index`, and `ccc status` take **no positional path argument** — each operates on the current working directory, and passing a path makes them exit non-zero with `Got unexpected extra argument`. Run them from `{source_root}` (`cd {source_root} && ccc …`, the same form `extract.md` step 2b and `knowledge/ccc-bridge.md` use), then return to `{project-root}` before the registry update below, which resolves `{forgeTierConfig}` relative to the project.
+**Working-directory contract:** `ccc init`, `ccc index`, and `ccc status` take **no positional path argument**: each operates on the current working directory, and passing a path makes them exit non-zero with `Got unexpected extra argument`. Run them from `{ccc_root}` (`cd "{ccc_root}" && ccc …`, the same form `extract.md` step 2b and `knowledge/ccc-bridge.md` use), then return to `{project-root}` before the registry update below, which resolves `{forgeTierConfig}` relative to the project.
+
+**Project root without settings:** check this before running any ccc command. When `{ccc_root}` is `{project-root}` and `{project-root}/.cocoindex_code/settings.yml` does not exist, do not run `ccc init` or `ccc index`: `/skf-setup` initializes the project index with the SKF exclusions, and in a project nested inside another git checkout `ccc index` would index the enclosing repository instead. Skip the rest of this section, including the registry update, note that re-running `/skf-setup` enables the index, and continue to §7.
+
+Otherwise, `ccc index` requires the directory to be initialized first:
+
+- `{ccc_settings_owner}` `skf`: resolve `{mergeCccExclusionsHelper}` from `{mergeCccExclusionsProbeOrder}` and, from `{project-root}`, run `uv run {mergeCccExclusionsHelper} --clone-root "{ccc_root}"`. It runs `ccc init -f` in the clone when its `settings.yml` is missing and adds the standard build and dependency exclusions the file lacks, as step 3 §2b does, so it changes nothing once step 3 prepared the clone. When no candidate resolves, the command fails or `settings_ready` is false, log it and skip the rest of this section, including the registry update.
+- `{ccc_settings_owner}` `user`: run `cd "{ccc_root}" && ccc init` (idempotent: a no-op once initialized).
+
+Then run `cd "{ccc_root}" && ccc index`, or use the ccc MCP tool. `ccc_bridge.ensure_index` is a conceptual interface, not a callable function. Indexing is a no-op if the source was already indexed during setup, step 2b or step 3.
+
+**Nested project marker:** when `{ccc_root}` is a local source inside a git checkout whose `.git` is a folder, or inside a folder that holds `.cocoindex_code/settings.yml` (a local source such as `./packages/lib`, or a linked worktree or submodule inside such a checkout, whose `.git` file ccc does not count as a marker), `ccc init` exits non-zero with `A parent directory has a project marker`. This is expected: re-run as `cd "{ccc_root}" && ccc init -f` to initialize at the subtree anyway, then `ccc index`. Do not treat the parent-marker warning as fatal. ccc writes no `.gitignore` entry for such a project; **Keep the index out of git** below covers it.
 
-`ccc index` requires the directory to be initialized first. Run `cd {source_root} && ccc init` (idempotent — a no-op once initialized) before `cd {source_root} && ccc index`, or use the ccc MCP tool. `ccc_bridge.ensure_index` is a conceptual interface, not a callable function. Indexing is a no-op if the source was already indexed during setup or step 2b.
+**Verify the index is not degraded:** after `ccc index`, load `{cccIndexCheckData}` and run it with `{ccc_root}` and `{ccc_settings_owner}`. An index that misses the source language silently cripples later `skf-audit-skill` / `skf-update-skill` searches with no error surfaced. On **index unverified**, log "index unverified" and continue with **Keep the index out of git**. On **degraded**, log it and continue per the error handling below: a degraded index is not workflow-fatal, but it must be recorded so the gap is visible.
 
-**Nested project marker:** when `{source_root}` is a subtree of a repo that already carries a project marker (e.g. a cloned source tree under `.forge-sources/`, or a `.cocoindex_code` / VCS marker in a parent), `ccc init` exits non-zero with `A parent directory has a project marker`. This is expected — re-run as `cd {source_root} && ccc init -f` to initialize at the subtree anyway, then `ccc index`. Do not treat the parent-marker warning as fatal.
+**Keep the index out of git:** once the ccc commands above are done (after the check, after "index unverified", or after a ccc command failed), return to `{project-root}` and resolve `{cccGitHygieneHelper}` from `{cccGitHygieneProbeOrder}`; first existing path wins. If no candidate exists, or the helper exits non-zero or prints no JSON, log "ccc git hygiene skipped" and continue to the registry update: this check never fails the workflow.
 
-**Verify the index is not degraded:** after `ccc index`, run `cd {source_root} && ccc status` and 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 `ccc index` ran against degraded settings (a stale `.cocoindex_code/` inherited from a parent project, or a no-op `ccc init` over a prior partial index that returned `Project already initialized.`) — the source code was never indexed, which silently cripples later `skf-audit-skill` / `skf-update-skill` searches with no error surfaced. When the source language is absent, rebuild from a clean init (`cd {source_root} && ccc init -f` then `ccc index`) and re-check the breakdown. Note that `-f` only skips the parent-marker warning — it does not clear a stale `.cocoindex_code/`; when the degraded settings survive the forced re-init, `ccc reset` (run from `{source_root}`) is what discards the existing databases. If the source language is still missing after a forced re-init, log it and continue per the error handling below — a degraded index is not workflow-fatal, but it must be recorded so the gap is visible.
+- **Workspace clone** (`{ccc_settings_owner}` is `skf`): run `uv run {cccGitHygieneHelper} workspace --repo "{ccc_root}"`. It undoes the edit a `ccc init` or `ccc index` made to the clone's tracked `.gitignore` and keeps the index folder out of git through the clone's `.git/info/exclude`, so a later move of the clone to another ref is not blocked. Read nothing from its output.
+- **Local source** (`{ccc_settings_owner}` is `user`): run `uv run {cccGitHygieneHelper} nested --dir "{ccc_root}" --project-root "{project-root}"`. ccc gitignores its index only at the top of a git checkout whose `.git` is a folder, so for a project in a subfolder of a checkout (the `ccc init -f` case above), a linked worktree or a submodule, `git status` lists the index database and a `git add -A` would commit it. When git does not ignore `{ccc_root}/.cocoindex_code/`, the helper writes a `.gitignore` holding `*` inside that folder so the folder ignores itself; SKF never edits a project's own `.gitignore`. It also repairs a nested index an earlier run left, and does nothing for `{project-root}` itself, for a folder without `.cocoindex_code/settings.yml`, or outside a git work tree. Bind `{ccc_ignore_notice}` ← `notice` and display `{ccc_ignore_notice}` verbatim when it is not null: its remedy command is quoted for paths with spaces.
 
 **Registry update:**
 
-**Resolve `{forgeTierRwHelper}`** from `{forgeTierRwProbeOrder}`; first existing path wins. HALT if no candidate exists.
+**Resolve `{forgeTierRwHelper}`** from `{forgeTierRwProbeOrder}`; first existing path wins. If no candidate exists, log it and skip the registry update.
 
-Register the indexed source path via `register-ccc-index` — a comment-preserving round-trip on `forge-tier.yaml`. This differs from §6, which mutates the registry with an inline read→modify→atomic-write under `flock`; here the helper owns the read→modify→write internally so the `ccc_index_registry` deduplication logic stays in the script. Acquire an exclusive `flock` on `{sidecar_path}/forge-tier.yaml.lock`, then:
+Register the indexed folder with `register-ccc-index`, a comment-preserving round-trip on `forge-tier.yaml` that keeps the `ccc_index_registry` deduplication in the script. Like every registry change of §6, the helper holds `{sidecar_path}/forge-tier.yaml.lock` for its one read-modify-write. Write `{ccc_root}` with `/` separators, so the JSON stays valid on Windows:
 
 ```bash
-echo '{"source_repo":"{brief.source_repo}","path":"{source_root}","skill_name":"{name}","indexed_at":"{current ISO date}","source_workflow":"create-skill"}' \
-  | uv run {forgeTierRwHelper} register-ccc-index --target {forgeTierConfig}
+uv run {forgeTierRwHelper} register-ccc-index --target "{forgeTierConfig}" <<'SKF_REGISTRY_ENTRY'
+{"source_repo": "{brief.source_repo}", "path": "{ccc_root}", "skill_name": "{name}", "indexed_at": "{current ISO date}", "source_workflow": "create-skill"}
+SKF_REGISTRY_ENTRY
 ```
 
-Deduplicates by `source_repo` + `skill_name` (not local `path`, which may be ephemeral). Release the lock after the command completes. If `flock` is unavailable, fall back to read-CAS-by-mtime.
+Deduplicates by `source_repo` + `skill_name`, not by the local `path`.
 
-**Error handling:** If ccc indexing or registry update fails, log and continue — do not fail the workflow.
+**Error handling:** If ccc indexing or registry update fails, log and continue: do not fail the workflow.
 
 **IF `tools.ccc` is false:** Skip this section silently.
 
 ### 7. Auto-Proceed
 
-No user interaction. Once all 7 files are written and verified (and optionally indexed into QMD), load `{nextStepFile}`, read it fully, then execute it. A QMD-indexing failure does not block; a file-write failure halts (§5) rather than proceeding with partial output.
+**Remove the private source tree.** When step 3 bound `{source_tree}`, no later step reads the source: resolve `{sourceTreeHelper}` from `{sourceTreeProbeOrder}` and, from `{project-root}`, run `uv run {sourceTreeHelper} close --tree "{source_tree}"`. Go on whatever it prints. On `left` or `refused`, a command that fails or prints no JSON, or no candidate, display "This run's source tree `{source_tree}` was not removed; a later SKF run removes it once it is seven days old." Then set `{source_tree}` to null.
 
+No user interaction. Once the skill is promoted and verified (and optionally indexed into QMD), load `{nextStepFile}`, read it fully, then execute it. A QMD-indexing failure does not block; a promotion failure halts (§3) rather than proceeding with partial output.

package/src/skf-create-skill/references/health-check.md

@@ -17,7 +17,7 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 
 - No user-facing reports, file writes, or result contracts in this step — those belong in step 8
 - Delegate directly to `{nextStepFile}` with no additional commentary
-- In batch mode, this step is only reached after the final brief — step 8 loops back to load-brief for remaining briefs and skips chaining here
+- Under `--batch`, `references/batch-mode.md` §4 loads this step once, after the batch summary; report.md §6 sends each brief back to batch-mode.md §3 instead of here
 - Do not attempt any other action between loading this step and executing `{nextStepFile}`
 
 ## MANDATORY SEQUENCE